pico6502 デベロッパーズガイド

English

概要

• M6502CPU.c / M6502CPU.h が Z80CPU.c / Z80CPU.h に代わり、メインのディスパッチおよびドライバーフレームワークファイルとなっています。
• 6502 には独立した I/O アドレス空間がありません — ioPtr[] 配列はなく、iomap の JSON セクションもありません。すべてのペリフェラルは 64KB メモリマップ内の FUNC タイプのブロックとして仮想化されます。
• PIO バスインターフェース（M6502.pio）は Z80 のシングルクロックモデルではなく、デュアルフェーズ PHI1/PHI2 クロッキングを実装しています。
• ビルドターゲットディレクトリは BaseZ80 ではなく BaseM6502 です。
• JSON の CPU セクションキーは "z80" ではなく "6502" です。

ソースツリー

tzpuPico/
├── CMakeLists.txt                          トップレベルビルドファイル
├── src/
│   ├── CMakeLists.txt                      ソースレベルビルドファイル — 新しいドライバーファイルをここに追加
│   ├── M6502CPU.c                          *** キーファイル: 6502 ディスパッチ、ドライバーフレームワーク、virtualFuncMap
│   ├── M6502CPU.h                          （レガシー — include/ 経由でインクルード）
│   ├── M6502.c                             PIO 初期化とバスサイクルエントリーポイント
│   ├── M6502.pio                           PIO プログラム: クロック、addr、data、サイクル、フェッチ、リード、ライト、irq、nmi、so
│   ├── Z80CPU.c / Z80CPU.h                 Z80 のカウンターパート（pico6502 ビルドでは不使用）
│   ├── FSPI.c / FSPI.h                     フラッシュ SPI インターフェース（共有）
│   ├── ESP.c / ESP.h                       ESP32 通信レイヤー（共有）
│   ├── psram.c / psram.h                   PSRAM 割り当てと管理（共有）
│   ├── cJSON.c / cJSON.h                   config.json 用 JSON パーサー（共有）
│   ├── include/
│   │   ├── M6502CPU.h                      *** キーファイル: すべての 6502 型定義とマクロ
│   │   ├── M6502.h                         PIO ヘルパー定義
│   │   └── drivers/
│   │       └── BBC/
│   │           └── ModelB.h               BBC Model B ドライバーヘッダー（初期プレースホルダー）
│   ├── drivers/
│   │   └── BBC/
│   │       └── ModelB.c                   *** サンプル/プレースホルダードライバー（BBC Model B ペルソナ）
│   └── model/
│       ├── BaseM6502/
│       │   ├── CMakeLists.txt             モデルごとのビルドターゲット
│       │   ├── main.c                     エントリーポイント（コア 0 + コア 1 起動）
│       │   ├── main_memmap_partition_1.ld スロット 1 用リンカースクリプト
│       │   └── main_memmap_partition_2.ld スロット 2 用リンカースクリプト
│       └── Bootloader/
│           ├── CMakeLists.txt
│           └── main.c                     共有ブートローダー（picoZ80 と同一）
└── esp32/
    ├── CMakeLists.txt
    └── main/
        └── ...                            ESP32 ファームウェア（picoZ80 と共有）

picoZ80 との主な違い

独立した I/O アドレス空間がない

PIO バスインターフェースの違い

PIO プログラミング — C コードによるバスサイクルの駆動方法

                  コア 1（C コード）              PIO ステートマシン
                  ──────────────                ──────────────────
    1. メモリマップから                          m6502_cycle: IRQ 0 セット
       アドレスを解決                              （PHI2 ロー待機中）
                  │
    2. アドレス → TX FIFO プッシュ ────────────→ m6502_addr: アドレス受信
       IRQ 0 クリア                                A0–A15 をピンに出力
                  │
    3. サイクル命令プッシュ ──────────────────→ m6502_cycle: out exec, 32
       （リードシーケンス）                         実行: R/W̄ ハイ、SYNC ロー設定
       サイクル SM TX FIFO へ                      実行: PHI2 ハイ待機
                  │                                実行: RDY 確認
    4. RX FIFO 待機 ←────────────────────────  m6502_data: D0–D7 サンプリング
       （バスからのデータバイト）                     PHI2 立ち下がりエッジで
                  │
    5. RX FIFO から                             m6502_cycle: JMP start_cycle
       データ読み取り                               （次のサイクル準備完了）
                  │
    6. PSRAM またはドライバー
       ハンドラーにディスパッチ

