Complete CB Prefix - BIT, RES and SET (0x40-0xFF)

Summary

The extended prefix CB table is 100% complete by implementing the remaining three quarters:BIT(0x40-0x7F),BEEF(0x80-0xBF) andSET(0xC0-0xFF). These instructions are essential for bit manipulation, which is an extremely common operation in Game Boy games. For example, Tetris constantly usesRES 7, (HL)to mark that a block has stopped falling. The full implementation covers an additional 192 CB opcodes (64 per operation), thus completing the 256 instructions of the CB prefix. Complete suite of TDD tests (8 tests) validating all the operations. All tests pass.

Hardware Concept

TheCB tableIt follows a perfect and elegant pattern on the LR35902 architecture. After implement the first quarter (0x00-0x3F) with rotations and shifts, the remaining three quarters follow a clear mathematical pattern:

CB Table Structure

• 0x00-0x3F:Rotations and Shifts (RLC, RRC, RL, RR, SLA, SRA, SRL, SWAP)
• 0x40-0x7F: BIT b, r- Test the bitbof the registryr
• 0x80-0xBF: RES b, r- Reset: Set the bitbto 0
• 0xC0-0xFF: SET b, r- Set: Sets the bitbto 1

Encoding Pattern

CB encoding is extremely regular. Each 8-bit CB opcode is decomposed like this:

• Bits 6-7:Operation type
  • 01(0x40-0x7F): BIT
  • 10(0x80-0xBF): RES
  • 11(0xC0-0xFF): SET
• Bits 3-5:Bit number to operate (0-7)
• Bits 0-2:Record index (0-7: B, C, D, E, H, L, (HL), A)

Encoding Examples:

• 0x40 = 01000000→ BIT 0, B (bit=0, reg=0)
• 0x41 = 01000001→ BIT 0, C (bit=0, reg=1)
• 0x7C = 01111100→ BIT 7, H (bit=7, reg=4)
• 0x80 = 10000000→ RES 0, B (bit=0, reg=0)
• 0xBE = 10111110→ RES 7, (HL) (bit=7, reg=6)
• 0xC0 = 11000000→ SET 0, B (bit=0, reg=0)
• 0xFE = 11111110→ SET 7, (HL) (bit=7, reg=6)

Flags and Behavior

BIT (Test Bit):

• Z:Inverse of tested bit (1 if bit is 0, 0 if bit is 1)
• N:Always 0
• H:Always 1 (hardware quirk)
• C:Unchanged (preserved)

The reverse logic of Z can be confusing, but it makes sense when used with conditional jumps:BIT 7, Hfollowed byJR Z, labeljumps if the bit is off.

RES (Reset Bit) and SET (Set Bit):

• Z, N, H, C: They are not modified(preserved)

RES and SET only modify the data, they do not affect the flags. This is critical because it allows manipulation bits without altering the state of the previous comparisons.

Timing

The timing follows the same pattern as the previous CB operations:

• Registers (B, C, D, E, H, L, A):2 M-Cycles
• Indirect memory (HL):4 M-Cycles (access to additional memory)

Implementation

The complete implementation of BIT, RES and SET was carried out through dynamic handler generation in the method_init_cb_bit_res_set_table(), which already existed but was incomplete. The generic helper structure already established for previous CB operations was taken advantage of.

Components created/modified

• src/cpu/core.py:
  • Method_init_cb_bit_res_set_table()- Complete generation of 192 handlers (64 BIT + 64 RES + 64 SET)
  • Existing generic helpers:
    • _bit(bit, value)- Updates flags according to the bit tested
    • _cb_res(bit, value)- Returns value with bit off
    • _cb_set(bit, value)- Returns value with bit on
    • _cb_get_register_value(reg_index)- Read register or memory
    • _cb_set_register_value(reg_index, value)- Write register or memory
• tests/test_cpu_cb_full.py:
  • Test correctiontest_bit_all_registersto properly handle HL configuration
  • Complete suite of 8 tests validating BIT, RES and SET in all registers and memory

Design decisions

Reuse of Helpers:The existing helper infrastructure was taken advantage of generic (_cb_get_register_value, _cb_set_register_value) to maintain consistency with previous CB operations (rotations and shifts).

Dynamic Generation:The same dynamic generation pattern with closures was used as was used for rotations and shifts, iterating over bits (0-7) and registers (0-7) to generate the 192 handlers needed.

Flag Preservation:RES and SET do not modify flags, which was simply implemented not calling any flag update function after the operation.

Affected Files

