tranZPUter FusionX デベロッパーズガイド

概要

1. Linuxカーネルモジュール（z80drv.ko、ttymzdrv.ko）— Cで記述され、SigmaStar Linux 4.9-rtカーネルツリーに対してビルドされます。z80drvは分離されたCPUコアでZ80エミュレーションディスパッチループを実行し、SPIとGPIOでCPLDと通信します。ttymzdrvはSharp MZキーボードと文字ディスプレイハードウェアへのTTYインターフェースを提供します。
2. ユーザー空間ユーティリティ（z80ctrl、k64fcpu、sharpbiter）— Cで記述され、arm-linux-gnueabihf-gccでクロスコンパイルされます。これらのユーティリティは実行時にカーネルモジュールを起動、停止、設定します。k64fcpuはK64F仮想CPUインターフェースをエミュレートするデーモンとして動作し、sharpbiterはホスト機ソフトウェアとLinuxコンソールの間でキーボードとディスプレイへのアクセスを調整します。
3. CPLD RTL（VHDL） — Altera Quartus II 13.0.1 SP1 Web Editionでビルドされます。CPLDはホスト機のZ80バス上に直接置かれ、物理的なZ80バス信号とSigmaStar SOM（System-on-Module）の間のハードウェアインターフェースとして機能します。すべてのバスサイクルをキャプチャし、SOMに通知し、読み取りサイクルのためにSOMに代わってZ80データバスを駆動します。

---

ソースツリー

FusionX/
├── CPLD/
│   └── v1.0/
│       ├── MZ80A/build/          Sharp MZ-80A用Quartus IIプロジェクト
│       ├── MZ700/build/          Sharp MZ-700用Quartus IIプロジェクト
│       ├── MZ2000/build/         Sharp MZ-2000用Quartus IIプロジェクト
│       ├── PCW8256/build/        Amstrad PCW-8256用Quartus IIプロジェクト
│       ├── tzpuFusionX.vhd           メインRTL（FSM、SPI、バスインターフェース、ビデオ/オーディオ）
│       ├── tzpuFusionX_Toplevel.vhd  トップレベルエンティティとI/Oピンアサイン
│       └── tzpuFusionX_pkg.vhd       共有パッケージ（型、定数、ジェネリクス）
└── software/
    ├── linux/
    │   └── Build_FusionX.sh      マスタービルドスクリプト（U-boot + カーネル + rootfs + apps）
    └── FusionX/
        └── src/
            ├── z80drv/
            │   ├── src.mz80a/    MZ-80Aビルドバリアント用MakefileとSymlinks
            │   ├── src.mz700/    MZ-700ビルドバリアント
            │   ├── src.mz2000/   MZ-2000ビルドバリアント
            │   ├── src.pcw/      PCW-8256ビルドバリアント
            │   └── src/          共通ソースファイル：
            │       ├── z80driver.c      メインカーネルモジュール：ディスパッチループ、メモリ/IOルーティング
            │       ├── z80driver.h      データ構造、マシンごとのメモリマップ定数
            │       ├── z80io.c          HAL：SPI書き込みパス、GPIO読み取りパス、CPLD通信
            │       ├── emumz.c          Zeta Z80命令実行ラッパー
            │       ├── z80vhw_mz80a.c   MZ-80A仮想ハードウェア
            │       ├── z80vhw_mz700.c   MZ-700仮想ハードウェア
            │       ├── z80vhw_mz2000.c  MZ-2000仮想ハードウェア
            │       ├── z80vhw_pcw.c     PCW-8256仮想ハードウェア
            │       ├── z80vhw_rfs.c     ROMファイリングシステム仮想デバイス
            │       └── z80vhw_tzpu.c    tranZPUter SW仮想ハードウェア（K64Fスタブ）
            ├── ttymz/
            │   ├── Makefile
            │   └── ttymzdrv.c           MZキーボード/ディスプレイTTYドライバ
            └── utils/
                ├── z80ctrl.c            z80drv制御ユーティリティ
                ├── k64fcpu.c            K64F仮想CPUデーモン
                └── sharpbiter.c         キーボード/ディスプレイアービタデーモン

---

開発環境のセットアップ

ツールチェーン

• クロスコンパイラ： arm-linux-gnueabihf-gcc — sudo apt install gcc-arm-linux-gnueabihfでインストールします。これはCortex-A7 SOM用の標準ハードフロートARMクロスコンパイラです。
• カーネルヘッダ： SigmaStar SDKソースツリーから取得します。SDKはカーネルモジュールをビルドするために必要なフルカーネルソース（SigmaStarパッチ付きLinux 4.9-rt）を提供します。ディストロのカーネルヘッダは使用しないでください。SigmaStarパッチ済みカーネルは異なるABIを持っています。
• CPLDツールチェーン： Altera Quartus II 13.0.1 SP1 Web Edition（無料）。この特定のバージョンが必要です。後のバージョンはFusionXボードで使用されているMAX7000AEファミリのサポートを削除しました。intel.comのIntel/Alteaレガシーソフトウェアセクションからダウンロードしてください。
• ビルドツール： make、bc、libssl-dev、git — sudo apt install make bc libssl-dev gitでインストールします。

SDKのセットアップ

# SigmaStar SDKをクローン/取得（アクセスについてはメンテナに連絡するかプロジェクトリポジトリを確認）
export CROSS_COMPILE=arm-linux-gnueabihf-
export ARCH=arm
export KERNEL_DIR=/path/to/sigmastar-sdk/kernel


# SSD202 SOM用フルNANDフラッシュイメージをビルド（初回ビルド）
cd software/linux/
./Build_FusionX.sh -f nand -p ssd202 -o 2D06 -m 256

