picoZ80 デベロッパーズガイド

picoZ80 デベロッパーズガイド

ソースツリー

tzpuPico/
├── CMakeLists.txt                          トップレベルのビルドファイル
├── src/
│   ├── CMakeLists.txt                      ソースレベルのビルドファイル — 新しいドライバーファイルをここに追加
│   ├── Z80CPU.c                            メイン Z80 エミュレーション、バスディスパッチ、ドライバーフレームワーク
│   ├── Z80CPU.h                            （レガシー — include/ 経由でインクルード）
│   ├── M6502CPU.c                          6502 並行（同じアーキテクチャ）
│   ├── FSPI.c / FSPI.h                     フラッシュ SPI インターフェース
│   ├── ESP.c / ESP.h                       ESP32 通信レイヤー
│   ├── psram.c / psram.h                   PSRAM の割り当てと管理
│   ├── cJSON.c / cJSON.h                   config.json 用 JSON パーサー
│   ├── dbgsh.c                             デバッグシェル（ICE デバッガー）— USB CDC チャネル 1
│   ├── PIT8253.c                           Intel 8253 PIT エミュレーションモジュール
│   ├── PPI8255.c                           Intel 8255 PPI エミュレーションモジュール
│   ├── include/
│   │   ├── Z80CPU.h                        *** 重要なファイル：すべての型定義とマクロ ***
│   │   ├── dbgsh.h                         デバッグシェル（ICE デバッガー）ヘッダー
│   │   └── drivers/
│   │       └── Sharp/
│   │           ├── MZ.h                    MZ シリーズ共通定数
│   │           ├── MZ700.h                 MZ-700 ドライバーヘッダー
│   │           ├── MZ80A.h                 MZ-80A ドライバーヘッダー
│   │           ├── MZ2000.h                MZ-2000 ドライバーヘッダー
│   │           ├── RFS.h / TZFS.h          ファイリングシステムヘッダー
│   │           ├── WD1773.h                フロッピーコントローラーヘッダー
│   │           ├── MZ8BFI.h                MZ-8BFI ドライバーヘッダー
│   │           └── QDDrive.h               QuickDisk ヘッダー
│   ├── drivers/
│   │   └── Sharp/
│   │       ├── MZ700.c                     *** サンプルドライバー ***
│   │       ├── MZ80A.c                     MZ-80A ペルソナドライバー
│   │       ├── MZ2000.c                    MZ-2000 ペルソナドライバー
│   │       ├── RFS.c                       ROM ファイリングシステムドライバー
│   │       ├── TZFS.c                      TranZPUter ファイリングシステムドライバー
│   │       ├── WD1773.c                    WD1773 フロッピーコントローラードライバー
│   │       ├── QDDrive.c                   QuickDisk ドライブドライバー
│   │       ├── MZ1500.c                    MZ-1500 ペルソナドライバー
│   │       ├── MZ-1E05.c / MZ-1E14.c / MZ-1E19.c   ペリフェラルインターフェースカード
│   │       ├── MZ8BFI.c                    MZ-8BFI フロッピーディスクインターフェース（MZ-2000）
│   │       ├── MZ-1R12.c / MZ-1R18.c      RAM 拡張カード
│   │       ├── MZ-1R23.c                   漢字 ROM / 辞書 ROM ボード
│   │       ├── MZ-1R37.c                   640KB 拡張メモリマネージャー
│   │       ├── PIO-3034.c                  IO DATA 320KB EMM
│   │       └── Celestite.c                 Celestite LAN/メモリ複合ボード
│   └── model/
│       ├── BaseZ80/
│       │   ├── CMakeLists.txt              モデルごとのビルドターゲット
│       │   ├── main.c                      エントリポイント（コア 0 + コア 1 起動）
│       │   ├── main_memmap_partition_1.ld  スロット 1 用リンカースクリプト
│       │   └── main_memmap_partition_2.ld  スロット 2 用リンカースクリプト
│       └── Bootloader/

PIO バスインターフェース — C コードによるステートマシンの駆動方法

// z80_cycle SM プログラム（PIO 0 SM 2）：
//
// start_cycle:
//     wait 0 irq 6          ; BUSREQ アクティブならストール
//     irq set 0             ; 「準備完了」を通知
//     wait 0 irq 0          ; C コードがアドレスをロードして IRQ 0 をクリアするまで待機
//     wait 1 gpio CLK       ; T1 立ち上がりエッジに同期
// cycle_exec:
//     out exec, 16           ; FIFO から命令を取得し実行
//     jmp cycle_exec         ; 繰り返し
//
// C コードはエンコード済み 16 ビット PIO 命令のシーケンスを
// サイクル SM の TX FIFO にプッシュします。シーケンスはバスサイクルの
// すべての側面を制御：どの制御信号をアサート/デアサートするか、
// いつクロックエッジを待つか、いつデータをサンプリングするか。
// すべてのシーケンスの最終命令は start_cycle への JMP です。

