tranZPUterファイリングシステム (TZFS) — デベロッパーズガイド

TZFS デベロッパーズガイド

非アセンブリプログラマー向け Z80 アセンブリ入門

ソースツリー

設定：tzfs_definitions.asm

BUILD_FUSIONX EQU 0    ; 1 = tranZPUter FusionX ハードウェアで動作
BUILD_PICOZ80 EQU 1    ; 1 = picoZ80 ボードで動作
ENADEBUG      EQU 0    ; 1 = 動作中の追加診断出力を有効化

UROMADDR    EQU 0E800H   ; TZFS エントリポイントのベースアドレス（ユーザー ROM ウィンドウ）
TZVARMEM    EQU 0EC80H   ; TZFS 変数ブロック（WARMSTART フラグ、モデル、テープ補正値）
TZSVCMEM    EQU 0ED80H   ; K64F サービス通信ブロック（共有メモリ API）
BANKRAMADDR EQU 02000H   ; bank4 アセンブラ/逆アセンブラテーブルのベースアドレス

MMCFG       EQU 060H     ; メモリ管理設定レジスタの I/O ポートアドレス

TZMM_TZFS   EQU 022H     ; モード 0x22：バンク 0 — 0xE800-0xFFFF のメイン TZFS コード
TZMM_TZFS2  EQU 023H     ; モード 0x23：バンク 1 — 0xF000-0xFFFF でマッピングされた tzfs_bank2
TZMM_TZFS3  EQU 024H     ; モード 0x24：バンク 2 — 0xF000-0xFFFF でマッピングされた tzfs_bank3
TZMM_TZFS4  EQU 025H     ; モード 0x25：バンク 3 — フルユーザー範囲にわたってマッピングされた tzfs_bank4

BELL    EQU 007H    ; ターミナルベル
CR      EQU 00DH    ; キャリッジリターン
LF      EQU 00AH    ; ラインフィード
CS      EQU 00CH    ; 画面クリア
SPACE   EQU 020H    ; ASCII スペース
DELETE  EQU 07FH    ; Delete キー

バンク切り替えの詳細

; TZFS コマンドテーブルエントリ 1 つ：
;
;   DB  FLAGS          ; 1 バイト：END|MATCH|BANK[5:3]|SIZE[2:0]
;   DB  "COMMAND"      ; SIZE バイト：コマンド文字列（ヌル終端なし）
;   DW  HANDLER_ADDR   ; 2 バイト：名前付きバンク内のハンドラルーティンのアドレス
;
; フラグバイト：
;   ビット 7 = 1：テーブル終端マーカー（最後のエントリ）。
;   ビット 6 = 1：完全一致が必要（コマンドは入力全体でなければならない、後続文字なし）。
;   ビット 5:3   バンク番号：0=TZMM_TZFS、1=TZMM_TZFS2、2=TZMM_TZFS3、3=TZMM_TZFS4。
;   ビット 2:0   コマンド文字列のバイト長。
;
; 例 — DASM コマンド（バンク 3 / TZMM_TZFS4 に存在、4 文字文字列）：
CMDTABLE:
    DB  000H | 000H | 018H | 004H    ; FLAGS：非終端、非完全一致、バンク 3 (0x18)、長さ 4
    DB  "DASM"                        ; コマンド文字列
    DW  ?DASM                         ; ハンドラ — DASM_MAIN のバンク間スタブ

ジャンプテーブル

CMT_RDINF  EQU UROMADDR+80H  ; 0xE880 — テープ/SD ファイルヘッダーを読み取る
CMT_RDDATA EQU UROMADDR+83H  ; 0xE883 — テープ/SD ファイルデータ本体を読み取る
CMT_WRINF  EQU UROMADDR+86H  ; 0xE886 — テープ/SD ファイルヘッダーを書き込む
CMT_WRDATA EQU UROMADDR+89H  ; 0xE889 — テープ/SD ファイルデータ本体を書き込む
CMT_VERIFY EQU UROMADDR+8CH  ; 0xE88C — テープデータをメモリと照合して確認する
CMT_DIR    EQU UROMADDR+8FH  ; 0xE88F — SD カードディレクトリリスト
CMT_CD     EQU UROMADDR+92H  ; 0xE892 — SD カードディレクトリ変更
SET_FREQ   EQU UROMADDR+95H  ; 0xE895 — CPU 動作周波数を設定する

CALL ?PRINTMSG

モジュールウォークスルー

K64F サービスコール

