pico6502 Guide du Developpeur

English

Vue d'ensemble

• M6502CPU.c / M6502CPU.h remplacent Z80CPU.c / Z80CPU.h comme fichiers principaux de dispatch et de framework de pilotes.
• Le 6502 n'a pas d'espace d'adressage E/S separe — il n'y a pas de tableau ioPtr[] et pas de section JSON iomap. Tous les peripheriques sont virtualises sous forme de blocs de type FUNC dans la carte memoire de 64 Ko.
• L'interface bus PIO (M6502.pio) implemente l'horloge biphasee PHI1/PHI2 au lieu du modele a horloge unique du Z80.
• Le repertoire cible de compilation est BaseM6502 au lieu de BaseZ80.
• La cle de section CPU JSON est "6502" au lieu de "z80".

Arborescence des sources

tzpuPico/
├── CMakeLists.txt                          Fichier de compilation de niveau superieur
├── src/
│   ├── CMakeLists.txt                      Fichier de compilation au niveau source — ajoutez les nouveaux fichiers pilotes ici
│   ├── M6502CPU.c                          *** FICHIER CLE : dispatch 6502, framework de pilotes, virtualFuncMap
│   ├── M6502CPU.h                          (historique — inclus via include/)
│   ├── M6502.c                             Initialisation PIO et points d'entree des cycles bus
│   ├── M6502.pio                           Programmes PIO : clock, addr, data, cycle, fetch, read, write, irq, nmi, so
│   ├── Z80CPU.c / Z80CPU.h                 Equivalent Z80 (non utilise pour les compilations pico6502)
│   ├── FSPI.c / FSPI.h                     Interface Flash SPI (partage)
│   ├── ESP.c / ESP.h                       Couche de communication ESP32 (partage)
│   ├── psram.c / psram.h                   Allocation et gestion PSRAM (partage)
│   ├── cJSON.c / cJSON.h                   Parseur JSON pour config.json (partage)
│   ├── include/
│   │   ├── M6502CPU.h                      *** FICHIER CLE : toutes les definitions de types et macros 6502
│   │   ├── M6502.h                         Definitions d'aide PIO
│   │   └── drivers/
│   │       └── BBC/
│   │           └── ModelB.h               En-tete du pilote BBC Model B (substitution precoce)
│   ├── drivers/
│   │   └── BBC/
│   │       └── ModelB.c                   *** PILOTE EXEMPLE/SUBSTITUTION (persona BBC Model B)
│   └── model/
│       ├── BaseM6502/
│       │   ├── CMakeLists.txt             Cibles de compilation par modele
│       │   ├── main.c                     Point d'entree (lancement Core 0 + Core 1)
│       │   ├── main_memmap_partition_1.ld Script de liaison pour le Slot 1
│       │   └── main_memmap_partition_2.ld Script de liaison pour le Slot 2
│       └── Bootloader/
│           ├── CMakeLists.txt
│           └── main.c                     Bootloader partage (meme que picoZ80)
└── esp32/
    ├── CMakeLists.txt
    └── main/
        └── ...                            Firmware ESP32 (partage avec picoZ80)

Differences cles avec le picoZ80

Pas d'espace d'adressage E/S separe

Differences de l'interface bus PIO

Programmation PIO — Comment le code C pilote les cycles bus

                  Core 1 (code C)               Machines d'etat PIO
                  ─────────────                 ──────────────────
    1. Resoudre l'adresse                       m6502_cycle: IRQ 0 active
       depuis la carte memoire                    (en attente de PHI2 bas)
                  │
    2. Pousser addr → TX FIFO ──────────────→ m6502_addr: recoit addr
       Effacer IRQ 0                              produit A0–A15 sur les broches
                  │
    3. Pousser les instructions ─────────────→ m6502_cycle: out exec, 32
       de cycle (sequence de                      execute: set R/W̄ haut, SYNC bas
       lecture) dans le FIFO                      execute: wait PHI2 haut
       TX de la SM de cycle                       execute: verifier RDY
                  │
    4. Attendre le RX FIFO ←────────────────  m6502_data: echantillonne D0–D7
       (octet de donnees du bus)                  sur front descendant PHI2
                  │
    5. Lire les donnees du                     m6502_cycle: JMP start_cycle
       RX FIFO                                    (pret pour le prochain cycle)
                  │
    6. Dispatcher vers PSRAM
       ou handler de pilote