// メモリリードサイクルの簡略化されたコア 1 フロー：

// 1. z80_cycle SM が IRQ 0 をセット — 新しいサイクルの準備完了。
//    z80_addr SM が IRQ 0 をセット — アドレスの準備完了。

// 2. コア 1 がアドレスを解決しバストランザクションを準備：
pio_sm_put(pio0, SM_ADDR, (pindirs_16 << 16) | address);  // z80_addr にプッシュ
pio_interrupt_clear(pio0, 0);                                // IRQ 0 クリア → addr SM 実行

// 3. コア 1 がサイクルタイプ命令シーケンスをプッシュ：
pio_sm_put(pio0, SM_CYCLE, encoded_wait_clk_low);   // wait 0 gpio CLK
pio_sm_put(pio0, SM_CYCLE, encoded_set_mreq_rd);    // set pins: /MREQ ロー、/RD ロー
pio_sm_put(pio0, SM_CYCLE, encoded_wait_clk_high);  // wait 1 gpio CLK (T2)
pio_sm_put(pio0, SM_CYCLE, encoded_wait_clk_low);   // wait 0 gpio CLK (T2)
// ... ウェイトステート確認、T3、データサンプリング ...
pio_sm_put(pio0, SM_CYCLE, encoded_jmp_start);       // JMP start_cycle（終了）

// 4. コア 1 が RX FIFO からデータバイトを読み取り：
uint8_t data = pio_sm_get(pio0, SM_DATA);

主要な型とデータ構造

メモリブロックタイプ定数

// src/include/Z80CPU.h

#define MEMBANK_TYPE_UNKNOWN        0x00  // 未初期化 — 実行時に現れてはならない
#define MEMBANK_TYPE_PHYSICAL       0x01  // パススルー：RP2350 がバスを解放し、ホストハードウェアが応答
#define MEMBANK_TYPE_PHYSICAL_VRAM  0x02  // ホストビデオ RAM 用ウェイトステート付きパススルー
#define MEMBANK_TYPE_PHYSICAL_HW    0x04  // ホスト I/O マッピングハードウェアレジスタのパススルー
#define MEMBANK_TYPE_RAM            0x08  // 読み書き — PSRAM バンクによってバック
#define MEMBANK_TYPE_VRAM           0x10  // PSRAM ビデオ RAM — 書き込みは物理 VRAM にもミラーリング
#define MEMBANK_TYPE_ROM            0x20  // 読み取り専用 — PSRAM バンクによってバック；書き込みはサイレントに無視
#define MEMBANK_TYPE_FUNC           0x40  // 仮想デバイス — すべてのアクセスが C 関数ハンドラーを呼び出す
#define MEMBANK_TYPE_PTR            0x80  // 間接 — 各バイトが別のアドレスにリダイレクト

membankPtr エンコーディング

ビット 31..24  =  メモリタイプ  （MEMBANK_TYPE_xxx 定数）
ビット 23..16  =  PSRAM バンク  （0-63、8MB PSRAM のどの 64KB バンクか）
ビット 15..0   =  Z80 アドレス  （バンク内のブロックのベースアドレス）

// ブロック idx（各ブロック = 512 バイト）をバンク 0 の RAM タイプにマッピング：
cpu->_membankPtr[idx] = (MEMBANK_TYPE_RAM  << 24)   // 上位バイトにタイプ
                      | (MZ700_MEMBANK_0   << 16)   // バンク番号
                      | (idx * MEMORY_BLOCK_SIZE);  // このブロックのベースアドレス

// 同じブロックをバンク 2 の ROM にマッピング：
cpu->_membankPtr[idx] = (MEMBANK_TYPE_ROM  << 24)
                      | (2                 << 16)
                      | (idx * MEMORY_BLOCK_SIZE);

// 同じブロックを物理（パススルー）にマッピング：
cpu->_membankPtr[idx] = (MEMBANK_TYPE_PHYSICAL << 24)
                      | (0 << 16)
                      | (idx * MEMORY_BLOCK_SIZE);

メモリ属性（t_memAttr）

// src/include/Z80CPU.h
typedef struct {
    uint8_t   waitStates;   // アクセス時に挿入する追加 T サイクルウェイトステート数
    bool      tCycSync;     // true = 各バスサイクルの T1 立ち上がりエッジに PSRAM アクセスを同期
} t_memAttr;