t_6502PSRAM 構造体

// src/include/M6502CPU.h（簡略版）
typedef struct {
    uint8_t      RAM[MAX_MEMORY_BANKS * MEMORY_PAGE_SIZE]; // 64バンク × 64KB = 4MB RAM/ROM領域
    MemoryFunc   memPtr[MEMORY_PAGE_SIZE];                  // 64K バイト単位リードリダイレクト（PTR タイプ）
    MemoryFunc   memioPtr[MEMORY_PAGE_SIZE];                // 64K メモリマップハンドラー配列（FUNC タイプ）
    // 注: ioPtr[] なし — 6502 には独立した I/O 空間がない
} t_6502PSRAM;

ハンドラー関数シグネチャー

// すべてのアクセスで MEMBANK_TYPE_FUNC ブロックに対して呼び出されるハンドラー
typedef uint8_t (*MemoryFunc)(M6502CPU *cpu, bool read, uint16_t addr, uint8_t data);

// パラメーター:
//   cpu  — M6502CPU 構造体へのポインター（これを通じて PSRAM、状態、キューにアクセス）
//   read — 6502 リードサイクル（RNW=1）の場合 true、ライトサイクル（RNW=0）の場合 false
//   addr — このハンドラーをトリガーした 16 ビットアドレス
//   data — 書き込まれたバイト（read=false の場合のみ意味がある）
// 戻り値:
//   データバスに置くバイト（read=true の場合のみ意味がある）

ドライバーフレームワーク

• virtualFuncMap[] 登録テーブルと、JSON の "name" フィールドがドライバー初期化関数にどのようにマッチングされるか。
• VirtualFunc typedef と M6502CPU_getVirtualFunc() ルックアップ。
• 二フェーズ初期化フロー（検証パスから設定パスへ）。
• ドライバーライフサイクルコールバック：reset_ptr、poll_ptr、task_ptr。

コア 1 ディスパッチループ

1. IRQ 0 を待つ（PHI1 でアドレス有効）。
2. PIO 0 RX FIFO から 16 ビットアドレスを読み取る。
3. _membankPtr[addr >> 9] を参照してブロックタイプ、バンク、ベースを取得する。
4. 制御 PIO から RNW（リード/ノットライト）を判定する。
5. ブロックタイプによってディスパッチ：PHYSICAL（ホストへパス）、RAM（PSRAM 読み書き）、ROM（PSRAM 読み取りのみ）、FUNC（memioPtr[addr] を呼び出す）、PTR（memPtr[addr] 経由でリダイレクト）。
6. リードの場合：PIO 0 TX FIFO 経由でデータバスに結果を置く。IRQ 1 を待つ（データフェーズ）。ライトの場合：IRQ 1 の後に PIO 0 RX FIFO からデータを読み取る。
7. 登録された各ドライバーの poll_ptr を呼び出す（約 2048 サイクルごと）。

// 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;  // 実際のホストハードウェアへのパススルー
    }
}

新しいドライバーの作成

1. src/include/drivers/<Family>/MyDriver.h にヘッダーファイルを作成
2. src/drivers/<Family>/MyDriver.c に実装ファイルを作成
3. ソースファイルを src/CMakeLists.txt に追加
4. #ifdef INCLUDE_<FAMILY>_DRIVERS ガードの下で M6502CPU.c にドライバーをインクルード
5. M6502CPU.c の virtualFuncMap[] にドライバーを登録
6. config.json に JSON ドライバーエントリーを追加

最小ドライバーテンプレート

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

// --- 内部状態 ---
typedef struct {
    uint8_t  regs[16];      // VIA 内部レジスター（ORB, ORA, DDRB, DDRA, T1CL, T1CH, ...）
    bool     irqPending;
} t_VIA6522State;

static t_VIA6522State ViaState = { .irqPending = false };

// --- メモリハンドラー（0xC000–0xC00F へのすべてのアクセスで呼び出される）---
static uint8_t VIA6522_Handler(M6502CPU *cpu, bool read, uint16_t addr, uint8_t data)
{
    uint8_t reg = addr & 0x0F;   // VIA は 16 の内部レジスターを持つ

    if(read)
    {
        return ViaState.regs[reg];
    }
    else
    {
        ViaState.regs[reg] = data;
        // TODO: 必要に応じてタイマー、シフトレジスター、ポートロジックを実装
        return 0;
    }
}

