Home Design Shortcuts Setup Aura TechNote API (rustdoc) Graphs TODO Log

AtmOS 開発環境・実機セットアップ

最終更新: 2026-07-24
統合元: UTM_SETUP_GUIDE.md / WALKTHROUGH_RPI3B_FIRST_BOOT_UART.md / TEMPLATE_RPI3B_FIRST_BOOT_RESULT.md

1. 開発環境の概要

項目	内容
開発 OS	macOS
ターゲット	`aarch64-unknown-none`（`no_std`）
ビルドツール	Rust（`cargo`）+ `cargo-binutils`（`llvm-tools` の `cargo-objcopy` で ELF→バイナリ変換）
エミュレータ	QEMU（`qemu-system-aarch64`、`raspi3b`）/ UTM
実機	Raspberry Pi 3B+
SD 書き込み	balenaEtcher / `dd`

2. ビルドと QEMU 起動

cd /Users/sugimura/Documents/AtmOS/arm/v1

# 初回のみ: ツールチェーン整備（rustup・aarch64-unknown-none ターゲット・
#           cargo-binutils・QEMU を Homebrew 経由で導入）
make ready

# ビルド: cargo build --release + cargo-objcopy → kernel8.img
make all

# ユニットテスト実行（完全隔離構成のホスト環境テスト、`arm/v1/tests/` 配下の150件超全PASS）
make test

# QEMU 起動（既定: マルチコア + GUI + USB 入力 + vmnet-shared ネットワーク）
make run

QEMU 終了: Ctrl+A → X

注意: Makefile は .DEFAULT_GOAL を意図的に外しているため、引数なしの make は最初のルール（空の sdcard.img 生成）だけを実行し、kernel8.img はビルドされない。カーネルのビルドは必ず make all を使うこと（make run は依存として kernel8.img を作る）。

ユニットテストは src/ 本体コードから完全に分離された arm/v1/tests/ ディレクトリ内で実行され、 make test を用いてホスト環境 (std) で高速に一括検証される。

lint/ビルドを CI と同じ条件で通すには cargo clippy --release（unwrap_used / expect_used / crate 全体 string_slice が deny レベル）+ cargo build --release。

起動バリアント

ターゲット	用途	sudo
`make run`	既定。GUI + vmnet-shared（NAT 経由でネット可）	必要
`make run-full`	フルスクリーン + ストレッチ	必要
`make run-no-ether`	ネットワーク無効・GUI のみ（手軽に試す）	不要
`make run-no-smp`	シングルコア起動	必要
`make run-no-gui`	ヘッドレス（シリアルのみ）	必要
`make run-debug`	ヘッドレス + 例外/ゲストエラーを `qemu_debug.log` へ	必要
`make run-vnc`	VNC 表示（`127.0.0.1:5900`）	必要
`make run-vmnet-bridged`	有線 LAN (en0) ブリッジ	必要

vmnet 系（run / run-full 等）は macOS の vmnet フレームワーク利用のため sudo が必須。ネットワーク不要で素早く確認したいときは make run-no-ether（sudo 不要）が便利。

自動回帰テスト（シリアルコンソール経由）

シリアル (UART) 入力はキーボードと同一の入力パイプラインへ流れる（main.rs の UART_FIFO ドレイン → keyboard::ascii_to_scancode → process_key_event）ため、 -serial stdio 経由で OS 全体を無人操作できる。expect test_browser.sh（arm/v1/）はこれを使い、起動時の各自己テスト（JS_SELFTEST / CSS_SELFTEST / LAYOUT_SELFTEST / USBSCHED_SELFTEST など）の PASS → ログイン → ブラウザ起動 → HTTPS ロード成功までを無人検証する。CI（.github/workflows/ci.yml）の QEMU スモークテストも同スクリプトを実行する。

GUI を GUI 操作として（QMP 経由で）検証する代替手順は TECHNOTE.md §9 を参照（HMP sendkey + QMP input-send-event 絶対座標 + screendump）。

3. SD カードイメージ作成（実機用）

