# terminal 模組:embedded(嵌入式 Linux 開發)

給「嵌入式 Linux 開發實戰」課程的 terminal 單元使用。全部是純 JS 的練習用模擬,**不會執行真實程式**。
實作檔:`resources/js/terminal-embedded.js`;測試:`node tools/test-terminal-embedded.mjs`。

啟用方式(課程 config):

```php
'config' => [
    'modules' => ['embedded'],
    'world'   => ['embedded' => [ /* 見「world 設定」 */ ]],
    ...
]
```

模擬環境的角色:終端機同時是「開發主機」(host,x86-64 Ubuntu)與「目標板」(核心模組、GPIO、I2C、磁碟指令作用在目標板)。
核心的 `uname` 沒有被覆寫,所以不要出 `uname -r` 的任務;核心版本請用 `world.kernel.release` 設定,模組與 `make` 會使用它。

---

## 1. 支援的指令

### 交叉編譯與二進位檢視

| 指令 | 支援 | 備註 |
|---|---|---|
| `gcc` / `cc`(host x86-64)、`arm-linux-gnueabihf-gcc`、`aarch64-linux-gnu-gcc` | `-o`、`-c`、`-static`、`-shared`、`-g`、`-s`、`-pie`/`-no-pie`、`-I`、`-L`、`-l`、`-D`、`-O*`、`-W*`、`-f*`、`-std=`、`--version`、`-dumpmachine` | 輸入 `.c` 與 `.o`;`-S`/`-E`/`.cpp`/`.S` 回報不支援 |
| `file [-b]` | 偽 ELF(依架構/動態/靜態/stripped/debug_info 輸出真實格式)、dtb、映像檔、`.ko`、kernel 映像(依檔名 `zImage`/`Image`/`uImage`/`bzImage`)、文字檔、目錄、空檔 | |
| `readelf` / `arm-linux-gnueabihf-readelf` / `aarch64-linux-gnu-readelf` | `-h`(檔頭)、`-d`(動態區段) | 其他選項回報不支援 |
| `size` / `strip`(及 `arm-linux-gnueabihf-`、`aarch64-linux-gnu-` 前綴版) | host 版只認 x86-64;cross 版只認對應架構,不符時 `file format not recognized` | `strip` 後檔案真的變小 |
| `ldd` | host 動態執行檔列出 `linux-vdso`、`libc.so.6`、`ld-linux`;ARM/aarch64 或靜態檔 → `not a dynamic executable`(exit 1) | |
| `qemu-arm` / `qemu-aarch64`(使用者模式) | 執行靜態檔或帶 `-L /usr/arm-linux-gnueabihf` 的動態檔,印出程式輸出 | 沒有 `-L` → `Could not open '/lib/ld-linux-armhf.so.3'` |
| `make` | 見下 | |

**編譯器會檢查的事**(真實風格錯誤):找不到檔案(`fatal error: no input files` / `compilation terminated.`)、
`#include "x.h"` 找不到、缺分號(`expected ‘;’ before ‘return’` 附原始碼片段與 caret)、大括號沒閉合、
缺 `main`(`undefined reference to 'main'` + `collect2: error: ld returned 1 exit status`)、`-lxxx` 找不到函式庫、
使用 `<gpiod.h>` 的 `gpiod_*` 卻沒加 `-lgpiod`、host 上使用 `-mfloat-abi` 等 ARM 專屬選項。
成功時**不輸出任何訊息**(也不會有警告),並寫出偽 ELF。

**執行編譯出的程式**:host `gcc` 編的 `./a.out` 會印出程式裡「單純字串的 `printf`/`puts`」(含 `%` 格式的 printf 只能略過並加一行提示);
ARM/aarch64 的檔案在 host 上執行 → `bash: cannot execute binary file: Exec format error`。要看到 ARM 程式的輸出請用 `qemu-arm`。
檔案大小是模擬值(動態 ARM 約 7 KB、靜態約 560 KB;strip 後縮小)。
`-static` 影響 `file`、`ldd`、`readelf -d`;`-g` 讓 `file` 顯示 `with debug_info`。