// アクセスパターン：
cpu->_memAttr[bank][idx].waitStates = 1;
cpu->_memAttr[bank][idx].tCycSync   = true;

PSRAM 構造体（t_Z80PSRAM）

// src/include/Z80CPU.h
typedef struct {
    // 4MB データ空間：64 バンク × 64KB RAM/ROM イメージストレージ
    uint8_t     RAM[MEMORY_PAGE_BANKS * MEMORY_PAGE_SIZE];

    // 64KB バイト単位リダイレクトテーブル（MEMBANK_TYPE_PTR ブロックが使用）
    uint32_t    memPtr[MEMORY_PAGE_SIZE];

    // 64KB メモリアドレス関数ポインターテーブル
    // インデックス = Z80 アドレス（0x0000-0xFFFF）
    // 値 = NULL（オーバーライドなし）または C ハンドラー関数へのポインター
    MemoryFunc  memioPtr[MEMORY_PAGE_SIZE];

    // 64KB I/O ポート関数ポインターテーブル
    // インデックス = Z80 I/O ポートアドレス（0x0000-0xFFFF；Z80 は実際のポートに下位 8 ビットを使用）
    // 値 = NULL（物理 I/O にパス）または C ハンドラー関数へのポインター
    MemoryFunc  ioPtr[IO_PAGE_SIZE];
} t_Z80PSRAM;

MemoryFunc ハンドラーシグネチャ

// src/include/Z80CPU.h
typedef uint8_t (*MemoryFunc)(Z80CPU *cpu, bool read, uint16_t addr, uint8_t data);

Z80CPU コンテキスト構造体

// src/include/Z80CPU.h（簡略化）
struct Z80CPU {
    Z80           _Z80;               // Zeta Z80 エミュレーター状態（レジスタ、フラグ、PC など）

    // 高速ディスパッチテーブル：128 エントリ、Z80 アドレス空間の 512 バイトブロックごとに 1 つ
    uint32_t      _membankPtr[MEMORY_PAGE_BLOCKS];  // MEMORY_PAGE_BLOCKS = 128

    // ブロックごとのウェイトステートと同期属性、[バンク][ブロック] でインデックス
    t_memAttr     _memAttr[MEMORY_PAGE_BANKS][MEMORY_PAGE_BLOCKS];

    // 8MB PSRAM 構造体へのポインター（RAM[]、memPtr[]、memioPtr[]、ioPtr[]）
    t_Z80PSRAM   *_z80PSRAM;

    // 読み込まれたドライバー設定（JSON 解析から）
    t_drivers     _drivers;

    // コア間通信キュー（コア 1 → コア 0 およびコア 0 → コア 1）
    queue_t       requestQueue;
    queue_t       responseQueue;

    bool          halt;        // Z80 が HALT 状態
    bool          hold;        // コア 0 がコア 1 に一時停止を要求
    bool          holdAck;     // コア 1 が保留リクエストを確認応答
    bool          forceReset;  // 非同期リセットフラグ
};

ドライバー設定構造体

// src/include/Z80CPU.h

// 単一パラメータのキーと値のペア（JSON "param" 配列から）
typedef struct {
    const char   *name;   // パラメータ名文字列
    const char   *value;  // パラメータ値文字列（常に文字列；必要に応じて解析する）
} t_ifParam;

// 単一 ROM イメージ割り当て（JSON "rom" 配列から）
typedef struct {
    const char   *file;       // ROM ファイルへの SD カードパス
    uint16_t      addr;       // この ROM の Z80 ターゲットアドレス
    uint8_t       bank;       // 読み込み先の PSRAM バンク
    uint16_t      size;       // 読み込むバイト数
    uint32_t      fileofs;    // ROM ファイルのバイトオフセット
    uint8_t       waitStates; // このブロックのウェイトステート
    bool          tCycSync;   // このブロックの T1 同期
} t_drvROMConfig;

// 単一アドレス空間リマップ（JSON "addrmap" 配列から）
typedef struct {
    uint16_t      srcAddr;    // 元の Z80 アドレス
    uint16_t      dstAddr;    // リダイレクト先アドレス
    uint16_t      size;       // 範囲サイズ
    uint8_t       bank;       // PSRAM バンク
    uint8_t       type;       // MEMBANK_TYPE_xxx
} t_addrReMap;

// 単一 I/O リマップ（JSON "iomap" 配列から）
typedef struct {
    uint16_t      srcAddr;    // I/O ポートアドレス
    uint16_t      size;       // ポート範囲サイズ
    const char   *funcName;   // ハンドラー関数の名前（メモリ関数マップで検索）
} t_ioReMap;