• src/cpu/core.py- Method_init_cb_bit_res_set_table()completed (already existed but was incomplete)
• tests/test_cpu_cb_full.py- Test correctiontest_bit_all_registersto properly handle HL settings when testing (HL)

Tests and Verification

The complete suite of tests for BIT, RES and SET was executed:

Test Execution

Command executed: python3 -m pytest tests/test_cpu_cb_full.py -v

Around:macOS, Python 3.9.6

Result: 8 passedin 0.28s

Implemented Tests

• TestBIT::test_bit_all_registers:Verify that BIT 0 works in all registers (B, C, D, E, H, L, (HL), A) and indirect memory
• TestBIT::test_bit_flags_quirk:Verify that BIT always sets H=1 (hardware quirk)
• TestBIT::test_bit_preserves_carry:Verify that BIT preserves the C flag (does not modify it)
• TestRES::test_res_memory:Verify that RES turns off bits in indirect memory (HL) without affecting flags
• TestRES::test_res_all_bits:Verify that RES correctly turns off all bits (0-7) in register B
• TestSET::test_set_memory:Verify that SET turns on bits in indirect memory (HL) without affecting flags
• TestSET::test_set_all_bits:Verify that SET correctly turns on all bits (0-7) in register B
• TestBITRESETIntegration::test_bit_res_set_workflow:Integration test that simulates a complete flow BIT → RES → SET

Evidence from Tests

============================== test session starts ==============================
platform darwin -- Python 3.9.6, pytest-8.4.2, pluggy-1.6.0
collected 8 items

tests/test_cpu_cb_full.py::TestBIT::test_bit_all_registers PASSED [ 12%]
tests/test_cpu_cb_full.py::TestBIT::test_bit_flags_quirk PASSED [ 25%]
tests/test_cpu_cb_full.py::TestBIT::test_bit_preserves_carry PASSED [ 37%]
tests/test_cpu_cb_full.py::TestRES::test_res_memory PASSED [ 50%]
tests/test_cpu_cb_full.py::TestRES::test_res_all_bits PASSED [ 62%]
tests/test_cpu_cb_full.py::TestSET::test_set_memory PASSED [ 75%]
tests/test_cpu_cb_full.py::TestSET::test_set_all_bits PASSED [ 87%]
tests/test_cpu_cb_full.py::TestBITRESETIntegration::test_bit_res_set_workflow PASSED [100%]

========================= 8 passed in 0.28s ===============

How valid

• BIT:Verify that the bit test correctly updates the flags (Z inverse, H=1 always, C preserved)
• BEEF:Verify that bits are turned off correctly without affecting flags
• SET:Verify that bits are lit correctly without affecting flags
• Indirect memory:Verify that operations work correctly with (HL) and consume 4 M-Cycles
• Timing:Verify that registers consume 2 M-Cycles and (HL) consumes 4 M-Cycles

Test Code (Essential Fragment)

Test exampletest_res_memorywhich validates RES in memory:

def test_res_memory(self):
    """Test: RES turns off bits in indirect memory (HL)."""
    mmu = MMU()
    cpu = CPU(mmu)
    
    # Set initial state
    cpu.registers.set_hl(0xC000)
    mmu.write_byte(0xC000, 0xFF) # All bits on
    
    # Write CB prefix and opcode
    mmu.write_byte(0x8000, 0xCB)
    mmu.write_byte(0x8001, 0x86) # RES 0, (HL)
    
    # Execute statement
    cycles = cpu.step()
    
    # Check result
    assert mmu.read_byte(0xC000) == 0xFE, "(HL) must be 0xFE (bit 0 off)"
    assert cycles == 4, "Must consume 4 M-Cycles (memory access)"

Sources consulted

• Bread Docs:CPU Instruction Set - CB Prefix encoding
• Bread Docs:BIT b, r instruction
• Bread Docs:RES b, r instruction
• Bread Docs:SET b, r instruction

Educational Integrity

Next Steps

The CB table is 100% complete! 🎉

After completing the CB prefix, only a few "miscellaneous" but vital instructions remain to finish the CPU core:

• [ ] RST(Restart) - Short calls to fixed addresses (0x00, 0x08, 0x10, 0x18, 0x20, 0x28, 0x30, 0x38)
• [ ] DAA(Decimal Adjust Accumulator) - Decimal adjustment for BCD operations (scores)
• [ ] CPL(Complement) - 1's complement of the accumulator
• [ ] SCF(Set Carry Flag) - Activates the C flag
• [ ] CCF(Complement Carry Flag) - Complements the C flag

With these instructions, theCore CPU will be 100% finished. 🏁