### make

簡化版 GNU make,讀 `Makefile`/`makefile`/`GNUmakefile`(`-f` 指定)。支援:

- 規則 `target: deps` + TAB 縮排配方;`@` 靜默、`-` 忽略錯誤;`.PHONY`;模式規則 `%.o: %.c`;預設目標為第一個非 `.` 開頭目標
- 變數 `=` `:=` `?=` `+=`、命令列 `VAR=值`(例如 `make CROSS_COMPILE=aarch64-linux-gnu-`)、`$(VAR)`/`${VAR}`、`$@ $< $^ $? $*`、替換參照 `$(SRCS:.c=.o)`
- 函式:`wildcard`、`patsubst`、`subst`、`notdir`、`dir`、`basename`、`addprefix`、`addsuffix`、`strip`、`sort`、`$(shell uname -r|uname -m|pwd)`
- 選項:`-f`、`-C 目錄`、`-n`、`-s`、`-k`、`-B`、`-j[N]`(忽略)
- 配方可呼叫本模組的編譯器/binutils,以及 `rm`、`echo`、`cp`、`mv`、`mkdir`、`touch`(支援 `&&`、`;`、`>`、`>>`,不支援管線)
- 「是否過期」不比較時間戳,而是記錄依賴檔內容簽章:`.c` 改動後重新編譯,沒改動回報 `make: 'app' is up to date.` / `make: Nothing to be done for 'all'.`
- 錯誤:`No targets specified and no makefile found.  Stop.`、`No rule to make target 'x', needed by 'y'.  Stop.`、
  `Makefile:N: *** missing separator (did you mean TAB instead of 8 spaces?).  Stop.`、`make: *** [Makefile:N: target] Error 1`
- **核心模組建置**:`make -C /lib/modules/6.1.0/build M=$(PWD) modules`(或 `clean`)讀取 `M` 目錄的 `obj-m += x.o`,
  檢查 `x.c` 後產生 `x.ko`(以及 `.o`、`.mod.o` 等)。`.ko` 內容由原始碼推得:`MODULE_LICENSE/AUTHOR/DESCRIPTION/VERSION`、
  `module_param` + `MODULE_PARM_DESC`、`module_init`/`module_exit` 函式裡 `pr_info`/`printk` 的字串(載入/卸載時會寫進 dmesg)。
  Makefile 中的 `make`/`$(MAKE)` 巢狀呼叫會顯示 `make[1]:`。

**不支援**(誠實回報 `make: *** 練習環境尚未支援:… Stop.`):`ifeq/ifdef`、`include`、`define`、`::` 規則、`$(foreach/if/call/eval/filter…)`、配方中的管線。

### 裝置樹

| 指令 | 說明 |
|---|---|
| `dtc -I dts -O dtb -o out.dtb in.dts` | 檢查語法(括號、分號、節點結構)→ 錯誤如 `Error: in.dts:19.2-3 syntax error` + `FATAL ERROR: Unable to parse input tree`;檢查 `&label` 參照 → `ERROR (phandle_references): /leds/led@0: Reference to non-existent node or label "gpio9"`;成功產生偽 dtb |
| `dtc -I dtb -O dts [-o out.dts] in.dtb` | 反編譯。輸出為標準化格式(tab 縮排、整數轉成 `0x` 十六進位),**保留 label 與 `&ref`**(真實 dtc 會轉成 phandle 數字) |
| `dtc -I dts -O dts` / `-I dtb -O dtb` | 重新格式化 / 複製 |
| `fdtget [-t s\|i\|u\|x] [-l] [-p] file.dtb /node [prop]` | 讀取屬性;`-l` 列子節點、`-p` 列屬性;不存在 → `Error at '/node': FDT_ERR_NOTFOUND` |
| `fdtput [-t s\|i\|u\|x] [-c] [-p] file.dtb /node prop value...` | 修改 dtb(`-c` 建立節點),之後 `fdtget`/`dtc -I dtb` 讀得到新值 |