カーネルモジュールのビルド

# MZ-80AターゲットのためにZ80drvをビルド
cd software/FusionX/src/z80drv/src.mz80a
make KDIR=/path/to/sigmastar-sdk/kernel CROSS_COMPILE=arm-linux-gnueabihf-


# ビルドされたモジュールをSSH経由で実行中のFusionXボードにコピー
scp z80drv.ko root@192.168.1.100:/apps/FusionX/modules/


# FusionXボード上：古いモジュールをアンロードして新しいものをロード
rmmod z80drv
insmod /apps/FusionX/modules/z80drv.ko

---

継続的インテグレーション（Jenkins）

サーバー要件

• 最低2 GB RAM（4 GB推奨 — Quartusのコンパイルはメモリを多く消費します）
• 20 GBの空きディスク容量（Jenkinsデータ、Dockerイメージ、ビルドアーティファクト用）
• DockerとDocker Composeがインストール済みであること
• Gitea（またはGitHub）リポジトリへのネットワークアクセス
• ドメイン名または静的IPアドレス（Webhookコールバック用）

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

# Allow your user to run Docker commands without sudo
sudo usermod -aG docker $USER
# Log out and back in for the group change to take effect

サーバーへのARMクロスコンパイラのインストール

# Download and install Linaro GCC 5.5-2017.10
cd /tmp
wget https://releases.linaro.org/components/toolchain/binaries/5.5-2017.10/arm-linux-gnueabihf/gcc-linaro-5.5.0-2017.10-x86_64_arm-linux-gnueabihf.tar.xz
sudo mkdir -p /opt/arm-linux-gnueabihf
sudo tar xf gcc-linaro-5.5.0-2017.10-x86_64_arm-linux-gnueabihf.tar.xz \
    --strip-components=1 -C /opt/arm-linux-gnueabihf

# Verify
/opt/arm-linux-gnueabihf/bin/arm-linux-gnueabihf-gcc --version
# Expected: arm-linux-gnueabihf-gcc (Linaro GCC 5.5-2017.10) 5.5.0

Quartus II Dockerイメージのビルド

# Dockerfile.13.0.1 — Quartus II 13.0.1 SP1 for headless CPLD compilation
FROM ubuntu:xenial

ENV DEBIAN_FRONTEND=noninteractive

RUN dpkg --add-architecture i386 && \
    apt-get update && \
    apt-get install -y --no-install-recommends \
        wget ca-certificates lib32z1 lib32stdc++6 lib32gcc1 \
        libx11-6:i386 libxext6:i386 libxrender1:i386 \
        libxtst6:i386 libxi6:i386 libfreetype6:i386 \
        libfontconfig1:i386 libsm6:i386 libxft2:i386 \
        unzip xvfb libncurses5 libncurses5:i386 && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /tmp/quartus_install

# Download Quartus II 13.0.1 SP1 Web Edition installer + device support
RUN wget -q http://download.altera.com/akdlm/software/acdsinst/13.0sp1/232/ib_installers/QuartusSetupWeb-13.0.1.232.run && \
    wget -q http://download.altera.com/akdlm/software/acdsinst/13.0sp1/232/ib_installers/QuartusSetupWeb-13.0.1.232-linux.run && \
    wget -q http://download.altera.com/akdlm/software/acdsinst/13.0sp1/232/ib_installers/max_013001.qdz && \
    wget -q http://download.altera.com/akdlm/software/acdsinst/13.0sp1/232/ib_installers/cyclone_013001.qdz && \
    wget -q http://download.altera.com/akdlm/software/acdsinst/13.0sp1/232/ib_installers/arria_013001.qdz && \
    chmod +x *.run

# Install Quartus unattended
RUN ./QuartusSetupWeb-13.0.1.232.run --mode unattended \
        --installdir /opt/altera --accept_eula 1 && \
    rm -rf /tmp/quartus_install

ENV PATH="/opt/altera/quartus/bin:${PATH}"

WORKDIR /build
CMD ["/bin/bash"]

# Build the Quartus Docker image
docker build -f Dockerfile.13.0.1 -t quartus-ii-13.0.1 .

# Verify the image works
docker run --rm quartus-ii-13.0.1 quartus_sh --version
# Expected output: Version 13.0.1 Build 232

# Compile a single CPLD target from the host command line
cd /path/to/tzpuFusionX
docker run --rm --net=host \
    -v "$(pwd):$(pwd)" \
    -w "$(pwd)/CPLD/v1.0/MZ80A/build" \
    quartus-ii-13.0.1 \
    quartus_sh --flow compile tzpuFusionX_MZ80A

# Compile all four targets
for target in MZ80A MZ700 MZ2000 PCW8256; do
    docker run --rm --net=host \
        -v "$(pwd):$(pwd)" \
        -w "$(pwd)/CPLD/v1.0/${target}/build" \
        quartus-ii-13.0.1 \
        quartus_sh --flow compile "tzpuFusionX_${target}"
done

# Run Quartus GUI with X11 forwarding (requires X server on host)
docker run --rm --net=host \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v "$(pwd):$(pwd)" \
    -w "$(pwd)" \
    quartus-ii-13.0.1 \
    quartus

Jenkinsのインストール

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

# /srv/jenkins/Dockerfile
FROM jenkins/jenkins:lts

USER root

# Install Docker CLI (not the full daemon — Jenkins uses the host's Docker via the socket)
RUN curl -fsSL https://get.docker.com | sh && rm -rf /var/lib/apt/lists/*