// 1 つのインターフェースブロック（JSON "if" 配列の 1 エントリ）
typedef struct t_drvIFConfig {
    const char       *name;           // インターフェース名（例："RFS"、"MZ-1E05"）
    bool              isPhysical;     // 仮想または物理インターフェース
    int               romCount;       // ROM エントリ数
    t_drvROMConfig   *romConfig;      // ROM 設定の配列
    int               addrMapCount;   // アドレスリマップ数
    t_addrReMap      *addrMap;        // アドレスリマップテーブル
    int               ioMapCount;     // I/O リマップ数
    t_ioReMap        *ioMap;          // I/O リマップテーブル
    int               ifParamCount;   // パラメータ数
    t_ifParam        *ifParam;        // パラメータ配列
} t_drvIFConfig;

// トップレベルドライバー設定（JSON "drivers" 配列の 1 エントリ）
typedef struct t_drvConfig {
    const char       *name;           // ドライバー名 — virtualFuncMap エントリと一致する必要がある
    bool              isPhysical;     // 仮想または物理ドライバー
    int               ifCount;        // インターフェース数
    t_drvIFConfig    *ifConfig;       // インターフェース配列
    ResetFunc         reset_ptr;      // ドライバー init が設定するリセットハンドラー
    PollFunc          poll_ptr;       // ドライバー init が設定するポールハンドラー
    TaskFunc          task_ptr;       // ドライバー init が設定するタスクハンドラー
} t_drvConfig;

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

メインループ構造

// src/Z80CPU.c — コア 1 エントリポイント
void __func_in_RAM(Z80CPU_cpu)(Z80CPU *cpu)
{
    // コア 0 にコア 1 が動作中であることをシグナルする
    multicore_fifo_push_blocking(1);

    while(1)
    {
        // --- 保留チェック ---
        // コア 0 はコア 1 を一時停止できる（例：安全な設定リロード用）
        if(cpu->hold == true)
        {
            cpu->holdAck = true;
            while(cpu->hold == true);  // スピン待機
            cpu->holdAck = false;
        }

        // --- ドライバーポール ---
        // 短い定期的なハウスキーピングのために各ドライバーのポールハンドラーを呼び出す
        for(int idx = 0; idx < cpu->_drivers.drvCount; idx++)
        {
            if(cpu->_drivers.driver[idx].poll_ptr != NULL)
                cpu->_drivers.driver[idx].poll_ptr(cpu);
        }

        // --- Z80 実行 ---
        // 2048 クロックサイクル Z80 エミュレーターを実行する
        z80_run(&cpu->_Z80, 2048);

        // --- リセットチェック ---
        // PIO IRQ 3 = ホストバスでハードウェア RESET がアサートされた
        if(cpu->forceReset || (pio_2->irq & (1u << 3)) != 0)
        {
            Z80CPU_reset(cpu);
            CLEAR_IRQ(pio_2, 3);
        }
    }
}

メモリ読み取りディスパッチ

// src/Z80CPU.c（簡略化・注釈付き）
uint8_t __func_in_RAM(Z80CPU_readMem)(Z80CPU *cpu, uint16_t addr)
{
    // ステップ 1：このアドレスを含む 512 バイトブロックを検索
    uint8_t  blockIdx   = addr >> 9;                        // addr / 512
    uint32_t membankptr = cpu->_membankPtr[blockIdx];       // 32 ビットエンコードエントリ

    // ステップ 2：エンコードされたエントリから 3 つのフィールドを抽出
    uint8_t  memType    = (membankptr >> 24) & 0xFF;        // 上位バイト = タイプ
    uint8_t  bank       = (membankptr >> 16) & 0xFF;        // 中位バイト = バンク
    uint16_t blockBase  = membankptr & 0xFFFF;              // 下位 16 ビット = ベースアドレス

    // ステップ 3：このアドレスの PSRAM バンクへのオフセットを計算
    uint32_t RAMaddr    = (bank * MEMORY_PAGE_SIZE) + blockBase;
    uint16_t blockOfs   = addr & (MEMORY_BLOCK_SIZE - 1);  // addr % 512 = ブロック内オフセット

    uint8_t  waitStates = cpu->_memAttr[bank][blockIdx].waitStates;
    uint8_t  data       = 0x00;

    switch(memType)
    {
        case MEMBANK_TYPE_PHYSICAL:
        case MEMBANK_TYPE_PHYSICAL_VRAM:
        case MEMBANK_TYPE_PHYSICAL_HW:
            // パススルー：ホストハードウェアに応答させる
            data = Z80CPU_readPhysicalMem(cpu, addr);
            break;

        case MEMBANK_TYPE_RAM:
        case MEMBANK_TYPE_VRAM:
        case MEMBANK_TYPE_ROM:
            if(cpu->_z80PSRAM->memioPtr[addr] != NULL)
            {
                // この特定のアドレスにハンドラーがインストールされている。
                // ハンドラーが使用または変更できるように現在の PSRAM 値を 'data' として渡す。
                data = cpu->_z80PSRAM->memioPtr[addr](
                           cpu, true, addr,
                           cpu->_z80PSRAM->RAM[RAMaddr + blockOfs]);
            }
            else
            {
                // ハンドラーなし — PSRAM から直接読み取る
                data = cpu->_z80PSRAM->RAM[RAMaddr + blockOfs];
            }
            if(waitStates) Z80CPU_waitPhysicalStates(cpu, waitStates);
            break;

        case MEMBANK_TYPE_FUNC:
            // 純粋な仮想デバイス — PSRAM バッキングなし
            if(cpu->_z80PSRAM->memioPtr[addr] != NULL)
                data = cpu->_z80PSRAM->memioPtr[addr](cpu, true, addr, 0);
            break;

        case MEMBANK_TYPE_PTR:
            // 間接 — バイトごとのポインターに従って再帰
            data = Z80CPU_readMem(cpu, addr, cpu->_z80PSRAM->memPtr[addr]);
            break;
    }
    return data;
}

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