不支援:`#include`、`/include/`、`/plugin/`(overlay)、括號運算式、`/delete-node/`、`-@`、`.dtbo`。節點以**完整名稱**(含 `@位址`)定址,例如 `/gpio@3f200000`。
偽 dtb 內含原始 dts 文字(所以反編譯回得來),`file` 的 size/block 數是依樹結構算出的真實大小。

### QEMU 與開機日誌

`qemu-system-arm`、`qemu-system-aarch64`、`qemu-system-x86_64`,以及 `qemu-img create [-f raw] x.img 64M` / `qemu-img info`。

- 參數檢查(真實風格訊息):沒有 `-M`(arm/aarch64)→ `No machine specified, and there is no default`;未知機器 → `unsupported machine type 'x'`;
  `-kernel`/`-dtb`/`-initrd`/`-bios`/`-drive file=` 檔案不存在;`-append` 沒有 `-kernel`;沒有 `-nographic`(或 `-display none`)→ `gtk initialization failed`(模擬沒有圖形介面)
- 機器:arm → `virt`、`vexpress-a9`(需要 `-dtb`)、`versatilepb`(需要 `-dtb`);aarch64 → `virt`;x86_64 → `pc`、`q35`。`-M help` 列出
- 磁碟:`-drive file=…,format=raw[,if=virtio|sd|ide|scsi|none]`(搭配 `-device virtio-blk-device,drive=ID`)、`-sd`、`-hda`。裝置命名:virt 預設 `/dev/vda`、`if=sd` → `/dev/mmcblk0`、x86 預設 `/dev/sda`
- **開機判定**(依實際參數,學員要自己看日誌排錯):
  - `root=` 缺少 → `VFS: Unable to mount root fs on unknown-block(0,0)`(panic)
  - `root=/dev/xxx` 與實際磁碟名稱不符 → `VFS: Cannot open root device "xxx" or unknown-block(0,0): error -6` + `Please append a correct "root=" boot option` + panic
  - 映像檔未格式化(`dd` 出來的零檔、`qemu-img create`)→ `EXT4-fs (vda): VFS: Can't find ext4 filesystem` + panic;`mkfs.ext4` 後就能開
  - `console=` 與機器序列埠不符(arm/aarch64 要 `ttyAMA0`、x86 要 `ttyS0`,x86 沒寫 `console=` 也算不符)或機器需要 dtb 卻沒給 → **完全沒有輸出**(提示卡住)
  - 沒有 `-append` 時使用 dtb 的 `/chosen/bootargs`;日誌會顯示 dtb 的 `model`
  - 成功:bootloader(有 `-bios` 或 `world.boot.uboot` 時印 U-Boot 橫幅與 `Starting kernel ...`)→ 核心版本 → 序列埠/區塊裝置 → 掛載 rootfs → `Run /sbin/init` → `Welcome to … / buildroot login:`
- QEMU 啟動後**直接輸出日誌並結束**,日誌尾端有一行「練習環境」說明(模擬終端機沒有互動 console)。panic 時 QEMU 真實會停住,也會註明。
- 輸出走 stdout(`out`),所以日誌不會被當成錯誤;只有參數錯誤才會走 `err` 並回傳 exit 1。
- 使用者模式與 KVM 等選項不支援;`-netdev/-device` 接受但不影響結果。

### 核心與模組

`lsmod`、`insmod`、`rmmod`、`modprobe [-r]`、`modinfo [-F 欄位|-d|-a|-l|-p]`、`depmod`(不做事)、`dmesg`(只支援無選項、`-c`、`-C`;`-T`/`-w`/`-l` 回報不支援)。