Struct t_6502PSRAM

// src/include/M6502CPU.h (simplifie)
typedef struct {
    uint8_t      RAM[MAX_MEMORY_BANKS * MEMORY_PAGE_SIZE]; // 64 banques x 64 Ko = 4 Mo zone RAM/ROM
    MemoryFunc   memPtr[MEMORY_PAGE_SIZE];                  // 64K redirection lecture par octet (type PTR)
    MemoryFunc   memioPtr[MEMORY_PAGE_SIZE];                // 64K tableau handlers mappes memoire (type FUNC)
    // NOTE : pas de ioPtr[] — le 6502 n'a pas d'espace E/S separe
} t_6502PSRAM;

Signature de la fonction handler

// Handler appele pour les blocs MEMBANK_TYPE_FUNC a chaque acces
typedef uint8_t (*MemoryFunc)(M6502CPU *cpu, bool read, uint16_t addr, uint8_t data);

// Parametres :
//   cpu  — pointeur vers la struct M6502CPU (acces PSRAM, etat, files via celui-ci)
//   read — true pour un cycle de lecture 6502 (RNW=1), false pour un cycle d'ecriture (RNW=0)
//   addr — adresse 16 bits qui a declenche ce handler
//   data — octet ecrit (significatif uniquement quand read=false)
// Retour :
//   octet a placer sur le bus de donnees (significatif uniquement quand read=true)

Framework de pilotes

• La table d'enregistrement virtualFuncMap[] et comment le champ JSON "name" est mis en correspondance avec une fonction d'initialisation de pilote.
• Le typedef VirtualFunc et la recherche M6502CPU_getVirtualFunc().
• Le flux d'initialisation en deux passes (passe de validation puis passe de configuration).
• Les callbacks de cycle de vie des pilotes : reset_ptr, poll_ptr, task_ptr.

Boucle de dispatch Core 1

1. Attendre IRQ 0 (adresse valide sur PHI1).
2. Lire l'adresse 16 bits depuis le FIFO RX de PIO 0.
3. Rechercher _membankPtr[addr >> 9] pour obtenir le type de bloc, la banque et la base.
4. Determiner RNW (read/not-write) depuis le PIO de controle.
5. Dispatcher selon le type de bloc : PHYSICAL (passer a l'hote), RAM (lecture/ecriture PSRAM), ROM (lecture seule PSRAM), FUNC (appeler memioPtr[addr]), PTR (rediriger via memPtr[addr]).
6. Si lecture : placer le resultat sur le bus de donnees via le FIFO TX de PIO 0. Attendre IRQ 1 (phase donnees). Si ecriture : lire les donnees depuis le FIFO RX de PIO 0 apres IRQ 1.
7. Appeler poll_ptr pour chaque pilote enregistre (environ tous les ~2048 cycles).

// Dispatch simplifie M6502CPU_readMem / M6502CPU_writeMem
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 vers le materiel reel de l'hote
    }
}

Ecrire un nouveau pilote

1. Creer un fichier d'en-tete dans src/include/drivers/<Family>/MyDriver.h
2. Creer un fichier d'implementation dans src/drivers/<Family>/MyDriver.c
3. Ajouter le fichier source a src/CMakeLists.txt
4. Inclure le pilote dans M6502CPU.c sous une garde #ifdef INCLUDE_<FAMILY>_DRIVERS
5. Enregistrer le pilote dans virtualFuncMap[] dans M6502CPU.c
6. Ajouter une entree de pilote JSON dans config.json

Template de pilote minimal

// 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"

// --- Etat interne ---
typedef struct {
    uint8_t  regs[16];      // Registres internes VIA (ORB, ORA, DDRB, DDRA, T1CL, T1CH, ...)
    bool     irqPending;
} t_VIA6522State;

static t_VIA6522State ViaState = { .irqPending = false };

// --- Handler memoire (appele pour chaque acces a 0xC000–0xC00F) ---
static uint8_t VIA6522_Handler(M6502CPU *cpu, bool read, uint16_t addr, uint8_t data)
{
    uint8_t reg = addr & 0x0F;   // Le VIA a 16 registres internes

    if(read)
    {
        return ViaState.regs[reg];
    }
    else
    {
        ViaState.regs[reg] = data;
        // TODO: implementer la logique timer, registre a decalage, port selon les besoins
        return 0;
    }
}

