Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 7 additions & 1 deletion README.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -357,7 +357,13 @@ interface = "eth0"
board_ip = "192.168.1.100"
```

`BootPayloadConfig.cmdline` and `initramfs` are independent optional fields. They are top-level runtime settings for QEMU, board, and U-Boot configurations rather than build settings. `initramfs` is the **host** archive, separate from a Linux guest initrd. Direct AArch64/RISC-V QEMU boot passes it with `-initrd` and passes `cmdline` with `-append`; x86 uses `EFI/BOOT/initramfs.cpio` and `cmdline.txt` on the UEFI ESP, not the Linux x86 boot protocol for a bare ELF. U-Boot includes the archive as a FIT ramdisk and sets `bootargs` before booting. FIT generation removes inherited `linux,initrd-start/end` properties and any exactly matching memory reservation from the input DTB. If the FIT contains a ramdisk, U-Boot writes the range for this boot. The serial command path rejects a `cmdline` containing a single quote. For board HTTP Boot, the archive and kernel belong to the same session and the server records the archive size and SHA-256. v5 devices retain identification and OTA; v6 devices first let the server verify the UART identity with the parameters reported for the current boot, then release the start request with a binding token, convert the compatibility entry to `__x86_64_efi_pe_entry`, and pass cmdline through EFI LoadOptions and initramfs through the TGOS `BootPayload` table. The v2/v3/v4 poll path retains identification and upgrade purposes, while ordinary boot returns `serial_protocol_upgrade_required`. The archive limit is 256 MiB and the command-line limit is 4095 printable ASCII bytes. Firmware and kernels on physical boards must implement the corresponding handoff.
`BootPayloadConfig.cmdline` and `initramfs` are independent optional fields. They are top-level runtime settings for QEMU, board, and U-Boot configurations rather than build settings. `initramfs` is the **host** archive, separate from a Linux guest initrd. Direct AArch64/RISC-V QEMU boot passes it with `-initrd` and passes `cmdline` with `-append`; x86 uses `EFI/BOOT/initramfs.cpio` and `cmdline.txt` on the UEFI ESP, not the Linux x86 boot protocol for a bare ELF. U-Boot includes the archive as a FIT ramdisk and sets `bootargs` before booting. FIT generation removes inherited `linux,initrd-start/end` properties and any exactly matching memory reservation from the input DTB. If the FIT contains a ramdisk, U-Boot writes the range for this boot. The serial command path rejects a `cmdline` containing a single quote. For board HTTP Boot, the archive and kernel belong to the same session and the server records the archive size and SHA-256. v5 devices retain identification and OTA; v6 devices first let the server verify the UART identity with the parameters reported for the current boot, then release the start request with a binding token, select the EFI entry for the kernel architecture (`__x86_64_efi_pe_entry` for x86_64, `efi_pe_entry` for RISC-V64 and LoongArch64), and pass cmdline through EFI LoadOptions and initramfs through the TGOS `BootPayload` table. The v2/v3/v4 poll path retains identification and upgrade purposes, while ordinary boot returns `serial_protocol_upgrade_required`. The archive limit is 256 MiB and the command-line limit is 4095 printable ASCII bytes. Firmware and kernels on physical boards must implement the corresponding handoff.

HTTP Boot does not persist `boot_arch`. Legacy values are read and discarded; after validating a legacy TOML, `FileBoardStore` atomically removes the field. A write failure preserves the source and reports an error; other unknown fields remain errors. The CLI reuses its existing ELF detection for the architecture header. The server parses little-endian ELF64 with `object`, checks `e_machine` against the declaration on upload, then rechecks the stored file, declaration and axloader's `observed.arch` before serial handoff. A mismatch sets serial state to `Failed` and stops the session. The board editor shows reported architecture read-only while online and unknown while offline or undiscovered; sessions and kernels can be prepared offline and matched when the device appears.

OTA images are opaque bytes to the server. `OtaStore` accepts nonempty content up to 32 MiB, stores its label, length and SHA-256, and checks storage integrity before delivery; axloader validates PE/COFF format, `Machine` and platform loadability. The server and Web UI do not restrict OTA by CPU architecture. Offline jobs may queue; missing actual `ota` state leaves a visible waiting reason. Legacy v4 poll upgrades also rely on device validation, while downloads still require the current registration, OTA capability and matching MAC/job binding.

A device's `202` only means the image was staged. A job succeeds only after the new slot actually runs, is confirmed and has the matching digest. A `400`/`413`/`422` refusal fails the job once and preserves the HTTP status and device response body, including legacy `422 {}`. A `409` refreshes state/epoch before a delayed retry; a `503` waits for state, capability or epoch to change without repeated pushes. Network errors and other `5xx` responses use bounded retries with backoff. An uncertain result is checked against actual device acceptance before retrying or declaring the final attempt failed. See the [loader upgrade contract](docs/axloader-network-control.md#22-装载器升级) for details.

### Ordered shell initialization steps

Expand Down
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -333,7 +333,13 @@ interface = "eth0"
board_ip = "192.168.1.100"
```