# Match the Docker group GID on the host so Jenkins can access /var/run/docker.sock.
# Run "getent group docker" on the host to find the correct GID (commonly 994 or 999).
ARG DOCKER_GID=994
RUN groupadd -g ${DOCKER_GID} hostdocker || true && \
    usermod -aG ${DOCKER_GID} jenkins

USER jenkins

# /srv/jenkins/docker-compose.yml
version: '3.8'
services:
  jenkins:
    build: .
    ports:
      - "8080:8080"       # Jenkins web UI
      - "50000:50000"     # Jenkins agent communication port
    volumes:
      - /srv/jenkins/data:/var/jenkins_home                      # Persistent Jenkins data
      - /opt/arm-linux-gnueabihf:/opt/arm-linux-gnueabihf:ro   # ARM cross-compiler (read-only)
      - /var/run/docker.sock:/var/run/docker.sock                # Host Docker socket for sibling containers
    environment:
      - JAVA_OPTS=-Djenkins.install.runSetupWizard=false
    restart: unless-stopped

• /srv/jenkins/data → /var/jenkins_home — すべてのJenkins設定、ジョブ、ビルド履歴がここに保存されます。コンテナの再起動後も永続化されます。
• /opt/arm-linux-gnueabihf — 前のステップでインストールしたLinaro GCC 5.5クロスコンパイラ。PipelineがARMバイナリをコンパイルできるように読み取り専用でマウントされます。
• /var/run/docker.sock — ホストのDockerソケット。JenkinsがDocker-inside-Dockerではなく、シブリングDockerコンテナ（Quartus）を起動できるようにします。

# Start Jenkins
cd /srv/jenkins
docker-compose up -d

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

# Jenkins is now running at http://your-server:8080

Jenkinsの初期設定

• Generic Webhook Trigger — Gitea（またはGitHub）がコードのプッシュ時にシンプルなHTTP POSTでビルドをトリガーできるようにします。
• Pipeline — ビルドスクリプトをGroovyコードとして記述できるようにします（通常、推奨プラグインにプリインストールされています）。
• Email Extension — ビルドの成功/失敗のメール通知用です（オプションですが推奨）。

Pipelineジョブの作成

1. Jenkinsダッシュボードから新規ジョブ作成をクリックします。
2. 名前を入力し（例：FusionX-Build）、Pipelineを選択して、OKをクリックします。
3. Pipelineセクションまでスクロールします。定義を「Pipeline script」に設定し、以下に示すGroovy Pipelineスクリプトを貼り付けます。
4. 保存をクリックします。

Pipelineスクリプト