virtualFuncMap — トップレベルドライバー登録

// src/Z80CPU.c
#ifdef INCLUDE_SHARP_DRIVERS
    {"MZ700",      MZ700_Init},      // Sharp MZ-700 ペルソナ
    {"MZ80A",      MZ80A_Init},      // Sharp MZ-80A ペルソナ
    {"MZ2000",     MZ2000_Init},     // Sharp MZ-2000 ペルソナ
    {"MZ1500",     MZ1500_Init},     // Sharp MZ-1500 ペルソナ
    {"MZ1R23",     MZ1R23_Init},     // 漢字 ROM / 辞書 ROM ボード
    {"MZ1R37",     MZ1R37_Init},     // 640KB 拡張メモリマネージャー
    {"PIO3034",    PIO3034_Init},    // IO DATA 320KB EMM
    {"Celestite",  Celestite_Init},  // Celestite LAN/メモリ複合ボード
#endif
};

初期化フロー

Z80CPU_configFromJSON()
    ├── Z80CPU_configDriversFromJSON()   JSON から "drivers" 配列を解析
    │       各ドライバーエントリに対して：
    │           ├── virtualFuncMap[] で名前を検索
    │           ├── インターフェース設定を解析（ROM、addrmap、iomap、param）
    │           └── VirtualFunc(cpu, appConfig, &drvConfig, NULL) を呼び出す
    │                   ↓
    │               ドライバー init が設定する：
    │                   ├── _membankPtr[] エントリ（ブロックタイプとバンク）
    │                   ├── _memAttr[][] エントリ（ウェイトステート、同期）
    │                   ├── memioPtr[] ハンドラー（メモリアドレスフック）
    │                   ├── ioPtr[] ハンドラー（I/O ポートフック）
    │                   ├── config->reset_ptr = MyDriver_Reset
    │                   ├── config->poll_ptr  = MyDriver_PollCB
    │                   └── config->task_ptr  = MyDriver_TaskProcessor
    │
    ├── Z80CPU_configMemoryFromJSON()    "memory" 配列を適用（ドライバーのデフォルトを上書き）
    └── Z80CPU_configIOFromJSON()        "io" 配列を適用（ドライバーのデフォルトを上書き）

ドライバーライフサイクルコールバック

実例：MZ-700 ドライバー

バンキングハンドラー — MZ700_IO_MemoryBankPorts()