- 模組以虛擬檔案系統裡的 `.ko` **文字檔**表示,每行 `欄位: 值`:

  ```
  license: GPL
  author: Manco
  description: Hello module
  vermagic: 6.1.0 SMP mod_unload       # 與 world.kernel.release 不同 → insmod: Invalid module format,dmesg 有 version magic 訊息
  depends: base                        # 相依模組未載入 → Unknown symbol in module(modprobe 會自動先載入)
  parm: debug:Enable debug (int)       # 可有多行;insmod x.ko debug=1;未宣告的參數 → unknown parameter
  init_msg: Hello, kernel!             # 載入時寫入 dmesg(可多行)
  exit_msg: Goodbye, kernel!           # 卸載時寫入 dmesg
  init_error: -22                      # 選用:模擬 init 失敗(-1 -2 -8 -12 -16 -17 -19 -22 -110 對應 errno 訊息)
  size: 16384                          # 選用:lsmod 顯示的大小
  arch: arm                            # 選用:file 顯示的架構(預設 world.kernel.arch 或 x86-64)
  ```
- 需要 root(`sudo`):`insmod`/`rmmod`/`modprobe`/`depmod`;沒有 sudo → `Operation not permitted`。`dmesg` 預設也要 sudo(Ubuntu 的 `dmesg_restrict`),`world.dmesg_restrict = false` 可關閉。
- `modprobe` 與 `modinfo 名稱` 會在 `/lib/modules/<release>/` 底下找 `名稱.ko`(`-` 與 `_` 視為相同);請在 `fs` 放 `lib/modules/6.1.0/kernel/xxx.ko`。
- 載入後會更新 `/proc/modules`、建立 `/sys/module/<名稱>/parameters/<參數>`;dmesg 追加 `loading out-of-tree module taints kernel.`(無 license 時加 `module license 'unspecified' taints kernel.`)與 `init_msg`。
- **核心設定檔練習**:在 `fs` 放 `.config`(例如 `home/student/linux/.config`),學員用核心的 `grep CONFIG_ .config`、`grep -c`、`cat` 完成;`scripts/config`、`/proc/config.gz`、`zcat` 不支援。

### 硬體介面:libgpiod(以 v2 語法為主)

| 指令 | 說明 |
|---|---|
| `gpiodetect` | `gpiochip0 [pinctrl-bcm2835] (54 lines)` |
| `gpioinfo [-c chip]` | 每條 line 的名稱、占用者(consumer)、方向;被占用的 line 標示 `[used]`。格式為近似 v2,**請人工複審** |
| `gpioget -c gpiochip0 17 [27…]` | v2 輸出 `17=inactive 27=active`;`--numeric` 或舊語法 `gpioget gpiochip0 17` 輸出 `1`/`0 1` |
| `gpioset -c gpiochip0 17=1` | v2 語法;值也可寫 `active/inactive/on/off/high/low/true/false`;也可用 line 名稱 `GPIO17=1`。設定後方向變 output,之後 `gpioget` 讀得到 |
| `gpiomon` | 回報不支援 |

- 註記:**真實 libgpiod v2 的 `gpioset` 在程式結束時會釋放 line**(需 `-t`/`-z`/互動模式才持續持有);練習環境為了讓「設定後再讀取」可行,設定的值會保留。`-t`、`-z`、`-i` 等選項回報不支援。
  v1(libgpiod 1.6,Ubuntu 22.04/24.04 套件)語法是 `gpioset gpiochip0 17=1`、`gpioget gpiochip0 17`,本模組兩種都接受。
- 被 `consumer` 占用的 line → `gpioset: unable to request lines on chip '/dev/gpiochip0': Device or resource busy`(gpioget 同);offset 超出範圍、找不到 line 名稱、chip 不存在都有對應訊息。
- **`/sys/class/gpio` 舊介面已棄用**:模組只提供 `export`、`unexport` 與 `gpiochip<base>/{label,ngpio,base}` 檔案(`world.gpio.sysfs = false` 可關閉),`echo 17 > export` 不會有任何效果。教材請引導學員改用 libgpiod。

### 硬體介面:i2c-tools