; ステップ 1 — サービスブロックにコマンドとパラメータを設定する。
 LD   A, TZSVC_CMD_LOADFILE
 LD   (TZSVCCMD), A              ; コマンドバイトを書き込む

; ステップ 2 — K64F にリクエストをシグナルする。
 LD   A, TZSVC_STATUS_REQUEST
 LD   (TZSVCRESULT), A           ; 結果フィールドを「リクエスト保留中」に設定
 OUT  (SVCREQ), A                ; K64F 割り込みをトリガー — K64F はこのポートをポーリングする

; ステップ 3 — K64F が操作を完了するまで結果フィールドをポーリングする。
WAIT:
    LD   A, (TZSVCRESULT)
    CP   TZSVC_STATUS_REQUEST   ; まだ保留中？
    JR   Z, WAIT                ; はい — 待ち続ける

; ステップ 4 — 結果を確認する。TZSVC_STATUS_OK (0x00) = 成功、非ゼロ = エラー。
 LD   A, (TZSVCRESULT)
 OR   A
 JR   NZ, ERROR

TZSVC_CMD_LOADFILE      ; SD カードから Z80 RAM に名前付きファイルを読み込む
TZSVC_CMD_SAVEFILE      ; Z80 RAM 領域を SD カードの名前付きファイルに保存する
TZSVC_CMD_DIR           ; SD カードからディレクトリリストを読み取る
TZSVC_CMD_SD_RDPAGE     ; 生の SD セクターを読み取る
TZSVC_CMD_SD_WRPAGE     ; 生の SD セクターに書き込む
TZSVC_CMD_EMU_SETMZ80K  ; ハードウェアエミュレーションを MZ-80K モードに切り替える
TZSVC_CMD_EMU_SETMZ80A  ; ハードウェアエミュレーションを MZ-80A モードに切り替える
TZSVC_CMD_EMU_SETMZ700  ; ハードウェアエミュレーションを MZ-700 モードに切り替える
TZSVC_CMD_EMU_SETMZ800  ; ハードウェアエミュレーションを MZ-800 モードに切り替える
TZSVC_CMD_EMU_SETMZ80B  ; ハードウェアエミュレーションを MZ-80B モードに切り替える
TZSVC_CMD_CPU_SETZ80    ; アクティブな CPU をハードウェア Z80 に設定する
TZSVC_CMD_CPU_SETT80    ; ファームウェアを読み込み、FPGA に T80（FPGA ソフトコア Z80）を有効化するシグナルを送る
TZSVC_CMD_CPU_SETZPUEVO ; ファームウェアを読み込み、FPGA に ZPU Evolution（FPGA ソフト CPU）を有効化するシグナルを送る
TZSVC_CMD_SET_VIDMODE   ; ビデオ出力モードを設定する
TZSVC_CMD_SET_VGAMODE   ; VGA 出力モードを設定する
TZSVC_CMD_SET_VBORDER   ; ビデオボーダーカラーを設定する

新しいモニターコマンドの追加

PROBE:
    ; エントリ時に HL はモニター入力バッファのパラメータを指す。
    CALL  SKIPCOMMA           ; 開始ポートを解析する
    ...                       ; 実装
    RET

?PROBE:
    PUSH  AF
    LD    A, TZMM_TZFS3
    OUT   (MMCFG), A          ; bank3 に切り替える
    CALL  PROBE               ; ハンドラを呼び出す
    LD    A, TZMM_TZFS
    OUT   (MMCFG), A          ; bank0 を復元する
    POP   AF
    RET

; FLAGS：非終端（bit7=0）、非完全一致（bit6=0）、バンク 2 = 0x10、長さ 5 = 0x05
    DB  000H | 000H | 010H | 005H
    DB  "PROBE"
    DW  ?PROBE

新しいハードウェアプラットフォームの追加

BUILD_NEWBOARD EQU 0    ; 1 = 新しいターゲットボード向けにビルド

IF BUILD_NEWBOARD = 1
MMCFG        EQU 070H         ; 新しいボードはメモリ管理にポート 0x70 を使用
TZMM_TZFS5   EQU 026H         ; 新しいボード用の追加バンクモード
ENDIF

デバッグのヒント

ビルド環境

# Install Java runtime (required for the GLASS assembler)
sudo apt install -y default-jre git

# Clone the repository
git clone https://git.eaw.app/eaw/tzpuFusionX.git
cd tzpuFusionX

# Initialise git submodules
git submodule update --init --recursive

# Build TZFS ROMs for all target machines
./build.sh --tzfs

# Build CP/M (CBIOS is part of the TZFS source tree)
./build.sh --cpm