// src/drivers/Sharp/MZ700.c
uint8_t MZ700_IO_MemoryBankPorts(Z80CPU *cpu, bool read, uint16_t addr, uint8_t data)
{
    uint8_t port = (uint8_t)(addr & 0xFF);  // Z80 アドレスからポート番号を抽出

    // 読み取りには副作用なし
    if(read) return 0xFF;

    // --- ポート 0xE0：下位 4KB DRAM を有効化 ---
    // モニター ROM（0x0000-0x0FFF）をバンク 1 の RAM に入れ替える
    if(port == 0xE0 && !MZ700Ctrl.loDRAMen)
    {
        for(int idx = 0; idx < (0x1000 / MEMORY_BLOCK_SIZE); idx++)
        {
            cpu->_membankPtr[idx] = (MEMBANK_TYPE_RAM << 24)
                                  | (MZ700_MEMBANK_1  << 16)
                                  | (idx * MEMORY_BLOCK_SIZE);
        }
        MZ700Ctrl.loDRAMen = true;
    }

    // --- ポート 0xE1：上位 DRAM を有効化（0xD000-0xFFFF）---
    // 現在の上位 membankPtr エントリを保存してバンク 1 の RAM に置き換える
    if(port == 0xE1 && !MZ700Ctrl.inhibit && !MZ700Ctrl.hiDRAMen)
    {
        // ... バンクを入れ替えて保存する
        MZ700Ctrl.hiDRAMen = true;
    }

    // --- ポート 0xE2：下位 ROM を復元 ---
    if(port == 0xE2 && MZ700Ctrl.loDRAMen)
    {
        // ... バンク 0 の ROM に復元する
        MZ700Ctrl.loDRAMen = false;
    }

    // --- ポート 0xE3：上位ハードウェアマッピングを復元 ---
    if(port == 0xE3 && MZ700Ctrl.hiDRAMen)
    {
        // ... 保存されたマッピングを復元する
        MZ700Ctrl.hiDRAMen = false;
    }

    // --- ポート 0xE4：上位 DRAM スワップを禁止 ---
    if(port == 0xE4)
        MZ700Ctrl.inhibit = true;

    // --- ポート 0xE5：上位禁止を有効化（エイリアス）---
    if(port == 0xE5)
        MZ700Ctrl.inhibit = false;

    return 0;
}

新しいドライバーの作成 — ステップバイステップ

ステップ 1 — ソースファイルを作成する

// ファイル：src/include/drivers/Sharp/MyDriver.h
#ifndef MYDRIVER_H
#define MYDRIVER_H

#include "Z80CPU.h"
#include "flash_ram.h"   // t_FlashAppConfigHeader 用

// トップレベル init（virtualFuncMap に登録）
uint8_t MyDriver_Init(Z80CPU *cpu,
                      t_FlashAppConfigHeader *appConfig,
                      t_drvConfig *config,
                      const char *ifName);

// ライフサイクルコールバック（init で設定、コア 1 ループが呼び出す）
uint8_t MyDriver_Reset(Z80CPU *cpu);
uint8_t MyDriver_PollCB(Z80CPU *cpu);
uint8_t MyDriver_TaskProcessor(Z80CPU *cpu,
                                enum Z80CPU_TASK_NAME task,
                                char *param);

// メモリ / I/O ハンドラー関数
uint8_t MyDriver_MemHandler(Z80CPU *cpu, bool read, uint16_t addr, uint8_t data);
uint8_t MyDriver_IOHandler(Z80CPU *cpu, bool read, uint16_t addr, uint8_t data);

#endif // MYDRIVER_H

ステップ 2 — CMakeLists.txt に追加する

# src/CMakeLists.txt — Sharp ドライバーリストにファイルを追加
set(pZ80_drivers_sharp_src
    ${CMAKE_CURRENT_LIST_DIR}/drivers/Sharp/MZ700.c
    # ... 既存のドライバー ...
    # ドライバーをここに追加：
    ${CMAKE_CURRENT_LIST_DIR}/drivers/Sharp/MyDriver.c
)

ステップ 3 — Z80CPU.c にヘッダーをインクルードする

// src/Z80CPU.c — 他のドライバーインクルードの近く
#ifdef INCLUDE_SHARP_DRIVERS
#include "drivers/Sharp/MZ700.h"
// ... 既存のインクルード ...
// インクルードを追加：
#include "drivers/Sharp/MyDriver.h"
#endif

ステップ 4 — virtualFuncMap に登録する

// src/Z80CPU.c
static const t_VirtualFuncMap virtualFuncMap[] = {
#ifdef INCLUDE_SHARP_DRIVERS
    {"MZ700",    MZ700_Init},
    {"MZ80A",    MZ80A_Init},
    {"MZ2000",   MZ2000_Init},
    // ドライバーを追加：
    {"MyDriver", MyDriver_Init},
#endif
};

ステップ 5 — config.json にドライバーを追加する

"drivers": [
  {
    "enable": 1,
    "name":   "MZ700",
    "type":   "VIRTUAL",
    "if": []
  },
  {
    "enable": 1,
    "name":   "MyDriver",
    "type":   "VIRTUAL",
    "if": []
  }
]

ステップ 6 — ビルドとテスト

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


# ファームウェア出力：

# build/bin/model/BaseZ80/BaseZ80_0x10020000.elf   （デバッグ ELF — GDB で使用）

# build/bin/model/BaseZ80/BaseZ80_0x10020000.bin   （OTA バイナリ）


# OTA ウェブページ経由でフラッシュするか、直接デバッグする：
openocd -f interface/cmsis-dap.cfg -f target/rp2350_tzpu.cfg -c "adapter speed 5000" &
cd build/bin/model/BaseZ80
gdb-multiarch BaseZ80_0x10020000.elf
(gdb) break MyDriver_Init
(gdb) continue