| 指令 | 說明 |
|---|---|
| `i2cdetect -y N` | 0x03–0x77 矩陣;有裝置顯示位址,無 `--`,已有核心驅動(`driver` 欄位)顯示 `UU`;`-a` 掃 0x00–0x7f;`-l` 列匯流排;沒加 `-y` 會顯示警告與 `Continue? [Y/n]` 並中止(模擬無法輸入) |
| `i2cget -y N 位址 [暫存器 [b\|w]]` | 輸出 `0x1a`(word 為 `0x601a`);沒有裝置 → `Error: Read failed`;`UU` 裝置 → `Error: Could not set address to 0x3c: Device or resource busy`(`-f` 強制) |
| `i2cset -y N 位址 暫存器 值 [b\|w]` | 改寫暫存器,之後 `i2cget` 讀得到;無裝置 → `Error: Write failed` |
| `i2cdump -y N 位址` | 256 位元組傾印(只支援 byte 模式) |

spi 工具不做。

### 磁碟與映像工具

| 指令 | 說明 |
|---|---|
| `lsblk` | 依 `world.disks` 輸出樹狀(只支援無選項) |
| `fdisk -l [裝置\|映像檔]` | 需要 sudo(否則 `Permission denied`);互動模式不支援 |
| `dd if= of= bs= count= status=` | 檔案/映像檔/`/dev/zero`/`/dev/urandom`/`/dev/null`/`/dev/sdX`;輸出 `N+0 records in/out` 與 `bytes (… MB, … MiB) copied`(統計走 **stdout**,方便驗證器不把它當錯誤);`if=/dev/zero` 必須有 `count=`;寫裝置要 sudo。**寫到系統碟(`system: true` 或掛載了 `/` 的磁碟與其分割區)→ 顯示 `Are you sure? [y/N] n` 與警告並拒絕(exit 1)** |
| `mkfs.ext4 [-L 標籤] 分割區\|映像檔` | 印出 `mke2fs 1.47.0 …` 全文;檔案不存在 → `The file x does not exist and no size was specified.`;已掛載 → `is mounted; will not make a filesystem here!`;無 sudo 格式化裝置 → `Permission denied while trying to determine filesystem size` |
| `mount [-t 類型] [-o loop] 裝置 掛載點` / `umount` | 需要 sudo(`must be superuser`);掛載點不存在、裝置不存在、未格式化(`wrong fs type, bad option, bad superblock…`)、已掛載、`target is busy`(目前目錄在掛載點內)。不加參數列出掛載表 |

`dd`/`mkfs.ext4` 對檔案的結果存成**偽映像檔**(`MANCO-IMG {json}`),`file` 會顯示 `data`/`ext4 filesystem data, … volume name`/`DOS/MBR boot sector; partition 1 …`,
QEMU `-drive` 會讀取它的檔案系統狀態。限制:`ls -l` 顯示的是偽檔案本身的小尺寸,不是映像檔宣告的大小(核心 `ls` 以內容長度計算)。
`mount` 時 `world.disks[].partitions[].files` 的內容會出現在掛載點;`umount` 時掛載點內容存回分割區(練習環境的簡化)。
不做:`losetup`、`gzip`/`gunzip`/`cpio`、`lsblk` 選項、`fdisk` 互動模式。

---

## 2. world 設定

`world.embedded`(全部欄位可省略):