# 1. カーネルのビルド（必ず make all）
cd /Users/sugimura/Documents/AtmOS/arm/v1
make all

# 2. SD イメージ生成
cd forRaspPi3B+
make
# → sylfs_rpi3b+.img が生成される（ブートファイル一式 + 上でビルドした kernel8.img を格納）

# 3. balenaEtcher で SD カードに書き込む
# または:
sudo dd if=sylfs_rpi3b+.img of=/dev/rdiskN bs=4m

forRaspPi3B+/Makefile の all は内部で $(MAKE) -C ..（＝引数なしの make）を呼ぶため、 カーネルは再ビルドされない。手順 1 の make all を先に済ませて最新の kernel8.img を用意しておかないと、古いカーネルが SD イメージに取り込まれる。

4. RPi3B+ UART ログ取得手順

目的

実機で kmain() が到達できているか確認し、フレームバッファ初期化・MMU・割り込みの動作を判定する。1 本の UART ログで不具合箇所を絞り込む。

必要機材

Raspberry Pi 3B+
microSD カード（8GB 以上推奨）
USB-UART 変換アダプタ（3.3V TTL 対応）
ジャンパ線 3 本（GND, TX, RX）
ホスト PC（macOS）

配線

Pi ピン	USB-UART
GND（任意の GND ピン）	GND
GPIO14（TXD）	RX
GPIO15（RXD）	TX

注意: 5V は絶対に接続しない。必ず 3.3V TTL 対応のアダプタを使用すること。

UART ログ取得（macOS）

# デバイス名を確認
ls /dev/cu.usb*

# 接続（115200 8N1）
screen /dev/cu.usbserial-XXXX 115200

# 終了: Ctrl+A → K → Y

期待されるログ（正常起動）

起動サマリーは番号付きチェックリスト形式（{:.<50} [OK]）で出力される。正常起動なら以下の順に [OK] が並ぶ（... の内容は実機のアドレス・解像度・ビルド情報などで変わる）:

==================================================
   AtmOS v3 (ARM64 / OS Base) starting...
   Version: 0.1.0 (Git: ...)
   Build Time: ...
   Author: SUGIMURA Hiroshi (Sugimura Laboratory)
==================================================
1. Graphics System (FrameBuffer).................. [OK]
2. Memory System (MMU & Heap)..................... [OK]
3. Core Software Self-Tests (JS_SELFTEST: PASS, BIGINT_SELFTEST: PASS, AURA_SELFTEST: PASS, CSS_SELFTEST: PASS, LAYOUT_SELFTEST: PASS, IME_SELFTEST: PASS, CLOUD_SELFTEST: PASS, H264_SELFTEST: PASS, H264_GOLDEN: PASS, RECLOCK_SELFTEST: PASS, FS_SELFTEST: PASS, USBSCHED_SELFTEST: PASS) [OK]
4. File System (SylFS)............................ [OK]
5. Audio Systems.................................. [OK]
6. USB Host Controller & HID Stack................ [OK]
7. System Scheduler & Interrupts.................. [OK]

実機で microSD が読めない場合は [WARN ] [FS] Failed to initialize microSD card ... Falling back to RAMDisk が出て RAMDisk で継続する（SylFS 自体は [OK]）。フレームバッファは 1024×600 を最優先に複数解像度へフォールバック探索する（main.rs の resolutions 配列）。

チェックリスト

5. RPi3B+ ファーストブート結果記録テンプレート

実機試験を実施した際は、以下のテンプレートをコピーして結果を記録する（WALKTHROUGH_COMPLETION_LOG.md に追記）。

## RPi3B+ ファーストブート試験記録

- 実施日時:
- 全員:
- Pi シリアル番号（任意・管理用）:
- 使用 SD イメージ:
- 使用ブランチ:
- 最新コミット:

### 接続確認

- USB-UART アダプタ型番:
- シリアルデバイス名（macOS）:
- ボーレート:
- 配線確認:
  - [x] GND 接続
  - [x] Pi TX(GPIO14) → USB-UART RX
  - [x] Pi RX(GPIO15) → USB-UART TX

### 実行コマンド