ESP32 ファームウェア — ネットワークモード選択

# ネットワークモードの選択（ESP32 ファームウェアビルド前）：
cp sdkconfig.mode_ncm_only sdkconfig       # NCM のみ（WiFi なし、FCC/RED 安全）
# cp sdkconfig.mode_wifi_only sdkconfig     # WiFi のみ
# cp sdkconfig.mode_wifi_and_ncm sdkconfig  # WiFi と NCM の両方
idf.py build

メモリフックパターンの詳細

パターン 1 — 純粋な仮想デバイス（FUNC ブロック）

// 0xC000-0xCFFF をバンク 4 の純粋な仮想デバイスとしてマッピング
int startBlock = 0xC000 / MEMORY_BLOCK_SIZE;
int endBlock   = 0xD000 / MEMORY_BLOCK_SIZE;

for(int idx = startBlock; idx < endBlock; idx++)
{
    cpu->_membankPtr[idx] = (MEMBANK_TYPE_FUNC << 24)
                          | (4               << 16)
                          | (idx * MEMORY_BLOCK_SIZE);
}

// 範囲内のすべてのアドレスにハンドラーをインストール
for(uint32_t addr = 0xC000; addr < 0xD000; addr++)
    cpu->_z80PSRAM->memioPtr[addr] = (MemoryFunc)MyVirtualDevice_Handler;

パターン 2 — RAM 領域への書き込みを横取りする

パターン 3 — ROM 領域への書き込みをトラップする

パターン 4 — スパースハンドラー（個別アドレス）

パターン 5 — I/O ポートハンドラー

// I/O ポート 0x80-0x8F（16 ポート）にハンドラーをインストール
for(int port = 0x80; port <= 0x8F; port++)
    cpu->_z80PSRAM->ioPtr[port] = (MemoryFunc)MyIO_Handler;

コア 0 / コア 1 の対話

コア間キューの使用

よくある落とし穴

デバッグログ

debugf() — バッファ付きデバッグ出力

// src/include/debug.h

// Primary debug output — mutex-protected, buffered in PSRAM, flushed to USB
debugf("Boot stage %d reached, PSRAM size = %d bytes\n", stage, psramSize);

// Single character / string output (also mutex-protected)
debug_putchar('.');
debug_puts("Init complete\n");

plogf() — PSRAM 永続起動ログ

// src/include/debug.h

// PSRAM persistent log structure (at 0x117FF000)
#define PLOG_ADDR   0x117FF000
#define PLOG_SIZE   3840          // 4KB minus 256 bytes reserved for fault diagnostics
#define PLOG_MAGIC  0x504C4F47    // "PLOG"

typedef struct {
    uint32_t  magic;              // PLOG_MAGIC if buffer contains valid data
    uint32_t  len;                // Current write position in buf[]
    char      buf[PLOG_SIZE - 8]; // Circular text buffer
} t_PsramLog;

// Write to persistent log (no mutex — Core 0 boot path only)
plogf("FSPI init: DMA TX=%d RX=%d\n", gDmaTx, gDmaRx);

// Dump captured log on next successful boot (called from main loop)
dump_plog();  // Outputs plog contents via debugf(), then clears the buffer

適切なデバッグ出力の選択

ウォッチドッグと起動進捗トラッキング

ウォッチドッグタイマー

// src/model/BaseZ80/main.c
watchdog_enable(30000, true);  // 30s timeout, pause-on-debug enabled

// Floppy disk load with retry logic — kick watchdog between attempts
for (int attempt = 0; attempt < 10; attempt++)
{
    watchdog_update();
    bytesXfer = ESP_readFloppyDiskFile(filename, ..., diskNo);
    if (bytesXfer > 0) break;
    watchdog_update();
    sleep_ms(500);
}

// QD disk change — kick watchdog while waiting for Core 1 hold acknowledge
z80CPU->hold = true;
for (int w = 3000; !z80CPU->holdAck && w > 0; w--)
{
    sleep_ms(1);
    if ((w % 1000) == 0) watchdog_update();
}

ウォッチドッグスクラッチレジスタ

// src/model/BaseZ80/main.c

// Scratch register allocation
#define BOOTP_SCR_MAGIC    5   // Magic marker: 0xB00710BE
#define BOOTP_SCR_STAGE    6   // Current boot stage code
#define BOOTP_SCR_RSTCAUS  7   // Reset cause from hardware
// scratch[0-3] = boot attempt history (FIFO, most recent in [3])
// scratch[4]   = SPI diagnostic counters (packed bitfield)