`BootPayloadConfig` 的 `cmdline` 与 `initramfs` 相互独立且都可省略;它们是 QEMU、board 与 U-Boot 的顶层运行配置,不属于构建配置。`initramfs` 是宿主归档,与 Linux guest 的 initrd 分开配置。QEMU 直启仅在 AArch64/RISC-V 路径使用 `-initrd` 和 `-append`;x86 使用 UEFI ESP 中的 `EFI/BOOT/initramfs.cpio`、`cmdline.txt`,不向裸 ELF 传 Linux x86 启动协议参数。U-Boot 的 `generate_fit_image()` 将归档作为 FIT ramdisk,并在启动前设置 `bootargs`;生成 FIT 前会清除输入 DTB 中遗留的 `linux,initrd-start/end` 及与其完全对应的内存预留;若 FIT 包含 ramdisk,U-Boot 会写入本次启动的实际范围。串口命令路径暂不接受含单引号的 `cmdline`。board HTTP Boot 将归档和内核上传到同一 session,服务端记录归档大小与 SHA-256。v5 设备保留识别与 OTA;v6 设备由服务端先按本次上报的 UART 参数确认串口身份,再以绑定令牌放行启动,兼容入口转换为 `__x86_64_efi_pe_entry`,cmdline 通过 EFI LoadOptions、initramfs 通过 TGOS `BootPayload` 交接。v2/v3/v4 poll 保留识别与升级用途,普通启动统一返回 `serial_protocol_upgrade_required`。归档上限为 256 MiB,cmdline 上限为 4095 字节且仅允许可打印 ASCII 和空格。实体板卡的固件和内核须实现对应交接协议。
`BootPayloadConfig` 的 `cmdline` 与 `initramfs` 相互独立且都可省略;它们是 QEMU、board 与 U-Boot 的顶层运行配置,不属于构建配置。`initramfs` 是宿主归档,与 Linux guest 的 initrd 分开配置。QEMU 直启仅在 AArch64/RISC-V 路径使用 `-initrd` 和 `-append`;x86 使用 UEFI ESP 中的 `EFI/BOOT/initramfs.cpio`、`cmdline.txt`,不向裸 ELF 传 Linux x86 启动协议参数。U-Boot 的 `generate_fit_image()` 将归档作为 FIT ramdisk,并在启动前设置 `bootargs`;生成 FIT 前会清除输入 DTB 中遗留的 `linux,initrd-start/end` 及与其完全对应的内存预留;若 FIT 包含 ramdisk,U-Boot 会写入本次启动的实际范围。串口命令路径暂不接受含单引号的 `cmdline`。board HTTP Boot 将归档和内核上传到同一 session,服务端记录归档大小与 SHA-256。v5 设备保留识别与 OTA;v6 设备由服务端先按本次上报的 UART 参数确认串口身份,再以绑定令牌放行启动,按内核架构选择 EFI 入口(x86_64 为 `__x86_64_efi_pe_entry`,RISC-V64 和 LoongArch64 为 `efi_pe_entry`),cmdline 通过 EFI LoadOptions、initramfs 通过 TGOS `BootPayload` 交接。v2/v3/v4 poll 保留识别与升级用途,普通启动统一返回 `serial_protocol_upgrade_required`。归档上限为 256 MiB,cmdline 上限为 4095 字节且仅允许可打印 ASCII 和空格。实体板卡的固件和内核须实现对应交接协议。

HTTP Boot 不持久保存 `boot_arch`;旧字段兼容读取后丢弃,`FileBoardStore` 验证旧 TOML 后原子删除该字段,写入失败保留源文件并报错,其他未知字段仍拒绝。CLI 复用已有 ELF 检测结果生成架构 Header;服务端用 `object` 解析小端 ELF64,上传时校验 `e_machine` 与声明,串口交接前再核对文件、声明及 axloader 的 `observed.arch`。不匹配时串口状态进入 `Failed` 并停止会话。编辑页只读展示在线设备上报架构,离线或未发现时显示未知,仍可准备 Session 和内核,待上线后匹配。