\`\`\`bash
# cd /Users/sugimura/Documents/AtmOS/arm/v1
# make all
# cd forRaspPi3B+
# make
# screen /dev/cu.usbserial-XXXX 115200
\`\`\`

### ログの先頭（必要な部分を貼り付け）

\`\`\`text
# ここに UART ログを貼り付け
\`\`\`

### チェック結果

- [ ] バナー `AtmOS v3 (ARM64 / OS Base) starting...` 出力
- [ ] `1. Graphics System (FrameBuffer) ... [OK]`
- [ ] `2. Memory System (MMU & Heap) ... [OK]`
- [ ] `3. Core Software Self-Tests (... 全 PASS) [OK]`
- [ ] `4. File System (SylFS) ... [OK]`
- [ ] `6. USB Host Controller & HID Stack ... [OK]`（USB デバイス列挙）
- [ ] `7. System Scheduler & Interrupts ... [OK]`
- [ ] GUI 表示確認

### 結果

- 判定: PASS / FAIL
- FAIL の場合の停止位置:
- 再現性:
  - [ ] 毎回再現
  - [ ] まれに再現
  - [ ] 一度きり
- 備考:
- 次アクション:

6. UTM を使った QEMU 起動（Wi-Fi ブリッジ対応）

CLI QEMU では Wi-Fi ブリッジが機能しない（詳細は TECHNOTE.md §5 参照）。
Wi-Fi ブリッジが必要な場合は UTM を使用する。

UTM セットアップ手順

ステップ 1: 空の仮想マシンを作成

UTM を起動 → 「新しい仮想マシンを作成」
「エミュレート」を選択
OS 選択は「その他」など適当に選択してウィザードを進める（スキップ）
適当な名前（例: AtmOS）を入力して「保存」

ステップ 2: 設定をカスタマイズ

仮想マシンを右クリック→「設定」を開く。

システム: アーキテクチャ=ARM64 (aarch64), システム=Raspberry Pi 3B (raspi3b)
ドライブ: 自動追加された空のドライブを全削除。「新規ドライブ」→ Interface=Kernel, ファイル=kernel8.img を追加
オーディオ: 「オーディオを有効化」をオフ
ディスプレイ: エミュレートカードを Default, SPICE ツールをオフ
共有: 共有ディレクトリをオフ

ステップ 3: ネットワーク設定

ネットワークモード: ブリッジ接続
ブリッジインターフェース: en0（Wi-Fi）
エミュレートするカード: usb-net

ステップ 4: QEMU 引数の追加

設定画面の「QEMU」タブ → 「QEMU 引数を直接編集」をオン → 以下を追加:

-device usb-hub,port-power=on,bus=usb-bus.0,port=1
-device usb-kbd,bus=usb-bus.0,port=1.1
-device usb-tablet,bus=usb-bus.0,port=1.2
-device usb-net,netdev=net0,bus=usb-bus.0,port=1.3

ステップ 5: 起動

UTM から AtmOS を起動。初回は「ネットワークブリッジの有効化」ポップアップが出るので許可・パスワード入力。成功すれば 192.168.x.x セグメントの IP が DHCP で取得される。

トラブルシューティング

「SPICE サーバへの接続試行中に内部エラーが発生しました」→ PCI デバイスが残っている。上記チェックリストで不要なデバイスをすべて無効化する。ログ確認方法: 設定の「QEMU」タブ→「デバッグログを有効化」→ 起動後「ログを書き出し」→ No 'PCI' bus found のようなエラーを探す。

7. WiFi ファームウェアの配置

RPi3B+ の WiFi（CYW43455）を使用するには、SD カードに Cypress のファームウェアを配置する必要がある。

# Raspberry Pi OS からファームウェアを入手
# 通常 /lib/firmware/brcm/ にある

# SylFS の /boot/ に配置（create_rpi_image.sh でコピー）
cp /lib/firmware/brcm/brcmfmac43455-sdio.bin <SylFS_boot_dir>/

ファームウェアが SylFS の /boot/brcmfmac43455-sdio.bin に存在すると、起動時に自動的にロードされる。