# Build everything (ROMs, TZFS, CP/M, drivers, CPLD)
./build.sh --all

1. コードをプッシュして Gitea リポジトリの master ブランチに反映します。
2. Gitea が Webhook を送信（HTTP 通知）して Jenkins サーバーに通知します。
3. Jenkins がリポジトリをクローンして、クリーンなワークスペースに配置します。
4. Jenkins が ./build.sh --tzfs を実行して、すべてのターゲットマシン（MZ-80A、MZ-700、MZ-2000）向けの TZFS ファームウェアをアセンブルします。
5. Jenkins が ./build.sh --cpm を実行して、各ターゲット向けの CP/M 2.2 バイナリをビルドします。
6. Jenkins が出力をパッケージングして、バージョン付き tarball（FusionX-TZFS-v1.08.tar.gz、FusionX-CPM-v1.08.tar.gz）を作成します。
7. Jenkins が Gitea Release を作成して、tarball をダウンロード可能なアセットとして添付します。
8. Jenkins がメールを送信して、成功または失敗を報告します。

# Install Docker (Debian/Ubuntu)
sudo apt update && sudo apt install -y docker.io docker-compose
sudo systemctl enable docker && sudo systemctl start docker

# Create the Jenkins directory
sudo mkdir -p /srv/jenkins/data
cd /srv/jenkins

# /srv/jenkins/docker-compose.yml
version: '3.8'
services:
  jenkins:
    image: jenkins/jenkins:lts
    ports:
      - "8080:8080"
    volumes:
      - /srv/jenkins/data:/var/jenkins_home
    environment:
      - JAVA_OPTS=-Djenkins.install.runSetupWizard=false
    restart: unless-stopped

# Start Jenkins
docker-compose up -d

# Get the initial admin password (first run only)
docker-compose logs jenkins | grep "initial admin password" -A 2

# Open http://your-server:8080 in a browser

1. Jenkins ダッシュボードで New Item をクリックします。
2. 名前（例：TZFS-Build）を入力し、Pipeline を選択して OK をクリックします。
3. Pipeline セクションで、Definition を「Pipeline script」に設定し、以下を貼り付けます：

pipeline {
    agent any
    environment {
        GITEA_URL   = "https://git.eaw.app"
        REPO_URL    = "https://git.eaw.app/eaw/tzpuFusionX.git"
        GITEA_TOKEN = credentials('gitea-api-token')
        GITEA_OWNER = "eaw"
        GITEA_REPO  = "tzpuFusionX"
    }
    triggers {
        GenericTrigger(
            genericVariables: [[key: 'ref', value: '$.ref']],
            causeString: 'Triggered by Gitea push to $ref',
            token: 'tzfs-build-trigger',
            regexpFilterText: '$ref',
            regexpFilterExpression: '^refs/heads/(main|master)$'
        )
    }
    stages {
        stage('Checkout') {
            steps {
                cleanWs()
                git url: "${REPO_URL}", branch: 'master'
                sh 'git submodule update --init --recursive'
            }
        }
        stage('Build TZFS ROMs') {
            steps {
                sh 'chmod +x build.sh && mkdir -p software/tmp software/roms'
                sh './build.sh --tzfs'
            }
        }
        stage('Build CP/M') {
            steps {
                sh './build.sh --cpm'
            }
        }
        stage('Package') {
            steps {
                script {
                    def ver = readFile('VERSION').trim()
                    sh """
                        mkdir -p release/tzfs release/cpm
                        cp software/roms/tzfs_*.rom software/roms/testtz_*.mzf release/tzfs/ 2>/dev/null || true
                        cp software/roms/cpm223_*.bin release/cpm/ 2>/dev/null || true
                        cd release/tzfs && tar czf ../../FusionX-TZFS-v${ver}.tar.gz * && cd ../..
                        cd release/cpm  && tar czf ../../FusionX-CPM-v${ver}.tar.gz *  && cd ../..
                    """
                    archiveArtifacts artifacts: "FusionX-*-v${ver}.tar.gz"
                }
            }
        }
    }
    post {
        success { mail to: 'your-email@example.com', subject: "TZFS Build - SUCCESS", body: "Build completed." }
        failure { mail to: 'your-email@example.com', subject: "TZFS Build - FAILED", body: "Check console output." }
        always  { cleanWs() }
    }
}

• Target URL: http://your-server:8080/generic-webhook-trigger/invoke?token=tzfs-build-trigger
• Content Type: application/json
• Trigger On: Push Events

参考サイト