// --- Handler de reset (appele quand le systeme hote se reinitialise) ---
static uint8_t VIA6522_Reset(M6502CPU *cpu)
{
    memset(&ViaState.regs, 0, sizeof(ViaState.regs));
    ViaState.irqPending = false;
    return 0;
}

// --- Fonction d'initialisation (appelee pendant le parsing de la configuration JSON) ---
int VIA6522_Init(M6502CPU *cpu, t_drvConfig *drvConfig, int pass)
{
    if(pass == 0)
    {
        // Passe de validation — verifier seulement que le nom correspond
        return (strcasecmp(drvConfig->name, "via6522") == 0) ? 1 : 0;
    }

    // Passe de configuration — installer les handlers
    // Installer le handler pour les 16 registres VIA a 0xC000–0xC00F
    for(uint16_t addr = 0xC000; addr <= 0xC00F; addr++)
    {
        cpu->_6502PSRAM->memioPtr[addr] = VIA6522_Handler;
    }

    // Enregistrer le callback de reset
    cpu->reset_ptr = VIA6522_Reset;

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

Configuration JSON

{
  "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" }
      ]
    }
  }
}

Enregistrement dans virtualFuncMap

// Dans M6502CPU.c — ajouter a virtualFuncMap[]
static const t_VirtualFuncMap virtualFuncMap[] = {
    { "BBCModelB", BBCModelB_Init },   // entree existante
    { "via6522",   VIA6522_Init   },   // votre nouveau pilote
    { NULL, NULL }                     // terminateur
};

Modification de CMakeLists.txt

# Dans src/CMakeLists.txt
target_sources(tzpuPico PRIVATE
    ...
    drivers/BBC/ModelB.c        # existant
    drivers/BBC/VIA6522.c       # votre nouveau pilote
)

target_compile_definitions(tzpuPico PRIVATE
    INCLUDE_BBC_DRIVERS=1
)

Compilation et test

# Depuis la racine du projet
./build_tzpuPico.sh

# Flasher via stockage de masse USB
cp build/bin/model/BaseM6502/BaseM6502_0x10020000.uf2 /media/$USER/RPI-RP2/

# Ou OTA : telecharger via http://<device-ip>/ota-rp2350.htm

Modeles de hooks memoire

Bloc FUNC — Peripherique virtuel

// Installer le handler pour la plage d'adresses 0xD000–0xD0FF (bloc peripherique de 256 octets)
for(uint16_t addr = 0xD000; addr <= 0xD0FF; addr++)
{
    cpu->_6502PSRAM->memioPtr[addr] = MyPeripheral_Handler;
}

Interception d'ecriture RAM

// Le handler intercepte les ecritures ; passe les lectures a la PSRAM
static uint8_t ZeroPage_Intercept(M6502CPU *cpu, bool read, uint16_t addr, uint8_t data)
{
    if(read)
    {
        // Lecture normale depuis la PSRAM
        return cpu->_6502PSRAM->RAM[addr];
    }
    else
    {
        // Ecriture dans la PSRAM et mise a jour de l'etat shadow
        cpu->_6502PSRAM->RAM[addr] = data;
        MyDriver_OnZeroPageWrite(addr, data);
        return 0;
    }
}

// Dans init : definir le type de bloc a FUNC et installer le handler
cpu->_membankPtr[0x0000 >> 9] = MEMBANK_ENCODE(MEMBANK_TYPE_FUNC, 0, 0x0000);
cpu->_6502PSRAM->memioPtr[0x0000] = ZeroPage_Intercept;
// ... repeter pour chaque bloc de 512 octets dans la plage

Adresses eparses / individuelles

// Seules les adresses 0xFFFE et 0xFFFF (vecteur de reset du 6502) sont interceptees
cpu->_6502PSRAM->memioPtr[0xFFFE] = ResetVector_Lo_Handler;
cpu->_6502PSRAM->memioPtr[0xFFFF] = ResetVector_Hi_Handler;

Persona BBC Model B (substitution)

Interaction Core 0 / Core 1

Pieges courants

Sites de reference

Avis reglementaire sans fil