pico6502 Entwicklerhandbuch

English

Uebersicht

• M6502CPU.c / M6502CPU.h ersetzen Z80CPU.c / Z80CPU.h als Haupt-Dispatch- und Treiberframework-Dateien.
• Der 6502 hat keinen separaten I/O-Adressraum — es gibt kein ioPtr[]-Array und keinen iomap-JSON-Abschnitt. Alle Peripheriegeraete werden als FUNC-Typ-Bloecke in der 64KB-Speicherbelegung virtualisiert.
• Das PIO-Bus-Interface (M6502.pio) implementiert Zweiphasen-PHI1/PHI2-Taktung anstelle des Z80-Einzeltaktmodells.
• Das Build-Zielverzeichnis ist BaseM6502 statt BaseZ80.
• Der JSON-CPU-Abschnittsschluessel ist "6502" statt "z80".

Quellbaum

tzpuPico/
├── CMakeLists.txt                          Top-Level-Build-Datei
├── src/
│   ├── CMakeLists.txt                      Quellcode-Build-Datei — neue Treiberdateien hier hinzufuegen
│   ├── M6502CPU.c                          *** SCHLUESSELDATEI: 6502-Dispatch, Treiberframework, virtualFuncMap
│   ├── M6502CPU.h                          (Legacy — eingebunden ueber include/)
│   ├── M6502.c                             PIO-Initialisierung und Buszyklus-Einstiegspunkte
│   ├── M6502.pio                           PIO-Programme: clock, addr, data, cycle, fetch, read, write, irq, nmi, so
│   ├── Z80CPU.c / Z80CPU.h                 Z80-Gegenstueck (nicht in pico6502-Builds verwendet)
│   ├── FSPI.c / FSPI.h                     Flash-SPI-Interface (gemeinsam)
│   ├── ESP.c / ESP.h                       ESP32-Kommunikationsschicht (gemeinsam)
│   ├── psram.c / psram.h                   PSRAM-Allokation und Verwaltung (gemeinsam)
│   ├── cJSON.c / cJSON.h                   JSON-Parser fuer config.json (gemeinsam)
│   ├── include/
│   │   ├── M6502CPU.h                      *** SCHLUESSELDATEI: alle 6502-Typdefinitionen und Makros
│   │   ├── M6502.h                         PIO-Hilfsdefinitionen
│   │   └── drivers/
│   │       └── BBC/
│   │           └── ModelB.h               BBC Model B Treiber-Header (fruehes Platzhalter-Stadium)
│   ├── drivers/
│   │   └── BBC/
│   │       └── ModelB.c                   *** BEISPIEL/PLATZHALTER-TREIBER (BBC Model B Persona)
│   └── model/
│       ├── BaseM6502/
│       │   ├── CMakeLists.txt             Modellspezifische Build-Ziele
│       │   ├── main.c                     Einstiegspunkt (Core 0 + Core 1 Start)
│       │   ├── main_memmap_partition_1.ld Linker-Skript fuer Slot 1
│       │   └── main_memmap_partition_2.ld Linker-Skript fuer Slot 2
│       └── Bootloader/
│           ├── CMakeLists.txt
│           └── main.c                     Gemeinsamer Bootloader (gleich wie picoZ80)
└── esp32/
    ├── CMakeLists.txt
    └── main/
        └── ...                            ESP32-Firmware (geteilt mit picoZ80)

Wesentliche Unterschiede zum picoZ80

Kein separater I/O-Adressraum

PIO-Bus-Interface-Unterschiede

PIO-Programmierung — Wie C-Code Buszyklen steuert

                  Core 1 (C code)               PIO State Machines
                  ─────────────                 ──────────────────
    1. Resolve address                          m6502_cycle: IRQ 0 set
       from memory map                           (waiting on PHI2 low)
                  │
    2. Push addr → TX FIFO ──────────────────→ m6502_addr: receives addr
       Clear IRQ 0                               outputs A0–A15 on pins
                  │
    3. Push cycle instructions ──────────────→ m6502_cycle: out exec, 32
       (read sequence) into                       executes: set R/W̄ high, SYNC low
       cycle SM TX FIFO                           executes: wait PHI2 high
                  │                               executes: check RDY
    4. Wait for RX FIFO ←────────────────────  m6502_data: samples D0–D7
       (data byte from bus)                       at PHI2 falling edge
                  │
    5. Read data from                          m6502_cycle: JMP start_cycle
       RX FIFO                                    (ready for next cycle)
                  │
    6. Dispatch to PSRAM
       or driver handler

t_6502PSRAM-Struktur

// src/include/M6502CPU.h (simplified)
typedef struct {
    uint8_t      RAM[MAX_MEMORY_BANKS * MEMORY_PAGE_SIZE]; // 64 banks × 64KB = 4MB RAM/ROM area
    MemoryFunc   memPtr[MEMORY_PAGE_SIZE];                  // 64K per-byte read redirect (PTR type)
    MemoryFunc   memioPtr[MEMORY_PAGE_SIZE];                // 64K memory-mapped handler array (FUNC type)
    // NOTE: no ioPtr[] — the 6502 has no separate I/O space
} t_6502PSRAM;