```php
'world' => ['embedded' => [
    'toolchains' => ['arm', 'aarch64'],       // 已安裝的交叉工具鏈(預設兩者都有);沒列的會回 "Command '…' not found, but can be installed with: sudo apt install gcc-…"
    'libs'       => ['z'],                    // 額外允許 -l 的函式庫(預設已含 m c pthread rt dl util gcc stdc++ gpiod crypt)
    'kernel'     => ['release' => '6.1.0', 'arch' => 'arm'],   // 目標核心版本(影響 .ko vermagic 檢查、modprobe 路徑、make -C 路徑)
    'boot' => [                                // QEMU 開機日誌
        'kernel_version' => '6.1.0',           // 日誌中的 Linux version(預設同 kernel.release)
        'hostname' => 'buildroot', 'distro' => 'Buildroot 2024.02',
        'uboot' => false,                      // true:先印 U-Boot 橫幅(用 -bios 時自動)
        'fail' => 'auto',                      // auto(依參數判定)|none|rootfs|init|oops|hang → 強制失敗模式(見下)
        'log_extra' => ['gpio-keys: probed'],  // 追加到核心日誌的行
    ],
    'modules' => ['gpio_pca953x', ['name' => 'i2c_dev', 'size' => 20480, 'deps' => []]],   // 開機時已載入的模組
    'dmesg'   => ['[    0.000000] Linux version 6.1.0', '[    1.234567] i2c i2c-1: new_device'], // 初始 dmesg
    'dmesg_restrict' => true,                  // false:不用 sudo 也能 dmesg
    'gpio' => [
        'root_only' => false,                  // true:非 root 存取 gpiochip → Permission denied
        'sysfs' => true,                       // false:不建立 /sys/class/gpio
        'chips' => [[
            'name' => 'gpiochip0', 'label' => 'pinctrl-bcm2835', 'ngpio' => 54, 'base' => 512,
            'lines' => [                       // 鍵 = offset;沒列出的 line 預設 input/unused/unnamed/0
                4  => ['name' => 'GPIO4'],
                17 => ['name' => 'GPIO17', 'dir' => 'output', 'value' => 0],
                18 => ['name' => 'GPIO18', 'dir' => 'output', 'value' => 1, 'consumer' => 'led0'],   // 被占用:gpioset/gpioget 會 busy
            ],
        ]],
    ],
    'i2c' => [
        'root_only' => false,
        'buses' => [1 => [
            'name' => 'bcm2835 (i2c@7e804000)',
            'devices' => [
                '0x48' => ['name' => 'tmp102', 'regs' => [0 => 0x1a, 1 => 0x60]],   // 暫存器預設 0
                '0x3c' => ['name' => 'ssd1306', 'driver' => 'ssd1307fb'],            // 有 driver → i2cdetect 顯示 UU,i2cget 回 busy
            ],
        ]],
    ],
    'disks' => [
        ['name' => 'sda', 'size' => '32G', 'system' => true, 'model' => 'SD/MMC', 'partitions' => [
            ['size' => '512M', 'fstype' => 'vfat', 'mount' => '/boot/firmware', 'boot' => true],
            ['size' => '31G', 'fstype' => 'ext4', 'mount' => '/'],
        ]],
        ['name' => 'sdb', 'size' => '8G', 'removable' => true, 'partitions' => [
            ['size' => '1G', 'fstype' => 'none', 'files' => ['readme.txt' => "sd card\n"]],   // fstype none = 尚未格式化
        ]],
    ],
]],
```

`boot.fail` 強制模式:`rootfs`(VFS: Unable to mount root fs)、`init`(No working init found)、`oops`(NULL pointer dereference → Kernel panic - Fatal exception)、`hang`(完全沒輸出)。
未設定(`auto`)時依參數判定,見上面「開機判定」。固定教學情境(例如「找出為什麼 panic」)可直接用 `fail`,也可以用 `fs` 放好錯誤的參數讓學員自己修。

### 在 fs 放置檔案

- 原始碼、Makefile、`.dts`:一般字串檔案即可。
- 核心映像、rootfs:任何非空字串檔案即可(例如 `'zImage' => 'zImage'`、`'rootfs.img' => 'rootfs'`);沒有 `MANCO-IMG` 標頭的檔案視為 ext4 映像。
- 要預先放「已格式化 / 已分割的映像檔」:內容寫 `MANCO-IMG {"size":67108864,"fstype":"ext4"}` 或
  `MANCO-IMG {"size":67108864,"fstype":"none","parts":[{"size":"16M","fstype":"vfat","boot":true},{"size":"32M","fstype":"ext4"}]}` 加換行。
- `.ko`:見上面的欄位格式。

---

## 3. check 類型