pipeline {
    agent any

    environment {
        GITEA_URL   = "https://git.eaw.app"          // Your Gitea server URL
        REPO_URL    = "https://git.eaw.app/eaw/tzpuFusionX.git"
        GITEA_TOKEN = credentials('gitea-api-token')  // Jenkins credential ID for Gitea API token
        GITEA_OWNER = "eaw"                           // Gitea username or organisation
        GITEA_REPO  = "tzpuFusionX"                   // Repository name
        PATH        = "/opt/arm-linux-gnueabihf/bin:${env.PATH}"
    }

    triggers {
        // Triggered by Gitea webhook — see "Gitea Webhook Setup" below
        GenericTrigger(
            genericVariables: [
                [key: 'ref', value: '$.ref']
            ],
            causeString: 'Triggered by Gitea push to $ref',
            token: 'fusionx-build-trigger',
            printContributedVariables: true,
            printPostContent: false,
            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('Determine Version') {
            steps {
                script {
                    // Read VERSION file, or auto-increment from last Gitea release tag
                    if (!fileExists('VERSION')) {
                        writeFile file: 'VERSION', text: '1.00'
                    }
                    def repoVersion = readFile('VERSION').trim()
                    def gitDiff = sh(script: 'git diff HEAD~1 -- VERSION 2>/dev/null || echo NO_PREV',
                                     returnStdout: true).trim()
                    if (gitDiff.contains('NO_PREV') || gitDiff == '') {
                        def lastTag = sh(script: """
                            curl -sf -H "Authorization: token \$GITEA_TOKEN" \
                                "\$GITEA_URL/api/v1/repos/\$GITEA_OWNER/\$GITEA_REPO/releases?limit=1" \
                            | grep -o '"tag_name":"[^"]*"' | head -1 | cut -d'"' -f4 || echo ''
                        """, returnStdout: true).trim()
                        if (lastTag && lastTag.startsWith('v')) {
                            def lastVer = lastTag.substring(1)
                            def parts = lastVer.tokenize('.')
                            def major = parts[0] as int
                            def minor = (parts.size() > 1 ? parts[1] : '0') as int
                            minor += 1
                            if (minor >= 100) { major += 1; minor = 0 }
                            env.VERSION = "${major}.${String.format('%02d', minor)}"
                        } else {
                            env.VERSION = repoVersion
                        }
                    } else {
                        env.VERSION = repoVersion
                    }
                    echo "Building version: ${env.VERSION}"
                }
            }
        }

        stage('Build Assembly ROMs') {
            steps {
                sh 'chmod +x build.sh && mkdir -p software/tmp software/roms'
                sh './build.sh --asm'
                sh 'mkdir -p release/roms && cp software/roms/*.rom software/roms/*.mzf release/roms/ 2>/dev/null || true'
            }
        }

        stage('Build TZFS ROMs') {
            steps {
                sh './build.sh --tzfs'
                sh 'mkdir -p release/tzfs && cp software/roms/tzfs_*.rom software/roms/testtz_*.mzf release/tzfs/ 2>/dev/null || true'
            }
        }

        stage('Build CP/M') {
            steps {
                sh './build.sh --cpm'
                sh 'mkdir -p release/cpm && cp software/roms/cpm223_*.bin release/cpm/ 2>/dev/null || true'
            }
        }

        stage('Build Drivers') {
            steps {
                sh './build.sh --drivers || true'
                sh 'mkdir -p release/drivers && cp software/FusionX/modules/*.ko software/FusionX/bin/* release/drivers/ 2>/dev/null || true'
            }
        }

        stage('Build SPI Tools') {
            steps {
                sh './build.sh --spi || true'
                sh 'mkdir -p release/drivers && cp software/FusionX/src/spitools/mspi_main release/drivers/ 2>/dev/null || true'
            }
        }

        stage('Build CPLD Bitstreams') {
            steps {
                script {
                    // Jenkins runs inside a container where /var/jenkins_home maps to /srv/jenkins/data
                    // on the host. Quartus runs as a SIBLING container, so volume mounts must use HOST paths.
                    def workspace = pwd()
                    def hostWorkspace = workspace.replace('/var/jenkins_home', '/srv/jenkins/data')
                    sh 'mkdir -p release/cpld'
                    sh """
                        for target in MZ80A MZ700 MZ2000 PCW8256; do
                            PROJECT="tzpuFusionX_\${target}"
                            BUILDDIR="CPLD/v1.0/\${target}/build"
                            if [ -f "${workspace}/\${BUILDDIR}/\${PROJECT}.qpf" ]; then
                                echo "==> Compiling CPLD: \${target}"
                                docker run --rm --net=host \\
                                    -v "${hostWorkspace}:${workspace}" \\
                                    -w "${workspace}/\${BUILDDIR}" \\
                                    quartus-ii-13.0.1 \\
                                    /opt/altera/quartus/bin/quartus_sh --flow compile "\${PROJECT}" \\
                                && cp "${workspace}/\${BUILDDIR}/output_files/\${PROJECT}.pof" release/cpld/ 2>/dev/null \\
                                || echo "  [FAIL] CPLD: \${target}"
                            fi
                        done
                    """
                }
            }
        }

        stage('Package Releases') {
            steps {
                script {
                    def ver = env.VERSION
                    sh """
                        cd release/roms && tar czf ../../FusionX-ROMs-v${ver}.tar.gz *    && cd ../..
                        cd release/tzfs && tar czf ../../FusionX-TZFS-v${ver}.tar.gz *    && cd ../..
                        cd release/cpm  && tar czf ../../FusionX-CPM-v${ver}.tar.gz *     && cd ../..
                        [ -n "\$(ls release/cpld/ 2>/dev/null)" ] && \
                            cd release/cpld && tar czf ../../FusionX-CPLD-v${ver}.tar.gz *    && cd ../..
                        [ -n "\$(ls release/drivers/ 2>/dev/null)" ] && \
                            cd release/drivers && tar czf ../../FusionX-Drivers-v${ver}.tar.gz * && cd ../..
                    """
                    archiveArtifacts artifacts: "FusionX-*-v${ver}.tar.gz"
                }
            }
        }

        stage('Create Gitea Release') {
            steps {
                script {
                    def ver = env.VERSION
                    def tag = "v${ver}"
                    def commitSha = sh(script: 'git rev-parse HEAD', returnStdout: true).trim()
                    def shortSha = commitSha.take(8)

                    // Delete any existing release with the same tag
                    sh """
                        OLD_ID=\$(curl -s -H "Authorization: token \$GITEA_TOKEN" \
                            "\$GITEA_URL/api/v1/repos/\$GITEA_OWNER/\$GITEA_REPO/releases/tags/${tag}" \
                            | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)
                        [ -n "\$OLD_ID" ] && curl -s -X DELETE -H "Authorization: token \$GITEA_TOKEN" \
                            "\$GITEA_URL/api/v1/repos/\$GITEA_OWNER/\$GITEA_REPO/releases/\$OLD_ID"
                    """

                    // Create release via Gitea API
                    def body = "Automated build from commit ${shortSha}\\n\\nIncludes:\\n" +
                        "- FusionX-ROMs-v${ver}.tar.gz\\n- FusionX-TZFS-v${ver}.tar.gz\\n" +
                        "- FusionX-CPM-v${ver}.tar.gz\\n- FusionX-CPLD-v${ver}.tar.gz\\n" +
                        "- FusionX-Drivers-v${ver}.tar.gz"
                    def releaseJson = """{"tag_name":"${tag}","name":"FusionX ${tag}","body":"${body}","target_commitish":"${commitSha}"}"""
                    writeFile file: 'release_body.json', text: releaseJson
                    sh 'curl -sf -X POST -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" -d @release_body.json "$GITEA_URL/api/v1/repos/$GITEA_OWNER/$GITEA_REPO/releases" > release_response.json'
                    def releaseId = sh(script: "grep -o '\"id\":[0-9]*' release_response.json | head -1 | cut -d: -f2", returnStdout: true).trim()

                    // Upload release tarballs
                    sh """
                        for asset in FusionX-ROMs-v${ver}.tar.gz FusionX-TZFS-v${ver}.tar.gz FusionX-CPM-v${ver}.tar.gz FusionX-CPLD-v${ver}.tar.gz FusionX-Drivers-v${ver}.tar.gz; do
                            [ -f "\${asset}" ] && curl -sf -H "Authorization: token \$GITEA_TOKEN" \
                                -F "attachment=@\${asset}" \
                                "\$GITEA_URL/api/v1/repos/\$GITEA_OWNER/\$GITEA_REPO/releases/${releaseId}/assets"
                        done
                    """
                }
            }
        }
    }

    post {
        success {
            mail to: 'your-email@example.com',
                 subject: "FusionX Build v${env.VERSION} - SUCCESS",
                 body: "FusionX build v${env.VERSION} completed.\nJob: ${env.JOB_NAME} #${env.BUILD_NUMBER}\nURL: ${env.BUILD_URL}"
        }
        failure {
            mail to: 'your-email@example.com',
                 subject: "FusionX Build - FAILED",
                 body: "FusionX build failed.\nJob: ${env.JOB_NAME} #${env.BUILD_NUMBER}\nURL: ${env.BUILD_URL}"
        }
        always { cleanWs() }
    }
}

Gitea Webhookの設定

1. Giteaで、リポジトリ → 設定 → Webhooks → Webhookを追加 → Giteaに移動します。
2. ターゲットURLを以下に設定します：
   http://your-server:8080/generic-webhook-trigger/invoke?token=fusionx-build-trigger
tokenの値はPipelineのGenericTriggerブロック内のtoken:フィールドと一致する必要があります。
3. HTTPメソッドをPOSTに、Content Typeをapplication/jsonに設定します。
4. トリガーで「Push Events」を選択します。
5. Webhookを追加をクリックします。Giteaは即座にテストpingを送信します。Jenkinsで受信されたことを確認してください。

シブリングコンテナの仕組み

// Inside the Jenkins pipeline:
def workspace = pwd()
// workspace = "/var/jenkins_home/workspace/FusionX-Build"

def hostWorkspace = workspace.replace('/var/jenkins_home', '/srv/jenkins/data')
// hostWorkspace = "/srv/jenkins/data/workspace/FusionX-Build"

// The Quartus container mounts the HOST path, but uses the Jenkins path as the mount point
// so that all paths in the Quartus project files resolve correctly.
docker run --rm --net=host \
    -v "${hostWorkspace}:${workspace}" \
    -w "${workspace}/CPLD/v1.0/MZ80A/build" \
    quartus-ii-13.0.1 \
    quartus_sh --flow compile tzpuFusionX_MZ80A

最初のビルドの検証

1. masterブランチにコミットをプッシュします。GiteaがJenkinsにWebhookを送信します。
2. JenkinsでFusionX-Buildジョブをクリックします。青い進行バーが表示された新しいビルドが確認できるはずです。
3. ビルド番号をクリックし、次にコンソール出力をクリックして、ビルドをリアルタイムで監視します。
4. ビルドが成功すると、すべてのステージが緑色で表示され、「SUCCESS」ステータスが表示されます。ビルドは通常3〜5分かかります。
5. Giteaリポジトリのリリースページを確認してください。ダウンロード可能なtarballを含む新しいリリースが表示されるはずです。

• "arm-linux-gnueabihf-gcc: not found" — クロスコンパイラがコンテナにマウントされていません。docker-compose.ymlの/opt/arm-linux-gnueabihfのボリュームマウントを確認してください。
• "docker: command not found" — Docker CLIがJenkinsイメージにインストールされていません。上記のDockerfileを使用してJenkins Dockerイメージをリビルドしてください。
• "permission denied" on docker.sock — Jenkins DockerfileのDOCKER_GIDがホストのDockerグループGIDと一致していません。ホストでgetent group dockerを実行し、Dockerfileを更新してください。
• Quartusライセンスエラー — Quartusコンテナが--net=hostで起動されていて、ライセンスサーバーに到達できることを確認してください。
• "fixdep: error opening config file" — 依存関係がファイル名にスペースを使用しています。Zetaライブラリはこの問題を回避するためにリポジトリにベンダリングされています。git submodule update --init --recursiveでサブモジュールが初期化されていることを確認してください。

---

主要データ構造

メモリマップ

// z80driver.h — MZ-80Aメモリマップの例
#define MZ80A_MONITOR_ROM_ADDR    0x0000
#define MZ80A_MONITOR_ROM_SIZE    0x1000  // 4KBシステムモニタ
#define MZ80A_VRAM_ADDR           0xD000  // ビデオRAM開始
#define MZ80A_VRAM_SIZE           0x0800  // 2KB VRAM
#define MZ80A_IO_KEYBOARD         0xE000  // キーボードI/Oポート

typedef struct {
    uint32_t  baseAddr;       // Z80アドレス空間の開始
    uint32_t  size;           // 領域サイズ（バイト）
    uint8_t  *data;           // エミュレーテッドメモリバッファへのポインタ
    uint8_t   type;           // MEM_ROM, MEM_RAM, MEM_VHARDWARE, MEM_PHYSICAL
    void     (*read_fn)(uint16_t addr, uint8_t *data);   // 仮想ハードウェア読み取りハンドラ
    void     (*write_fn)(uint16_t addr, uint8_t data);   // 仮想ハードウェア書き込みハンドラ
} t_memRegion;

バスサイクルリクエスト

// CPLD GPIOピンからキャプチャされたバスサイクル情報
typedef struct {
    uint16_t  address;        // Z80アドレスバスA0-A15
    uint8_t   data;           // Z80データバスD0-D7
    uint8_t   busType;        // BUS_MREQ_RD, BUS_MREQ_WR, BUS_IORQ_RD, BUS_IORQ_WR, BUS_M1
    bool      isRead;         // true = 読み取りサイクル、false = 書き込みサイクル
} t_busCycle;

仮想ハードウェアモジュールインターフェース

// 各z80vhw_*.cはこれらの関数を実装します：

// モジュールロード時に一度呼び出される — メモリ/IO領域とハンドラを登録
int vhw_init(void);

// メモリ読み取りハンドラ — メモリマップ領域のためにディスパッチループから呼び出される
uint8_t vhw_mem_read(uint16_t addr);

// メモリ書き込みハンドラ
void vhw_mem_write(uint16_t addr, uint8_t data);

// I/O読み取りハンドラ（6502ベースのマシンには使用されないが、Z80では常に存在する）
uint8_t vhw_io_read(uint16_t port);

// I/O書き込みハンドラ
void vhw_io_write(uint16_t port, uint8_t data);

// Z80リセット時に呼び出される — ハードウェア状態を再初期化
void vhw_reset(void);

// ディスパッチループから定期的に呼び出される — タイマー、サウンドエミュレーションなどのため
void vhw_tick(uint64_t cycles);

---

z80driver.c — ディスパッチループ

// 簡略化されたディスパッチループ (z80driver.c)
static int z80_emulation_thread(void *data)
{
    while (!kthread_should_stop()) {
        // 1. CPLDが保留中のバスサイクルを通知するのを待つ（GPIO IRQまたはポール）
        t_busCycle cycle = cpld_read_bus_cycle();    // GPIOピンを読み取る

        // 2. サイクルタイプとアドレスに基づいてディスパッチ
        if (cycle.busType == BUS_M1) {
            // オペコードフェッチ — Zetaライブラリで1つのZ80命令を実行
            zeta_run_one_instruction(&z80_state);

        } else if (cycle.busType == BUS_MREQ_RD) {
            // メモリ読み取り
            uint8_t data = dispatch_mem_read(cycle.address);
            cpld_write_data(data);                   // CPLDへのSPI書き込み

        } else if (cycle.busType == BUS_MREQ_WR) {
            // メモリ書き込み
            dispatch_mem_write(cycle.address, cycle.data);

        } else if (cycle.busType == BUS_IORQ_RD) {
            // I/O読み取り
            uint8_t data = dispatch_io_read(cycle.address & 0xFF);
            cpld_write_data(data);

        } else if (cycle.busType == BUS_IORQ_WR) {
            // I/O書き込み
            dispatch_io_write(cycle.address & 0xFF, cycle.data);
        }

        // 3. 定期的なハウスキーピング
        if ((cycle_count++ & 0x7FF) == 0)
            vhw_tick(cycle_count);
    }
    return 0;
}

---

新しいマシンの追加

ステップ1 — z80driver.hでメモリマップを定義する

#ifdef TARGET_SPECTRUM48K
  #define TARGET_NAME           "Spectrum48K"
  #define SPECTRUM_ROM_ADDR     0x0000
  #define SPECTRUM_ROM_SIZE     0x4000   // 16KB Spectrum ROM
  #define SPECTRUM_RAM_ADDR     0x4000
  #define SPECTRUM_RAM_SIZE     0xC000   // 48KB RAM
  #define SPECTRUM_ULA_PORT     0xFE    // ULA I/Oポート（キーボード、ボーダー、スピーカー、テープ）
#endif

ステップ2 — 仮想ハードウェアモジュールを作成する

// software/FusionX/src/z80drv/src/z80vhw_spectrum48k.c
#include "z80driver.h"

// ROMデータ — 初期化時にSDカードからロードされるかコンパイルイン
static uint8_t spectrum_rom[0x4000];
static uint8_t spectrum_ram[0xC000];

// ULA状態
static uint8_t ula_border = 7;    // 初期化時に白いボーダー
static uint8_t ula_ear = 0;
static uint8_t ula_mic = 0;

// キーボードマトリクス（8行×5列）
static uint8_t key_matrix[8] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};