Handler-Funktionssignatur

// Handler called for MEMBANK_TYPE_FUNC blocks on every access
typedef uint8_t (*MemoryFunc)(M6502CPU *cpu, bool read, uint16_t addr, uint8_t data);

// Parameters:
//   cpu  — pointer to the M6502CPU struct (access PSRAM, state, queues via this)
//   read — true for a 6502 read cycle (RNW=1), false for a write cycle (RNW=0)
//   addr — 16-bit address that triggered this handler
//   data — byte written (only meaningful when read=false)
// Return:
//   byte to place on the data bus (only meaningful when read=true)

Treiberframework

• Der virtualFuncMap[]-Registrierungstabelle und wie das JSON-"name"-Feld mit einer Treiber-Init-Funktion abgeglichen wird.
• Der VirtualFunc-Typdefinition und M6502CPU_getVirtualFunc()-Suche.
• Dem Zweiphasen-Init-Ablauf (Validierungsdurchlauf dann Konfigurationsdurchlauf).
• Treiber-Lifecycle-Callbacks: reset_ptr, poll_ptr, task_ptr.

Core 1-Dispatch-Schleife

1. Warte auf IRQ 0 (Adresse gueltig bei PHI1).
2. Lese die 16-Bit-Adresse aus dem PIO 0 RX FIFO.
3. Schlage _membankPtr[addr >> 9] nach, um Blocktyp, Bank und Basis zu erhalten.
4. Bestimme RNW (Read/Not-Write) vom Steuer-PIO.
5. Dispatch basierend auf Blocktyp: PHYSICAL (an Host weiterleiten), RAM (PSRAM lesen/schreiben), ROM (nur PSRAM lesen), FUNC (memioPtr[addr] aufrufen), PTR (ueber memPtr[addr] umleiten).
6. Bei Lesen: Ergebnis ueber PIO 0 TX FIFO auf Datenbus legen. Auf IRQ 1 (Datenphase) warten. Bei Schreiben: Daten aus PIO 0 RX FIFO nach IRQ 1 lesen.
7. poll_ptr fuer jeden registrierten Treiber aufrufen (ca. alle ~2048 Zyklen).

// Simplified M6502CPU_readMem / M6502CPU_writeMem dispatch
uint8_t M6502CPU_readMem(M6502CPU *cpu, uint16_t addr)
{
    uint32_t entry = cpu->_membankPtr[addr >> 9];
    uint8_t  type  = (entry >> 24) & 0xFF;
    uint8_t  bank  = (entry >> 16) & 0xFF;
    uint32_t base  = (entry & 0xFFFF) << 9;

    switch(type)
    {
        case MEMBANK_TYPE_RAM:
        case MEMBANK_TYPE_ROM:
            return cpu->_6502PSRAM->RAM[(bank * MEMORY_PAGE_SIZE) + addr];

        case MEMBANK_TYPE_FUNC:
            if(cpu->_6502PSRAM->memioPtr[addr] != NULL)
                return cpu->_6502PSRAM->memioPtr[addr](cpu, true, addr, 0);
            return 0x00;

        case MEMBANK_TYPE_PTR:
            if(cpu->_6502PSRAM->memPtr[addr] != NULL)
                return cpu->_6502PSRAM->memPtr[addr](cpu, true, addr, 0);
            return 0x00;

        case MEMBANK_TYPE_PHYSICAL:
        default:
            return 0xFF;  // Pass-through to real host hardware
    }
}

Einen neuen Treiber schreiben

1. Eine Header-Datei in src/include/drivers/<Familie>/MyDriver.h erstellen
2. Eine Implementierungsdatei in src/drivers/<Familie>/MyDriver.c erstellen
3. Die Quelldatei zu src/CMakeLists.txt hinzufuegen
4. Den Treiber in M6502CPU.c unter einem #ifdef INCLUDE_<FAMILY>_DRIVERS-Guard einbinden
5. Den Treiber in virtualFuncMap[] in M6502CPU.c registrieren
6. Einen JSON-Treibereintrag in config.json hinzufuegen

Minimale Treibervorlage

// src/include/drivers/BBC/VIA6522.h
#ifndef VIA6522_H
#define VIA6522_H

#include "M6502CPU.h"

int VIA6522_Init(M6502CPU *cpu, t_drvConfig *drvConfig, int pass);

#endif

// src/drivers/BBC/VIA6522.c
#include "../../include/M6502CPU.h"
#include "../../include/drivers/BBC/VIA6522.h"

// --- Internal state ---
typedef struct {
    uint8_t  regs[16];      // VIA internal registers (ORB, ORA, DDRB, DDRA, T1CL, T1CH, ...)
    bool     irqPending;
} t_VIA6522State;

static t_VIA6522State ViaState = { .irqPending = false };