| type | 欄位 | 說明 |
|---|---|---|
| `elf` | `path`;可選 `arch`(`ARM`/`AArch64`/`x86-64`,不分大小寫,也接受 `arm64`、`x86_64`)、`static`(`true`/`false`)、`stripped`、`kind`(`executable`/`obj`/`so`) | 路徑是偽 ELF 且符合條件 |
| `dtb` | `path`;可選 `node`、`prop`、`equals`(屬性值文字;數字以空白分隔十進位)、`contains`(反編譯文字包含) | 是有效 dtb(可驗證 `fdtput` 修改結果) |
| `boot` | `state`(`ok`/`panic`/`hang`/`error`);可選 `contains`(日誌包含文字)、`machine`、`arch` | **最後一次** qemu 執行的結果;`hang`=無輸出卡住,`error`=參數錯誤或沒有可開機內容(不含 `Command not found`) |
| `module` | `name`;`loaded`(`true`/`false`,預設 `true`) | 模組目前是否載入 |
| `gpio` | `chip`(預設 `gpiochip0`)、`line`(offset 或名稱);可選 `value`(0/1/`active`…)、`direction`(`input`/`output`) | line 目前的值 |
| `i2c` | `addr`;可選 `bus`、`reg`(預設 0)、`value`、`read`(`true`:要求學員成功 `i2cget`/`i2cdump` 讀到這個值) | 預設檢查裝置暫存器目前的值(沒有 `value` 則只檢查裝置存在);`read: true` 檢查「曾經讀到」 |
| `mounted` | 可選 `path`、`dev`、`mounted`(預設 `true`) | 掛載狀態 |
| `fs` | `dev`(如 `/dev/sdb1`)或 `path`(映像檔);可選 `fstype`(預設 `ext4`)、`label` | 分割區/映像檔的檔案系統類型(驗證 `mkfs.ext4`) |

其他通用 check(`exists`、`contains`、`ran`、`out` 等)照常使用。例如檢查編譯出的檔案用 `exists` 就夠,要驗證架構才用 `elf`。
任務一開始不可成立:`boot`、`module(loaded:true)`、`gpio(value:1)` 等在初始世界都是 false,但 `module(loaded:false)` 與 `mounted(mounted:false)` 一開始就成立,**不要單獨使用**(搭配 `ran`)。

---

## 4. 驗證時的注意事項

- `tools/validate-terminal.mjs` 會把有 `err` 輸出的解答指令視為出錯。編譯失敗、`dd` 拒絕、`insmod` 失敗等「刻意示範錯誤」的步驟請列入 `allow_errors`。
- QEMU 日誌走 `out`,`dd` 統計走 `out`(真實為 stderr),所以不需要 `allow_errors`。
- `sudo` 對每個指令各自有效(核心行為):`sudo insmod hello.ko`、`sudo dmesg`。

## 5. 完整範例