#define BOOTP_MAGIC  0xB00710BE  // "BOOT-PROBE" marker

// Inline function to record current boot stage
static inline void bootStage(uint32_t stage)
{
    watchdog_hw->scratch[BOOTP_SCR_STAGE] = stage;
}

// Usage throughout boot sequence:
bootStage(BOOTP_START);         // 0x01 — entry point
// ... clock setup ...
bootStage(BOOTP_CLK_SET);       // 0x02
// ... PSRAM init ...
bootStage(BOOTP_PSRAM_INIT);    // 0x03
watchdog_update();
bootStage(BOOTP_PSRAM_OK);      // 0x04
// ... and so on through BOOTP_MAIN_LOOP (0x10)

起動ステージリファレンス

ICE デバッグシェル（dbgsh.c）

フォールトハンドラーと PSRAM 診断

PSRAM フォールト診断構造体

// src/fault_handlers.c

#define PSRAM_DIAG_ADDR   0x117FFF00   // Last 256 bytes of 8MB PSRAM
#define PSRAM_DIAG_MAGIC  0xFA017000   // "FAULT" marker

typedef struct {
    uint32_t  magic;       // PSRAM_DIAG_MAGIC if valid
    uint32_t  faultType;   // 1=Hard, 2=MemManage, 3=BusFault, 4=UsageFault
    uint32_t  pc;          // Program counter at fault
    uint32_t  lr;          // Link register (return address)
    uint32_t  sp;          // Stack pointer
    uint32_t  r0, r1, r2, r3, r12;  // General-purpose registers
    uint32_t  psr;         // Program Status Register
    uint32_t  cfsr;        // Configurable Fault Status Register
    uint32_t  hfsr;        // Hard Fault Status Register
    uint32_t  bfar;        // Bus Fault Address Register
    uint32_t  mmfar;       // Memory Management Fault Address Register
    uint32_t  coreId;      // Which core faulted (0 or 1)
} t_PsramFaultDiag;

フォールトハンドラーの実装

// Interpreting fault diagnostics (from GDB or from debugf output):
//
// faultType=1 (Hard Fault):
//   Check HFSR bit 30 (FORCED) — indicates escalated fault.
//   Check CFSR for the original fault type.
//
// faultType=3 (Bus Fault):
//   Check CFSR bits [15:8] for bus fault status.
//   If BFARVALID (bit 15), BFAR contains the faulting address.
//   Common cause: PSRAM SPI contention between Core 0 and Core 1.
//
// faultType=4 (Usage Fault):
//   Check CFSR bits [25:16] for usage fault status.
//   UNDEFINSTR = undefined instruction (corrupted code in Flash/PSRAM).
//   DIVBYZERO  = division by zero (if enabled).
//
// PC value: the instruction that faulted.
// LR value: the return address (caller of the faulting function).

PSRAM 診断メモリマップ

バイナリ IPC プロトコル (FSPI v1.1)

フレーム構造

// src/include/ipc_protocol.h

typedef struct __attribute__((packed)) {
    uint8_t   frameType;              // 0:  IPCF_TYPE_COMMAND / RESPONSE / NOP
    uint8_t   command;                // 1:  IPCF_CMD_* opcode
    uint8_t   status;                 // 2:  IPCF_STATUS_* (response only)
    uint8_t   seqNum;                 // 3:  Sequence number (retry detection)
    uint16_t  payloadLen;             // 4:  Payload bytes (little-endian)
    uint16_t  sectorCount;            // 6:  Sectors in burst (1–16)
    uint32_t  fileOffset;             // 8:  Byte offset in file
    uint8_t   diskNo;                 // 12: Drive number
    uint8_t   flags;                  // 13: IPCF_FLAG_*
    uint16_t  reserved;               // 14: Reserved
    char      filename[48];           // 16: Null-terminated path (48 bytes)
} t_IpcFrameHdr;                      // Total: 64 bytes

// Frame layout:
// [64-byte header][0–8192 bytes payload][4-byte CRC32]

#define IPCF_HEADER_SIZE    64
#define IPCF_MAX_SECTORS    16        // Max sectors per burst
#define IPCF_SECTOR_SIZE    512       // Bytes per sector
#define IPCF_CRC_SIZE       4         // CRC32 trailer
#define IPCF_MAX_PAYLOAD    (IPCF_MAX_SECTORS * IPCF_SECTOR_SIZE)  // 8192
#define IPCF_MAX_FRAME_SIZE (IPCF_HEADER_SIZE + IPCF_MAX_PAYLOAD + IPCF_CRC_SIZE)  // 8260

コマンドオペコード

DMA と整合性

参考サイト

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