// --- Memory handler (called for every access to 0xC000–0xC00F) ---
static uint8_t VIA6522_Handler(M6502CPU *cpu, bool read, uint16_t addr, uint8_t data)
{
    uint8_t reg = addr & 0x0F;   // VIA has 16 internal registers

    if(read)
    {
        return ViaState.regs[reg];
    }
    else
    {
        ViaState.regs[reg] = data;
        // TODO: implement timer, shift register, port logic as needed
        return 0;
    }
}

// --- Reset handler (called when host system resets) ---
static uint8_t VIA6522_Reset(M6502CPU *cpu)
{
    memset(&ViaState.regs, 0, sizeof(ViaState.regs));
    ViaState.irqPending = false;
    return 0;
}

// --- Init function (called during JSON config parse) ---
int VIA6522_Init(M6502CPU *cpu, t_drvConfig *drvConfig, int pass)
{
    if(pass == 0)
    {
        // Validation pass — just check the name matches
        return (strcasecmp(drvConfig->name, "via6522") == 0) ? 1 : 0;
    }

    // Configuration pass — install handlers
    // Install the handler for all 16 VIA registers at 0xC000–0xC00F
    for(uint16_t addr = 0xC000; addr <= 0xC00F; addr++)
    {
        cpu->_6502PSRAM->memioPtr[addr] = VIA6522_Handler;
    }

    // Register reset callback
    cpu->reset_ptr = VIA6522_Reset;

    debugf("VIA6522: Initialised at 0xC000–0xC00F\n");
    return 1;
}

JSON-Konfiguration

{
  "rp2350": {
    "6502": {
      "memory": [
        { "enable":1, "addr":"0x0000", "size":"0xC000",
          "type":"RAM",  "bank":0, "task":"", "file":"" },
        { "enable":1, "addr":"0xC000", "size":"0x0010",
          "type":"FUNC", "bank":0, "task":"via6522", "file":"" },
        { "enable":1, "addr":"0xE000", "size":"0x2000",
          "type":"ROM",  "bank":0, "task":"", "file":"/ROM/bios.rom" }
      ],
      "drivers": [
        { "enable":1, "name":"via6522" }
      ]
    }
  }
}

In virtualFuncMap registrieren

// In M6502CPU.c — add to virtualFuncMap[]
static const t_VirtualFuncMap virtualFuncMap[] = {
    { "BBCModelB", BBCModelB_Init },   // existing entry
    { "via6522",   VIA6522_Init   },   // your new driver
    { NULL, NULL }                     // terminator
};

CMakeLists.txt-Aenderung

# In src/CMakeLists.txt
target_sources(tzpuPico PRIVATE
    ...
    drivers/BBC/ModelB.c        # existing
    drivers/BBC/VIA6522.c       # your new driver
)

target_compile_definitions(tzpuPico PRIVATE
    INCLUDE_BBC_DRIVERS=1
)

Erstellen und Testen

# Vom Projektstammverzeichnis
./build_tzpuPico.sh

# Ueber USB-Massenspeicher flashen
cp build/bin/model/BaseM6502/BaseM6502_0x10020000.uf2 /media/$USER/RPI-RP2/

# Oder OTA: hochladen ueber http://<device-ip>/ota-rp2350.htm

Speicher-Hook-Muster

FUNC-Block — Virtuelles Peripheriegeraet

// Install handler for address range 0xD000–0xD0FF (256-byte peripheral block)
for(uint16_t addr = 0xD000; addr <= 0xD0FF; addr++)
{
    cpu->_6502PSRAM->memioPtr[addr] = MyPeripheral_Handler;
}

RAM-Schreib-Abfangen

// Handler intercepts writes; passes reads to PSRAM
static uint8_t ZeroPage_Intercept(M6502CPU *cpu, bool read, uint16_t addr, uint8_t data)
{
    if(read)
    {
        // Read from PSRAM normally
        return cpu->_6502PSRAM->RAM[addr];
    }
    else
    {
        // Write to PSRAM and update shadow state
        cpu->_6502PSRAM->RAM[addr] = data;
        MyDriver_OnZeroPageWrite(addr, data);
        return 0;
    }
}

// In init: set the block type to FUNC and install the handler
cpu->_membankPtr[0x0000 >> 9] = MEMBANK_ENCODE(MEMBANK_TYPE_FUNC, 0, 0x0000);
cpu->_6502PSRAM->memioPtr[0x0000] = ZeroPage_Intercept;
// ... repeat for each 512-byte block in the range

Verteilte / einzelne Adressen

// Only addresses 0xFFFE and 0xFFFF (6502 reset vector) are intercepted
cpu->_6502PSRAM->memioPtr[0xFFFE] = ResetVector_Lo_Handler;
cpu->_6502PSRAM->memioPtr[0xFFFF] = ResetVector_Hi_Handler;

BBC Model B Persona (Platzhalter)

Core 0 / Core 1-Interaktion

Haeufige Fallstricke

Referenz-Websites

Regulatorischer Hinweis fuer Funkgeraete