uint8_t vhw_mem_read(uint16_t addr) {
    if (addr < SPECTRUM_ROM_SIZE)
        return spectrum_rom[addr];
    if (addr >= SPECTRUM_RAM_ADDR)
        return spectrum_ram[addr - SPECTRUM_RAM_ADDR];
    return 0xFF;
}

void vhw_mem_write(uint16_t addr, uint8_t data) {
    if (addr >= SPECTRUM_RAM_ADDR)
        spectrum_ram[addr - SPECTRUM_RAM_ADDR] = data;
    // ROM書き込みは無視される
}

// ... (詳細な実装は省略)

ステップ3 — ビルドバリアントディレクトリを作成する

mkdir software/FusionX/src/z80drv/src.spectrum48k
cd software/FusionX/src/z80drv/src.spectrum48k


# このバリアントに必要な共通ソースファイルへのシンボリックリンクを追加
ln -s ../src/z80driver.c .
ln -s ../src/z80io.c .
ln -s ../src/emumz.c .
ln -s ../src/z80vhw_spectrum48k.c .

ccflags-y += -DTARGET_SPECTRUM48K
obj-m := z80drv.o
z80drv-objs := z80driver.o z80io.o emumz.o z80vhw_spectrum48k.o

ステップ4 — CPLD VHDLバリアントを作成する