```php
['title' => '交叉編譯並在 QEMU 開機', 'type' => 'terminal', 'xp' => 40,
 'content' => <<<'TXT'
你要為一塊 ARM 開發板準備第一個程式:先在主機上交叉編譯 hello.c(目標是 32 位元 ARM),
再把裝置樹編譯成 dtb,用 QEMU 的 virt 機器開機確認核心能掛載 rootfs;最後在目標板上載入核心模組、
點亮 GPIO 17 的 LED,並讀取 I2C 溫度感測器(0x48)的暫存器。每一步都用 file、lsmod、gpioget 等指令確認結果。
TXT,
 'config' => [
    'modules' => ['embedded'],
    'world' => ['embedded' => [
        'kernel' => ['release' => '6.1.0'],
        'gpio' => ['chips' => [['name' => 'gpiochip0', 'label' => 'pinctrl-bcm2835', 'ngpio' => 28, 'lines' => [17 => ['name' => 'LED']]]]],
        'i2c' => ['buses' => [1 => ['devices' => ['0x48' => ['name' => 'tmp102', 'regs' => [0 => 0x1a, 1 => 0x60]]]]]],
    ]],
    'fs' => ['home' => ['student' => [
        'hello.c' => "#include <stdio.h>\n\nint main(void)\n{\n    printf(\"Hello, ARM!\\n\");\n    return 0;\n}\n",
        'board.dts' => "/dts-v1/;\n/ {\n\tmodel = \"Manco Board\";\n\tchosen {\n\t\tbootargs = \"console=ttyAMA0 root=/dev/vda\";\n\t};\n};\n",
        'zImage' => 'zImage', 'rootfs.img' => 'rootfs',
        'hello.ko' => "license: GPL\ndescription: Hello module\nvermagic: 6.1.0 SMP mod_unload \ninit_msg: Hello, kernel!\n",
    ]]],
    'tasks' => [
        ['title' => '用 arm-linux-gnueabihf-gcc 把 hello.c 編成 hello', 'hint' => 'arm-linux-gnueabihf-gcc -o hello hello.c', 'check' => ['type' => 'elf', 'path' => '~/hello', 'arch' => 'ARM', 'static' => false]],
        ['title' => '再編一份靜態連結的 aarch64 版本 hello64', 'hint' => 'aarch64-linux-gnu-gcc -static -o hello64 hello.c', 'check' => ['type' => 'elf', 'path' => '~/hello64', 'arch' => 'AArch64', 'static' => true]],
        ['title' => '把 board.dts 編譯成 board.dtb', 'hint' => 'dtc -I dts -O dtb -o board.dtb board.dts', 'check' => ['type' => 'dtb', 'path' => '~/board.dtb']],
        ['title' => '用 QEMU virt 機器開機,到達 login 提示', 'hint' => 'qemu-system-arm -M virt -kernel zImage -dtb board.dtb -drive file=rootfs.img,format=raw -nographic', 'check' => ['type' => 'boot', 'state' => 'ok']],
        ['title' => '載入 hello.ko', 'hint' => 'sudo insmod hello.ko', 'check' => ['type' => 'module', 'name' => 'hello', 'loaded' => true]],
        ['title' => '用 libgpiod 把 GPIO17 設為 1', 'hint' => 'gpioset -c gpiochip0 17=1', 'check' => ['type' => 'gpio', 'chip' => 'gpiochip0', 'line' => 17, 'value' => 1]],
        ['title' => '讀取 I2C 匯流排 1、位址 0x48、暫存器 0 的值', 'hint' => 'i2cget -y 1 0x48 0', 'check' => ['type' => 'i2c', 'addr' => '0x48', 'reg' => 0, 'value' => '0x1a', 'read' => true]],
    ],
    'solution' => [
        'arm-linux-gnueabihf-gcc -o hello hello.c',
        'aarch64-linux-gnu-gcc -static -o hello64 hello.c',
        'dtc -I dts -O dtb -o board.dtb board.dts',
        'qemu-system-arm -M virt -kernel zImage -dtb board.dtb -drive file=rootfs.img,format=raw -nographic',
        'sudo insmod hello.ko',
        'gpioset -c gpiochip0 17=1',
        'i2cget -y 1 0x48 0',
    ],
 ],
],
```

## 6. 已知簡化與需人工複審的輸出格式

- `gpioinfo` / `gpioget` 的欄位與錯誤訊息是依 libgpiod v2 的印象實作,版本之間差異大(Ubuntu 22.04/24.04 套件是 v1.6)。
- `dtc` 的錯誤位置(`行.起欄-迄欄`)、`fdtput` 找不到節點的訊息、QEMU `-dtb` 無效檔案的訊息。
- 缺分號等編譯錯誤的 caret/`~` 片段、核心模組建置失敗時的 `make[2]` 行號(`scripts/Makefile.build:243`)。
- `lsblk` 的 MAJ:MIN 置中、`fdisk -l` 欄寬、`mkfs.ext4` 的區塊數與 journal 大小、`file` 對 `.ko`/映像檔的描述。
- ARM 交叉編譯預設為非 PIE(`ELF 32-bit LSB executable`);真實 Ubuntu 的 cross gcc 可能預設 PIE(`pie executable`)。需要時學員可加 `-pie`。