OTA 镜像对服务端是不透明的字节:`OtaStore` 接受非空且不超过 32 MiB 的内容,保存标签、长度与 SHA-256,下发前校验存储完整性;PE/COFF 格式、`Machine` 和平台可加载性由 axloader 判定。服务端和 Web UI 不按 CPU 架构限制 OTA,离线可排队,缺失实际 `ota` 状态时保留可见的等待原因。旧 v4 poll 升级同样由设备校验镜像,下载仍要求当前注册代次、OTA 能力及 MAC/任务绑定匹配。

设备返回 `202` 仅表示暂存通过,任务须在新槽实际运行、确认且摘要匹配后才成功。`400`/`413`/`422` 拒绝会使本次任务一次失败并保留 HTTP 状态和设备响应体(包括旧 `422 {}`);`409` 刷新状态/代次并延迟重试,`503` 等待状态、能力或代次变化而不重复推送。网络错误和其他 `5xx` 有限退避重试,结果不确定时先核对设备是否已接受,最后一次尝试也在判定失败前核对。完整契约见[装载器升级](docs/axloader-network-control.md#22-装载器升级)。

### 有序 Shell 初始化步骤

Expand Down
24 changes: 20 additions & 4 deletions docs/admin-ui.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,21 @@ QEMU 使用已有虚拟设备,保留原来的真实网络发现与匹配校验
由会话的 SSE 展示;`serial_manager` 展示发现请求数与候选监听数。没有黑名单界面。
继电器配置继续保留,server 在发现前排除其所有路径别名和 SN。

HTTP Boot 的 `boot_arch` 保留在“高级启动设置”中;留空沿用现有 CLI 的
`x86_64` 默认值,并不表示自动识别。设备上报架构只读展示,普通绑定无需填写该项。
HTTP Boot 不再配置或保存 `boot_arch`,旧配置中的该字段在载入后忽略,重新保存时移除。
内核架构从 ELF 读取,设备架构取自 axloader 的 `observed.arch`;发现列表和
`BoardEditor` 只读展示设备上报架构,编辑页在设备离线或未发现时显示未知。
`boardToFormState()` 和 `buildRequestPayload()` 不保留人工架构状态,选择 MAC 只改变绑定。

`BoardOta` 的上传、排队、任务历史和取消操作不按 CPU 架构隐藏;设备离线或未发现时
仍可先排队。服务端保存非空且不超过 32 MiB 的镜像字节、标签、长度及 SHA-256,
由 axloader 校验格式、`Machine` 和平台兼容性。实际 `ota` 状态缺失时不下发镜像,
任务保留可见的等待原因;设备返回 `503` 后,等待状态、能力或代次变化再尝试。

面板通过现有 `ota` SSE 资源展示 `Job.phase` 和 `Job.error`,包含设备 HTTP 状态与
原始错误体;旧设备的 `422 {}` 也会显示为拒绝并只失败一次。`202` 仅表示暂存,
待新槽实际运行、确认且摘要匹配后任务才成功。`409` 延迟重试和网络错误的有限退避
由服务器处理;用户仍可查看错误或取消非终态任务。完整状态规则见
[装载器升级](axloader-network-control.md#22-装载器升级)。

开关机命令提交后由服务器持有,关闭页面不取消、不自动断电。实体板没有电源
反馈时,只显示命令完成。电源资源正在执行操作或属于使用中/释放中的板卡时,
Expand Down Expand Up @@ -116,8 +129,11 @@ pnpm --dir ostool-server/webui test:e2e
启动逐文件读取板卡 TOML。语法错误、不支持的枚举、缺失必填字段、校验失败、
文件名与 ID 不一致或重复 MAC 的文件移动到
`<board_dir>/quarantine/<UTC时间>-<UUID>/<原文件名>`,原始字节保持不变。
同目录的 `reason.json` 保存来源、备份路径、时间和完整原因;启动日志和开发板
页面也显示隔离记录。备份名称不会覆盖之前的文件,下次启动不再扫描隔离目录。
同目录的 `reason.json` 保存来源、备份路径、时间和完整原因,启动日志报告本次
隔离的配置。开发板页面的 `Boards` 将 `quarantined_boards` 与已加载的 `boards`
核对,仅提示尚未恢复同名配置的隔离记录。配置恢复并成功加载后,即使板卡已禁用,
旧错误也不再作为待修复问题显示;历史备份及原因仍保留。备份名称不会覆盖之前的
文件,下次启动不再扫描隔离目录。

目录按文件名排序加载;重复 MAC 保留排序最前的有效配置,隔离后续冲突文件。
其余有效板卡继续提供服务。修正备份文件后,管理员可将其放回板卡配置目录并
Expand Down
Loading