• 開始点としてCPLD/v1.0/MZ80A/をCPLD/v1.0/Spectrum48K/にコピーします。
• tzpuFusionX_Toplevel.vhdを編集：新しいマシンの物理的なソケットピンアウトに合わせてLOCATION制約のI/Oピンアサインを調整します。各マシンは異なるコネクタを使用してZ80バス信号を異なるCPLDピンにマッピングします。
• tzpuFusionX.vhdを編集：マシン固有のFSM状態を追加します。Spectrum 48Kの場合、ULAのコンテンドメモリウェイトステート挿入（ULAは各水平スキャンラインの上半分の間4MHzでZ80からサイクルを奪います）を追加し、SpectumのZ80クロック3.5MHzに合わせてバスホールドタイミングを調整します。
• tzpuFusionX_pkg.vhdを編集：Spectrum 48K用の新しいMACHINE_TYPE定数と新しいタイミングパラメータを追加します。
• Quartus II 13.0.1 SP1で新しいプロジェクトを開き、解析と合成、フィッタ、アセンブラを実行して.pofビットストリームファイルを生成します。
• USB Blaster（または互換品）プログラマとQuartus IIプログラマツールを使用してJTAG経由で新しいビットストリームをCPLDにプログラムします。

ステップ5 — 起動スクリプトを作成する