// --- リセットハンドラー（ホストシステムリセット時に呼び出される）---
static uint8_t VIA6522_Reset(M6502CPU *cpu)
{
    memset(&ViaState.regs, 0, sizeof(ViaState.regs));
    ViaState.irqPending = false;
    return 0;
}

// --- 初期化関数（JSON 設定パース中に呼び出される）---
int VIA6522_Init(M6502CPU *cpu, t_drvConfig *drvConfig, int pass)
{
    if(pass == 0)
    {
        // 検証パス — 名前が一致するかどうかを確認するだけ
        return (strcasecmp(drvConfig->name, "via6522") == 0) ? 1 : 0;
    }

    // 設定パス — ハンドラーをインストール
    // 0xC000–0xC00F のすべての 16 VIA レジスターにハンドラーをインストール
    for(uint16_t addr = 0xC000; addr <= 0xC00F; addr++)
    {
        cpu->_6502PSRAM->memioPtr[addr] = VIA6522_Handler;
    }

    // リセットコールバックを登録
    cpu->reset_ptr = VIA6522_Reset;

    debugf("VIA6522: 0xC000–0xC00F で初期化済み\n");
    return 1;
}

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

virtualFuncMap への登録

// M6502CPU.c — virtualFuncMap[] に追加
static const t_VirtualFuncMap virtualFuncMap[] = {
    { "BBCModelB", BBCModelB_Init },   // 既存エントリー
    { "via6522",   VIA6522_Init   },   // 新しいドライバー
    { NULL, NULL }                     // ターミネーター
};

CMakeLists.txt の変更

# src/CMakeLists.txt
target_sources(tzpuPico PRIVATE
    ...
    drivers/BBC/ModelB.c        # 既存
    drivers/BBC/VIA6522.c       # 新しいドライバー
)

target_compile_definitions(tzpuPico PRIVATE
    INCLUDE_BBC_DRIVERS=1
)

ビルドとテスト

# プロジェクトルートから
./build_tzpuPico.sh


# USB マスストレージ経由で書き込み
cp build/bin/model/BaseM6502/BaseM6502_0x10020000.uf2 /media/$USER/RPI-RP2/


# または OTA: http://<device-ip>/ota-rp2350.htm 経由でアップロード

メモリフックパターン

FUNC ブロック — 仮想ペリフェラル

// アドレス範囲 0xD000–0xD0FF（256 バイトペリフェラルブロック）にハンドラーをインストール
for(uint16_t addr = 0xD000; addr <= 0xD0FF; addr++)
{
    cpu->_6502PSRAM->memioPtr[addr] = MyPeripheral_Handler;
}

RAM ライトインターセプト

// ハンドラーはライトをインターセプト；リードは PSRAM に通す
static uint8_t ZeroPage_Intercept(M6502CPU *cpu, bool read, uint16_t addr, uint8_t data)
{
    if(read)
    {
        // 通常通り PSRAM から読み取る
        return cpu->_6502PSRAM->RAM[addr];
    }
    else
    {
        // PSRAM に書き込み、シャドウ状態を更新
        cpu->_6502PSRAM->RAM[addr] = data;
        MyDriver_OnZeroPageWrite(addr, data);
        return 0;
    }
}

// 初期化時：ブロックタイプを FUNC に設定してハンドラーをインストール
cpu->_membankPtr[0x0000 >> 9] = MEMBANK_ENCODE(MEMBANK_TYPE_FUNC, 0, 0x0000);
cpu->_6502PSRAM->memioPtr[0x0000] = ZeroPage_Intercept;
// ... 範囲内の各 512 バイトブロックに対して繰り返す

スパース/個別アドレス

// アドレス 0xFFFE と 0xFFFF（6502 リセットベクター）のみをインターセプト
cpu->_6502PSRAM->memioPtr[0xFFFE] = ResetVector_Lo_Handler;
cpu->_6502PSRAM->memioPtr[0xFFFF] = ResetVector_Hi_Handler;

BBC Model B ペルソナ（プレースホルダー）

コア 0 / コア 1 の相互作用

よくある落とし穴

参考サイト

無線規制に関する注意事項