MOS 6502 ABAP Emulator Development

Expert guidance for working with CPU6502-ABAP, a MOS 6502 CPU emulator written in ABAP that executes 6502 machine code on SAP systems.

Project Context

**Status:** Working! All 44 unit tests pass.

**Package:** `$CPU6502`

**MCP Server:** vibing-steampunk (vsp) - provides SAP ADT access tools

Step-by-Step Instructions

1. Understanding the MCP Tools

You have access to specialized SAP ADT tools via the vibing-steampunk MCP server:

**Always use these MCP tools instead of reading/writing files directly.**

2. Architecture Overview

**Core Components:**

**Interfaces:**

**Entry Points:**

3. CRITICAL Implementation Rules

#### Integer Division (MUST FOLLOW!)

ABAP's `/` operator performs **decimal** division. All bit operations MUST use `DIV` for integer division:

```abap

" CORRECT - integer division

lv_result = mv_a DIV 2.

" WRONG - decimal division (will break bit operations!)

lv_result = mv_a / 2.

```

This affects LSR, ROR, and address calculations.

#### Status Flag Manipulation

The 6502 status register (P) uses specific bit positions:

```abap

" Flag positions: N V - B D I Z C (bits 7-0)

" Setting Z flag (bit 1)

IF lv_result = 0.

mv_p = mv_p BIT-OR 2. " Set Z

ELSE.

mv_p = mv_p BIT-AND 253. " Clear Z

ENDIF.

" Setting N flag (bit 7)

IF lv_result >= 128.

mv_p = mv_p BIT-OR 128. " Set N

ELSE.

mv_p = mv_p BIT-AND 127. " Clear N

ENDIF.

```

#### Memory Access Pattern

```abap

" Read byte

lv_value = mo_bus->read( iv_addr ).

" Write byte

mo_bus->write( iv_addr = lv_addr iv_value = lv_value ).

" 16-bit little-endian address

lv_lo = mo_bus->read( iv_addr ).

lv_hi = mo_bus->read( iv_addr + 1 ).

lv_addr16 = lv_hi * 256 + lv_lo.

```

#### Stack Operations

```abap

" Stack at $0100-$01FF, SP points to next free, grows down

" Push

mo_bus->write( iv_addr = 256 + mv_sp iv_value = lv_value ).

mv_sp = mv_sp - 1.

IF mv_sp < 0. mv_sp = 255. ENDIF.

" Pull

mv_sp = mv_sp + 1.

IF mv_sp > 255. mv_sp = 0. ENDIF.

lv_value = mo_bus->read( 256 + mv_sp ).

```

4. ABAP Naming Conventions

| Prefix | Usage | Example |

|--------|-------|---------|

| `ts_` | Structure types | `ts_instruction` |

| `tt_` | Table types | `tt_memory` |

| `lv_` | Local variables | `lv_opcode` |

| `lt_` | Local tables | `lt_bytes` |

| `mv_` | Instance attributes | `mv_pc`, `mv_a` |

| `mt_` | Instance tables | `mt_memory` |

| `mo_` | Instance objects | `mo_bus` |

| `iv_` | Import parameters | `iv_addr` |

| `ev_` | Export parameters | `ev_value` |

| `rv_` | Return values | `rv_result` |

**Important:** Use `ts_` for structures, NOT `ty_`.

5. Running Tests

Always run unit tests after making changes:

```

RunUnitTests(object_url="/sap/bc/adt/oo/classes/ZCL_CPU_00_TEST")

```

The 44 tests cover all 6502 operations, addressing modes, and edge cases.

6. 6502 Instruction Categories

**Load/Store:** LDA, LDX, LDY, STA, STX, STY

**Transfer:** TAX, TXA, TAY, TYA, TSX, TXS

**Stack:** PHA, PLA, PHP, PLP

**Arithmetic:** ADC, SBC, INC, DEC, INX, DEX, INY, DEY

**Logical:** AND, ORA, EOR

**Shift/Rotate:** ASL, LSR, ROL, ROR

**Compare:** CMP, CPX, CPY, BIT

**Branch:** BEQ, BNE, BCS, BCC, BMI, BPL, BVS, BVC

**Jump/Call:** JMP, JSR, RTS, RTI, BRK

**Flags:** CLC, SEC, CLI, SEI, CLV, CLD, SED

**No-op:** NOP

7. MS-BASIC Integration

The `msbasic/` directory contains a fork of mist64/msbasic with ABAP target support.

**Build:** `cd msbasic && ./make.sh` (requires cc65)

**Output:** `msbasic/tmp/abap.bin` (~30KB)

**Memory Map:**

**Entry Point:** `$272D` (COLD_START)

**I/O Handling:** Bus implementation must intercept reads/writes to `$FFF0-$FFF2` for character I/O.

8. Development Workflow

1. **Search for objects:** Use `SearchObject` to find relevant classes

2. **Read source:** Use `GetSource` to retrieve current code

3. **Make changes:** Use `EditSource` for surgical edits or `WriteSource` for full updates

4. **Validate:** Use `SyntaxCheck` before activation

5. **Activate:** Use `Activate` to make changes live

6. **Test:** Use `RunUnitTests` to verify correctness

9. Common Tasks

**Adding a new instruction:**

1. GetSource for `zcl_cpu_00_cpu`

2. Add opcode case in execute method

3. Implement addressing mode logic

4. Update flag calculations

5. SyntaxCheck, Activate, RunUnitTests

**Debugging a failing test:**

1. GetSource for `zcl_cpu_00_test`

2. Examine test setup and assertions

3. GetSource for relevant CPU method

4. Use EditSource to add debug output or fix logic

5. RunUnitTests to verify fix

**Extending bus functionality:**

1. GetSource for `zcl_cpu_00_bus_simple` or `zif_cpu_00_bus`

2. Add memory-mapped I/O handling

3. Update read/write methods

4. Test with custom programs

Constraints