#!/bin/sh

# startZ80_Spectrum48K.sh
insmod /apps/FusionX/modules/ttymzdrv.ko
/apps/FusionX/bin/sharpbiter &
taskset -c 1 insmod /apps/FusionX/modules/z80drv.ko
/apps/FusionX/bin/z80ctrl --adddev --device spectrum48k
/apps/FusionX/bin/z80ctrl --loadrom /sd/ROM/spectrum48k.rom --addr 0x0000 --size 0x4000
/apps/FusionX/bin/z80ctrl --start

---

仮想ハードウェアデバイスの追加

// z80vhw_mz80a.cで — I/Oポート0xB0-0xB7に仮想RTCを追加

typedef struct {
    uint8_t seconds, minutes, hours, day, month, year;
} t_virtualRTC;

static t_virtualRTC rtc = {0};

static uint8_t rtc_read(uint16_t port) {
    switch (port & 0x07) {
        case 0: return rtc.seconds;
        case 1: return rtc.minutes;
        case 2: return rtc.hours;
        case 3: return rtc.day;
        case 4: return rtc.month;
        case 5: return rtc.year;
        default: return 0xFF;
    }
}

// vhw_init()で：
register_io_handler(0xB0, 0x08, rtc_read, rtc_write);

---

CPLDの変更

tzpuFusionX.vhdの主要箇所

• Z80バスFSM： マルチフェーズZ80バスサイクル（M1、MREQ、IORQ、RD、WR、RFSH、HALT、BUSRQ、BUSAK）を処理します。DMAバスリクエスト/グラントなどの新しいサイクルタイプを追加するには、このFSMに新しい状態を追加して適切なVHDL信号をアサートします。Z80 CPU技術マニュアルで指定されているすべてのZ80バスタイミング要件を満たすよう注意してください。セットアップとホールドタイムの違反はデバッグが非常に困難なデータ破損を引き起こします。
• SOMインターフェース： SPIスレーブとGPIO信号アサイン。新しいSPIコマンドはSPIデコーダプロセスを拡張することで追加できます。SOMへのGPIO信号は物理的なピン数によって制限されます。ピンを再アサインする場合はSOM Linux GPIOドライバの対応する変更が必要です。
• ビデオタイミング： コンポジットビデオ出力のためのSync pulse生成。ビデオタイミングの変更はマシン固有です。MZ-80A、MZ-700、MZ-2000はキャラクタセルサイズとSync極性が異なります。タイミングの変更には水平および垂直周波数を維持するための慎重なカウンタ演算が必要です。
• マシン固有のFSM状態： Spectrum ULAは各水平スキャンラインの上半分の間にアドレス0x4000〜0x7FFFのメモリサイクルをコンテンドします。これを実装するには、CPLDが正しいピクセルクロックフェーズでZ80バス上のWAITをアサートする必要があります。バンク切り替え制御信号（ページドROMまたはRAMを持つマシン用）もここで管理されます。

新しいSPIコマンドの追加

-- tzpuFusionX_pkg.vhdで — 新しいコマンド定数を追加
constant CMD_SET_BORDER : std_logic_vector(7 downto 0) := x"42";

-- tzpuFusionX.vhd SPIデコーダプロセスで
when CMD_SET_BORDER =>
    border_colour <= spi_data_in(2 downto 0);

Quartus SignalTap IIによるデバッグ

1. ターゲットマシン用のQuartus IIプロジェクトを開き、ツールメニューからSignalTap IIロジックアナライザを起動します。
2. 観察したいVHDL内部信号（FSM状態レジスタ、SPIバイトカウンタ、バス制御ライン）をプローブ信号として追加します。
3. トリガー条件を設定します（例：SPIコマンドバイトが0x42に等しい場合にトリガー）、サンプル深度とクロックソースを設定します。
4. プロジェクトを再コンパイル（解析と合成 + フィッタ + アセンブラ）してSignalTap IIロジックをビットストリームに埋め込みます。SignalTap IIはCPLDロジックリソースを消費します。設計がすでに100%の使用率に近い場合、スペースを確保するために一時的に他のロジックを削除する必要があるかもしれません。
5. JTAG経由で新しいビットストリームをCPLDにプログラムし、SignalTap II内からインシステムキャプチャを開始します。FusionXソフトウェアを実行して条件をトリガーし、キャプチャされた波形を検査します。

---

ユーザーユーティリティのクロスコンパイル

# z80ctrlをクイックテスト用にクロスコンパイル
arm-linux-gnueabihf-gcc -o z80ctrl z80ctrl.c -lpthread


# SSH経由で実行中のFusionXボードにコピー
scp z80ctrl root@192.168.1.100:/apps/FusionX/bin/


# あるいは、フルBuildrootパイプライン経由ですべてのユーティリティをビルド（リリースには推奨）
cd software/linux/
./Build_FusionX.sh -f nand -p ssd202 -o 2D06 -m 256

---

OTAファームウェアアップデート

アップデートイメージのビルド

cd software/linux/
./Build_FusionX.sh -f nand -p ssd202 -o 2D06 -m 256


# 出力イメージの場所: project/image/output/images/

# 主要ファイル:

#   uboot.img          U-bootブートローダーイメージ

#   kernel.img         Linuxカーネル + デバイスツリー

#   rootfs.ubifs       ルートファイルシステム（UBIFS）

#   FusionX_apps.tar   アプリケーションファイル（カーネルモジュール、ユーティリティ、ROMイメージ）

SDカードの準備

# SDカードを準備（SDカードが/media/sdcardにマウントされていると仮定）
mkdir -p /media/sdcard/FusionX/upgrade/


# パーティションイメージをSDカードにコピー
cp project/image/output/images/uboot.img       /media/sdcard/FusionX/upgrade/
cp project/image/output/images/kernel.img      /media/sdcard/FusionX/upgrade/
cp project/image/output/images/rootfs.ubifs    /media/sdcard/FusionX/upgrade/
cp project/image/output/images/FusionX_apps.tar /media/sdcard/FusionX/upgrade/


# アップグレードをトリガーするセンチネルファイルを作成
touch /media/sdcard/FusionX/upgrade/DO_UPGRADE


# 電源投入前に安全に取り出してFusionXに挿入
sync
umount /media/sdcard

アップグレードプロセス

1. 電源投入前に準備済みSDカードをFusionX SDスロットに挿入します。
2. FusionXの電源を入れます。U-boot（またはLinuxinitスクリプト）がSDカードを検出してDO_UPGRADEセンチネルファイルを見つけます。
3. アップグレードスクリプトは関連するNANDパーティションを消去して新しいイメージを書き込みます。これはrootfsのサイズに応じて約2〜5分かかります。このステップ中は電源を切らないでください。
4. アップグレードスクリプトはDO_UPGRADEセンチネルファイルを削除（または名前変更）してシステムを再起動します。
5. 再起動後のLEDパターンがアップグレード成功を示した後にSDカードを取り出します。ボードは新しくプログラムされたNANDからブートするようになります。

---

よくある落とし穴

• z80drvでCPU0でブロック： CPU1のz80drvディスパッチループで実行されているコードからの任意のLinuxシステムコール（ファイルI/O、GFP_KERNELでのkmalloc、スリープ）はスケジューラのプリエンプションまたはデッドロックのリスクがあります。ホットパスではカーネルセーフでノンブロッキングのAPIのみを使用してください。ブロックする可能性がある操作はCPU0の別のカーネルスレッドに延期し、ロックフリーリングバッファまたはアトミックフラグを介して通信しなければなりません。
• CPLDビットストリームバリアントの不一致： MZ-80AピンアサインでCPLDをコンパイルしてMZ-700に接続されたハードウェアにプログラムすると、不正なバスタイミングとアドレスデコードが発生します。マシンは起動しているように見えますが、Z80バスから誤ったデータを読み取ります。プログラムする前に必ずQuartus IIプロジェクトの設定（デバイス、ピンアサイン、パッケージファイル内のマシン固有のジェネリクス）が物理的なハードウェアと一致していることを確認してください。
• CPU分離が有効でない： カーネルブート引数にisolcpus=1が存在しない場合、LinuxスケジューラはZ80バスサイクル中にz80drvディスパッチスレッドをプリエンプトし、ホスト機が停止またはクラッシュを引き起こします。cat /proc/cmdlineで分離が有効であることを確認し、CPU1がリストされているかどうかを確認してください。
• SPIクロックスキュー： SOM SPIバスは50MHzで動作しており、SPIライン下の適切なグランドプレーンとともに一致したトレース長を持つ慎重なPCBレイアウトが必要です。
• ROMイメージの欠落： z80ctrl --loadromはSDカードにROMファイルが見つからなくても成功を報告する場合があります。Z80を起動する前に必ずdmesg | grep z80drvでカーネルモジュールが成功したROMロードを報告していることを確認してください。
• vhw_tick周波数： vhw_tick()は約2048マイクロ秒ごとではなく、約2048 Z80サイクルごとに呼び出されます。4MHzではこれは約0.5msのティックに相当します。正確なタイマーエミュレーションのために、ティック呼び出し回数ではなくcycles引数を介して渡された実際の経過サイクルデルタをカウントしてください。
• GPIO読み取りレイテンシ： Z80アドレスバスとサイクルタイプをキャプチャするために使用されるGPIO読み取りパスはSigmaStar SOMで読み取りごとに約200nsのオーバーヘッドがあります。これは4MHz Z80動作には十分高速ですが、より高いクロック速度で動作するマシンにはギリギリかもしれません。

---

参考サイト

リソース	リンク
tranZPUter FusionX プロジェクトページ	/tranzputer-fusionx/
tranZPUter FusionX ユーザーマニュアル	/tranzputer-fusionx-usermanual/
tranZPUter FusionX テクニカルガイド	/tranzputer-fusionx-technicalguide/
SigmaStar SSD202 製品ページ	sigmastar.com.tw
Altera MAX7000AE デバイスファミリデータシート	intel.com
Zeta Z80 エミュレータライブラリ	github.com/redcode/Zeta
Quartus II 13.0.1 SP1 Web Edition	intel.com レガシーソフトウェア
Linux PREEMPT_RT パッチ	wiki.linuxfoundation.org/realtime
Buildroot プロジェクト	buildroot.org
FusionX デベロッパーズガイド	/tranzputer-fusionx-developersguide/
arm-linux-gnueabihf ツールチェーン	packages.ubuntu.com/gcc-arm-linux-gnueabihf

---

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