Compare commits

...
Author SHA1 Message Date
noah c7cda3064e ci: move OS PR gate and build/pages jobs onto the alkane-ci pool (#17)
main-release-gate / verify-and-release (push) Failing after 6m10s
2026-11-16 14:57:41 -07:00
noah 484f479b90 Merge pull request 'web: public read-only GET /api/identity for fleet discovery' (#16) from feature/scan-identity into main
main-release-gate / verify-and-release (push) Failing after 16m44s
2026-11-12 15:13:21 -07:00
noahandClaude Opus 5.5 2d3417b7d3 web: public read-only GET /api/identity for fleet discovery
source-pr / source (pull_request) Successful in 3m26s
alkane-toolkit's fleet scan (asic-rs) recognises miners by their cgminer
socket or vendor web UI; an Alkane board has neither exposed, so it never
appeared and could not be right-clicked to flash. Add an open, read-only
identity endpoint beside /api/summary: os, os_version, board, sdk_revision,
hostname, mac, kernel - nothing a stock miner does not already expose, no
secret. The .afw packager stamps the bundle version into
/etc/alkane-os-version for it. Tests: served without a session; every field
read from the board files; absent files read as null.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-12 15:40:02 -06:00
noah cc14543ced Merge pull request 'main: afw OS-bundle line (web console, .afw producer, zynq image, review fixes)' (#15) from feature/afw-os-bundle into main
main-release-gate / verify-and-release (push) Failing after 9m34s
2026-11-12 14:13:16 -07:00
noahandClaude Opus 5.5 a34cf20628 ci: drop the stale source-pr.yml; fold its checks into fast-pr
source-pr / source (pull_request) Successful in 2m26s
main replaced source-pr.yml with fast-pr.yml (same workflow name, same
concurrency group, newer runner image); the merge kept both, so every PR ran
two "source-pr / source" jobs that cancelled each other, and fast-pr's
runner-image check failed on the stale pin in source-pr.yml. Remove
source-pr.yml and carry its checks into fast-pr for non-documentation changes:
the patch-whitespace check (vendored trees excluded) and the CI/evidence tool
tests. Locally: runner-image pins PASS, ci tests pass, cargo test --locked 250
passed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-12 15:10:28 -06:00
noahandClaude Opus 5.5 abb6bfd35d ci: keep the patch-whitespace check off vendored third-party trees
source-pr / source (pull_request) Failing after 10s
source-pr / source (pull_request) Successful in 2m9s
The afw line adds the cargo vendor tree (vendor/) and the flare-ui source
(third-party/). Their upstream files carry trailing whitespace and SSE golden
fixtures end with a blank line by format; editing them would break cargo's
vendor checksums and the fixtures. Exclude both trees from git diff --check in
source-pr and fast-pr, as the toolkit's gate does. No first-party file fails
the check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-12 14:55:25 -06:00
noahandClaude Opus 5.5 dce31c8784 style: rustfmt the console/runtime work (no behaviour change)
source-pr / source (pull_request) Failing after 9s
source-pr / source (pull_request) Canceled after 0s
The source-pr gate runs cargo fmt --check; the afw OS-bundle line had not been
formatted. Pure cargo fmt output. 250 tests pass; clippy -D warnings clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-12 14:53:52 -06:00
noahandClaude Opus 5.5 32ab0d75ba Merge main into feature/afw-os-bundle
Bring the Oct 18-20 CI hardening on main into the afw OS-bundle line before
promoting it to main. Resolution:
- src/{main,lib,hal_wire,management}.rs, Cargo.toml, Cargo.lock: the branch
  side; it is a superset of main's (main's ALKANE_API_LISTEN management API now
  lives in src/app.rs and is wired for every run mode).
- workflows: main's runner-image pin (ad56db2f) and conditional SSH install,
  main's workflow_run triggers for the badge and Pages publishers, next's
  CARGO_BUILD_JOBS=2; the branch's extra gates (image safety, .afw tests,
  research/evidence, version checks, evidence-status artifact) are kept.
- ci/last-attempt-badge.py + its test, ci/publish-bench-pages.py: main's
  (workflow_run events; stderr detail on failure). ci/cleanup-generated.py: the
  branch's (also cleans the evidence-status file the kept step writes).
- README.md, ci/CONFORMANCE.md: the branch's (documents the web console and
  the evidence-status report, both present in the merged tree).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-12 14:53:17 -06:00
noahandClaude Opus 4.8 2c5eccae55 os: apply code-review-harness fixes (security/reliability/correctness)
Four-dimension review (correctness/security/reliability/maintainability) of today's
console/bus/login/dashboard/image work found no Critical/High; the HTTP parser,
login gate (un-bypassable), bus semantics and the HMAC/PBKDF2/SHA-256 math were
verified correct. The Medium findings are fixed here.

Security:
- Token-gate /api/files and /api/file (were session-only despite the docs/Security
  page claiming token-gated - arbitrary root-readable file exfiltration).
- Neutralize settings-redirect header-splitting: __section/__tab are constrained to
  safe slugs before going into the Location header (CRLF no longer injects).
- One token source (auth::rand_hex): fail loud + non-constant fallback instead of the
  published "dev-csrf-token" / second-granular wsid when /dev/urandom is unreadable.
- Constant-time UI-token compare (auth::ct_eq); write auth.json 0600, dir 0700.
- Cap concurrent connections (64, 503 beyond) + 10s head-read deadline, bounding the
  thread-per-connection flood on the open :80.

Reliability/correctness:
- Settings persistence now propagates its write error (was swallowed and reported as
  success with a misleading comment) and writes atomically (temp+rename); deck save
  atomic too. Auth::login returns None if the session insert failed.
- TuningLoop::set_target resets the PID accumulator on a mode change (the old target's
  integral is in the old units) while keeping the operating point.
- Editable-deck JS: monotonic new-block ids (no collision after remove+add), default
  source frequency (was power_w, not in the live map), symmetric drag-drop placement,
  re-render after save. Drivers "stopped" shows the bare reason, not JSON-quoted.

Maintainability:
- New `form` module consolidates the three divergent percent_decode/field copies
  (web/service/dashboard). Added a test asserting published state topics match the
  registry contract.

Report in code-review-report.md (verdict, accepted-by-design posture incl. the
no-TLS / factory-creds residual risk, and a deferred list: ui.rs dead code, deck
assets extraction, target_label dedup). 206 lib tests + integration pass, clippy
-D warnings clean, no emojis. Image rebuilt with the fixed binary.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-10 21:41:59 -06:00
noahandClaude Opus 4.8 18b5fac584 image: build the console into a zynq-7010 .afw + fix serve_only API bind
Produce a flashable zynq-7010 image carrying the current console, and make the
image serve it on boot.

- image/make-zynq-afw.sh: cross-compiles alkane-os for armv7 (static musl,
  matching the SDK rootfs; the ARM cross-gcc is the linker since the host cc
  cannot link ARM objects), drops the binary and the image overlay into the SDK's
  zynq rootfs, repacks the ramdisk under fakeroot (device nodes + root ownership
  preserved), and packages zImage + dtb + rootfs into a .afw via ci/make-afw.sh.
- image/overlay/etc/init.d/S60alkane-web: starts `alkane-os --serve` after the
  network, so the booted image serves the console (login + read-only API) on :80.
  The SDK init owns board-detect/network/ssh and leaves the console to this.
- main.rs: fix serve_only to default the cgminer API to loopback (127.0.0.1:4028)
  instead of 0.0.0.0, which bind_local (loopback-only) rejected - so plain
  `--serve` now starts instead of failing to bind.

Verified: the build produces dist/alkane-os-0.1.0-zynq-7010-armv7.afw (check-afw
OK: kernel 4.3MB, dtb 11KB, rootfs 3.26MB), the rootfs carries the new binary +
the web-init overlay, and the static armv7 binary runs under qemu-arm and serves
the console end to end (login page renders, admin/admin -> 303 session,
/api/hardware open). dist/ is gitignored, so the artifact is not committed.
clippy -D warnings clean, no emojis.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-10 21:26:53 -06:00
noahandClaude Opus 4.8 34bccbd437 os: editable main dashboard + full settings tabs (drivers/services/monitor)
Make the main dashboard an editable deck, like wardenOS's dashboard, and split
the remaining settings into their own tabs.

- console.rs: dashboard/overview is now an editable deck - a .wdash-style
  document stored on the box (bus dashboard/* verbs behind /api/dashboard) whose
  blocks draw live values from the open miner-state API. A self-contained island
  (CSS + JS in the flare-ui shell) renders the grid and, in edit mode, adds,
  removes, reorders and saves blocks; Reset restores the template. Drivers,
  Services and Monitor are now distinct settings tabs rather than bundled into
  System/Security.
- schema/alkane-bb.json: add the settings/drivers, settings/services and
  settings/monitor menus so the nav shows them (settings now has 11 tabs).
- service.rs: the deck directory falls back to a writable path off the miner so
  the editable dashboard saves in a dev run too.

Verified on --serve-sim: the dashboard renders with an Edit toolbar, a deck
saves and reloads from /api/dashboard and Reset restores the 5-block template,
and every settings tab (system/tuning/pools/network/drivers/security/services/
monitor/logs/files/terminal) answers. 203 tests pass, clippy -D warnings clean,
no emojis.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-10 21:18:18 -06:00
noahandClaude Opus 4.8 e036d99f02 os: add console login (local account + session cookie), wardenOS-style
Gate the web console behind a sign-in, modeled on wardenOS's local auth (spec
d05): a local account whose password is stored only as a salted KDF hash, and a
`wsid` session cookie issued on login. wardenOS uses Argon2 from warden-verifier;
alkane-os is dependency-light, so auth.rs implements PBKDF2-HMAC-SHA256 on the
crate's own pure-Rust SHA-256 (pow::sha256) - a standard password KDF with no
new dependency (RFC 4231 / PBKDF2 test vectors included). Factory account is
admin/admin, persisted to /etc/alkane/auth.json when writable. OIDC and FLARE
bundle users are out of scope (no portal here).

- auth.rs: Account (salt+iters+hash), Auth (account + live sessions), login ->
  wsid, valid, logout. Iterations tuned for the pure-Rust hash so a login stays
  sub-second on a slow board while staying strong as defense-in-depth behind SSH.
- web.rs: WebContext gains the Auth; the request parser reads the wsid cookie;
  route() gates everything behind a live session EXCEPT the read-only miner-state
  JSON (/api/hardware|summary|control), which stays open as the interface of
  record (also on the cgminer socket). /login, POST /auth/local (CSRF-checked,
  sets the HttpOnly SameSite=Lax cookie) and POST /auth/logout added.
- console.rs: login_page - a standalone flare-ui card.

Verified on --serve-sim: unauthenticated GET / serves the login page, admin/admin
issues a session and the console renders, host/mutation endpoints 401 without a
session, miner-state reads stay open. 203 lib tests pass, full suite green,
clippy -D warnings clean, no emojis.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-10 21:11:54 -06:00
noahandClaude Opus 4.8 43a09c158a os: re-seat the UI and API on a command/state bus (wardenOS-style)
Introduce a single command point - the bus - that the HTTP API, the web console,
and any future remote/flare client all go through, mirroring wardenOS's
architecture (flare-edge `sprint`). wardenOS runs this as an MQTT broker over a
Unix socket; per its own porting note the right first step is to implement the
Bus facade (publish_state / read_state / request / emit) over an in-process
broker with the registry as the contract, swappable for a socket broker later
without touching callers. alkane-os is std-only and headless, so that is what
this does - no tokio, no MQTT.

- bus.rs: the in-process hub. Retained `state` topics (reads), `req`/`reply`
  verbs dispatched to one owning handler (the single write path), and a bounded
  `evt` ring. BusError carries warden-style E_* codes.
- registry.rs: the contract - every topic and verb as typed constants plus a
  machine-readable description. A test asserts the live bus matches it, the
  property busgen gives warden, so the contract cannot drift from the code.
- service.rs: the miner service owns the control/settings/dashboard verbs and
  publishes the hardware/summary/control state. Like a warden service it
  republishes the affected state the instant a command applies, so a reader
  never sees a command lag the periodic telemetry publish (the bus is held Weak
  to avoid an Arc cycle).
- web.rs is now a thin HTTP->bus translator (WebContext{bus, csrf}): writes are
  bus.request, miner-state reads are bus.read_state, the legacy hand-rendered
  page arms are gone (the console renders every nav tab). console.rs reads the
  state docs and the csrf is passed in. app::start/main.rs build the bus, register
  the service, and publish each control period.

Verified on --serve-sim: stop -> switch to ambient:18000 -> start now each
reflect immediately in /api/control, live frequency tracks the target, and a
stale CSRF is rejected. 193 lib tests pass (incl. bus/registry/service), full
suite green, clippy -D warnings clean, no emojis.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-10 21:03:08 -06:00
noahandClaude Opus 4.8 c752fc6d8b third-party: re-vendor flare-ui at sprint (the most-ahead branch)
The vendored flare-ui was a Nov-4 snapshot with no recorded pin. Advance it to
the furthest-along upstream branch: blueflare/flare-ui `sprint`
(0e1f5a259faa), which is 247 commits beyond `main`, 71 beyond `next`, and
already contains `next` in full. The scattered 1-3 commit leads on individual
sp/* feature branches are unmerged side-work, not a more-ahead integration line,
so vendoring one of those would drop the 247-commit integration; `sprint` is the
single most-ahead branch.

This brings sprint's flare-ui crate additions (form.rs, page.rs, page/, table.rs
and the flare-ui-axum / flare-plugin-host crates) into the tree. Record the pin
in flare-ui.lock so the next re-vendor is reproducible.

alkane-os builds against it with no source changes: the console (console.rs) and
the rest compile clean, clippy -D warnings is clean, and 183 lib + integration
tests pass (including the dashboard schema tests, so the wschema model stayed
compatible). Re-verified the live console on sprint: --serve-sim boots, the
flare-ui shell and control pages render, and stop -> ambient:18000 -> start all
succeed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-10 20:19:12 -06:00
noahandClaude Opus 4.8 802f254e9a web: make the flare-ui console fully functional with a live sim backend and operator control
The on-box UI shipped as a half-migrated shell: the schema settings rendered
with no submit form, the flare-ui nav tabs shadowed the legacy pages with empty
cards, and --serve stood the UI up with no runtime so every value read "not
identified" and nothing could be controlled. This makes it work end to end,
driven by flare-ui, and fully exercisable on a workstation with no hashboard.

Live backend (alkane-os --serve-sim): run the reference HAL in-process on a
private unix socket, boot the runtime against it, and run a control loop that
applies the operator intent every period and publishes a live snapshot. On this
workstation the console shows the chain frequency climbing toward the target and
the controls taking effect; --serve keeps serving the same console with no
backend for a board whose HAL is not written yet.

Operator control channel (control.rs): the one mutable path into the runtime -
a mode/target and a run switch, plus a per-process CSRF token. ControlMode maps
one-to-one onto the real TuningTarget variants (power / ambient / hashrate /
max-fan), so the UI never offers a behaviour the controller lacks. runtime.rs /
tuning.rs gain set_target/target so a mode change applies in place, keeping the
PID state instead of snapping to the envelope floor.

flare-ui console (console.rs): every nav tab rendered from flare-ui primitives
(shell, render::card, readings, actions, components) with live data - overview
hero + state, mining hashboards/power/fans, a Control page with Start/Stop
action buttons, a working Tuning form that posts to /settings, and the system/
security/logs/files/terminal pages wired to their existing data. The tuning
form submit persists the setting AND switches the live target; Start/Stop and
the form are CSRF-checked. /api/control exposes the operator state as JSON, the
interface of record behind the page.

Wiring: app::start and web::serve_listener/handle/route carry Arc<Control>;
main.rs gains --serve-sim and threads a Control through the existing serve/boot
paths. README updated: the "no web frontend" note is no longer true.

Verified on this workstation: --serve-sim boots (s19jpro-bm1362-pic, 3 chains),
frequency converges toward power:2400, and the flare-ui pages drive stop ->
switch to ambient:18000 -> start, with a stale CSRF token rejected (403).
Tests: 183 lib + integration green; clippy -D warnings clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-10 20:14:10 -06:00
noahandClaude Opus 4.8 8d48e488bd a113d (Amlogic AXG/S21 Pro): .afw producer profile + double brick gate
Add the S21 Pro-class Amlogic A113D/AXG control board to the .afw producer
and the CI brick-prevention gate, matching the Zynq-7010 treatment.

- ci/afw_boards.py: a113d producer profile (arm64, preserve, buildable). Maps
  the 7-mtd layout, names nvdata (mtd6) the only image-bearing partition, and
  stages three images vmlinux.bin/devicetree.dtb/uramdisk.image.gz
  (arm64-image/fdt/uimage) into it.
- ci/afw_manifest.py: validate_a113d enforces exactly those three images, the
  formats, per-image ceilings, total <= nvdata usable, and that no
  bootloader/spl/fip/tpl member is present and no non-nvdata partition carries
  an image.
- ci/check-afw.py: the independent checker re-validates the produced bundle
  (arm64, preserve, no FIP member, three named images with formats/ceilings,
  total <= nvdata, mtd0-5 carry no image) and knows the arm64 Image magic.
- ci/test-afw.py: a113d bundle passes and installs all three into nvdata;
  non-arm64 kernel, oversize kernel, an added FIP member, and a preserved mtd
  made to carry an image are each refused.

All 37 afw tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qHxYpv7yf7Ah57g4rQ
2026-11-06 21:01:56 -06:00
noahandClaude Opus 4.8 baf19ed6c8 Formalize zynq-7010 tier-2 .afw: producer profile + brick gate (zimage format, ceilings, preserve)
Adds a buildable zynq-7010 profile and its .afw brick-prevention gate, so the
proven Zynq image is a first-class .afw like cv1835/am335x.
- afw_boards.py: full zynq-7010 profile (armv7, preserve; kernel(zimage)+dtb(fdt)
  into mtd0, rootfs(cpio-gzip) into mtd1); new strict 'zimage' SAFE_IMAGE_FORMAT.
- afw_manifest.py + check-afw.py: validate_zynq / the zynq-7010 gate - exactly the
  kernel/dtb/rootfs image set, correct formats, size ceilings (kernel <= 0x500000
  fits the slot, dtb <= 0x20000, rootfs <= 0x2000000 fits mtd1), and NO
  bootloader/spl/BOOT.bin member (stock BOOT.bin + FPGA bitstream preserved). The
  per-unit kernel-slot offset is placed by the install method (differs S17/S19),
  so the gate enforces formats+ceilings+policy, not a fixed offset map.
- check-afw: strict zimage magic (0x016f2818 at 0x24).
- tests: good bundle, non-zImage kernel, oversize kernel, bootloader-member refusals.
Built + double-gated the real bundle: alkane-os-0.1.0-zynq-7010-armv7.afw
(kernel 4.1 MiB, dtb 11 KB, rootfs 2.5 MiB). Full afw suite green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qHxYpv7yf7Ah57g4rQ
2026-11-06 19:43:47 -06:00
noahandClaude Opus 4.8 6b24c85fce Add am335x-stock (tier-3) .afw producer profile + brick gates
Mirrors the alkane-sdk tier-3 plan gate on the producer side so a from-stock
bundle can be built and verified. The am335x-stock profile writes our non-RSA
U-Boot to mtd4 (legacy firmware uImage, ih_type 5) plus kernel/dtb/root, and:
- afw_boards.py: am335x-stock profile (bootloader_policy include, mtd4 write
  target at order 3, kernel at order 4, u-boot image).
- afw_manifest.py + check-afw.py: validate_am335x_stock - shares the 12-part map
  and 0x780000 hole with tier-2 but asserts policy include, the 4-image set,
  mtd4 ceiling 0x1c0000, the U-Boot member is a type-5 firmware uImage, and that
  no SPL copy (mtd0-3) or bootenv (mtd5) is ever a write target.
- check_format: am335x uImage checks now cover am335x-stock, incl. u-boot type 5.
- tests: 3 am335x-stock producer cases (good 4-install bundle, wrong U-Boot type,
  SPL-write refusal). Full afw suite 28 green; am335x tier-2 + cv1835 unchanged.

Built and double-gated the real bundle locally: alkane-os-0.1.0-am335x-stock-arm.afw
(u-boot 723440 B type5 -> mtd4, kernel -> mtd7, dtb -> mtd6, rootfs -> mtd8).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qHxYpv7yf7Ah57g4rQ
2026-11-05 20:18:43 -06:00
noah 95568d7339 Emit and gate legacy-uImage AM335x .afw bundles 2026-11-04 17:03:13 -06:00
noahandClaude Opus 4.8 d612bb6521 make-afw: emit SHA256SUMS for the built bundle so it cannot drift
The producer verified the bundle but never wrote the SHA256SUMS release
artifact, so a stale file from a previous build could describe a different
bundle. Write it (overwrite) from the finished file.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qHxYpv7yf7Ah57g4rQ
2026-11-04 15:25:38 -06:00
noahandDeepSeek Harness c1736f65e8 Cover the plan cross-check in the .afw gate tests
Assert that the checker accepts a matching plan size and rejects a plan
whose p1 size disagrees with the manifest.

Co-Authored-By: DeepSeek Harness <noreply@deepseek.com>
2026-11-04 14:33:32 -06:00
noahandDeepSeek Harness 553f6a04fb Add a full-OS .afw bundle and strict CI gate
Replace the release-tree producer with a board-aware schema-2 manifest,
fixed-order ustar packing, optional Ed25519 signing, and a checker that
rejects a wrong board or arch, a missing or oversized image, a bootloader
member under preserve, a hash or size mismatch, and a traversal member.
Document the format and add offline fixtures for every refusal.

Co-Authored-By: DeepSeek Harness <noreply@deepseek.com>
2026-11-04 14:31:35 -06:00
x 997771ab5e Wire the schema-driven dashboard and add the .afw firmware package
Dashboard (src/dashboard.rs): the on-box UI now renders from
schema/alkane-bb.json through flare-ui and wschema. The sidebar, the tab strip
and all 20 settings controls come from the schema; the host boundary does what
the crates require - validate the submitted batch with wschema before persisting,
ignore keys that are not in the schema, and never write on a rejected form.
Settings live in /etc/alkane/settings.json (temp dir when the root is read-only).

Web: GET /<section> and /<section>/<tab> render the dashboard, /assets/* serves
the crate's embedded token/component/theme stylesheets, POST /settings applies a
form. The existing JSON API routes are untouched.

Settings wired (all from real runtime knobs): tuning target mode and its four
values, frequency ceiling, the PID gains and limits in milli-units (the schema
has integer kinds only), fan zones/duty/sweep, detection ports and budget,
profile database path, board name.

Tests: 10 dashboard tests (schema loads, all settings present, page renders
inputs, valid submit persists and reloads, out-of-range rejected with nothing
written, unknown keys ignored, percent decoding) plus the existing 162. 172 pass.

Packaging (ci/make-afw.sh): .afw modelled on the Warden .wfw bundle - strict
POSIX ustar, manifest first, payload verified by size and sha256 - with three
deliberate differences: the payload is gzip-compressed, the manifest carries
 and x86_64, and both appear in the file name
(alkane-os-0.1.0-am335x-bb-armv7.afw) so a bundle cannot be mistaken for another
family. Signature is declared  in the manifest until a release key
exists; the sha256 is the only integrity claim today.
2026-11-04 14:06:25 -06:00
x ad31cfbafa Vendor flare-ui v0.2.9 and prove the schema-driven UI in an image
Spike, not the final UI: it answers whether flare-ui can drive Alkane OS's
on-box pages, and what it costs.

What works:

- schema/alkane-bb.json authors the sidebar as data (3 sections, 14 tabs);
- src/bin/ui-spike.rs renders it through flare_ui::nav + flare_ui::shell, so
  the unified sidebar, ordering and surface filtering come from the schema
  rather than from hand-written HTML;
- the render uses the shared bf- design tokens, the same ones the rest of the
  suite uses.

Size, measured rather than assumed (armv7, release, stripped):

  ui-baseline   323 KiB   (maud + serde_json, no flare-ui)
  ui-spike      771 KiB   (flare-ui + wschema + sha2)
  marginal      448 KiB

Vendoring: third-party/flare-ui is the full v0.2.9 tree pinned in
flare-ui/flare-ui.lock (a partial archive does not compile, since the crate
include_str!s assets from dash-editor/). vendor/ is re-generated as a cargo
directory source with the new registry dependencies (maud, sha2, typenum,
digest, generic-array, block-buffer, crypto-common, cfg-if, etc.) so the build
still works offline. third-party/README.md records how to re-pin.
2026-11-04 14:06:25 -06:00
noah 67a33b8221 Gate the OS image payloads against the formats a board can actually boot
The SDK refuses a bad payload before writing it; this is the same rule on the
producing side, so a release cannot ship an image that would not boot or would
not fit the partition it targets.

Checks every payload artefact it can find: magic must match the claimed format
(FDT d00dfeed, legacy uImage 27051956, raw ARM zImage 016f2818 at 0x24) and the
size must fit the partition. Absent artefacts pass with a note, so the gate can
be wired before the first image exists.

Proven both ways: it accepts the four payload files that actually installed
OurOS, and rejects a zImage renamed to the ramdisk slot on size.
2026-11-04 14:06:24 -06:00
noah 13b1787e1a Square corners, a full-screen mobile drawer, and populated settings
The design system retired every radius step on 2026-07-14 (tokens/radius.json
resolves xs..pill to 0), so the cards, buttons, inputs, pills and code blocks
lose their rounded corners.

Below 901px the rail is now the design's mobile menu: a full-screen drawer on
the page background with the brand and a close control in its head, rows split
by 1px dividers. It closes by the X, the backdrop, Escape, or picking a
destination; without a script the :target fragment still opens it.

Settings stops being a bare list: System now groups Identity, Network and
Updates the way the Warden console does, and Drivers groups Chains and
Firmware. Verified on the bench S21 Pro at port 80.
2026-11-04 14:06:24 -06:00
noah 5a6b895113 Style the UI on the FLARE unified rail
Follows the rebuild's design rather than inventing a palette: the 232px navy
rail from portal.css (#192858), its 44px head and appbar, cyan-400 for the
current page and its 2px left marker, 18px stroke icons, 11px uppercase
headings with 2px tracking, and the navy surface/border steps from tokens.css.

Behaviour comes from the same place: one native <details> per group so the tree
opens without a script and the current page's path renders open, a one-item
group rendered as a plain link, aria-current instead of a class, inward focus
rings because the rail scrolls, and an off-canvas rail below 901px reopened by
a :target fragment. A collapse toggle shrinks it to the 40px icon cell and
remembers the choice.

Verified on the bench S21 Pro: the page on port 80 renders the rail with icons
and the open Mining section.
2026-11-04 14:06:24 -06:00
noah 93c47d90ef Add the on-box web UI: sidebar, editable dashboards, settings pages
The UI follows the Warden/FLARE console shape rather than inventing one: a
fixed sidebar of groups and items, hash-routed pages, and dashboards that are a
JSON document an operator edits in place, with a default template per deck and
server-side caps on what a save may contain.

Sections: Dashboard and Mining/Overview are editable dashboards (drag to
reorder, add a block, save, reset). Mining also serves Hashboards, Power Supply
and Fans from the hardware document. Settings serves System, Drivers, Security,
Services, Monitor, Logs, Files and Terminal. Files and Terminal are gated on a
token at /var/lib/alkane/ui-token so a shared network cannot use them.

Served on port 80 of the miner's own address (8080 if 80 cannot be bound), and
started from the runlevel so the page is up without an operator. The JSON API
remains the interface of record: every value shown is also at /api/, and nothing
is reachable only through the page.

Verified: 165 tests, clippy clean, all 13 pages answering, and on the bench S21
Pro the UI answers on port 80 after an unattended reboot.
2026-11-04 14:06:24 -06:00
noah f6af71138c Publish the live operating point every control period
source-pr / source (pull_request) Successful in 12s
A client watching the API during a run saw the boot-time snapshot: status was
published at boot and again when the loop exited, so frequency and voltage were
frozen at their starting values for the whole run. The loop now publishes each
period, which is what makes the UI and the API honest while the machine is
actually mining.
2026-10-22 11:10:32 -06:00
noah 8564ced65d Validate profile databases and make the power check meaningful
source-pr / source (pull_request) Successful in 12s
--check-profiles parses a database and reports schema, count and validation,
so envelope work can be checked before an image ever boots with it. An inverted
envelope is rejected with a non-zero exit.

The conformance power check now sets 500 MHz before reading, because a backend
that always reports 0 W passed a range check while being useless to a
power-target loop. It must now report a plausible non-zero draw at a known
operating point.
2026-10-22 11:08:07 -06:00
noah 78baeb8c31 Add a HAL conformance harness for family backends
source-pr / source (pull_request) Successful in 12s
A family backend is only useful if it answers the contract the OS expects, and
until now the only way to know was to boot a board and watch it fail somewhere
downstream. --check-hal walks the contract in order (capabilities, probe,
EEPROM, PSU, frequency and temperature, power, fan) and reports each check
separately, using a fresh connection per check so one desynchronised exchange
cannot invalidate the rest.

It catches the failure modes that matter for autodetect: a backend that does
not advertise chain probing, one that reports an inverted envelope, one that
returns an implausible temperature or power, and one that cannot accept
frequency or fan commands.
2026-10-22 11:06:22 -06:00
noah a16a4385f8 Drive an SV2 session against a socket pool end to end
source-pr / source (pull_request) Successful in 12s
The codec and session had only ever been tested in memory. This runs the real
path over TCP: the client handshakes, opens a channel, receives SetNewPrevHash
and an active NewMiningJob, submits a share and consumes the acknowledgement,
against a mock pool that speaks the same frames.

It also pins the ordering the protocol depends on: the job is interpreted only
after the prev hash, and the submit sequence starts at one.
2026-10-22 11:03:41 -06:00
noah 79f492e5e8 Make the reference server thermal model fan-aware
source-pr / source (pull_request) Successful in 13s
Zones now respond to the fan that actually cools them (round-robin by zone
index), so the active fan sweep can be demonstrated end to end without
hardware: with two fans and three zones the learned map is fan 0 -> zones 0,2
and fan 1 -> zone 1, persisted to the map file.

The settle interval is configurable (ALKANE_FAN_SETTLE_MS) because the real
twenty-second settle makes an interactive sweep last minutes.
2026-10-22 11:02:02 -06:00
noah b0d81b5d0e Add a reference HAL server and power telemetry
source-pr / source (pull_request) Successful in 13s
The reference server answers the real ALKH contract from a fixed machine
description, so the whole OS path can run on a development host and a backend
author has a concrete example of every opcode. It serves detection, frequency,
fan, temperature and power over one socket.

Power was the missing measurement: a power target could not regulate because
the HAL had no way to report watts, so READ_POWER joins the verbs behind
CAP_POWER. With it, --boot against the reference server settles the loop at
623 MHz for a 2400 W target (4 W per MHz in the model) instead of holding at
the boot frequency.

Fan mapping stays opt-in for --boot (ALKANE_FAN_FANS/ALKANE_FAN_ZONES) because
it perturbs the machine and takes minutes.
2026-10-22 10:59:53 -06:00
noah dccbefc8b7 Add the HAL frequency actuator and a --boot command
source-pr / source (pull_request) Successful in 14s
The tuner produced a frequency the hardware contract had no way to apply, so
detection and tuning could not affect a real board. SET_CHAIN_FREQUENCY joins
the HAL verbs behind its own capability bit, and HalClient refuses to use it
when the backend does not advertise it.

--boot HAL_SOCKET PROFILES.json TARGET [PIC|NOPIC] [TICKS] now runs the real
path: detect over the socket, serve the API and UI, read the hottest sensor,
tick the runtime, apply the frequency to each active chain and the fan duty
when the target owns the fan, then print the published document. A missing
socket exits 1 with a backend error instead of a half-booted miner.
2026-10-22 10:56:43 -06:00
noah 894b22277f Boot over the real HAL contract
source-pr / source (pull_request) Successful in 14s
boot_from_hal connects the board backend, detects through the actual HAL
verbs, runs the one-time fan sweep through the same socket, publishes the
snapshot and returns the runtime and the learned map.

The tests drive it against a mock backend that speaks the real wire protocol
(ALKH framing, CAPABILITIES, PROBE_CHAIN, READ_EEPROM, IDENTIFY_PSU), so the
detection path is exercised end to end rather than assumed, and a missing
socket surfaces as a backend error instead of a half-booted miner.
2026-10-22 10:54:35 -06:00
noah 64e1a9ae2b Report one operating point, not two
source-pr / source (pull_request) Successful in 13s
The live frequency and the boot-time operating point were both in the
hardware document, so a client could read 563 MHz in one field and 300 MHz in
another. The document and the cgminer stats now both derive the operating point
from the live frequency and the envelope, which is also what makes the reported
voltage correct.
2026-10-22 10:51:45 -06:00
noah 2b07d27c67 Pair voltage with frequency across the profile envelope
source-pr / source (pull_request) Successful in 12s
Boards do not run at a fixed voltage across their frequency range, so the
reported operating point was describing a machine that does not exist: the
voltage stayed at the boot value while the tuner moved the frequency.

Envelope::voltage_for interpolates linearly between the profile floor and
ceiling and clamps outside it, and MinerRuntime now reports the voltage that
pairs with the applied frequency. A single-frequency envelope reports its
floor without dividing by zero.
2026-10-22 10:50:56 -06:00
noah 42509a6383 Add a runnable self-check for the boot path
source-pr / source (pull_request) Successful in 12s
alkane-os --self-check drives the whole chain without hardware: parse the
example profile database, detect three BM1362 chains with a dead EEPROM,
identify an APW12, boot the runtime, tick toward a power target and print the
published hardware document. It fails loudly if the profile database does not
parse, detection refuses, the tuner does not move, or the chain set is wrong,
which makes it usable as a bench smoke test on a bare control board.

profiles.example.json is a shape example, not validated hardware data: the
envelopes are placeholders until real captures fill the database.
2026-10-22 10:49:04 -06:00
noah 5048156b74 Persist the learned fan map and reuse it until the hardware changes
source-pr / source (pull_request) Successful in 12s
Mapping fans perturbs the machine, so it is done once and stored. ensure_map
reuses a stored map only when the fan and sensor counts match the current
machine; a mismatch is ignored rather than trusted, because applying a map
learned on four fans to a two-fan machine would mis-control thermals.

The store is a small schema-1 document; corrupt or foreign files are ignored
and trigger a fresh sweep instead of failing the boot.
2026-10-22 10:47:19 -06:00
noah 5a1a7948b1 Add the boot sequence from backend and profiles to runtime
source-pr / source (pull_request) Successful in 12s
app::boot is the sequence a family image runs at start-up: validate the
profile database, detect the hardware through the backend, build the runtime
with the operator target and fault policy, and publish the API snapshot in one
step. It returns the runtime or an explicit BootError, so a refusal is visible
to the caller instead of a half-configured miner.

Target labels are defined once (power:3000, hashrate:200, ambient:20000,
fan:100) so the API, UI and logs cannot drift apart.
2026-10-22 10:45:33 -06:00
noah 2c6535f948 Wire the API and UI through one start-up path
source-pr / source (pull_request) Successful in 12s
Add an app layer that binds and starts the management API and the web UI,
publishes the runtime snapshot, and exposes a bound-address result so callers
can discover ephemeral ports. The binary now uses the same function the tests
use, so the wiring CI exercises is the wiring that runs on a board, and it
gained ALKANE_WEB_LISTEN alongside ALKANE_API_LISTEN.

The snapshot is built from the live runtime: active chains, stop reason and
the last applied frequency rather than the boot default.
2026-10-22 10:43:39 -06:00
noah e3e0dab0ec Add the SV2 TCP link and the V1 fallback policy
source-pr / source (pull_request) Successful in 12s
TcpLink turns a TCP stream into framed SV2 messages: it buffers partial reads
and returns one frame at a time, so a frame split across packets is not a
protocol error and two frames in one read are still delivered separately. A
closed stream is an error, never an empty frame.

The fallback policy permits Stratum V1 only when the operator allowed it and
the failure is not transport-level: a dead route or a dropped stream fails
identically on V1, so falling back there would only delay the real error. V1
failures never loop back to V2.
2026-10-22 10:41:23 -06:00
noah 97ea7a4f65 Add the mining runtime state machine
source-pr / source (pull_request) Successful in 13s
Tie the detection plan, the fault ladder and the tuner together, where their
order is decided: a stopped machine is never tuned, a disabled chain is never
dispatched to, and a missing measurement holds the last command instead of
inventing one.

MinerRuntime exposes the active chain set, the stop reason and an operating
point that reflects the last applied command rather than the boot-time
default, which is what the API snapshot reports.
2026-10-22 10:39:43 -06:00
noah b25d6b2a71 Serve an on-box web UI backed by the JSON API
source-pr / source (pull_request) Successful in 12s
The miner now serves a single page that polls /api/hardware and shows profile,
chip, PSU, operating point, chains and EEPROM state, active chains, target and
whether hashing stopped. The page is a convenience; the API routes it uses are
the interface of record, so a JSON-only client loses nothing.

No framework and no new dependency: the request parser is bounded, only GET is
accepted, responses close the connection and are not cached. MiningStatus now
exposes its hardware and summary documents so the UI and the cgminer-style
server build them once, in one place.
2026-10-22 10:38:07 -06:00
noah 914fb8bef7 Add the Stratum V2 session: handshake, jobs and submissions
source-pr / source (pull_request) Successful in 11s
Drive the client half of an SV2 mining connection: send SetupConnection,
verify the success reply, open a standard channel and remember its id, target
and extranonce prefix. Afterwards the session interprets NewMiningJob,
SetNewPrevHash, SetTarget and share acknowledgements, and submits standard
shares with a monotonic sequence number.

State is explicit rather than assumed: a job that arrives before any
SetNewPrevHash reports no previous hash instead of a zero one, a setup or
channel rejection carries the server's error code, and an unknown message is
ignored instead of killing the session.
2026-10-22 10:36:29 -06:00
noah 6ab645e731 Add the Stratum V2 mining-protocol codec
source-pr / source (pull_request) Successful in 12s
Implement the client half of SV2 as framed messages: the 6-byte header
(extension_type U16, msg_type U8, msg_length U24), SetupConnection and its
success reply, OpenStandardMiningChannel and its success reply, NewMiningJob
with both the active and future ntime forms, SetNewPrevHash and
SubmitSharesStandard.

Field layouts and message identifiers come from the published specification
(03-Protocol-Overview 3.2/3.6, 08-Message-Types, 05-Mining-Protocol 5.3) and
were checked against it rather than recalled. Decoding is strict: truncated
payloads, bad option markers, bad UTF-8 and a non-finite or negative hashrate
are protocol errors, never defaults.
2026-10-22 10:34:44 -06:00
noah b62d64adfb Split hashrate across pools with smooth weighted round-robin
source-pr / source (pull_request) Successful in 12s
Each dispatched work slot comes from exactly one pool, and the router hands
out slots in proportion to the configured weights. Smooth weighted
round-robin is used instead of a plain repeating pattern because it keeps the
mix correct at every prefix: a miner with three chains still gets the intended
ratio in the first three slots, not only after a hundred.

Weights parse from a simple list, a zero-weight pool never receives work, and
malformed configurations (empty, all zero, non-numeric, too many pools) are
refused rather than silently normalised.
2026-10-22 10:32:42 -06:00
noah fe0c2d43ce Expose detection, envelope and tuning state on the management API
source-pr / source (pull_request) Successful in 12s
The cgminer-compatible surface only answered summary and version, which hides
everything detection learned. The API now also answers hardware (profile, chip,
PSU, envelope, operating point, per-chain chip count and EEPROM state, fan
zones, active chains, stop reason, target and live frequency) and stats (the
same data in cgminer's flat STATS shape).

MiningStatus carries an optional HardwareSnapshot behind a mutex, so a client
can tell unavailable apart from an empty machine, and unknown commands still
refuse. Chip models gained a stable API name so the wire strings do not drift
from the enum.
2026-10-22 10:30:49 -06:00
noah 96f84dc283 Add the ambient-temperature and max-fan tuning targets
source-pr / source (pull_request) Successful in 12s
Ambient mode holds the hottest sensor a configured margin above the measured
intake temperature, which is the efficiency-at-this-ambient operating point;
missing either sensor is an error rather than a guess. Max-fan mode pins the
fan at its cap, ramps frequency toward the envelope ceiling, and still defers
to the thermal guard.

step() now returns a Command carrying the frequency and, when the target owns
the fan, the duty to apply. The max-fan ramp is explicit rather than a
setpoint loop: a P controller fed its own output settles at half the ceiling,
which the ramp test caught.
2026-10-22 10:28:53 -06:00
noah 5aa6349e27 Add adaptive PID tuning with a thermal derate guard
source-pr / source (pull_request) Successful in 12s
Replace preset tuning with a bounded controller: a PID over chain frequency
that targets a DC power draw or a hashrate, inside the profile envelope. The
controller rate-limits its output, ignores errors inside a deadband, takes the
derivative on the measurement so a setpoint change does not kick it, and uses
conditional integration so a saturated actuator does not wind the integral up.

A thermal guard runs before the target logic: any sensor at or above the
ceiling derates the frequency regardless of what the operator asked for, so a
hashrate target can never cook a board.
2026-10-22 10:26:30 -06:00
noah 724b3da478 Add the fault-tolerance escalation ladder
source-pr / source (pull_request) Successful in 12s
The machine should keep hashing with as many dead chips or chains as
possible, so faults escalate in steps instead of stopping at the first one:
a chain error retries up to a policy limit, then the chain is disabled and the
rest keep running; a chip fault disables only that chip; a chain whose nonce
response stays below the policy floor for consecutive windows is disabled; a
temperature fault stops the machine immediately.

Disabling every chain stops with NoChainsLeft rather than leaving the miner
spinning on an empty active set. The supervisor owns no hardware and no
thermal limits; those come from the profile envelope.
2026-10-22 10:24:38 -06:00
noah ef399d0ca5 Drive fan probing through the HAL client
source-pr / source (pull_request) Successful in 12s
HalClient implements FanProbe, so the measurement sweep runs against a real
board over the same local contract: set_fan maps to SET_FAN_TARGET and
read_zone maps to READ_TEMPERATURE. The wire round-trip test now exercises
both fan verbs through the mock backend.
2026-10-22 10:22:52 -06:00
noah 4139576155 Add the fan-mapping measurement sweep
source-pr / source (pull_request) Successful in 11s
sweep() drives the probing run that map_fans consumes: it moves one fan at a
time between the low and high duty while the others hold their setting, waits
for the settle interval, and records every zone reading. Repeat readings are
emitted so the mapper averages noise.

Safety is enforced in the loop, not by convention: a probe duty below the
minimum, an empty duty range, an inverted range, zero reads and zero fans are
all refused before any fan is touched, and the run always ends with every fan
restored to the high duty so the machine is not left under-cooled.
2026-10-22 10:21:26 -06:00
noah c616429669 Map fans to thermal zones by active probing
source-pr / source (pull_request) Successful in 11s
Fans are not labeled by the hardware: a fan can cool one hashboard heavily
and another barely, and front/back top/bottom is physical. map_fans learns the
map from a stepped run: for every fan compare zone temperatures at the lowest
and highest duty, then give each zone to the fan with the strongest cooling
response.

A response must clear min_drop_mc and beat the runner-up by
min_margin_per_mille, otherwise the zone is reported unresolved rather than
guessed, so a noisy run cannot invent a map. One fan may own several zones,
and a fan with no duty range contributes no evidence.
2026-10-22 10:19:45 -06:00
noah 9ed94bd01f Add the profile database and the end-to-end detection driver
source-pr / source (pull_request) Successful in 12s
Profiles carry the only envelopes detection may use, so a combination absent
from the database is refused rather than guessed. The schema-1 document is
validated on load: unknown chips or sensor wiring, inverted or zero envelopes,
zero chain counts and duplicate names are all rejected.

run_detection now ties the pieces together: probe every declared port, select
a profile by chip, sensor wiring and physical port count, identify the PSU, and
emit a HardwarePlan. A machine with a dead chain still matches its three-chain
profile and runs degraded instead of being reclassified; plan() now tolerates
unidentified chains and refuses only when nothing identified.

The detection backend contract gains identify_psu(), and HalClient answers it
through the new HAL verb.
2026-10-22 10:17:34 -06:00
noah 3028ef29fb Carry detection verbs over the HAL wire contract
source-pr / source (pull_request) Successful in 12s
Add capability negotiation and three detection verbs to the local HAL
contract: CAPABILITIES, PROBE_CHAIN, READ_EEPROM and IDENTIFY_PSU. A backend
that predates them rejects the capability query, which surfaces as a protocol
error instead of a silent zero. HalClient implements ChainProbe, so the OS
detection driver can run against a real board without knowing the family.

The probe contract is now error-aware: a transport failure propagates as an
error and is never reported as a silent port, and probe_chain/detect_chains
are generic over the backend. A wire round-trip test drives a mock backend
over a socket pair and checks the encoding of all three verbs.
2026-10-22 10:15:29 -06:00
noah 99fb12d725 Add chain probing policy to the detection core
source-pr / source (pull_request) Successful in 12s
Define the backend contract for identification (ChainProbe) with a bounded
ProbeBudget and a ProbeOutcome that distinguishes an identified chain from a
silent port and from unframed bytes. probe_chain retries a chain until it
identifies or the budget is spent, and reports an exhausted chain as an
unknown chip instead of dropping it; detect_chains walks every declared port.

Framing and baud switching stay in the per-family SDK backend. Tests cover
retry-until-identified, budget exhaustion, EEPROM state retention and the
refusal path when a chain never identifies.
2026-10-22 10:13:18 -06:00
noah 367f07d956 Add hardware detection plan model
source-pr / source (pull_request) Successful in 14s
Introduce the detection core data model: chain observations, board profile
and PSU envelopes, envelope intersection, and a conservative operating point
when the hardware is not confirmed by an EEPROM. Refusal is explicit for
unknown chips, missing PSUs and empty envelopes, and degraded chains are
reported rather than fatal.
2026-10-22 10:11:52 -06:00
noah 29749fee4a Merge pull request 'Name each Alkane evidence milestone without promoting claims' (#13) from tooling/evidence-levels into next
next-build / build (push) Successful in 26s
2026-10-21 07:50:26 -06:00
noah 1f558ef596 Name each Alkane evidence milestone without promoting claims
source-pr / source (pull_request) Successful in 58s
2026-10-21 07:48:45 -06:00
noah 576f834169 Merge pull request 'Separate research evidence and speed scoped OS PR checks' (#12) from tooling/lab-evidence-ci into next
next-build / build (push) Successful in 38s
2026-10-21 07:40:53 -06:00
noah 093cb62212 Separate research evidence and speed scoped OS PR checks
source-pr / source (pull_request) Successful in 10s
2026-10-21 07:38:30 -06:00
noah e928140351 Merge pull request 'Isolate trusted OS jobs from fast runner' (#11) from ci/isolate-fast-runner-main into main
main-release-gate / verify-and-release (push) Failing after 2m45s
2026-10-20 18:56:43 -06:00
noah 2e42bedb84 Merge pull request 'Route trusted OS next jobs to verifier' (#10) from ci/isolate-fast-runner-next into next
next-build / build (push) Successful in 29s
2026-10-20 18:56:41 -06:00
noah c424f7e192 Isolate trusted OS jobs from fast runner
source-pr / source (pull_request) Successful in 48s
2026-10-20 18:45:04 -06:00
noah 0b785eebb5 Route trusted OS next jobs to verifier
source-pr / source (pull_request) Successful in 57s
2026-10-20 18:45:04 -06:00
noah 885a71b6fe Merge pull request 'Preserve queued OS merge builds and guard reruns' (#9) from ci/preserve-next-runs into next
next-build / build (push) Successful in 42s
2026-10-19 14:46:44 -06:00
noah 8672507fa4 Preserve queued OS merge builds and guard reruns
source-pr / source (pull_request) Successful in 42s
2026-10-19 14:45:35 -06:00
noah 37f1f8433b Merge pull request 'Route short OS builds to Alkane fast runner' (#8) from ci/route-os-fast-runner into next
next-build / build (push) Successful in 25s
2026-10-19 14:43:50 -06:00
noah b703c757e4 Route short OS builds to Alkane fast runner
source-pr / source (pull_request) Successful in 29s
2026-10-19 14:42:54 -06:00
noah 98d891fc67 Merge pull request 'Expose observed BM1370 work ID correlation' (#7) from feature/bm1370-work-id into next
next-build / build (push) Canceled after 0s
2026-10-19 14:35:26 -06:00
noah d6e043d79f Expose observed BM1370 work ID correlation
source-pr / source (pull_request) Successful in 10s
2026-10-19 13:48:13 -06:00
noah ba286758c7 Merge BM1370 captured wire primitives
next-build / build (push) Successful in 13s
Pure Rust framing; chain, work attribution, and pool acceptance remain open.
2026-10-19 12:17:42 -06:00
noah b65e6bc9f1 Install rustfmt in Alkane OS pull request job
source-pr / source (pull_request) Successful in 12s
2026-10-19 12:15:30 -06:00
noah f7aeeaa2eb Run protected Alkane OS source checks on pull requests
source-pr / source (pull_request) Failing after 5s
2026-10-19 12:12:48 -06:00
noah 1b0607cbd8 Add capture-checked BM1370 wire primitives 2026-10-19 12:11:00 -06:00
noah ae7745772a Merge pull request 'Use prebuilt CI tools on all Alkane OS runners' (#5) from ci/prebuilt-ci-tools into main
main-release-gate / verify-and-release (push) Failing after 3m32s
2026-10-18 22:30:22 -06:00
noah 28af64daa5 Pin prebuilt CI tools for every OS job
source-pr / source (pull_request) Successful in 45s
2026-10-18 22:28:54 -06:00
noah 871a2cd3f7 Merge pull request 'Pin OS jobs to the shared Alkane runner image' (#4) from ci/pin-runner-image into main
main-release-gate / verify-and-release (push) Failing after 3m18s
2026-10-18 21:41:54 -06:00
noah 322766cf63 Pin OS jobs to shared Alkane runner image
source-pr / source (pull_request) Successful in 42s
2026-10-18 21:21:33 -06:00
noah c13db2a5ba Merge pull request 'Save coverage tool before conformance gate' (#3) from ci/coverage-cache-early-save into main
main-release-gate / verify-and-release (push) Failing after 5m24s
2026-10-18 21:11:53 -06:00
noah 7c361aecd9 Invalidate ASIC work when pool version mask changes
next-build / build (push) Successful in 21s
2026-10-17 06:05:03 -06:00
noah 212c9198eb docs: shorten OS entry guide
next-build / build (push) Successful in 19s
2026-10-17 01:42:42 -06:00
noah be0a57a1d9 Publish benchmark Pages on the standing Alkane runner
next-build / build (push) Successful in 15s
2026-10-17 01:17:56 -06:00
noah 8bdcd8fb83 Pin benchmark Pages SSH host key
next-build / build (push) Successful in 15s
2026-10-17 01:05:04 -06:00
noah 885a4571ff Make wrong-sequence HAL test stop after rejected header
next-build / build (push) Successful in 12s
2026-10-16 23:02:56 -06:00
noah e746efcb94 Bound management request lifetime
next-build / build (push) Successful in 12s
2026-10-16 21:04:27 -06:00
noah 16c9d4962a Add local read-only mining status API
next-build / build (push) Canceled after 0s
2026-10-16 21:03:40 -06:00
noah 283287f74f Benchmark captured BM1366 report poll path
next-build / build (push) Canceled after 0s
2026-10-16 17:02:10 -06:00
noah 98f3eb75c0 Benchmark BM13xx protocol checksums
next-build / build (push) Canceled after 0s
2026-10-16 14:06:25 -06:00
noah 853cb845ff Benchmark HAL and Stratum socket exchanges
next-build / build (push) Canceled after 0s
2026-10-16 11:06:59 -06:00
noah e9a3c3a669 Benchmark BM1362 work and Stratum handshake paths
next-build / build (push) Canceled after 0s
2026-10-16 09:02:45 -06:00
noah 895081e509 Validate public benchmark page before upload
next-build / build (push) Canceled after 0s
2026-10-16 08:47:19 -06:00
noah b76b74cb63 Describe selected BM13xx host mining formats
next-build / build (push) Canceled after 0s
2026-10-16 08:12:51 -06:00
noah 289ad40d86 Select BM1362 work encoding for captured replay
next-build / build (push) Canceled after 0s
2026-10-16 08:11:46 -06:00
noah f0c9d4d904 Set captured midstate count in BM1366 work
next-build / build (push) Canceled after 0s
2026-10-16 08:03:40 -06:00
noah f6b5df831e Publish OS benchmarks to public Pages site
next-build / build (push) Canceled after 0s
2026-10-16 07:19:41 -06:00
noah d1d7c576cf Bound queued OS CI attempts per branch
next-build / build (push) Canceled after 0s
2026-10-16 07:08:18 -06:00
noah 8d19cdeae6 Schedule CI badge refresh without workflow recursion
next-build / build (push) Successful in 18s
2026-10-16 07:03:17 -06:00
noah 52e6093011 Require complete OS microbenchmark measurements
next-build / build (push) Successful in 18s
2026-10-16 05:02:08 -06:00
noah 7fd9c8eee3 Keep buffered Stratum partial line deadline across drains
next-build / build (push) Successful in 13s
2026-10-16 04:01:56 -06:00
noah f302bbbb24 Attach OS quality gate evidence to metrics
next-build / build (push) Successful in 14s
2026-10-16 02:06:01 -06:00
noah b22b494ede Grade OS code quality from static checks
next-build / build (push) Successful in 15s
2026-10-16 02:02:53 -06:00
noah 6c23ce847d Coalesce pending CI badge updates
next-build / build (push) Successful in 15s
2026-10-16 01:02:52 -06:00
noah 6a466a611f Reject invalid BM1362 geometry and baud requests
next-build / build (push) Successful in 18s
2026-10-15 22:07:45 -06:00
noah 1300d7e372 Benchmark BM1362 frame encoding
next-build / build (push) Successful in 18s
2026-10-15 22:06:01 -06:00
noah 66e4f3d47a Add Rust BM1362 wire frame encoders
next-build / build (push) Successful in 18s
2026-10-15 22:04:07 -06:00
noah 37028cc3eb Verify Litecoin Scrypt shares in conformance gate
next-build / build (push) Successful in 18s
2026-10-15 21:05:08 -06:00
noah 0e6fd9269b Add simulator mining command to Alkane OS
next-build / build (push) Canceled after 0s
2026-10-15 18:22:49 -06:00
noah 3d63bbb3eb Set Rust-first core implementation policy
next-build / build (push) Canceled after 0s
2026-10-15 14:46:30 -06:00
noah 5d8f14c992 Shorten OS README to scope and release gates
next-build / build (push) Canceled after 0s
2026-10-15 14:37:04 -06:00
noah 6f87f48dca Document miner work ID and shutdown guards
next-build / build (push) Successful in 10s
2026-10-15 13:04:51 -06:00
noah 7d398caa66 Reserve ASIC work IDs until hardware flush and fault on failed shutdown
next-build / build (push) Successful in 16s
2026-10-15 13:04:14 -06:00
noah 96dd7bf6d2 Clean OS CI outputs after build and release
next-build / build (push) Canceled after 0s
2026-10-15 11:48:14 -06:00
noah 59249d44d3 Verify BM1362 capture through shared miner work path
next-build / build (push) Canceled after 0s
2026-10-15 05:50:00 -06:00
noah f011557cd5 Add MIT Litecoin Scrypt share verifier
next-build / build (push) Canceled after 0s
2026-10-15 04:56:39 -06:00
noah d52996c02a Accept captured BM1362 share through strict pool
next-build / build (push) Canceled after 0s
2026-10-15 04:28:46 -06:00
noah b59aa8d9c1 Verify BM1362 captured share through HAL replay
next-build / build (push) Canceled after 0s
2026-10-15 04:20:29 -06:00
noah 523ec5fd0b Replay 33 captured BM1366 shares through pool
next-build / build (push) Canceled after 0s
2026-10-15 04:11:00 -06:00
noah a1d8e34390 Flush ASIC work before recycling job IDs
next-build / build (push) Canceled after 0s
2026-10-15 03:55:13 -06:00
noah 2d6233cdc7 Verify captured BM1366 share through strict pool replay
next-build / build (push) Canceled after 0s
2026-10-15 03:47:59 -06:00
noah eb9dcf830b Calibrate microbenchmarks and measure quality grade
next-build / build (push) Canceled after 0s
2026-10-15 03:17:58 -06:00
noah af49d4905d Require Git tag for completed release
next-build / build (push) Canceled after 0s
2026-10-15 03:09:11 -06:00
noah 8fa9e5d9e6 Bind share evidence to Stratum work and improve pool polling
next-build / build (push) Canceled after 0s
2026-10-15 03:07:16 -06:00
noah 492fe68c9e Verify release artifacts and keep uploads draft until complete
next-build / build (push) Canceled after 0s
2026-10-15 02:49:03 -06:00
noah f215cb3196 Fail closed on pool and HAL faults and bind release evidence to CI run
next-build / build (push) Canceled after 0s
2026-10-15 02:33:33 -06:00
noah 6e3b798273 Cross-check release evidence against built target matrix
next-build / build (push) Canceled after 0s
2026-10-15 02:16:34 -06:00
noah 16b55b58e3 Bound pool share replies and advance mining cycle
next-build / build (push) Canceled after 0s
2026-10-15 02:12:19 -06:00
noah 90a2fe12d5 Track pool jobs and share replies in connection
next-build / build (push) Canceled after 0s
2026-10-15 01:56:55 -06:00
noah bc38a4a787 Negotiate pool extensions and authorize over bounded transport
next-build / build (push) Canceled after 0s
2026-10-15 01:44:12 -06:00
noah 654b205e00 Add bounded Stratum TCP transport and request frames
next-build / build (push) Canceled after 0s
2026-10-15 01:31:33 -06:00
noah ece32ef55f Track Stratum jobs across ASIC work IDs
next-build / build (push) Canceled after 0s
2026-10-15 01:16:19 -06:00
noah 5cd77eb5de Convert pool difficulty to exact share targets
next-build / build (push) Successful in 11s
2026-10-15 01:00:53 -06:00
noah e7a23faa5a Decode Stratum pool control notifications
next-build / build (push) Canceled after 0s
2026-10-15 00:49:35 -06:00
noah e0f9b1ab50 Vendor pinned Rust dependencies for offline SDK builds
next-build / build (push) Canceled after 0s
2026-10-15 00:15:24 -06:00
noah 323e45ab0e Decode bounded Stratum V1 pool jobs
next-build / build (push) Canceled after 0s
2026-10-15 00:05:19 -06:00
noah 6fd329e047 Format mask-checked Stratum V1 share submissions
next-build / build (push) Canceled after 0s
2026-10-15 00:00:22 -06:00
noah 7d602d2f03 Keep in-flight ASIC work across pool job changes
next-build / build (push) Canceled after 0s
2026-10-14 20:57:56 -06:00
noah 78b9416985 Use Gitea-compatible pinned artifact uploads
next-build / build (push) Canceled after 0s
2026-10-14 20:51:16 -06:00
noah d2afef19a9 Construct SHA-256 Stratum work headers for BM1366
next-build / build (push) Canceled after 0s
2026-10-14 20:24:34 -06:00
noah e67ffcd204 Record private per-commit OS benchmark history
next-build / build (push) Canceled after 0s
2026-10-14 20:17:31 -06:00
noah 6cf9ed1620 Publish measured OS badges to private branch
next-build / build (push) Canceled after 0s
2026-10-14 20:11:09 -06:00
noah 4f21677ae5 Ignore cancelled runs in completed CI badge
next-build / build (push) Canceled after 0s
2026-10-14 19:58:25 -06:00
noah 9f7d8ebb51 Add fail-safe BM1366 mining session
next-build / build (push) Canceled after 0s
2026-10-14 19:53:40 -06:00
noah 81d726cca2 Publish branch badges from completed CI runs
next-build / build (push) Successful in 11s
2026-10-14 19:47:07 -06:00
noah 74ba049b5c Add reusable BM1366 work and report codec
next-build / build (push) Successful in 10s
2026-10-14 19:43:06 -06:00
noah 46a4f58019 Verify captured ASIC shares and probe SDK simulator
next-build / build (push) Successful in 13s
2026-10-14 19:37:38 -06:00
noah e9d7200a05 Keep bounded HAL connections dependency free
next-build / build (push) Canceled after 0s
2026-10-14 19:19:37 -06:00
noah 544711885e Bound HAL socket exchanges and validate errors
next-build / build (push) Canceled after 0s
2026-10-14 19:17:12 -06:00
noah 7d3cebea79 Add versioned SDK HAL socket client
next-build / build (push) Canceled after 0s
2026-10-14 19:10:17 -06:00
noah 1ce22d9d9f Merge branch 'main' into next
next-build / build (push) Successful in 9s
2026-10-13 11:59:47 -06:00
noah 4eef88b5df Point next CI badge at next attempts
next-build / build (push) Successful in 8s
2026-10-13 11:46:20 -06:00
3571 changed files with 1289137 additions and 36 deletions
+7
View File
@@ -0,0 +1,7 @@
2026-11-10T21:41:18-06:00 1 17293278c1c7 src/web.rs 320 Medium files/file endpoints not token-gated (fixed)
2026-11-10T21:41:18-06:00 1 073768bc5201 src/web.rs 389 Medium settings redirect header-splitting via __section/__tab (fixed)
2026-11-10T21:41:18-06:00 1 d45a2e52d1ba src/auth.rs 37 Medium RNG fallback to constant csrf/guessable wsid (fixed)
2026-11-10T21:41:18-06:00 1 b6701ede5237 src/dashboard.rs 199 Medium settings write error swallowed, reported success (fixed)
2026-11-10T21:41:18-06:00 1 1b4915d2c7a6 src/tuning.rs 180 Low set_target kept PID integral across unit-mismatched modes (fixed)
2026-11-10T21:41:18-06:00 1 97ba434fdd3a src/console.rs 234 Medium editable-deck new-block id collision (fixed)
2026-11-10T21:41:18-06:00 1 0a2a1950ad0d src/web.rs 81 Medium unbounded thread-per-connection DoS (fixed: conn cap)
+44
View File
@@ -0,0 +1,44 @@
# Code Review Memory
This file is maintained by the `code-review-harness` skill. It records
findings across review sessions so the skill can spot recurring issues
and apply more aggressive remediation when an issue persists.
The skill **reads this file at the start of every review** and **updates
it at the end** with new findings.
## How to use
- The "Recurring Issues" section is rebuilt automatically each run. Treat
it as the high-signal list of things that keep coming back.
- The "Session Log" is append-only. Each row is one finding from one
session. The log is the source of truth; the index is derived from it.
- If a finding has been fixed and you don't want it to count toward
recurrence anymore, add a `RESOLVED:` row referencing the finding
fingerprint.
## Recurring Issues
_(auto-generated — rebuilt at end of each session)_
<!-- BEGIN RECURRING -->
_No recurring issues yet — every finding has been a one-off, or memory was just initialized._
<!-- END RECURRING -->
## Session Log
_(append-only)_
<!-- BEGIN LOG -->
- `2026-11-10T21:41:18-06:00` iter=1 `src/web.rs:320` [Medium] files/file endpoints not token-gated (fixed) (fp:17293278c1c7)
- `2026-11-10T21:41:18-06:00` iter=1 `src/web.rs:389` [Medium] settings redirect header-splitting via __section/__tab (fixed) (fp:073768bc5201)
- `2026-11-10T21:41:18-06:00` iter=1 `src/auth.rs:37` [Medium] RNG fallback to constant csrf/guessable wsid (fixed) (fp:d45a2e52d1ba)
- `2026-11-10T21:41:18-06:00` iter=1 `src/dashboard.rs:199` [Medium] settings write error swallowed, reported success (fixed) (fp:b6701ede5237)
- `2026-11-10T21:41:18-06:00` iter=1 `src/tuning.rs:180` [Low] set_target kept PID integral across unit-mismatched modes (fixed) (fp:1b4915d2c7a6)
- `2026-11-10T21:41:18-06:00` iter=1 `src/console.rs:234` [Medium] editable-deck new-block id collision (fixed) (fp:97ba434fdd3a)
- `2026-11-10T21:41:18-06:00` iter=1 `src/web.rs:81` [Medium] unbounded thread-per-connection DoS (fixed: conn cap) (fp:0a2a1950ad0d)
<!-- END LOG -->
+3 -1
View File
@@ -12,7 +12,9 @@ concurrency:
jobs:
publish:
runs-on: alkane-pages
runs-on: alkane-ci
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:ad56db2fc456a3f1c68c715ba44309751cb5c455376d9f797ac346833c011e15
permissions:
contents: read
steps:
+3 -1
View File
@@ -12,7 +12,9 @@ concurrency:
jobs:
publish:
runs-on: alkane-fast
runs-on: alkane-ci
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:ad56db2fc456a3f1c68c715ba44309751cb5c455376d9f797ac346833c011e15
permissions:
actions: read
contents: write
+24 -2
View File
@@ -11,7 +11,9 @@ concurrency:
jobs:
source:
runs-on: alkane-fast
runs-on: alkane-ci
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:ad56db2fc456a3f1c68c715ba44309751cb5c455376d9f797ac346833c011e15
env:
CARGO_TARGET_DIR: target
CARGO_BUILD_JOBS: 2
@@ -19,6 +21,8 @@ jobs:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Check runner image pins
run: python3 ci/check-runner-image.py
- name: Detect README-only change
id: surface
run: |
@@ -35,7 +39,7 @@ jobs:
if: steps.surface.outputs.surface == 'documentation'
run: |
base="$(git merge-base HEAD "origin/$GITHUB_BASE_REF")"
git diff --check "$base" HEAD
git diff --check "$base" HEAD -- . ':(exclude)vendor' ':(exclude)third-party'
if git grep -nIE '^[[:space:]]*-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----[[:space:]]*$' --; then
echo "private key material found in tracked source" >&2
exit 1
@@ -43,6 +47,24 @@ jobs:
status=$?
[ "$status" -eq 1 ]
fi
- name: Check patch whitespace
if: steps.surface.outputs.surface != 'documentation'
run: |
# Vendored crates (vendor/) and the flare-ui source (third-party/) keep
# their upstream bytes (cargo vendor checksums, byte-exact fixtures).
if [ "$GITHUB_EVENT_NAME" = pull_request ]; then
base="$(git merge-base HEAD "origin/$GITHUB_BASE_REF")"
git diff --check "$base" HEAD -- . ':(exclude)vendor' ':(exclude)third-party'
else
git diff --check HEAD^ HEAD -- . ':(exclude)vendor' ':(exclude)third-party'
fi
- name: Check CI and evidence tools
if: steps.surface.outputs.surface != 'documentation'
run: |
python3 -m compileall -q ci
for test in ci/test-*.py; do python3 "$test"; done
python3 ci/evidence_status.py
python3 ci/experiment_priority.py
- name: Check source
if: steps.surface.outputs.surface != 'documentation'
run: |
+19 -17
View File
@@ -11,6 +11,8 @@ concurrency:
jobs:
verify-and-release:
runs-on: alkane-ci
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:ad56db2fc456a3f1c68c715ba44309751cb5c455376d9f797ac346833c011e15
env:
CARGO_TARGET_DIR: target
permissions:
@@ -28,6 +30,10 @@ jobs:
fi
- name: Install Rust quality tools
run: rustup component add rustfmt clippy
- name: Image safety gate
run: sh ci/check-image-safety.sh
- name: .afw format tests
run: python3 ci/test-afw.py
- name: Formatting
run: cargo fmt --check
- name: Last-attempt badge checks
@@ -38,8 +44,15 @@ jobs:
run: python3 ci/test-metrics.py
- name: Release evidence gate checks
run: python3 ci/test-conformance.py
- name: Research and experiment report checks
run: |
python3 ci/test-evidence-status.py
python3 ci/test-experiment-priority.py
python3 ci/test-pr-surface.py
- name: Release publication checks
run: python3 ci/test-release.py
- name: Release version checks
run: python3 ci/test-version.py
- name: CI cleanup containment checks
run: python3 ci/test-cleanup-generated.py
- name: Quality
@@ -56,27 +69,10 @@ jobs:
run: |
set -o pipefail
cargo test --release --locked -- --ignored --nocapture --test-threads=1 | tee bench-current.txt
- name: Restore coverage tool
id: coverage-cache
uses: actions/cache/restore@v4
continue-on-error: true
with:
path: /root/.cargo/bin/cargo-llvm-cov
key: cargo-llvm-cov-0.8.7-rust-1.97.1-${{ runner.os }}
- name: Coverage tool
run: |
rustup component add llvm-tools-preview
if [ "$(cargo llvm-cov --version 2>/dev/null || true)" != 'cargo-llvm-cov 0.8.7' ]; then
cargo install --locked --force cargo-llvm-cov --version 0.8.7
fi
[ "$(cargo llvm-cov --version)" = 'cargo-llvm-cov 0.8.7' ]
- name: Save coverage tool
if: steps.coverage-cache.outputs.cache-hit != 'true'
uses: actions/cache/save@v4
continue-on-error: true
with:
path: /root/.cargo/bin/cargo-llvm-cov
key: cargo-llvm-cov-0.8.7-rust-1.97.1-${{ runner.os }}
- name: Unit test coverage
run: |
mkdir -p coverage
@@ -116,6 +112,12 @@ jobs:
with:
name: alkane-os-benchmark-site-preview
path: bench-site/index.html
- name: Separate research from release evidence
run: python3 ci/evidence_status.py --output evidence-status-current.json
- uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
with:
name: alkane-os-evidence-status
path: evidence-status-current.json
- name: Pairing and simulator conformance
run: python3 ci/check-conformance.py
- name: Select release version
+8 -2
View File
@@ -10,7 +10,9 @@ concurrency:
jobs:
build:
runs-on: alkane-fast
runs-on: alkane-ci
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:ad56db2fc456a3f1c68c715ba44309751cb5c455376d9f797ac346833c011e15
env:
CARGO_TARGET_DIR: target
CARGO_BUILD_JOBS: 2
@@ -18,8 +20,12 @@ jobs:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Image safety gate
run: sh ci/check-image-safety.sh
- name: .afw format tests
run: python3 ci/test-afw.py
- name: Build release candidate
run: cargo build --release --locked
run: cargo build --release --offline --locked
- name: Select candidate version
id: version
run: python3 ci/version.py next >> "$GITHUB_OUTPUT"
Generated
+444 -1
View File
@@ -2,11 +2,246 @@
# It is not intended for manual editing.
version = 4
[[package]]
name = "aho-corasick"
version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
dependencies = [
"memchr",
]
[[package]]
name = "alkane-os"
version = "0.1.0"
dependencies = [
"flare-ui",
"maud",
"serde_json",
"wschema",
]
[[package]]
name = "anes"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"
[[package]]
name = "anstyle"
version = "1.0.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
[[package]]
name = "autocfg"
version = "1.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
[[package]]
name = "block-buffer"
version = "0.10.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
dependencies = [
"generic-array",
]
[[package]]
name = "cast"
version = "0.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"
[[package]]
name = "cfg-if"
version = "1.0.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
[[package]]
name = "ciborium"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "42e69ffd6f0917f5c029256a24d0161db17cea3997d185db0d35926308770f0e"
dependencies = [
"ciborium-io",
"ciborium-ll",
"serde",
]
[[package]]
name = "ciborium-io"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "05afea1e0a06c9be33d539b876f1ce3692f4afea2cb41f740e7743225ed1c757"
[[package]]
name = "ciborium-ll"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "57663b653d948a338bfb3eeba9bb2fd5fcfaecb9e199e87e1eda4d9e8b240fd9"
dependencies = [
"ciborium-io",
"half",
]
[[package]]
name = "clap"
version = "4.6.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "aa8876b300ab35ba921adea3dfd70157a46249b33f95c9084ae5709785478946"
dependencies = [
"clap_builder",
]
[[package]]
name = "clap_builder"
version = "4.6.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ec0797fb7aeb1406c84efac526901f7ec3ead2124f946b494e72879d4b54704d"
dependencies = [
"anstyle",
"clap_lex",
]
[[package]]
name = "clap_lex"
version = "1.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1c133bc6a41be0d194c306b5506d15e6feeea7b1d6604bd3f8310dfb2ca96486"
[[package]]
name = "cpufeatures"
version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
dependencies = [
"libc",
]
[[package]]
name = "criterion"
version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f"
dependencies = [
"anes",
"cast",
"ciborium",
"clap",
"criterion-plot",
"is-terminal",
"itertools",
"num-traits",
"once_cell",
"oorandom",
"regex",
"serde",
"serde_derive",
"serde_json",
"tinytemplate",
"walkdir",
]
[[package]]
name = "criterion-plot"
version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"
dependencies = [
"cast",
"itertools",
]
[[package]]
name = "crunchy"
version = "0.2.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
[[package]]
name = "crypto-common"
version = "0.1.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
dependencies = [
"generic-array",
"typenum",
]
[[package]]
name = "digest"
version = "0.10.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
dependencies = [
"block-buffer",
"crypto-common",
]
[[package]]
name = "either"
version = "1.19.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
[[package]]
name = "flare-ui"
version = "0.0.1"
dependencies = [
"criterion",
"maud",
"serde_json",
"wschema",
]
[[package]]
name = "generic-array"
version = "0.14.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
dependencies = [
"typenum",
"version_check",
]
[[package]]
name = "half"
version = "2.7.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
dependencies = [
"cfg-if",
"crunchy",
"zerocopy",
]
[[package]]
name = "hermit-abi"
version = "0.5.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e17592d60ebacc7d5e169f4663c5f84f9161cc90328abcfe8456f41e4dfcb284"
[[package]]
name = "is-terminal"
version = "0.4.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
dependencies = [
"hermit-abi",
"libc",
"windows-sys",
]
[[package]]
name = "itertools"
version = "0.10.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473"
dependencies = [
"either",
]
[[package]]
@@ -15,12 +250,61 @@ version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "libc"
version = "0.2.191"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
[[package]]
name = "maud"
version = "0.27.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8156733e27020ea5c684db5beac5d1d611e1272ab17901a49466294b84fc217e"
dependencies = [
"itoa",
"maud_macros",
]
[[package]]
name = "maud_macros"
version = "0.27.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7261b00f3952f617899bc012e3dbd56e4f0110a038175929fa5d18e5a19913ca"
dependencies = [
"proc-macro2",
"proc-macro2-diagnostics",
"quote",
"syn 2.0.119",
]
[[package]]
name = "memchr"
version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
[[package]]
name = "num-traits"
version = "0.2.19"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
dependencies = [
"autocfg",
]
[[package]]
name = "once_cell"
version = "1.21.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
[[package]]
name = "oorandom"
version = "11.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
[[package]]
name = "proc-macro2"
version = "1.0.107"
@@ -30,6 +314,18 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "proc-macro2-diagnostics"
version = "0.10.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "af066a9c399a26e020ada66a034357a868728e72cd426f3adcd35f80d88d88c8"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
"version_check",
]
[[package]]
name = "quote"
version = "1.0.47"
@@ -39,6 +335,44 @@ dependencies = [
"proc-macro2",
]
[[package]]
name = "regex"
version = "1.13.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
dependencies = [
"aho-corasick",
"memchr",
"regex-automata",
"regex-syntax",
]
[[package]]
name = "regex-automata"
version = "0.4.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
dependencies = [
"aho-corasick",
"memchr",
"regex-syntax",
]
[[package]]
name = "regex-syntax"
version = "0.8.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
[[package]]
name = "same-file"
version = "1.0.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
dependencies = [
"winapi-util",
]
[[package]]
name = "serde"
version = "1.0.229"
@@ -46,6 +380,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
dependencies = [
"serde_core",
"serde_derive",
]
[[package]]
@@ -65,7 +400,7 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
dependencies = [
"proc-macro2",
"quote",
"syn",
"syn 3.0.9",
]
[[package]]
@@ -81,6 +416,28 @@ dependencies = [
"zmij",
]
[[package]]
name = "sha2"
version = "0.10.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
dependencies = [
"cfg-if",
"cpufeatures",
"digest",
]
[[package]]
name = "syn"
version = "2.0.119"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
dependencies = [
"proc-macro2",
"quote",
"unicode-ident",
]
[[package]]
name = "syn"
version = "3.0.9"
@@ -92,12 +449,98 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "tinytemplate"
version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "be4d6b5f19ff7664e8c98d03e2139cb510db9b0a60b55f8e8709b689d939b6bc"
dependencies = [
"serde",
"serde_json",
]
[[package]]
name = "typenum"
version = "1.20.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
[[package]]
name = "unicode-ident"
version = "1.0.27"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
[[package]]
name = "version_check"
version = "0.9.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
[[package]]
name = "walkdir"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
dependencies = [
"same-file",
"winapi-util",
]
[[package]]
name = "winapi-util"
version = "0.1.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
dependencies = [
"windows-sys",
]
[[package]]
name = "windows-link"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
[[package]]
name = "windows-sys"
version = "0.61.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
dependencies = [
"windows-link",
]
[[package]]
name = "wschema"
version = "0.0.1"
dependencies = [
"criterion",
"serde",
"serde_json",
"sha2",
]
[[package]]
name = "zerocopy"
version = "0.8.63"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8"
dependencies = [
"zerocopy-derive",
]
[[package]]
name = "zerocopy-derive"
version = "0.8.63"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]]
name = "zmij"
version = "1.0.23"
+12
View File
@@ -10,6 +10,18 @@ name = "alkane_os"
[dependencies]
serde_json = { version = "=1.0.154", features = ["arbitrary_precision"] }
flare-ui = { path = "third-party/flare-ui/crates/flare-ui" }
wschema = { path = "third-party/flare-ui/crates/wschema" }
maud = "0.27"
[workspace]
members = ["third-party/flare-ui/crates/flare-ui", "third-party/flare-ui/crates/wschema"]
[workspace.package]
version = "0.0.1"
edition = "2021"
rust-version = "1.85"
license = "MIT"
[profile.release]
lto = true
+15 -1
View File
@@ -12,7 +12,10 @@
Rust mining and tuning core for Alkane control boards. The
[SDK](https://gitea.bluefla.re/blueflare/alkane-sdk) builds board images and
provides the hardware backend. The miner has no on-board web frontend.
provides the hardware backend. The on-board web console is the parameterised
`flare-ui`: a sidebar shell with live telemetry (readings) and real controls
(mode/target, start/stop) that drive the runtime, with `/api/...` as the
interface of record behind every page.
## Status
@@ -21,6 +24,9 @@ Stratum V1. Tests have replayed 33 captured BM1366 shares and one BM1362
share to a loopback pool with matching ACCEPT responses. Production board
control is still under development.
The BM1370 module encodes a captured S21 Pro job and parses captured nonce
frames. Work-ID mapping, chain control, and pool acceptance remain open.
The HAL client requests PSU shutdown on sensor faults and reserves work IDs
until a confirmed reset or shutdown. A production backend still needs a
power lease, watchdog, and validated temperature limits. SHA-256d and
@@ -37,6 +43,14 @@ ALKANE_POOL_PASSWORD="$POOL_PASSWORD" alkane-os --mine-simulator HAL_SOCKET POOL
Use `BM1362` for that chip. Set `ALKANE_API_LISTEN=127.0.0.1:4028` for
read-only `summary` and `version` commands; reach it remotely through SSH.
To bring up the full web console on a workstation with no hashboard, run
`alkane-os --serve-sim`: a reference HAL runs in-process, the runtime boots
against it, and the printed URL serves the live, controllable console (the
frequency moves toward the target; start/stop and mode changes take effect).
`alkane-os --serve` serves the same console with no backend, for a board whose
HAL backend is not written yet. `ALKANE_WEB_LISTEN=ADDR` overrides the bind
(default port 80, or 8080 without privilege).
## Release gate
`main` runs tests, benchmarks, and conformance before release; `next` builds
+11
View File
@@ -5,6 +5,17 @@ currently fails because the simulator and bench evidence producer is not yet
implemented. A green Rust build, host HAL replay probe, or rootfs archive does
not fill any cell.
`research-evidence.json` records scoped historical observations with source
hashes. `evidence_status.py` reports those separately from declarations in
`conformance.json`. Neither research claims nor manifest declarations count
as verified release cells. The current-run checker below is the only release
validator. `experiment-queue.json` ranks the next protocol and controller
experiments by the number of affected cells; blocked work stays visible.
The status report names catalog, decoded protocol, stock simulator boot,
captured-nonce pool acceptance, physical lifecycle, and complete-cell levels.
It leaves current-run verified counts unset; the conformance checker certifies
the full cells separately.
Each CI run must put a JSON report at
`ci/evidence/<GITHUB_RUN_ID>/<board>/<chip>.json`. The report binds its
`run_id`, `source_commit`, `os_binary_sha256`, `board`, and `chip` to the
+275
View File
@@ -0,0 +1,275 @@
# SPDX-License-Identifier: MIT
"""Board profiles used by the .afw producer and the CI checker.
An .afw is valid for exactly one board family. The arch and bootloader policy
come from this table, never from the caller alone, so a bundle cannot claim a
board it was not built for. cv1835 and am335x have complete, buildable profiles in this release; the
other Antminer families are listed so a wrong-board bundle is rejected by name
instead of being accepted as "unknown".
"""
AM335X_PARTITIONS = [
{"name": "mtd0", "device": "/dev/mtd0", "offset": 0x0000000, "size": 0x20000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "mtd1", "device": "/dev/mtd1", "offset": 0x0020000, "size": 0x20000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "mtd2", "device": "/dev/mtd2", "offset": 0x0040000, "size": 0x20000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "mtd3", "device": "/dev/mtd3", "offset": 0x0060000, "size": 0x20000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "mtd4", "device": "/dev/mtd4", "offset": 0x0080000, "size": 0x1C0000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "mtd5", "device": "/dev/mtd5", "offset": 0x0240000, "size": 0x20000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "mtd6", "device": "/dev/mtd6", "offset": 0x0260000, "size": 0x20000,
"secure": False, "boot_critical": True, "write_order": 2, "image": "dtb"},
{"name": "mtd7", "device": "/dev/mtd7", "offset": 0x0280000, "size": 0x500000,
"secure": False, "boot_critical": True, "write_order": 3, "image": "kernel"},
{"name": "mtd8", "device": "/dev/mtd8", "offset": 0x0800000, "size": 0x1400000,
"secure": False, "boot_critical": True, "write_order": 1, "image": "rootfs"},
{"name": "mtd9", "device": "/dev/mtd9", "offset": 0x1C00000, "size": 0x200000,
"secure": True, "boot_critical": False, "write_order": 0, "image": None},
{"name": "mtd10", "device": "/dev/mtd10", "offset": 0x1E00000, "size": 0x200000,
"secure": True, "boot_critical": False, "write_order": 0, "image": None},
{"name": "mtd11", "device": "/dev/mtd11", "offset": 0x2000000, "size": 0x6000000,
"secure": True, "boot_critical": False, "write_order": 0, "image": None},
]
AM335X_IMAGES = [
{"name": "kernel", "source": "alkane-am335x.uImage", "role": "kernel",
"format": "uimage", "partition": "mtd7", "install": True, "exact_bytes": None},
{"name": "dtb", "source": "am335x-alkane.dtb", "role": "dtb",
"format": "fdt", "partition": "mtd6", "install": True, "exact_bytes": None},
{"name": "rootfs", "source": "alkane-am335x-ramdisk.uImage", "role": "rootfs",
"format": "uimage", "partition": "mtd8", "install": True, "exact_bytes": None},
]
# Tier-3 from-stock variant: same 12-partition NAND map, but mtd4 is written
# with our non-RSA U-Boot (a legacy uImage the preserved SPL chainloads), so its
# secure flag is False and it carries the u-boot image at write_order 3; the
# kernel moves to write_order 4 (U-Boot lands before the kernel). The SPL copies
# (mtd0-3) and bootenv (mtd5) stay preserved and are never write targets.
AM335X_STOCK_PARTITIONS = []
for _p in AM335X_PARTITIONS:
_q = dict(_p)
if _q["name"] == "mtd4":
_q.update(secure=False, write_order=3, image="u-boot")
elif _q["name"] == "mtd7":
_q.update(write_order=4)
AM335X_STOCK_PARTITIONS.append(_q)
AM335X_STOCK_IMAGES = [
{"name": "u-boot", "source": "alkane-am335x-uboot-mtd4.uImage", "role": "bootloader",
"format": "uimage", "partition": "mtd4", "install": True, "exact_bytes": None},
] + [dict(_img) for _img in AM335X_IMAGES]
BOARDS = {
"am335x": {
"arch": "arm",
"bootloader_policy": "preserve",
"buildable": True,
"format_checks": ["uimage", "fdt", "uimage"],
"partitions": AM335X_PARTITIONS,
"images": AM335X_IMAGES,
},
"am335x-stock": {
"arch": "arm",
"bootloader_policy": "include",
"buildable": True,
"format_checks": ["uimage", "uimage", "fdt", "uimage"],
"partitions": AM335X_STOCK_PARTITIONS,
"images": AM335X_STOCK_IMAGES,
},
"cv1835": {
"arch": "arm64",
"bootloader_policy": "preserve",
"buildable": True,
"format_checks": ["fit", "arm64-image", "fdt", "cpio-gzip"],
"partitions": [
{
"name": "p1",
"device": "/dev/mmcblk0p1",
"offset": 0,
"size": 16 * 1024 * 1024,
"secure": False,
"boot_critical": True,
"write_order": 1,
"image": "p1",
},
{
"name": "p3",
"device": "/dev/mmcblk0p3",
"offset": 0,
"size": 32 * 1024 * 1024,
"secure": True,
"boot_critical": False,
"write_order": 0,
"image": None,
},
{
"name": "boot0",
"device": "/dev/mmcblk0boot0",
"offset": 0,
"size": 4 * 1024 * 1024,
"secure": True,
"boot_critical": True,
"write_order": 0,
"image": None,
},
{
"name": "boot1",
"device": "/dev/mmcblk0boot1",
"offset": 0,
"size": 4 * 1024 * 1024,
"secure": True,
"boot_critical": True,
"write_order": 0,
"image": None,
},
],
"images": [
{
"name": "kernel",
"source": "Image",
"role": "kernel",
"format": "arm64-image",
"partition": None,
"install": False,
"exact_bytes": None,
},
{
"name": "dtb",
"source": "cv-alkane.dtb",
"role": "dtb",
"format": "fdt",
"partition": None,
"install": False,
"exact_bytes": None,
},
{
"name": "rootfs",
"source": "rootfs.cpio.gz",
"role": "rootfs",
"format": "cpio-gzip",
"partition": None,
"install": False,
"exact_bytes": None,
},
{
"name": "p1",
"source": "alkane-cv1835-p1.fit",
"role": "boot",
"format": "fit",
"partition": "p1",
"install": True,
"exact_bytes": 16 * 1024 * 1024,
},
],
},
# Antminer families that the seven-board release gate still lists. They are
# known, so a wrong-board bundle is refused by identity, but they do not
# have a buildable .afw profile in this release.
"zynq-7010": {
"arch": "armv7",
"bootloader_policy": "preserve",
"buildable": True,
# kernel (zImage), dtb (FDT), rootfs (gzip cpio ramdisk)
"format_checks": ["zimage", "fdt", "cpio-gzip"],
# Both bench Zynq-7010 units (S19, S17) share mtd0 (40 MiB: BOOT.bin +
# the kernel slot) and mtd1 (32 MiB: ramfs). BOOT.bin (FSBL + FPGA
# bitstream + stock U-Boot) is PRESERVED - the bundle carries no
# bootloader member; only the kernel slot in mtd0 and the ramfs in mtd1
# are our OS. The exact kernel-slot sub-offset is placed by the install
# method (it differs by unit), so this profile gates image formats and
# size ceilings, not a fixed offset map.
"partitions": [
{"name": "mtd0", "device": "/dev/mtd0", "offset": 0, "size": 0x2800000,
"secure": False, "boot_critical": True, "write_order": 1, "image": "kernel"},
{"name": "mtd1", "device": "/dev/mtd1", "offset": 0x2800000, "size": 0x2000000,
"secure": False, "boot_critical": True, "write_order": 2, "image": "rootfs"},
],
"images": [
{"name": "kernel", "source": "zImage", "role": "kernel",
"format": "zimage", "partition": "mtd0", "install": True, "exact_bytes": None},
{"name": "dtb", "source": "zynq-alkane.dtb", "role": "dtb",
"format": "fdt", "partition": "mtd0", "install": True, "exact_bytes": None},
{"name": "rootfs", "source": "rootfs.cpio.gz", "role": "rootfs",
"format": "cpio-gzip", "partition": "mtd1", "install": True, "exact_bytes": None},
],
},
"zynq-s17": {"arch": "armv7", "bootloader_policy": "include", "buildable": False},
# Amlogic A113D / AXG (S21 Pro-class) control board. arm64. Our OS is staged
# as FILES in the nvdata UBI volume (mtd6): kernel (arm64 Image), dtb, and a
# uImage ramdisk. The signed FIP bootloader and the stock boot partition
# (mtd0-5) are PRESERVED - zero raw writes outside nvdata, so the stock OS in
# mtd4 stays as a one-setenv fallback. Hence bootloader_policy preserve and no
# bootloader member.
"a113d": {
"arch": "arm64",
"bootloader_policy": "preserve",
"buildable": True,
"format_checks": ["arm64-image", "fdt", "uimage"],
"partitions": [
{"name": "mtd0", "device": "/dev/mtd0", "offset": 0x0000000, "size": 0x200000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "mtd1", "device": "/dev/mtd1", "offset": 0x0800000, "size": 0x800000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "mtd2", "device": "/dev/mtd2", "offset": 0x1000000, "size": 0x200000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "mtd3", "device": "/dev/mtd3", "offset": 0x1200000, "size": 0x1000000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "mtd4", "device": "/dev/mtd4", "offset": 0x2200000, "size": 0x2000000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "mtd5", "device": "/dev/mtd5", "offset": 0x4200000, "size": 0x500000,
"secure": True, "boot_critical": True, "write_order": 0, "image": None},
{"name": "nvdata", "device": "/dev/mtd6", "offset": 0x4700000, "size": 0xB900000,
"secure": False, "boot_critical": True, "write_order": 1, "image": "kernel"},
],
"images": [
{"name": "kernel", "source": "vmlinux.bin", "role": "kernel",
"format": "arm64-image", "partition": "nvdata", "install": True, "exact_bytes": None},
{"name": "dtb", "source": "devicetree.dtb", "role": "dtb",
"format": "fdt", "partition": "nvdata", "install": True, "exact_bytes": None},
{"name": "rootfs", "source": "uramdisk.image.gz", "role": "rootfs",
"format": "uimage", "partition": "nvdata", "install": True, "exact_bytes": None},
],
},
"a113d-s21pro": {"arch": "arm64", "bootloader_policy": "preserve", "buildable": False},
"am335x-bb": {"arch": "armv7", "bootloader_policy": "preserve", "buildable": False},
}
SAFE_IMAGE_FORMATS = {
"fit",
"arm64-image",
"zimage",
"fdt",
"cpio-gzip",
"uimage",
"raw",
}
SAFE_IMAGE_ROLES = {
"kernel",
"dtb",
"rootfs",
"bootloader",
"boot",
"component",
}
def board(name):
"""Return the profile for a board family, or raise KeyError."""
return BOARDS[name]
def known_board(name):
return name in BOARDS
def expect_arch(name):
return BOARDS[name]["arch"]
def expect_policy(name):
return BOARDS[name]["bootloader_policy"]
+656
View File
@@ -0,0 +1,656 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Generate an .afw manifest and stage its payload members.
The output is a full OS install bundle for exactly one board family: the
manifest names every image, its size and SHA-256, the partition plan, the
bootloader policy, the network recovery path and a liveness marker. Payload
members are staged under <staging>/payload/ in manifest order.
This script does not create the tar. ci/make-afw.sh packs the staged members
in the fixed order manifest.json, optional manifest.json.sig, then payload.
ci/check-afw.py verifies the finished bundle before it is published.
"""
import argparse
import datetime
import hashlib
import json
import os
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile
import afw_boards
SCHEMA = 2
P1_LOAD = 0x100200000
GOLDEN_LBA_BYTES = 0x300000 * 512
REVISION = 40
AM335X_MAP = {
"mtd0": (0x0000000, 0x20000, True, True, 0, None),
"mtd1": (0x0020000, 0x20000, True, True, 0, None),
"mtd2": (0x0040000, 0x20000, True, True, 0, None),
"mtd3": (0x0060000, 0x20000, True, True, 0, None),
"mtd4": (0x0080000, 0x1C0000, True, True, 0, None),
"mtd5": (0x0240000, 0x20000, True, True, 0, None),
"mtd6": (0x0260000, 0x20000, False, True, 2, "dtb"),
"mtd7": (0x0280000, 0x500000, False, True, 3, "kernel"),
"mtd8": (0x0800000, 0x1400000, False, True, 1, "rootfs"),
"mtd9": (0x1C00000, 0x200000, True, False, 0, None),
"mtd10": (0x1E00000, 0x200000, True, False, 0, None),
"mtd11": (0x2000000, 0x6000000, True, False, 0, None),
}
AM335X_HOLE = (0x780000, 0x80000)
AM335X_CHIP = 0x8000000
AM335X_TARGETS = {"kernel": "mtd7", "dtb": "mtd6", "rootfs": "mtd8"}
AM335X_FORMATS = {"kernel": "uimage", "dtb": "fdt", "rootfs": "uimage"}
AM335X_CEILINGS = {"kernel": 0x500000, "dtb": 0x20000, "rootfs": 0x1400000}
# Tier-3 from-stock: same map except mtd4 is a write target (our U-Boot).
AM335X_STOCK_MAP = dict(AM335X_MAP)
AM335X_STOCK_MAP["mtd4"] = (0x0080000, 0x1C0000, False, True, 3, "u-boot")
AM335X_STOCK_MAP["mtd7"] = (0x0280000, 0x500000, False, True, 4, "kernel")
AM335X_STOCK_TARGETS = {"u-boot": "mtd4", "kernel": "mtd7", "dtb": "mtd6", "rootfs": "mtd8"}
AM335X_STOCK_FORMATS = {"u-boot": "uimage", "kernel": "uimage", "dtb": "fdt", "rootfs": "uimage"}
AM335X_STOCK_CEILINGS = {"u-boot": 0x1C0000, "kernel": 0x500000, "dtb": 0x20000, "rootfs": 0x1400000}
# SPL copies (mtd0-3) and bootenv (mtd5) must never be written on either tier.
AM335X_NEVER_WRITE = {"mtd0", "mtd1", "mtd2", "mtd3", "mtd5"}
# Zynq-7010 (tier 2, preserve): kernel into the mtd0 kernel slot, dtb, rootfs
# into mtd1; BOOT.bin (FSBL + FPGA bitstream + stock U-Boot) preserved.
ZYNQ_FORMATS = {"kernel": "zimage", "dtb": "fdt", "rootfs": "cpio-gzip"}
ZYNQ_CEILINGS = {"kernel": 0x500000, "dtb": 0x20000, "rootfs": 0x2000000}
# Amlogic A113D/AXG (tier 2, preserve): kernel (arm64 Image), dtb and a uImage
# ramdisk are staged as FILES in the nvdata UBI (mtd6); the FIP bootloader and
# the stock boot partition (mtd0-5) are preserved. Ceilings keep the three well
# within the ~185 MiB usable nvdata UBI.
A113D_FORMATS = {"kernel": "arm64-image", "dtb": "fdt", "rootfs": "uimage"}
A113D_CEILINGS = {"kernel": 0x4000000, "dtb": 0x100000, "rootfs": 0x6000000}
A113D_NVDATA_USABLE = 0xB900000 # mtd6 nvdata size; the three images must fit
def die(message):
print(f"afw_manifest: error: {message}", file=sys.stderr)
raise SystemExit(1)
def sha256_bytes(data):
return hashlib.sha256(data).hexdigest()
def sha256_file(path):
digest = hashlib.sha256()
with path.open("rb") as source:
for chunk in iter(lambda: source.read(1024 * 1024), b""):
digest.update(chunk)
return digest.hexdigest()
def git_revision(path):
try:
return subprocess.check_output(
["git", "-C", str(path), "rev-parse", "HEAD"],
text=True,
stderr=subprocess.DEVNULL,
).strip()
except (OSError, subprocess.CalledProcessError):
return None
def check_revision(name, value):
if value is None or len(value) != REVISION:
die(f"{name} must be a 40-character git revision, got {value!r}")
if any(character not in "0123456789abcdef" for character in value):
die(f"{name} must be lowercase hexadecimal")
return value
def build_date(value):
if value is None:
return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
try:
moment = datetime.datetime.fromtimestamp(int(value), datetime.timezone.utc)
except (ValueError, OSError):
die("SOURCE_DATE_EPOCH must be an integer Unix timestamp")
return moment.strftime("%Y-%m-%dT%H:%M:%SZ")
def magic_ok(fmt, path):
with path.open("rb") as source:
data = source.read() if fmt == "fit" else source.read(4096)
if fmt == "fit":
if not data.startswith(b"\xd0\x0d\xfe\xed"):
return "does not start with the FIT/FDT magic d00dfeed"
if b"config@cv1835_miner_emmc" not in data:
return "FIT is missing config@cv1835_miner_emmc"
if b"signature@" in data:
return "FIT carries signature@ nodes, which this board cannot boot"
elif fmt == "fdt":
if not data.startswith(b"\xd0\x0d\xfe\xed"):
return "does not start with the FDT magic d00dfeed"
elif fmt == "arm64-image":
if len(data) < 64 or data[0x38:0x3C] != b"ARMd":
return "does not carry the arm64 Image ARMd header magic"
elif fmt == "cpio-gzip":
if not data.startswith(b"\x1f\x8b"):
return "is not gzip-compressed"
elif fmt == "uimage":
if not data.startswith(b"\x27\x05\x19\x56"):
return "is not a legacy uImage"
return None
def pad_to(source, destination, exact_bytes):
size = source.stat().st_size
if size > exact_bytes:
die(f"{source.name} is {size} bytes, larger than its {exact_bytes}-byte partition")
destination.parent.mkdir(parents=True, exist_ok=True)
with source.open("rb") as reader, destination.open("wb") as writer:
shutil.copyfileobj(reader, writer)
if size < exact_bytes:
writer.write(b"\0" * (exact_bytes - size))
if destination.stat().st_size != exact_bytes:
die(f"{destination.name} did not reach the exact {exact_bytes}-byte size")
def load_plan(path, profile, board):
plan = json.loads(Path(path).read_text())
if plan.get("board") != board:
die(f"plan board {plan.get('board')!r} does not match --board {board!r}")
if plan.get("arch") != profile["arch"]:
die(f"plan arch {plan.get('arch')!r} does not match {profile['arch']!r}")
policy = plan.get("bootloader_policy", profile["bootloader_policy"])
if policy != profile["bootloader_policy"]:
die(f"plan bootloader_policy {policy!r} does not match {profile['bootloader_policy']!r}")
partitions = plan.get("partitions")
images = plan.get("images")
if not isinstance(partitions, list) or not isinstance(images, list):
die("plan must contain partitions and images lists")
return partitions, images
def signing_key(path):
raw = Path(path).read_bytes()
if len(raw) == 64:
try:
raw = bytes.fromhex(raw.decode("ascii").strip())
except (ValueError, UnicodeDecodeError):
die("signing key file must be 32 raw bytes or 64 hexadecimal characters")
if len(raw) != 32:
die("signing key file must be 32 raw bytes or 64 hexadecimal characters")
try:
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
except ImportError:
die("Ed25519 signing needs the Python cryptography package")
private = Ed25519PrivateKey.from_private_bytes(raw)
public = private.public_key().public_bytes(
serialization.Encoding.Raw, serialization.PublicFormat.Raw
)
return private, public.hex()
def validate_am335x(partitions, images):
"""Reject the AM335x brick paths before a bundle is packed."""
installs = [image for image in images if image["install"]]
if len(installs) != 3:
die("am335x must install exactly kernel, dtb and rootfs")
if {image["name"] for image in installs} != set(AM335X_TARGETS):
die("am335x install images must be named kernel, dtb and rootfs")
for image in images:
lowered = f"{image['name']} {image['file']}".lower()
if "spl" in lowered or "u-boot" in lowered or "uboot" in lowered:
die(f"am335x bundle carries an spl/u-boot member: {image['file']!r}")
for image in installs:
name = image["name"]
if image["format"] != AM335X_FORMATS[name]:
die(f"am335x {name} format must be {AM335X_FORMATS[name]}")
if image["partition"] != AM335X_TARGETS[name]:
die(f"am335x {name} must target {AM335X_TARGETS[name]}")
if image["size"] > AM335X_CEILINGS[name]:
die(
f"am335x {name} is {image['size']} bytes, over the "
f"0x{AM335X_CEILINGS[name]:x}-byte ceiling"
)
seen = {}
for partition in partitions:
name = partition["name"]
if name not in AM335X_MAP:
die(f"unknown am335x partition {name!r}")
seen[name] = partition
offset, size, secure, boot_critical, write_order, image_name = AM335X_MAP[name]
if int(partition["offset"]) != offset:
die(f"am335x {name} offset must be 0x{offset:x}")
if int(partition["size"]) != size:
die(f"am335x {name} size must be 0x{size:x}")
if bool(partition["secure"]) is not secure:
die(f"am335x {name} secure flag is wrong")
if bool(partition["boot_critical"]) is not boot_critical:
die(f"am335x {name} boot_critical flag is wrong")
if int(partition.get("write_order", 0)) != write_order:
die(f"am335x {name} write_order must be {write_order}")
if partition.get("image") != image_name:
die(f"am335x {name} image must be {image_name!r}")
start = int(partition["offset"])
end = start + int(partition["size"])
hole_start, hole_size = AM335X_HOLE
if start < hole_start + hole_size and end > hole_start:
die(f"am335x {name} overlaps the 0x780000-0x800000 hole")
if name in {f"mtd{index}" for index in range(0, 6)} and write_order != 0:
die(f"am335x {name} is preserved and must not be written")
if set(seen) != set(AM335X_MAP):
die("am335x manifest partition map is incomplete")
if int(seen["mtd7"]["offset"]) + int(seen["mtd7"]["size"]) != AM335X_HOLE[0]:
die("am335x mtd7 must end at the 0x780000 hole")
if int(seen["mtd8"]["offset"]) != AM335X_HOLE[0] + AM335X_HOLE[1]:
die("am335x mtd8 must start at 0x800000 after the hole")
total = sum(int(part["size"]) for part in partitions)
if total != AM335X_CHIP - AM335X_HOLE[1]:
die("am335x partition sizes must sum to 0x7F80000")
def validate_am335x_stock(partitions, images):
"""Reject the AM335x tier-3 (from-stock) brick paths before packing.
This bundle DOES write mtd4 (our non-RSA U-Boot), so unlike the tier-2
validator it permits a u-boot member - but it still guards every brick
path: the four install images are exactly u-boot/kernel/dtb/rootfs, mtd4
carries the u-boot and no SPL copy is ever a write target, the 0x780000
hole and the 12-partition geometry are exact, and no mtd0-3/mtd5 may hold
an image.
"""
installs = [image for image in images if image["install"]]
if len(installs) != 4:
die("am335x-stock must install exactly u-boot, kernel, dtb and rootfs")
if {image["name"] for image in installs} != set(AM335X_STOCK_TARGETS):
die("am335x-stock install images must be named u-boot, kernel, dtb and rootfs")
# The U-Boot member is expected here; a loose 'spl' member never is.
for image in images:
lowered = f"{image['name']} {image['file']}".lower()
if "spl" in lowered:
die(f"am335x-stock bundle carries an spl member: {image['file']!r}")
for image in installs:
name = image["name"]
if image["format"] != AM335X_STOCK_FORMATS[name]:
die(f"am335x-stock {name} format must be {AM335X_STOCK_FORMATS[name]}")
if image["partition"] != AM335X_STOCK_TARGETS[name]:
die(f"am335x-stock {name} must target {AM335X_STOCK_TARGETS[name]}")
if image["size"] > AM335X_STOCK_CEILINGS[name]:
die(
f"am335x-stock {name} is {image['size']} bytes, over the "
f"0x{AM335X_STOCK_CEILINGS[name]:x}-byte ceiling"
)
if installs[[img["name"] for img in installs].index("u-boot")]["role"] != "bootloader":
die("am335x-stock u-boot image must have role bootloader")
seen = {}
for partition in partitions:
name = partition["name"]
if name not in AM335X_STOCK_MAP:
die(f"unknown am335x-stock partition {name!r}")
seen[name] = partition
offset, size, secure, boot_critical, write_order, image_name = AM335X_STOCK_MAP[name]
if int(partition["offset"]) != offset:
die(f"am335x-stock {name} offset must be 0x{offset:x}")
if int(partition["size"]) != size:
die(f"am335x-stock {name} size must be 0x{size:x}")
if bool(partition["secure"]) is not secure:
die(f"am335x-stock {name} secure flag is wrong")
if bool(partition["boot_critical"]) is not boot_critical:
die(f"am335x-stock {name} boot_critical flag is wrong")
if int(partition.get("write_order", 0)) != write_order:
die(f"am335x-stock {name} write_order must be {write_order}")
if partition.get("image") != image_name:
die(f"am335x-stock {name} image must be {image_name!r}")
start = int(partition["offset"])
end = start + int(partition["size"])
hole_start, hole_size = AM335X_HOLE
if start < hole_start + hole_size and end > hole_start:
die(f"am335x-stock {name} overlaps the 0x780000-0x800000 hole")
if name in AM335X_NEVER_WRITE and (write_order != 0 or partition.get("image") is not None):
die(f"am335x-stock {name} is preserved and must not be written")
if set(seen) != set(AM335X_STOCK_MAP):
die("am335x-stock manifest partition map is incomplete")
if int(seen["mtd7"]["offset"]) + int(seen["mtd7"]["size"]) != AM335X_HOLE[0]:
die("am335x-stock mtd7 must end at the 0x780000 hole")
if int(seen["mtd8"]["offset"]) != AM335X_HOLE[0] + AM335X_HOLE[1]:
die("am335x-stock mtd8 must start at 0x800000 after the hole")
total = sum(int(part["size"]) for part in partitions)
if total != AM335X_CHIP - AM335X_HOLE[1]:
die("am335x-stock partition sizes must sum to 0x7F80000")
def validate_zynq(partitions, images):
"""Reject the Zynq-7010 brick paths before packing (tier 2, preserve).
The board reuses the stock BOOT.bin (FSBL + FPGA bitstream + stock U-Boot),
so the bundle must carry NO bootloader/spl/BOOT.bin member; it installs our
kernel (zImage) into the mtd0 kernel slot, the dtb, and the rootfs
(gzip cpio) into mtd1. The exact kernel-slot offset is placed per-unit by the
install method, so this gate enforces the image set, formats and the
size ceilings (so an oversize image cannot overrun the slot) - not a fixed
offset map.
"""
installs = [image for image in images if image["install"]]
if len(installs) != 3:
die("zynq-7010 must install exactly kernel, dtb and rootfs")
if {image["name"] for image in installs} != set(ZYNQ_FORMATS):
die("zynq-7010 install images must be named kernel, dtb and rootfs")
for image in images:
lowered = f"{image['name']} {image['file']} {image.get('role','')}".lower()
if "spl" in lowered or "u-boot" in lowered or "uboot" in lowered \
or "boot.bin" in lowered or image.get("role") == "bootloader":
die(f"zynq-7010 bundle carries a bootloader/spl member: {image['file']!r}")
for image in installs:
name = image["name"]
if image["format"] != ZYNQ_FORMATS[name]:
die(f"zynq-7010 {name} format must be {ZYNQ_FORMATS[name]}")
if image["size"] > ZYNQ_CEILINGS[name]:
die(
f"zynq-7010 {name} is {image['size']} bytes, over the "
f"0x{ZYNQ_CEILINGS[name]:x}-byte ceiling"
)
# BOOT.bin lives at the front of mtd0 and is never a write target here.
for partition in partitions:
if partition.get("image") in (None, "kernel", "rootfs"):
continue
die(f"zynq-7010 partition {partition['name']!r} has an unexpected image target")
def validate_a113d(partitions, images):
"""Reject the Amlogic A113D/AXG brick paths before packing (tier 2, preserve).
Our OS is staged as files in the nvdata UBI; the signed FIP bootloader and the
stock boot partition (mtd0-5) are preserved, so the bundle must carry NO
bootloader/spl/tpl/fip member. The kernel (arm64 Image), dtb and uImage
ramdisk must fit the nvdata UBI both individually (ceilings) and together.
"""
installs = [image for image in images if image["install"]]
if len(installs) != 3:
die("a113d must install exactly kernel, dtb and rootfs")
if {image["name"] for image in installs} != set(A113D_FORMATS):
die("a113d install images must be named kernel, dtb and rootfs")
for image in images:
lowered = f"{image['name']} {image['file']} {image.get('role','')}".lower()
if "spl" in lowered or "u-boot" in lowered or "uboot" in lowered \
or "fip" in lowered or "tpl" in lowered or image.get("role") == "bootloader":
die(f"a113d bundle carries a bootloader/spl/fip member: {image['file']!r}")
total = 0
for image in installs:
name = image["name"]
if image["format"] != A113D_FORMATS[name]:
die(f"a113d {name} format must be {A113D_FORMATS[name]}")
if image["size"] > A113D_CEILINGS[name]:
die(f"a113d {name} is {image['size']} bytes, over the 0x{A113D_CEILINGS[name]:x}-byte ceiling")
total += image["size"]
if total > A113D_NVDATA_USABLE:
die(f"a113d images total {total} bytes, over the 0x{A113D_NVDATA_USABLE:x}-byte nvdata UBI")
# mtd0-5 (FIP + stock boot) are never a write target.
for partition in partitions:
if partition["name"] != "nvdata" and partition.get("image") is not None:
die(f"a113d partition {partition['name']!r} is preserved and must not carry an image")
def build(args):
board = args.board
if not afw_boards.known_board(board):
die(f"unknown board family {board!r}")
profile = afw_boards.board(board)
if not profile["buildable"]:
die(f"board {board!r} has no buildable .afw profile in this release")
input_dir = Path(args.input)
if not input_dir.is_dir():
die(f"input directory does not exist: {input_dir}")
plan_document = None
if args.plan:
plan_document = json.loads(Path(args.plan).read_text())
partitions, image_specs = load_plan(args.plan, profile, board)
else:
partitions = profile["partitions"]
image_specs = profile["images"]
staging = Path(args.staging) if args.staging else Path(tempfile.mkdtemp(prefix="afw-manifest."))
payload_dir = staging / "payload"
payload_dir.mkdir(parents=True, exist_ok=True)
images = []
for spec in image_specs:
source_name = spec.get("source", spec.get("file"))
if not source_name:
die(f"image {spec.get('name')!r} has no source file")
source = input_dir / source_name
if not source.is_file():
die(f"required image is missing: {source}")
name = spec["name"]
fmt = spec.get("format", "raw")
if fmt not in afw_boards.SAFE_IMAGE_FORMATS:
die(f"image {name!r} has unsupported format {fmt!r}")
role = spec.get("role", "component")
if role not in afw_boards.SAFE_IMAGE_ROLES:
die(f"image {name!r} has unsupported role {role!r}")
target = payload_dir / source.name
exact = spec.get("exact_bytes")
if exact is not None:
pad_to(source, target, int(exact))
else:
shutil.copyfile(source, target)
problem = magic_ok(fmt, target)
if problem:
die(f"image {name!r} ({target.name}) {problem}")
size = target.stat().st_size
images.append(
{
"name": name,
"file": f"payload/{target.name}",
"role": role,
"format": fmt,
"size": size,
"sha256": sha256_file(target),
"partition": spec.get("partition"),
"install": bool(spec.get("install", False)),
}
)
names = {image["name"] for image in images}
for partition in partitions:
image_name = partition.get("image")
if image_name is not None and image_name not in names:
die(f"partition {partition.get('name')!r} references missing image {image_name!r}")
if not partition.get("secure", False):
size = int(partition.get("size", 0))
if size <= 0:
die(f"partition {partition.get('name')!r} has no positive size")
if partition.get("write_order", 0) > 0 and image_name is None:
die(f"installable partition {partition.get('name')!r} has no image")
device = partition.get("device", "")
if not device.startswith("/dev/"):
die(f"partition {partition.get('name')!r} has an invalid device path")
if "boot0" in device and not partition.get("secure", False):
die("boot0 must be declared secure and must never be a write target")
if "boot0" in device and partition.get("write_order", 0) > 0:
die("boot0 must not be in the write order")
for image in images:
partition_name = image.get("partition")
if partition_name is None:
continue
matches = [item for item in partitions if item.get("name") == partition_name]
if len(matches) != 1:
die(f"image {image['name']!r} targets unknown partition {partition_name!r}")
partition = matches[0]
if partition.get("secure", False):
die(f"image {image['name']!r} targets secure partition {partition_name!r}")
if image["size"] > int(partition["size"]):
die(
f"image {image['name']!r} is {image['size']} bytes, larger than "
f"partition {partition_name!r} ({partition['size']} bytes)"
)
exact = image.get("exact_bytes", partition.get("exact_bytes"))
if exact is not None and image["size"] != int(exact):
die(f"image {image['name']!r} must be exactly {exact} bytes")
installs = [image for image in images if image["install"]]
if not installs:
die("bundle has no installable image")
if board == "cv1835":
if len(installs) != 1 or installs[0]["name"] != "p1":
die("cv1835 must install exactly one image, p1")
if installs[0]["size"] != 16 * 1024 * 1024:
die("cv1835 p1 must be the 16 MiB padded FIT")
elif board == "am335x":
validate_am335x(partitions, images)
elif board == "am335x-stock":
validate_am335x_stock(partitions, images)
elif board == "zynq-7010":
validate_zynq(partitions, images)
elif board == "a113d":
validate_a113d(partitions, images)
policy = profile["bootloader_policy"]
if policy == "preserve" and any(image["role"] == "bootloader" for image in images):
die("bootloader_policy is preserve but the bundle carries a bootloader image")
if policy == "include" and not any(image["role"] == "bootloader" for image in images):
die("bootloader_policy is include but the bundle has no bootloader image")
sdk_revision = check_revision(
"sdk_revision", args.sdk_revision or (git_revision(args.sdk_dir) if args.sdk_dir else None)
)
os_revision = check_revision(
"os_revision", args.os_revision or (git_revision(args.os_dir) if args.os_dir else None)
)
signature = {
"type": "unsigned",
"member": None,
"public_key_hex": None,
}
signer = None
if args.signing_key:
signer, public_hex = signing_key(args.signing_key)
signature = {
"type": "ed25519",
"member": "manifest.json.sig",
"public_key_hex": public_hex,
}
if board == "am335x":
boot_switch = {
"method": "preserved-u-boot-go",
"detail": "mtd0-5 (SPL and our non-RSA U-Boot) are preserved and never "
"written. The update writes mtd8 root, mtd6 dtb and mtd7 kernel as "
"legacy ARM uImages, and the existing boot command loads them.",
}
preflight = {
"required_commands": ["flash_erase", "nandwrite", "nanddump", "md5sum", "sync"],
"forbidden_devices": [f"/dev/mtd{index}" for index in range(0, 6)],
"min_free_bytes": 32 * 1024 * 1024,
"source_os": ["alkane", "ouros", "braiins"],
"held_partitions": ["mtd8", "mtd6", "mtd7"],
"preserve_partitions": [f"mtd{index}" for index in range(0, 6)],
}
recovery = {
"network": "afw restore --host <ip> --held-backup <mtd8.img> --confirm FLASH",
"held_partition": "mtd8",
"held_partitions": ["mtd8", "mtd6", "mtd7"],
}
else:
boot_switch = {
"method": "partition-overwrite",
"detail": "Writing /dev/mmcblk0p1 replaces the FIT. The vendor boot0, "
"BL2, BL31 and U-Boot chain is preserved and never written.",
}
preflight = {
"required_commands": ["dd", "md5sum", "sync"],
"forbidden_devices": ["/dev/mmcblk0", "/dev/mmcblk0boot0", "/dev/mmcblk0boot1"],
"min_free_bytes": 32 * 1024 * 1024,
"source_os": ["stock-bitmain", "vnish", "braiins", "ouros", "alkane"],
}
recovery = {
"network": "afw restore --host <ip> --held-backup <file>",
"held_partition": "p1",
"golden_lba_bytes": GOLDEN_LBA_BYTES,
}
manifest = {
"schema": SCHEMA,
"format": "afw",
"board": board,
"arch": profile["arch"],
"version": args.version,
"build_date": build_date(os.environ.get("SOURCE_DATE_EPOCH")),
"sdk_revision": sdk_revision,
"os_revision": os_revision,
"payload_type": "os",
"bootloader_policy": policy,
"signature": signature,
"partitions": [
{
"name": item["name"],
"device": item["device"],
"offset": int(item.get("offset", 0)),
"size": int(item["size"]),
"secure": bool(item.get("secure", False)),
"boot_critical": bool(item.get("boot_critical", False)),
"write_order": int(item.get("write_order", 0)),
"image": item.get("image"),
}
for item in partitions
],
"images": images,
"boot_switch": boot_switch,
"preflight": preflight,
"recovery": recovery,
"marker": (plan_document or {}).get("marker")
or args.marker
or ("Alkane" if board == "am335x" else "ALKANE"),
"kernel_version": (plan_document or {}).get("kernel_version")
or args.kernel_version
or "6.18.48",
}
if args.notes:
manifest["notes"] = args.notes
manifest_path = staging / "manifest.json"
manifest_bytes = (json.dumps(manifest, indent=2) + "\n").encode()
manifest_path.write_bytes(manifest_bytes)
if signer is not None:
signature_bytes = signer.sign(manifest_bytes)
(staging / "manifest.json.sig").write_bytes(signature_bytes)
(staging / "manifest.pub").write_text(signature["public_key_hex"] + "\n")
print(str(manifest_path))
return staging, manifest_path
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--board", required=True)
parser.add_argument("--version", required=True)
parser.add_argument("--input", required=True, help="SDK board output directory")
parser.add_argument("--staging", help="staging directory for manifest.json and payload/")
parser.add_argument("--plan", help="plan JSON emitted by alkane-sdk ci/check-plans.py")
parser.add_argument("--sdk-revision")
parser.add_argument("--os-revision")
parser.add_argument("--sdk-dir")
parser.add_argument("--os-dir", default=".")
parser.add_argument("--signing-key", help="raw 32-byte or 64-hex Ed25519 seed file")
parser.add_argument("--kernel-version")
parser.add_argument("--marker")
parser.add_argument("--notes")
args = parser.parse_args()
try:
build(args)
except SystemExit:
raise
except (OSError, ValueError, KeyError) as error:
die(str(error))
if __name__ == "__main__":
main()
+709
View File
@@ -0,0 +1,709 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Verify an .afw OS install bundle before it can be published or installed.
The gate is deliberately strict and offline. It reads the tar itself instead of
trusting GNU tar, checks the fixed member order, rejects path traversal and
non-regular members, verifies every payload size and SHA-256 against the
manifest, checks the board/arch and bootloader policy, checks each image against
its partition ceiling, and refuses a signed bundle it cannot verify.
Exit codes: 0 pass, 1 failure, 2 usage error.
"""
import argparse
import hashlib
import json
from pathlib import Path
import sys
import afw_boards
BLOCK = 512
MAX_MANIFEST = 64 * 1024
MAX_ARCHIVE = 512 * 1024 * 1024
AM335X_MAP = {
"mtd0": (0x0000000, 0x20000, True, True, 0, None),
"mtd1": (0x0020000, 0x20000, True, True, 0, None),
"mtd2": (0x0040000, 0x20000, True, True, 0, None),
"mtd3": (0x0060000, 0x20000, True, True, 0, None),
"mtd4": (0x0080000, 0x1C0000, True, True, 0, None),
"mtd5": (0x0240000, 0x20000, True, True, 0, None),
"mtd6": (0x0260000, 0x20000, False, True, 2, "dtb"),
"mtd7": (0x0280000, 0x500000, False, True, 3, "kernel"),
"mtd8": (0x0800000, 0x1400000, False, True, 1, "rootfs"),
"mtd9": (0x1C00000, 0x200000, True, False, 0, None),
"mtd10": (0x1E00000, 0x200000, True, False, 0, None),
"mtd11": (0x2000000, 0x6000000, True, False, 0, None),
}
AM335X_HOLE = (0x780000, 0x80000)
AM335X_CHIP = 0x8000000
AM335X_TARGETS = {"kernel": "mtd7", "dtb": "mtd6", "rootfs": "mtd8"}
AM335X_FORMATS = {"kernel": "uimage", "dtb": "fdt", "rootfs": "uimage"}
AM335X_CEILINGS = {"kernel": 0x500000, "dtb": 0x20000, "rootfs": 0x1400000}
# Tier-3 from-stock: same map, mtd4 written with our U-Boot; kernel at order 4.
AM335X_STOCK_MAP = dict(AM335X_MAP)
AM335X_STOCK_MAP["mtd4"] = (0x0080000, 0x1C0000, False, True, 3, "u-boot")
AM335X_STOCK_MAP["mtd7"] = (0x0280000, 0x500000, False, True, 4, "kernel")
AM335X_STOCK_TARGETS = {"u-boot": "mtd4", "kernel": "mtd7", "dtb": "mtd6", "rootfs": "mtd8"}
AM335X_STOCK_FORMATS = {"u-boot": "uimage", "kernel": "uimage", "dtb": "fdt", "rootfs": "uimage"}
AM335X_STOCK_CEILINGS = {"u-boot": 0x1C0000, "kernel": 0x500000, "dtb": 0x20000, "rootfs": 0x1400000}
AM335X_NEVER_WRITE = {"mtd0", "mtd1", "mtd2", "mtd3", "mtd5"}
ZYNQ_FORMATS = {"kernel": "zimage", "dtb": "fdt", "rootfs": "cpio-gzip"}
ZYNQ_CEILINGS = {"kernel": 0x500000, "dtb": 0x20000, "rootfs": 0x2000000}
A113D_FORMATS = {"kernel": "arm64-image", "dtb": "fdt", "rootfs": "uimage"}
A113D_CEILINGS = {"kernel": 0x4000000, "dtb": 0x100000, "rootfs": 0x6000000}
A113D_NVDATA_USABLE = 0xB900000
class AfwError(Exception):
pass
def fail(message):
raise AfwError(message)
def parse_octal(field, name):
text = field.split(b"\0", 1)[0].strip()
if not text:
return 0
if any(byte >= 0x80 for byte in text):
fail(f"{name}: base-256 tar numbers are not part of this format")
try:
return int(text, 8)
except ValueError:
fail(f"{name}: invalid octal field")
def safe_member_name(name):
if not name or len(name) > 255:
fail(f"unsafe member name length: {name!r}")
if name.startswith("/") or name.startswith("./"):
fail(f"absolute or ./-prefixed member is not allowed: {name!r}")
if "\\" in name or "\0" in name:
fail(f"member name contains a forbidden character: {name!r}")
parts = name.split("/")
if any(part in ("", ".", "..") for part in parts):
fail(f"path traversal or empty component in member name: {name!r}")
if any(ord(character) < 0x20 for character in name):
fail(f"control character in member name: {name!r}")
return name
def read_tar(path):
try:
size = path.stat().st_size
except OSError as error:
fail(f"cannot read {path}: {error}")
if size == 0 or size > MAX_ARCHIVE:
fail(f"archive size {size} is outside the accepted range")
if size % BLOCK:
fail(f"archive length {size} is not a multiple of {BLOCK} (truncated tar)")
data = path.read_bytes()
members = []
offset = 0
zero_blocks = 0
while offset < len(data):
block = data[offset : offset + BLOCK]
offset += BLOCK
if block == b"\0" * BLOCK:
zero_blocks += 1
if zero_blocks == 2:
break
continue
if zero_blocks:
fail("non-zero data appears between end-of-archive blocks")
if block[257:262] != b"ustar":
fail("member header is not POSIX ustar")
stored = parse_octal(block[148:156], "tar checksum")
header = bytearray(block)
header[148:156] = b" " * 8
if sum(header) != stored:
fail("tar header checksum mismatch")
name = block[0:100].split(b"\0", 1)[0].decode("utf-8", "strict")
prefix = block[345:500].split(b"\0", 1)[0].decode("utf-8", "strict")
if prefix:
name = f"{prefix}/{name}"
safe_member_name(name)
typeflag = block[156:157]
if typeflag not in (b"\0", b"0"):
fail(f"member {name!r} is not a regular file (typeflag {typeflag!r})")
length = parse_octal(block[124:136], f"size of {name}")
if length > MAX_ARCHIVE:
fail(f"member {name!r} is too large")
padded = (length + BLOCK - 1) // BLOCK * BLOCK
if offset + padded > len(data):
fail(f"member {name!r} runs past the end of the archive (truncated tar)")
payload = data[offset : offset + length]
offset += padded
members.append((name, payload))
if zero_blocks < 2:
fail("archive has no two-block end marker (truncated tar)")
if any(data[offset:]):
fail("non-zero trailing bytes after the end-of-archive marker")
if not members:
fail("archive has no members")
names = [name for name, _ in members]
if len(names) != len(set(names)):
fail("archive has duplicate member names")
return members
def require(condition, message):
if not condition:
fail(message)
def is_hex(value, length=64):
return (
isinstance(value, str)
and len(value) == length
and all(character in "0123456789abcdef" for character in value)
)
def check_format(manifest, image, payload, name):
fmt = image["format"]
if fmt == "fit":
require(payload.startswith(b"\xd0\x0d\xfe\xed"), f"{name} is not a FIT")
require(b"config@cv1835_miner_emmc" in payload, f"{name} has no default CV config")
require(b"signature@" not in payload, f"{name} carries signature@ nodes")
elif fmt == "fdt":
require(payload.startswith(b"\xd0\x0d\xfe\xed"), f"{name} is not an FDT")
elif fmt == "arm64-image":
require(len(payload) >= 64 and payload[0x38:0x3C] == b"ARMd", f"{name} is not an arm64 Image")
elif fmt == "zimage":
# ARM zImage: magic 0x016f2818 (little-endian) at offset 0x24.
require(len(payload) >= 0x28 and payload[0x24:0x28] == b"\x18\x28\x6f\x01",
f"{name} is not an ARM zImage")
elif fmt == "cpio-gzip":
require(payload.startswith(b"\x1f\x8b"), f"{name} is not gzip-compressed")
elif fmt == "uimage":
require(payload.startswith(b"\x27\x05\x19\x56"), f"{name} is not a legacy uImage")
if manifest["board"] in ("am335x", "am335x-stock"):
require(len(payload) >= 64, f"{name} has no complete uImage header")
# ih_arch (byte 29) ARM = 2; ih_type (byte 30): kernel 2, ramdisk 3,
# firmware (our U-Boot in mtd4) 5.
require(payload[29] == 2, f"{name} is not an ARM uImage")
if image["name"] == "rootfs" or image["role"] == "rootfs":
require(payload[30] == 3, f"{name} must be a type-3 ramdisk uImage")
elif image["name"] == "u-boot" or image["role"] == "bootloader":
require(payload[30] == 5, f"{name} must be a type-5 firmware (U-Boot) uImage")
else:
require(payload[30] == 2, f"{name} must be a type-2 kernel uImage")
def verify_signature(manifest_bytes, manifest, signature_member, public_key):
signature = manifest.get("signature")
require(isinstance(signature, dict), "manifest signature is not an object")
kind = signature.get("type")
if kind == "unsigned":
require(signature_member is None, "unsigned manifest carries a signature member")
require(signature.get("member") is None, "unsigned manifest names a signature member")
return "unsigned"
require(kind == "ed25519", f"unsupported signature type {kind!r}")
require(signature.get("member") == "manifest.json.sig", "signature member name is wrong")
require(signature_member is not None, "ed25519 manifest has no signature member")
require(len(signature_member) == 64, "manifest.json.sig must be exactly 64 bytes")
key_hex = public_key or signature.get("public_key_hex")
require(is_hex(key_hex), "ed25519 manifest needs a 32-byte public key")
if public_key and signature.get("public_key_hex") not in (None, public_key):
fail("--public-key differs from the manifest public_key_hex")
try:
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
except ImportError:
fail("Ed25519 verification needs the Python cryptography package")
try:
Ed25519PublicKey.from_public_bytes(bytes.fromhex(key_hex)).verify(
signature_member, manifest_bytes
)
except InvalidSignature:
fail("manifest.json.sig does not verify against the public key")
return "ed25519"
def validate_am335x(manifest, images, partitions, install_images):
require(manifest["arch"] == "arm", "am335x must be arm")
require(
manifest["bootloader_policy"] == "preserve",
"am335x must preserve mtd0-5",
)
for image in images:
lowered = f"{image['name']} {image['file']}".lower()
require(
"spl" not in lowered and "u-boot" not in lowered and "uboot" not in lowered,
f"am335x bundle carries an spl/u-boot member: {image['file']!r}",
)
require(len(install_images) == 3, "am335x installs exactly kernel, dtb and rootfs")
require(
{image["name"] for image in install_images} == set(AM335X_TARGETS),
"am335x install images must be named kernel, dtb and rootfs",
)
for image in install_images:
name = image["name"]
require(
image["format"] == AM335X_FORMATS[name],
f"am335x {name} format must be {AM335X_FORMATS[name]}",
)
require(
image["partition"] == AM335X_TARGETS[name],
f"am335x {name} must target {AM335X_TARGETS[name]}",
)
require(
image["size"] <= AM335X_CEILINGS[name],
f"am335x {name} ({image['size']} B) exceeds the "
f"0x{AM335X_CEILINGS[name]:x}-byte mtd ceiling",
)
seen = {}
for partition in partitions:
name = partition["name"]
require(name in AM335X_MAP, f"unknown am335x partition {name!r}")
if name not in AM335X_MAP:
continue
seen[name] = partition
offset, size, secure, boot_critical, write_order, image_name = AM335X_MAP[name]
require(partition["offset"] == offset, f"am335x {name} offset must be 0x{offset:x}")
require(partition["size"] == size, f"am335x {name} size must be 0x{size:x}")
require(partition["secure"] is secure, f"am335x {name} secure flag is wrong")
require(
partition["boot_critical"] is boot_critical,
f"am335x {name} boot_critical flag is wrong",
)
require(
partition["write_order"] == write_order,
f"am335x {name} write_order must be {write_order}",
)
require(
partition.get("image") == image_name,
f"am335x {name} image must be {image_name!r}",
)
start = partition["offset"]
end = start + partition["size"]
hole_start, hole_size = AM335X_HOLE
require(
not (start < hole_start + hole_size and end > hole_start),
f"am335x {name} overlaps the 0x780000-0x800000 hole",
)
if name in {f"mtd{index}" for index in range(0, 6)}:
require(
partition["write_order"] == 0 and partition.get("image") is None,
f"am335x {name} is preserved and must not be written",
)
require(set(seen) == set(AM335X_MAP), "am335x manifest partition map is incomplete")
require(
seen["mtd7"]["offset"] + seen["mtd7"]["size"] == AM335X_HOLE[0],
"am335x mtd7 must end at the 0x780000 hole",
)
require(
seen["mtd8"]["offset"] == AM335X_HOLE[0] + AM335X_HOLE[1],
"am335x mtd8 must start at 0x800000 after the hole",
)
total = sum(part["size"] for part in partitions)
require(total == AM335X_CHIP - AM335X_HOLE[1], "am335x partition sizes must sum to 0x7F80000")
def validate_am335x_stock(manifest, images, partitions, install_images):
"""Tier-3 from-stock gate: the bundle writes mtd4 (our U-Boot) but must
still never touch an SPL copy, and the geometry/ceilings/hole stay exact."""
require(manifest["arch"] == "arm", "am335x-stock must be arm")
require(
manifest["bootloader_policy"] == "include",
"am335x-stock must declare bootloader_policy include",
)
# A u-boot member is expected; a loose spl member never is.
for image in images:
lowered = f"{image['name']} {image['file']}".lower()
require("spl" not in lowered, f"am335x-stock bundle carries an spl member: {image['file']!r}")
require(len(install_images) == 4, "am335x-stock installs exactly u-boot, kernel, dtb and rootfs")
require(
{image["name"] for image in install_images} == set(AM335X_STOCK_TARGETS),
"am335x-stock install images must be named u-boot, kernel, dtb and rootfs",
)
for image in install_images:
name = image["name"]
require(
image["format"] == AM335X_STOCK_FORMATS[name],
f"am335x-stock {name} format must be {AM335X_STOCK_FORMATS[name]}",
)
require(
image["partition"] == AM335X_STOCK_TARGETS[name],
f"am335x-stock {name} must target {AM335X_STOCK_TARGETS[name]}",
)
require(
image["size"] <= AM335X_STOCK_CEILINGS[name],
f"am335x-stock {name} ({image['size']} B) exceeds the "
f"0x{AM335X_STOCK_CEILINGS[name]:x}-byte ceiling",
)
uboot = [image for image in install_images if image["name"] == "u-boot"][0]
require(uboot["role"] == "bootloader", "am335x-stock u-boot image must have role bootloader")
seen = {}
for partition in partitions:
name = partition["name"]
require(name in AM335X_STOCK_MAP, f"unknown am335x-stock partition {name!r}")
seen[name] = partition
offset, size, secure, boot_critical, write_order, image_name = AM335X_STOCK_MAP[name]
require(partition["offset"] == offset, f"am335x-stock {name} offset must be 0x{offset:x}")
require(partition["size"] == size, f"am335x-stock {name} size must be 0x{size:x}")
require(partition["secure"] is secure, f"am335x-stock {name} secure flag is wrong")
require(
partition["boot_critical"] is boot_critical,
f"am335x-stock {name} boot_critical flag is wrong",
)
require(
partition["write_order"] == write_order,
f"am335x-stock {name} write_order must be {write_order}",
)
require(partition.get("image") == image_name, f"am335x-stock {name} image must be {image_name!r}")
start = partition["offset"]
end = start + partition["size"]
if start < AM335X_HOLE[0] + AM335X_HOLE[1] and end > AM335X_HOLE[0]:
fail(f"am335x-stock {name} overlaps the 0x780000-0x800000 hole")
if name in AM335X_NEVER_WRITE and (write_order != 0 or partition.get("image") is not None):
fail(f"am335x-stock {name} is preserved and must not be written")
require(set(seen) == set(AM335X_STOCK_MAP), "am335x-stock manifest partition map is incomplete")
require(
seen["mtd7"]["offset"] + seen["mtd7"]["size"] == AM335X_HOLE[0],
"am335x-stock mtd7 must end at the 0x780000 hole",
)
require(
seen["mtd8"]["offset"] == AM335X_HOLE[0] + AM335X_HOLE[1],
"am335x-stock mtd8 must start at 0x800000 after the hole",
)
total = sum(part["size"] for part in partitions)
require(total == AM335X_CHIP - AM335X_HOLE[1], "am335x-stock partition sizes must sum to 0x7F80000")
def validate(path, allow_unsigned=False, public_key=None, expect_board=None, plan_path=None):
members = read_tar(Path(path))
if members[0][0] != "manifest.json":
fail("first member must be manifest.json")
manifest_bytes = members[0][1]
if len(manifest_bytes) > MAX_MANIFEST:
fail(f"manifest.json is {len(manifest_bytes)} bytes, over the 64 KiB cap")
try:
manifest = json.loads(manifest_bytes)
except (ValueError, UnicodeDecodeError) as error:
fail(f"manifest.json is not valid JSON: {error}")
require(isinstance(manifest, dict), "manifest.json must be an object")
required = (
"schema",
"format",
"board",
"arch",
"version",
"build_date",
"sdk_revision",
"os_revision",
"payload_type",
"bootloader_policy",
"signature",
"partitions",
"images",
"boot_switch",
"preflight",
"recovery",
"marker",
"kernel_version",
)
for key in required:
require(key in manifest, f"manifest is missing {key!r}")
require(manifest["schema"] == 2, "only .afw schema 2 is accepted")
require(manifest["format"] == "afw", "manifest format is not afw")
require(manifest["payload_type"] == "os", "payload_type must be os")
board = manifest["board"]
require(afw_boards.known_board(board), f"unknown board family {board!r}")
profile = afw_boards.board(board)
require(manifest["arch"] == profile["arch"], f"board {board} must use {profile['arch']}")
require(
manifest["bootloader_policy"] == profile["bootloader_policy"],
f"board {board} requires bootloader_policy {profile['bootloader_policy']}",
)
require(
manifest["bootloader_policy"] in ("include", "preserve"),
"bootloader_policy must be include or preserve",
)
if expect_board is not None:
require(board == expect_board, f"bundle is for {board}, expected {expect_board}")
for field in ("sdk_revision", "os_revision"):
require(is_hex(manifest[field], 40), f"{field} must be a 40-character revision")
require(isinstance(manifest["version"], str) and manifest["version"], "version is empty")
require(isinstance(manifest["build_date"], str) and manifest["build_date"], "build_date is empty")
require(isinstance(manifest["marker"], str) and manifest["marker"], "marker is empty")
require(
isinstance(manifest["kernel_version"], str) and manifest["kernel_version"],
"kernel_version is empty",
)
for field in ("boot_switch", "preflight", "recovery"):
require(isinstance(manifest[field], dict), f"{field} must be an object")
images = manifest["images"]
partitions = manifest["partitions"]
require(isinstance(images, list) and images, "images must be a non-empty list")
require(isinstance(partitions, list) and partitions, "partitions must be a non-empty list")
image_names = set()
install_images = []
for image in images:
require(isinstance(image, dict), "image entry is not an object")
for key in ("name", "file", "role", "format", "size", "sha256", "install"):
require(key in image, f"image entry is missing {key!r}")
name = image["name"]
require(isinstance(name, str) and name and name not in image_names, f"duplicate image {name!r}")
image_names.add(name)
require(image["role"] in afw_boards.SAFE_IMAGE_ROLES, f"image {name} has an unknown role")
require(image["format"] in afw_boards.SAFE_IMAGE_FORMATS, f"image {name} has an unknown format")
require(isinstance(image["size"], int) and image["size"] > 0, f"image {name} has no size")
require(is_hex(image["sha256"]), f"image {name} has no sha256")
require(isinstance(image["install"], bool), f"image {name} install flag is not a bool")
safe_member_name(image["file"])
require(image["file"].startswith("payload/"), f"image {name} is outside payload/")
require(image["file"] not in ("payload/manifest.json",), f"image {name} reuses a reserved name")
if image["install"]:
require(image.get("partition"), f"installable image {name} has no partition")
install_images.append(image)
require(install_images, "bundle has no installable image")
partition_names = set()
for partition in partitions:
require(isinstance(partition, dict), "partition entry is not an object")
for key in ("name", "device", "offset", "size", "secure", "boot_critical", "write_order"):
require(key in partition, f"partition entry is missing {key!r}")
name = partition["name"]
require(isinstance(name, str) and name and name not in partition_names, f"duplicate partition {name!r}")
partition_names.add(name)
device = partition["device"]
require(isinstance(device, str) and device.startswith("/dev/"), f"partition {name} has a bad device")
require(isinstance(partition["size"], int) and partition["size"] > 0, f"partition {name} has no size")
require(partition["offset"] >= 0, f"partition {name} has a negative offset")
require(isinstance(partition["secure"], bool), f"partition {name} secure is not a bool")
require(isinstance(partition["boot_critical"], bool), f"partition {name} boot_critical is not a bool")
require(isinstance(partition["write_order"], int) and partition["write_order"] >= 0, f"partition {name} write_order")
if "boot0" in device:
require(partition["secure"], "boot0 must be declared secure")
require(partition["write_order"] == 0, "boot0 must not be in the write order")
require(partition.get("image") is None, "boot0 must not carry an install image")
image_name = partition.get("image")
if image_name is not None:
require(image_name in image_names, f"partition {name} names missing image {image_name!r}")
for image in images:
if image.get("partition") is None:
continue
matches = [item for item in partitions if item["name"] == image["partition"]]
require(len(matches) == 1, f"image {image['name']} names an unknown partition")
partition = matches[0]
require(not partition["secure"], f"image {image['name']} targets a secure partition")
require(
image["size"] <= partition["size"],
f"image {image['name']} ({image['size']} B) exceeds partition "
f"{partition['name']} ({partition['size']} B)",
)
if board == "am335x":
validate_am335x(manifest, images, partitions, install_images)
if board == "am335x-stock":
validate_am335x_stock(manifest, images, partitions, install_images)
if board == "a113d":
require(manifest["arch"] == "arm64", "a113d must be arm64")
require(manifest["bootloader_policy"] == "preserve", "a113d must preserve the FIP bootloader")
for image in images:
lowered = f"{image['name']} {image['file']} {image['role']}".lower()
require(
"spl" not in lowered and "u-boot" not in lowered and "uboot" not in lowered
and "fip" not in lowered and "tpl" not in lowered and image["role"] != "bootloader",
f"a113d bundle carries a bootloader/spl/fip member: {image['file']!r}",
)
require(len(install_images) == 3, "a113d installs exactly kernel, dtb and rootfs")
require(
{image["name"] for image in install_images} == set(A113D_FORMATS),
"a113d install images must be named kernel, dtb and rootfs",
)
total = 0
for image in install_images:
name = image["name"]
require(image["format"] == A113D_FORMATS[name], f"a113d {name} format must be {A113D_FORMATS[name]}")
require(
image["size"] <= A113D_CEILINGS[name],
f"a113d {name} ({image['size']} B) exceeds the 0x{A113D_CEILINGS[name]:x}-byte ceiling",
)
total += image["size"]
require(total <= A113D_NVDATA_USABLE, f"a113d images total {total} B exceed the nvdata UBI (0x{A113D_NVDATA_USABLE:x})")
# Only nvdata (mtd6) may carry an image; mtd0-5 (FIP + stock boot) are preserved.
for partition in partitions:
if partition["name"] != "nvdata":
require(partition.get("image") is None, f"a113d {partition['name']!r} is preserved and must not carry an image")
if board == "zynq-7010":
require(manifest["arch"] == "armv7", "zynq-7010 must be armv7")
require(manifest["bootloader_policy"] == "preserve", "zynq-7010 must preserve BOOT.bin")
for image in images:
lowered = f"{image['name']} {image['file']} {image['role']}".lower()
require(
"spl" not in lowered and "u-boot" not in lowered and "uboot" not in lowered
and "boot.bin" not in lowered and image["role"] != "bootloader",
f"zynq-7010 bundle carries a bootloader/spl member: {image['file']!r}",
)
require(len(install_images) == 3, "zynq-7010 installs exactly kernel, dtb and rootfs")
require(
{image["name"] for image in install_images} == set(ZYNQ_FORMATS),
"zynq-7010 install images must be named kernel, dtb and rootfs",
)
for image in install_images:
name = image["name"]
require(
image["format"] == ZYNQ_FORMATS[name],
f"zynq-7010 {name} format must be {ZYNQ_FORMATS[name]}",
)
require(
image["size"] <= ZYNQ_CEILINGS[name],
f"zynq-7010 {name} ({image['size']} B) exceeds the "
f"0x{ZYNQ_CEILINGS[name]:x}-byte ceiling",
)
if board == "cv1835":
require(len(install_images) == 1 and install_images[0]["name"] == "p1", "cv1835 installs only p1")
p1 = install_images[0]
require(p1["format"] == "fit", "cv1835 p1 must be a FIT")
require(p1["size"] == 16 * 1024 * 1024, "cv1835 p1 must be the 16 MiB padded FIT")
p1_parts = [item for item in partitions if item["name"] == "p1"]
require(len(p1_parts) == 1, "cv1835 manifest must plan p1")
require(p1_parts[0]["size"] == 16 * 1024 * 1024, "cv1835 p1 partition must be 16 MiB")
require(p1_parts[0]["device"] == "/dev/mmcblk0p1", "cv1835 p1 device is wrong")
require(not p1_parts[0]["secure"], "cv1835 p1 must not be secure")
require(p1_parts[0]["write_order"] == 1, "cv1835 p1 must be written once")
if manifest["bootloader_policy"] == "preserve":
require(
not any(image["role"] == "bootloader" for image in images),
"bootloader_policy is preserve but the bundle carries a bootloader image",
)
else:
require(
any(image["role"] == "bootloader" for image in images),
"bootloader_policy is include but the bundle has no bootloader image",
)
signature = manifest["signature"]
require(isinstance(signature, dict), "signature must be an object")
kind = signature.get("type")
if kind == "unsigned":
if not allow_unsigned:
fail("bundle is unsigned; pass --allow-unsigned for bench-only use")
elif kind != "ed25519":
fail(f"unsupported signature type {kind!r}")
expected = [image["file"] for image in images]
signature_member = None
body = members[1:]
if signature.get("member") is not None:
require(len(body) >= 1 and body[0][0] == "manifest.json.sig", "signature member must be second")
signature_member = body[0][1]
body = body[1:]
verify_signature(manifest_bytes, manifest, signature_member, public_key)
actual = [name for name, _ in body]
require(actual == expected, "payload members are missing, extra, or out of manifest order")
for (name, payload), image in zip(body, images):
require(len(payload) == image["size"], f"size mismatch for {name}")
digest = hashlib.sha256(payload).hexdigest()
require(digest == image["sha256"], f"sha256 mismatch for {name}")
check_format(manifest, image, payload, name)
summary = {
"file": str(path),
"board": board,
"arch": manifest["arch"],
"version": manifest["version"],
"bootloader_policy": manifest["bootloader_policy"],
"signature": kind,
"marker": manifest["marker"],
"kernel_version": manifest["kernel_version"],
"members": [name for name, _ in members],
"payloads": [
{"name": image["name"], "file": image["file"], "size": image["size"], "sha256": image["sha256"]}
for image in images
],
"install": [
{
"image": image["name"],
"partition": image["partition"],
"size": image["size"],
}
for image in install_images
],
}
if plan_path:
plan = json.loads(Path(plan_path).read_text())
require(plan.get("board") == board, "plan board differs from manifest board")
require(plan.get("arch") == manifest["arch"], "plan arch differs from manifest arch")
require(
plan.get("bootloader_policy") == manifest["bootloader_policy"],
"plan bootloader policy differs from manifest",
)
plan_parts = {item["name"]: item for item in plan.get("partitions", [])}
for partition in partitions:
if partition["name"] not in plan_parts:
continue
require(
int(plan_parts[partition["name"]]["size"]) == partition["size"],
f"plan size for {partition['name']} differs from the manifest",
)
return summary
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("afw")
parser.add_argument("--allow-unsigned", action="store_true")
parser.add_argument("--public-key", help="Ed25519 public key hex, or a file containing it")
parser.add_argument("--expect-board")
parser.add_argument("--plan", help="plan JSON to cross-check")
parser.add_argument("--json", action="store_true")
parser.add_argument("--quiet", action="store_true")
args = parser.parse_args()
public_key = args.public_key
if public_key and len(public_key) != 64:
try:
public_key = Path(public_key).read_text().strip()
except OSError as error:
parser.error(f"cannot read public key: {error}")
try:
summary = validate(
Path(args.afw),
allow_unsigned=args.allow_unsigned,
public_key=public_key,
expect_board=args.expect_board,
plan_path=args.plan,
)
except AfwError as error:
print(f"afw: FAIL {args.afw}: {error}", file=sys.stderr)
return 1
except (OSError, ValueError) as error:
print(f"afw: FAIL {args.afw}: {error}", file=sys.stderr)
return 1
if args.json:
print(json.dumps(summary, indent=2))
elif not args.quiet:
print(f"afw: OK {args.afw}")
print(
f" board {summary['board']} arch {summary['arch']} version {summary['version']} "
f"bootloader {summary['bootloader_policy']} signature {summary['signature']}"
)
print(f" marker {summary['marker']} kernel {summary['kernel_version']}")
for item in summary["payloads"]:
print(f" payload {item['name']}: {item['size']} B sha256 {item['sha256']}")
for item in summary["install"]:
print(f" install {item['image']} -> {item['partition']} ({item['size']} B)")
return 0
if __name__ == "__main__":
sys.exit(main())
+92
View File
@@ -0,0 +1,92 @@
#!/bin/sh
# Refuse to publish an OS image whose payload would not fit, or would not boot,
# on the board it claims to target.
#
# The SDK's planner refuses a bad payload before it is ever written; this is the
# other half of the same rule, applied to the artefacts the OS repo produces. A
# wrongly-formatted image is not a firmware bug a board survives: the vendor SPL
# only parses a legacy uImage, stock U-Boot only parses a legacy uImage, and a
# raw zImage in the wrong slot boots nothing.
#
# Checks, per payload file found:
# * magic matches the format its name claims
# * size fits the target partition
# A file that is present but unreadable, or that claims a format it does not
# have, fails the gate. When no payload artefacts exist yet the gate says so and
# passes, so it can be wired into CI before the first image is built.
set -eu
fail=0
note() { printf ' %s\n' "$*"; }
bad() { printf ' FAIL %s\n' "$*"; fail=1; }
# name-glob|format|max-bytes
RULES='
kernel-mtd8.zImage|zimage|20971520
zImage|zimage|20971520
Image|zimage|16777216
dtb-mtd6.dtb|fdt|131072
am335x-alkane.dtb|fdt|131072
meson-axg-alkane.dtb|fdt|131072
ramdisk-mtd7.uimg|uimage|5242880
uramdisk.image.gz|uimage|8388608
uboot-mtd4.img|uimage|1835008
'
check_file() {
file=$1
name=$(basename "$file")
size=$(wc -c < "$file")
rule=$(printf '%s\n' "$RULES" | awk -F'|' -v n="$name" '$1 == n { print; exit }')
if [ -z "$rule" ]; then
return 0
fi
format=$(printf '%s' "$rule" | cut -d'|' -f2)
limit=$(printf '%s' "$rule" | cut -d'|' -f3)
if [ "$size" -gt "$limit" ]; then
bad "$name is $size bytes, larger than its $limit-byte partition"
return 0
fi
magic=$(od -An -tx1 -N4 "$file" | tr -d ' \n')
case "$format" in
fdt)
[ "$magic" = "d00dfeed" ] || bad "$name does not start with the FDT magic (got $magic)"
;;
uimage)
[ "$magic" = "27051956" ] || bad "$name is not a legacy uImage (got $magic)"
;;
zimage)
# ARM zImage: 0x016f2818 at offset 0x24, stored little-endian on disk.
z=$(od -An -tx1 -j36 -N4 "$file" | tr -d ' \n')
[ "$z" = "18286f01" ] || bad "$name is not a raw ARM zImage (got $z at 0x24)"
;;
esac
note "$name: $format, $size bytes"
}
echo "image-safety: scanning for payload artefacts"
found=0
for dir in "${1:-.}" dist build/out target/payload; do
[ -d "$dir" ] || continue
for file in $(find "$dir" -maxdepth 3 -type f \
\( -name 'kernel-mtd8.zImage' -o -name 'zImage' -o -name 'Image' \
-o -name 'dtb-mtd6.dtb' -o -name 'am335x-alkane.dtb' \
-o -name 'meson-axg-alkane.dtb' -o -name 'ramdisk-mtd7.uimg' \
-o -name 'uramdisk.image.gz' -o -name 'uboot-mtd4.img' \) 2>/dev/null); do
found=$((found + 1))
check_file "$file"
done
done
if [ "$found" -eq 0 ]; then
note "no payload artefacts present in this checkout"
else
note "$found payload file(s) checked"
fi
if [ "$fail" -ne 0 ]; then
echo "image-safety: FAILED - do not publish this image" >&2
exit 1
fi
echo "image-safety: OK"
+39
View File
@@ -0,0 +1,39 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Keep OS jobs on the verified Alkane runner image."""
from pathlib import Path
import re
import sys
import yaml
ROOT = Path(__file__).resolve().parents[1]
IMAGE = (ROOT / "ci/runner-image.txt").read_text().strip()
def main() -> int:
if not re.fullmatch(
r"gitea\.bluefla\.re/blueflare/alkane-ci@sha256:[0-9a-f]{64}", IMAGE
):
print("Runner image must be pinned by Gitea registry digest", file=sys.stderr)
return 1
for path in sorted((ROOT / ".gitea/workflows").glob("*.yml")):
workflow = yaml.load(path.read_text(), Loader=yaml.BaseLoader)
for name, job in workflow.get("jobs", {}).items():
if (job.get("runs-on") in {"alkane-fast", "alkane-pages"}
and "secrets." in str(job)):
print(f"{path.name}: {name} exposes a secret to the fast runner", file=sys.stderr)
return 1
if job.get("runs-on") not in {"alkane-ci", "alkane-fast", "alkane-verify"}:
continue
if job.get("container", {}).get("image") != IMAGE:
print(f"{path.name}: {name} has a different runner image", file=sys.stderr)
return 1
print("OS runner image pins: PASS")
return 0
if __name__ == "__main__":
raise SystemExit(main())
+37
View File
@@ -0,0 +1,37 @@
#!/bin/sh
# Report what the schema-driven UI costs in a firmware binary.
#
# Two binaries are built for the same target with the same profile: one renders
# a page through flare-ui and wschema, the other renders the same shape with only
# maud and serde_json. The difference is the marginal cost of the dependency, and
# it is the number a release decision should be made on.
#
# Measured on armv7-unknown-linux-gnueabihf, release, stripped:
# ui-baseline 323 KiB
# ui-spike 771 KiB (marginal: ~448 KiB)
set -eu
ROOT=${1:-$(cd "$(dirname "$0")/.." && pwd)}
TARGET=${ALKANE_SIZE_TARGET:-armv7-unknown-linux-gnueabihf}
OUT=${CARGO_TARGET_DIR:-/tmp/alkane-os-target}
STRIP=${ALKANE_STRIP:-arm-linux-gnueabihf-strip}
cd "$ROOT"
# The workspace mount drops the executable bit on build scripts, so build into
export CARGO_TARGET_DIR="$OUT"
CARGO_TARGET_ARMV7_UNKNOWN_LINUX_GNUEABIHF_LINKER=${ALKANE_ARM_LINKER:-arm-linux-gnueabihf-gcc} \
cargo build --release --offline --target "$TARGET" --bins >/dev/null
sizes=""
for bin in ui-baseline ui-spike; do
src="$OUT/$TARGET/release/$bin"
[ -f "$src" ] || { echo "ui-size: $bin was not built" >&2; exit 1; }
cp "$src" "/tmp/$bin.size"
"$STRIP" "/tmp/$bin.size" 2>/dev/null || true
bytes=$(wc -c < "/tmp/$bin.size")
sizes="$sizes $bin=$bytes"
printf ' %-12s %4d KiB\n' "$bin" $((bytes / 1024))
done
base=$(printf '%s' "$sizes" | sed 's/.*ui-baseline=\([0-9]*\).*/\1/')
spike=$(printf '%s' "$sizes" | sed 's/.*ui-spike=\([0-9]*\).*/\1/')
printf ' marginal %4d KiB\n' $(((spike - base) / 1024))
+2 -1
View File
@@ -10,7 +10,8 @@ import sys
ROOT = Path(__file__).resolve().parents[1]
DIRECTORIES = ("target", "coverage", "dist", "bench-site")
FILES = ("tests-current.txt", "bench-current.txt", "quality-current.json")
FILES = ("tests-current.txt", "bench-current.txt", "quality-current.json",
"evidence-status-current.json")
def cleanup() -> None:
+84
View File
@@ -0,0 +1,84 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Summarize research separately from current-run release conformance."""
import argparse
import json
from pathlib import Path
import re
LEVELS = {"catalogued", "protocol_decoded"}
DIGEST = re.compile(r"[0-9a-f]{64}\Z")
def summarize(matrix: dict, research: dict) -> dict:
if matrix.get("schema") != 1 or research.get("schema") != 1:
raise ValueError("unsupported evidence schema")
boards = matrix["boards"]
chips = matrix["chips"]
vendors = matrix["vendors"]
expected = {(board, chip) for board in boards for chip in chips
if vendors[board] == vendors[chip]}
rows = matrix["targets"]
actual = [(row["board"], row["chip"]) for row in rows]
if set(actual) != expected or len(actual) != len(expected) or len(actual) != 64:
raise ValueError("release target matrix is incomplete or duplicated")
levels = {"catalogued": set(), "protocol_decoded": set()}
for claim in research["claims"]:
cell = claim["board"], claim["chip"]
level = claim["level"]
if cell not in expected or level not in LEVELS:
raise ValueError("research claim is outside target matrix or level")
if not isinstance(claim.get("scope"), str) or not claim["scope"].strip():
raise ValueError("research claim lacks scope")
if not isinstance(claim.get("source"), str) or not claim["source"].strip():
raise ValueError("research claim lacks provenance")
if not isinstance(claim.get("sha256"), str) or not DIGEST.fullmatch(claim["sha256"]):
raise ValueError("research claim lacks a source digest")
levels[level].add(cell)
declared = {
"stock_result": sum(row.get("stock_result") in {"mines", "rejects"} for row in rows),
"alkane_share_capture": sum(bool(row.get("alkane_share_accept_capture")) for row in rows),
"bench_validation": sum(bool(row.get("bench_validation")) for row in rows),
}
evidence_levels = {
"catalogued": {"research_claims": len(levels["catalogued"])},
"protocol_decoded": {"research_claims": len(levels["protocol_decoded"])},
"stock_simulator_boot": {"manifest_claims_unverified": declared["stock_result"],
"current_run_verified": None},
"captured_nonce_pool_accept": {
"manifest_claims_unverified": declared["alkane_share_capture"],
"current_run_verified": None},
"physical_install_update_uninstall_recovery": {
"manifest_claims_unverified": declared["bench_validation"],
"current_run_verified": None},
"full_release_cell": {"current_run_verified": None},
}
return {
"schema": 1,
"target_cells": len(expected),
"research_only": {key: len(value) for key, value in levels.items()},
"evidence_levels": evidence_levels,
"release_manifest_declarations_unverified": declared,
"verified_release_cells": None,
"note": "Only check-conformance.py may verify current-run artifacts; research claims never satisfy a release cell",
}
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--matrix", type=Path, default=Path("ci/conformance.json"))
parser.add_argument("--research", type=Path, default=Path("ci/research-evidence.json"))
parser.add_argument("--output", type=Path)
args = parser.parse_args()
report = summarize(json.loads(args.matrix.read_text()), json.loads(args.research.read_text()))
output = json.dumps(report, indent=2, sort_keys=True) + "\n"
if args.output:
args.output.write_text(output)
else:
print(output, end="")
if __name__ == "__main__":
main()
+65
View File
@@ -0,0 +1,65 @@
{
"schema": 1,
"experiments": [
{
"id": "am335x-original-nand-boot",
"kind": "controller",
"board": "am335x-bb",
"chip": null,
"psu": null,
"state": "ready_local",
"next_evidence": "Boot hash-pinned stock NAND through the original ROM and SPL path; record the first failing register",
"blocker": null
},
{
"id": "bm1368-command-and-nonce",
"kind": "chip",
"board": null,
"chip": "BM1368",
"psu": null,
"state": "needs_machine",
"next_evidence": "Capture real BM1368 enumeration, job, and nonce frames on a recovered test unit",
"blocker": "No verified BM1368 silicon candidate in the current inventory"
},
{
"id": "zynq-bm1366-fpga-window",
"kind": "transport",
"board": "zynq-7010",
"chip": "BM1366",
"psu": "APW121215d/e",
"state": "needs_identity",
"next_evidence": "Read a bounded FPGA register/FIFO trace on a verified rooted test unit",
"blocker": "Historical mule 10.1.2.137 now reports BTM_S21PRO; do not infer BM1366 from its address"
},
{
"id": "a113d-bm1370-apw17-voltage",
"kind": "psu",
"board": "a113d",
"chip": "BM1370",
"psu": "APW171215a/c",
"state": "needs_identity",
"next_evidence": "Decode captured GPIO bit-bang command and read-only voltage response against an independent meter",
"blocker": "Historical 10.4.0.192 unit is not currently reachable for confirmation"
},
{
"id": "h6-kf1950-power-and-asic",
"kind": "chip_psu",
"board": "allwinner-h6",
"chip": "KF1950",
"psu": "unknown",
"state": "needs_machine",
"next_evidence": "Observe actual ASIC and PSU bus frames on a matched miner before modeling either device",
"blocker": "Current H6 bench board is bare and its recovery RX path is unproven"
},
{
"id": "s19-88-chain-enumeration",
"kind": "topology_psu",
"board": "a113d",
"chip": "BM1362",
"psu": "APW121417b",
"state": "needs_identity",
"next_evidence": "Capture the 88-chip address walk and read-only PSU identity on a rooted matched test unit",
"blocker": "10.7.1.190 reports BTM_S19_88, but its SSH key and physical recovery are unverified"
}
]
}
+62
View File
@@ -0,0 +1,62 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Rank representative experiments without changing the 64-cell release gate."""
import argparse
import json
from pathlib import Path
STATES = {"ready_local", "needs_identity", "needs_machine"}
def rank(matrix: dict, queue: dict) -> list[dict]:
if queue.get("schema") != 1 or matrix.get("schema") != 1:
raise ValueError("unsupported experiment schema")
targets = {(row["board"], row["chip"]) for row in matrix["targets"]}
if len(targets) != 64 or len(matrix["targets"]) != 64:
raise ValueError("expected 64 unique release targets")
seen = set()
result = []
for experiment in queue["experiments"]:
ident = experiment["id"]
if ident in seen:
raise ValueError("duplicate experiment id")
seen.add(ident)
state = experiment["state"]
if state not in STATES:
raise ValueError("unknown experiment state")
board, chip = experiment["board"], experiment["chip"]
if board is None and chip is None:
raise ValueError("experiment has no target selector")
affected = sorted((b, c) for b, c in targets
if (board is None or board == b) and (chip is None or chip == c))
if not affected:
raise ValueError("experiment selects no same-vendor target")
if not experiment.get("next_evidence"):
raise ValueError("experiment lacks a measurable next result")
if state != "ready_local" and not experiment.get("blocker"):
raise ValueError("blocked experiment lacks a blocker")
result.append({"id": ident, "kind": experiment["kind"], "state": state,
"affected_release_cells": len(affected), "board": board,
"chip": chip, "psu": experiment["psu"],
"next_evidence": experiment["next_evidence"],
"blocker": experiment["blocker"]})
return sorted(result, key=lambda row: (row["state"] != "ready_local",
-row["affected_release_cells"], row["id"]))
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--matrix", type=Path, default=Path("ci/conformance.json"))
parser.add_argument("--queue", type=Path, default=Path("ci/experiment-queue.json"))
args = parser.parse_args()
for item in rank(json.loads(args.matrix.read_text()), json.loads(args.queue.read_text())):
print(f"{item['id']}: {item['state']}, {item['affected_release_cells']} cells")
print(f" next: {item['next_evidence']}")
if item["blocker"]:
print(f" blocked: {item['blocker']}")
if __name__ == "__main__":
main()
Executable
+146
View File
@@ -0,0 +1,146 @@
#!/usr/bin/env bash
# Build a full-OS .afw install bundle for one board family.
#
# A .afw is a strict POSIX ustar with members in this exact order:
# manifest.json
# manifest.json.sig (only for an Ed25519-signed bundle)
# payload/<image>... (in manifest.images order)
#
# The manifest carries the board, arch, SDK/OS revisions, every image's size
# and SHA-256, the partition plan, bootloader_policy, the network recovery path
# and a liveness marker. ci/check-afw.py verifies the finished bundle before
# this script returns success. There is no default signing key: unsigned is
# allowed only with an explicit --allow-unsigned, and that is bench-only.
#
# usage:
# ci/make-afw.sh --board cv1835 --version 0.1.0 \
# --input build/out/cv1835 --sdk-dir ../alkane-sdk \
# --sdk-revision "$(git -C ../alkane-sdk rev-parse HEAD)" \
# --os-revision "$(git rev-parse HEAD)" \
# --output dist [--plan plan.json] [--signing-key FILE] [--allow-unsigned]
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
BOARD=
VERSION=
INPUT=
OUTPUT=dist
PLAN=
SIGNING_KEY=
SDK_DIR=
SDK_REVISION=
OS_REVISION=
KERNEL_VERSION=
ALLOW_UNSIGNED=0
usage() {
sed -n '2,30p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
exit "${1:-1}"
}
while [ "$#" -gt 0 ]; do
case "$1" in
--board) BOARD=${2:?--board needs a value}; shift 2 ;;
--version) VERSION=${2:?--version needs a value}; shift 2 ;;
--input) INPUT=${2:?--input needs a value}; shift 2 ;;
--output) OUTPUT=${2:?--output needs a value}; shift 2 ;;
--plan) PLAN=${2:?--plan needs a value}; shift 2 ;;
--signing-key) SIGNING_KEY=${2:?--signing-key needs a value}; shift 2 ;;
--sdk-dir) SDK_DIR=${2:?--sdk-dir needs a value}; shift 2 ;;
--sdk-revision) SDK_REVISION=${2:?--sdk-revision needs a value}; shift 2 ;;
--os-revision) OS_REVISION=${2:?--os-revision needs a value}; shift 2 ;;
--kernel-version) KERNEL_VERSION=${2:?--kernel-version needs a value}; shift 2 ;;
--allow-unsigned) ALLOW_UNSIGNED=1; shift ;;
-h|--help) usage 0 ;;
*) echo "make-afw: unknown argument: $1" >&2; usage 2 ;;
esac
done
[ -n "$BOARD" ] || { echo "make-afw: --board is required" >&2; usage 2; }
[ -n "$VERSION" ] || { echo "make-afw: --version is required" >&2; usage 2; }
[ -n "$INPUT" ] || { echo "make-afw: --input is required" >&2; usage 2; }
[ -d "$INPUT" ] || { echo "make-afw: input directory not found: $INPUT" >&2; exit 1; }
if [ -z "$SDK_REVISION" ] && [ -n "$SDK_DIR" ]; then
SDK_REVISION=$(git -C "$SDK_DIR" rev-parse HEAD)
fi
if [ -z "$OS_REVISION" ]; then
OS_REVISION=$(git -C "$ROOT" rev-parse HEAD)
fi
[ -n "$SDK_REVISION" ] || { echo "make-afw: --sdk-revision or --sdk-dir is required" >&2; exit 1; }
mkdir -p "$OUTPUT"
OUTPUT="$(cd "$OUTPUT" && pwd)"
WORK=$(mktemp -d "${TMPDIR:-/tmp}/make-afw.XXXXXX")
trap 'rm -rf "$WORK"' EXIT
MANIFEST_ARGS=(
--board "$BOARD"
--version "$VERSION"
--input "$INPUT"
--staging "$WORK"
--sdk-revision "$SDK_REVISION"
--os-revision "$OS_REVISION"
--os-dir "$ROOT"
)
[ -n "$PLAN" ] && MANIFEST_ARGS+=(--plan "$PLAN")
[ -n "$SIGNING_KEY" ] && MANIFEST_ARGS+=(--signing-key "$SIGNING_KEY")
[ -n "$KERNEL_VERSION" ] && MANIFEST_ARGS+=(--kernel-version "$KERNEL_VERSION")
python3 "$ROOT/ci/afw_manifest.py" "${MANIFEST_ARGS[@]}" >/dev/null
ARCH=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["arch"])' "$WORK/manifest.json")
NAME="alkane-os-$VERSION-$BOARD-$ARCH.afw"
MEMBERS="$WORK/members.txt"
python3 - "$WORK" >"$MEMBERS" <<'PY'
import json
import sys
from pathlib import Path
stage = Path(sys.argv[1])
manifest = json.loads((stage / "manifest.json").read_text())
members = ["manifest.json"]
if manifest["signature"]["member"]:
members.append(manifest["signature"]["member"])
members.extend(image["file"] for image in manifest["images"])
for member in members:
if not (stage / member).is_file():
raise SystemExit(f"staged member is missing: {member}")
print("\n".join(members))
PY
MTIME=()
if [ -n "${SOURCE_DATE_EPOCH:-}" ]; then
MTIME=(--mtime="@${SOURCE_DATE_EPOCH}")
fi
tar --format=ustar --owner=0 --group=0 --numeric-owner "${MTIME[@]}" \
--create --file "$OUTPUT/$NAME" -C "$WORK" -T "$MEMBERS"
GOT=$(tar -tf "$OUTPUT/$NAME")
WANT=$(cat "$MEMBERS")
if [ "$GOT" != "$WANT" ]; then
echo "make-afw: FATAL: member order is wrong" >&2
printf 'expected:\n%s\nactual:\n%s\n' "$WANT" "$GOT" >&2
rm -f "$OUTPUT/$NAME"
exit 1
fi
CHECK=(--expect-board "$BOARD")
if [ -f "$WORK/manifest.pub" ]; then
CHECK+=(--public-key "$(cat "$WORK/manifest.pub")")
elif [ "$ALLOW_UNSIGNED" -eq 1 ]; then
CHECK+=(--allow-unsigned)
else
echo "make-afw: unsigned bundle needs --allow-unsigned (bench-only)" >&2
rm -f "$OUTPUT/$NAME"
exit 1
fi
python3 "$ROOT/ci/check-afw.py" "$OUTPUT/$NAME" "${CHECK[@]}"
# Emit a SHA256SUMS covering exactly this bundle, so the release artifact can
# never drift from the file it describes. Overwrite, do not append.
( cd "$OUTPUT" && sha256sum "$NAME" > SHA256SUMS )
printf '%s\n' "$OUTPUT/$NAME"
+47
View File
@@ -0,0 +1,47 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Select a safe fast PR check from the exact merge-base diff."""
import os
from pathlib import Path
import subprocess
ROOT = Path(__file__).resolve().parents[1]
def classify(paths: list[str]) -> str:
if not paths:
return "rust"
docs = {"README.md", "LICENSE", "AGENTS.md", "ci/CONFORMANCE.md"}
def is_doc(path: str) -> bool:
return path in docs or path.startswith("docs/") and path.endswith(".md")
def is_tool(path: str) -> bool:
return (path.startswith("ci/") and Path(path).suffix in {".py", ".json"}
or path.startswith(".gitea/workflows/") and path.endswith(".yml"))
if all(is_doc(path) for path in paths):
return "documentation"
if all(is_doc(path) or is_tool(path) for path in paths):
return "tooling"
return "rust"
def changed_paths() -> list[str]:
if os.environ.get("GITHUB_EVENT_NAME") != "pull_request":
return []
base = os.environ.get("GITHUB_BASE_REF")
if base not in {"next", "main"}:
return []
try:
merge_base = subprocess.check_output(
["git", "merge-base", "HEAD", f"origin/{base}"], cwd=ROOT).strip()
diff = subprocess.check_output(
["git", "diff", "--name-only", "-z", merge_base, "HEAD"], cwd=ROOT)
return [path.decode() for path in diff.split(b"\0") if path]
except (OSError, UnicodeError, subprocess.CalledProcessError):
return []
if __name__ == "__main__":
with open(os.environ["GITHUB_OUTPUT"], "a") as output:
output.write(f"surface={classify(changed_paths())}\n")
+21
View File
@@ -0,0 +1,21 @@
{
"schema": 1,
"claims": [
{
"board": "a113d",
"chip": "BM1366",
"level": "protocol_decoded",
"source": "miner-firmware/firmware-analysis/prong-b/aml-112/fullcov/capC1.strace",
"sha256": "05303e93f6d00433a6db5a9ee973b6cdb0351f3efa35d293dd172ede7da89d54",
"scope": "Historical BM1366 UART enumeration and nonce frames on an A113D S19k Pro"
},
{
"board": "zynq-7010",
"chip": "BM1366",
"level": "catalogued",
"source": "miner-firmware/firmware-analysis/prong-b/xil-137/fullcov/capC1.strace",
"sha256": "3daa3f7381580ef87f3b5925d5a03fdb4d2e7cd93a82b943ef2578da3d545607",
"scope": "Historical sensor and board observations; FPGA chip data path was not captured"
}
]
}
+1
View File
@@ -0,0 +1 @@
gitea.bluefla.re/blueflare/alkane-ci@sha256:ad56db2fc456a3f1c68c715ba44309751cb5c455376d9f797ac346833c011e15
Executable
+874
View File
@@ -0,0 +1,874 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Offline tests for the .afw producer and the CI brick-prevention gate."""
import json
import os
from pathlib import Path
import shutil
import subprocess
import sys
import tarfile
import tempfile
import unittest
HERE = Path(__file__).resolve().parent
ROOT = HERE.parent
MAKE = ROOT / "ci" / "make-afw.sh"
CHECK = ROOT / "ci" / "check-afw.py"
REVISION = "0" * 40
P1 = 16 * 1024 * 1024
def run(command, **kwargs):
return subprocess.run(command, text=True, capture_output=True, **kwargs)
def fixture_input(directory):
directory.mkdir(parents=True, exist_ok=True)
image = bytearray(4096)
image[0x38:0x3C] = b"ARMd"
image[0x08:0x10] = (0x200000).to_bytes(8, "little")
(directory / "Image").write_bytes(image)
dtb = bytearray(1024)
dtb[0:4] = b"\xd0\x0d\xfe\xed"
(directory / "cv-alkane.dtb").write_bytes(dtb)
(directory / "rootfs.cpio.gz").write_bytes(b"\x1f\x8b" + b"rootfs" + b"\0" * 64)
fit = bytearray(P1)
fit[0:4] = b"\xd0\x0d\xfe\xed"
marker = b"config@cv1835_miner_emmc"
fit[0x100 : 0x100 + len(marker)] = marker
(directory / "alkane-cv1835-p1.fit").write_bytes(fit)
return directory
def build_afw(work, input_dir, name="good.afw", extra=()):
output = work / "dist"
result = run(
[
"bash",
str(MAKE),
"--board",
"cv1835",
"--version",
"0.1.0",
"--input",
str(input_dir),
"--output",
str(output),
"--sdk-revision",
REVISION,
"--os-revision",
REVISION,
"--allow-unsigned",
*extra,
]
)
if result.returncode != 0:
raise AssertionError(f"producer failed:\n{result.stdout}\n{result.stderr}")
files = list(output.glob("*.afw"))
if len(files) != 1:
raise AssertionError(f"expected one bundle, found {files}")
return files[0]
def pack_members(directory, members, output):
listing = output.with_suffix(".list")
listing.write_text("\n".join(members) + "\n")
result = run(
[
"tar",
"--format=ustar",
"--owner=0",
"--group=0",
"--numeric-owner",
"--create",
"--file",
str(output),
"-C",
str(directory),
"-T",
str(listing),
]
)
if result.returncode != 0:
raise AssertionError(result.stderr)
listing.unlink()
return output
def rewrite_bundle(source, destination, edit_manifest=None, flip_payload=None):
"""Unpack a bundle, edit the manifest or payload, and repack it strictly."""
work = destination.parent / (destination.name + ".unpack")
if work.exists():
shutil.rmtree(work)
work.mkdir()
with tarfile.open(source, "r:") as archive:
names = archive.getnames()
archive.extractall(work)
manifest_path = work / "manifest.json"
manifest = json.loads(manifest_path.read_text())
if edit_manifest is not None:
edit_manifest(manifest, work)
manifest_path.write_text(json.dumps(manifest, indent=2) + "\n")
members = ["manifest.json"]
if manifest["signature"]["member"]:
members.append(manifest["signature"]["member"])
members.extend(image["file"] for image in manifest["images"])
if flip_payload:
for member in members:
if member in ("manifest.json", "manifest.json.sig"):
continue
path = work / member
if path.is_file():
data = bytearray(path.read_bytes())
if data:
data[len(data) // 2] ^= 0x01
path.write_bytes(data)
break
pack_members(work, members, destination)
shutil.rmtree(work)
return destination
class AfwTests(unittest.TestCase):
def setUp(self):
self.temp = Path(tempfile.mkdtemp(prefix="afw-test."))
self.input = fixture_input(self.temp / "sdk-out")
def tearDown(self):
shutil.rmtree(self.temp, ignore_errors=True)
def check(self, path, *extra):
return run([sys.executable, str(CHECK), str(path), *extra])
def test_good_bundle_passes_and_reports_install(self):
bundle = build_afw(self.temp, self.input)
result = self.check(bundle, "--allow-unsigned", "--expect-board", "cv1835")
self.assertEqual(result.returncode, 0, result.stderr)
self.assertIn("afw: OK", result.stdout)
self.assertIn("install p1 -> p1", result.stdout)
result = self.check(bundle, "--allow-unsigned", "--json")
self.assertEqual(result.returncode, 0, result.stderr)
summary = json.loads(result.stdout)
self.assertEqual(summary["board"], "cv1835")
self.assertEqual(summary["arch"], "arm64")
self.assertEqual(summary["install"][0]["size"], P1)
def test_unsigned_bundle_needs_the_flag(self):
bundle = build_afw(self.temp, self.input)
result = self.check(bundle)
self.assertNotEqual(result.returncode, 0)
self.assertIn("unsigned", result.stderr)
def test_one_byte_tampered_payload_fails(self):
bundle = build_afw(self.temp, self.input)
tampered = rewrite_bundle(bundle, self.temp / "tampered.afw", flip_payload=True)
result = self.check(tampered, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("sha256 mismatch", result.stderr)
def test_wrong_board_is_refused(self):
bundle = build_afw(self.temp, self.input)
result = self.check(bundle, "--allow-unsigned", "--expect-board", "zynq-7010")
self.assertNotEqual(result.returncode, 0)
self.assertIn("expected zynq-7010", result.stderr)
def test_manifest_cannot_claim_a_different_arch(self):
bundle = build_afw(self.temp, self.input)
def edit(manifest, _work):
manifest["arch"] = "armv7"
wrong = rewrite_bundle(bundle, self.temp / "wrong-arch.afw", edit_manifest=edit)
result = self.check(wrong, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("must use arm64", result.stderr)
def test_truncated_tar_fails(self):
bundle = build_afw(self.temp, self.input)
truncated = self.temp / "truncated.afw"
truncated.write_bytes(bundle.read_bytes()[:100])
result = self.check(truncated, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("truncated", result.stderr)
def test_traversal_member_fails(self):
stage = self.temp / "traversal"
stage.mkdir()
(stage / "manifest.json").write_text("{}\n")
(stage / "payload").mkdir()
(stage / "payload" / "p1.fit").write_bytes(b"\xd0\x0d\xfe\xed")
bundle = self.temp / "traversal.afw"
import io
with tarfile.open(bundle, "w", format=tarfile.USTAR_FORMAT) as archive:
for name, data in (
("manifest.json", b"{}\n"),
("payload/../escape", b"x"),
):
info = tarfile.TarInfo(name)
info.size = len(data)
archive.addfile(info, io.BytesIO(data))
result = self.check(bundle, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("traversal", result.stderr)
def test_oversize_fit_is_refused_by_producer(self):
fit = self.input / "alkane-cv1835-p1.fit"
data = fit.read_bytes()
fit.write_bytes(data + b"\0")
result = run(
[
"bash",
str(MAKE),
"--board",
"cv1835",
"--version",
"0.1.0",
"--input",
str(self.input),
"--output",
str(self.temp / "dist"),
"--sdk-revision",
REVISION,
"--os-revision",
REVISION,
"--allow-unsigned",
]
)
self.assertNotEqual(result.returncode, 0)
self.assertIn("larger than", result.stderr)
def test_oversize_fit_is_refused_by_checker(self):
bundle = build_afw(self.temp, self.input)
def edit(manifest, work):
manifest["images"][-1]["size"] = P1 + 1
manifest["images"][-1]["sha256"] = "0" * 64
path = work / manifest["images"][-1]["file"]
path.write_bytes(path.read_bytes() + b"\0")
oversize = rewrite_bundle(bundle, self.temp / "oversize.afw", edit_manifest=edit)
result = self.check(oversize, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("exceeds partition", result.stderr)
def test_bootloader_member_under_preserve_is_refused(self):
bundle = build_afw(self.temp, self.input)
def edit(manifest, work):
manifest["images"].append(
{
"name": "u-boot",
"file": "payload/u-boot.img",
"role": "bootloader",
"format": "uimage",
"size": 4,
"sha256": "0" * 64,
"partition": None,
"install": False,
}
)
(work / "payload" / "u-boot.img").write_bytes(b"\x27\x05\x19\x56")
wrong = rewrite_bundle(bundle, self.temp / "bootloader.afw", edit_manifest=edit)
result = self.check(wrong, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("preserve", result.stderr)
def test_hash_mismatch_fails(self):
bundle = build_afw(self.temp, self.input)
def edit(manifest, _work):
manifest["images"][0]["sha256"] = "1" * 64
wrong = rewrite_bundle(bundle, self.temp / "hash.afw", edit_manifest=edit)
result = self.check(wrong, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("sha256 mismatch", result.stderr)
def test_missing_image_fails_producer(self):
(self.input / "Image").unlink()
result = run(
[
"bash",
str(MAKE),
"--board",
"cv1835",
"--version",
"0.1.0",
"--input",
str(self.input),
"--output",
str(self.temp / "dist"),
"--sdk-revision",
REVISION,
"--os-revision",
REVISION,
"--allow-unsigned",
]
)
self.assertNotEqual(result.returncode, 0)
self.assertIn("required image is missing", result.stderr)
def test_plan_size_cross_check(self):
bundle = build_afw(self.temp, self.input)
plan = self.temp / "plan.json"
plan.write_text(json.dumps({
"board": "cv1835",
"arch": "arm64",
"bootloader_policy": "preserve",
"partitions": [{"name": "p1", "size": P1}],
}))
result = self.check(bundle, "--allow-unsigned", "--plan", plan)
self.assertEqual(result.returncode, 0, result.stderr)
plan.write_text(json.dumps({
"board": "cv1835",
"arch": "arm64",
"bootloader_policy": "preserve",
"partitions": [{"name": "p1", "size": P1 - 1}],
}))
result = self.check(bundle, "--allow-unsigned", "--plan", plan)
self.assertNotEqual(result.returncode, 0)
self.assertIn("differs from the manifest", result.stderr)
def test_unknown_board_fails(self):
result = run(
[
"bash",
str(MAKE),
"--board",
"whatsminer-h6",
"--version",
"0.1.0",
"--input",
str(self.input),
"--output",
str(self.temp / "dist"),
"--sdk-revision",
REVISION,
"--os-revision",
REVISION,
"--allow-unsigned",
]
)
self.assertNotEqual(result.returncode, 0)
self.assertIn("unknown board family", result.stderr)
if __name__ == "__main__":
unittest.main(verbosity=2)
AM_KERNEL_MAX = 0x500000
AM_ROOT_MAX = 0x1400000
def uimage_header(kind, payload=b"payload"):
header = bytearray(64)
header[0:4] = b"\x27\x05\x19\x56"
header[12:16] = len(payload).to_bytes(4, "big")
header[29] = 2 # ARM
header[30] = kind # 2 kernel, 3 ramdisk
header[31] = 0 if kind == 2 else 1
header[32:48] = b"alkane-am335x\0\0\0"
return bytes(header) + payload
def am_fixture_input(directory):
directory.mkdir(parents=True, exist_ok=True)
(directory / "alkane-am335x.uImage").write_bytes(uimage_header(2, b"kernel"))
dtb = bytearray(2048)
dtb[0:4] = b"\xd0\x0d\xfe\xed"
(directory / "am335x-alkane.dtb").write_bytes(dtb)
(directory / "alkane-am335x-ramdisk.uImage").write_bytes(
uimage_header(3, b"ramdisk")
)
return directory
def build_am_afw(work, input_dir, extra=()):
output = work / "dist-am"
result = run(
[
"bash",
str(MAKE),
"--board",
"am335x",
"--version",
"0.1.0",
"--input",
str(input_dir),
"--output",
str(output),
"--sdk-revision",
REVISION,
"--os-revision",
REVISION,
"--allow-unsigned",
*extra,
]
)
if result.returncode != 0:
raise AssertionError(f"producer failed:\n{result.stdout}\n{result.stderr}")
files = list(output.glob("*.afw"))
if len(files) != 1:
raise AssertionError(f"expected one bundle, found {files}")
return files[0]
class Am335xAfwTests(unittest.TestCase):
def setUp(self):
self.temp = Path(tempfile.mkdtemp(prefix="am335x-afw-test."))
self.input = am_fixture_input(self.temp / "sdk-out")
def tearDown(self):
shutil.rmtree(self.temp, ignore_errors=True)
def check(self, path, *extra):
return run([sys.executable, str(CHECK), str(path), *extra])
def test_good_bundle_passes_and_reports_three_installs(self):
bundle = build_am_afw(self.temp, self.input)
result = self.check(bundle, "--allow-unsigned", "--expect-board", "am335x")
self.assertEqual(result.returncode, 0, result.stderr)
self.assertIn("afw: OK", result.stdout)
self.assertIn("board am335x arch arm", result.stdout)
self.assertIn("bootloader preserve", result.stdout)
result = self.check(bundle, "--allow-unsigned", "--json")
self.assertEqual(result.returncode, 0, result.stderr)
summary = json.loads(result.stdout)
installs = {item["image"]: item["partition"] for item in summary["install"]}
self.assertEqual(
installs, {"kernel": "mtd7", "dtb": "mtd6", "rootfs": "mtd8"}
)
def test_oversize_kernel_is_refused_by_producer(self):
path = self.input / "alkane-am335x.uImage"
path.write_bytes(path.read_bytes() + b"\0" * (AM_KERNEL_MAX + 1))
result = run(
[
"bash", str(MAKE), "--board", "am335x", "--version", "0.1.0",
"--input", str(self.input), "--output", str(self.temp / "dist"),
"--sdk-revision", REVISION, "--os-revision", REVISION,
"--allow-unsigned",
]
)
self.assertNotEqual(result.returncode, 0)
self.assertIn("larger than", result.stderr)
def test_oversize_root_is_refused_by_producer(self):
path = self.input / "alkane-am335x-ramdisk.uImage"
path.write_bytes(path.read_bytes() + b"\0" * (AM_ROOT_MAX + 1))
result = run(
[
"bash", str(MAKE), "--board", "am335x", "--version", "0.1.0",
"--input", str(self.input), "--output", str(self.temp / "dist"),
"--sdk-revision", REVISION, "--os-revision", REVISION,
"--allow-unsigned",
]
)
self.assertNotEqual(result.returncode, 0)
self.assertIn("larger than", result.stderr)
def test_u_boot_member_under_preserve_is_refused(self):
bundle = build_am_afw(self.temp, self.input)
def edit(manifest, work):
manifest["images"].append(
{
"name": "u-boot",
"file": "payload/u-boot.img",
"role": "component",
"format": "uimage",
"size": 4,
"sha256": __import__("hashlib").sha256(b"boot").hexdigest(),
"partition": None,
"install": False,
}
)
(work / "payload" / "u-boot.img").write_bytes(b"boot")
bad = rewrite_bundle(bundle, self.temp / "uboot.afw", edit_manifest=edit)
result = self.check(bad, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("u-boot", result.stderr)
def test_manifest_cannot_claim_arm64(self):
bundle = build_am_afw(self.temp, self.input)
def edit(manifest, _work):
manifest["arch"] = "arm64"
bad = rewrite_bundle(bundle, self.temp / "wrong-arch.afw", edit_manifest=edit)
result = self.check(bad, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("must use arm", result.stderr)
def test_mtd4_write_target_is_refused(self):
bundle = build_am_afw(self.temp, self.input)
def edit(manifest, _work):
for part in manifest["partitions"]:
if part["name"] == "mtd4":
part["write_order"] = 1
part["image"] = "kernel"
part["secure"] = False
bad = rewrite_bundle(bundle, self.temp / "mtd4.afw", edit_manifest=edit)
result = self.check(bad, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("mtd4", result.stderr)
def test_offset_in_the_0x780000_hole_is_refused(self):
bundle = build_am_afw(self.temp, self.input)
def edit(manifest, _work):
for part in manifest["partitions"]:
if part["name"] == "mtd8":
part["offset"] = 0x780000
bad = rewrite_bundle(bundle, self.temp / "hole.afw", edit_manifest=edit)
result = self.check(bad, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("hole", result.stderr)
def test_ramdisk_must_be_type_3(self):
(self.input / "alkane-am335x-ramdisk.uImage").write_bytes(
uimage_header(2, b"not-a-ramdisk")
)
result = run(
[
"bash", str(MAKE), "--board", "am335x", "--version", "0.1.0",
"--input", str(self.input), "--output", str(self.temp / "dist"),
"--sdk-revision", REVISION, "--os-revision", REVISION,
"--allow-unsigned",
]
)
self.assertNotEqual(result.returncode, 0)
self.assertIn("type-3 ramdisk", result.stderr)
def test_truncated_tar_fails(self):
bundle = build_am_afw(self.temp, self.input)
truncated = self.temp / "truncated.afw"
truncated.write_bytes(bundle.read_bytes()[:100])
result = self.check(truncated, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("truncated", result.stderr)
def test_traversal_member_fails(self):
import io
bundle = self.temp / "traversal.afw"
with tarfile.open(bundle, "w", format=tarfile.USTAR_FORMAT) as archive:
for name, data in (
("manifest.json", b"{}\n"),
("payload/../escape", b"x"),
):
info = tarfile.TarInfo(name)
info.size = len(data)
archive.addfile(info, io.BytesIO(data))
result = self.check(bundle, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("traversal", result.stderr)
def test_plan_json_cross_check(self):
sdk = Path("/home/noah/projects/alkane-sdk")
plan_yaml = sdk / "install" / "plans" / "am335x.yaml"
if not plan_yaml.is_file():
self.skipTest("alkane-sdk am335x plan not present")
plan_json = self.temp / "am335x-plan.json"
result = run(
[
sys.executable, str(sdk / "ci" / "check-plans.py"),
"--plan", str(plan_yaml), "--emit-json", str(plan_json),
]
)
self.assertEqual(result.returncode, 0, result.stderr)
bundle = build_am_afw(
self.temp, self.input, extra=("--plan", str(plan_json))
)
result = self.check(
bundle, "--allow-unsigned", "--plan", str(plan_json)
)
self.assertEqual(result.returncode, 0, result.stderr)
def am_stock_fixture_input(directory):
"""The tier-3 from-stock input: adds our U-Boot (firmware uImage, type 5)
alongside the kernel/dtb/ramdisk."""
am_fixture_input(directory)
(directory / "alkane-am335x-uboot-mtd4.uImage").write_bytes(
uimage_header(5, b"u-boot")
)
return directory
def build_am_stock_afw(work, input_dir, extra=()):
output = work / "dist-am-stock"
result = run(
[
"bash", str(MAKE), "--board", "am335x-stock", "--version", "0.1.0",
"--input", str(input_dir), "--output", str(output),
"--sdk-revision", REVISION, "--os-revision", REVISION,
"--allow-unsigned", *extra,
]
)
if result.returncode != 0:
raise AssertionError(f"producer failed:\n{result.stdout}\n{result.stderr}")
files = list(output.glob("*.afw"))
if len(files) != 1:
raise AssertionError(f"expected one bundle, found {files}")
return files[0]
class Am335xStockAfwTests(unittest.TestCase):
"""Tier-3 from-stock bundle: writes U-Boot to mtd4 but must still refuse
every SPL write and a wrongly-typed U-Boot member."""
def setUp(self):
self.temp = Path(tempfile.mkdtemp(prefix="am335x-stock-afw-test."))
self.input = am_stock_fixture_input(self.temp / "sdk-out")
def tearDown(self):
shutil.rmtree(self.temp, ignore_errors=True)
def check(self, path, *extra):
return run([sys.executable, str(CHECK), str(path), *extra])
def test_good_stock_bundle_passes_with_four_installs(self):
bundle = build_am_stock_afw(self.temp, self.input)
result = self.check(bundle, "--allow-unsigned", "--expect-board", "am335x-stock")
self.assertEqual(result.returncode, 0, result.stderr)
self.assertIn("afw: OK", result.stdout)
self.assertIn("bootloader include", result.stdout)
result = self.check(bundle, "--allow-unsigned", "--json")
self.assertEqual(result.returncode, 0, result.stderr)
installs = {item["image"]: item["partition"] for item in json.loads(result.stdout)["install"]}
self.assertEqual(
installs, {"u-boot": "mtd4", "kernel": "mtd7", "dtb": "mtd6", "rootfs": "mtd8"}
)
def test_u_boot_member_must_be_firmware_type(self):
# A U-Boot payload wrongly built as a type-2 kernel uImage must be caught.
(self.input / "alkane-am335x-uboot-mtd4.uImage").write_bytes(uimage_header(2, b"u-boot"))
result = run(
[
"bash", str(MAKE), "--board", "am335x-stock", "--version", "0.1.0",
"--input", str(self.input), "--output", str(self.temp / "dist"),
"--sdk-revision", REVISION, "--os-revision", REVISION, "--allow-unsigned",
]
)
self.assertNotEqual(result.returncode, 0)
self.assertIn("firmware", result.stderr + result.stdout)
def test_making_an_spl_copy_a_write_target_is_refused(self):
bundle = build_am_stock_afw(self.temp, self.input)
def edit(manifest, _work):
for part in manifest["partitions"]:
if part["name"] == "mtd0":
part["secure"] = False
part["write_order"] = 5
part["image"] = "u-boot"
bad = rewrite_bundle(bundle, self.temp / "spl-write.afw", edit_manifest=edit)
result = self.check(bad, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("mtd0", result.stderr)
def zimage_blob(payload=b"zkernel"):
# ARM zImage: magic 0x016f2818 (LE) at offset 0x24.
b = bytearray(64)
b[0x24:0x28] = b"\x18\x28\x6f\x01"
return bytes(b) + payload
def zynq_fixture_input(directory):
directory.mkdir(parents=True, exist_ok=True)
(directory / "zImage").write_bytes(zimage_blob())
dtb = bytearray(1024); dtb[0:4] = b"\xd0\x0d\xfe\xed"
(directory / "zynq-alkane.dtb").write_bytes(dtb)
(directory / "rootfs.cpio.gz").write_bytes(b"\x1f\x8b" + b"rootfs")
return directory
def build_zynq_afw(work, input_dir, extra=()):
output = work / "dist-zynq"
result = run(["bash", str(MAKE), "--board", "zynq-7010", "--version", "0.1.0",
"--input", str(input_dir), "--output", str(output),
"--sdk-revision", REVISION, "--os-revision", REVISION,
"--allow-unsigned", *extra])
if result.returncode != 0:
raise AssertionError(f"producer failed:\n{result.stdout}\n{result.stderr}")
files = list(output.glob("*.afw"))
if len(files) != 1:
raise AssertionError(f"expected one bundle, found {files}")
return files[0]
class ZynqAfwTests(unittest.TestCase):
"""zynq-7010 tier-2 bundle: kernel(zImage)/dtb/rootfs, BOOT.bin preserved."""
def setUp(self):
self.temp = Path(tempfile.mkdtemp(prefix="zynq-afw-test."))
self.input = zynq_fixture_input(self.temp / "sdk-out")
def tearDown(self):
shutil.rmtree(self.temp, ignore_errors=True)
def check(self, path, *extra):
return run([sys.executable, str(CHECK), str(path), *extra])
def test_good_zynq_bundle_passes(self):
bundle = build_zynq_afw(self.temp, self.input)
result = self.check(bundle, "--allow-unsigned", "--expect-board", "zynq-7010")
self.assertEqual(result.returncode, 0, result.stderr)
self.assertIn("afw: OK", result.stdout)
self.assertIn("bootloader preserve", result.stdout)
def test_non_zimage_kernel_is_refused(self):
(self.input / "zImage").write_bytes(b"\x00" * 4096) # no zImage magic
result = run(["bash", str(MAKE), "--board", "zynq-7010", "--version", "0.1.0",
"--input", str(self.input), "--output", str(self.temp / "d"),
"--sdk-revision", REVISION, "--os-revision", REVISION, "--allow-unsigned"])
self.assertNotEqual(result.returncode, 0)
self.assertIn("zImage", result.stderr + result.stdout)
def test_oversize_kernel_is_refused(self):
(self.input / "zImage").write_bytes(zimage_blob(b"\x00" * (0x500000 + 1)))
result = run(["bash", str(MAKE), "--board", "zynq-7010", "--version", "0.1.0",
"--input", str(self.input), "--output", str(self.temp / "d"),
"--sdk-revision", REVISION, "--os-revision", REVISION, "--allow-unsigned"])
self.assertNotEqual(result.returncode, 0)
self.assertIn("ceiling", result.stderr + result.stdout)
def test_bootloader_member_is_refused(self):
bundle = build_zynq_afw(self.temp, self.input)
def edit(manifest, work):
manifest["images"].append({
"name": "u-boot", "file": "payload/BOOT.bin", "role": "bootloader",
"format": "raw", "size": 4,
"sha256": __import__("hashlib").sha256(b"boot").hexdigest(),
"partition": None, "install": False,
})
(work / "payload" / "BOOT.bin").write_bytes(b"boot")
bad = rewrite_bundle(bundle, self.temp / "bl.afw", edit_manifest=edit)
result = self.check(bad, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
def arm64_image_blob(payload=b"a64kernel"):
# arm64 Linux Image: ASCII "ARMd" at offset 0x38.
b = bytearray(64)
b[0x38:0x3C] = b"ARMd"
b[0x08:0x10] = (0x200000).to_bytes(8, "little") # text_offset / image_size hint
return bytes(b) + payload
def uramdisk_blob(payload=b"ramdisk"):
# legacy uImage ramdisk (magic 0x27051956); a113d does not enforce arch/type.
b = bytearray(64)
b[0:4] = b"\x27\x05\x19\x56"
b[12:16] = len(payload).to_bytes(4, "big")
return bytes(b) + payload
def a113d_fixture_input(directory):
directory.mkdir(parents=True, exist_ok=True)
(directory / "vmlinux.bin").write_bytes(arm64_image_blob())
dtb = bytearray(2048); dtb[0:4] = b"\xd0\x0d\xfe\xed"
(directory / "devicetree.dtb").write_bytes(bytes(dtb))
(directory / "uramdisk.image.gz").write_bytes(uramdisk_blob())
return directory
def build_a113d_afw(work, input_dir, extra=()):
output = work / "dist-a113d"
result = run(["bash", str(MAKE), "--board", "a113d", "--version", "0.1.0",
"--input", str(input_dir), "--output", str(output),
"--sdk-revision", REVISION, "--os-revision", REVISION,
"--allow-unsigned", *extra])
if result.returncode != 0:
raise AssertionError(f"producer failed:\n{result.stdout}\n{result.stderr}")
files = list(output.glob("*.afw"))
if len(files) != 1:
raise AssertionError(f"expected one bundle, found {files}")
return files[0]
class A113dAfwTests(unittest.TestCase):
"""a113d tier-2 bundle: kernel/dtb/rootfs staged into nvdata; FIP + mtd0-5 preserved."""
def setUp(self):
self.temp = Path(tempfile.mkdtemp(prefix="a113d-afw-test."))
self.input = a113d_fixture_input(self.temp / "sdk-out")
def tearDown(self):
shutil.rmtree(self.temp, ignore_errors=True)
def check(self, path, *extra):
return run([sys.executable, str(CHECK), str(path), *extra])
def make(self, outdir="d"):
return run(["bash", str(MAKE), "--board", "a113d", "--version", "0.1.0",
"--input", str(self.input), "--output", str(self.temp / outdir),
"--sdk-revision", REVISION, "--os-revision", REVISION, "--allow-unsigned"])
def test_good_a113d_bundle_passes_and_preserves(self):
bundle = build_a113d_afw(self.temp, self.input)
result = self.check(bundle, "--allow-unsigned", "--expect-board", "a113d")
self.assertEqual(result.returncode, 0, result.stderr)
self.assertIn("afw: OK", result.stdout)
self.assertIn("bootloader preserve", result.stdout)
# all three images install into the nvdata UBI, never a raw mtd0-5 write
self.assertEqual(result.stdout.count("-> nvdata"), 3)
def test_non_arm64_kernel_is_refused(self):
(self.input / "vmlinux.bin").write_bytes(b"\x00" * 4096) # no ARMd magic
result = self.make()
self.assertNotEqual(result.returncode, 0)
self.assertIn("arm64", (result.stderr + result.stdout).lower())
def test_oversize_kernel_is_refused(self):
(self.input / "vmlinux.bin").write_bytes(arm64_image_blob(b"\x00" * (0x4000000 + 1)))
result = self.make()
self.assertNotEqual(result.returncode, 0)
self.assertIn("ceiling", (result.stderr + result.stdout).lower())
def test_fip_member_is_refused(self):
bundle = build_a113d_afw(self.temp, self.input)
def edit(manifest, work):
manifest["images"].append({
"name": "fip", "file": "payload/fip.bin", "role": "bootloader",
"format": "raw", "size": 4,
"sha256": __import__("hashlib").sha256(b"fip!").hexdigest(),
"partition": None, "install": False,
})
(work / "payload" / "fip.bin").write_bytes(b"fip!")
bad = rewrite_bundle(bundle, self.temp / "fip.afw", edit_manifest=edit)
result = self.check(bad, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("fip", (result.stderr + result.stdout).lower())
def test_preserved_mtd_carrying_an_image_is_refused(self):
bundle = build_a113d_afw(self.temp, self.input)
def edit(manifest, work):
for partition in manifest["partitions"]:
if partition["name"] != "nvdata":
partition["image"] = "kernel" # try to aim a write at the FIP side
break
bad = rewrite_bundle(bundle, self.temp / "pre.afw", edit_manifest=edit)
result = self.check(bad, "--allow-unsigned")
self.assertNotEqual(result.returncode, 0)
self.assertIn("preserved", (result.stderr + result.stdout).lower())
+43
View File
@@ -0,0 +1,43 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Research observations cannot promote a target into release conformance."""
import copy
import importlib.util
import json
from pathlib import Path
import unittest
ROOT = Path(__file__).resolve().parent
spec = importlib.util.spec_from_file_location("evidence_status", ROOT / "evidence_status.py")
status = importlib.util.module_from_spec(spec)
spec.loader.exec_module(status)
MATRIX = json.loads((ROOT / "conformance.json").read_text())
RESEARCH = json.loads((ROOT / "research-evidence.json").read_text())
class EvidenceStatusTest(unittest.TestCase):
def test_historical_protocol_does_not_satisfy_release(self):
report = status.summarize(MATRIX, RESEARCH)
self.assertEqual(report["target_cells"], 64)
self.assertEqual(report["research_only"], {"catalogued": 1, "protocol_decoded": 1})
self.assertIsNone(report["verified_release_cells"])
self.assertEqual(sum(report["release_manifest_declarations_unverified"].values()), 0)
for level in ("stock_simulator_boot", "captured_nonce_pool_accept",
"physical_install_update_uninstall_recovery", "full_release_cell"):
self.assertIsNone(report["evidence_levels"][level]["current_run_verified"])
def test_rejects_missing_cell_and_unsupported_claim(self):
matrix = copy.deepcopy(MATRIX)
matrix["targets"].pop()
with self.assertRaisesRegex(ValueError, "incomplete"):
status.summarize(matrix, RESEARCH)
research = copy.deepcopy(RESEARCH)
research["claims"][0]["level"] = "pool_accept"
with self.assertRaisesRegex(ValueError, "outside target matrix or level"):
status.summarize(MATRIX, research)
if __name__ == "__main__":
unittest.main()
+41
View File
@@ -0,0 +1,41 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Representative experiments preserve the full release target set."""
import copy
import importlib.util
import json
from pathlib import Path
import unittest
ROOT = Path(__file__).resolve().parent
spec = importlib.util.spec_from_file_location("experiment_priority", ROOT / "experiment_priority.py")
priority = importlib.util.module_from_spec(spec)
spec.loader.exec_module(priority)
MATRIX = json.loads((ROOT / "conformance.json").read_text())
QUEUE = json.loads((ROOT / "experiment-queue.json").read_text())
class ExperimentPriorityTest(unittest.TestCase):
def test_local_boot_model_ranks_first_without_reducing_gate(self):
ordered = priority.rank(MATRIX, QUEUE)
self.assertEqual(ordered[0]["id"], "am335x-original-nand-boot")
self.assertEqual(ordered[0]["affected_release_cells"], 13)
self.assertEqual(len(MATRIX["targets"]), 64)
self.assertEqual(next(row for row in ordered if row["id"] == "bm1368-command-and-nonce")
["affected_release_cells"], 4)
def test_no_selector_or_unexplained_blocker(self):
queue = copy.deepcopy(QUEUE)
queue["experiments"][0]["board"] = None
with self.assertRaisesRegex(ValueError, "no target selector"):
priority.rank(MATRIX, queue)
queue = copy.deepcopy(QUEUE)
queue["experiments"][1]["blocker"] = None
with self.assertRaisesRegex(ValueError, "lacks a blocker"):
priority.rank(MATRIX, queue)
if __name__ == "__main__":
unittest.main()
+28
View File
@@ -0,0 +1,28 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Unknown PR paths must retain compiled source checks."""
import importlib.util
from pathlib import Path
import unittest
spec = importlib.util.spec_from_file_location("pr_surface", Path(__file__).with_name("pr_surface.py"))
surface = importlib.util.module_from_spec(spec)
spec.loader.exec_module(surface)
class PrSurfaceTest(unittest.TestCase):
def test_documentation_and_tooling(self):
self.assertEqual(surface.classify(["README.md", "docs/boards.md"]), "documentation")
self.assertEqual(surface.classify(["ci/evidence_status.py", "ci/CONFORMANCE.md"]), "tooling")
def test_unknown_and_rust_paths_fail_open_to_build(self):
for paths in ([], ["src/main.rs"], ["Cargo.toml"], ["unknown/file"],
["ci/evidence_status.py", "src/main.rs"]):
with self.subTest(paths=paths):
self.assertEqual(surface.classify(paths), "rust")
if __name__ == "__main__":
unittest.main()
+59
View File
@@ -0,0 +1,59 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Check candidate numbering and covered-commit reruns with real Git tags."""
from pathlib import Path
import subprocess
import tempfile
VERSION = Path(__file__).with_name("version.py")
def git(root: Path, *args: str) -> str:
result = subprocess.run(
["git", *args], cwd=root, text=True, check=True, capture_output=True
)
return result.stdout.strip()
def selected(root: Path, branch: str) -> dict[str, str]:
result = subprocess.run(
["python3", str(VERSION), branch], cwd=root,
text=True, check=True, capture_output=True
)
return dict(line.split("=", 1) for line in result.stdout.splitlines())
def main() -> None:
with tempfile.TemporaryDirectory(prefix="alkane-os-version-") as path:
root = Path(path)
(root / "ci").mkdir()
(root / "ci/version-x.txt").write_text("0\n")
git(root, "init", "-q")
git(root, "config", "user.name", "Alkane CI")
git(root, "config", "user.email", "ci@example.invalid")
git(root, "add", ".")
git(root, "commit", "-qm", "First source")
first = git(root, "rev-parse", "HEAD")
assert selected(root, "next") == {
"release": "true", "tag": "v0.1.0-rc.1", "version": "0.1.0-rc.1"
}
git(root, "tag", "v0.1.0-rc.1")
assert selected(root, "next") == {"release": "false"}
(root / "README.md").write_text("A later merge.\n")
git(root, "add", ".")
git(root, "commit", "-qm", "Later source")
assert selected(root, "next") == {
"release": "true", "tag": "v0.1.0-rc.2", "version": "0.1.0-rc.2"
}
git(root, "tag", "v0.1.0-rc.2")
assert selected(root, "next") == {"release": "false"}
git(root, "checkout", "-q", first)
assert selected(root, "next") == {"release": "false"}
print("PASS: exact and superseded candidate reruns do not publish")
if __name__ == "__main__":
main()
+7
View File
@@ -27,6 +27,13 @@ def main():
parser.add_argument("branch", choices=("main", "next"))
args = parser.parse_args()
major = int(pathlib.Path("ci/version-x.txt").read_text().strip())
# A rerun of a commit already covered by a published tag must not issue
# a newer candidate number for older source.
tagged_descendants = set(git("tag", "--contains", "HEAD", "-l", "v*").splitlines())
known_tags = {tag for _, tag in versions("main") + versions("next")}
if tagged_descendants & known_tags:
print("release=false")
return
finals = versions("main")
previous = finals[-1] if finals else None
if previous and previous[0][0] > major:
+110
View File
@@ -0,0 +1,110 @@
# Code review report - alkane-os console/bus/login/dashboard/image
Scope: today's work on `feature/afw-os-bundle` (bus, registry, service, web, console,
app, main, control, runtime, tuning, auth, dashboard, schema menus, image tooling).
Method: code-review-harness, 4 parallel reviewers (correctness, security, reliability,
maintainability) at high reasoning effort over the branch diff, then fixes applied and
re-verified. Installation-from-stock / restore-to-stock method tooling was out of scope
(DeepSeek Harness's domain; not in this repo).
## Verdict: READY TO SHIP (software checkpoint)
No Critical or High findings. The HTTP parser, login/session gate, bus semantics, and the
crypto (HMAC-SHA256 / PBKDF2 / SHA-256 against RFC 4231 / RFC 7914 vectors) were verified
correct; the session gate cannot be bypassed. Every Medium finding has been fixed and
re-verified. Remaining items are Low / maintainability and are listed as deferred.
External tooling: `cargo clippy --all-targets -- -D warnings` clean; 206 lib tests + all
integration tests pass; no emojis.
## Fixed in this pass
Security
- `/api/files` and `/api/file` were reachable with a session but no token, contradicting
the module docs and the Security page (arbitrary root-readable file exfiltration). Now
token-gated via `authorised()`, matching the advertised control. (web.rs)
- Response/header-splitting: `__section`/`__tab` from the settings form were interpolated
into the `Location:` header; `%0d%0a` decoded to CRLF. Now constrained to safe slugs
(`safe_slug`) before the redirect. (web.rs)
- RNG degradation: an unreadable `/dev/urandom` substituted the published constant
`"dev-csrf-token"` and second-granular, guessable session ids. Now a single token source
(`auth::rand_hex`) that warns loudly and falls back to a per-call, non-constant mix; the
CSRF generator delegates to it. (auth.rs, web.rs)
- The UI token was compared with `==` (timing oracle). Now `auth::ct_eq` (constant time).
(web.rs)
- `auth.json` (password hash) was written umask-default (world-readable). Now created 0600
with the parent dir 0700. (auth.rs)
- Unbounded thread-per-connection + no absolute read deadline (flood DoS on the open :80).
Now a 64-connection cap (503 beyond it) and a 10 s head-read deadline, on top of the
per-read timeout. (web.rs)
Reliability / correctness
- Settings persistence swallowed its write error and reported success with a misleading
comment. Now the error propagates (surfaced as the form's rejection) and the write is
atomic (temp + rename). Deck save is atomic too. (dashboard.rs, service.rs)
- `Auth::login` returned a cookie even if the session insert failed (redirect loop). Now
returns `None` on a poisoned lock. (auth.rs)
- `TuningLoop::set_target` carried the PID integral across modes whose error is in
different units (watts vs millidegrees vs TH/s), injecting a stale push on a mode switch.
Now the accumulator resets on a target change while the operating point is kept. (tuning.rs)
- Editable-deck JS: new-block ids collided after remove-then-add (duplicate ids, both
deleted on remove); the default new-block source `power_w` wasn't in the live-value map
(rendered n/a); drag-drop placement was asymmetric; save didn't re-render the normalized
doc. All fixed. (console.rs)
- Drivers page showed `"temperature"` with JSON quotes for the stopped reason. Now the bare
string. (web.rs)
Maintainability
- `percent_decode` / form-field parsing existed in three divergent copies; consolidated into
one `form` module used by web, service and dashboard. The CSPRNG-to-hex helper is now one
function (`auth::rand_hex`).
- Added a test asserting the published state topics match the registry contract (the
"single source of truth" claim for topics was previously unenforced).
## Deferred (reported, not blocking)
- `ui.rs` is now largely dead: only `validate_deck` / `default_deck` (+ two consts) are used
(by `service.rs`); the legacy console (`page`, `dashboard_page`, `sidebar`, `NAV`, the CSS/JS
consts, `icon`/`group_icon_svg` which `Box::leak`) has no callers. Recommend moving the two
deck helpers to a `deck` module and deleting the rest. (~34 KB)
- `control::target_label` vs `app::target_label` are two implementations of the same mapping;
recommend one canonical (e.g. in `tuning`).
- `DECK_CSS` / `DECK_JS` / `TERMINAL_JS` are large inline strings; recommend moving to
`assets/*.js|css`, `include_str!`, and serving under `/assets` like the stylesheets, so they
can be linted.
- `web.rs` still owns host-fact gatherers (`system_rows`, ...) that `console.rs` consumes;
recommend a `hostfacts` module both depend on.
- `route()` is long; the `/api/*` arm could be an `api_route()`.
- `Dashboard::page()` is now test-only (console renders pages); remove or mark reference-only.
- serve_sim's control loop spins silently if the in-process HAL thread dies; recommend
surfacing the fault and dropping `running` (the real-hardware `boot_hal` loop already exits
on a HAL write error, so this is dev-path only).
- `make-zynq-afw.sh` usage comment omits `--sdk-dir` (doc drift).
- No change-password route exists though the login page tells the operator to change
admin/admin; wire one or soften the text.
## Accepted-by-design posture (stated, not defects)
The box is SSH-guarded and the console is defense-in-depth on a shared network:
- No TLS: the console is HTTP on `0.0.0.0:80`, so a passive sniffer can capture the password
and session cookie. This is the dominant residual risk and should be made explicit to the
operator. A TLS front (or binding the console to a management interface / WireGuard) is the
real mitigation.
- Factory `admin`/`admin` with nothing forcing a change; the login page prints it.
- `/api/terminal` is a gated (session + token) root `/bin/sh` - an accepted diagnostic on an
already-root-reachable box. Note the shipped terminal UI does not send the token, so it is
fail-closed/unusable until a token is supplied.
- The web process runs as root (binds 80); consider a post-bind privilege drop.
- `/api/hardware|summary|control` are intentionally open (interface of record, mirror of the
cgminer socket).
- PBKDF2 at 50k iterations - low by modern standards, accepted behind SSH; matters only if the
hash leaks (now 0600).
- `make-zynq-afw.sh` always passes `--allow-unsigned` (bench-only helper; do not reuse on a
release path).
## Verification after fixes
Live `--serve-sim`: unauthenticated GET / serves the login page; admin/admin issues a session
and the console renders; `/api/files` returns 403 without a token; a CRLF-injected `__section`
is neutralized (303, no header split); the editable deck saves and reloads. clippy -D warnings
clean; 206 lib tests + integration pass.
+179
View File
@@ -0,0 +1,179 @@
# .afw OS install bundle format
Status: schema 2. Released only by `alkane-os`. One `.afw` is valid for exactly
one board family.
An `.afw` is a full OS install bundle: kernel, device tree, rootfs, the
bootable image(s), the partition plan, the boot switch, the preflight rules and
the network recovery path. It is not an application package.
## Container
A strict POSIX ustar archive. No compression, no directory entries, no leading
`./`, no GNU long-name or pax members, and no links. Members are, in this exact
order:
1. `manifest.json`
2. `manifest.json.sig` (only for an Ed25519-signed bundle)
3. Each payload member named by `manifest.images[].file`, in manifest order.
Every member is a regular file. The manifest is at most 64 KiB. The verifier
reads the tar itself: it checks the header checksum, rejects path traversal,
absolute paths, duplicate names, non-regular members and truncated archives,
and requires the two-block end marker. It verifies the manifest and every
payload hash before any consumer may write to a board.
## Manifest
Required members:
| Field | Meaning |
|---|---|
| `schema` | `2` |
| `format` | `afw` |
| `board` | One board family, for example `cv1835` |
| `arch` | `arm64` or `armv7`; must match the board profile |
| `version` | Release version |
| `build_date` | UTC ISO-8601 |
| `sdk_revision` | 40-character SDK git revision |
| `os_revision` | 40-character alkane-os git revision |
| `payload_type` | `os` |
| `bootloader_policy` | `include` or `preserve` |
| `signature` | Signature object, see below |
| `partitions` | Partition plan, see below |
| `images` | Payload images, see below |
| `boot_switch` | How the preserved or written boot path selects the new OS |
| `preflight` | Required commands, forbidden devices, free space, source OS list |
| `recovery` | Network recovery command, held partition, golden copy location |
| `marker` | String served by the installed OS, used by `afw verify-live` |
| `kernel_version` | Kernel release the installed OS must report |
`notes` is optional. Unknown keys are ignored by this schema so a future field
does not break old readers.
### Images
Each image entry has `name`, `file`, `role`, `format`, `size`, `sha256`,
`partition` (or null) and `install` (bool). Roles are `kernel`, `dtb`,
`rootfs`, `bootloader`, `boot` and `component`. Formats are `fit`,
`arm64-image`, `fdt`, `cpio-gzip`, `uimage` and `raw`.
An image with `install: true` must name a partition and is the only kind the
installer writes. Component images (kernel, dtb, rootfs) are carried for
inspection and for boards whose installer composes them; for CV1835 they are
also the inputs of the p1 FIT.
`bootloader_policy: preserve` means no image with role `bootloader` may be
present. `include` means exactly one must be present. The toolkit refuses a
bundle whose policy does not match its board module.
### Partitions
Each partition entry has `name`, `device`, `offset`, `size`, `secure`,
`boot_critical`, `write_order` and `image` (or null). Secure partitions and
`boot0` are declared so preflight can refuse them, never as write targets.
`write_order` is 0 for a region that is not written and a positive order for
an install target.
For CV1835 the plan is:
| Region | Device | Size | Secure | Written |
|---|---|---|---|---|
| `p1` | `/dev/mmcblk0p1` | 16 MiB | no | yes, order 1 |
| `p3` | `/dev/mmcblk0p3` | 32 MiB | yes | no |
| `boot0` | `/dev/mmcblk0boot0` | 4 MiB | yes | no |
| `boot1` | `/dev/mmcblk0boot1` | 4 MiB | yes | no |
The p1 payload is the 16 MiB padded FIT. A FIT larger than the partition is a
build failure. A wrong or missing FIT is a boot failure, not a write failure,
as long as the held p1 backup is present.
## Signatures
`signature` is always an object:
```json
{"type": "unsigned", "member": null, "public_key_hex": null}
```
A signed bundle uses:
```json
{"type": "ed25519", "member": "manifest.json.sig",
"public_key_hex": "<64 hex characters>"}
```
`manifest.json.sig` is the 64-byte raw Ed25519 signature over the exact
`manifest.json` bytes, and is the second member. The key is a 32-byte raw seed
or 64 hex characters in a file named by the release environment; no key value
is stored in this repository. Adding a signature changes only the member set,
not the schema, so unsigned bundles remain readable.
Site use requires a signed bundle. The bench allows an unsigned bundle only
with `--allow-unsigned`, which prints a warning and the payload SHA-256.
## Build and check
The producer stages the manifest and payload, pads the CV p1 FIT to exactly
16 MiB, and packs the members. The checker is the release gate. Both are
offline and use only the Python standard library, except that Ed25519 signing
and verification use the `cryptography` package.
```sh
alkane-os/ci/make-afw.sh \
--board cv1835 --version 0.1.0 \
--input alkane-sdk/build/out/cv1835 \
--sdk-revision "$(git -C alkane-sdk rev-parse HEAD)" \
--os-revision "$(git -C alkane-os rev-parse HEAD)" \
--output alkane-os/dist --allow-unsigned
python3 alkane-os/ci/check-afw.py \
alkane-os/dist/alkane-os-0.1.0-cv1835-arm64.afw \
--allow-unsigned --expect-board cv1835
```
The checker fails on a wrong board or arch, a missing image, an image larger
than its partition, a bootloader member under `preserve`, a hash or size
mismatch, a path-traversal member, a truncated tar, a signed bundle without a
valid signature, or an unsigned bundle without the explicit flag.
## Install rule
The toolkit verifies the whole bundle before opening a transport. It then
preflights the board, holds the current p1 over the network, writes only the
declared install partition, reads the whole partition back, and compares the
hash before it reboots. No install step needs a serial console, an SD card, a
U-Boot prompt, JTAG or a button.
## AM335x (legacy-uImage, non-FIT)
`am335x` is the BeagleBone-class AM335x slice. The board already runs our
non-RSA U-Boot, so the bundle preserves mtd0-5 (SPL, U-Boot, bootenv) and
writes only:
| Region | Device | Size | Image | Order |
|---|---|---|---|---|
| `mtd8` | `/dev/mtd8` | 20 MiB | type-3 ramdisk uImage | 1 |
| `mtd6` | `/dev/mtd6` | 128 KiB | dtb (FDT) | 2 |
| `mtd7` | `/dev/mtd7` | 5 MiB | type-2 kernel uImage | 3 |
`mtd0-5` are declared secure, image-free and outside the write order. Every
partition offset is taken from the 12-entry map, including the unmapped
512 KiB hole at `0x780000-0x800000`; mtd7 ends at `0x780000` and mtd8 starts
at `0x800000`, never `0x780000`. The producer and both checkers refuse an
offset in the hole, a write to mtd0-5, an image over its mtd ceiling, a
bundle carrying an spl/u-boot member, a wrong arch, an oversize image, a
truncated tar, or a traversal member. The images are legacy ARM uImages
(kernel type 2, ramdisk type 3); a FIT is rejected.
```sh
alkane-os/ci/make-afw.sh \
--board am335x --version 0.1.0 \
--input alkane-sdk/build/out/am335x \
--sdk-dir alkane-sdk --plan am335x-plan.json \
--output alkane-os/dist --allow-unsigned
python3 alkane-os/ci/check-afw.py \
alkane-os/dist/alkane-os-0.1.0-am335x-arm.afw \
--allow-unsigned --expect-board am335x
```
+5
View File
@@ -0,0 +1,5 @@
# Vendored flare-ui pin. Re-vendor with scripts, never edit the tree by hand.
repo = https://gitea.bluefla.re/blueflare/flare-ui
branch = sprint
commit = 0e1f5a259faa32798bbb9ff3fedaa0b5faf5302d
vendored = 2026-11-10
+87
View File
@@ -0,0 +1,87 @@
#!/usr/bin/env bash
# Build a zynq-7010 .afw carrying the current alkane-os console.
#
# The SDK builds the base OS (kernel, dtb, rootfs) for the board; this script
# cross-compiles the current alkane-os binary for armv7 (static musl, matching
# the SDK rootfs), drops it and the image overlay (image/overlay) into the SDK's
# rootfs, repacks the ramdisk, and packages the three images into a .afw with
# ci/make-afw.sh. The rootfs is repacked under fakeroot so device nodes and root
# ownership survive. Unsigned is bench-only.
#
# usage:
# image/make-zynq-afw.sh [--sdk-out DIR] [--version X.Y.Z] [--skip-build]
# defaults: --sdk-out ../alkane-sdk/build/out/zynq-7010 --version 0.1.0
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
SDK_OUT="$ROOT/../alkane-sdk/build/out/zynq-7010"
SDK_DIR="$ROOT/../alkane-sdk"
VERSION=0.1.0
TARGET=armv7-unknown-linux-musleabihf
SKIP_BUILD=0
while [ "$#" -gt 0 ]; do
case "$1" in
--sdk-out) SDK_OUT=$2; shift 2 ;;
--sdk-dir) SDK_DIR=$2; shift 2 ;;
--version) VERSION=$2; shift 2 ;;
--skip-build) SKIP_BUILD=1; shift ;;
*) echo "unknown argument: $1" >&2; exit 2 ;;
esac
done
command -v fakeroot >/dev/null 2>&1 || { echo "fakeroot is required" >&2; exit 1; }
SDK_OUT="$(cd "$SDK_OUT" && pwd)"
for f in zImage zynq-alkane.dtb rootfs.cpio.gz; do
[ -f "$SDK_OUT/$f" ] || { echo "missing SDK image: $SDK_OUT/$f (build it in alkane-sdk first)" >&2; exit 1; }
done
TARGET_DIR="${CARGO_TARGET_DIR:-$ROOT/target}"
BIN="$TARGET_DIR/$TARGET/release/alkane-os"
if [ "$SKIP_BUILD" -eq 0 ]; then
echo "cross-compiling alkane-os for $TARGET (static)"
# rustc drives the final link through a C compiler; the host cc cannot link
# ARM objects, so use the ARM cross-gcc as the linker (musl crt + libs come
# from rustup's self-contained target, so only the ARM linker driver is used).
export CARGO_TARGET_ARMV7_UNKNOWN_LINUX_MUSLEABIHF_LINKER="${ARMV7_LINKER:-arm-linux-gnueabihf-gcc}"
( cd "$ROOT" && cargo build --release --offline --target "$TARGET" --bin alkane-os )
fi
[ -f "$BIN" ] || { echo "cross-compiled binary not found: $BIN" >&2; exit 1; }
WORK=$(mktemp -d "${TMPDIR:-/tmp}/zynq-afw.XXXXXX")
trap 'rm -rf "$WORK"' EXIT
mkdir -p "$WORK/in"
echo "staging the console binary"
cp "$BIN" "$WORK/alkane-os"
command -v arm-linux-gnueabihf-strip >/dev/null 2>&1 && arm-linux-gnueabihf-strip "$WORK/alkane-os" || true
echo "repacking the SDK rootfs with the console + overlay (under fakeroot)"
cat > "$WORK/pack.sh" <<'PACK'
set -e
RFS=$1; SDK_OUT=$2; WORK=$3; OVERLAY=$4; VERSION=$5
mkdir -p "$RFS"
( cd "$RFS" && zcat "$SDK_OUT/rootfs.cpio.gz" | cpio -idm --quiet )
install -D -m 0755 "$WORK/alkane-os" "$RFS/usr/bin/alkane-os"
# The .afw version, reported by GET /api/identity (fleet discovery).
printf '%s\n' "$VERSION" > "$RFS/etc/alkane-os-version"
if [ -d "$OVERLAY" ]; then
( cd "$OVERLAY" && find . -type f ) | while IFS= read -r f; do
install -D -m 0755 "$OVERLAY/${f#./}" "$RFS/${f#./}"
done
fi
( cd "$RFS" && find . | cpio -o -H newc --owner=0:0 --quiet | gzip -9 > "$WORK/in/rootfs.cpio.gz" )
PACK
fakeroot -- bash "$WORK/pack.sh" "$WORK/rootfs" "$SDK_OUT" "$WORK" "$ROOT/image/overlay" "$VERSION"
cp "$SDK_OUT/zImage" "$WORK/in/zImage"
cp "$SDK_OUT/zynq-alkane.dtb" "$WORK/in/zynq-alkane.dtb"
echo "packaging the .afw"
"$ROOT/ci/make-afw.sh" \
--board zynq-7010 \
--version "$VERSION" \
--input "$WORK/in" \
--sdk-dir "$SDK_DIR" \
--os-revision "$(git -C "$ROOT" rev-parse HEAD)" \
--output "$ROOT/dist" \
--allow-unsigned
+34
View File
@@ -0,0 +1,34 @@
#!/bin/sh
# S60alkane-web: serve the Alkane console and HTTP API.
#
# Starts after the network (S40). `alkane-os --serve` brings up the web console
# (gated on a login) and the read-only JSON API on port 80, falling back to 8080
# without privilege. The board HAL/mining backend is started separately; this
# only needs the box to be reachable and observable, so every page renders and
# the console works before any hashboard is driven.
#
# This file is part of the alkane-os image overlay (image/overlay), dropped into
# the SDK rootfs at build time. It is intentionally not in the SDK's own init,
# which owns board-detect / network / ssh and leaves the console to alkane-os.
PIDFILE=/run/alkane-web.pid
BIN=/usr/bin/alkane-os
start() {
[ -x "$BIN" ] || { echo "alkane-web: $BIN missing"; exit 1; }
echo "alkane-web: starting console on :80 (falls back to :8080)"
start-stop-daemon -S -b -m -p "$PIDFILE" -x "$BIN" -- --serve
}
stop() {
echo "alkane-web: stopping console"
start-stop-daemon -K -q -p "$PIDFILE" 2>/dev/null
rm -f "$PIDFILE"
}
case "$1" in
start) start ;;
stop) stop ;;
restart) stop; start ;;
*) echo "usage: $0 {start|stop|restart}"; exit 1 ;;
esac
+19
View File
@@ -0,0 +1,19 @@
{
"schema": 1,
"profiles": [
{
"name": "s19jpro-bm1362-pic",
"chip": "bm1362",
"sensor": "pic",
"chains": 3,
"envelope": {"v_min_mv": 1100, "v_max_mv": 1500, "f_min_mhz": 300, "f_max_mhz": 700}
},
{
"name": "s19kpro-bm1366-nopic",
"chip": "bm1366",
"sensor": "nopic",
"chains": 3,
"envelope": {"v_min_mv": 1100, "v_max_mv": 1500, "f_min_mhz": 300, "f_max_mhz": 700}
}
]
}
+639
View File
@@ -0,0 +1,639 @@
{
"format": 1,
"id": "alkane.bb",
"kind": "base",
"menus": [
{
"id": "dashboard",
"slug": "dashboard",
"title": "Dashboard",
"icon": "dashboard",
"band": 0,
"order": 10
},
{
"id": "dashboard/overview",
"slug": "overview",
"title": "Overview",
"order": 10,
"page": "dashboard.overview"
},
{
"id": "dashboard/alerts",
"slug": "alerts",
"title": "Alerts",
"order": 20,
"page": "dashboard.alerts"
},
{
"id": "mining",
"slug": "mining",
"title": "Mining",
"icon": "pickaxe",
"band": 1,
"order": 10
},
{
"id": "mining/overview",
"slug": "overview",
"title": "Overview",
"order": 10,
"page": "mining.overview"
},
{
"id": "mining/hashboards",
"slug": "hashboards",
"title": "Hashboards",
"order": 20,
"page": "mining.hashboards"
},
{
"id": "mining/power",
"slug": "power",
"title": "Power Supply",
"order": 30,
"page": "mining.power"
},
{
"id": "mining/fans",
"slug": "fans",
"title": "Fans",
"order": 40,
"page": "mining.fans"
},
{
"id": "settings",
"slug": "settings",
"title": "Settings",
"icon": "gear",
"band": 2,
"order": 10
},
{
"id": "settings/system",
"slug": "system",
"title": "System",
"order": 10,
"page": "settings.system"
},
{
"id": "settings/tuning",
"slug": "tuning",
"title": "Tuning",
"order": 20,
"page": "settings.tuning"
},
{
"id": "settings/pools",
"slug": "pools",
"title": "Pools",
"order": 30,
"page": "settings.pools"
},
{
"id": "settings/network",
"slug": "network",
"title": "Network",
"order": 40,
"page": "settings.network"
},
{
"id": "settings/security",
"slug": "security",
"title": "Security",
"order": 50,
"page": "settings.security"
},
{
"id": "settings/logs",
"slug": "logs",
"title": "Logs",
"order": 60,
"page": "settings.logs"
},
{
"id": "settings/drivers",
"slug": "drivers",
"title": "Drivers",
"order": 50,
"page": "settings.drivers"
},
{
"id": "settings/services",
"slug": "services",
"title": "Services",
"order": 70,
"page": "settings.services"
},
{
"id": "settings/monitor",
"slug": "monitor",
"title": "Monitor",
"order": 80,
"page": "settings.monitor"
},
{
"id": "settings/files",
"slug": "files",
"title": "Files",
"order": 70,
"page": "settings.files"
},
{
"id": "settings/terminal",
"slug": "terminal",
"title": "Terminal",
"order": 80,
"page": "settings.terminal"
}
],
"pages": [],
"settings": [
{
"path": "tuning.mode",
"label": "Tuning target",
"help": "What the controller holds: a power draw, a hashrate, an ambient margin, or a fan ceiling.",
"kind": {
"t": "enum",
"values": [
{
"v": "power",
"label": "Power"
},
{
"v": "hashrate",
"label": "Hashrate"
},
{
"v": "ambient",
"label": "Ambient"
},
{
"v": "max-fan",
"label": "Max Fan"
}
]
},
"default": {
"value": "power"
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 10,
"apply": {
"class": "none"
},
"display": {
"t": "dropdown"
}
},
{
"path": "tuning.power_w",
"label": "Power target",
"help": "DC power to hold when the target is power.",
"kind": {
"t": "int",
"lo": 200,
"hi": 4000,
"units": "W"
},
"default": {
"value": 1200
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 20,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "tuning.hashrate_ths",
"label": "Hashrate target",
"help": "Hashrate to maximise up to, when the target is hashrate.",
"kind": {
"t": "int",
"lo": 1,
"hi": 200,
"units": "TH/s"
},
"default": {
"value": 60
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 30,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "tuning.ambient_margin_c",
"label": "Ambient margin",
"help": "Hold the hottest sensor this far above measured ambient.",
"kind": {
"t": "int",
"lo": 0,
"hi": 40,
"units": "C"
},
"default": {
"value": 20
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 40,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "tuning.max_fan_pwm",
"label": "Fan ceiling",
"help": "Fan duty cap, percent, when the target is max-fan.",
"kind": {
"t": "int",
"lo": 0,
"hi": 100,
"units": "%"
},
"default": {
"value": 80
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 50,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "tuning.ceiling_mc",
"label": "Frequency ceiling",
"help": "Upper bound on the operating frequency, MHz.",
"kind": {
"t": "int",
"lo": 100,
"hi": 1000,
"units": "MHz"
},
"default": {
"value": 700
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 60,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "tuning.pid.kp_milli",
"label": "Proportional gain",
"help": "PID proportional term, thousandths of a unit.",
"kind": {
"t": "int",
"lo": 0,
"hi": 10000
},
"default": {
"value": 500
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 100,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "tuning.pid.ki_milli",
"label": "Integral gain",
"help": "PID integral term, milli-units.",
"kind": {
"t": "int",
"lo": 0,
"hi": 10000
},
"default": {
"value": 100
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 110,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "tuning.pid.kd_milli",
"label": "Derivative gain",
"help": "PID derivative term, milli-units.",
"kind": {
"t": "int",
"lo": 0,
"hi": 10000
},
"default": {
"value": 0
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 120,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "tuning.pid.out_min_milli",
"label": "Output floor",
"help": "Lowest control output the loop may emit, milli-units.",
"kind": {
"t": "int",
"lo": 0,
"hi": 1000000
},
"default": {
"value": 0
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 130,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "tuning.pid.out_max_milli",
"label": "Output ceiling",
"help": "Highest control output the loop may emit, milli-units.",
"kind": {
"t": "int",
"lo": 0,
"hi": 5000000
},
"default": {
"value": 1000000
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 140,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "tuning.pid.max_step_milli",
"label": "Maximum step",
"help": "Largest output change per second, milli-units.",
"kind": {
"t": "int",
"lo": 0,
"hi": 500000
},
"default": {
"value": 50000
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 150,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "tuning.pid.deadband_milli",
"label": "Deadband",
"help": "Errors inside this band are ignored, milli-units.",
"kind": {
"t": "int",
"lo": 0,
"hi": 50000
},
"default": {
"value": 1000
},
"owner": "synced",
"guarded": false,
"section": "tuning",
"order": 160,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "fans.zone_count",
"label": "Fan zones",
"help": "Number of independently driven fan zones.",
"kind": {
"t": "int",
"lo": 1,
"hi": 8
},
"default": {
"value": 4
},
"owner": "synced",
"guarded": false,
"section": "fans",
"order": 10,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "fans.pwm_min",
"label": "Minimum duty",
"help": "Duty floor applied to every zone, percent.",
"kind": {
"t": "int",
"lo": 0,
"hi": 100,
"units": "%"
},
"default": {
"value": 20
},
"owner": "synced",
"guarded": false,
"section": "fans",
"order": 20,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "fans.sweep_steps",
"label": "Sweep steps",
"help": "Steps per zone when mapping fans to sensors.",
"kind": {
"t": "int",
"lo": 1,
"hi": 32
},
"default": {
"value": 8
},
"owner": "synced",
"guarded": false,
"section": "fans",
"order": 30,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "detect.chain_ports",
"label": "Chain ports",
"help": "Chain UART ports to probe, comma separated.",
"kind": {
"t": "str"
},
"default": {
"value": "1,2,3"
},
"owner": "synced",
"guarded": false,
"section": "detect",
"order": 10,
"apply": {
"class": "none"
},
"display": {
"t": "list"
}
},
{
"path": "detect.probe_budget",
"label": "Probe budget",
"help": "Attempts per chain before detection gives up.",
"kind": {
"t": "int",
"lo": 1,
"hi": 20
},
"default": {
"value": 3
},
"owner": "synced",
"guarded": false,
"section": "detect",
"order": 20,
"apply": {
"class": "none"
},
"display": {
"t": "stepper"
}
},
{
"path": "profiles.db",
"label": "Profile database",
"help": "Path to the board's tuning profile database.",
"kind": {
"t": "str"
},
"default": {
"value": "/etc/alkane/profiles.json"
},
"owner": "synced",
"guarded": false,
"section": "system",
"order": 10,
"apply": {
"class": "none"
},
"display": {
"t": "text"
}
},
{
"path": "system.name",
"label": "Board name",
"help": "Name shown in the dashboard header.",
"kind": {
"t": "str"
},
"default": {
"value": "alkane"
},
"owner": "synced",
"guarded": false,
"section": "system",
"order": 20,
"apply": {
"class": "none"
},
"display": {
"t": "text"
}
}
],
"groups": [],
"actions": [],
"rules": [],
"maps": [],
"legacy_keys": [],
"requires": {
"display_api": 1,
"checks_api": 1
},
"vocab": []
}
+596
View File
@@ -0,0 +1,596 @@
// SPDX-License-Identifier: MIT
//! Process wiring: start the API and UI servers and publish the hardware snapshot.
//!
//! The binary and the tests use the same function, so the wiring that CI exercises is the wiring
//! that runs on a board. Servers are bound before they are spawned, which lets a caller discover
//! ephemeral ports instead of guessing them.
use crate::bus::Bus;
use crate::detect::{
run_detection, DetectionBackend, DetectionFailure, DetectionRequest, FanZone, ProbeBudget,
SensorTopology,
};
use crate::fanmap::{FanMap, MapThresholds, SweepConfig};
use crate::fanmap_store::ensure_map;
use crate::fault::FaultPolicy;
use crate::hal_wire::{HalClient, HalError};
use crate::management::{bind_local, serve, HardwareSnapshot, MiningStatus};
use crate::profiles::{ProfileDb, ProfileError};
use crate::runtime::MinerRuntime;
use crate::tuning::{PidConfig, TuningTarget};
use crate::web;
use std::fmt;
use std::io;
use std::net::{SocketAddr, TcpListener, TcpStream};
use std::path::Path;
use std::sync::Arc;
use std::thread::JoinHandle;
use std::time::Duration;
/// Bound servers and their worker threads.
pub struct Servers {
pub api: Option<SocketAddr>,
pub web: Option<SocketAddr>,
handles: Vec<JoinHandle<()>>,
}
impl Servers {
/// Addresses actually bound, which matters when port 0 was requested.
pub fn addresses(&self) -> (Option<SocketAddr>, Option<SocketAddr>) {
(self.api, self.web)
}
/// Wait for the workers. Only useful in tests; the binary runs until it is killed.
pub fn join(self) {
for handle in self.handles {
let _ = handle.join();
}
}
}
/// Bind and start the cgminer-style API and the web UI, each when an address is given.
pub fn start(
status: Arc<MiningStatus>,
api: Option<SocketAddr>,
web_bind: Option<SocketAddr>,
bus: Arc<Bus>,
) -> io::Result<Servers> {
let api_listener = match api {
Some(address) => Some(bind_local(address)?),
None => None,
};
let api_address = api_listener
.as_ref()
.map(|listener| listener.local_addr())
.transpose()?;
let web_listener = match web_bind {
Some(address) => Some(TcpListener::bind(address)?),
None => None,
};
let web_address = web_listener
.as_ref()
.map(|listener| listener.local_addr())
.transpose()?;
let mut handles = Vec::new();
if let Some(listener) = api_listener {
let snapshot = Arc::clone(&status);
handles.push(std::thread::spawn(move || {
if let Err(error) = serve(listener, snapshot) {
eprintln!("management API stopped: {error}");
}
}));
}
if let Some(listener) = web_listener {
let ctx = web::WebContext::new(Arc::clone(&bus));
handles.push(std::thread::spawn(move || {
if let Err(error) = web::serve_listener(listener, ctx) {
eprintln!("web UI stopped: {error}");
}
}));
}
Ok(Servers {
api: api_address,
web: web_address,
handles,
})
}
/// Build the API snapshot from the live runtime.
pub fn snapshot(runtime: &MinerRuntime, target: &str) -> HardwareSnapshot {
let plan = runtime.plan();
HardwareSnapshot {
plan: plan.clone(),
active_chains: runtime.active_chains(),
stopped: runtime.stop_reason().map(|reason| match reason {
crate::fault::StopReason::Temperature => "temperature",
crate::fault::StopReason::NoChainsLeft => "no chains left",
}),
frequency_mhz: runtime.operating_point().frequency_mhz,
target: target.to_owned(),
}
}
/// Everything a boot needs besides the backend.
#[derive(Clone, Debug, PartialEq)]
pub struct BootConfig {
pub profile_db_json: String,
pub chain_ports: Vec<u8>,
pub sensor: SensorTopology,
pub budget: ProbeBudget,
pub fan_zones: Vec<FanZone>,
pub target: TuningTarget,
pub pid: PidConfig,
pub ceiling_mc: i32,
pub fault_policy: FaultPolicy,
}
/// Why boot did not reach a running runtime.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum BootError<E> {
Profile(ProfileError),
Detection(DetectionFailure<E>),
/// The board backend could not be reached or refused an operation.
Backend(E),
}
impl<E: fmt::Debug> fmt::Display for BootError<E> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Profile(error) => write!(f, "profile database rejected: {error:?}"),
Self::Detection(error) => write!(f, "hardware detection refused: {error:?}"),
Self::Backend(error) => write!(f, "hardware backend failed: {error:?}"),
}
}
}
impl<E: fmt::Debug> std::error::Error for BootError<E> {}
/// Operator target in the form the API and UI report.
pub fn target_label(target: &TuningTarget) -> String {
match *target {
TuningTarget::PowerW(watts) => format!("power:{watts:.0}"),
TuningTarget::HashrateThs(rate) => format!("hashrate:{rate:.0}"),
TuningTarget::AmbientC { margin_mc } => format!("ambient:{margin_mc}"),
TuningTarget::MaxFan { max_pwm } => format!("fan:{max_pwm}"),
}
}
/// Detect, decide, and publish: the sequence a family image runs at start-up.
pub fn boot<B: DetectionBackend>(
backend: &mut B,
config: &BootConfig,
status: &MiningStatus,
) -> Result<MinerRuntime, BootError<B::Error>> {
let db = ProfileDb::from_json(&config.profile_db_json).map_err(BootError::Profile)?;
let request = DetectionRequest {
chain_ports: &config.chain_ports,
budget: config.budget,
sensor: config.sensor,
fan_zones: config.fan_zones.clone(),
};
let plan = run_detection(backend, &db, &request).map_err(BootError::Detection)?;
let runtime = MinerRuntime::new(
plan,
config.fault_policy,
config.target,
config.pid,
config.ceiling_mc,
);
status.set_hardware(snapshot(&runtime, &target_label(&config.target)));
Ok(runtime)
}
/// A boot over the real local HAL contract, including the one-time fan sweep.
pub struct HalBoot<'a> {
pub config: &'a BootConfig,
pub sweep: SweepConfig,
pub thresholds: MapThresholds,
pub map_path: &'a Path,
}
/// Connect the board backend, detect, map the fans once, and publish.
///
/// This is the path an image takes on real hardware; the fakes in the tests speak the same HAL
/// protocol, so the wiring is exercised rather than assumed.
pub fn boot_from_hal(
socket: &Path,
settings: &HalBoot<'_>,
status: &MiningStatus,
) -> Result<(MinerRuntime, FanMap), BootError<HalError>> {
let mut client = HalClient::connect(socket).map_err(BootError::Backend)?;
let zone_count = settings.sweep.zones;
let map = if zone_count == 0 {
FanMap::default()
} else {
ensure_map(
&mut client,
&settings.sweep,
settings.thresholds,
settings.map_path,
|millis| std::thread::sleep(std::time::Duration::from_millis(u64::from(millis))),
)
.map_err(|error| match error {
crate::fanmap_store::StoreError::Sweep(crate::fanmap::SweepError::Backend(error)) => {
BootError::Backend(error)
}
crate::fanmap_store::StoreError::Sweep(_) => {
BootError::Backend(HalError::Protocol("fan sweep configuration rejected"))
}
crate::fanmap_store::StoreError::Io(message) => {
BootError::Backend(HalError::Protocol(message))
}
})?
};
let config = BootConfig {
fan_zones: map.assignments.clone(),
..settings.config.clone()
};
let runtime = boot(&mut client, &config, status)?;
Ok((runtime, map))
}
/// Read one HTTP response body from a bound server, for health checks and tests.
pub fn http_get(address: SocketAddr, path: &str) -> io::Result<String> {
use std::io::{Read, Write};
let mut stream = TcpStream::connect_timeout(&address, Duration::from_secs(2))?;
stream.set_read_timeout(Some(Duration::from_secs(2)))?;
stream.write_all(format!("GET {path} HTTP/1.1\r\nHost: miner\r\n\r\n").as_bytes())?;
let mut reply = String::new();
stream.read_to_string(&mut reply)?;
Ok(reply)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::detect::{
ChainReport, ChipModel, EepromState, Envelope, FanZone, HardwarePlan, OperatingPoint,
};
use crate::detect::{ProbeOutcome, PsuCapability};
use crate::fanmap::{MapThresholds, SweepConfig};
use crate::fault::FaultPolicy;
use crate::tuning::{PidConfig, TuningTarget};
use std::io::{Read, Write};
fn runtime() -> MinerRuntime {
MinerRuntime::new(
HardwarePlan {
profile: "s19jpro-bm1362-pic".into(),
chip: ChipModel::Bm1362,
chains: vec![ChainReport {
index: 0,
chip: ChipModel::Bm1362,
chips_found: 126,
eeprom: EepromState::Absent,
response_per_mille: Some(950),
}],
envelope: Envelope {
v_min_mv: 1100,
v_max_mv: 1500,
f_min_mhz: 300,
f_max_mhz: 700,
},
operating_point: OperatingPoint {
voltage_mv: 1200,
frequency_mhz: 300,
confirmed: false,
},
psu: "APW12".into(),
fan_zones: vec![FanZone {
fan: 0,
zones: vec![0],
}],
},
FaultPolicy::default(),
TuningTarget::PowerW(2_400.0),
PidConfig::default(),
95_000,
)
}
#[test]
fn both_servers_serve_the_published_snapshot() {
let status = Arc::new(MiningStatus::new());
status.set_hardware(snapshot(&runtime(), "power:2400"));
let bus = crate::bus::Bus::new();
let control = Arc::new(crate::control::Control::default());
crate::service::register(&bus, Arc::clone(&status), Arc::clone(&control));
crate::service::publish(&bus, &status, &control);
let servers = start(
Arc::clone(&status),
Some("127.0.0.1:0".parse().unwrap()),
Some("127.0.0.1:0".parse().unwrap()),
bus,
)
.expect("start");
let (api, web) = servers.addresses();
let api = api.expect("api address");
let web = web.expect("web address");
let page = http_get(web, "/api/hardware").expect("web");
assert!(page.contains("s19jpro-bm1362-pic"));
assert!(page.contains("power:2400"));
let mut client =
TcpStream::connect_timeout(&api, Duration::from_secs(2)).expect("api connect");
client
.set_read_timeout(Some(Duration::from_secs(3)))
.expect("timeout");
client.write_all(b"summary").expect("api write");
let mut summary = String::new();
client.read_to_string(&mut summary).expect("api read");
assert!(summary.contains("SUMMARY"));
}
#[test]
fn servers_are_optional() {
let status = Arc::new(MiningStatus::new());
let servers = start(status, None, None, crate::bus::Bus::new()).expect("start");
assert_eq!(servers.addresses(), (None, None));
}
#[test]
fn the_snapshot_reports_runtime_state_not_boot_defaults() {
let mut runtime = runtime();
runtime.tick(&crate::runtime::Tick {
power_w: Some(1_000.0),
hashrate_ths: None,
hottest_mc: Some(60_000),
ambient_mc: None,
dt_s: 1.0,
});
let snapshot = snapshot(&runtime, "power:2400");
assert_eq!(snapshot.target, "power:2400");
assert_eq!(snapshot.active_chains, vec![0]);
assert!(snapshot.frequency_mhz > 300);
assert!(snapshot.stopped.is_none());
}
struct BootBackend {
outcome: ProbeOutcome,
psu: Option<PsuCapability>,
}
impl DetectionBackend for BootBackend {
type Error = ();
fn probe(&mut self, _chain: u8, _attempt: u8) -> Result<ProbeOutcome, ()> {
Ok(self.outcome)
}
fn eeprom(&mut self, _chain: u8) -> Result<EepromState, ()> {
Ok(EepromState::Absent)
}
fn identify_psu(&mut self) -> Result<Option<PsuCapability>, ()> {
Ok(self.psu.clone())
}
}
const DB: &str = r#"{"schema":1,"profiles":[{"name":"s19jpro-bm1362-pic",
"chip":"bm1362","sensor":"pic","chains":3,
"envelope":{"v_min_mv":1100,"v_max_mv":1500,"f_min_mhz":300,"f_max_mhz":700}}]}"#;
fn boot_config() -> BootConfig {
BootConfig {
profile_db_json: DB.into(),
chain_ports: vec![0, 1, 2],
sensor: SensorTopology::Pic,
budget: ProbeBudget::default(),
fan_zones: Vec::new(),
target: TuningTarget::PowerW(2_400.0),
pid: PidConfig::default(),
ceiling_mc: 95_000,
fault_policy: FaultPolicy::default(),
}
}
fn psu() -> PsuCapability {
PsuCapability {
name: "APW12".into(),
envelope: Envelope {
v_min_mv: 1200,
v_max_mv: 1600,
f_min_mhz: 0,
f_max_mhz: 1_000,
},
max_dc_watts: 3_600,
}
}
#[test]
fn boot_detects_and_publishes() {
let mut backend = BootBackend {
outcome: ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
psu: Some(psu()),
};
let status = MiningStatus::new();
let runtime = boot(&mut backend, &boot_config(), &status).expect("boot");
assert_eq!(runtime.active_chains(), vec![0, 1, 2]);
let document = status.hardware_document();
assert_eq!(document["available"], true);
assert_eq!(document["target"], "power:2400");
assert_eq!(document["psu"], "APW12");
}
#[test]
fn boot_refuses_an_unknown_chip() {
let mut backend = BootBackend {
outcome: ProbeOutcome::Silent,
psu: Some(psu()),
};
let status = MiningStatus::new();
assert!(matches!(
boot(&mut backend, &boot_config(), &status),
Err(BootError::Detection(DetectionFailure::Refused(_)))
));
assert_eq!(status.hardware_document()["available"], false);
}
#[test]
fn boot_refuses_a_bad_profile_database() {
let mut backend = BootBackend {
outcome: ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
psu: Some(psu()),
};
let mut config = boot_config();
config.profile_db_json = "{\"schema\": 9}".into();
assert!(matches!(
boot(&mut backend, &config, &MiningStatus::new()),
Err(BootError::Profile(_))
));
}
#[test]
fn boot_refuses_a_missing_psu() {
let mut backend = BootBackend {
outcome: ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
psu: None,
};
assert!(matches!(
boot(&mut backend, &boot_config(), &MiningStatus::new()),
Err(BootError::Detection(DetectionFailure::Refused(_)))
));
}
#[test]
fn target_labels_are_stable() {
assert_eq!(target_label(&TuningTarget::PowerW(3_000.0)), "power:3000");
assert_eq!(
target_label(&TuningTarget::HashrateThs(200.0)),
"hashrate:200"
);
assert_eq!(
target_label(&TuningTarget::AmbientC { margin_mc: 20_000 }),
"ambient:20000"
);
assert_eq!(
target_label(&TuningTarget::MaxFan { max_pwm: 100 }),
"fan:100"
);
}
fn hal_server(socket: std::path::PathBuf) -> std::thread::JoinHandle<()> {
use std::io::{Read, Write};
use std::os::unix::net::UnixListener;
let listener = UnixListener::bind(&socket).expect("bind hal");
std::thread::spawn(move || {
let (mut stream, _) = listener.accept().expect("accept");
loop {
let mut header = [0_u8; 16];
if stream.read_exact(&mut header).is_err() {
return;
}
let opcode = header[5];
let sequence = header[8..12].to_vec();
let length =
u32::from_le_bytes([header[12], header[13], header[14], header[15]]) as usize;
let mut payload = vec![0_u8; length];
if length > 0 && stream.read_exact(&mut payload).is_err() {
return;
}
let body: Vec<u8> = match opcode {
// CAPABILITIES: chain probe, EEPROM, PSU identity.
7 => {
let mut body = vec![0_u8];
body.extend_from_slice(&7_u32.to_le_bytes());
body
}
// PROBE_CHAIN: identified, bm1362, 126 chips.
8 => vec![0, 0, 1, 126, 0],
// READ_EEPROM: absent.
9 => vec![0, 1],
// IDENTIFY_PSU: APW12 with its envelope.
10 => {
let name = b"APW12";
let mut body = vec![0_u8, name.len() as u8];
body.extend_from_slice(name);
for word in [1200_u16, 1600, 0, 1000, 3600] {
body.extend_from_slice(&word.to_le_bytes());
}
body
}
_ => vec![1],
};
let mut out = [0_u8; 16];
out[..4].copy_from_slice(b"ALKH");
out[4] = 1;
out[5] = opcode;
out[6..8].copy_from_slice(&1_u16.to_le_bytes());
out[8..12].copy_from_slice(&sequence);
out[12..16].copy_from_slice(&(body.len() as u32).to_le_bytes());
if stream.write_all(&out).is_err() || stream.write_all(&body).is_err() {
return;
}
}
})
}
#[test]
fn boot_over_the_hal_socket_detects_and_publishes() {
let base = std::env::temp_dir().join(format!("alkane-hal-{}", std::process::id()));
let socket = base.with_extension("sock");
let map_path = base.with_extension("map.json");
let _ = std::fs::remove_file(&socket);
let server = hal_server(socket.clone());
let status = MiningStatus::new();
let config = boot_config();
let settings = HalBoot {
config: &config,
sweep: SweepConfig {
fans: 0,
zones: 0,
low_pwm: 40,
high_pwm: 100,
repeats: 1,
settle_ms: 0,
},
thresholds: MapThresholds::default(),
map_path: &map_path,
};
let (runtime, map) = boot_from_hal(&socket, &settings, &status).expect("boot over hal");
assert_eq!(runtime.active_chains(), vec![0, 1, 2]);
assert!(map.assignments.is_empty());
let document = status.hardware_document();
assert_eq!(document["available"], true);
assert_eq!(document["psu"], "APW12");
assert_eq!(document["chip"], "bm1362");
let _ = std::fs::remove_file(&socket);
let _ = server.join();
}
#[test]
fn boot_over_a_missing_socket_is_a_backend_error() {
let socket =
std::env::temp_dir().join(format!("alkane-missing-{}.sock", std::process::id()));
let status = MiningStatus::new();
let config = boot_config();
let settings = HalBoot {
config: &config,
sweep: SweepConfig {
fans: 0,
zones: 0,
low_pwm: 40,
high_pwm: 100,
repeats: 1,
settle_ms: 0,
},
thresholds: MapThresholds::default(),
map_path: &socket,
};
assert!(matches!(
boot_from_hal(&socket, &settings, &status),
Err(BootError::Backend(_))
));
}
}
+341
View File
@@ -0,0 +1,341 @@
// SPDX-License-Identifier: MIT
//! Web console authentication: a local account and session cookies.
//!
//! Modeled on wardenOS's web auth (spec d05): a local account whose password is
//! stored only as a salted KDF hash, and a `wsid` session cookie issued on
//! login. wardenOS uses Argon2 from its `warden-verifier` crate; alkane-os is
//! dependency-light, so this uses PBKDF2-HMAC-SHA256 built on the crate's own
//! pure-Rust SHA-256 (`pow::sha256`) - a standard password KDF with no new
//! dependency. OIDC and FLARE bundle users are out of scope (no portal here).
//!
//! The box is guarded by SSH; this login is defense-in-depth for the console on
//! a shared network, and the factory account is `admin` / `admin`, which the
//! operator is expected to change.
use crate::pow::sha256;
use serde_json::{json, Value};
use std::collections::HashMap;
use std::fs::{self, OpenOptions};
use std::io::{Read, Write};
use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Mutex;
use std::time::{Duration, SystemTime, UNIX_EPOCH};
/// PBKDF2 iterations. A compromise for the crate's pure-Rust SHA-256: strong
/// enough as defense-in-depth behind SSH, while a single login stays well under
/// a second even on a slow control board.
const PBKDF2_ITERS: u32 = 50_000;
/// How long a session cookie stays valid.
const SESSION_TTL: Duration = Duration::from_secs(12 * 3600);
const AUTH_FILE: &str = "/etc/alkane/auth.json";
fn now_unix() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0)
}
/// 16 bytes (32 hex) from the OS CSPRNG. The single random-token source for the
/// console (CSRF token and session ids). If `/dev/urandom` is unreadable it
/// fails LOUD and still avoids a fixed/guessable value: a per-call mix (nanos,
/// pid, a process counter, a stack address) hashed through SHA-256, distinct on
/// every call. Not a CSPRNG, but never the published constant it replaced.
pub(crate) fn rand_hex() -> String {
if let Ok(mut f) = fs::File::open("/dev/urandom") {
let mut b = [0_u8; 16];
if f.read_exact(&mut b).is_ok() {
return hex(&b);
}
}
static CTR: AtomicU64 = AtomicU64::new(0);
eprintln!("alkane auth: WARNING /dev/urandom unreadable; session/token entropy is degraded");
let n = CTR.fetch_add(1, Ordering::Relaxed);
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_nanos() as u64)
.unwrap_or(0);
let stack = &n as *const _ as u64;
let mix = nanos
^ (std::process::id() as u64).rotate_left(17)
^ n.rotate_left(33)
^ stack.rotate_left(49);
hex(&sha256(&mix.to_le_bytes())[..16])
}
fn hex(bytes: &[u8]) -> String {
let mut s = String::with_capacity(bytes.len() * 2);
for b in bytes {
s.push_str(&format!("{b:02x}"));
}
s
}
fn unhex(text: &str) -> Vec<u8> {
(0..text.len() / 2)
.filter_map(|i| u8::from_str_radix(text.get(i * 2..i * 2 + 2)?, 16).ok())
.collect()
}
/// HMAC-SHA256 over the crate's SHA-256.
fn hmac_sha256(key: &[u8], msg: &[u8]) -> [u8; 32] {
const BLOCK: usize = 64;
let mut k = [0_u8; BLOCK];
if key.len() > BLOCK {
k[..32].copy_from_slice(&sha256(key));
} else {
k[..key.len()].copy_from_slice(key);
}
let mut ipad = [0x36_u8; BLOCK];
let mut opad = [0x5c_u8; BLOCK];
for i in 0..BLOCK {
ipad[i] ^= k[i];
opad[i] ^= k[i];
}
let mut inner = Vec::with_capacity(BLOCK + msg.len());
inner.extend_from_slice(&ipad);
inner.extend_from_slice(msg);
let ih = sha256(&inner);
let mut outer = Vec::with_capacity(BLOCK + 32);
outer.extend_from_slice(&opad);
outer.extend_from_slice(&ih);
sha256(&outer)
}
/// PBKDF2-HMAC-SHA256 producing one 32-byte block (dkLen == hLen).
fn pbkdf2_sha256(password: &[u8], salt: &[u8], iters: u32) -> [u8; 32] {
let mut block1 = salt.to_vec();
block1.extend_from_slice(&1_u32.to_be_bytes());
let mut u = hmac_sha256(password, &block1);
let mut t = u;
for _ in 1..iters.max(1) {
u = hmac_sha256(password, &u);
for i in 0..32 {
t[i] ^= u[i];
}
}
t
}
/// Constant-time comparison of two byte slices.
pub(crate) fn ct_eq(a: &[u8], b: &[u8]) -> bool {
if a.len() != b.len() {
return false;
}
let mut diff = 0_u8;
for i in 0..a.len() {
diff |= a[i] ^ b[i];
}
diff == 0
}
/// The stored local account.
#[derive(Clone, Debug)]
struct Account {
user: String,
salt: Vec<u8>,
iters: u32,
hash: Vec<u8>,
}
impl Account {
fn factory() -> Self {
Self::with_password("admin", "admin")
}
fn with_password(user: &str, password: &str) -> Self {
let salt = unhex(&rand_hex());
let hash = pbkdf2_sha256(password.as_bytes(), &salt, PBKDF2_ITERS).to_vec();
Self {
user: user.to_string(),
salt,
iters: PBKDF2_ITERS,
hash,
}
}
fn to_json(&self) -> Value {
json!({
"user": self.user,
"salt": hex(&self.salt),
"iters": self.iters,
"hash": hex(&self.hash),
})
}
fn from_json(v: &Value) -> Option<Self> {
Some(Self {
user: v.get("user")?.as_str()?.to_string(),
salt: unhex(v.get("salt")?.as_str()?),
iters: v.get("iters")?.as_u64()? as u32,
hash: unhex(v.get("hash")?.as_str()?),
})
}
fn verify(&self, user: &str, password: &str) -> bool {
let candidate = pbkdf2_sha256(password.as_bytes(), &self.salt, self.iters);
// Compare the user name too, but not in constant time (it is not secret).
user == self.user && ct_eq(&candidate, &self.hash)
}
}
/// The console auth state: one local account and the live sessions.
pub struct Auth {
account: Account,
sessions: Mutex<HashMap<String, u64>>,
path: PathBuf,
}
impl Auth {
/// Load the account from `AUTH_FILE`, creating the factory `admin`/`admin`
/// account (persisted when the path is writable) on first run.
pub fn load() -> Self {
Self::load_from(Path::new(AUTH_FILE))
}
pub fn load_from(path: &Path) -> Self {
let account = fs::read_to_string(path)
.ok()
.and_then(|t| serde_json::from_str::<Value>(&t).ok())
.and_then(|v| Account::from_json(&v))
.unwrap_or_else(|| {
let account = Account::factory();
persist(path, &account);
account
});
Self {
account,
sessions: Mutex::new(HashMap::new()),
path: path.to_path_buf(),
}
}
/// Check a login. On success return a fresh `wsid`.
pub fn login(&self, user: &str, password: &str) -> Option<String> {
if !self.account.verify(user, password) {
return None;
}
let wsid = rand_hex() + &rand_hex();
// Only hand back a cookie if the session was actually recorded; a
// poisoned lock must not mint a token that `valid` will always reject.
match self.sessions.lock() {
Ok(mut s) => {
s.insert(wsid.clone(), now_unix() + SESSION_TTL.as_secs());
Some(wsid)
}
Err(_) => None,
}
}
/// True when `wsid` names a live, unexpired session.
pub fn valid(&self, wsid: &str) -> bool {
if wsid.is_empty() {
return false;
}
let now = now_unix();
let mut sessions = match self.sessions.lock() {
Ok(s) => s,
Err(_) => return false,
};
sessions.retain(|_, &mut exp| exp > now);
sessions.get(wsid).is_some_and(|&exp| exp > now)
}
/// End a session.
pub fn logout(&self, wsid: &str) {
if let Ok(mut s) = self.sessions.lock() {
s.remove(wsid);
}
}
/// The path the account is stored at (for diagnostics).
pub fn store_path(&self) -> &Path {
&self.path
}
}
fn persist(path: &Path, account: &Account) {
if let Some(parent) = path.parent() {
if fs::create_dir_all(parent).is_err() {
eprintln!(
"alkane auth: cannot create {}; account not persisted",
parent.display()
);
return;
}
let _ = fs::set_permissions(parent, fs::Permissions::from_mode(0o700));
}
// The file holds the password hash: create it 0600, not umask-default.
let text = serde_json::to_string_pretty(&account.to_json()).unwrap_or_default();
match OpenOptions::new()
.write(true)
.create(true)
.truncate(true)
.mode(0o600)
.open(path)
{
Ok(mut file) => {
let _ = file.write_all(text.as_bytes());
}
Err(error) => eprintln!("alkane auth: cannot write {}: {error}", path.display()),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn hmac_matches_rfc4231_case_2() {
// RFC 4231 test case 2: key "Jefe", data "what do ya want for nothing?".
let mac = hmac_sha256(b"Jefe", b"what do ya want for nothing?");
assert_eq!(
hex(&mac),
"5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843"
);
}
#[test]
fn pbkdf2_matches_a_known_vector() {
// RFC 7914 / standard PBKDF2-HMAC-SHA256: P="passwd", S="salt", c=1.
let dk = pbkdf2_sha256(b"passwd", b"salt", 1);
assert_eq!(&hex(&dk)[..16], "55ac046e56e3089f");
}
fn temp(name: &str) -> PathBuf {
let mut p = std::env::temp_dir();
p.push(format!("alkane-auth-{name}-{}.json", std::process::id()));
let _ = fs::remove_file(&p);
p
}
#[test]
fn factory_account_accepts_admin_admin_and_rejects_others() {
let auth = Auth::load_from(&temp("factory"));
assert!(auth.login("admin", "admin").is_some());
assert!(auth.login("admin", "wrong").is_none());
assert!(auth.login("root", "admin").is_none());
}
#[test]
fn a_session_is_valid_until_logout() {
let auth = Auth::load_from(&temp("session"));
let wsid = auth.login("admin", "admin").expect("login");
assert!(auth.valid(&wsid));
assert!(!auth.valid("not-a-session"));
auth.logout(&wsid);
assert!(!auth.valid(&wsid));
}
#[test]
fn the_account_persists_and_reloads() {
let path = temp("persist");
let _ = Auth::load_from(&path);
assert!(path.exists(), "the factory account should be written");
let again = Auth::load_from(&path);
assert!(again.login("admin", "admin").is_some());
let _ = fs::remove_file(&path);
}
}
+29
View File
@@ -0,0 +1,29 @@
// SPDX-License-Identifier: MIT
//! Control for the size measurement: the same page shape rendered without
//! flare-ui, so `check-ui-size.sh` reports the marginal cost of the dependency
//! rather than the cost of a Rust binary at all.
fn main() {
let sections = [
("dashboard", "Dashboard"),
("mining", "Mining"),
("settings", "Settings"),
];
let body = maud::html! {
section class="bf-card" {
h1 class="bf-text-title" { "Alkane OS" }
p class="bf-text-body" { "Schema-driven page." }
}
};
let mut html = String::from("<!doctype html><html><body>");
for (slug, title) in sections {
html.push_str(&format!("<a href=\"/{slug}\">{title}</a>"));
}
html.push_str(&body.into_string());
html.push_str("</body></html>");
println!(
"{} {}",
html.len(),
serde_json::json!({"sections": sections.len()})
);
}
+78
View File
@@ -0,0 +1,78 @@
// SPDX-License-Identifier: MIT
//! Spike: render the on-box UI from a schema document through flare-ui.
//!
//! This is the incorporation test, not the final UI. It answers three questions
//! with evidence rather than argument:
//!
//! 1. does a hand-authored Alkane schema drive the unified sidebar through
//! `flare_ui::nav` + `flare_ui::shell`?
//! 2. does the page render with the shared design tokens?
//! 3. what does it cost in a firmware binary?
//!
//! Run it, then compare `--size` against the current hand-rolled renderer.
use flare_ui::assets::PageAssets;
use flare_ui::nav::{self, AllowAll, AppSet, CapSet};
use flare_ui::shell::{self, Active};
use flare_ui::url::Routes;
use wschema::model::{Document, Surface};
/// The schema is the single source of the UI: sections, tabs and their order.
const RECIPE_SCHEMA: &str = include_str!("../../schema/alkane-bb.json");
fn main() {
let schema = match Document::from_json(RECIPE_SCHEMA) {
Ok(schema) => schema,
Err(error) => {
eprintln!("schema did not parse: {error}");
std::process::exit(1);
}
};
// Capabilities the board actually reports decide what is visible. On a real
// board these come from the HAL; here they are the bb set.
let caps = CapSet::new(["hashboard-bm1395", "psu-apm", "pid-fan", "cgminer-api"]);
let routes = Routes::console();
let apps = AppSet::default();
let ctx = nav::NavContext {
surface: Surface::Web,
principal: &AllowAll,
caps: &caps,
apps: &apps,
routes: &routes,
};
let visible = nav::visible(&schema.menus, &ctx);
let first = visible
.first_tab()
.map(|(section, tab)| Active { section, tab });
let active = first.unwrap_or(Active {
section: "",
tab: "",
});
let body = maud::html! {
section class="bf-card" {
h1 class="bf-text-title" { "Alkane OS" }
p class="bf-text-body" { "Schema-driven page. Sections and tabs above come from dashboard.json." }
}
};
let assets = PageAssets::default();
let page = shell::page("Alkane OS", &assets, &visible, active, body);
let html = page.into_string();
if std::env::args().any(|arg| arg == "--size") {
println!("html_bytes {}", html.len());
println!("sections {}", visible.sections.len());
for section in &visible.sections {
println!(
"section {} ({}) tabs={}",
section.slug,
section.title,
section.tabs.len()
);
}
} else {
println!("{html}");
}
}
+203
View File
@@ -0,0 +1,203 @@
// SPDX-License-Identifier: MIT
//! BM1370 wire frames observed on an S21 Pro. This module does not control power.
use crate::bm13xx::{crc16, crc5};
pub use crate::bm1362::Job;
pub const JOB_BYTES: usize = 88;
pub const REPORT_BYTES: usize = 11;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct NonceReport {
pub nonce: u32,
pub byte6: u8,
pub byte7: u8,
pub byte8: u8,
pub byte9: u8,
/// Raw trailer: bit 7 marks a nonce response; bits 4:0 carry CRC5.
/// No chip identity is inferred from this byte.
pub trailer: u8,
}
impl NonceReport {
/// Work ID observed in the Braiins S21 Pro capture. Chip and version
/// attribution remain unknown, and this has no accepted-share proof.
pub fn observed_work_id(&self) -> u8 {
(self.byte7 & 0xf0) >> 1
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ReportError {
Length,
Preamble,
RegisterResponse,
Checksum,
}
/// Encode only the job shape observed in the S21 Pro capture. `Job` fields
/// are in wire order; this does not validate a pool header or start a chain.
pub fn encode_job(job: &Job) -> Option<[u8; JOB_BYTES]> {
if job.work_id & 7 != 0 || job.num_midstates != 1 || job.start_nonce != 0 {
return None;
}
let mut frame = crate::bm1362::encode_job(job);
frame[3] = 0x36;
let checksum = crc16(&frame[2..86]);
frame[86..88].copy_from_slice(&checksum.to_be_bytes());
Some(frame)
}
/// Keep the five trailing bytes raw. The work-ID expression is correlated with
/// same-UART jobs in one capture; chip and version mapping remain unverified.
/// The marker bit distinguishes nonce reports from register replies.
pub fn decode_nonce_report(frame: &[u8]) -> Result<NonceReport, ReportError> {
if frame.len() != REPORT_BYTES {
return Err(ReportError::Length);
}
if frame[..2] != [0xaa, 0x55] {
return Err(ReportError::Preamble);
}
if frame[10] & 0x80 == 0 {
return Err(ReportError::RegisterResponse);
}
if crc5(&frame[2..]) != 0 {
return Err(ReportError::Checksum);
}
Ok(NonceReport {
nonce: u32::from_le_bytes(frame[2..6].try_into().expect("four-byte nonce")),
byte6: frame[6],
byte7: frame[7],
byte8: frame[8],
byte9: frame[9],
trailer: frame[10],
})
}
#[cfg(test)]
mod tests {
use super::*;
// firmware-analysis/prong-b/s21-192/c2-steady.strace, SHA-256
// c0aac1222e05e95bdcbd1de5a8ee244a581256e8f28e3dadf5300df6110229c7.
const CAPTURED_JOB: &str = concat!(
"55aa21366001000000008f060217834f276af0f09aafc588165b7fbfc56f8f09a55d3d0de5",
"798bd87460278af180c4696fc200000000000000008af701003acc10cdebe5bc3c90f095e5",
"03c6b7de69ca8b5d00000020e769"
);
fn captured_bytes<const N: usize>(hex: &str) -> [u8; N] {
assert_eq!(hex.len(), N * 2);
let mut bytes = [0; N];
for (index, pair) in hex.as_bytes().chunks_exact(2).enumerate() {
bytes[index] = u8::from_str_radix(std::str::from_utf8(pair).unwrap(), 16).unwrap();
}
bytes
}
fn with_valid_crc(mut frame: [u8; REPORT_BYTES]) -> [u8; REPORT_BYTES] {
for checksum in 0..32 {
frame[10] = (frame[10] & 0xe0) | checksum;
if crc5(&frame[2..]) == 0 {
return frame;
}
}
panic!("no valid CRC5 trailer");
}
#[test]
fn live_job_matches_all_88_bytes() {
let captured = captured_bytes::<JOB_BYTES>(CAPTURED_JOB);
let mut merkle_root = [0; 32];
merkle_root.copy_from_slice(&captured[18..50]);
let mut previous_hash = [0; 32];
previous_hash.copy_from_slice(&captured[50..82]);
let job = Job {
work_id: captured[4],
num_midstates: captured[5],
start_nonce: u32::from_le_bytes(captured[6..10].try_into().unwrap()),
nbits: u32::from_le_bytes(captured[10..14].try_into().unwrap()),
ntime: u32::from_le_bytes(captured[14..18].try_into().unwrap()),
merkle_root,
previous_hash,
version: u32::from_le_bytes(captured[82..86].try_into().unwrap()),
};
assert_eq!(encode_job(&job), Some(captured));
let mut invalid = job;
invalid.work_id |= 1;
assert_eq!(encode_job(&invalid), None);
invalid = job;
invalid.num_midstates = 2;
assert_eq!(encode_job(&invalid), None);
invalid = job;
invalid.start_nonce = 1;
assert_eq!(encode_job(&invalid), None);
assert_eq!(
crc16(&captured[2..86]),
u16::from_be_bytes([captured[86], captured[87]])
);
}
#[test]
fn live_nonce_reports_preserve_raw_tags() {
for hex in [
"aa555804a92a041e133e86",
"aa55771def23001c16fc82",
"aa5574480ae6021417b492",
] {
let frame = captured_bytes::<REPORT_BYTES>(hex);
let report = decode_nonce_report(&frame).unwrap();
assert_eq!(
report.nonce,
u32::from_le_bytes(frame[2..6].try_into().unwrap())
);
assert_eq!(report.byte6, frame[6]);
assert_eq!(report.byte7, frame[7]);
assert_eq!(report.byte8, frame[8]);
assert_eq!(report.byte9, frame[9]);
assert_eq!(report.trailer, frame[10]);
}
}
#[test]
fn observed_work_id_matches_same_uart_job() {
// c2-steady.strace lines 1287 and 1352: job byte 4 is 0x10.
let frame = captured_bytes::<REPORT_BYTES>("aa554a3488c70022013291");
let report = decode_nonce_report(&frame).unwrap();
assert_eq!(report.observed_work_id(), 0x10);
assert_eq!(report.byte7, 0x22);
}
#[test]
fn invalid_report_fails_closed() {
let mut frame = captured_bytes::<REPORT_BYTES>("aa555804a92a041e133e86");
assert_eq!(decode_nonce_report(&frame[..10]), Err(ReportError::Length));
frame[0] = 0;
assert_eq!(decode_nonce_report(&frame), Err(ReportError::Preamble));
frame[0] = 0xaa;
frame[10] &= 0x60;
frame = with_valid_crc(frame);
assert_eq!(crc5(&frame[2..]), 0);
assert_eq!(
decode_nonce_report(&frame),
Err(ReportError::RegisterResponse)
);
frame[10] |= 0x80;
frame = with_valid_crc(frame);
frame[4] ^= 1;
assert_eq!(decode_nonce_report(&frame), Err(ReportError::Checksum));
}
#[test]
fn trailer_low_bits_are_checksum_not_chip_identity() {
let original = captured_bytes::<REPORT_BYTES>("aa555804a92a041e133e86");
let mut changed_nonce = original;
changed_nonce[2] ^= 1;
changed_nonce = with_valid_crc(changed_nonce);
assert_eq!(crc5(&changed_nonce[2..]), 0);
assert_ne!(changed_nonce[10] & 0x1f, original[10] & 0x1f);
assert_eq!(changed_nonce[10] & 0xe0, original[10] & 0xe0);
assert!(decode_nonce_report(&changed_nonce).is_ok());
}
}
+286
View File
@@ -0,0 +1,286 @@
// SPDX-License-Identifier: MIT
//! The command/state bus: the single point of command for the miner.
//!
//! Modeled on wardenOS's bus (flare-edge `sprint`): one hub that the HTTP API,
//! the web UI, and any future remote/flare client all go through, so there is no
//! second way to change the machine. State is *retained* - a reader subscribes
//! to / reads a topic and gets the last published document - and commands are
//! *request/reply* to the service that owns the verb.
//!
//! wardenOS runs this as an MQTT-5 broker over a Unix socket with per-user ACLs.
//! Here the wire is in-process (std threads, no broker, no async): the facade
//! below - `publish_state` / `read_state` / `request` / `emit` - matches the
//! warden `Bus` surface, so callers never learn the transport and the broker can
//! be swapped in later without touching them. The registry in `registry.rs` is
//! the contract (topics and verbs), exactly as warden's `topics.json` is.
//!
//! Topic kinds, mirroring warden:
//! - `state` (retained): telemetry and status. Read = `read_state`.
//! - `evt` (not retained): events (log lines, faults). `emit` keeps a bounded
//! ring the UI and API can tail.
//! - `req`/`reply`: a command to an owning service. `register` + `request`.
use serde_json::{json, Value};
use std::collections::{BTreeMap, VecDeque};
use std::sync::{Arc, Mutex, RwLock};
use std::time::{SystemTime, UNIX_EPOCH};
/// How many recent events the bus keeps for tailing.
const EVENT_RING: usize = 256;
/// Why a request could not be served. Serializes to the warden-style
/// `{ "error": CODE, "message": ... }` envelope.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum BusError {
/// No service owns this verb.
NoHandler(String),
/// The request body was malformed for this verb.
BadRequest(String),
/// The owning service refused the request (out of range, wrong state).
Rejected(String),
}
impl BusError {
pub fn code(&self) -> &'static str {
match self {
BusError::NoHandler(_) => "E_NO_HANDLER",
BusError::BadRequest(_) => "E_BAD_REQUEST",
BusError::Rejected(_) => "E_REJECTED",
}
}
pub fn message(&self) -> &str {
match self {
BusError::NoHandler(m) | BusError::BadRequest(m) | BusError::Rejected(m) => m,
}
}
/// The JSON error envelope a surface returns to its client.
pub fn envelope(&self) -> Value {
json!({ "error": self.code(), "message": self.message() })
}
}
impl std::fmt::Display for BusError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}: {}", self.code(), self.message())
}
}
impl std::error::Error for BusError {}
/// A command handler: owns one verb, validates and applies the request, and
/// returns the result document (or a [`BusError`]).
pub type Handler = Box<dyn Fn(&Value) -> Result<Value, BusError> + Send + Sync>;
/// One emitted event, kept in the ring for tailing.
#[derive(Clone, Debug)]
pub struct Event {
pub topic: String,
pub body: Value,
pub at_unix: u64,
}
/// The in-process bus.
pub struct Bus {
state: RwLock<BTreeMap<String, Value>>,
handlers: RwLock<BTreeMap<String, Handler>>,
events: Mutex<VecDeque<Event>>,
}
impl Default for Bus {
fn default() -> Self {
Self::new_inner()
}
}
impl Bus {
fn new_inner() -> Self {
Self {
state: RwLock::new(BTreeMap::new()),
handlers: RwLock::new(BTreeMap::new()),
events: Mutex::new(VecDeque::with_capacity(EVENT_RING)),
}
}
/// A shared bus handle. The hub is cheap to clone (`Arc`).
pub fn new() -> Arc<Self> {
Arc::new(Self::new_inner())
}
// --- state (retained) ----------------------------------------------------
/// Publish a retained state document. A later reader gets this verbatim.
pub fn publish_state(&self, topic: &str, doc: Value) {
if let Ok(mut map) = self.state.write() {
map.insert(topic.to_string(), doc);
}
}
/// Read the last retained document for a topic, if any.
pub fn read_state(&self, topic: &str) -> Option<Value> {
self.state
.read()
.ok()
.and_then(|map| map.get(topic).cloned())
}
/// Read a retained document, or a fallback when nothing is published yet.
pub fn read_state_or(&self, topic: &str, fallback: Value) -> Value {
self.read_state(topic).unwrap_or(fallback)
}
/// Drop a retained document (the warden "clear via empty will" semantics).
pub fn clear_state(&self, topic: &str) {
if let Ok(mut map) = self.state.write() {
map.remove(topic);
}
}
/// Every state topic currently published, for introspection and parity tests.
pub fn state_topics(&self) -> Vec<String> {
self.state
.read()
.map(|map| map.keys().cloned().collect())
.unwrap_or_default()
}
// --- commands (request/reply) --------------------------------------------
/// Register the service that owns `verb`. Re-registering replaces it.
pub fn register<F>(&self, verb: &str, handler: F)
where
F: Fn(&Value) -> Result<Value, BusError> + Send + Sync + 'static,
{
if let Ok(mut map) = self.handlers.write() {
map.insert(verb.to_string(), Box::new(handler));
}
}
/// Dispatch a command to its owning service. This is the single write path:
/// the API and the UI both call this, so a verb cannot be driven two ways.
pub fn request(&self, verb: &str, body: &Value) -> Result<Value, BusError> {
let map = self
.handlers
.read()
.map_err(|_| BusError::Rejected("bus handler lock poisoned".into()))?;
let handler = map
.get(verb)
.ok_or_else(|| BusError::NoHandler(format!("no service owns {verb}")))?;
handler(body)
}
/// True when a service owns the verb.
pub fn has_verb(&self, verb: &str) -> bool {
self.handlers
.read()
.map(|m| m.contains_key(verb))
.unwrap_or(false)
}
/// Every registered verb, sorted, for introspection and parity tests.
pub fn verbs(&self) -> Vec<String> {
self.handlers
.read()
.map(|map| map.keys().cloned().collect())
.unwrap_or_default()
}
// --- events (non-retained) -----------------------------------------------
/// Emit an event onto the ring (faults, log lines, notices).
pub fn emit(&self, topic: &str, body: Value) {
let at_unix = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0);
if let Ok(mut ring) = self.events.lock() {
if ring.len() == EVENT_RING {
ring.pop_front();
}
ring.push_back(Event {
topic: topic.to_string(),
body,
at_unix,
});
}
}
/// The most recent `n` events, oldest first.
pub fn recent_events(&self, n: usize) -> Vec<Event> {
self.events
.lock()
.map(|ring| ring.iter().rev().take(n).rev().cloned().collect())
.unwrap_or_default()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn retained_state_round_trips() {
let bus = Bus::new();
assert_eq!(bus.read_state("miner/state/x"), None);
bus.publish_state("miner/state/x", json!({"v": 1}));
assert_eq!(bus.read_state("miner/state/x"), Some(json!({"v": 1})));
bus.publish_state("miner/state/x", json!({"v": 2}));
assert_eq!(bus.read_state("miner/state/x").unwrap()["v"], 2);
bus.clear_state("miner/state/x");
assert_eq!(bus.read_state("miner/state/x"), None);
}
#[test]
fn a_request_reaches_its_owning_handler() {
let bus = Bus::new();
bus.register("control/echo", |body| Ok(body.clone()));
let out = bus.request("control/echo", &json!({"hi": true})).unwrap();
assert_eq!(out["hi"], true);
}
#[test]
fn an_unowned_verb_is_a_no_handler_error() {
let bus = Bus::new();
let err = bus.request("nope", &json!({})).unwrap_err();
assert_eq!(err.code(), "E_NO_HANDLER");
assert_eq!(err.envelope()["error"], "E_NO_HANDLER");
}
#[test]
fn a_handler_can_reject_and_the_code_is_preserved() {
let bus = Bus::new();
bus.register("control/set", |_| {
Err(BusError::Rejected("out of range".into()))
});
let err = bus.request("control/set", &json!({})).unwrap_err();
assert_eq!(err.code(), "E_REJECTED");
assert_eq!(err.message(), "out of range");
}
#[test]
fn registering_a_verb_replaces_the_prior_owner() {
let bus = Bus::new();
bus.register("v", |_| Ok(json!(1)));
bus.register("v", |_| Ok(json!(2)));
assert_eq!(bus.request("v", &json!({})).unwrap(), json!(2));
assert!(bus.has_verb("v"));
assert_eq!(bus.verbs(), vec!["v".to_string()]);
}
#[test]
fn the_event_ring_is_bounded_and_ordered() {
let bus = Bus::new();
for i in 0..(EVENT_RING + 10) {
bus.emit("evt/log", json!({ "i": i }));
}
let recent = bus.recent_events(5);
assert_eq!(recent.len(), 5);
// oldest-first, and the very last is the newest emitted.
assert_eq!(
recent.last().unwrap().body["i"],
(EVENT_RING + 10 - 1) as i64
);
assert!(recent[0].body["i"].as_i64().unwrap() < recent[1].body["i"].as_i64().unwrap());
}
}
+564
View File
@@ -0,0 +1,564 @@
// SPDX-License-Identifier: MIT
//! The flare-ui console: every navigation tab rendered with live data and real
//! controls, inside the shared `flare-ui` shell.
//!
//! Content comes from the bus: telemetry is read from `state` topics and every
//! control is a form that POSTs to a bus verb through `web.rs`. Host facts (the
//! system/security/logs/files/terminal pages) are read directly. The module is
//! built entirely from `flare-ui` primitives so the on-box console is the
//! parameterised FLARE UI rather than a second hand-written one.
use std::collections::BTreeMap;
use maud::{html, Markup, PreEscaped};
use serde_json::Value;
use flare_ui::actions::{self, Tone};
use flare_ui::components;
use flare_ui::nav::VisibleNav;
use flare_ui::readings::{self, Level, Reading};
use flare_ui::render::{self, View};
use flare_ui::shell::{self, Active};
use wschema::model::Surface;
use crate::bus::Bus;
use crate::dashboard::Dashboard;
use crate::registry::topics;
use crate::{service, web};
/// Render one navigation tab. `section`/`tab` are already validated by the
/// caller. `errors` carries messages from a rejected form (`""` = a general
/// banner, a path key = a field error).
pub fn page(
bus: &Bus,
csrf: &str,
section: &str,
tab: &str,
errors: &BTreeMap<String, String>,
) -> Markup {
let dash = Dashboard::load(service::settings_path());
let nav = dash.nav().unwrap_or_default();
let title = tab_title(&nav, section, tab);
let hw = bus.read_state_or(topics::HARDWARE, serde_json::json!({"available": false}));
let ctl = bus.read_state_or(topics::CONTROL, serde_json::json!({"running": false}));
let body = match (section, tab) {
("dashboard", "overview") | ("", "") => editable_dashboard(),
("dashboard", "alerts") => alerts_card(&hw),
("mining", "overview") => control_card(&hw, &ctl, csrf),
("mining", "hashboards") => hashboards_card(&hw),
("mining", "power") => power_card(&hw),
("mining", "fans") => fans_card(&hw),
("settings", "system") => system_card(),
("settings", "tuning") => tuning_card(&dash, &ctl, csrf, errors),
("settings", "pools") => pools_card(),
("settings", "network") => network_card(),
("settings", "drivers") => drivers_card(&hw),
("settings", "security") => security_card(),
("settings", "services") => services_card(),
("settings", "monitor") => monitor_card(&hw),
("settings", "logs") => logs_card(),
("settings", "files") => files_card(),
("settings", "terminal") => terminal_card(),
_ => components::card(&title, readings::note("This page has no content yet.")),
};
shell::page(
"Alkane OS",
&Dashboard::assets(),
&nav,
Active { section, tab },
body,
)
}
/// The sign-in page: a standalone card (no nav) styled with the flare-ui tokens,
/// modeled on wardenOS's local login.
pub fn login_page(csrf: &str, error: Option<&str>) -> Markup {
html! {
(maud::DOCTYPE)
html lang="en" {
head {
meta charset="utf-8";
meta name="viewport" content="width=device-width, initial-scale=1";
title { "Alkane OS - Sign in" }
link rel="stylesheet" href="/assets/tokens.css";
link rel="stylesheet" href="/assets/components.css";
link rel="stylesheet" href="/assets/theme.css";
}
body class="bf-shell" {
main class="bf-main" {
section class="bf-card" {
h1 class="bf-text-title" { "Alkane OS" }
@if let Some(message) = error {
p class="bf-field-error bf-text-body" role="alert" { (message) }
}
form class="bf-form" method="post" action="/auth/local" {
input type="hidden" name="csrf" value=(csrf);
div class="bf-field" {
label {
span class="bf-field-label bf-text-label" { "User" }
input class="bf-input" type="text" name="user" autocomplete="username";
}
}
div class="bf-field" {
label {
span class="bf-field-label bf-text-label" { "Password" }
input class="bf-input" type="password" name="password" autocomplete="current-password";
}
}
div class="bf-actions" {
button type="submit" class="bf-btn bf-btn-primary bf-text-button" { "Sign in" }
}
}
p class="bf-text-body-sm" { "Factory login is admin / admin. Change it after first sign-in." }
}
}
}
}
}
}
fn tab_title(nav: &VisibleNav, section: &str, tab: &str) -> String {
nav.sections
.iter()
.find(|s| s.slug == section)
.and_then(|s| s.tabs.iter().find(|t| t.slug == tab))
.map(|t| t.title.clone())
.unwrap_or_else(|| tab.to_string())
}
// --- value helpers -----------------------------------------------------------
fn reading(key: &str, label: &str, value: Option<f64>, units: &str, digits: usize) -> Reading {
Reading {
key: key.to_string(),
label: label.to_string(),
value,
units: units.to_string(),
digits,
}
}
fn num(doc: &Value, pointer: &str) -> Option<f64> {
doc.pointer(pointer).and_then(Value::as_f64)
}
fn text(doc: &Value, pointer: &str, fallback: &str) -> String {
doc.pointer(pointer)
.and_then(Value::as_str)
.unwrap_or(fallback)
.to_string()
}
fn active_chain_count(hw: &Value) -> usize {
hw.get("active_chains")
.and_then(Value::as_array)
.map(|a| a.len())
.unwrap_or(0)
}
/// Run/stop badge: a fault stop wins over the operator switch.
fn run_state(hw: &Value, ctl: &Value) -> (Level, String) {
if let Some(reason) = hw.get("stopped").and_then(Value::as_str) {
return (Level::Err, format!("stopped: {reason}"));
}
if ctl.get("running").and_then(Value::as_bool).unwrap_or(false) {
(Level::Ok, "mining".to_string())
} else {
(Level::Warn, "idle (operator stopped)".to_string())
}
}
// --- cards -------------------------------------------------------------------
/// The main dashboard: an editable deck, like wardenOS's dashboard. The layout
/// is a `.wdash`-style document stored on the box (bus `dashboard/*` verbs behind
/// `/api/dashboard`); blocks draw live values from the open miner-state API. In
/// edit mode the operator can add, remove, reorder and save blocks.
fn editable_dashboard() -> Markup {
html! {
(PreEscaped(DECK_CSS))
div class="bf-card" {
div class="akd-bar" {
button id="akd-edit" class="bf-btn bf-text-button" type="button" { "Edit" }
button id="akd-add" class="bf-btn bf-text-button" type="button" hidden { "Add block" }
button id="akd-save" class="bf-btn bf-btn-primary bf-text-button" type="button" hidden { "Save" }
button id="akd-reset" class="bf-btn bf-btn-danger bf-text-button" type="button" hidden { "Reset to template" }
span id="akd-msg" class="bf-text-body-sm" {}
}
div id="akd-grid" class="akd-grid" {}
}
(PreEscaped(DECK_JS))
}
}
const DECK_CSS: &str = "<style>\
.akd-bar{display:flex;gap:8px;align-items:center;margin-bottom:12px;flex-wrap:wrap}\
.akd-grid{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:12px}\
.akd-card{border:1px solid var(--border,#192858);border-radius:8px;padding:12px;background:rgba(255,255,255,.03);min-width:0}\
.akd-card h3{margin:0 0 6px;font-size:13px;font-weight:600;opacity:.8}\
.akd-big{font-size:28px;font-weight:700;line-height:1.1;word-break:break-word}\
.akd-unit{opacity:.7;font-size:13px;margin-left:4px}\
.akd-s1{grid-column:span 1}.akd-s2{grid-column:span 2}.akd-s3{grid-column:span 3}.akd-s4{grid-column:span 4}\
.akd-card table{width:100%;border-collapse:collapse;font-size:12px}.akd-card td,.akd-card th{text-align:left;padding:2px 4px}\
.akd-card.drag{opacity:.5}.akd-rm{float:right;cursor:pointer;opacity:.6}\
.akd-dim{opacity:.5}\
@media(max-width:720px){.akd-grid{grid-template-columns:1fr}.akd-s2,.akd-s3,.akd-s4{grid-column:span 1}}\
</style>";
const DECK_JS: &str = "<script>(function(){\
var DECK='dashboard',doc=null,edit=false,drag=null;\
function $(i){return document.getElementById(i)}\
function esc(s){return String(s).replace(/[&<>\"']/g,function(c){return{'&':'&amp;','<':'&lt;','>':'&gt;','\"':'&quot;',\"'\":'&#39;'}[c]})}\
function msg(t){var e=$('akd-msg');if(e)e.textContent=t}\
var grid=$('akd-grid');\
function render(){grid.innerHTML='';(doc.blocks||[]).forEach(function(b){\
var c=document.createElement('div');c.className='akd-card akd-s'+(b.span||1);c.draggable=edit;\
c.addEventListener('dragstart',function(){drag=b.id;c.classList.add('drag')});\
c.addEventListener('dragend',function(){c.classList.remove('drag')});\
c.addEventListener('dragover',function(e){if(edit)e.preventDefault()});\
c.addEventListener('drop',function(e){e.preventDefault();if(!drag||drag===b.id)return;\
var f=doc.blocks.findIndex(function(x){return x.id===drag}),t=doc.blocks.findIndex(function(x){return x.id===b.id});\
if(f<0||t<0)return;var m=doc.blocks.splice(f,1)[0];doc.blocks.splice(f<t?t-1:t,0,m);render();msg('unsaved changes')});\
var h=document.createElement('h3');h.textContent=b.title||b.id;\
if(edit){var x=document.createElement('span');x.className='akd-rm';x.textContent='x';x.title='remove';\
x.onclick=function(){doc.blocks=doc.blocks.filter(function(y){return y.id!==b.id});render();msg('unsaved changes')};h.appendChild(x)}\
c.appendChild(h);\
if(b.kind==='metric'||b.kind==='status'){var big=document.createElement('div');big.className='akd-big';big.dataset.source=b.source||'';big.textContent='--';\
if(b.unit){var u=document.createElement('span');u.className='akd-unit';u.textContent=b.unit;big.appendChild(u)}c.appendChild(big)}\
else if(b.kind==='table'){var tb=document.createElement('table');tb.dataset[b.source==='fans'?'fans':'table']=b.source||'';tb.innerHTML='<tbody><tr><td class=akd-dim>loading</td></tr></tbody>';c.appendChild(tb)}\
else{var p=document.createElement('div');p.className='akd-dim';p.dataset.kv=b.source||'';p.textContent='loading';c.appendChild(p)}\
grid.appendChild(c)})}\
function fill(){var hw=null,sm=null;function paint(){if(!hw||!sm)return;var s=(sm.SUMMARY||[{}])[0];\
var src={status:s.Status||'unknown',accepted:s.Accepted||0,rejected:s.Rejected||0,elapsed:s.Elapsed||0,\
active_chains:(hw.active_chains||[]).length,frequency:hw.frequency_mhz||0,voltage:(hw.operating_point||{}).voltage_mv||0,target:hw.target||'-'};\
document.querySelectorAll('[data-source]').forEach(function(el){var v=src[el.dataset.source];var u=el.querySelector('.akd-unit');\
el.childNodes[0]&&(el.childNodes[0].nodeValue=(v===undefined||v===null)?'n/a':String(v));if(u)el.appendChild(u)});\
document.querySelectorAll('[data-table]').forEach(function(t){var rows=(hw.chains||[]).map(function(c){return[c.index,c.chip,c.chips_found,c.response_per_mille]});\
t.innerHTML=rows.length?'<thead><tr><th>#</th><th>chip</th><th>chips</th><th>resp</th></tr></thead><tbody>'+rows.map(function(r){return '<tr>'+r.map(function(c){return '<td>'+esc(c)+'</td>'}).join('')+'</tr>'}).join('')+'</tbody>':'<tbody><tr><td class=akd-dim>no chains</td></tr></tbody>'});\
document.querySelectorAll('[data-kv]').forEach(function(el){var rows=[['profile',hw.profile||'-'],['chip',hw.chip||'-'],['psu',hw.psu||'-'],['target',hw.target||'-'],['stopped',hw.stopped?hw.stopped:'no']];\
el.innerHTML=rows.map(function(r){return '<div><span class=akd-dim>'+esc(r[0])+'</span> '+esc(r[1])+'</div>'}).join('')});\
document.querySelectorAll('[data-fans]').forEach(function(t){var rows=(hw.fan_zones||[]).map(function(z){return[z.fan,(z.zones||[]).join(', ')]});\
t.innerHTML=rows.length?'<thead><tr><th>fan</th><th>zones</th></tr></thead><tbody>'+rows.map(function(r){return '<tr><td>'+esc(r[0])+'</td><td>'+esc(r[1])+'</td></tr>'}).join('')+'</tbody>':'<tbody><tr><td class=akd-dim>not mapped</td></tr></tbody>'})}\
fetch('/api/hardware').then(function(r){return r.json()}).then(function(h){hw=h;paint()}).catch(function(){});\
fetch('/api/summary').then(function(r){return r.json()}).then(function(x){sm=x;paint()}).catch(function(){})}\
function setEdit(on){edit=on;['akd-add','akd-save','akd-reset'].forEach(function(i){$(i).hidden=!on});$('akd-edit').textContent=on?'Done':'Edit';render()}\
$('akd-edit').onclick=function(){setEdit(!edit)};\
$('akd-add').onclick=function(){if(doc.blocks.length>=32){msg('32 block limit');return}var n=1;doc.blocks.forEach(function(b){var x=parseInt(String(b.id).replace(/[^0-9]/g,''),10)||0;if(x>=n)n=x+1});doc.blocks.push({id:'block'+n,kind:'metric',span:1,title:'New block',source:'frequency',unit:'MHz'});render();msg('unsaved changes')};\
$('akd-save').onclick=function(){fetch('/api/dashboard?deck='+DECK,{method:'PUT',headers:{'Content-Type':'application/json'},body:JSON.stringify(doc)}).then(function(r){return r.ok?r.json().then(function(d){doc=d;render();msg('saved')}):r.text().then(msg)})};\
$('akd-reset').onclick=function(){fetch('/api/dashboard?deck='+DECK+'&reset=1',{method:'PUT',headers:{'Content-Type':'application/json'},body:'{}'}).then(function(r){return r.json()}).then(function(d){doc=d;render();fill();msg('template restored')})};\
fetch('/api/dashboard?deck='+DECK).then(function(r){return r.json()}).then(function(d){doc=d;render();fill();setInterval(fill,5000)});\
})();</script>";
fn alerts_card(hw: &Value) -> Markup {
let stopped = hw.get("stopped").and_then(Value::as_str);
let run = reading("alert", "Supervisor", None, "", 0);
components::card(
"Alerts",
html! {
@match stopped {
Some(reason) => (readings::status(&run, Level::Err, &format!("machine stopped: {reason}"))),
None => (readings::status(&run, Level::Ok, "no active faults")),
}
(readings::log(&web::recent_log_lines(40)))
},
)
}
fn control_card(hw: &Value, ctl: &Value, csrf: &str) -> Markup {
let (level, state) = run_state(hw, ctl);
let run = reading("run", "State", None, "", 0);
let freq = reading(
"frequency_mhz",
"Chain frequency",
num(hw, "/frequency_mhz"),
"MHz",
0,
);
components::card(
"Control",
html! {
(readings::status(&run, level, &state))
(readings::hero(&freq))
(readings::plate(&[
("Mode".into(), text(ctl, "/mode_label", "-")),
("Target".into(), text(hw, "/target", "-")),
("Active chains".into(), active_chain_count(hw).to_string()),
]))
div class="bf-actions" {
@if let Some(b) = actions::action_button("/control/start", "Start mining", Tone::Primary, csrf, None) { (b) }
@if let Some(b) = actions::action_button("/control/stop", "Stop mining", Tone::Danger, csrf, Some("Stops hashing immediately.")) { (b) }
}
(readings::note("Change the mode and target on Settings -> Tuning. A thermal or chain fault always overrides the operator switch."))
},
)
}
fn hashboards_card(hw: &Value) -> Markup {
let rows: Vec<Vec<String>> = hw
.get("chains")
.and_then(Value::as_array)
.map(|chains| {
chains
.iter()
.map(|c| {
vec![
c.get("index").map(|v| v.to_string()).unwrap_or_default(),
c.get("chip")
.and_then(Value::as_str)
.unwrap_or("-")
.to_string(),
c.get("chips_found")
.map(|v| v.to_string())
.unwrap_or_default(),
c.pointer("/eeprom/state")
.and_then(Value::as_str)
.unwrap_or("-")
.to_string(),
c.get("response_per_mille")
.map(|v| v.to_string())
.unwrap_or_default(),
]
})
.collect()
})
.unwrap_or_default();
components::card(
"Hashboards",
if rows.is_empty() {
readings::note("No chains detected.")
} else {
readings::table(
&["#", "chip", "chips", "eeprom", "response per mille"],
&rows,
)
},
)
}
fn power_card(hw: &Value) -> Markup {
components::card(
"Power supply",
readings::plate(&[
("Supply".into(), text(hw, "/psu", "not identified")),
(
"Voltage range".into(),
format!(
"{} - {} mV",
hw.pointer("/envelope/v_min_mv")
.map(|v| v.to_string())
.unwrap_or_default(),
hw.pointer("/envelope/v_max_mv")
.map(|v| v.to_string())
.unwrap_or_default()
),
),
(
"Frequency range".into(),
format!(
"{} - {} MHz",
hw.pointer("/envelope/f_min_mhz")
.map(|v| v.to_string())
.unwrap_or_default(),
hw.pointer("/envelope/f_max_mhz")
.map(|v| v.to_string())
.unwrap_or_default()
),
),
(
"Operating point".into(),
format!(
"{} mV / {} MHz",
hw.pointer("/operating_point/voltage_mv")
.map(|v| v.to_string())
.unwrap_or_default(),
hw.pointer("/operating_point/frequency_mhz")
.map(|v| v.to_string())
.unwrap_or_default()
),
),
("Target".into(), text(hw, "/target", "-")),
]),
)
}
fn fans_card(hw: &Value) -> Markup {
let rows: Vec<Vec<String>> = hw
.get("fan_zones")
.and_then(Value::as_array)
.map(|zones| {
zones
.iter()
.map(|z| {
vec![
z.get("fan").map(|v| v.to_string()).unwrap_or_default(),
z.get("zones").map(|v| v.to_string()).unwrap_or_default(),
]
})
.collect()
})
.unwrap_or_default();
components::card(
"Fans",
if rows.is_empty() {
readings::note("No fan zones mapped.")
} else {
readings::table(&["fan", "zones it cools"], &rows)
},
)
}
fn plate_from(rows: Vec<(&str, String)>) -> Markup {
let items: Vec<(String, String)> = rows.into_iter().map(|(k, v)| (k.to_string(), v)).collect();
readings::plate(&items)
}
fn system_card() -> Markup {
html! {
(components::card("Identity", plate_from(web::system_rows())))
(components::card("Updates", plate_from(web::update_rows())))
}
}
fn network_card() -> Markup {
components::card("Network", plate_from(web::network_rows()))
}
fn drivers_card(hw: &Value) -> Markup {
components::card("Drivers", plate_from(web::driver_rows(hw)))
}
fn security_card() -> Markup {
components::card("Security", plate_from(web::security_rows()))
}
fn services_card() -> Markup {
components::card(
"Services",
readings::table(&["service", "running"], &web::service_rows()),
)
}
fn monitor_card(hw: &Value) -> Markup {
components::card("Monitor", plate_from(web::monitor_rows(hw)))
}
fn logs_card() -> Markup {
components::card("Logs", readings::log(&web::recent_log_lines(200)))
}
fn files_card() -> Markup {
let doc = web::files_document("/");
let rows: Vec<Vec<String>> = doc
.get("entries")
.and_then(Value::as_array)
.map(|entries| {
entries
.iter()
.map(|e| {
vec![
e.get("name")
.and_then(Value::as_str)
.unwrap_or("-")
.to_string(),
e.get("kind")
.and_then(Value::as_str)
.unwrap_or("-")
.to_string(),
e.get("size").map(|v| v.to_string()).unwrap_or_default(),
]
})
.collect()
})
.unwrap_or_default();
components::card(
"Files",
html! {
(readings::note("Read-only listing of /. Individual text files are at /api/file?path=."))
(readings::table(&["name", "kind", "size"], &rows))
},
)
}
fn pools_card() -> Markup {
components::card(
"Pools",
readings::note("Pool configuration is set at mining start (worker and pool address). Live pool editing from the console is not wired yet."),
)
}
fn terminal_card() -> Markup {
if web::ui_token().is_none() {
return components::card(
"Terminal",
readings::note("Terminal is disabled until a token exists at /var/lib/alkane/ui-token. Create one, then reload."),
);
}
components::card(
"Terminal",
html! {
div class="bf-field" {
label {
span class="bf-field-label bf-text-label" { "Command (runs as root on this miner)" }
input id="cmd" class="bf-input" type="text" placeholder="command";
}
}
div class="bf-actions" {
button id="run" class="bf-btn bf-btn-primary bf-text-button" type="button" { "Run" }
}
pre id="out" class="bf-log" { "ready" }
(PreEscaped(TERMINAL_JS))
},
)
}
const TERMINAL_JS: &str = "<script>(function(){var b=document.getElementById('run');if(!b)return;\
b.onclick=function(){var c=document.getElementById('cmd').value;\
fetch('/api/terminal?cmd='+encodeURIComponent(c),{method:'POST'})\
.then(function(r){return r.text()}).then(function(t){document.getElementById('out').textContent=t})}})();</script>";
/// The tuning control: the schema `tuning` settings in a working form that posts
/// to `/settings` (persist + drive the live runtime), plus the mode legend.
fn tuning_card(
dash: &Dashboard,
ctl: &Value,
csrf: &str,
errors: &BTreeMap<String, String>,
) -> Markup {
let Ok(eff) = dash.schema() else {
return components::card("Tuning", readings::note("Schema did not load."));
};
let view = View {
eff,
rows: dash.rows(),
errors,
surface: Surface::Web,
can_write: true,
};
let banner = errors.get("").cloned();
html! {
@if let Some(message) = banner {
div class="bf-card" {
p class="bf-field-error bf-text-body" role="alert" { "Could not apply: " (message) }
}
}
form class="bf-form" method="post" action="/settings" {
input type="hidden" name="csrf" value=(csrf);
input type="hidden" name="__section" value="settings";
input type="hidden" name="__tab" value="tuning";
(render::card("Tuning target", "tuning", &view))
div class="bf-actions" {
button type="submit" class="bf-btn bf-btn-primary bf-text-button" { "Apply target" }
}
}
(components::card("How it maps", html! {
(readings::plate(&[
("Current mode".into(), text(ctl, "/mode_label", "-")),
("Power target".into(), "hold a DC draw; efficiency follows the power point".into()),
("Ambient temperature target".into(), "hold the hottest sensor a margin above ambient".into()),
("Hashrate ceiling".into(), "seek a hashrate".into()),
("Max fan".into(), "pin the fan and ramp under it".into()),
]))
(readings::note("Apply writes the setting and switches the live target. Start and stop are on Mining -> Overview."))
}))
}
}
+234
View File
@@ -0,0 +1,234 @@
// SPDX-License-Identifier: MIT
//! Operator control intent for the live runtime.
//!
//! The management status in `management.rs` is read-only by design. This is the
//! one small mutable channel the other way: the web UI (and any local client)
//! WRITES a desired mode/target and a run switch here, and the serve-path
//! runtime loop READS it each control period and applies it with
//! [`crate::runtime::MinerRuntime::set_target`]. It owns nothing the fault
//! supervisor owns: a thermal or chain fault still stops the machine regardless
//! of what the operator asked for.
//!
//! A generation counter lets the loop notice a change cheaply without diffing
//! the target every period.
use crate::tuning::TuningTarget;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::Mutex;
/// The operator-visible control modes. Each maps onto exactly one
/// [`TuningTarget`] the runtime already implements, so the UI never claims a
/// behaviour the controller does not have.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ControlMode {
/// Hold a DC power draw; efficiency follows from the power point. The MPC
/// "power target" mode.
Power,
/// Hold the hottest sensor a fixed margin above measured ambient. The MPC
/// "ambient temperature target" mode.
Ambient,
/// Seek a hashrate ceiling.
Hashrate,
/// Pin the fan at a duty and ramp frequency under it.
MaxFan,
}
impl ControlMode {
pub fn as_str(self) -> &'static str {
match self {
ControlMode::Power => "power",
ControlMode::Ambient => "ambient",
ControlMode::Hashrate => "hashrate",
ControlMode::MaxFan => "fan",
}
}
pub fn label(self) -> &'static str {
match self {
ControlMode::Power => "Power target",
ControlMode::Ambient => "Ambient temperature target",
ControlMode::Hashrate => "Hashrate ceiling",
ControlMode::MaxFan => "Max fan",
}
}
pub fn all() -> [ControlMode; 4] {
[
ControlMode::Power,
ControlMode::Ambient,
ControlMode::Hashrate,
ControlMode::MaxFan,
]
}
pub fn of_target(target: TuningTarget) -> ControlMode {
match target {
TuningTarget::PowerW(_) => ControlMode::Power,
TuningTarget::AmbientC { .. } => ControlMode::Ambient,
TuningTarget::HashrateThs(_) => ControlMode::Hashrate,
TuningTarget::MaxFan { .. } => ControlMode::MaxFan,
}
}
}
/// The unit and sensible value for a mode's input box, for the UI form.
pub fn mode_input(mode: ControlMode) -> (&'static str, &'static str) {
match mode {
ControlMode::Power => ("W", "watts of DC draw to hold"),
ControlMode::Ambient => ("C", "degrees above ambient to hold the hottest sensor"),
ControlMode::Hashrate => ("TH/s", "hashrate ceiling"),
ControlMode::MaxFan => ("% PWM", "fan duty to pin (0-100)"),
}
}
/// Build a [`TuningTarget`] from a mode name and its single value. The value is
/// in the mode's natural unit (watts, degrees C, TH/s, percent).
pub fn parse_target(mode: &str, value: f32) -> Result<TuningTarget, String> {
if !value.is_finite() || value < 0.0 {
return Err(format!("value {value} is not a non-negative number"));
}
Ok(match mode {
"power" => TuningTarget::PowerW(value),
"hashrate" => TuningTarget::HashrateThs(value),
"ambient" => TuningTarget::AmbientC {
// UI gives whole degrees C; the controller works in millidegrees.
margin_mc: (value * 1000.0).round() as i32,
},
"fan" => {
if value > 100.0 {
return Err("fan duty must be 0-100".into());
}
TuningTarget::MaxFan {
max_pwm: value.round() as u8,
}
}
other => return Err(format!("unknown mode {other:?}")),
})
}
/// The compact `kind:value` label, matching the management `target` field and
/// `app::target_label`.
pub fn target_label(target: TuningTarget) -> String {
match target {
TuningTarget::PowerW(w) => format!("power:{}", w.round() as i64),
TuningTarget::HashrateThs(t) => format!("hashrate:{}", t.round() as i64),
TuningTarget::AmbientC { margin_mc } => format!("ambient:{margin_mc}"),
TuningTarget::MaxFan { max_pwm } => format!("fan:{max_pwm}"),
}
}
/// Shared operator intent. Cheap to read every control period.
#[derive(Debug)]
pub struct Control {
running: AtomicBool,
generation: AtomicU64,
target: Mutex<TuningTarget>,
}
impl Control {
pub fn new(initial: TuningTarget, running: bool) -> Self {
Self {
running: AtomicBool::new(running),
generation: AtomicU64::new(1),
target: Mutex::new(initial),
}
}
/// Monotonic counter, bumped on every mutation. The loop keeps the last
/// value it applied and only re-applies when this moves.
pub fn generation(&self) -> u64 {
self.generation.load(Ordering::Acquire)
}
pub fn running(&self) -> bool {
self.running.load(Ordering::Acquire)
}
pub fn set_running(&self, running: bool) {
self.running.store(running, Ordering::Release);
self.generation.fetch_add(1, Ordering::AcqRel);
}
pub fn target(&self) -> TuningTarget {
*self.target.lock().expect("control target lock")
}
pub fn set_target(&self, target: TuningTarget) {
*self.target.lock().expect("control target lock") = target;
self.generation.fetch_add(1, Ordering::AcqRel);
}
pub fn set_mode_value(&self, mode: &str, value: f32) -> Result<(), String> {
let target = parse_target(mode, value)?;
self.set_target(target);
Ok(())
}
}
impl Default for Control {
fn default() -> Self {
// Default to a conservative power target, stopped until the operator starts it.
Self::new(TuningTarget::PowerW(2_400.0), false)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn modes_round_trip_through_targets() {
for mode in ControlMode::all() {
let value = match mode {
ControlMode::MaxFan => 80.0,
ControlMode::Ambient => 20.0,
_ => 2_400.0,
};
let target = parse_target(mode.as_str(), value).expect("parse");
assert_eq!(ControlMode::of_target(target), mode);
}
}
#[test]
fn ambient_degrees_become_millidegrees() {
let target = parse_target("ambient", 20.0).expect("parse");
assert_eq!(target, TuningTarget::AmbientC { margin_mc: 20_000 });
}
#[test]
fn fan_duty_is_bounded() {
assert!(parse_target("fan", 120.0).is_err());
assert_eq!(
parse_target("fan", 100.0).expect("parse"),
TuningTarget::MaxFan { max_pwm: 100 }
);
}
#[test]
fn negative_and_unknown_are_rejected() {
assert!(parse_target("power", -1.0).is_err());
assert!(parse_target("bogus", 1.0).is_err());
}
#[test]
fn setting_target_or_running_bumps_the_generation() {
let control = Control::new(TuningTarget::PowerW(2_000.0), false);
let g0 = control.generation();
control.set_target(TuningTarget::HashrateThs(100.0));
let g1 = control.generation();
assert!(g1 > g0);
assert_eq!(control.target(), TuningTarget::HashrateThs(100.0));
control.set_running(true);
assert!(control.generation() > g1);
assert!(control.running());
}
#[test]
fn label_matches_management_shape() {
assert_eq!(target_label(TuningTarget::PowerW(3_000.0)), "power:3000");
assert_eq!(
target_label(TuningTarget::AmbientC { margin_mc: 20_000 }),
"ambient:20000"
);
}
}
+391
View File
@@ -0,0 +1,391 @@
// SPDX-License-Identifier: MIT
//! Schema-driven dashboard for the on-box UI.
//!
//! The sidebar, the tab strip and every settings control come from
//! `schema/alkane-bb.json` through `flare-ui` and `wschema`; this module is the
//! host boundary the crates expect: it owns the stored rows, applies a
//! submitted form only after `wschema` validates it, and keeps the JSON API as
//! the interface of record.
//!
//! Everything here is pure except `load` and `save`, which touch one file.
use std::collections::BTreeMap;
use std::fs;
use std::path::{Path, PathBuf};
use maud::Markup;
use serde_json::{Map, Value};
use flare_ui::assets::PageAssets;
use flare_ui::nav::{self, AllowAll, AppSet, CapSet, NavContext, VisibleNav};
use flare_ui::render::{self, View};
use flare_ui::shell::{self, Active};
use flare_ui::tokens;
use flare_ui::url::Routes;
use wschema::effective::{self, Effective};
use wschema::model::{Document, Surface};
use wschema::validate::{Op, Rows};
/// The schema document is the single source of the UI.
pub const SCHEMA: &str = include_str!("../schema/alkane-bb.json");
/// Capabilities this board reports, which decide what the sidebar shows.
pub fn board_caps() -> CapSet {
CapSet::new(["hashboard", "psu", "fan-map", "cgminer-api"])
}
/// The dashboard: an effective schema plus the stored rows.
pub struct Dashboard {
effective: Result<Effective, String>,
rows: Rows,
path: PathBuf,
}
impl Dashboard {
/// Load the schema and the stored settings, defaulting absent rows to the
/// schema's own defaults.
pub fn load(path: impl AsRef<Path>) -> Dashboard {
let path = path.as_ref().to_path_buf();
let effective = Document::from_json(SCHEMA)
.map_err(|error| error.to_string())
.and_then(|doc| {
effective::merge(&doc, &[]).map_err(|errors| {
errors
.iter()
.map(|error| error.msg.clone())
.collect::<Vec<_>>()
.join("; ")
})
});
let mut rows = Rows::new();
if let Ok(text) = fs::read_to_string(&path) {
if let Ok(Value::Object(map)) = serde_json::from_str::<Value>(&text) {
for (key, value) in map {
rows.insert(key, value);
}
}
}
Dashboard {
effective,
rows,
path,
}
}
pub fn schema(&self) -> Result<&Effective, String> {
self.effective.as_ref().map_err(|error| error.clone())
}
pub fn rows(&self) -> &Rows {
&self.rows
}
/// The visible navigation for this board and viewer.
pub fn nav(&self) -> Result<VisibleNav, String> {
let effective = self.effective.as_ref().map_err(|error| error.clone())?;
let caps = board_caps();
let apps = AppSet::default();
let routes = Routes::console();
let ctx = NavContext {
surface: Surface::Web,
principal: &AllowAll,
caps: &caps,
apps: &apps,
routes: &routes,
};
Ok(nav::visible(&effective.doc.menus, &ctx))
}
/// Stylesheets the shell needs, served from the crate's embedded assets.
pub fn assets() -> PageAssets {
PageAssets {
styles: vec![
"/assets/tokens.css".to_string(),
"/assets/components.css".to_string(),
"/assets/theme.css".to_string(),
],
scripts: Vec::new(),
streams: Vec::new(),
}
}
/// The three stylesheets, for the host to serve.
pub fn stylesheets() -> [(&'static str, &'static str); 3] {
[
("tokens.css", tokens::TOKENS_CSS),
("components.css", tokens::COMPONENTS_CSS),
("theme.css", tokens::THEME_CSS),
]
}
/// Render one page: the shell around the settings card of the tab.
///
/// `section` is the navigation section (`settings`), `tab` the tab slug
/// (`tuning`), and the settings card shows the group named by the tab.
///
/// `errors` carries per-path messages from a rejected submission, so the
/// same render can show what went wrong.
pub fn page(&self, section: &str, tab: &str, errors: &BTreeMap<String, String>) -> Markup {
let effective = match self.effective.as_ref() {
Ok(effective) => effective,
Err(error) => {
return maud::html! {
main class="bf-main" {
p class="bf-field-error bf-text-body" role="alert" { "Schema did not load: " (error) }
}
}
}
};
let nav = self.nav().unwrap_or_default();
let view = View {
eff: effective,
rows: &self.rows,
errors,
surface: Surface::Web,
can_write: true,
};
let title = effective
.doc
.menus
.iter()
.find(|menu| menu.slug == tab && menu.id.starts_with(&format!("{section}/")))
.map(|menu| menu.title.clone())
.unwrap_or_else(|| section.to_string());
let card = render::card(&title, tab, &view);
let body = maud::html! {
section class="bf-card" {
h1 class="bf-text-title" { (title) }
(card)
}
};
shell::page(
"Alkane OS",
&Self::assets(),
&nav,
Active { section, tab },
body,
)
}
/// Apply a submitted form body (`application/x-www-form-urlencoded`).
///
/// Returns the per-path failures when the schema rejects the batch, and
/// persists nothing in that case. Unknown keys are ignored: they are not in
/// the schema, so they cannot be written.
pub fn submit(&mut self, body: &str) -> Result<(), BTreeMap<String, String>> {
let effective = match self.effective.as_ref() {
Ok(effective) => effective,
Err(error) => {
let mut failures = BTreeMap::new();
failures.insert(String::new(), error.clone());
return Err(failures);
}
};
let ops = self.parse_ops(effective, body);
let failures = render::validate_form(
effective,
&ops,
&self.rows,
wschema::validate::Origin::Web,
None,
);
if !failures.is_empty() {
return Err(failures);
}
for op in &ops {
if let Op::Set { path, value } = op {
self.rows.insert(path.clone(), value.clone());
}
}
let map: Map<String, Value> = self
.rows
.iter()
.map(|(key, value)| (key.clone(), value.clone()))
.collect();
let text =
serde_json::to_string_pretty(&Value::Object(map)).unwrap_or_else(|_| "{}".into());
// Persist only after validation passed, atomically (temp + rename), and
// surface a write failure instead of reporting a false success.
let fail = |message: String| -> BTreeMap<String, String> {
let mut failures = BTreeMap::new();
failures.insert(String::new(), message);
failures
};
if let Some(parent) = self.path.parent() {
fs::create_dir_all(parent)
.map_err(|e| fail(format!("cannot create {}: {e}", parent.display())))?;
}
let tmp = self.path.with_extension("json.tmp");
fs::write(&tmp, &text).map_err(|e| fail(format!("cannot write settings: {e}")))?;
fs::rename(&tmp, &self.path).map_err(|e| fail(format!("cannot save settings: {e}")))?;
Ok(())
}
/// Turn a form body into schema ops, coercing each value to its declared kind.
fn parse_ops(&self, effective: &Effective, body: &str) -> Vec<Op> {
let mut ops = Vec::new();
for pair in body.split('&') {
if pair.is_empty() {
continue;
}
let (raw_key, raw_value) = pair.split_once('=').unwrap_or((pair, ""));
let key = crate::form::percent_decode(raw_key);
let raw = crate::form::percent_decode(raw_value);
let setting = match effective.setting(&key) {
Some(setting) => setting,
None => continue,
};
let value = coerce(setting.kind.token(), &raw);
ops.push(Op::Set {
path: setting.path.clone(),
value,
});
}
ops
}
}
fn coerce(kind: &str, raw: &str) -> Value {
match kind {
"int" | "int_set" => raw
.trim()
.parse::<i64>()
.map(Value::from)
.unwrap_or_else(|_| Value::String(raw.to_string())),
"bool" => Value::Bool(matches!(raw, "true" | "on" | "1")),
_ => Value::String(raw.to_string()),
}
}
#[cfg(test)]
mod tests {
use super::*;
fn temp_path(name: &str) -> PathBuf {
let mut path = std::env::temp_dir();
path.push(format!(
"alkane-dashboard-{name}-{}.json",
std::process::id()
));
let _ = fs::remove_file(&path);
path
}
#[test]
fn the_schema_loads_and_yields_the_three_sections() {
let dash = Dashboard::load(temp_path("load"));
let effective = dash.schema().expect("schema loads");
assert_eq!(effective.doc.menus.len(), 20);
let nav = dash.nav().expect("nav builds");
assert_eq!(nav.sections.len(), 3);
assert_eq!(nav.sections[1].slug, "mining");
assert_eq!(nav.sections[1].tabs.len(), 4);
// Settings now carries the full tab set including drivers/services/monitor.
assert_eq!(nav.sections[2].slug, "settings");
assert_eq!(nav.sections[2].tabs.len(), 11);
}
#[test]
fn every_scaffolded_setting_is_in_the_schema() {
let dash = Dashboard::load(temp_path("settings"));
let effective = dash.schema().expect("schema loads");
for path in [
"tuning.mode",
"tuning.power_w",
"tuning.ceiling_mc",
"tuning.pid.kp_milli",
"tuning.pid.deadband_milli",
"fans.zone_count",
"fans.pwm_min",
"detect.chain_ports",
"detect.probe_budget",
"profiles.db",
"system.name",
] {
assert!(
effective.setting(path).is_some(),
"{path} is missing from the schema"
);
}
assert_eq!(effective.doc.settings.len(), 20);
}
#[test]
fn a_page_renders_its_settings_with_inputs() {
let dash = Dashboard::load(temp_path("page"));
let html = dash
.page("settings", "tuning", &BTreeMap::new())
.into_string();
assert!(
html.contains("bf-sidebar"),
"the unified sidebar is missing"
);
assert!(html.contains("bf-tabs"), "the tab strip is missing");
assert!(
html.contains("Tuning target"),
"a settings label is missing"
);
assert!(html.contains("tuning.power_w"), "the field path is missing");
assert!(
html.contains("name=\"tuning.mode\""),
"the mode field is missing"
);
}
#[test]
fn a_valid_submission_is_persisted_and_reloaded() {
let path = temp_path("submit");
let mut dash = Dashboard::load(&path);
dash.submit("tuning.power_w=1500&system.name=s19jpro")
.expect("valid form");
assert_eq!(
dash.rows().get("tuning.power_w"),
Some(&serde_json::json!(1500))
);
let stored = fs::read_to_string(&path).expect("settings file written");
assert!(stored.contains("\"tuning.power_w\": 1500"), "{stored}");
let reloaded = Dashboard::load(&path);
assert_eq!(
reloaded.rows().get("system.name"),
Some(&serde_json::json!("s19jpro"))
);
let _ = fs::remove_file(&path);
}
#[test]
fn an_out_of_range_value_is_rejected_and_nothing_is_written() {
let path = temp_path("reject");
let mut dash = Dashboard::load(&path);
let failures = dash
.submit("tuning.power_w=99999")
.expect_err("must be rejected");
assert!(
failures.keys().any(|key| key.contains("tuning.power_w")),
"{failures:?}"
);
assert!(
!path.exists(),
"a rejected submission must not be persisted"
);
assert_eq!(dash.rows().get("tuning.power_w"), None);
}
#[test]
fn unknown_form_keys_are_ignored() {
let path = temp_path("unknown");
let mut dash = Dashboard::load(&path);
dash.submit("not.a.setting=1&tuning.ceiling_mc=650")
.expect("known key applies");
assert_eq!(dash.rows().get("not.a.setting"), None);
assert_eq!(
dash.rows().get("tuning.ceiling_mc"),
Some(&serde_json::json!(650))
);
let _ = fs::remove_file(&path);
}
#[test]
fn form_values_are_percent_decoded() {
assert_eq!(crate::form::percent_decode("a+b%2Fc"), "a b/c");
}
}
+761
View File
@@ -0,0 +1,761 @@
// SPDX-License-Identifier: MIT
//! Hardware detection model.
//!
//! The detection core decides what is physically attached to a control board and whether that
//! combination is safe to run. It never talks to a chain directly; backends report what they
//! probed, and this module turns that into a `HardwarePlan` the miner can execute.
//!
//! Identification deliberately does not require a hashboard EEPROM. The EEPROM, when present and
//! valid, confirms a board revision; a chain probe alone is enough to select a chip profile.
/// Chip families the detection core can name. `Unknown` is a real answer, not a placeholder.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ChipModel {
Bm1362,
Bm1366,
Bm1368,
Bm1370,
Bm1398,
Unknown,
}
impl ChipModel {
/// Stable wire/API name for this chip family.
pub fn name(self) -> &'static str {
match self {
Self::Bm1362 => "bm1362",
Self::Bm1366 => "bm1366",
Self::Bm1368 => "bm1368",
Self::Bm1370 => "bm1370",
Self::Bm1398 => "bm1398",
Self::Unknown => "unknown",
}
}
}
/// How a chain reports temperature. PIC boards proxy telemetry through the power MCU.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum SensorTopology {
Pic,
NoPic,
Unknown,
}
/// State of a hashboard EEPROM. Absence is normal and must never block detection.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum EepromState {
Present { model: String },
Absent,
Invalid,
}
/// What a backend observed on one physical chain.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ChainReport {
pub index: u8,
pub chip: ChipModel,
pub chips_found: u16,
pub eeprom: EepromState,
/// Nonce responses per mille of dispatched work, when the backend could measure it.
pub response_per_mille: Option<u16>,
}
impl ChainReport {
pub fn is_identified(&self) -> bool {
self.chip != ChipModel::Unknown && self.chips_found > 0
}
}
/// Safe operating envelope for one hashboard/chip profile, from the profile database.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Envelope {
pub v_min_mv: u16,
pub v_max_mv: u16,
pub f_min_mhz: u16,
pub f_max_mhz: u16,
}
impl Envelope {
/// Voltage that pairs with a frequency across this envelope.
///
/// Voltage follows frequency linearly between the profile's floor and ceiling and is clamped
/// outside it. Boards do not run at a fixed voltage across their frequency range, so reporting
/// one voltage while the frequency moves would describe a machine that does not exist.
pub fn voltage_for(self, frequency_mhz: u16) -> u16 {
if frequency_mhz <= self.f_min_mhz {
return self.v_min_mv;
}
if frequency_mhz >= self.f_max_mhz {
return self.v_max_mv;
}
let span_f = u32::from(self.f_max_mhz - self.f_min_mhz);
let span_v = u32::from(self.v_max_mv - self.v_min_mv);
let offset = u32::from(frequency_mhz - self.f_min_mhz);
let voltage = u32::from(self.v_min_mv) + (span_v * offset) / span_f;
voltage.min(u32::from(u16::MAX)) as u16
}
pub fn intersect(self, other: Envelope) -> Option<Envelope> {
let v_min_mv = self.v_min_mv.max(other.v_min_mv);
let v_max_mv = self.v_max_mv.min(other.v_max_mv);
let f_min_mhz = self.f_min_mhz.max(other.f_min_mhz);
let f_max_mhz = self.f_max_mhz.min(other.f_max_mhz);
if v_min_mv > v_max_mv || f_min_mhz > f_max_mhz {
return None;
}
Some(Envelope {
v_min_mv,
v_max_mv,
f_min_mhz,
f_max_mhz,
})
}
}
/// A hashboard profile from the database.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct BoardProfile {
pub name: String,
pub chip: ChipModel,
pub sensor: SensorTopology,
pub chains: u8,
pub envelope: Envelope,
}
/// What the PSU reports about itself and what it can deliver.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PsuCapability {
pub name: String,
pub envelope: Envelope,
pub max_dc_watts: u16,
}
/// Which fans cool which thermal zones, learned by active probing.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct FanZone {
pub fan: u8,
pub zones: Vec<u8>,
}
/// Why detection refused a combination.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum DetectionError {
NoChains,
UnknownChip,
ChipProfileMismatch,
PsuUnidentified,
EnvelopeEmpty,
}
/// Operating point chosen for the machine.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct OperatingPoint {
pub voltage_mv: u16,
pub frequency_mhz: u16,
/// True when the profile was confirmed by an EEPROM or a full chain identification.
pub confirmed: bool,
}
/// The result of detection: everything the miner needs and nothing it has to guess.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct HardwarePlan {
pub profile: String,
pub chip: ChipModel,
pub chains: Vec<ChainReport>,
pub envelope: Envelope,
pub operating_point: OperatingPoint,
pub psu: String,
pub fan_zones: Vec<FanZone>,
}
impl HardwarePlan {
/// Chains that identified but reported no nonces, or fewer than expected chips.
pub fn degraded_chains(&self, expected: u16) -> Vec<u8> {
self.chains
.iter()
.filter(|chain| {
chain.chips_found < expected
|| chain.response_per_mille.is_some_and(|ratio| ratio == 0)
})
.map(|chain| chain.index)
.collect()
}
}
/// Turn observations into a plan, or refuse.
///
/// Refusal is a feature: an unverified or out-of-envelope combination must not mine silently.
pub fn plan(
chains: &[ChainReport],
profile: &BoardProfile,
psu: Option<&PsuCapability>,
fan_zones: Vec<FanZone>,
) -> Result<HardwarePlan, DetectionError> {
if chains.is_empty() {
return Err(DetectionError::NoChains);
}
if chains.iter().all(|chain| chain.chip == ChipModel::Unknown) {
return Err(DetectionError::UnknownChip);
}
if chains
.iter()
.filter(|chain| chain.is_identified())
.any(|chain| chain.chip != profile.chip)
{
return Err(DetectionError::ChipProfileMismatch);
}
let psu = psu.ok_or(DetectionError::PsuUnidentified)?;
let envelope = profile
.envelope
.intersect(psu.envelope)
.ok_or(DetectionError::EnvelopeEmpty)?;
let confirmed = chains
.iter()
.any(|chain| matches!(chain.eeprom, EepromState::Present { .. }))
&& chains.iter().all(ChainReport::is_identified);
let operating_point = if confirmed {
OperatingPoint {
voltage_mv: envelope.v_max_mv.min(profile.envelope.v_max_mv),
frequency_mhz: envelope.f_max_mhz.min(profile.envelope.f_max_mhz),
confirmed: true,
}
} else {
// Unverified hardware runs at the conservative floor of the usable envelope.
OperatingPoint {
voltage_mv: envelope.v_min_mv,
frequency_mhz: envelope.f_min_mhz,
confirmed: false,
}
};
Ok(HardwarePlan {
profile: profile.name.clone(),
chip: profile.chip,
chains: chains.to_vec(),
envelope,
operating_point,
psu: psu.name.clone(),
fan_zones,
})
}
/// Outcome of one chip-identification attempt on a chain.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ProbeOutcome {
/// Chips answered: the model and how many responded.
Identified { chip: ChipModel, chips: u16 },
/// The port is electrically silent (no signal at all).
Silent,
/// Bytes arrived but did not frame as a chip response: wrong baud, noise, or a dead TX.
Garbled,
}
/// Backend contract for identification.
///
/// Framing, baud switching and electrical detail stay in the SDK image for that family; the OS
/// only decides how many attempts to spend and what the results mean.
pub trait DetectionBackend {
type Error;
/// Attempt one identification on `chain`. `attempt` lets the backend cycle its candidate
/// interface/baud set deterministically. A transport failure is an error, never `Silent`.
fn probe(&mut self, chain: u8, attempt: u8) -> Result<ProbeOutcome, Self::Error>;
/// Read the hashboard EEPROM, or report that it is absent or unreadable.
fn eeprom(&mut self, chain: u8) -> Result<EepromState, Self::Error>;
/// Identify the PSU, if this backend can. `None` means "cannot tell", which refuses later.
fn identify_psu(&mut self) -> Result<Option<PsuCapability>, Self::Error>;
}
/// How many identification attempts to spend per chain before declaring it unidentified.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ProbeBudget {
pub attempts: u8,
}
impl Default for ProbeBudget {
fn default() -> Self {
Self { attempts: 4 }
}
}
/// Probe one chain until it identifies or the budget is spent.
///
/// A chain that never identifies is reported as `ChipModel::Unknown` with zero chips rather than
/// being dropped, so the plan can refuse explicitly and the API can show why.
pub fn probe_chain<B: DetectionBackend>(
backend: &mut B,
chain: u8,
budget: ProbeBudget,
) -> Result<ChainReport, B::Error> {
let mut outcome = ProbeOutcome::Silent;
for attempt in 0..budget.attempts.max(1) {
outcome = backend.probe(chain, attempt)?;
if matches!(outcome, ProbeOutcome::Identified { .. }) {
break;
}
}
let (chip, chips_found) = match outcome {
ProbeOutcome::Identified { chip, chips } => (chip, chips),
_ => (ChipModel::Unknown, 0),
};
Ok(ChainReport {
index: chain,
chip,
chips_found,
eeprom: backend.eeprom(chain)?,
response_per_mille: None,
})
}
/// Probe every declared chain port.
pub fn detect_chains<B: DetectionBackend>(
backend: &mut B,
chains: &[u8],
budget: ProbeBudget,
) -> Result<Vec<ChainReport>, B::Error> {
let mut reports = Vec::with_capacity(chains.len());
for &chain in chains {
reports.push(probe_chain(backend, chain, budget)?);
}
Ok(reports)
}
/// Everything the caller knows before probing: which ports exist, how hard to try, and how the
/// hashboards report temperature.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct DetectionRequest<'a> {
pub chain_ports: &'a [u8],
pub budget: ProbeBudget,
pub sensor: SensorTopology,
pub fan_zones: Vec<FanZone>,
}
/// Why a detection run did not produce a plan.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum DetectionFailure<E> {
Backend(E),
Refused(DetectionError),
NoProfile,
}
/// Detect, select a profile, and decide whether the machine may run.
///
/// The profile is selected by chip, sensor wiring and the number of physical chain ports, so a
/// machine with a dead chain still matches its profile and runs degraded instead of being
/// reclassified as a different model.
pub fn run_detection<B: DetectionBackend>(
backend: &mut B,
db: &crate::profiles::ProfileDb,
request: &DetectionRequest<'_>,
) -> Result<HardwarePlan, DetectionFailure<B::Error>> {
let reports = detect_chains(backend, request.chain_ports, request.budget)
.map_err(DetectionFailure::Backend)?;
let chip = reports
.iter()
.find(|report| report.is_identified())
.map(|report| report.chip)
.ok_or(DetectionFailure::Refused(DetectionError::UnknownChip))?;
let chains = u8::try_from(request.chain_ports.len()).unwrap_or(u8::MAX);
let profile = db
.find(chip, chains, request.sensor)
.ok_or(DetectionFailure::NoProfile)?;
let psu = backend.identify_psu().map_err(DetectionFailure::Backend)?;
plan(&reports, profile, psu.as_ref(), request.fan_zones.clone())
.map_err(DetectionFailure::Refused)
}
#[cfg(test)]
mod tests {
use super::*;
fn profile() -> BoardProfile {
BoardProfile {
name: "s19jpro-bm1362".into(),
chip: ChipModel::Bm1362,
sensor: SensorTopology::Pic,
chains: 3,
envelope: Envelope {
v_min_mv: 1100,
v_max_mv: 1500,
f_min_mhz: 300,
f_max_mhz: 700,
},
}
}
fn psu() -> PsuCapability {
PsuCapability {
name: "APW12".into(),
envelope: Envelope {
v_min_mv: 1200,
v_max_mv: 1600,
f_min_mhz: 0,
f_max_mhz: 1000,
},
max_dc_watts: 3600,
}
}
fn chain(index: u8, eeprom: EepromState) -> ChainReport {
ChainReport {
index,
chip: ChipModel::Bm1362,
chips_found: 126,
eeprom,
response_per_mille: Some(980),
}
}
#[test]
fn confirmed_plan_uses_verified_ceiling() {
let chains = [chain(
0,
EepromState::Present {
model: "BHB42601".into(),
},
)];
let plan = plan(&chains, &profile(), Some(&psu()), Vec::new()).expect("plan");
assert!(plan.operating_point.confirmed);
assert_eq!(plan.operating_point.voltage_mv, 1500);
assert_eq!(plan.operating_point.frequency_mhz, 700);
assert_eq!(plan.envelope.v_min_mv, 1200);
}
#[test]
fn absent_eeprom_still_yields_a_conservative_plan() {
let chains = [chain(0, EepromState::Absent)];
let plan = plan(&chains, &profile(), Some(&psu()), Vec::new()).expect("plan");
assert!(!plan.operating_point.confirmed);
assert_eq!(plan.operating_point.voltage_mv, plan.envelope.v_min_mv);
assert_eq!(plan.operating_point.frequency_mhz, plan.envelope.f_min_mhz);
}
#[test]
fn unknown_chip_refuses() {
let mut chains = [chain(0, EepromState::Absent)];
chains[0].chip = ChipModel::Unknown;
assert_eq!(
plan(&chains, &profile(), Some(&psu()), Vec::new()),
Err(DetectionError::UnknownChip)
);
}
#[test]
fn wrong_chip_refuses() {
let mut chains = [chain(0, EepromState::Absent)];
chains[0].chip = ChipModel::Bm1366;
assert_eq!(
plan(&chains, &profile(), Some(&psu()), Vec::new()),
Err(DetectionError::ChipProfileMismatch)
);
}
#[test]
fn missing_psu_refuses() {
let chains = [chain(0, EepromState::Absent)];
assert_eq!(
plan(&chains, &profile(), None, Vec::new()),
Err(DetectionError::PsuUnidentified)
);
}
#[test]
fn incompatible_psu_refuses() {
let chains = [chain(0, EepromState::Absent)];
let weak = PsuCapability {
name: "APW3".into(),
envelope: Envelope {
v_min_mv: 700,
v_max_mv: 1090,
f_min_mhz: 0,
f_max_mhz: 1000,
},
max_dc_watts: 1600,
};
assert_eq!(
plan(&chains, &profile(), Some(&weak), Vec::new()),
Err(DetectionError::EnvelopeEmpty)
);
}
#[test]
fn empty_chain_set_refuses() {
assert_eq!(
plan(&[], &profile(), Some(&psu()), Vec::new()),
Err(DetectionError::NoChains)
);
}
#[test]
fn degraded_chains_are_reported_not_fatal() {
let mut silent = chain(1, EepromState::Absent);
silent.response_per_mille = Some(0);
let chains = [chain(0, EepromState::Absent), silent];
let plan = plan(&chains, &profile(), Some(&psu()), Vec::new()).expect("plan");
assert_eq!(plan.degraded_chains(126), vec![1]);
}
#[test]
fn fan_zones_are_carried_into_the_plan() {
let chains = [chain(0, EepromState::Absent)];
let zones = vec![FanZone {
fan: 0,
zones: vec![0, 1],
}];
let plan = plan(&chains, &profile(), Some(&psu()), zones.clone()).expect("plan");
assert_eq!(plan.fan_zones, zones);
}
struct ScriptedProbe {
plan: std::collections::VecDeque<ProbeOutcome>,
eeprom: EepromState,
calls: usize,
fail_at: u8,
psu: Option<PsuCapability>,
}
impl ScriptedProbe {
fn new(plan: &[ProbeOutcome], eeprom: EepromState) -> Self {
Self {
plan: plan.iter().copied().collect(),
eeprom,
calls: 0,
fail_at: u8::MAX,
psu: Some(psu()),
}
}
}
impl DetectionBackend for ScriptedProbe {
type Error = ();
fn probe(&mut self, _chain: u8, attempt: u8) -> Result<ProbeOutcome, ()> {
self.calls += 1;
if attempt == self.fail_at {
return Err(());
}
Ok(self.plan.pop_front().unwrap_or(ProbeOutcome::Silent))
}
fn eeprom(&mut self, _chain: u8) -> Result<EepromState, ()> {
Ok(self.eeprom.clone())
}
fn identify_psu(&mut self) -> Result<Option<PsuCapability>, ()> {
Ok(self.psu.clone())
}
}
#[test]
fn probe_retries_until_the_chain_identifies() {
let mut backend = ScriptedProbe::new(
&[
ProbeOutcome::Silent,
ProbeOutcome::Garbled,
ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
],
EepromState::Absent,
);
let report = probe_chain(&mut backend, 0, ProbeBudget { attempts: 4 }).expect("probe");
assert_eq!(backend.calls, 3);
assert_eq!(report.chip, ChipModel::Bm1362);
assert_eq!(report.chips_found, 126);
assert!(report.is_identified());
}
#[test]
fn probe_exhaustion_is_reported_not_hidden() {
let mut backend = ScriptedProbe::new(&[ProbeOutcome::Silent; 4], EepromState::Absent);
let report = probe_chain(&mut backend, 1, ProbeBudget { attempts: 4 }).expect("probe");
assert_eq!(backend.calls, 4);
assert_eq!(report.chip, ChipModel::Unknown);
assert_eq!(report.chips_found, 0);
assert!(!report.is_identified());
}
#[test]
fn probe_keeps_the_eeprom_state_even_when_unidentified() {
let mut backend = ScriptedProbe::new(
&[ProbeOutcome::Garbled; 2],
EepromState::Present {
model: "BHB42601".into(),
},
);
let report = probe_chain(&mut backend, 2, ProbeBudget { attempts: 2 }).expect("probe");
assert_eq!(report.chip, ChipModel::Unknown);
assert_eq!(
report.eeprom,
EepromState::Present {
model: "BHB42601".into()
}
);
}
#[test]
fn detection_covers_every_declared_chain_port() {
let mut backend = ScriptedProbe::new(
&[
ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
],
EepromState::Absent,
);
let reports =
detect_chains(&mut backend, &[0, 1, 2], ProbeBudget::default()).expect("detect");
assert_eq!(reports.len(), 3);
assert_eq!(
reports.iter().map(|r| r.index).collect::<Vec<_>>(),
vec![0, 1, 2]
);
assert!(reports.iter().all(ChainReport::is_identified));
}
#[test]
fn transport_failure_is_not_reported_as_a_silent_port() {
let mut backend = ScriptedProbe::new(&[ProbeOutcome::Silent; 4], EepromState::Absent);
backend.fail_at = 1;
assert_eq!(
probe_chain(&mut backend, 0, ProbeBudget::default()),
Err(())
);
assert_eq!(backend.calls, 2);
}
#[test]
fn unidentified_chain_makes_the_plan_refuse() {
let mut backend = ScriptedProbe::new(&[ProbeOutcome::Silent; 4], EepromState::Absent);
let reports = detect_chains(&mut backend, &[0], ProbeBudget::default()).expect("detect");
assert_eq!(
plan(&reports, &profile(), Some(&psu()), Vec::new()),
Err(DetectionError::UnknownChip)
);
}
fn db() -> crate::profiles::ProfileDb {
crate::profiles::ProfileDb::new(vec![profile()]).expect("db")
}
#[test]
fn run_detection_emits_a_plan_end_to_end() {
let mut backend = ScriptedProbe::new(
&[
ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
],
EepromState::Absent,
);
let request = DetectionRequest {
chain_ports: &[0, 1, 2],
budget: ProbeBudget::default(),
sensor: SensorTopology::Pic,
fan_zones: vec![FanZone {
fan: 0,
zones: vec![0],
}],
};
let plan = run_detection(&mut backend, &db(), &request).expect("plan");
assert_eq!(plan.chains.len(), 3);
assert_eq!(plan.psu, "APW12");
assert!(!plan.operating_point.confirmed);
assert_eq!(plan.operating_point.voltage_mv, 1200);
}
#[test]
fn run_detection_refuses_when_no_profile_matches() {
let mut backend = ScriptedProbe::new(
&[ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
}],
EepromState::Absent,
);
let request = DetectionRequest {
chain_ports: &[0],
budget: ProbeBudget::default(),
sensor: SensorTopology::Pic,
fan_zones: Vec::new(),
};
assert_eq!(
run_detection(&mut backend, &db(), &request),
Err(DetectionFailure::NoProfile)
);
}
#[test]
fn run_detection_runs_degraded_with_a_dead_chain() {
let mut backend = ScriptedProbe::new(
&[
ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
ProbeOutcome::Identified {
chip: ChipModel::Bm1362,
chips: 126,
},
ProbeOutcome::Silent,
ProbeOutcome::Silent,
ProbeOutcome::Silent,
ProbeOutcome::Silent,
],
EepromState::Absent,
);
let request = DetectionRequest {
chain_ports: &[0, 1, 2],
budget: ProbeBudget::default(),
sensor: SensorTopology::Pic,
fan_zones: Vec::new(),
};
let plan = run_detection(&mut backend, &db(), &request).expect("plan");
assert_eq!(plan.degraded_chains(126), vec![2]);
}
#[test]
fn voltage_follows_frequency_and_clamps_outside_the_envelope() {
let envelope = Envelope {
v_min_mv: 1100,
v_max_mv: 1500,
f_min_mhz: 300,
f_max_mhz: 700,
};
assert_eq!(envelope.voltage_for(200), 1100);
assert_eq!(envelope.voltage_for(300), 1100);
assert_eq!(envelope.voltage_for(500), 1300);
assert_eq!(envelope.voltage_for(700), 1500);
assert_eq!(envelope.voltage_for(900), 1500);
}
#[test]
fn a_single_frequency_envelope_reports_its_floor() {
let envelope = Envelope {
v_min_mv: 1200,
v_max_mv: 1400,
f_min_mhz: 500,
f_max_mhz: 500,
};
assert_eq!(envelope.voltage_for(500), 1200);
assert_eq!(envelope.voltage_for(600), 1400);
}
}
+469
View File
@@ -0,0 +1,469 @@
// SPDX-License-Identifier: MIT
//! Active fan-to-thermal-zone mapping.
//!
//! Antminer chassis wire fans to zones in a way that is not reported by the hardware: a fan may
//! cool one hashboard heavily and another barely, and the front/back, top/bottom labels are
//! physical. The mapping is learned by stepping one fan at a time and watching which zone's
//! temperature responds, which is why this module takes measurements rather than configuration.
use crate::detect::FanZone;
/// One sensor reading taken while a fan was held at a given duty.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ZoneReading {
pub zone: u8,
pub temp_mc: i32,
}
/// One measurement step: a fan duty and the temperatures observed during it.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ProbeSample {
pub fan: u8,
pub pwm: u8,
pub readings: Vec<ZoneReading>,
}
/// Thresholds that decide when a response is real.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct MapThresholds {
/// Minimum cooling (millidegrees) between the low and high duty to count as a response.
pub min_drop_mc: i32,
/// Minimum margin over the next-best fan, in parts per thousand of the best response.
pub min_margin_per_mille: u16,
}
impl Default for MapThresholds {
fn default() -> Self {
Self {
min_drop_mc: 500,
min_margin_per_mille: 250,
}
}
}
/// The learned mapping.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct FanMap {
pub assignments: Vec<FanZone>,
/// Zones whose response was ambiguous and were therefore left unassigned.
pub unresolved: Vec<u8>,
/// Per assigned zone, the margin over the runner-up in parts per thousand.
pub confidence_per_mille: Vec<u16>,
}
impl FanMap {
/// Zones a fan was confidently assigned to.
pub fn zones_for(&self, fan: u8) -> Vec<u8> {
self.assignments
.iter()
.find(|assignment| assignment.fan == fan)
.map(|assignment| assignment.zones.clone())
.unwrap_or_default()
}
}
/// Response per (fan, zone): positive means the zone cooled when that fan sped up.
fn responses(samples: &[ProbeSample], zones: &[u8]) -> Vec<(u8, Vec<(u8, i32)>)> {
let mut fans: Vec<u8> = samples.iter().map(|sample| sample.fan).collect();
fans.sort_unstable();
fans.dedup();
let mut out = Vec::new();
for fan in fans {
let fan_samples: Vec<&ProbeSample> =
samples.iter().filter(|sample| sample.fan == fan).collect();
let min_pwm = fan_samples.iter().map(|sample| sample.pwm).min();
let max_pwm = fan_samples.iter().map(|sample| sample.pwm).max();
let (Some(low), Some(high)) = (min_pwm, max_pwm) else {
continue;
};
if low == high {
continue;
}
let mut per_zone = Vec::with_capacity(zones.len());
for &zone in zones {
let mean_at = |pwm: u8| -> Option<i32> {
let values: Vec<i32> = fan_samples
.iter()
.filter(|sample| sample.pwm == pwm)
.flat_map(|sample| {
sample
.readings
.iter()
.filter(|reading| reading.zone == zone)
.map(|reading| reading.temp_mc)
})
.collect();
if values.is_empty() {
return None;
}
let sum: i64 = values.iter().map(|value| *value as i64).sum();
Some((sum / values.len() as i64) as i32)
};
// Duty goes up, temperature should come down: response = warm-run minus fast-run.
if let (Some(slow_temp), Some(fast_temp)) = (mean_at(low), mean_at(high)) {
per_zone.push((zone, slow_temp - fast_temp));
}
}
out.push((fan, per_zone));
}
out
}
/// Learn which fans cool which zones from a stepped measurement run.
///
/// Every zone goes to the fan with the strongest cooling response, provided that response clears
/// `min_drop_mc` and beats the runner-up by `min_margin_per_mille`. Anything weaker stays
/// unresolved instead of being guessed, so a noisy run cannot invent a fan map.
pub fn map_fans(samples: &[ProbeSample], zones: &[u8], thresholds: MapThresholds) -> FanMap {
let responses = responses(samples, zones);
let mut map = FanMap::default();
for &zone in zones {
let mut ranked: Vec<(i32, u8)> = responses
.iter()
.filter_map(|(fan, per_zone)| {
per_zone
.iter()
.find(|(candidate, _)| *candidate == zone)
.map(|(_, drop)| (*drop, *fan))
})
.collect();
ranked.sort_unstable_by_key(|entry| std::cmp::Reverse(entry.0));
let Some(&(best_drop, best_fan)) = ranked.first() else {
map.unresolved.push(zone);
continue;
};
let runner_up = ranked.get(1).map(|(drop, _)| *drop).unwrap_or(0);
let margin = best_drop - runner_up.max(0);
let margin_per_mille = if best_drop > 0 {
((margin as i64 * 1000) / best_drop as i64) as u16
} else {
0
};
if best_drop < thresholds.min_drop_mc || margin_per_mille < thresholds.min_margin_per_mille
{
map.unresolved.push(zone);
continue;
}
match map
.assignments
.iter_mut()
.find(|assignment| assignment.fan == best_fan)
{
Some(assignment) => assignment.zones.push(zone),
None => map.assignments.push(FanZone {
fan: best_fan,
zones: vec![zone],
}),
}
map.confidence_per_mille.push(margin_per_mille);
}
map
}
/// Safe limits for a fan-mapping sweep.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct SweepConfig {
pub fans: u8,
pub zones: u8,
/// Lowest duty used during probing. Never zero: the boards must keep airflow.
pub low_pwm: u8,
pub high_pwm: u8,
/// Readings taken per (fan, duty) step; the mapper averages them.
pub repeats: u8,
/// Time to wait after a duty change before reading temperatures.
pub settle_ms: u32,
}
impl Default for SweepConfig {
fn default() -> Self {
Self {
fans: 4,
zones: 3,
low_pwm: 40,
high_pwm: 100,
repeats: 2,
settle_ms: 20_000,
}
}
}
/// Minimum duty a sweep may use. Airflow is never removed to make a measurement.
pub const MIN_PROBE_PWM: u8 = 20;
/// Why a sweep did not run.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum SweepError<E> {
Backend(E),
InvalidConfig(&'static str),
}
/// The two backend actions a sweep needs.
pub trait FanProbe {
type Error;
fn set_fan(&mut self, fan: u8, pwm: u8) -> Result<(), Self::Error>;
fn read_zone(&mut self, zone: u8) -> Result<i32, Self::Error>;
}
/// Step every fan between the low and high duty and record what the zones do.
///
/// One fan is moved at a time while the others hold their previous duty, so the response belongs
/// to that fan. The run ends with every fan back at `high_pwm`: leaving a fan low after probing
/// would be a thermal hazard for whatever runs next.
pub fn sweep<B: FanProbe, S: FnMut(u32)>(
backend: &mut B,
config: &SweepConfig,
mut settle: S,
) -> Result<Vec<ProbeSample>, SweepError<B::Error>> {
if config.fans == 0 {
return Err(SweepError::InvalidConfig("no fans to sweep"));
}
if config.zones == 0 {
return Err(SweepError::InvalidConfig("no zones to read"));
}
if config.low_pwm < MIN_PROBE_PWM {
return Err(SweepError::InvalidConfig(
"probe duty below the safe minimum",
));
}
if config.high_pwm > 100 {
return Err(SweepError::InvalidConfig("probe duty above 100 percent"));
}
if config.low_pwm >= config.high_pwm {
return Err(SweepError::InvalidConfig("probe duty range is empty"));
}
if config.repeats == 0 {
return Err(SweepError::InvalidConfig("no readings requested"));
}
let mut samples = Vec::new();
for fan in 0..config.fans {
for pwm in [config.low_pwm, config.high_pwm] {
backend.set_fan(fan, pwm).map_err(SweepError::Backend)?;
settle(config.settle_ms);
for _ in 0..config.repeats {
let mut readings = Vec::with_capacity(config.zones as usize);
for zone in 0..config.zones {
readings.push(ZoneReading {
zone,
temp_mc: backend.read_zone(zone).map_err(SweepError::Backend)?,
});
}
samples.push(ProbeSample { fan, pwm, readings });
}
}
}
for fan in 0..config.fans {
backend
.set_fan(fan, config.high_pwm)
.map_err(SweepError::Backend)?;
}
Ok(samples)
}
#[cfg(test)]
mod tests {
use super::*;
fn sample(fan: u8, pwm: u8, zone_temps: &[(u8, i32)]) -> ProbeSample {
ProbeSample {
fan,
pwm,
readings: zone_temps
.iter()
.map(|(zone, temp)| ZoneReading {
zone: *zone,
temp_mc: *temp,
})
.collect(),
}
}
#[test]
fn each_zone_is_assigned_to_the_fan_that_cools_it() {
let samples = vec![
sample(0, 30, &[(0, 70_000), (1, 60_000)]),
sample(0, 100, &[(0, 50_000), (1, 59_000)]),
sample(1, 30, &[(0, 69_000), (1, 60_000)]),
sample(1, 100, &[(0, 68_000), (1, 40_000)]),
];
let map = map_fans(&samples, &[0, 1], MapThresholds::default());
assert_eq!(map.zones_for(0), vec![0]);
assert_eq!(map.zones_for(1), vec![1]);
assert!(map.unresolved.is_empty());
}
#[test]
fn ambiguity_leaves_a_zone_unresolved() {
let samples = vec![
sample(0, 30, &[(0, 70_000)]),
sample(0, 100, &[(0, 60_000)]),
sample(1, 30, &[(0, 70_500)]),
sample(1, 100, &[(0, 60_500)]),
];
let map = map_fans(&samples, &[0], MapThresholds::default());
assert!(map.assignments.is_empty());
assert_eq!(map.unresolved, vec![0]);
}
#[test]
fn a_fan_that_does_not_change_temperature_is_not_assigned() {
let samples = vec![
sample(0, 30, &[(0, 60_000)]),
sample(0, 100, &[(0, 59_900)]),
];
let map = map_fans(&samples, &[0], MapThresholds::default());
assert!(map.assignments.is_empty());
assert_eq!(map.unresolved, vec![0]);
}
#[test]
fn a_fan_without_duty_range_is_skipped() {
let samples = vec![sample(0, 50, &[(0, 60_000)]), sample(0, 50, &[(0, 60_000)])];
let map = map_fans(&samples, &[0], MapThresholds::default());
assert!(map.assignments.is_empty());
assert_eq!(map.unresolved, vec![0]);
}
#[test]
fn one_fan_can_own_several_zones() {
let samples = vec![
sample(0, 30, &[(0, 70_000), (1, 71_000), (2, 55_000)]),
sample(0, 100, &[(0, 55_000), (1, 56_000), (2, 54_000)]),
sample(1, 30, &[(0, 70_000), (1, 71_000), (2, 54_000)]),
sample(1, 100, &[(0, 69_000), (1, 70_000), (2, 50_000)]),
];
let map = map_fans(&samples, &[0, 1, 2], MapThresholds::default());
assert_eq!(map.zones_for(0), vec![0, 1]);
assert_eq!(map.zones_for(1), vec![2]);
}
struct ThermalMock {
duty: Vec<u8>,
owners: Vec<(u8, u8)>,
fail: bool,
}
impl ThermalMock {
fn new(owners: &[(u8, u8)]) -> Self {
let fans = owners.iter().map(|(fan, _)| *fan).max().unwrap_or(0) + 1;
Self {
duty: vec![100; fans as usize],
owners: owners.to_vec(),
fail: false,
}
}
}
impl FanProbe for ThermalMock {
type Error = &'static str;
fn set_fan(&mut self, fan: u8, pwm: u8) -> Result<(), Self::Error> {
if self.fail {
return Err("fan bus down");
}
self.duty[fan as usize] = pwm;
Ok(())
}
fn read_zone(&mut self, zone: u8) -> Result<i32, Self::Error> {
if self.fail {
return Err("sensor bus down");
}
let owner = self
.owners
.iter()
.find(|(_, candidate)| *candidate == zone)
.map(|(fan, _)| *fan)
.expect("zone has an owner");
let cooled = self.duty[owner as usize] >= 100;
Ok(if cooled { 50_000 } else { 70_000 })
}
}
#[test]
fn sweep_then_map_resolves_each_zone() {
let mut backend = ThermalMock::new(&[(0, 0), (1, 1)]);
let config = SweepConfig {
fans: 2,
zones: 2,
low_pwm: 40,
high_pwm: 100,
repeats: 2,
settle_ms: 0,
};
let samples = sweep(&mut backend, &config, |_| {}).expect("sweep");
assert_eq!(samples.len(), 2 * 2 * 2);
let map = map_fans(&samples, &[0, 1], MapThresholds::default());
assert_eq!(map.zones_for(0), vec![0]);
assert_eq!(map.zones_for(1), vec![1]);
assert!(map.unresolved.is_empty());
}
#[test]
fn sweep_restores_every_fan_to_high_duty() {
let mut backend = ThermalMock::new(&[(0, 0), (1, 1)]);
let config = SweepConfig {
fans: 2,
zones: 2,
low_pwm: 40,
high_pwm: 100,
repeats: 1,
settle_ms: 0,
};
sweep(&mut backend, &config, |_| {}).expect("sweep");
assert_eq!(backend.duty, vec![100, 100]);
}
#[test]
fn sweep_refuses_an_unsafe_duty() {
let mut backend = ThermalMock::new(&[(0, 0)]);
let config = SweepConfig {
fans: 1,
zones: 1,
low_pwm: 10,
high_pwm: 100,
repeats: 1,
settle_ms: 0,
};
assert_eq!(
sweep(&mut backend, &config, |_| {}),
Err(SweepError::InvalidConfig(
"probe duty below the safe minimum"
))
);
}
#[test]
fn sweep_refuses_an_empty_range_and_zero_reads() {
let mut backend = ThermalMock::new(&[(0, 0)]);
let flat = SweepConfig {
fans: 1,
zones: 1,
low_pwm: 60,
high_pwm: 60,
repeats: 1,
settle_ms: 0,
};
assert!(matches!(
sweep(&mut backend, &flat, |_| {}),
Err(SweepError::InvalidConfig(_))
));
let no_reads = SweepConfig { repeats: 0, ..flat };
assert!(matches!(
sweep(&mut backend, &no_reads, |_| {}),
Err(SweepError::InvalidConfig(_))
));
}
#[test]
fn sweep_propagates_backend_failures() {
let mut backend = ThermalMock::new(&[(0, 0)]);
backend.fail = true;
let config = SweepConfig::default();
assert_eq!(
sweep(&mut backend, &config, |_| {}),
Err(SweepError::Backend("fan bus down"))
);
}
}
+318
View File
@@ -0,0 +1,318 @@
// SPDX-License-Identifier: MIT
//! Persisting the learned fan map.
//!
//! Mapping fans means heating and cooling the machine deliberately, so it is done once, stored, and
//! reused until the fan or sensor set changes. A stored map that does not match the current set is
//! ignored rather than trusted: silently applying a map learned on four fans to a machine with two
//! would mis-control thermals.
use crate::detect::FanZone;
use crate::fanmap::{map_fans, sweep, FanMap, FanProbe, MapThresholds, SweepConfig, SweepError};
use serde_json::{json, Value};
use std::fs;
use std::io;
use std::path::Path;
/// A stored map together with the hardware it was learned on.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct StoredMap {
pub fans: u8,
pub zones: u8,
pub assignments: Vec<FanZone>,
pub unresolved: Vec<u8>,
}
impl StoredMap {
pub fn from_map(map: &FanMap, fans: u8, zones: u8) -> Self {
Self {
fans,
zones,
assignments: map.assignments.clone(),
unresolved: map.unresolved.clone(),
}
}
pub fn to_map(&self) -> FanMap {
FanMap {
assignments: self.assignments.clone(),
unresolved: self.unresolved.clone(),
confidence_per_mille: vec![0; self.assignments.len()],
}
}
/// True when this map was learned on the same fan and zone counts.
pub fn matches(&self, fans: u8, zones: u8) -> bool {
self.fans == fans && self.zones == zones
}
pub fn to_json(&self) -> String {
json!({
"schema": 1,
"fans": self.fans,
"zones": self.zones,
"assignments": self.assignments.iter().map(|zone| json!({
"fan": zone.fan,
"zones": zone.zones,
})).collect::<Vec<_>>(),
"unresolved": self.unresolved,
})
.to_string()
}
pub fn from_json(text: &str) -> Option<Self> {
let root: Value = serde_json::from_str(text).ok()?;
if root.get("schema")?.as_u64()? != 1 {
return None;
}
let fans = u8::try_from(root.get("fans")?.as_u64()?).ok()?;
let zones = u8::try_from(root.get("zones")?.as_u64()?).ok()?;
let assignments = root
.get("assignments")?
.as_array()?
.iter()
.map(|entry| {
Some(FanZone {
fan: u8::try_from(entry.get("fan")?.as_u64()?).ok()?,
zones: entry
.get("zones")?
.as_array()?
.iter()
.map(|zone| u8::try_from(zone.as_u64()?).ok())
.collect::<Option<Vec<u8>>>()?,
})
})
.collect::<Option<Vec<FanZone>>>()?;
let unresolved = root
.get("unresolved")?
.as_array()?
.iter()
.map(|zone| u8::try_from(zone.as_u64()?).ok())
.collect::<Option<Vec<u8>>>()?;
Some(Self {
fans,
zones,
assignments,
unresolved,
})
}
}
/// Why mapping did not produce a stored map.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum StoreError<E> {
Sweep(SweepError<E>),
Io(&'static str),
}
/// Read a stored map, if one exists and parses.
pub fn load(path: &Path) -> Option<StoredMap> {
let text = fs::read_to_string(path).ok()?;
StoredMap::from_json(&text)
}
/// Write a map, creating the parent directory when needed.
pub fn save(path: &Path, stored: &StoredMap) -> io::Result<()> {
if let Some(parent) = path.parent() {
if !parent.as_os_str().is_empty() {
fs::create_dir_all(parent)?;
}
}
fs::write(path, stored.to_json())
}
/// Return the stored map when it matches this machine, otherwise sweep, map, and store the result.
pub fn ensure_map<B: FanProbe, S: FnMut(u32)>(
backend: &mut B,
config: &SweepConfig,
thresholds: MapThresholds,
path: &Path,
settle: S,
) -> Result<FanMap, StoreError<B::Error>> {
if let Some(stored) = load(path) {
if stored.matches(config.fans, config.zones) {
return Ok(stored.to_map());
}
}
let zones: Vec<u8> = (0..config.zones).collect();
let samples = sweep(backend, config, settle).map_err(StoreError::Sweep)?;
let map = map_fans(&samples, &zones, thresholds);
let stored = StoredMap::from_map(&map, config.fans, config.zones);
save(path, &stored).map_err(|_| StoreError::Io("cannot write the fan map"))?;
Ok(map)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::fanmap::{ProbeSample, ZoneReading};
struct CountingBackend {
duty: Vec<u8>,
owners: Vec<(u8, u8)>,
calls: usize,
}
impl FanProbe for CountingBackend {
type Error = ();
fn set_fan(&mut self, fan: u8, pwm: u8) -> Result<(), ()> {
self.calls += 1;
self.duty[fan as usize] = pwm;
Ok(())
}
fn read_zone(&mut self, zone: u8) -> Result<i32, ()> {
// Zones without an explicit owner follow fan 0, which keeps the mock usable when a
// test asks for more zones than the fixture declares.
let owner = self
.owners
.iter()
.find(|(_, candidate)| *candidate == zone)
.map(|(fan, _)| *fan)
.unwrap_or(0);
Ok(if self.duty[owner as usize] >= 100 {
50_000
} else {
70_000
})
}
}
fn backend() -> CountingBackend {
CountingBackend {
duty: vec![100, 100],
owners: vec![(0, 0), (1, 1)],
calls: 0,
}
}
fn config(zones: u8) -> SweepConfig {
SweepConfig {
fans: 2,
zones,
low_pwm: 40,
high_pwm: 100,
repeats: 1,
settle_ms: 0,
}
}
fn path(name: &str) -> std::path::PathBuf {
let mut dir = std::env::temp_dir();
dir.push(format!("alkane-fanmap-{}-{name}.json", std::process::id()));
dir
}
#[test]
fn a_stored_map_round_trips() {
let map = FanMap {
assignments: vec![FanZone {
fan: 0,
zones: vec![0, 1],
}],
unresolved: vec![2],
confidence_per_mille: vec![900],
};
let stored = StoredMap::from_map(&map, 4, 3);
let text = stored.to_json();
assert_eq!(StoredMap::from_json(&text).expect("parse"), stored);
let back = stored.to_map();
assert_eq!(back.assignments, map.assignments);
assert_eq!(back.unresolved, map.unresolved);
}
#[test]
fn corrupt_or_foreign_json_is_ignored() {
assert!(StoredMap::from_json("not json").is_none());
assert!(StoredMap::from_json(r#"{"schema":2}"#).is_none());
assert!(StoredMap::from_json(r#"{"schema":1,"fans":2}"#).is_none());
}
#[test]
fn a_matching_map_is_reused_without_sweeping() {
let file = path("reuse");
let first = ensure_map(
&mut backend(),
&config(2),
MapThresholds::default(),
&file,
|_| {},
)
.expect("first");
assert_eq!(first.zones_for(0), vec![0]);
let mut reuse = backend();
let second = ensure_map(
&mut reuse,
&config(2),
MapThresholds::default(),
&file,
|_| {},
)
.expect("second");
assert_eq!(second.zones_for(0), vec![0]);
assert_eq!(reuse.calls, 0, "a stored map must not cause another sweep");
let _ = std::fs::remove_file(&file);
}
#[test]
fn a_changed_sensor_set_forces_a_new_sweep() {
let file = path("changed");
ensure_map(
&mut backend(),
&config(2),
MapThresholds::default(),
&file,
|_| {},
)
.expect("first");
let mut fresh = backend();
let map = ensure_map(
&mut fresh,
&config(2),
MapThresholds::default(),
&file,
|_| {},
)
.expect("second");
assert_eq!(map.zones_for(1), vec![1]);
// The stored file describes two zones; asking for three must not reuse it.
let mut three = CountingBackend {
duty: vec![100, 100],
owners: vec![(0, 0), (1, 1)],
calls: 0,
};
let _ = ensure_map(
&mut three,
&config(3),
MapThresholds::default(),
&file,
|_| {},
);
assert!(three.calls > 0);
let _ = std::fs::remove_file(&file);
}
#[test]
fn samples_from_a_sweep_still_map_correctly() {
let samples = vec![
ProbeSample {
fan: 0,
pwm: 40,
readings: vec![ZoneReading {
zone: 0,
temp_mc: 70_000,
}],
},
ProbeSample {
fan: 0,
pwm: 100,
readings: vec![ZoneReading {
zone: 0,
temp_mc: 50_000,
}],
},
];
let map = map_fans(&samples, &[0], MapThresholds::default());
assert_eq!(map.zones_for(0), vec![0]);
}
}
+332
View File
@@ -0,0 +1,332 @@
// SPDX-License-Identifier: MIT
//! Fault-tolerance supervisor.
//!
//! The goal is to keep hashing with as many dead chips or chains as possible. Faults therefore
//! escalate in steps (retry, disable chip, disable chain) and only irreversible conditions stop the
//! machine. This module owns that ladder; it does not talk to hardware and it does not choose
//! thermal limits, which come from the profile envelope.
/// A single health observation from the mining loop.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum FaultEvent {
/// A chain accepted work and reported nonces for it.
NoncesReported { chain: u8, per_mille: u16 },
/// A chain returned an error for a frame, reset or work dispatch.
ChainError { chain: u8 },
/// A chain produced nothing for a full observation window.
ChainSilent { chain: u8 },
/// One chip on a chain failed its identification or stopped responding.
ChipFault { chain: u8, chip: u16 },
/// A temperature reading left the profile envelope.
TemperatureFault { zone: u8 },
}
/// What the caller should do next.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum FaultAction {
/// Keep hashing; nothing changed.
None,
/// Retry the chain before treating the fault as permanent.
Retry { chain: u8 },
/// Keep the machine running without this chain.
DisableChain { chain: u8 },
/// Keep the machine running without this chip.
DisableChip { chain: u8, chip: u16 },
/// Stop hashing entirely; the reason is carried for the API.
Stop { reason: StopReason },
}
/// Why the machine stopped.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum StopReason {
Temperature,
NoChainsLeft,
}
/// Thresholds for escalation.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct FaultPolicy {
/// Consecutive errors tolerated before the chain is disabled (retries included).
pub retries: u8,
/// Nonce-response ratio below which a chain is considered stalled.
pub min_response_per_mille: u16,
/// Consecutive weak windows before a stalled chain is disabled.
pub weak_windows: u8,
}
impl Default for FaultPolicy {
fn default() -> Self {
Self {
retries: 2,
min_response_per_mille: 100,
weak_windows: 3,
}
}
}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
struct ChainHealth {
chain: u8,
errors: u8,
weak: u8,
disabled: bool,
}
/// Escalation state for one machine.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct FaultSupervisor {
policy: FaultPolicy,
chains: Vec<ChainHealth>,
stopped: Option<StopReason>,
}
impl FaultSupervisor {
pub fn new(chains: &[u8], policy: FaultPolicy) -> Self {
Self {
policy,
chains: chains
.iter()
.map(|&chain| ChainHealth {
chain,
..ChainHealth::default()
})
.collect(),
stopped: None,
}
}
pub fn is_stopped(&self) -> bool {
self.stopped.is_some()
}
pub fn stop_reason(&self) -> Option<StopReason> {
self.stopped
}
/// Chains the miner may still dispatch work to.
pub fn active_chains(&self) -> Vec<u8> {
self.chains
.iter()
.filter(|health| !health.disabled)
.map(|health| health.chain)
.collect()
}
/// Apply one observation and return the escalation step it implies.
pub fn observe(&mut self, event: FaultEvent) -> FaultAction {
if self.stopped.is_some() {
return FaultAction::None;
}
match event {
FaultEvent::NoncesReported { chain, per_mille } => {
let min_response = self.policy.min_response_per_mille;
let weak_windows = self.policy.weak_windows;
let Some(health) = self.health_mut(chain) else {
return FaultAction::None;
};
health.errors = 0;
if per_mille >= min_response {
health.weak = 0;
return FaultAction::None;
}
health.weak = health.weak.saturating_add(1);
if health.weak >= weak_windows {
health.disabled = true;
self.maybe_stop(chain)
} else {
FaultAction::None
}
}
FaultEvent::ChainError { chain } | FaultEvent::ChainSilent { chain } => {
let policy = self.policy;
let Some(health) = self.health_mut(chain) else {
return FaultAction::None;
};
if health.disabled {
return FaultAction::None;
}
health.errors = health.errors.saturating_add(1);
if health.errors > policy.retries {
health.disabled = true;
self.maybe_stop(chain)
} else {
FaultAction::Retry { chain }
}
}
FaultEvent::ChipFault { chain, chip } => FaultAction::DisableChip { chain, chip },
FaultEvent::TemperatureFault { .. } => {
self.stopped = Some(StopReason::Temperature);
FaultAction::Stop {
reason: StopReason::Temperature,
}
}
}
}
fn health_mut(&mut self, chain: u8) -> Option<&mut ChainHealth> {
self.chains.iter_mut().find(|health| health.chain == chain)
}
fn maybe_stop(&mut self, chain: u8) -> FaultAction {
if self.chains.iter().all(|health| health.disabled) {
self.stopped = Some(StopReason::NoChainsLeft);
return FaultAction::Stop {
reason: StopReason::NoChainsLeft,
};
}
FaultAction::DisableChain { chain }
}
}
#[cfg(test)]
mod tests {
use super::*;
fn supervisor() -> FaultSupervisor {
FaultSupervisor::new(&[0, 1, 2], FaultPolicy::default())
}
#[test]
fn transient_errors_retry_then_disable_the_chain() {
let mut faults = supervisor();
assert_eq!(
faults.observe(FaultEvent::ChainError { chain: 1 }),
FaultAction::Retry { chain: 1 }
);
assert_eq!(
faults.observe(FaultEvent::ChainError { chain: 1 }),
FaultAction::Retry { chain: 1 }
);
assert_eq!(
faults.observe(FaultEvent::ChainSilent { chain: 1 }),
FaultAction::DisableChain { chain: 1 }
);
assert_eq!(faults.active_chains(), vec![0, 2]);
}
#[test]
fn healthy_nonces_reset_the_error_count() {
let mut faults = supervisor();
faults.observe(FaultEvent::ChainError { chain: 0 });
faults.observe(FaultEvent::ChainError { chain: 0 });
assert_eq!(
faults.observe(FaultEvent::NoncesReported {
chain: 0,
per_mille: 900
}),
FaultAction::None
);
assert_eq!(
faults.observe(FaultEvent::ChainError { chain: 0 }),
FaultAction::Retry { chain: 0 }
);
}
#[test]
fn a_stalled_chain_is_disabled_after_repeated_weak_windows() {
let mut faults = supervisor();
for _ in 0..2 {
assert_eq!(
faults.observe(FaultEvent::NoncesReported {
chain: 2,
per_mille: 10
}),
FaultAction::None
);
}
assert_eq!(
faults.observe(FaultEvent::NoncesReported {
chain: 2,
per_mille: 10
}),
FaultAction::DisableChain { chain: 2 }
);
assert_eq!(faults.active_chains(), vec![0, 1]);
}
#[test]
fn one_good_window_clears_weak_history() {
let mut faults = supervisor();
faults.observe(FaultEvent::NoncesReported {
chain: 0,
per_mille: 10,
});
faults.observe(FaultEvent::NoncesReported {
chain: 0,
per_mille: 10,
});
faults.observe(FaultEvent::NoncesReported {
chain: 0,
per_mille: 900,
});
faults.observe(FaultEvent::NoncesReported {
chain: 0,
per_mille: 10,
});
faults.observe(FaultEvent::NoncesReported {
chain: 0,
per_mille: 10,
});
assert_eq!(
faults.observe(FaultEvent::NoncesReported {
chain: 0,
per_mille: 10
}),
FaultAction::DisableChain { chain: 0 }
);
}
#[test]
fn a_chip_fault_disables_only_that_chip() {
let mut faults = supervisor();
assert_eq!(
faults.observe(FaultEvent::ChipFault { chain: 1, chip: 42 }),
FaultAction::DisableChip { chain: 1, chip: 42 }
);
assert_eq!(faults.active_chains(), vec![0, 1, 2]);
}
#[test]
fn temperature_fault_stops_the_machine() {
let mut faults = supervisor();
assert_eq!(
faults.observe(FaultEvent::TemperatureFault { zone: 2 }),
FaultAction::Stop {
reason: StopReason::Temperature
}
);
assert!(faults.is_stopped());
assert_eq!(
faults.observe(FaultEvent::ChainError { chain: 0 }),
FaultAction::None
);
}
#[test]
fn losing_every_chain_stops_instead_of_hanging() {
let mut faults = FaultSupervisor::new(
&[0],
FaultPolicy {
retries: 0,
..FaultPolicy::default()
},
);
assert_eq!(
faults.observe(FaultEvent::ChainError { chain: 0 }),
FaultAction::Stop {
reason: StopReason::NoChainsLeft
}
);
assert_eq!(faults.active_chains(), Vec::<u8>::new());
}
#[test]
fn unknown_chains_are_ignored() {
let mut faults = supervisor();
assert_eq!(
faults.observe(FaultEvent::ChainError { chain: 9 }),
FaultAction::None
);
assert_eq!(faults.active_chains(), vec![0, 1, 2]);
}
}
+66
View File
@@ -0,0 +1,66 @@
// SPDX-License-Identifier: MIT
//! Shared `application/x-www-form-urlencoded` / query decoding for the HTTP edge.
//!
//! One implementation, used by the web server, the miner service and the
//! dashboard, so a fix or a bug cannot diverge between copies.
/// Percent-decode a form or query token (`%XX` escapes and `+` as space).
pub fn percent_decode(text: &str) -> String {
let bytes = text.as_bytes();
let mut out = Vec::with_capacity(bytes.len());
let mut i = 0;
while i < bytes.len() {
match bytes[i] {
b'%' if i + 2 < bytes.len() => {
let hex = std::str::from_utf8(&bytes[i + 1..i + 3]).unwrap_or("");
match u8::from_str_radix(hex, 16) {
Ok(byte) => {
out.push(byte);
i += 3;
}
Err(_) => {
out.push(bytes[i]);
i += 1;
}
}
}
b'+' => {
out.push(b' ');
i += 1;
}
byte => {
out.push(byte);
i += 1;
}
}
}
String::from_utf8_lossy(&out).into_owned()
}
/// Read one field from a urlencoded body by key (first match), percent-decoded.
pub fn field(body: &str, key: &str) -> Option<String> {
body.split('&').find_map(|pair| {
let (k, v) = pair.split_once('=')?;
(percent_decode(k) == key).then(|| percent_decode(v))
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn decodes_escapes_and_plus() {
assert_eq!(percent_decode("a+b%2Fc"), "a b/c");
assert_eq!(percent_decode("%0d%0a"), "\r\n");
// A truncated trailing escape is passed through, not dropped.
assert_eq!(percent_decode("x%2"), "x%2");
}
#[test]
fn field_reads_first_match() {
assert_eq!(field("a=1&b=two&a=3", "b").as_deref(), Some("two"));
assert_eq!(field("a=1", "missing"), None);
assert_eq!(field("csrf=tok&user=admin", "csrf").as_deref(), Some("tok"));
}
}
+218
View File
@@ -0,0 +1,218 @@
// SPDX-License-Identifier: MIT
//! HAL conformance checks.
//!
//! A family backend is only useful if it answers the contract the OS expects. This module walks the
//! contract in order and reports each check separately, so a backend author sees exactly which
//! opcode is missing or wrong instead of a single opaque failure.
//!
//! Every check uses a fresh connection: a backend that desynchronises one exchange must not make
//! the following checks meaningless.
use crate::hal_wire::{HalClient, CAP_CHAIN_PROBE, CAP_FREQUENCY, CAP_POWER, CAP_PSU_IDENTITY};
use crate::HardwareBackend;
use std::path::Path;
/// One check and its outcome.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Check {
pub name: &'static str,
pub passed: bool,
pub detail: String,
}
impl Check {
fn pass(name: &'static str, detail: impl Into<String>) -> Self {
Self {
name,
passed: true,
detail: detail.into(),
}
}
fn fail(name: &'static str, detail: impl Into<String>) -> Self {
Self {
name,
passed: false,
detail: detail.into(),
}
}
}
/// Run the contract checks against a backend socket.
pub fn run(socket: &Path) -> Vec<Check> {
vec![
check_capabilities(socket),
check_probe(socket),
check_eeprom(socket),
check_psu(socket),
check_frequency_and_temperature(socket),
check_power(socket),
check_fan(socket),
]
}
fn connect(socket: &Path) -> Result<HalClient, String> {
HalClient::connect(socket).map_err(|error| format!("{error:?}"))
}
fn check_capabilities(socket: &Path) -> Check {
const NAME: &str = "capabilities";
match connect(socket)
.and_then(|mut client| client.capabilities().map_err(|error| format!("{error:?}")))
{
Ok(mask) if mask & CAP_CHAIN_PROBE == 0 => {
Check::fail(NAME, format!("mask {mask:#x} lacks chain probing"))
}
Ok(mask) => Check::pass(NAME, format!("mask {mask:#x}")),
Err(error) => Check::fail(NAME, error),
}
}
fn check_probe(socket: &Path) -> Check {
const NAME: &str = "probe chain 0";
match connect(socket) {
Ok(mut client) => match client.probe_chain(0, 0) {
Ok(outcome) => Check::pass(NAME, format!("{outcome:?}")),
Err(error) => Check::fail(NAME, format!("{error:?}")),
},
Err(error) => Check::fail(NAME, error),
}
}
fn check_eeprom(socket: &Path) -> Check {
const NAME: &str = "read EEPROM chain 0";
match connect(socket) {
Ok(mut client) => match client.read_eeprom(0) {
Ok(state) => Check::pass(NAME, format!("{state:?}")),
Err(error) => Check::fail(NAME, format!("{error:?}")),
},
Err(error) => Check::fail(NAME, error),
}
}
fn check_psu(socket: &Path) -> Check {
const NAME: &str = "identify PSU";
match connect(socket) {
Ok(mut client) => match client.capabilities() {
Ok(mask) if mask & CAP_PSU_IDENTITY == 0 => {
Check::fail(NAME, "backend does not advertise PSU identity")
}
Ok(_) => match client.identify_psu() {
Ok(psu) if psu.envelope.v_min_mv <= psu.envelope.v_max_mv => {
Check::pass(NAME, format!("{} {} mV", psu.name, psu.envelope.v_max_mv))
}
Ok(psu) => Check::fail(NAME, format!("inverted envelope from {}", psu.name)),
Err(error) => Check::fail(NAME, format!("{error:?}")),
},
Err(error) => Check::fail(NAME, format!("{error:?}")),
},
Err(error) => Check::fail(NAME, error),
}
}
fn check_frequency_and_temperature(socket: &Path) -> Check {
const NAME: &str = "frequency and temperature";
match connect(socket) {
Ok(mut client) => {
let caps = match client.capabilities() {
Ok(mask) => mask,
Err(error) => return Check::fail(NAME, format!("{error:?}")),
};
if caps & CAP_FREQUENCY == 0 {
return Check::fail(NAME, "backend does not advertise frequency control");
}
if let Err(error) = client.set_chain_frequency(0, 500) {
return Check::fail(NAME, format!("set frequency: {error:?}"));
}
match client.read_temperature_mc(0) {
Ok(value) if (-40_000..=150_000).contains(&value) => {
Check::pass(NAME, format!("500 MHz, {} mC", value))
}
Ok(value) => Check::fail(NAME, format!("implausible temperature {value} mC")),
Err(error) => Check::fail(NAME, format!("read temperature: {error:?}")),
}
}
Err(error) => Check::fail(NAME, error),
}
}
fn check_power(socket: &Path) -> Check {
const NAME: &str = "read power";
match connect(socket) {
Ok(mut client) => match client.capabilities() {
Ok(mask) if mask & CAP_POWER == 0 => {
Check::fail(NAME, "backend does not advertise power telemetry")
}
Ok(_) => {
// Ask for a known operating point first: a backend that always reports 0 W would
// otherwise pass a range check while being useless to a power-target loop.
if let Err(error) = client.set_chain_frequency(0, 500) {
return Check::fail(NAME, format!("set frequency: {error:?}"));
}
std::thread::sleep(std::time::Duration::from_millis(50));
match client.read_power_w() {
Ok(0) => Check::fail(NAME, "reports 0 W at 500 MHz"),
Ok(watts) if watts <= 10_000 => {
Check::pass(NAME, format!("{watts} W at 500 MHz"))
}
Ok(watts) => Check::fail(NAME, format!("implausible power {watts} W")),
Err(error) => Check::fail(NAME, format!("{error:?}")),
}
}
Err(error) => Check::fail(NAME, format!("{error:?}")),
},
Err(error) => Check::fail(NAME, error),
}
}
fn check_fan(socket: &Path) -> Check {
const NAME: &str = "fan target";
match connect(socket) {
Ok(mut client) => match client.set_fan_target(0, 100) {
Ok(()) => Check::pass(NAME, "100 percent accepted"),
Err(error) => Check::fail(NAME, format!("{error:?}")),
},
Err(error) => Check::fail(NAME, error),
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::hal_sim::{serve, SimConfig};
fn socket(name: &str) -> std::path::PathBuf {
std::env::temp_dir().join(format!("alkane-conf-{}-{name}.sock", std::process::id()))
}
#[test]
fn the_reference_server_passes_every_check() {
let path = socket("ok");
let server_path = path.clone();
let server = std::thread::spawn(move || {
let _ = serve(&server_path, SimConfig::default());
});
// The reference server binds inside serve(); wait for the socket to exist.
for _ in 0..100 {
if path.exists() {
break;
}
std::thread::sleep(std::time::Duration::from_millis(10));
}
let checks = run(&path);
let failed: Vec<&Check> = checks.iter().filter(|check| !check.passed).collect();
assert!(failed.is_empty(), "reference server failed: {failed:?}");
assert_eq!(checks.len(), 7);
let _ = std::fs::remove_file(&path);
// The server thread is left to exit when the socket disappears.
drop(server);
}
#[test]
fn an_unreachable_socket_fails_every_check() {
let path = socket("missing");
let checks = run(&path);
assert_eq!(checks.len(), 7);
assert!(checks.iter().all(|check| !check.passed));
}
}
+255
View File
@@ -0,0 +1,255 @@
// SPDX-License-Identifier: MIT
//! Reference HAL server.
//!
//! Speaks the same ALKH contract a family backend serves on a real board, but answers from a fixed
//! description of a machine. Two uses: it lets the whole OS path run on any development machine, and
//! it shows a backend author exactly what each opcode must return.
use std::io::{self, Read, Write};
use std::os::unix::net::{UnixListener, UnixStream};
use std::path::Path;
const MAGIC: [u8; 4] = *b"ALKH";
const VERSION: u8 = 1;
const RESPONSE: u16 = 1;
const HEADER_LEN: usize = 16;
const SEND_FRAME: u8 = 1;
const RECEIVE_FRAME: u8 = 2;
const SET_CHAIN_RESET: u8 = 3;
const SET_FAN_TARGET: u8 = 4;
const READ_TEMPERATURE: u8 = 5;
const SET_PSU_ENABLED: u8 = 6;
const CAPABILITIES: u8 = 7;
const PROBE_CHAIN: u8 = 8;
const READ_EEPROM: u8 = 9;
const IDENTIFY_PSU: u8 = 10;
const SET_CHAIN_FREQUENCY: u8 = 11;
const READ_POWER: u8 = 12;
const CAP_ALL: u32 = (1 << 5) - 1;
/// What the simulated machine looks like.
#[derive(Clone, Debug)]
pub struct SimConfig {
/// Chains that identify. Chains beyond this answer silent.
pub chains: u8,
/// Chips reported per chain.
pub chips: u16,
/// Chip identifier on the wire (1 = bm1362).
pub chip: u8,
/// Report a working EEPROM instead of an absent one.
pub eeprom: bool,
/// PSU name and envelope, or `None` to fail identification.
pub psu: Option<(String, u16, u16, u16, u16, u16)>,
/// Fans on the simulated chassis; zones are distributed over them.
pub fans: u8,
}
impl Default for SimConfig {
fn default() -> Self {
Self {
chains: 3,
chips: 126,
chip: 1,
eeprom: false,
psu: Some(("APW12".into(), 1200, 1600, 0, 1000, 3600)),
fans: 2,
}
}
}
struct State {
config: SimConfig,
frequency_mhz: u16,
/// Duty per fan, so a zone can respond to the fan that actually cools it.
fan_pwm: [u8; 4],
}
impl State {
/// Which fan cools a zone. Zones are distributed over the fans round-robin.
fn owner(&self, zone: u8) -> usize {
let fans = usize::from(self.config.fans.max(1));
usize::from(zone) % fans
}
}
/// Serve one socket path until the program exits.
pub fn serve(path: &Path, config: SimConfig) -> io::Result<()> {
let _ = std::fs::remove_file(path);
let listener = UnixListener::bind(path)?;
for stream in listener.incoming() {
let Ok(stream) = stream else { continue };
let mut state = State {
config: config.clone(),
frequency_mhz: 0,
fan_pwm: [100; 4],
};
let _ = serve_connection(stream, &mut state);
}
Ok(())
}
fn serve_connection(mut stream: UnixStream, state: &mut State) -> io::Result<()> {
loop {
let mut header = [0_u8; HEADER_LEN];
if stream.read_exact(&mut header).is_err() {
return Ok(());
}
if header[..4] != MAGIC {
return Err(io::Error::new(io::ErrorKind::InvalidData, "bad HAL magic"));
}
let opcode = header[5];
let sequence = header[8..12].to_vec();
let length = u32::from_le_bytes([header[12], header[13], header[14], header[15]]) as usize;
let mut payload = vec![0_u8; length];
if length > 0 && stream.read_exact(&mut payload).is_err() {
return Ok(());
}
let body = respond(opcode, &payload, state);
let mut out = [0_u8; HEADER_LEN];
out[..4].copy_from_slice(&MAGIC);
out[4] = VERSION;
out[5] = opcode;
out[6..8].copy_from_slice(&RESPONSE.to_le_bytes());
out[8..12].copy_from_slice(&sequence);
out[12..16].copy_from_slice(&(body.len() as u32).to_le_bytes());
stream.write_all(&out)?;
stream.write_all(&body)?;
stream.flush()?;
}
}
fn respond(opcode: u8, payload: &[u8], state: &mut State) -> Vec<u8> {
match opcode {
CAPABILITIES => {
let mut body = vec![0_u8];
body.extend_from_slice(&CAP_ALL.to_le_bytes());
body
}
PROBE_CHAIN => {
let chain = payload.first().copied().unwrap_or(0);
if chain >= state.config.chains {
return vec![0, 1, 0, 0, 0]; // silent
}
let chips = state.config.chips.to_le_bytes();
vec![0, 0, state.config.chip, chips[0], chips[1]]
}
READ_EEPROM => {
if state.config.eeprom {
let mut body = vec![0_u8, 0];
body.extend_from_slice(b"BHB42601");
body
} else {
vec![0, 1]
}
}
IDENTIFY_PSU => match &state.config.psu {
Some((name, v_min, v_max, f_min, f_max, watts)) => {
let mut body = vec![0_u8, name.len() as u8];
body.extend_from_slice(name.as_bytes());
for word in [*v_min, *v_max, *f_min, *f_max, *watts] {
body.extend_from_slice(&word.to_le_bytes());
}
body
}
None => vec![1],
},
SET_CHAIN_FREQUENCY => {
if let Some(mhz) = payload.get(1..3) {
state.frequency_mhz = u16::from_le_bytes([mhz[0], mhz[1]]);
}
vec![0]
}
SET_FAN_TARGET => {
let fan = usize::from(payload.first().copied().unwrap_or(0)).min(3);
state.fan_pwm[fan] = payload.get(1).copied().unwrap_or(0);
vec![0]
}
READ_TEMPERATURE => {
// Temperature rises with frequency so the tuner has something to regulate, and falls
// when the fan that owns the zone is fast so the fan sweep can learn the mapping.
let zone = payload.first().copied().unwrap_or(0);
let rise = i32::from(state.frequency_mhz) * 20;
let airflow = if state.fan_pwm[state.owner(zone)] >= 100 {
0
} else {
20_000
};
let mut body = vec![0_u8];
body.extend_from_slice(&(45_000 + rise + airflow).to_le_bytes());
body
}
READ_POWER => {
// Four watts per MHz, so a power target has something to regulate.
let watts = u16::try_from(u32::from(state.frequency_mhz) * 4).unwrap_or(u16::MAX);
let mut body = vec![0_u8];
body.extend_from_slice(&watts.to_le_bytes());
body
}
SET_CHAIN_RESET | SET_PSU_ENABLED => vec![0],
SEND_FRAME => vec![0],
RECEIVE_FRAME => {
// No nonce traffic in the reference backend.
let count: u16 = 0;
let mut body = vec![0_u8];
body.extend_from_slice(&count.to_le_bytes());
body
}
_ => vec![1],
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::fanmap::FanProbe;
use crate::hal_wire::HalClient;
use crate::HardwareBackend;
#[test]
fn a_client_can_detect_against_the_reference_server() {
let path = std::env::temp_dir().join(format!("alkane-sim-hal-{}.sock", std::process::id()));
// Bind before spawning so the client cannot race the socket into existence.
let listener = UnixListener::bind(&path).expect("bind");
let server = std::thread::spawn(move || {
let (stream, _) = listener.accept().expect("accept");
let mut state = State {
config: SimConfig::default(),
frequency_mhz: 0,
fan_pwm: [100; 4],
};
let _ = serve_connection(stream, &mut state);
});
let mut client = HalClient::connect(&path).expect("connect");
assert_eq!(client.capabilities().expect("caps"), CAP_ALL);
match client.probe_chain(0, 0).expect("probe") {
crate::detect::ProbeOutcome::Identified { chip, chips } => {
assert_eq!(chip, crate::detect::ChipModel::Bm1362);
assert_eq!(chips, 126);
}
other => panic!("unexpected probe: {other:?}"),
}
assert_eq!(
client.read_eeprom(0).expect("eeprom"),
crate::detect::EepromState::Absent
);
let psu = client.identify_psu().expect("psu");
assert_eq!(psu.name, "APW12");
client.set_chain_frequency(0, 512).expect("freq");
assert_eq!(client.read_power_w().expect("power"), 512 * 4);
// Zone 1 is owned by fan 1: slowing fan 1 must heat zone 1 and not zone 0.
let baseline_0 = client.read_temperature_mc(0).expect("temp");
let baseline_1 = client.read_temperature_mc(1).expect("temp");
client.set_fan(1, 40).expect("fan");
assert_eq!(client.read_temperature_mc(0).expect("temp"), baseline_0);
assert!(client.read_temperature_mc(1).expect("temp") > baseline_1);
assert_eq!(
client.read_temperature_mc(0).expect("temp"),
45_000 + 512 * 20
);
drop(client);
let _ = std::fs::remove_file(&path);
server.join().expect("server");
}
}
+286
View File
@@ -1,6 +1,9 @@
// SPDX-License-Identifier: MIT
//! Versioned local wire contract between Alkane OS and an SDK hardware backend.
use crate::detect::{
ChipModel, DetectionBackend, EepromState, Envelope, ProbeOutcome, PsuCapability,
};
use crate::HardwareBackend;
use std::fmt;
use std::io::{self, Read, Write};
@@ -24,6 +27,27 @@ const SET_CHAIN_RESET: u8 = 3;
const SET_FAN_TARGET: u8 = 4;
const READ_TEMPERATURE: u8 = 5;
const SET_PSU_ENABLED: u8 = 6;
const CAPABILITIES: u8 = 7;
const PROBE_CHAIN: u8 = 8;
const READ_EEPROM: u8 = 9;
const IDENTIFY_PSU: u8 = 10;
const SET_CHAIN_FREQUENCY: u8 = 11;
const READ_POWER: u8 = 12;
/// Backend feature bits reported by `CAPABILITIES`.
pub const CAP_CHAIN_PROBE: u32 = 1 << 0;
pub const CAP_EEPROM: u32 = 1 << 1;
pub const CAP_PSU_IDENTITY: u32 = 1 << 2;
pub const CAP_FREQUENCY: u32 = 1 << 3;
pub const CAP_POWER: u32 = 1 << 4;
const PROBE_IDENTIFIED: u8 = 0;
const PROBE_SILENT: u8 = 1;
const PROBE_GARBLED: u8 = 2;
const EEPROM_PRESENT: u8 = 0;
const EEPROM_ABSENT: u8 = 1;
const EEPROM_INVALID: u8 = 2;
#[cfg(not(target_os = "linux"))]
compile_error!("Alkane HAL sockets require Linux");
@@ -337,6 +361,156 @@ fn connect_until(path: &Path, deadline: Instant) -> io::Result<UnixStream> {
Ok(stream)
}
impl HalClient {
/// Feature mask advertised by the backend. Old backends reject the opcode, which surfaces as
/// a protocol error rather than a silent zero.
pub fn capabilities(&mut self) -> Result<u32, HalError> {
let body = self.exchange(CAPABILITIES, &[])?;
let bytes: [u8; 4] = body
.try_into()
.map_err(|_| HalError::Protocol("invalid capability response"))?;
Ok(u32::from_le_bytes(bytes))
}
fn require(&mut self, capability: u32) -> Result<(), HalError> {
if self.capabilities()? & capability == 0 {
return Err(HalError::Protocol("backend lacks a detection capability"));
}
Ok(())
}
pub fn probe_chain(&mut self, chain: u8, attempt: u8) -> Result<ProbeOutcome, HalError> {
self.require(CAP_CHAIN_PROBE)?;
let body = self.exchange(PROBE_CHAIN, &[chain, attempt])?;
if body.len() != 4 {
self.poison();
return Err(HalError::Protocol("invalid probe response"));
}
let chips = u16::from_le_bytes([body[2], body[3]]);
match body[0] {
PROBE_IDENTIFIED => match chip_from_wire(body[1]) {
Some(chip) => Ok(ProbeOutcome::Identified { chip, chips }),
None => {
self.poison();
Err(HalError::Protocol("unknown chip identifier"))
}
},
PROBE_SILENT => Ok(ProbeOutcome::Silent),
PROBE_GARBLED => Ok(ProbeOutcome::Garbled),
_ => {
self.poison();
Err(HalError::Protocol("invalid probe outcome"))
}
}
}
pub fn read_eeprom(&mut self, chain: u8) -> Result<EepromState, HalError> {
self.require(CAP_EEPROM)?;
let body = self.exchange(READ_EEPROM, &[chain])?;
match body.first().copied() {
Some(EEPROM_ABSENT) if body.len() == 1 => Ok(EepromState::Absent),
Some(EEPROM_INVALID) if body.len() == 1 => Ok(EepromState::Invalid),
Some(EEPROM_PRESENT) if body.len() > 1 => {
let model = std::str::from_utf8(&body[1..])
.map_err(|_| HalError::Protocol("invalid EEPROM model text"))?;
Ok(EepromState::Present {
model: model.to_owned(),
})
}
_ => {
self.poison();
Err(HalError::Protocol("invalid EEPROM response"))
}
}
}
/// Apply a chain frequency in MHz. The backend owns the PLL write; the OS owns the decision.
pub fn set_chain_frequency(&mut self, chain: u8, mhz: u16) -> Result<(), HalError> {
self.require(CAP_FREQUENCY)?;
let mut payload = [0_u8; 3];
payload[0] = chain;
payload[1..].copy_from_slice(&mhz.to_le_bytes());
self.empty_reply(SET_CHAIN_FREQUENCY, &payload)
}
/// Measured DC input power in watts, when the board can read its PSU.
pub fn read_power_w(&mut self) -> Result<u16, HalError> {
self.require(CAP_POWER)?;
let body = self.exchange(READ_POWER, &[])?;
if body.len() != 2 {
self.poison();
return Err(HalError::Protocol("invalid power response"));
}
Ok(u16::from_le_bytes([body[0], body[1]]))
}
pub fn identify_psu(&mut self) -> Result<PsuCapability, HalError> {
self.require(CAP_PSU_IDENTITY)?;
let body = self.exchange(IDENTIFY_PSU, &[])?;
let name_len = *body
.first()
.ok_or(HalError::Protocol("empty PSU response"))? as usize;
if body.len() != name_len + 1 + 10 {
self.poison();
return Err(HalError::Protocol("invalid PSU response"));
}
let name = std::str::from_utf8(&body[1..1 + name_len])
.map_err(|_| HalError::Protocol("invalid PSU name"))?
.to_owned();
let at = 1 + name_len;
let word = |offset: usize| u16::from_le_bytes([body[at + offset], body[at + offset + 1]]);
Ok(PsuCapability {
name,
envelope: Envelope {
v_min_mv: word(0),
v_max_mv: word(2),
f_min_mhz: word(4),
f_max_mhz: word(6),
},
max_dc_watts: word(8),
})
}
}
impl DetectionBackend for HalClient {
type Error = HalError;
fn probe(&mut self, chain: u8, attempt: u8) -> Result<ProbeOutcome, Self::Error> {
self.probe_chain(chain, attempt)
}
fn eeprom(&mut self, chain: u8) -> Result<EepromState, Self::Error> {
self.read_eeprom(chain)
}
fn identify_psu(&mut self) -> Result<Option<PsuCapability>, Self::Error> {
self.identify_psu().map(Some)
}
}
impl crate::fanmap::FanProbe for HalClient {
type Error = HalError;
fn set_fan(&mut self, fan: u8, pwm: u8) -> Result<(), Self::Error> {
self.set_fan_target(fan, pwm)
}
fn read_zone(&mut self, zone: u8) -> Result<i32, Self::Error> {
self.read_temperature_mc(zone)
}
}
fn chip_from_wire(value: u8) -> Option<ChipModel> {
match value {
1 => Some(ChipModel::Bm1362),
2 => Some(ChipModel::Bm1366),
3 => Some(ChipModel::Bm1368),
4 => Some(ChipModel::Bm1370),
5 => Some(ChipModel::Bm1398),
_ => None,
}
}
impl HardwareBackend for HalClient {
type Error = HalError;
@@ -403,3 +577,115 @@ impl HardwareBackend for HalClient {
result
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::fanmap::FanProbe;
use std::os::unix::net::UnixStream;
fn mock_backend(mut server: UnixStream) {
loop {
let mut header = [0_u8; 16];
if server.read_exact(&mut header).is_err() {
return;
}
let opcode = header[5];
let sequence = [header[8], header[9], header[10], header[11]];
let length = u32::from_le_bytes(header[12..16].try_into().unwrap()) as usize;
let mut payload = vec![0_u8; length];
if length > 0 && server.read_exact(&mut payload).is_err() {
return;
}
let body: Vec<u8> = match opcode {
CAPABILITIES => {
let mut body = vec![0_u8];
body.extend_from_slice(
&(CAP_CHAIN_PROBE
| CAP_EEPROM
| CAP_PSU_IDENTITY
| CAP_FREQUENCY
| CAP_POWER)
.to_le_bytes(),
);
body
}
PROBE_CHAIN => vec![0, PROBE_IDENTIFIED, 1, 126, 0],
READ_EEPROM => {
let mut body = vec![0, EEPROM_PRESENT];
body.extend_from_slice(b"BHB42601");
body
}
IDENTIFY_PSU => {
let name = b"APW12";
let mut body = vec![0_u8];
body.push(name.len() as u8);
body.extend_from_slice(name);
for word in [1200_u16, 1600, 0, 1000, 3600] {
body.extend_from_slice(&word.to_le_bytes());
}
body
}
SET_FAN_TARGET | SET_CHAIN_FREQUENCY => vec![0],
READ_POWER => {
let mut body = vec![0_u8];
body.extend_from_slice(&0_u16.to_le_bytes());
body
}
READ_TEMPERATURE => {
let mut body = vec![0_u8];
body.extend_from_slice(&42_000_i32.to_le_bytes());
body
}
_ => vec![1],
};
let mut out = [0_u8; 16];
out[..4].copy_from_slice(&MAGIC);
out[4] = VERSION;
out[5] = opcode;
out[6..8].copy_from_slice(&RESPONSE.to_le_bytes());
out[8..12].copy_from_slice(&sequence);
out[12..16].copy_from_slice(&(body.len() as u32).to_le_bytes());
if server.write_all(&out).is_err() || server.write_all(&body).is_err() {
return;
}
}
}
#[test]
fn detection_verbs_round_trip_over_the_wire() {
let (client_stream, server_stream) = UnixStream::pair().expect("socket pair");
let server = std::thread::spawn(move || mock_backend(server_stream));
let mut client = HalClient::from_stream(client_stream).expect("client");
assert_eq!(
client.capabilities().expect("capabilities"),
CAP_CHAIN_PROBE | CAP_EEPROM | CAP_PSU_IDENTITY | CAP_FREQUENCY | CAP_POWER
);
match client.probe_chain(0, 0).expect("probe") {
ProbeOutcome::Identified { chip, chips } => {
assert_eq!(chip, ChipModel::Bm1362);
assert_eq!(chips, 126);
}
other => panic!("unexpected probe outcome: {other:?}"),
}
assert_eq!(
client.read_eeprom(0).expect("eeprom"),
EepromState::Present {
model: "BHB42601".into()
}
);
let psu = client.identify_psu().expect("psu");
assert_eq!(psu.name, "APW12");
assert_eq!(psu.envelope.v_min_mv, 1200);
assert_eq!(psu.envelope.v_max_mv, 1600);
assert_eq!(psu.max_dc_watts, 3600);
client.set_chain_frequency(2, 512).expect("set frequency");
client.set_fan(1, 60).expect("set fan");
assert_eq!(client.read_zone(2).expect("read zone"), 42_000);
drop(client);
server.join().expect("server thread");
}
}
+25
View File
@@ -3,21 +3,46 @@
//! An entry in the target matrix is a development obligation, not a claim that
//! the pairing already mines. Hardware backends are supplied by SDK images.
pub mod app;
pub mod auth;
pub mod bm1362;
pub mod bm1366;
pub mod bm1370;
pub mod bm13xx;
pub mod bus;
pub mod console;
pub mod control;
pub mod dashboard;
pub mod detect;
pub mod difficulty;
pub mod fanmap;
pub mod fanmap_store;
pub mod fault;
pub mod form;
pub mod hal_conformance;
pub mod hal_sim;
pub mod hal_wire;
pub mod management;
pub mod miner;
pub mod pow;
pub mod profiles;
pub mod registry;
pub mod runtime;
pub mod scrypt_pow;
pub mod service;
pub mod split;
pub mod stratum_client;
pub mod stratum_link;
pub mod stratum_session;
pub mod stratum_submit;
pub mod stratum_v1;
pub mod stratum_v2;
pub mod stratum_v2_session;
pub mod stratum_wire;
pub mod stratum_work;
pub mod tuning;
pub mod ui;
pub mod web;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum Vendor {
+498 -10
View File
@@ -1,9 +1,20 @@
// SPDX-License-Identifier: MIT
use alkane_os::app;
use alkane_os::bus::Bus;
use alkane_os::control::Control;
use alkane_os::detect::{
ChipModel as DetectedChip, DetectionBackend, EepromState, Envelope, ProbeBudget, ProbeOutcome,
PsuCapability, SensorTopology,
};
use alkane_os::hal_wire::HalClient;
use alkane_os::management::{bind_local, serve, MiningStatus};
use alkane_os::management::MiningStatus;
use alkane_os::miner::{Bm1366Miner, ChipModel};
use alkane_os::runtime::{Tick, TickOutcome};
use alkane_os::service;
use alkane_os::stratum_client::{PoolConnection, PoolEvent};
use alkane_os::target_matrix;
use alkane_os::tuning::{PidConfig, TuningTarget};
use alkane_os::HardwareBackend;
use std::error::Error;
use std::io;
use std::net::SocketAddr;
@@ -26,14 +37,22 @@ fn sim_mine(mut args: impl Iterator<Item = String>) -> Result<(), Box<dyn Error>
let password = std::env::var("ALKANE_POOL_PASSWORD")
.map_err(|_| "set ALKANE_POOL_PASSWORD in the environment")?;
let status = Arc::new(MiningStatus::new());
if let Ok(bind) = std::env::var("ALKANE_API_LISTEN") {
let listener = bind_local(bind.parse()?)?;
let snapshot = Arc::clone(&status);
std::thread::spawn(move || {
if let Err(error) = serve(listener, snapshot) {
eprintln!("management API stopped: {error}");
}
});
let api = std::env::var("ALKANE_API_LISTEN")
.ok()
.map(|bind| bind.parse())
.transpose()?;
let web = web_listen()?;
let control = Arc::new(Control::default());
let bus = Bus::new();
service::register(&bus, Arc::clone(&status), Arc::clone(&control));
service::publish(&bus, &status, &control);
let servers = app::start(Arc::clone(&status), api, web, Arc::clone(&bus))?;
let (api_address, web_address) = servers.addresses();
if let Some(address) = api_address {
println!("management API on {address}");
}
if let Some(address) = web_address {
println!("web UI on http://{address}/");
}
// Connect to the pool before enabling power. The SDK HAL server owns the
@@ -80,6 +99,382 @@ fn sim_mine(mut args: impl Iterator<Item = String>) -> Result<(), Box<dyn Error>
}
}
/// A backend that answers without hardware, so the boot path can be exercised on any machine.
struct SelfCheckBackend;
impl DetectionBackend for SelfCheckBackend {
type Error = ();
fn probe(&mut self, _chain: u8, _attempt: u8) -> Result<ProbeOutcome, ()> {
Ok(ProbeOutcome::Identified {
chip: DetectedChip::Bm1362,
chips: 126,
})
}
fn eeprom(&mut self, _chain: u8) -> Result<EepromState, ()> {
Ok(EepromState::Absent)
}
fn identify_psu(&mut self) -> Result<Option<PsuCapability>, ()> {
Ok(Some(PsuCapability {
name: "APW12".into(),
envelope: Envelope {
v_min_mv: 1200,
v_max_mv: 1600,
f_min_mhz: 0,
f_max_mhz: 1000,
},
max_dc_watts: 3600,
}))
}
}
/// Run detection, the runtime loop and the API document against the self-check backend.
///
/// This is the smoke test an image can run on a bench machine before any hashboard is attached:
/// it proves the profile database parses, detection produces a plan, the tuner moves within the
/// envelope and the published document is well formed.
fn self_check() -> Result<(), Box<dyn Error>> {
let status = MiningStatus::new();
let config = app::BootConfig {
profile_db_json: include_str!("../profiles.example.json").to_owned(),
chain_ports: vec![0, 1, 2],
sensor: SensorTopology::Pic,
budget: ProbeBudget::default(),
fan_zones: Vec::new(),
target: TuningTarget::PowerW(2_400.0),
pid: PidConfig::default(),
ceiling_mc: 95_000,
fault_policy: Default::default(),
};
let mut backend = SelfCheckBackend;
let mut runtime = app::boot(&mut backend, &config, &status)?;
let start = runtime.operating_point().frequency_mhz;
for _ in 0..20 {
let power = 4.0 * f32::from(runtime.operating_point().frequency_mhz);
runtime.tick(&Tick {
power_w: Some(power),
hashrate_ths: None,
hottest_mc: Some(70_000),
ambient_mc: None,
dt_s: 1.0,
});
}
let end = runtime.operating_point().frequency_mhz;
if end <= start {
return Err("self-check: frequency did not move toward the target".into());
}
if runtime.active_chains().len() != 3 {
return Err("self-check: detection did not expose three chains".into());
}
status.set_hardware(app::snapshot(&runtime, &app::target_label(&config.target)));
let document = status.hardware_document();
if document["available"] != true {
return Err("self-check: hardware document is not available".into());
}
println!("{}", serde_json::to_string_pretty(&document)?);
Ok(())
}
fn parse_target(text: &str) -> Result<TuningTarget, Box<dyn Error>> {
let (kind, value) = text
.split_once(':')
.ok_or("target must look like power:2400")?;
let value: f32 = value.parse()?;
Ok(match kind {
"power" => TuningTarget::PowerW(value),
"hashrate" => TuningTarget::HashrateThs(value),
"ambient" => TuningTarget::AmbientC {
margin_mc: value as i32,
},
"fan" => TuningTarget::MaxFan {
max_pwm: value as u8,
},
_ => return Err("target must be power, hashrate, ambient or fan".into()),
})
}
/// Boot a real board through the HAL socket, then run a bounded tuning loop.
fn boot_hal(mut args: impl Iterator<Item = String>) -> Result<(), Box<dyn Error>> {
let socket = args.next().ok_or("missing HAL socket")?;
let profiles = args.next().ok_or("missing profile database path")?;
let target = parse_target(&args.next().ok_or("missing target")?)?;
let sensor = match args.next().as_deref() {
Some("nopic") => SensorTopology::NoPic,
Some("pic") | None => SensorTopology::Pic,
Some(_) => return Err("sensor must be pic or nopic".into()),
};
let ticks: usize = args
.next()
.map(|value| value.parse())
.transpose()?
.unwrap_or(30);
let profile_db_json = std::fs::read_to_string(&profiles)?;
let status = Arc::new(MiningStatus::new());
let api = std::env::var("ALKANE_API_LISTEN")
.ok()
.map(|bind| bind.parse())
.transpose()?;
let web = web_listen()?;
let control = Arc::new(Control::default());
let bus = Bus::new();
service::register(&bus, Arc::clone(&status), Arc::clone(&control));
service::publish(&bus, &status, &control);
let servers = app::start(Arc::clone(&status), api, web, Arc::clone(&bus))?;
let config = app::BootConfig {
profile_db_json,
chain_ports: vec![0, 1, 2],
sensor,
budget: ProbeBudget::default(),
fan_zones: Vec::new(),
target,
pid: PidConfig::default(),
ceiling_mc: 95_000,
fault_policy: Default::default(),
};
let map_path = std::path::PathBuf::from(
std::env::var("ALKANE_FANMAP").unwrap_or_else(|_| "/var/lib/alkane/fanmap.json".into()),
);
// Fan mapping is opt-in: it perturbs the machine and takes minutes, so a plain boot skips it.
let fans: u8 = std::env::var("ALKANE_FAN_FANS")
.ok()
.and_then(|v| v.parse().ok())
.unwrap_or(0);
let zones: u8 = std::env::var("ALKANE_FAN_ZONES")
.ok()
.and_then(|v| v.parse().ok())
.unwrap_or(0);
let settings = app::HalBoot {
config: &config,
sweep: alkane_os::fanmap::SweepConfig {
fans,
zones,
low_pwm: 40,
high_pwm: 100,
repeats: 1,
settle_ms: std::env::var("ALKANE_FAN_SETTLE_MS")
.ok()
.and_then(|v| v.parse().ok())
.unwrap_or(20_000),
},
thresholds: Default::default(),
map_path: &map_path,
};
let (mut runtime, _map) =
app::boot_from_hal(std::path::Path::new(&socket), &settings, &status)?;
println!(
"detected {} with {} active chains",
runtime.plan().profile,
runtime.active_chains().len()
);
let mut client = HalClient::connect(std::path::Path::new(&socket))?;
let label = app::target_label(&config.target);
for _ in 0..ticks {
let hottest = client.read_temperature_mc(0).ok();
let power_w = client.read_power_w().ok().map(f32::from);
let outcome = runtime.tick(&Tick {
power_w,
hashrate_ths: None,
hottest_mc: hottest,
ambient_mc: None,
dt_s: 1.0,
});
if let TickOutcome::Run(command) = outcome {
for chain in runtime.active_chains() {
client.set_chain_frequency(chain, command.frequency_mhz)?;
}
if let Some(pwm) = command.fan_pwm {
client.set_fan_target(0, pwm)?;
}
}
// Publish every period: a client watching the API must see the live operating point,
// not the boot-time snapshot.
status.set_hardware(app::snapshot(&runtime, &label));
service::publish(&bus, &status, &control);
if let Some(reason) = runtime.stop_reason() {
println!("stopped: {reason:?}");
break;
}
std::thread::sleep(Duration::from_millis(50));
}
status.set_hardware(app::snapshot(&runtime, &app::target_label(&config.target)));
println!(
"{}",
serde_json::to_string_pretty(&status.hardware_document())?
);
let _ = servers;
Ok(())
}
/// Where the UI listens. The miner serves it on port 80 of its own address;
/// if that is not permitted (a non-root development run), fall back to 8080
/// rather than refusing to start.
fn web_listen() -> Result<Option<std::net::SocketAddr>, Box<dyn std::error::Error>> {
if let Ok(bind) = std::env::var("ALKANE_WEB_LISTEN") {
return Ok(Some(bind.parse()?));
}
let port = if std::net::TcpListener::bind("0.0.0.0:80").is_ok() {
80
} else {
8080
};
Ok(Some(std::net::SocketAddr::from(([0, 0, 0, 0], port))))
}
/// Serve the full UI and API driven by the reference simulator HAL, in-process.
///
/// This is the "fully functional on a workstation" path: no hashboard is needed.
/// A reference HAL runs on a private unix socket, the runtime boots against it,
/// and a control loop applies the operator intent (mode/target, start/stop) from
/// the web UI every period, publishing a live snapshot. Open the printed URL and
/// the console shows frequency moving toward the target and the controls working.
fn serve_sim() -> Result<(), Box<dyn std::error::Error>> {
use alkane_os::hal_sim::{serve as sim_serve, SimConfig};
let socket = std::env::temp_dir().join(format!("alkane-serve-sim-{}.sock", std::process::id()));
let _ = std::fs::remove_file(&socket);
{
let socket = socket.clone();
std::thread::spawn(move || {
if let Err(error) = sim_serve(&socket, SimConfig::default()) {
eprintln!("reference HAL stopped: {error}");
}
});
}
// Wait for the HAL to bind its socket before the first connection.
for _ in 0..500 {
if socket.exists() {
break;
}
std::thread::sleep(Duration::from_millis(10));
}
let status = Arc::new(MiningStatus::new());
let initial = TuningTarget::PowerW(2_400.0);
// Start hashing immediately so the page is live; the operator can stop it.
let control = Arc::new(Control::new(initial, true));
let bus = Bus::new();
service::register(&bus, Arc::clone(&status), Arc::clone(&control));
let config = app::BootConfig {
profile_db_json: include_str!("../profiles.example.json").to_owned(),
chain_ports: vec![0, 1, 2],
sensor: SensorTopology::Pic,
budget: ProbeBudget::default(),
fan_zones: Vec::new(),
target: initial,
pid: PidConfig::default(),
ceiling_mc: 95_000,
fault_policy: Default::default(),
};
let map_path =
std::env::temp_dir().join(format!("alkane-serve-sim-{}.map.json", std::process::id()));
let settings = app::HalBoot {
config: &config,
sweep: alkane_os::fanmap::SweepConfig {
fans: 0,
zones: 0,
low_pwm: 40,
high_pwm: 100,
repeats: 1,
settle_ms: 0,
},
thresholds: Default::default(),
map_path: &map_path,
};
let (mut runtime, _map) = app::boot_from_hal(&socket, &settings, &status)?;
println!(
"detected {} with {} active chains",
runtime.plan().profile,
runtime.active_chains().len()
);
let api = std::env::var("ALKANE_API_LISTEN")
.ok()
.map(|bind| bind.parse())
.transpose()?
.or(Some("127.0.0.1:4028".parse()?));
let servers = app::start(Arc::clone(&status), api, web_listen()?, Arc::clone(&bus))?;
let (api_address, web_address) = servers.addresses();
if let Some(address) = api_address {
println!("management API on {address}");
}
if let Some(address) = web_address {
println!("web UI on http://{address}/");
}
// The control loop: its own HAL connection, applying operator intent.
let mut client = HalClient::connect(&socket)?;
let mut last_generation = 0_u64;
loop {
let generation = control.generation();
if generation != last_generation {
runtime.set_target(control.target());
last_generation = generation;
}
let label = app::target_label(&control.target());
if control.running() && runtime.stop_reason().is_none() {
status.set_running(true);
let hottest = client.read_temperature_mc(0).ok();
let power_w = client.read_power_w().ok().map(f32::from);
let outcome = runtime.tick(&Tick {
power_w,
hashrate_ths: None,
hottest_mc: hottest,
// The bench enclosure has no ambient sensor; assume 25 C so the
// ambient-target mode has something to track.
ambient_mc: Some(25_000),
dt_s: 1.0,
});
if let TickOutcome::Run(command) = outcome {
for chain in runtime.active_chains() {
let _ = client.set_chain_frequency(chain, command.frequency_mhz);
}
if let Some(pwm) = command.fan_pwm {
let _ = client.set_fan_target(0, pwm);
}
}
} else {
status.set_running(false);
}
status.set_hardware(app::snapshot(&runtime, &label));
service::publish(&bus, &status, &control);
std::thread::sleep(Duration::from_millis(250));
}
}
/// Serve the UI and the API without a mining backend. A board whose HAL
/// backend is not written yet still has to be reachable and observable; every
/// page says "not identified" rather than claiming hardware it cannot see.
fn serve_only() -> Result<(), Box<dyn std::error::Error>> {
let status = Arc::new(MiningStatus::new());
let api = std::env::var("ALKANE_API_LISTEN")
.ok()
.map(|bind| bind.parse())
.transpose()?;
// The cgminer-style API is loopback-only (reach it through SSH); default to
// loopback so `--serve` starts even when ALKANE_API_LISTEN is unset.
let api = api.or(Some("127.0.0.1:4028".parse()?));
let control = Arc::new(Control::default());
let bus = Bus::new();
service::register(&bus, Arc::clone(&status), Arc::clone(&control));
service::publish(&bus, &status, &control);
let servers = app::start(Arc::clone(&status), api, web_listen()?, Arc::clone(&bus))?;
let (api_address, web_address) = servers.addresses();
if let Some(address) = api_address {
println!("management API on {address}");
}
if let Some(address) = web_address {
println!("web UI on http://{address}");
}
loop {
std::thread::sleep(Duration::from_secs(3600));
}
}
fn main() {
let mut args = std::env::args().skip(1);
match args.next().as_deref() {
@@ -93,6 +488,96 @@ fn main() {
}
}
Some("--version") => println!("alkane-os {}", env!("CARGO_PKG_VERSION")),
Some("--serve") => {
if let Err(error) = serve_only() {
eprintln!("serve failed: {error}");
std::process::exit(1);
}
}
Some("--serve-sim") => {
if let Err(error) = serve_sim() {
eprintln!("serve-sim failed: {error}");
std::process::exit(1);
}
}
Some("--boot") => {
if let Err(error) = boot_hal(args) {
eprintln!("boot failed: {error}");
std::process::exit(1);
}
}
Some("--sim-hal") => {
let socket = match args.next() {
Some(path) => path,
None => {
eprintln!("usage: alkane-os --sim-hal SOCKET");
std::process::exit(2);
}
};
if let Err(error) = alkane_os::hal_sim::serve(
std::path::Path::new(&socket),
alkane_os::hal_sim::SimConfig::default(),
) {
eprintln!("reference HAL stopped: {error}");
std::process::exit(1);
}
}
Some("--check-profiles") => {
let path = match args.next() {
Some(path) => path,
None => {
eprintln!("usage: alkane-os --check-profiles PATH");
std::process::exit(2);
}
};
let text = match std::fs::read_to_string(&path) {
Ok(text) => text,
Err(error) => {
eprintln!("cannot read {path}: {error}");
std::process::exit(1);
}
};
match alkane_os::profiles::ProfileDb::from_json(&text) {
Ok(db) => {
println!("{} profiles, schema 1, validated", db.len());
}
Err(error) => {
eprintln!("profile database rejected: {error:?}");
std::process::exit(1);
}
}
}
Some("--check-hal") => {
let socket = match args.next() {
Some(path) => path,
None => {
eprintln!("usage: alkane-os --check-hal SOCKET");
std::process::exit(2);
}
};
let checks = alkane_os::hal_conformance::run(std::path::Path::new(&socket));
let mut failed = 0;
for check in &checks {
println!(
"{:<28} {:<4} {}",
check.name,
if check.passed { "PASS" } else { "FAIL" },
check.detail
);
if !check.passed {
failed += 1;
}
}
if failed > 0 {
std::process::exit(1);
}
}
Some("--self-check") => {
if let Err(error) = self_check() {
eprintln!("self-check failed: {error}");
std::process::exit(1);
}
}
Some("--mine-simulator") => {
if let Err(error) = sim_mine(args) {
eprintln!("simulator mining failed: {error}");
@@ -100,7 +585,10 @@ fn main() {
}
}
_ => {
eprintln!("usage: alkane-os --list-targets | --version | --mine-simulator HAL_SOCKET POOL_ADDRESS WORKER BM1362|BM1366 [MAX_ACCEPTS]");
eprintln!("usage: alkane-os --list-targets | --version | --self-check | --serve | --serve-sim | --boot HAL_SOCKET PROFILES.json TARGET [PIC|NOPIC] [TICKS] | --sim-hal SOCKET | --check-hal SOCKET | --check-profiles PATH | --mine-simulator HAL_SOCKET POOL_ADDRESS WORKER BM1362|BM1366 [MAX_ACCEPTS]");
eprintln!(
"env: ALKANE_API_LISTEN=ADDR ALKANE_WEB_LISTEN=ADDR ALKANE_POOL_PASSWORD=..."
);
std::process::exit(2);
}
}
+196
View File
@@ -1,23 +1,39 @@
// SPDX-License-Identifier: MIT
//! Bounded, read-only cgminer-style status for a local management client.
use crate::detect::{EepromState, HardwarePlan};
use serde_json::{json, Value};
use std::io::{self, Read, Write};
use std::net::{SocketAddr, TcpListener, TcpStream};
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::Arc;
use std::sync::Mutex;
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
const MAX_REQUEST_BYTES: usize = 2048;
const CLIENT_TIMEOUT: Duration = Duration::from_millis(500);
const REQUEST_DEADLINE: Duration = Duration::from_secs(2);
/// Everything the extended API exposes beyond share counters.
#[derive(Clone, Debug, PartialEq)]
pub struct HardwareSnapshot {
pub plan: HardwarePlan,
/// Chains the supervisor still allows work on.
pub active_chains: Vec<u8>,
/// `None` while hashing; otherwise why the machine stopped.
pub stopped: Option<&'static str>,
pub frequency_mhz: u16,
/// Operator target in the form `power:3000`, `hashrate:200`, `ambient:20000`, `fan:100`.
pub target: String,
}
#[derive(Debug)]
pub struct MiningStatus {
started: Instant,
running: AtomicBool,
accepted: AtomicU64,
rejected: AtomicU64,
hardware: Mutex<Option<HardwareSnapshot>>,
}
impl Default for MiningStatus {
@@ -33,9 +49,31 @@ impl MiningStatus {
running: AtomicBool::new(false),
accepted: AtomicU64::new(0),
rejected: AtomicU64::new(0),
hardware: Mutex::new(None),
}
}
/// Publish the current hardware view for the API.
pub fn set_hardware(&self, snapshot: HardwareSnapshot) {
if let Ok(mut slot) = self.hardware.lock() {
*slot = Some(snapshot);
}
}
/// The `hardware` document, for the on-box UI and local clients.
pub fn hardware_document(&self) -> Value {
hardware_json(self.hardware())
}
/// The `summary` document, for the on-box UI and local clients.
pub fn summary_document(&self) -> Value {
self.response("summary")
}
fn hardware(&self) -> Option<HardwareSnapshot> {
self.hardware.lock().ok().and_then(|slot| slot.clone())
}
pub fn set_running(&self, running: bool) {
self.running.store(running, Ordering::Relaxed);
}
@@ -72,6 +110,16 @@ impl MiningStatus {
"API": "1.0"
}]}),
),
"hardware" => (
"S",
"Hardware",
json!({"HARDWARE": [hardware_json(self.hardware())]}),
),
"stats" => (
"S",
"Stats",
json!({"STATS": [stats_json(self.hardware())]}),
),
_ => ("E", "Unknown command", json!({})),
};
let mut response = json!({"STATUS": [{
@@ -89,6 +137,69 @@ impl MiningStatus {
}
}
fn eeprom_json(state: &EepromState) -> Value {
match state {
EepromState::Present { model } => json!({"state": "present", "model": model}),
EepromState::Absent => json!({"state": "absent"}),
EepromState::Invalid => json!({"state": "invalid"}),
}
}
fn hardware_json(snapshot: Option<HardwareSnapshot>) -> Value {
let Some(snapshot) = snapshot else {
return json!({"available": false});
};
let plan = &snapshot.plan;
json!({
"available": true,
"profile": plan.profile,
"chip": plan.chip.name(),
"psu": plan.psu,
"envelope": {
"v_min_mv": plan.envelope.v_min_mv,
"v_max_mv": plan.envelope.v_max_mv,
"f_min_mhz": plan.envelope.f_min_mhz,
"f_max_mhz": plan.envelope.f_max_mhz,
},
"operating_point": {
"voltage_mv": plan.envelope.voltage_for(snapshot.frequency_mhz),
"frequency_mhz": snapshot.frequency_mhz,
"confirmed": plan.operating_point.confirmed,
},
"chains": plan.chains.iter().map(|chain| json!({
"index": chain.index,
"chip": chain.chip.name(),
"chips_found": chain.chips_found,
"eeprom": eeprom_json(&chain.eeprom),
"response_per_mille": chain.response_per_mille,
})).collect::<Vec<_>>(),
"fan_zones": plan.fan_zones.iter().map(|zone| json!({
"fan": zone.fan,
"zones": zone.zones,
})).collect::<Vec<_>>(),
"active_chains": snapshot.active_chains,
"stopped": snapshot.stopped,
"target": snapshot.target,
"frequency_mhz": snapshot.frequency_mhz,
})
}
fn stats_json(snapshot: Option<HardwareSnapshot>) -> Value {
let Some(snapshot) = snapshot else {
return json!({"available": false});
};
json!({
"Profile": snapshot.plan.profile,
"Chip": snapshot.plan.chip.name(),
"PSU": snapshot.plan.psu,
"FrequencyMHz": snapshot.frequency_mhz,
"VoltageMV": snapshot.plan.envelope.voltage_for(snapshot.frequency_mhz),
"Target": snapshot.target,
"ActiveChains": snapshot.active_chains.len(),
"Stopped": snapshot.stopped,
})
}
fn request_command(bytes: &[u8]) -> Option<&str> {
let request = std::str::from_utf8(bytes).ok()?.trim();
if request.starts_with('{') {
@@ -97,12 +208,16 @@ fn request_command(bytes: &[u8]) -> Option<&str> {
match command {
"summary" => Some("summary"),
"version" => Some("version"),
"hardware" => Some("hardware"),
"stats" => Some("stats"),
_ => Some("unknown"),
}
} else {
match request {
"summary" => Some("summary"),
"version" => Some("version"),
"hardware" => Some("hardware"),
"stats" => Some("stats"),
_ => Some("unknown"),
}
}
@@ -246,4 +361,85 @@ mod tests {
assert!(parsed.get("SUMMARY").is_some());
worker.join().unwrap();
}
fn snapshot() -> HardwareSnapshot {
HardwareSnapshot {
plan: HardwarePlan {
profile: "s19jpro-bm1362-pic".into(),
chip: crate::detect::ChipModel::Bm1362,
chains: vec![crate::detect::ChainReport {
index: 0,
chip: crate::detect::ChipModel::Bm1362,
chips_found: 126,
eeprom: EepromState::Absent,
response_per_mille: Some(950),
}],
envelope: crate::detect::Envelope {
v_min_mv: 1100,
v_max_mv: 1500,
f_min_mhz: 300,
f_max_mhz: 700,
},
operating_point: crate::detect::OperatingPoint {
voltage_mv: 1200,
frequency_mhz: 500,
confirmed: false,
},
psu: "APW12".into(),
fan_zones: vec![crate::detect::FanZone {
fan: 0,
zones: vec![0, 1],
}],
},
active_chains: vec![0],
stopped: None,
frequency_mhz: 512,
target: "power:3000".into(),
}
}
#[test]
fn hardware_is_unavailable_until_published() {
let status = MiningStatus::new();
let reply = status.response("hardware");
assert_eq!(reply["HARDWARE"][0]["available"], false);
}
#[test]
fn hardware_command_exposes_detection_and_fault_state() {
let status = MiningStatus::new();
status.set_hardware(snapshot());
let reply = status.response("hardware");
let hardware = &reply["HARDWARE"][0];
assert_eq!(hardware["available"], true);
assert_eq!(hardware["profile"], "s19jpro-bm1362-pic");
assert_eq!(hardware["chip"], "bm1362");
assert_eq!(hardware["psu"], "APW12");
assert_eq!(hardware["chains"][0]["chips_found"], 126);
assert_eq!(hardware["chains"][0]["eeprom"]["state"], "absent");
assert_eq!(hardware["operating_point"]["confirmed"], false);
assert_eq!(hardware["active_chains"][0], 0);
assert_eq!(hardware["target"], "power:3000");
assert_eq!(hardware["fan_zones"][0]["zones"][1], 1);
}
#[test]
fn stats_command_keeps_cgminer_shape() {
let status = MiningStatus::new();
status.set_hardware(snapshot());
let reply = status.response("stats");
let stats = &reply["STATS"][0];
assert_eq!(stats["Profile"], "s19jpro-bm1362-pic");
assert_eq!(stats["FrequencyMHz"], 512);
assert_eq!(stats["VoltageMV"], 1312);
assert_eq!(stats["ActiveChains"], 1);
assert!(stats["Stopped"].is_null());
}
#[test]
fn unknown_commands_still_refuse() {
let status = MiningStatus::new();
let reply = status.response("reboot");
assert_eq!(reply["STATUS"][0]["STATUS"], "E");
}
}
+236
View File
@@ -0,0 +1,236 @@
// SPDX-License-Identifier: MIT
//! Board profile database.
//!
//! Profiles carry the safe voltage/frequency envelope a chip/board combination may run inside.
//! Detection may only use what this database provides: if a combination is absent, the answer is
//! "refuse", never "assume a number". Entries are data, so they can be filled from captures
//! without touching code.
use crate::detect::{BoardProfile, ChipModel, Envelope, SensorTopology};
use serde_json::Value;
/// Why a profile database was rejected.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum ProfileError {
InvalidJson,
UnsupportedSchema,
MissingProfiles,
UnknownChip(String),
UnknownSensor(String),
InvalidEnvelope(String),
DuplicateName(String),
}
/// A validated set of profiles.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct ProfileDb {
profiles: Vec<BoardProfile>,
}
impl ProfileDb {
/// Validate and keep a set of profiles.
pub fn new(profiles: Vec<BoardProfile>) -> Result<Self, ProfileError> {
for (index, profile) in profiles.iter().enumerate() {
if profiles[..index]
.iter()
.any(|other| other.name == profile.name)
{
return Err(ProfileError::DuplicateName(profile.name.clone()));
}
if profile.chains == 0 {
return Err(ProfileError::InvalidEnvelope(profile.name.clone()));
}
let envelope = profile.envelope;
if envelope.v_min_mv == 0
|| envelope.v_min_mv > envelope.v_max_mv
|| envelope.f_min_mhz > envelope.f_max_mhz
{
return Err(ProfileError::InvalidEnvelope(profile.name.clone()));
}
}
Ok(Self { profiles })
}
/// Parse the schema-1 profile document.
pub fn from_json(text: &str) -> Result<Self, ProfileError> {
let root: Value = serde_json::from_str(text).map_err(|_| ProfileError::InvalidJson)?;
match root.get("schema").and_then(Value::as_u64) {
Some(1) => {}
Some(_) => return Err(ProfileError::UnsupportedSchema),
None => return Err(ProfileError::UnsupportedSchema),
}
let entries = root
.get("profiles")
.and_then(Value::as_array)
.ok_or(ProfileError::MissingProfiles)?;
let mut profiles = Vec::with_capacity(entries.len());
for entry in entries {
profiles.push(profile_from_value(entry)?);
}
if profiles.is_empty() {
return Err(ProfileError::MissingProfiles);
}
Self::new(profiles)
}
/// Exact lookup: a profile only applies to the chip, chain count and sensor wiring it declares.
pub fn find(
&self,
chip: ChipModel,
chains: u8,
sensor: SensorTopology,
) -> Option<&BoardProfile> {
self.profiles.iter().find(|profile| {
profile.chip == chip && profile.chains == chains && profile.sensor == sensor
})
}
pub fn len(&self) -> usize {
self.profiles.len()
}
pub fn is_empty(&self) -> bool {
self.profiles.is_empty()
}
}
fn profile_from_value(entry: &Value) -> Result<BoardProfile, ProfileError> {
let name = entry
.get("name")
.and_then(Value::as_str)
.ok_or(ProfileError::InvalidJson)?
.to_owned();
let chip_text = entry
.get("chip")
.and_then(Value::as_str)
.ok_or(ProfileError::UnknownChip(name.clone()))?;
let chip = match chip_text {
"bm1362" => ChipModel::Bm1362,
"bm1366" => ChipModel::Bm1366,
"bm1368" => ChipModel::Bm1368,
"bm1370" => ChipModel::Bm1370,
"bm1398" => ChipModel::Bm1398,
other => return Err(ProfileError::UnknownChip(other.to_owned())),
};
let sensor_text = entry
.get("sensor")
.and_then(Value::as_str)
.ok_or(ProfileError::UnknownSensor(name.clone()))?;
let sensor = match sensor_text {
"pic" => SensorTopology::Pic,
"nopic" => SensorTopology::NoPic,
"unknown" => SensorTopology::Unknown,
other => return Err(ProfileError::UnknownSensor(other.to_owned())),
};
let chains = entry
.get("chains")
.and_then(Value::as_u64)
.and_then(|value| u8::try_from(value).ok())
.ok_or(ProfileError::InvalidEnvelope(name.clone()))?;
let envelope = entry
.get("envelope")
.and_then(Value::as_object)
.ok_or(ProfileError::InvalidEnvelope(name.clone()))?;
let field = |key: &str| -> Result<u16, ProfileError> {
envelope
.get(key)
.and_then(Value::as_u64)
.and_then(|value| u16::try_from(value).ok())
.ok_or(ProfileError::InvalidEnvelope(name.clone()))
};
let envelope = Envelope {
v_min_mv: field("v_min_mv")?,
v_max_mv: field("v_max_mv")?,
f_min_mhz: field("f_min_mhz")?,
f_max_mhz: field("f_max_mhz")?,
};
Ok(BoardProfile {
name,
chip,
sensor,
chains,
envelope,
})
}
#[cfg(test)]
mod tests {
use super::*;
const VALID: &str = r#"{
"schema": 1,
"profiles": [
{
"name": "s19jpro-bm1362-pic",
"chip": "bm1362",
"sensor": "pic",
"chains": 3,
"envelope": {"v_min_mv": 1100, "v_max_mv": 1500, "f_min_mhz": 300, "f_max_mhz": 700}
}
]
}"#;
#[test]
fn valid_document_loads_and_resolves() {
let db = ProfileDb::from_json(VALID).expect("db");
assert_eq!(db.len(), 1);
let profile = db
.find(ChipModel::Bm1362, 3, SensorTopology::Pic)
.expect("profile");
assert_eq!(profile.name, "s19jpro-bm1362-pic");
assert_eq!(profile.envelope.v_max_mv, 1500);
assert!(db.find(ChipModel::Bm1362, 2, SensorTopology::Pic).is_none());
assert!(db
.find(ChipModel::Bm1362, 3, SensorTopology::NoPic)
.is_none());
}
#[test]
fn unknown_chip_is_rejected() {
let text = VALID.replace("bm1362", "bm9999");
assert_eq!(
ProfileDb::from_json(&text),
Err(ProfileError::UnknownChip("bm9999".into()))
);
}
#[test]
fn inverted_envelope_is_rejected() {
let text = VALID.replace(
"\"v_min_mv\": 1100, \"v_max_mv\": 1500",
"\"v_min_mv\": 1500, \"v_max_mv\": 1100",
);
assert!(matches!(
ProfileDb::from_json(&text),
Err(ProfileError::InvalidEnvelope(_))
));
}
#[test]
fn wrong_schema_is_rejected() {
let text = VALID.replace("\"schema\": 1", "\"schema\": 2");
assert_eq!(
ProfileDb::from_json(&text),
Err(ProfileError::UnsupportedSchema)
);
}
#[test]
fn missing_profiles_are_rejected() {
assert_eq!(
ProfileDb::from_json("{\"schema\": 1}"),
Err(ProfileError::MissingProfiles)
);
}
#[test]
fn duplicate_names_are_rejected() {
let one = VALID.split("\"profiles\": [").nth(1).unwrap();
let entry = one.trim().trim_end_matches("]\n }").trim();
let duplicated = format!("{{\"schema\": 1, \"profiles\": [{entry}, {entry}]}}");
assert!(matches!(
ProfileDb::from_json(&duplicated),
Err(ProfileError::DuplicateName(_))
));
}
}
+93
View File
@@ -0,0 +1,93 @@
// SPDX-License-Identifier: MIT
//! The bus registry: the single source of truth for every topic and verb.
//!
//! wardenOS keeps this as `bus/registry/topics.json` and generates the broker
//! ACL, the constants and the retain rules from it with `busgen`. alkane-os is
//! std-only and in-process, so the registry lives here as typed constants plus a
//! machine-readable description ([`contract`]). A test asserts that every verb a
//! service registers and every state topic it publishes appears here, so the
//! contract cannot drift from the code - the property `busgen` gives warden.
use serde_json::{json, Value};
/// Retained state topics (read with `Bus::read_state`).
pub mod topics {
/// Full hardware/runtime snapshot (profile, chip, PSU, chains, operating point).
pub const HARDWARE: &str = "miner/state/hardware";
/// cgminer-style summary (elapsed, accepted, rejected, mining/stopped).
pub const SUMMARY: &str = "miner/state/summary";
/// Operator control state (running, mode, target, generation).
pub const CONTROL: &str = "miner/state/control";
}
/// Event topics (emitted with `Bus::emit`, tailed from the ring).
pub mod events {
/// A human-facing notice (fault, state change) for the alerts view.
pub const NOTICE: &str = "miner/evt/notice";
}
/// Command verbs (dispatched with `Bus::request`). Each is owned by one service.
pub mod verbs {
/// Start hashing (operator). Body: `{}`.
pub const CONTROL_START: &str = "control/start";
/// Stop hashing (operator). Body: `{}`.
pub const CONTROL_STOP: &str = "control/stop";
/// Switch the live MPC target. Body: `{ "mode": "power|ambient|hashrate|fan", "value": <f32> }`.
pub const CONTROL_SET_TARGET: &str = "control/set_target";
/// Apply a settings form (persist + drive the runtime). Body: `{ "form": "<urlencoded>" }`.
pub const SETTINGS_APPLY: &str = "settings/apply";
/// Load a dashboard deck. Body: `{ "deck": "<name>" }` -> the deck document.
pub const DASHBOARD_LOAD: &str = "dashboard/load";
/// Save a dashboard deck. Body: `{ "deck": "<name>", "doc": <deck> }`.
pub const DASHBOARD_SAVE: &str = "dashboard/save";
/// Reset a dashboard deck to the compiled default. Body: `{ "deck": "<name>" }`.
pub const DASHBOARD_RESET: &str = "dashboard/reset";
}
/// The declared contract: every verb and state topic the miner service owns.
/// The parity test checks the live bus against this, so a new verb that is not
/// listed here, or a listed verb no service registers, fails CI.
pub fn contract() -> Value {
json!({
"state": [topics::HARDWARE, topics::SUMMARY, topics::CONTROL],
"events": [events::NOTICE],
"verbs": [
verbs::CONTROL_START,
verbs::CONTROL_STOP,
verbs::CONTROL_SET_TARGET,
verbs::SETTINGS_APPLY,
verbs::DASHBOARD_LOAD,
verbs::DASHBOARD_SAVE,
verbs::DASHBOARD_RESET,
],
})
}
/// The verbs in the contract, as a sorted list.
pub fn contract_verbs() -> Vec<String> {
let mut v: Vec<String> = contract()["verbs"]
.as_array()
.map(|a| {
a.iter()
.filter_map(|x| x.as_str().map(str::to_string))
.collect()
})
.unwrap_or_default();
v.sort();
v
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_contract_lists_distinct_verbs_and_topics() {
let verbs = contract_verbs();
let mut unique = verbs.clone();
unique.dedup();
assert_eq!(verbs, unique, "duplicate verb in the contract");
assert!(verbs.contains(&verbs::CONTROL_SET_TARGET.to_string()));
assert_eq!(contract()["state"].as_array().unwrap().len(), 3);
}
}
+329
View File
@@ -0,0 +1,329 @@
// SPDX-License-Identifier: MIT
//! Mining runtime: one state machine over the detection plan, the fault ladder and the tuner.
//!
//! Each tick takes a measurement, lets the tuner move the operating point, and lets the fault
//! supervisor veto the machine. The pieces are tested in isolation elsewhere; this module is the
//! place where their order is decided, and the order matters: a stopped machine must not be tuned,
//! and a disabled chain must not be dispatched to.
use crate::detect::{HardwarePlan, OperatingPoint};
use crate::fault::{FaultAction, FaultEvent, FaultPolicy, FaultSupervisor, StopReason};
use crate::tuning::{Command, Observation, PidConfig, TuningError, TuningLoop, TuningTarget};
/// One control period's measurements.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Tick {
pub power_w: Option<f32>,
pub hashrate_ths: Option<f32>,
pub hottest_mc: Option<i32>,
pub ambient_mc: Option<i32>,
pub dt_s: f32,
}
/// What the runtime decided for this period.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum TickOutcome {
/// Apply this command to the hardware.
Run(Command),
/// Measurement missing; hold the previous operating point.
Hold(Command),
/// The machine is stopped and must not hash.
Stopped(StopReason),
}
/// Runtime state for one machine.
#[derive(Clone, Debug)]
pub struct MinerRuntime {
plan: HardwarePlan,
faults: FaultSupervisor,
tuning: TuningLoop,
last_command: Command,
}
impl MinerRuntime {
pub fn new(
plan: HardwarePlan,
policy: FaultPolicy,
target: TuningTarget,
pid: PidConfig,
ceiling_mc: i32,
) -> Self {
let chains: Vec<u8> = plan.chains.iter().map(|chain| chain.index).collect();
let last_command = Command {
frequency_mhz: plan.operating_point.frequency_mhz,
fan_pwm: None,
};
Self {
faults: FaultSupervisor::new(&chains, policy),
tuning: TuningLoop::new(target, plan.envelope, pid, ceiling_mc),
plan,
last_command,
}
}
pub fn plan(&self) -> &HardwarePlan {
&self.plan
}
pub fn operating_point(&self) -> OperatingPoint {
OperatingPoint {
voltage_mv: self
.plan
.envelope
.voltage_for(self.last_command.frequency_mhz),
frequency_mhz: self.last_command.frequency_mhz,
confirmed: self.plan.operating_point.confirmed,
}
}
pub fn active_chains(&self) -> Vec<u8> {
self.faults.active_chains()
}
/// The operator target currently in force.
pub fn target(&self) -> TuningTarget {
self.tuning.target()
}
/// Switch the operator target (one of the MPC modes) without a restart. The
/// PID state carries over, so the operating point moves from where it is
/// rather than snapping back to the envelope floor.
pub fn set_target(&mut self, target: TuningTarget) {
self.tuning.set_target(target);
}
pub fn stop_reason(&self) -> Option<StopReason> {
self.faults.stop_reason()
}
/// Feed one health observation; returns what the supervisor decided.
pub fn on_event(&mut self, event: FaultEvent) -> FaultAction {
self.faults.observe(event)
}
/// Advance one control period.
pub fn tick(&mut self, tick: &Tick) -> TickOutcome {
if let Some(reason) = self.faults.stop_reason() {
return TickOutcome::Stopped(reason);
}
let observation = Observation {
power_w: tick.power_w,
hashrate_ths: tick.hashrate_ths,
hottest_mc: tick.hottest_mc,
ambient_mc: tick.ambient_mc,
};
match self.tuning.step(observation, tick.dt_s) {
Ok(command) => {
self.last_command = command;
TickOutcome::Run(command)
}
Err(TuningError::NoMeasurement) => TickOutcome::Hold(self.last_command),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::detect::{ChainReport, ChipModel, EepromState, Envelope, FanZone};
fn plan() -> HardwarePlan {
HardwarePlan {
profile: "s19jpro-bm1362-pic".into(),
chip: ChipModel::Bm1362,
chains: (0..3)
.map(|index| ChainReport {
index,
chip: ChipModel::Bm1362,
chips_found: 126,
eeprom: EepromState::Absent,
response_per_mille: Some(950),
})
.collect(),
envelope: Envelope {
v_min_mv: 1100,
v_max_mv: 1500,
f_min_mhz: 300,
f_max_mhz: 700,
},
operating_point: OperatingPoint {
voltage_mv: 1200,
frequency_mhz: 300,
confirmed: false,
},
psu: "APW12".into(),
fan_zones: vec![FanZone {
fan: 0,
zones: vec![0],
}],
}
}
fn runtime() -> MinerRuntime {
MinerRuntime::new(
plan(),
FaultPolicy::default(),
TuningTarget::PowerW(2_400.0),
PidConfig {
kp: 0.2,
ki: 0.05,
kd: 0.0,
out_min: 0.0,
out_max: 0.0,
max_step_per_s: 50.0,
deadband: 0.0,
},
95_000,
)
}
fn tick(power: f32) -> Tick {
Tick {
power_w: Some(power),
hashrate_ths: None,
hottest_mc: Some(70_000),
ambient_mc: None,
dt_s: 1.0,
}
}
#[test]
fn a_fresh_runtime_exposes_every_chain() {
assert_eq!(runtime().active_chains(), vec![0, 1, 2]);
assert_eq!(runtime().stop_reason(), None);
}
#[test]
fn ticks_move_frequency_inside_the_envelope() {
let mut runtime = runtime();
let mut frequency = 300;
for _ in 0..60 {
let power = 4.0 * f32::from(frequency);
if let TickOutcome::Run(command) = runtime.tick(&tick(power)) {
frequency = command.frequency_mhz;
assert!((300..=700).contains(&frequency));
}
}
assert!(frequency > 300, "frequency never moved: {frequency}");
}
#[test]
fn a_missing_measurement_holds_the_last_command() {
let mut runtime = runtime();
let empty = Tick {
power_w: None,
hashrate_ths: None,
hottest_mc: None,
ambient_mc: None,
dt_s: 1.0,
};
match runtime.tick(&empty) {
TickOutcome::Hold(command) => assert_eq!(command.frequency_mhz, 300),
other => panic!("unexpected outcome: {other:?}"),
}
}
#[test]
fn a_dead_chain_is_removed_from_dispatch_without_stopping_the_machine() {
let mut runtime = runtime();
assert_eq!(
runtime.on_event(FaultEvent::ChainError { chain: 1 }),
FaultAction::Retry { chain: 1 }
);
assert_eq!(
runtime.on_event(FaultEvent::ChainError { chain: 1 }),
FaultAction::Retry { chain: 1 }
);
assert_eq!(
runtime.on_event(FaultEvent::ChainError { chain: 1 }),
FaultAction::DisableChain { chain: 1 }
);
assert_eq!(runtime.active_chains(), vec![0, 2]);
assert!(matches!(runtime.tick(&tick(2_000.0)), TickOutcome::Run(_)));
}
#[test]
fn a_temperature_fault_stops_the_machine_for_good() {
let mut runtime = runtime();
assert_eq!(
runtime.on_event(FaultEvent::TemperatureFault { zone: 1 }),
FaultAction::Stop {
reason: StopReason::Temperature
}
);
assert_eq!(
runtime.tick(&tick(2_400.0)),
TickOutcome::Stopped(StopReason::Temperature)
);
assert_eq!(
runtime.tick(&tick(2_400.0)),
TickOutcome::Stopped(StopReason::Temperature)
);
}
#[test]
fn losing_every_chain_stops_the_machine() {
let mut runtime = MinerRuntime::new(
plan(),
FaultPolicy {
retries: 0,
..FaultPolicy::default()
},
TuningTarget::PowerW(2_400.0),
PidConfig::default(),
95_000,
);
for chain in 0..3 {
runtime.on_event(FaultEvent::ChainError { chain });
}
assert_eq!(runtime.stop_reason(), Some(StopReason::NoChainsLeft));
assert!(runtime.active_chains().is_empty());
}
#[test]
fn switching_target_keeps_the_operating_point_and_takes_effect() {
let mut runtime = runtime();
// Climb under a power target so the frequency leaves the floor.
for _ in 0..30 {
let power = 4.0 * f32::from(runtime.operating_point().frequency_mhz);
runtime.tick(&tick(power));
}
let climbed = runtime.operating_point().frequency_mhz;
assert!(climbed > 300, "frequency never left the floor: {climbed}");
assert!(matches!(runtime.target(), TuningTarget::PowerW(_)));
// Switch to an ambient target in place: the target changes and the
// operating point carries over (no snap back to the floor).
runtime.set_target(TuningTarget::AmbientC { margin_mc: 20_000 });
assert!(matches!(
runtime.target(),
TuningTarget::AmbientC { margin_mc: 20_000 }
));
assert_eq!(runtime.operating_point().frequency_mhz, climbed);
// The ambient target now drives: feed ambient + hottest and it still runs.
let outcome = runtime.tick(&Tick {
power_w: None,
hashrate_ths: None,
hottest_mc: Some(60_000),
ambient_mc: Some(40_000),
dt_s: 1.0,
});
assert!(matches!(outcome, TickOutcome::Run(_)));
}
#[test]
fn the_operating_point_reflects_the_last_command() {
let mut runtime = runtime();
for _ in 0..10 {
runtime.tick(&tick(1_500.0));
}
let point = runtime.operating_point();
assert!(point.frequency_mhz > 300);
assert!(!point.confirmed);
// Voltage follows the frequency across the envelope instead of staying at the boot value.
assert_eq!(
point.voltage_mv,
runtime.plan().envelope.voltage_for(point.frequency_mhz)
);
assert!(point.voltage_mv > 1100);
}
}
+307
View File
@@ -0,0 +1,307 @@
// SPDX-License-Identifier: MIT
//! The miner service: the one owner of the control verbs, the settings/dashboard
//! verbs, and the published state topics.
//!
//! Every surface - the HTTP API, the web console, a future remote/flare client -
//! reaches the machine only by a `Bus::request` to a verb registered here, or by
//! reading a state topic published here. There is no second write path, which is
//! the wardenOS property: one dispatch shared by all surfaces.
use serde_json::{json, Value};
use std::fs;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use crate::bus::{Bus, BusError};
use crate::control::{self, Control, ControlMode};
use crate::management::MiningStatus;
use crate::registry::{topics, verbs};
use crate::ui;
const DECK_DIR: &str = "/var/lib/alkane/decks";
/// Where the dashboard keeps operator settings (the schema rows).
pub(crate) fn settings_path() -> PathBuf {
let etc = Path::new("/etc/alkane/settings.json");
if etc.exists() || Path::new("/etc/alkane").is_dir() {
return etc.to_path_buf();
}
// A read-only root or a test run: keep the file beside the binary.
std::env::temp_dir().join("alkane-settings.json")
}
/// The deck directory: the on-box `/var/lib/alkane/decks` when it exists or can
/// be created (root on the miner), else a writable fallback for a dev run.
fn deck_dir() -> PathBuf {
let dir = Path::new(DECK_DIR);
if dir.is_dir() || fs::create_dir_all(dir).is_ok() {
return dir.to_path_buf();
}
std::env::temp_dir().join("alkane-decks")
}
fn deck_path(deck: &str) -> PathBuf {
let safe: String = deck
.chars()
.filter(|c| c.is_ascii_alphanumeric() || *c == '-' || *c == '_')
.collect();
deck_dir().join(format!("{safe}.json"))
}
pub(crate) fn load_deck(deck: &str) -> Value {
fs::read_to_string(deck_path(deck))
.ok()
.and_then(|text| ui::validate_deck(&text).ok())
.unwrap_or_else(|| ui::default_deck(deck))
}
fn save_deck(deck: &str, doc: &Value) -> Result<(), String> {
let path = deck_path(deck);
if let Some(parent) = path.parent() {
fs::create_dir_all(parent)
.map_err(|e| format!("cannot create {}: {e}", parent.display()))?;
}
let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?;
// Atomic replace: a concurrent read never sees a half-written deck.
let tmp = path.with_extension("json.tmp");
fs::write(&tmp, text).map_err(|e| format!("cannot write {}: {e}", tmp.display()))?;
fs::rename(&tmp, &path).map_err(|e| format!("cannot replace {}: {e}", path.display()))
}
/// Translate a settings form's tuning fields into the live control target.
fn apply_tuning(body: &str, control: &Control) {
let Some(mode) = crate::form::field(body, "tuning.mode") else {
return;
};
let (mode, value_field) = match mode.as_str() {
"power" => ("power", "tuning.power_w"),
"hashrate" => ("hashrate", "tuning.hashrate_ths"),
"ambient" => ("ambient", "tuning.ambient_margin_c"),
"max-fan" => ("fan", "tuning.max_fan_pwm"),
_ => return,
};
if let Some(value) =
crate::form::field(body, value_field).and_then(|v| v.trim().parse::<f32>().ok())
{
let _ = control.set_mode_value(mode, value);
}
}
/// The owner of the control state: it mutates [`Control`] and, like a wardenOS
/// service, republishes the affected state the instant a command applies, so a
/// reader never sees a command lag behind the periodic telemetry publish. The
/// bus is held `Weak` to avoid an `Arc` cycle (the bus owns the handlers).
struct MinerService {
status: Arc<MiningStatus>,
control: Arc<Control>,
bus: std::sync::Weak<Bus>,
}
impl MinerService {
fn republish_control(&self) {
if let Some(bus) = self.bus.upgrade() {
bus.publish_state(
topics::CONTROL,
control_document(&self.status, &self.control),
);
}
}
}
/// Register every miner verb on the bus. Called once at start-up.
pub fn register(bus: &Arc<Bus>, status: Arc<MiningStatus>, control: Arc<Control>) {
let svc = Arc::new(MinerService {
status,
control,
bus: Arc::downgrade(bus),
});
{
let s = Arc::clone(&svc);
bus.register(verbs::CONTROL_START, move |_| {
s.control.set_running(true);
s.republish_control();
Ok(json!({ "running": true }))
});
}
{
let s = Arc::clone(&svc);
bus.register(verbs::CONTROL_STOP, move |_| {
s.control.set_running(false);
s.republish_control();
Ok(json!({ "running": false }))
});
}
{
let s = Arc::clone(&svc);
bus.register(verbs::CONTROL_SET_TARGET, move |body| {
let mode = body
.get("mode")
.and_then(Value::as_str)
.ok_or_else(|| BusError::BadRequest("mode is required".into()))?;
let value = body
.get("value")
.and_then(Value::as_f64)
.ok_or_else(|| BusError::BadRequest("value is required".into()))?
as f32;
s.control
.set_mode_value(mode, value)
.map_err(BusError::Rejected)?;
s.republish_control();
Ok(json!({
"target": control::target_label(s.control.target()),
"mode": ControlMode::of_target(s.control.target()).as_str(),
}))
});
}
{
// A settings form: persist the validated rows, then drive the runtime
// from the tuning fields. Body carries the raw urlencoded form.
let s = Arc::clone(&svc);
bus.register(verbs::SETTINGS_APPLY, move |body| {
let form = body
.get("form")
.and_then(Value::as_str)
.ok_or_else(|| BusError::BadRequest("form is required".into()))?;
let mut dash = crate::dashboard::Dashboard::load(settings_path());
dash.submit(form).map_err(|failures| {
let mut msg = String::new();
for (k, why) in failures {
msg.push_str(&format!("{k}: {why}; "));
}
BusError::Rejected(msg.trim_end().to_string())
})?;
apply_tuning(form, &s.control);
s.republish_control();
Ok(json!({ "applied": true }))
});
}
bus.register(verbs::DASHBOARD_LOAD, |body| {
let deck = body
.get("deck")
.and_then(Value::as_str)
.unwrap_or("dashboard");
Ok(load_deck(deck))
});
bus.register(verbs::DASHBOARD_SAVE, |body| {
let deck = body
.get("deck")
.and_then(Value::as_str)
.unwrap_or("dashboard");
let doc = body
.get("doc")
.ok_or_else(|| BusError::BadRequest("doc is required".into()))?;
let validated = ui::validate_deck(&doc.to_string()).map_err(BusError::Rejected)?;
save_deck(deck, &validated).map_err(BusError::Rejected)?;
Ok(validated)
});
bus.register(verbs::DASHBOARD_RESET, |body| {
let deck = body
.get("deck")
.and_then(Value::as_str)
.unwrap_or("dashboard");
let doc = ui::default_deck(deck);
save_deck(deck, &doc).map_err(BusError::Rejected)?;
Ok(doc)
});
}
/// Publish the current miner state onto the bus. Called each control period and
/// once at start-up. These documents are exactly what the API and UI read back.
pub fn publish(bus: &Bus, status: &MiningStatus, control: &Control) {
bus.publish_state(topics::HARDWARE, status.hardware_document());
bus.publish_state(topics::SUMMARY, status.summary_document());
bus.publish_state(topics::CONTROL, control_document(status, control));
}
/// The operator control document (also the `/api/control` body).
pub fn control_document(status: &MiningStatus, control: &Control) -> Value {
let hw = status.hardware_document();
let mode = ControlMode::of_target(control.target());
json!({
"running": control.running(),
"mode": mode.as_str(),
"mode_label": mode.label(),
"target": control::target_label(control.target()),
"generation": control.generation(),
"stopped": hw.get("stopped").cloned().unwrap_or(Value::Null),
"frequency_mhz": hw.get("frequency_mhz").cloned().unwrap_or(Value::Null),
"available": hw.get("available").cloned().unwrap_or(Value::Bool(false)),
})
}
#[cfg(test)]
mod tests {
use super::*;
use crate::registry;
#[test]
fn registered_verbs_match_the_contract() {
let bus = Bus::new();
register(
&bus,
Arc::new(MiningStatus::new()),
Arc::new(Control::default()),
);
let mut registered = bus.verbs();
registered.sort();
// Every registered verb is declared in the contract (nothing undocumented),
// and every contract verb is actually registered (nothing missing).
assert_eq!(registered, registry::contract_verbs());
}
#[test]
fn published_state_topics_match_the_contract() {
let bus = Bus::new();
publish(&bus, &MiningStatus::new(), &Control::default());
let mut published = bus.state_topics();
published.sort();
let mut declared: Vec<String> = registry::contract()["state"]
.as_array()
.unwrap()
.iter()
.map(|v| v.as_str().unwrap().to_string())
.collect();
declared.sort();
assert_eq!(
published, declared,
"published state topics must match the contract"
);
}
#[test]
fn control_verbs_drive_the_shared_control() {
let bus = Bus::new();
let control = Arc::new(Control::default());
register(&bus, Arc::new(MiningStatus::new()), Arc::clone(&control));
bus.request(verbs::CONTROL_START, &json!({})).unwrap();
assert!(control.running());
bus.request(verbs::CONTROL_STOP, &json!({})).unwrap();
assert!(!control.running());
bus.request(
verbs::CONTROL_SET_TARGET,
&json!({"mode": "ambient", "value": 18.0}),
)
.unwrap();
assert_eq!(
control.target(),
crate::tuning::TuningTarget::AmbientC { margin_mc: 18_000 }
);
}
#[test]
fn set_target_rejects_a_bad_mode() {
let bus = Bus::new();
register(
&bus,
Arc::new(MiningStatus::new()),
Arc::new(Control::default()),
);
let err = bus
.request(
verbs::CONTROL_SET_TARGET,
&json!({"mode": "bogus", "value": 1.0}),
)
.unwrap_err();
assert_eq!(err.code(), "E_REJECTED");
}
}
+172
View File
@@ -0,0 +1,172 @@
// SPDX-License-Identifier: MIT
//! Hashrate splitting across pools.
//!
//! Splitting is per work slot: each dispatched job comes from exactly one pool, and the router
//! hands out slots in proportion to the configured weights. Smooth weighted round-robin is used
//! because it keeps the mix correct at every prefix, not just over a long run, which matters when
//! a miner only has a handful of chains.
/// Why a split configuration was rejected.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum SplitError {
Empty,
NoWeight,
InvalidNumber,
TooManyPools,
}
/// Per-pool weights, `50,50` style.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SplitWeights {
weights: Vec<u32>,
}
impl SplitWeights {
/// Parse a comma-separated weight list such as `"60,40"`.
pub fn parse(text: &str) -> Result<Self, SplitError> {
let mut weights = Vec::new();
for part in text.split(',') {
let trimmed = part.trim();
if trimmed.is_empty() {
return Err(SplitError::InvalidNumber);
}
let weight: u32 = trimmed.parse().map_err(|_| SplitError::InvalidNumber)?;
weights.push(weight);
}
Self::new(weights)
}
pub fn new(weights: Vec<u32>) -> Result<Self, SplitError> {
if weights.is_empty() {
return Err(SplitError::Empty);
}
if weights.len() > 16 {
return Err(SplitError::TooManyPools);
}
if weights.iter().all(|weight| *weight == 0) {
return Err(SplitError::NoWeight);
}
Ok(Self { weights })
}
pub fn pools(&self) -> usize {
self.weights.len()
}
pub fn weight(&self, pool: usize) -> u32 {
self.weights.get(pool).copied().unwrap_or(0)
}
/// Split `slots` work slots across the pools and return how many each receives.
pub fn allocate(&self, slots: usize) -> Vec<usize> {
let mut router = WorkRouter::new(self.clone());
let mut counts = vec![0_usize; self.pools()];
for _ in 0..slots {
counts[router.next_pool()] += 1;
}
counts
}
}
/// Smooth weighted round-robin state.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct WorkRouter {
weights: SplitWeights,
current: Vec<i64>,
total: i64,
}
impl WorkRouter {
pub fn new(weights: SplitWeights) -> Self {
let current = vec![0_i64; weights.pools()];
let total: i64 = weights
.weights
.iter()
.map(|weight| i64::from(*weight))
.sum();
Self {
weights,
current,
total,
}
}
/// Which pool supplies the next work slot.
///
/// A pool with weight 0 never receives a slot. The winner's running score is reduced by the
/// total weight, which is what keeps the distribution proportional at every prefix.
pub fn next_pool(&mut self) -> usize {
let mut winner = 0;
for pool in 0..self.weights.pools() {
self.current[pool] += i64::from(self.weights.weight(pool));
if self.current[pool] > self.current[winner] {
winner = pool;
}
}
self.current[winner] -= self.total;
winner
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn equal_weights_split_evenly() {
let weights = SplitWeights::parse("50,50").expect("weights");
assert_eq!(weights.allocate(10), vec![5, 5]);
assert_eq!(weights.allocate(4), vec![2, 2]);
}
#[test]
fn unequal_weights_split_proportionally() {
let weights = SplitWeights::parse("1,2").expect("weights");
assert_eq!(weights.allocate(9), vec![3, 6]);
assert_eq!(weights.allocate(3), vec![1, 2]);
}
#[test]
fn rounding_is_exact_at_every_prefix() {
let weights = SplitWeights::parse("1,1,1").expect("weights");
assert_eq!(weights.allocate(10), vec![4, 3, 3]);
assert_eq!(weights.allocate(3), vec![1, 1, 1]);
assert_eq!(weights.allocate(1), vec![1, 0, 0]);
}
#[test]
fn zero_weight_pools_never_receive_work() {
let weights = SplitWeights::parse("100,0,100").expect("weights");
assert_eq!(weights.allocate(6), vec![3, 0, 3]);
}
#[test]
fn a_single_pool_takes_everything() {
let weights = SplitWeights::parse("100").expect("weights");
assert_eq!(weights.allocate(5), vec![5]);
}
#[test]
fn malformed_configurations_are_rejected() {
assert_eq!(SplitWeights::parse(""), Err(SplitError::InvalidNumber));
assert_eq!(
SplitWeights::parse("50,abc"),
Err(SplitError::InvalidNumber)
);
assert_eq!(SplitWeights::parse("0,0"), Err(SplitError::NoWeight));
assert_eq!(SplitWeights::new(Vec::new()), Err(SplitError::Empty));
let many = vec![1_u32; 17];
assert_eq!(SplitWeights::new(many), Err(SplitError::TooManyPools));
}
#[test]
fn the_router_is_deterministic_for_the_same_input() {
let weights = SplitWeights::parse("60,40").expect("weights");
let first = weights.allocate(50);
let second = weights.allocate(50);
assert_eq!(first, second);
assert_eq!(first.iter().sum::<usize>(), 50);
assert_eq!(first[0], 30);
assert_eq!(first[1], 20);
}
}
+385
View File
@@ -0,0 +1,385 @@
// SPDX-License-Identifier: MIT
//! Stratum V2 transport and version selection.
//!
//! `TcpLink` turns a TCP stream into the framed messages the session expects: it buffers partial
//! reads and hands out one frame at a time, so a frame split across packets is not a protocol
//! error. The selection policy decides when a miner may fall back to Stratum V1.
use crate::stratum_v2::{Frame, V2Error};
use crate::stratum_v2_session::V2Link;
use std::io::{self, Read, Write};
use std::net::{SocketAddr, TcpStream};
use std::time::Duration;
const READ_CHUNK: usize = 4096;
/// A framed connection over TCP.
pub struct TcpLink {
stream: TcpStream,
buffer: Vec<u8>,
}
impl TcpLink {
pub fn connect(address: SocketAddr, timeout: Duration) -> io::Result<Self> {
let stream = TcpStream::connect_timeout(&address, timeout)?;
stream.set_read_timeout(Some(timeout))?;
stream.set_write_timeout(Some(timeout))?;
stream.set_nodelay(true)?;
Ok(Self {
stream,
buffer: Vec::new(),
})
}
pub fn from_stream(stream: TcpStream) -> io::Result<Self> {
stream.set_nodelay(true)?;
Ok(Self {
stream,
buffer: Vec::new(),
})
}
/// Bytes received but not yet consumed, for diagnostics.
pub fn buffered(&self) -> usize {
self.buffer.len()
}
}
impl V2Link for TcpLink {
type Error = io::Error;
fn send(&mut self, frame: &Frame) -> io::Result<()> {
let mut wire = Vec::with_capacity(frame.payload.len() + 6);
frame.encode(&mut wire);
self.stream.write_all(&wire)?;
self.stream.flush()
}
fn recv(&mut self) -> io::Result<Frame> {
loop {
if !self.buffer.is_empty() {
match Frame::decode(&self.buffer) {
Ok((frame, consumed)) => {
self.buffer.drain(..consumed);
return Ok(frame);
}
Err(V2Error::Truncated) => {}
Err(error) => {
self.buffer.clear();
return Err(io::Error::new(io::ErrorKind::InvalidData, error));
}
}
}
let mut chunk = [0_u8; READ_CHUNK];
let count = self.stream.read(&mut chunk)?;
if count == 0 {
return Err(io::Error::new(
io::ErrorKind::UnexpectedEof,
"stratum v2 stream closed",
));
}
self.buffer.extend_from_slice(&chunk[..count]);
}
}
}
/// Which protocol the miner speaks.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum StratumVersion {
V1,
V2,
}
/// Why an attempt failed.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum FailureKind {
/// The server refused the connection or the setup message.
Refused,
/// No mutually supported version.
Unsupported,
/// The connection could not be established or dropped.
Transport,
/// The server did not answer in time.
Timeout,
}
/// Operator preference.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Preference {
pub primary: StratumVersion,
pub allow_v1_fallback: bool,
}
impl Default for Preference {
fn default() -> Self {
Self {
primary: StratumVersion::V2,
allow_v1_fallback: true,
}
}
}
/// The protocol to try next, or `None` when there is nothing left.
///
/// V1 is attempted only when the operator allowed it and the failure is not a transport-level
/// problem: a dead route or a dropped stream will fail identically on V1, so falling back would
/// only delay the operator-visible error.
pub fn fallback(
preference: Preference,
failed: StratumVersion,
kind: FailureKind,
) -> Option<StratumVersion> {
match (preference.primary, failed) {
(StratumVersion::V2, StratumVersion::V2)
if preference.allow_v1_fallback && kind != FailureKind::Transport =>
{
Some(StratumVersion::V1)
}
_ => None,
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::net::TcpListener;
#[test]
fn a_frame_arrives_intact_over_tcp() {
let listener = TcpListener::bind("127.0.0.1:0").expect("bind");
let address = listener.local_addr().expect("addr");
let server = std::thread::spawn(move || {
let (mut stream, _) = listener.accept().expect("accept");
let mut wire = Vec::new();
Frame::new(0x00, vec![1, 2, 3, 4]).encode(&mut wire);
stream.write_all(&wire).expect("write");
});
let mut link = TcpLink::connect(address, Duration::from_secs(2)).expect("connect");
let frame = link.recv().expect("recv");
assert_eq!(frame.msg_type, 0x00);
assert_eq!(frame.payload, vec![1, 2, 3, 4]);
server.join().expect("join");
}
#[test]
fn a_frame_split_across_reads_is_reassembled() {
let listener = TcpListener::bind("127.0.0.1:0").expect("bind");
let address = listener.local_addr().expect("addr");
let server = std::thread::spawn(move || {
let (mut stream, _) = listener.accept().expect("accept");
let mut wire = Vec::new();
Frame::new(0x10, vec![9; 40]).encode(&mut wire);
stream.write_all(&wire[..5]).expect("first");
std::thread::sleep(Duration::from_millis(20));
stream.write_all(&wire[5..]).expect("rest");
});
let mut link = TcpLink::connect(address, Duration::from_secs(2)).expect("connect");
let frame = link.recv().expect("recv");
assert_eq!(frame.msg_type, 0x10);
assert_eq!(frame.payload.len(), 40);
server.join().expect("join");
}
#[test]
fn two_frames_in_one_read_are_returned_one_at_a_time() {
let listener = TcpListener::bind("127.0.0.1:0").expect("bind");
let address = listener.local_addr().expect("addr");
let server = std::thread::spawn(move || {
let (mut stream, _) = listener.accept().expect("accept");
let mut wire = Vec::new();
Frame::new(0x01, vec![1]).encode(&mut wire);
Frame::new(0x02, vec![2]).encode(&mut wire);
stream.write_all(&wire).expect("write");
});
let mut link = TcpLink::connect(address, Duration::from_secs(2)).expect("connect");
assert_eq!(link.recv().expect("first").msg_type, 0x01);
assert_eq!(link.recv().expect("second").msg_type, 0x02);
server.join().expect("join");
}
#[test]
fn a_closed_stream_is_an_error_not_an_empty_frame() {
let listener = TcpListener::bind("127.0.0.1:0").expect("bind");
let address = listener.local_addr().expect("addr");
let server = std::thread::spawn(move || {
let (_stream, _) = listener.accept().expect("accept");
});
let mut link = TcpLink::connect(address, Duration::from_secs(2)).expect("connect");
let error = link.recv().expect_err("closed stream");
assert_eq!(error.kind(), io::ErrorKind::UnexpectedEof);
server.join().expect("join");
}
#[test]
fn v1_fallback_requires_permission_and_a_non_transport_failure() {
let allowed = Preference {
primary: StratumVersion::V2,
allow_v1_fallback: true,
};
assert_eq!(
fallback(allowed, StratumVersion::V2, FailureKind::Refused),
Some(StratumVersion::V1)
);
assert_eq!(
fallback(allowed, StratumVersion::V2, FailureKind::Unsupported),
Some(StratumVersion::V1)
);
assert_eq!(
fallback(allowed, StratumVersion::V2, FailureKind::Timeout),
Some(StratumVersion::V1)
);
assert_eq!(
fallback(allowed, StratumVersion::V2, FailureKind::Transport),
None
);
}
#[test]
fn v1_fallback_can_be_disabled_and_v1_failures_do_not_loop() {
let denied = Preference {
primary: StratumVersion::V2,
allow_v1_fallback: false,
};
assert_eq!(
fallback(denied, StratumVersion::V2, FailureKind::Refused),
None
);
let allowed = Preference::default();
assert_eq!(
fallback(allowed, StratumVersion::V1, FailureKind::Refused),
None
);
}
fn mock_pool() -> std::net::SocketAddr {
use crate::stratum_v2::{
NewMiningJob, OpenStandardMiningChannelSuccess, SetNewPrevHash, SetupConnectionSuccess,
OPEN_STANDARD_MINING_CHANNEL, OPEN_STANDARD_MINING_CHANNEL_SUCCESS, SETUP_CONNECTION,
SETUP_CONNECTION_SUCCESS, SET_NEW_PREV_HASH, SUBMIT_SHARES_SUCCESS,
};
let listener = TcpListener::bind("127.0.0.1:0").expect("bind");
let address = listener.local_addr().expect("addr");
// Publish the address through a channel so the test can connect after binding.
let (tx, rx) = std::sync::mpsc::channel();
tx.send(address).expect("send address");
std::thread::spawn(move || {
let (stream, _) = listener.accept().expect("accept");
let mut link = TcpLink::from_stream(stream).expect("link");
let setup = link.recv().expect("setup");
assert_eq!(setup.msg_type, SETUP_CONNECTION);
link.send(&Frame::new(
SETUP_CONNECTION_SUCCESS,
SetupConnectionSuccess {
used_version: 2,
flags: 0,
}
.encode(),
))
.expect("setup success");
let open = link.recv().expect("open");
assert_eq!(open.msg_type, OPEN_STANDARD_MINING_CHANNEL);
link.send(&Frame::new(
OPEN_STANDARD_MINING_CHANNEL_SUCCESS,
OpenStandardMiningChannelSuccess {
request_id: 1,
channel_id: 7,
target: [0x7f; 32],
extranonce_prefix: vec![9, 9],
group_channel_id: 0,
}
.encode(),
))
.expect("channel success");
link.send(&Frame::new(
SET_NEW_PREV_HASH,
SetNewPrevHash {
channel_id: 7,
job_id: 41,
prev_hash: [0x11; 32],
ntime_start: 1_700_000_000,
nbits: 0x1707_0000,
}
.encode(),
))
.expect("prev hash");
link.send(&Frame::new(
NEW_MINING_JOB_TYPE,
NewMiningJob {
channel_id: 7,
job_id: 42,
ntime_start: Some(1_700_000_100),
version: 0x2000_0000,
merkle_root: [0x22; 32],
}
.encode(),
))
.expect("job");
let share = link.recv().expect("share");
assert_eq!(share.msg_type, SUBMIT_SHARES_STANDARD_TYPE);
let mut body = Vec::new();
body.extend_from_slice(&7_u32.to_le_bytes());
body.extend_from_slice(&1_u32.to_le_bytes());
body.extend_from_slice(&1_u32.to_le_bytes());
body.extend_from_slice(&0_u64.to_le_bytes());
link.send(&Frame::new(SUBMIT_SHARES_SUCCESS, body))
.expect("share success");
});
rx.recv().expect("address")
}
const NEW_MINING_JOB_TYPE: u8 = 0x15;
const SUBMIT_SHARES_STANDARD_TYPE: u8 = 0x1a;
#[test]
fn a_session_runs_against_a_socket_pool() {
use crate::stratum_v2_session::{handshake, V2Config, V2Event, V2Session};
let address = mock_pool();
let mut link = TcpLink::connect(address, Duration::from_secs(3)).expect("connect");
let config = V2Config {
host: "pool.test".into(),
port: 3333,
flags: 0,
user_identity: "worker".into(),
nominal_hash_rate: 1.0e14,
max_target: [0xff; 32],
vendor: "alkane".into(),
hardware: "bench".into(),
firmware: "alkane-os".into(),
device_id: "b1".into(),
};
let channel = handshake(&mut link, &config).expect("handshake");
assert_eq!(channel.channel_id, 7);
assert_eq!(channel.extranonce_prefix, vec![9, 9]);
let mut session = V2Session::new(channel);
let prev = session
.on_frame(&link.recv().expect("prev"))
.expect("prev event");
assert!(matches!(prev, V2Event::PrevHash { job_id: 41, .. }));
let job = session
.on_frame(&link.recv().expect("job"))
.expect("job event");
match job {
V2Event::Job(parsed) => {
assert_eq!(parsed.job_id, 42);
assert_eq!(parsed.prev_hash, Some([0x11; 32]));
assert_eq!(parsed.ntime_start, Some(1_700_000_100));
}
other => panic!("unexpected event: {other:?}"),
}
let sequence = session
.submit(&mut link, 42, 0xdead_beef, 1_700_000_100, 0x2000_0000)
.expect("submit");
assert_eq!(sequence, 1);
let ack = session
.on_frame(&link.recv().expect("ack"))
.expect("ack event");
assert_eq!(
ack,
V2Event::ShareAccepted {
last_sequence: 1,
accepted: 1
}
);
}
}
+631
View File
@@ -0,0 +1,631 @@
// SPDX-License-Identifier: MIT
//! Stratum V2 mining-protocol codec.
//!
//! Covers the client half of the mining sub-protocol: connection setup, opening a standard
//! channel, and the job/share messages that follow. Layouts follow the published specification
//! (framing in 03-Protocol-Overview 3.2, message types in 08-Message-Types, payloads in
//! 05-Mining-Protocol 5.3).
//!
//! Everything is little-endian. `U256` is carried as the raw 32 bytes of the little-endian
//! integer, which for a SHA-256 digest is the digest's own byte order.
use std::fmt;
pub const EXTENSION_TYPE_CORE: u16 = 0;
pub const SETUP_CONNECTION: u8 = 0x00;
pub const SETUP_CONNECTION_SUCCESS: u8 = 0x01;
pub const SETUP_CONNECTION_ERROR: u8 = 0x02;
pub const OPEN_STANDARD_MINING_CHANNEL: u8 = 0x10;
pub const OPEN_STANDARD_MINING_CHANNEL_SUCCESS: u8 = 0x11;
pub const OPEN_MINING_CHANNEL_ERROR: u8 = 0x12;
pub const NEW_MINING_JOB: u8 = 0x15;
pub const SUBMIT_SHARES_STANDARD: u8 = 0x1a;
pub const SUBMIT_SHARES_SUCCESS: u8 = 0x1c;
pub const SUBMIT_SHARES_ERROR: u8 = 0x1d;
pub const SET_NEW_PREV_HASH: u8 = 0x20;
pub const SET_TARGET: u8 = 0x21;
const HEADER_LEN: usize = 6;
const MAX_FRAME: usize = 1 << 20;
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum V2Error {
Truncated,
Length,
String,
NonFiniteRate,
UnknownMessage(u8),
}
impl fmt::Display for V2Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Truncated => f.write_str("stratum v2 message is truncated"),
Self::Length => f.write_str("stratum v2 length field is invalid"),
Self::String => f.write_str("stratum v2 string field is invalid"),
Self::NonFiniteRate => {
f.write_str("stratum v2 hashrate is not a finite positive number")
}
Self::UnknownMessage(kind) => {
write!(f, "unsupported stratum v2 message type {kind:#x}")
}
}
}
}
impl std::error::Error for V2Error {}
/// One framed message: 6-byte header plus payload.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Frame {
pub extension_type: u16,
pub msg_type: u8,
pub payload: Vec<u8>,
}
impl Frame {
pub fn new(msg_type: u8, payload: Vec<u8>) -> Self {
Self {
extension_type: EXTENSION_TYPE_CORE,
msg_type,
payload,
}
}
pub fn encode(&self, out: &mut Vec<u8>) {
out.extend_from_slice(&self.extension_type.to_le_bytes());
out.push(self.msg_type);
let length = self.payload.len() as u32;
out.extend_from_slice(&length.to_le_bytes()[..3]);
out.extend_from_slice(&self.payload);
}
/// Decode one frame from `buf`, returning it and how many bytes it consumed.
pub fn decode(buf: &[u8]) -> Result<(Self, usize), V2Error> {
if buf.len() < HEADER_LEN {
return Err(V2Error::Truncated);
}
let extension_type = u16::from_le_bytes([buf[0], buf[1]]);
let msg_type = buf[2];
let length = u32::from_le_bytes([buf[3], buf[4], buf[5], 0]) as usize;
if length > MAX_FRAME {
return Err(V2Error::Length);
}
let end = HEADER_LEN + length;
if buf.len() < end {
return Err(V2Error::Truncated);
}
Ok((
Self {
extension_type,
msg_type,
payload: buf[HEADER_LEN..end].to_vec(),
},
end,
))
}
}
/// `SetupConnection` for the mining sub-protocol.
#[derive(Clone, Debug, PartialEq)]
pub struct SetupConnection {
pub protocol: u8,
pub min_version: u16,
pub max_version: u16,
pub flags: u32,
pub endpoint_host: String,
pub endpoint_port: u16,
pub vendor: String,
pub hardware_version: String,
pub firmware: String,
pub device_id: String,
}
impl SetupConnection {
pub fn encode(&self) -> Vec<u8> {
let mut out = Vec::new();
out.push(self.protocol);
put_u16(&mut out, self.min_version);
put_u16(&mut out, self.max_version);
put_u32(&mut out, self.flags);
put_str(&mut out, &self.endpoint_host);
put_u16(&mut out, self.endpoint_port);
put_str(&mut out, &self.vendor);
put_str(&mut out, &self.hardware_version);
put_str(&mut out, &self.firmware);
put_str(&mut out, &self.device_id);
out
}
pub fn decode(payload: &[u8]) -> Result<Self, V2Error> {
let mut reader = Reader::new(payload);
Ok(Self {
protocol: reader.u8()?,
min_version: reader.u16()?,
max_version: reader.u16()?,
flags: reader.u32()?,
endpoint_host: reader.string()?,
endpoint_port: reader.u16()?,
vendor: reader.string()?,
hardware_version: reader.string()?,
firmware: reader.string()?,
device_id: reader.string()?,
})
}
}
/// `SetupConnection.Success`.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct SetupConnectionSuccess {
pub used_version: u16,
pub flags: u32,
}
impl SetupConnectionSuccess {
pub fn encode(&self) -> Vec<u8> {
let mut out = Vec::new();
put_u16(&mut out, self.used_version);
put_u32(&mut out, self.flags);
out
}
pub fn decode(payload: &[u8]) -> Result<Self, V2Error> {
let mut reader = Reader::new(payload);
Ok(Self {
used_version: reader.u16()?,
flags: reader.u32()?,
})
}
}
/// `OpenStandardMiningChannel`.
#[derive(Clone, Debug, PartialEq)]
pub struct OpenStandardMiningChannel {
pub request_id: u32,
pub user_identity: String,
pub nominal_hash_rate: f32,
pub max_target: [u8; 32],
}
impl OpenStandardMiningChannel {
pub fn encode(&self) -> Vec<u8> {
let mut out = Vec::new();
put_u32(&mut out, self.request_id);
put_str(&mut out, &self.user_identity);
out.extend_from_slice(&self.nominal_hash_rate.to_le_bytes());
out.extend_from_slice(&self.max_target);
out
}
pub fn decode(payload: &[u8]) -> Result<Self, V2Error> {
let mut reader = Reader::new(payload);
let request_id = reader.u32()?;
let user_identity = reader.string()?;
let nominal_hash_rate = reader.f32()?;
if !nominal_hash_rate.is_finite() || nominal_hash_rate < 0.0 {
return Err(V2Error::NonFiniteRate);
}
Ok(Self {
request_id,
user_identity,
nominal_hash_rate,
max_target: reader.u256()?,
})
}
}
/// `OpenStandardMiningChannel.Success`.
#[derive(Clone, Debug, PartialEq)]
pub struct OpenStandardMiningChannelSuccess {
pub request_id: u32,
pub channel_id: u32,
pub target: [u8; 32],
pub extranonce_prefix: Vec<u8>,
pub group_channel_id: u32,
}
impl OpenStandardMiningChannelSuccess {
pub fn encode(&self) -> Vec<u8> {
let mut out = Vec::new();
put_u32(&mut out, self.request_id);
put_u32(&mut out, self.channel_id);
out.extend_from_slice(&self.target);
put_bytes(&mut out, &self.extranonce_prefix);
put_u32(&mut out, self.group_channel_id);
out
}
pub fn decode(payload: &[u8]) -> Result<Self, V2Error> {
let mut reader = Reader::new(payload);
Ok(Self {
request_id: reader.u32()?,
channel_id: reader.u32()?,
target: reader.u256()?,
extranonce_prefix: reader.bytes(32)?,
group_channel_id: reader.u32()?,
})
}
}
/// `NewMiningJob` on a standard channel.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct NewMiningJob {
pub channel_id: u32,
pub job_id: u32,
/// `None` means a future job, activated by the matching `SetNewPrevHash`.
pub ntime_start: Option<u32>,
pub version: u32,
pub merkle_root: [u8; 32],
}
impl NewMiningJob {
pub fn encode(&self) -> Vec<u8> {
let mut out = Vec::new();
put_u32(&mut out, self.channel_id);
put_u32(&mut out, self.job_id);
match self.ntime_start {
Some(ntime) => {
out.push(1);
put_u32(&mut out, ntime);
}
None => out.push(0),
}
put_u32(&mut out, self.version);
out.extend_from_slice(&self.merkle_root);
out
}
pub fn decode(payload: &[u8]) -> Result<Self, V2Error> {
let mut reader = Reader::new(payload);
let channel_id = reader.u32()?;
let job_id = reader.u32()?;
let ntime_start = reader.option_u32()?;
Ok(Self {
channel_id,
job_id,
ntime_start,
version: reader.u32()?,
merkle_root: reader.u256()?,
})
}
}
/// `SetNewPrevHash`.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct SetNewPrevHash {
pub channel_id: u32,
pub job_id: u32,
pub prev_hash: [u8; 32],
pub ntime_start: u32,
pub nbits: u32,
}
impl SetNewPrevHash {
pub fn encode(&self) -> Vec<u8> {
let mut out = Vec::new();
put_u32(&mut out, self.channel_id);
put_u32(&mut out, self.job_id);
out.extend_from_slice(&self.prev_hash);
put_u32(&mut out, self.ntime_start);
put_u32(&mut out, self.nbits);
out
}
pub fn decode(payload: &[u8]) -> Result<Self, V2Error> {
let mut reader = Reader::new(payload);
Ok(Self {
channel_id: reader.u32()?,
job_id: reader.u32()?,
prev_hash: reader.u256()?,
ntime_start: reader.u32()?,
nbits: reader.u32()?,
})
}
}
/// `SubmitSharesStandard`.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct SubmitSharesStandard {
pub channel_id: u32,
pub sequence_number: u32,
pub job_id: u32,
pub nonce: u32,
pub ntime: u32,
pub version: u32,
}
impl SubmitSharesStandard {
pub fn encode(&self) -> Vec<u8> {
let mut out = Vec::new();
put_u32(&mut out, self.channel_id);
put_u32(&mut out, self.sequence_number);
put_u32(&mut out, self.job_id);
put_u32(&mut out, self.nonce);
put_u32(&mut out, self.ntime);
put_u32(&mut out, self.version);
out
}
pub fn decode(payload: &[u8]) -> Result<Self, V2Error> {
let mut reader = Reader::new(payload);
Ok(Self {
channel_id: reader.u32()?,
sequence_number: reader.u32()?,
job_id: reader.u32()?,
nonce: reader.u32()?,
ntime: reader.u32()?,
version: reader.u32()?,
})
}
}
fn put_u16(out: &mut Vec<u8>, value: u16) {
out.extend_from_slice(&value.to_le_bytes());
}
fn put_u32(out: &mut Vec<u8>, value: u32) {
out.extend_from_slice(&value.to_le_bytes());
}
fn put_str(out: &mut Vec<u8>, text: &str) {
let bytes = text.as_bytes();
let length = bytes.len().min(255);
out.push(length as u8);
out.extend_from_slice(&bytes[..length]);
}
fn put_bytes(out: &mut Vec<u8>, bytes: &[u8]) {
let length = bytes.len().min(255);
out.push(length as u8);
out.extend_from_slice(&bytes[..length]);
}
struct Reader<'a> {
buf: &'a [u8],
at: usize,
}
impl<'a> Reader<'a> {
fn new(buf: &'a [u8]) -> Self {
Self { buf, at: 0 }
}
fn take(&mut self, count: usize) -> Result<&'a [u8], V2Error> {
let end = self.at.checked_add(count).ok_or(V2Error::Length)?;
if end > self.buf.len() {
return Err(V2Error::Truncated);
}
let slice = &self.buf[self.at..end];
self.at = end;
Ok(slice)
}
fn u8(&mut self) -> Result<u8, V2Error> {
Ok(self.take(1)?[0])
}
fn u16(&mut self) -> Result<u16, V2Error> {
let bytes = self.take(2)?;
Ok(u16::from_le_bytes([bytes[0], bytes[1]]))
}
fn u32(&mut self) -> Result<u32, V2Error> {
let bytes = self.take(4)?;
Ok(u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]))
}
fn f32(&mut self) -> Result<f32, V2Error> {
Ok(f32::from_bits(self.u32()?))
}
fn u256(&mut self) -> Result<[u8; 32], V2Error> {
let bytes = self.take(32)?;
let mut out = [0_u8; 32];
out.copy_from_slice(bytes);
Ok(out)
}
fn string(&mut self) -> Result<String, V2Error> {
let length = self.u8()? as usize;
let bytes = self.take(length)?;
String::from_utf8(bytes.to_vec()).map_err(|_| V2Error::String)
}
fn bytes(&mut self, max: usize) -> Result<Vec<u8>, V2Error> {
let length = self.u8()? as usize;
if length > max {
return Err(V2Error::Length);
}
Ok(self.take(length)?.to_vec())
}
fn option_u32(&mut self) -> Result<Option<u32>, V2Error> {
match self.u8()? {
0 => Ok(None),
1 => Ok(Some(self.u32()?)),
_ => Err(V2Error::Length),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn hash(byte: u8) -> [u8; 32] {
[byte; 32]
}
#[test]
fn frame_header_matches_the_specification() {
let mut wire = Vec::new();
Frame::new(SETUP_CONNECTION, vec![1, 2, 3]).encode(&mut wire);
assert_eq!(&wire[..3], &[0x00, 0x00, 0x00]);
assert_eq!(&wire[3..6], &[0x03, 0x00, 0x00]);
let (frame, consumed) = Frame::decode(&wire).expect("frame");
assert_eq!(consumed, wire.len());
assert_eq!(frame.msg_type, SETUP_CONNECTION);
assert_eq!(frame.payload, vec![1, 2, 3]);
}
#[test]
fn a_truncated_frame_is_rejected() {
assert_eq!(Frame::decode(&[0, 0, 0x00]), Err(V2Error::Truncated));
let mut wire = Vec::new();
Frame::new(SETUP_CONNECTION, vec![9; 10]).encode(&mut wire);
assert_eq!(Frame::decode(&wire[..8]), Err(V2Error::Truncated));
}
#[test]
fn setup_connection_round_trips() {
let message = SetupConnection {
protocol: 0,
min_version: 2,
max_version: 2,
flags: 0b1011,
endpoint_host: "pool.example".into(),
endpoint_port: 3333,
vendor: "alkane".into(),
hardware_version: "s19jpro-bm1362".into(),
firmware: "alkane-os/0.1.0".into(),
device_id: "bench-169".into(),
};
let wire = message.encode();
assert_eq!(SetupConnection::decode(&wire).expect("decode"), message);
}
#[test]
fn setup_connection_success_round_trips() {
let message = SetupConnectionSuccess {
used_version: 2,
flags: 0,
};
assert_eq!(
SetupConnectionSuccess::decode(&message.encode()).expect("decode"),
message
);
}
#[test]
fn open_standard_channel_round_trips() {
let message = OpenStandardMiningChannel {
request_id: 7,
user_identity: "bc1q.example".into(),
nominal_hash_rate: 95_000_000_000_000.0,
max_target: hash(0xff),
};
assert_eq!(
OpenStandardMiningChannel::decode(&message.encode()).expect("decode"),
message
);
}
#[test]
fn a_non_finite_hashrate_is_a_protocol_error() {
let message = OpenStandardMiningChannel {
request_id: 1,
user_identity: "x".into(),
nominal_hash_rate: f32::NAN,
max_target: hash(0),
};
assert_eq!(
OpenStandardMiningChannel::decode(&message.encode()),
Err(V2Error::NonFiniteRate)
);
let negative = OpenStandardMiningChannel {
nominal_hash_rate: -1.0,
..message
};
assert_eq!(
OpenStandardMiningChannel::decode(&negative.encode()),
Err(V2Error::NonFiniteRate)
);
}
#[test]
fn channel_success_carries_the_extranonce_prefix() {
let message = OpenStandardMiningChannelSuccess {
request_id: 7,
channel_id: 11,
target: hash(0x7f),
extranonce_prefix: vec![0xde, 0xad, 0xbe, 0xef],
group_channel_id: 0,
};
assert_eq!(
OpenStandardMiningChannelSuccess::decode(&message.encode()).expect("decode"),
message
);
}
#[test]
fn new_job_round_trips_both_ntime_forms() {
let active = NewMiningJob {
channel_id: 1,
job_id: 2,
ntime_start: Some(1_700_000_000),
version: 0x2000_0000,
merkle_root: hash(0x11),
};
assert_eq!(
NewMiningJob::decode(&active.encode()).expect("decode"),
active
);
let future = NewMiningJob {
ntime_start: None,
..active
};
assert_eq!(
NewMiningJob::decode(&future.encode()).expect("decode"),
future
);
}
#[test]
fn set_new_prev_hash_round_trips() {
let message = SetNewPrevHash {
channel_id: 1,
job_id: 2,
prev_hash: hash(0x22),
ntime_start: 1_700_000_100,
nbits: 0x1707_0000,
};
assert_eq!(
SetNewPrevHash::decode(&message.encode()).expect("decode"),
message
);
}
#[test]
fn submit_shares_round_trips() {
let message = SubmitSharesStandard {
channel_id: 3,
sequence_number: 99,
job_id: 4,
nonce: 0xdead_beef,
ntime: 1_700_000_200,
version: 0x2000_0000,
};
assert_eq!(
SubmitSharesStandard::decode(&message.encode()).expect("decode"),
message
);
}
#[test]
fn a_short_payload_is_rejected_rather_than_padded() {
let wire = SubmitSharesStandard {
channel_id: 3,
sequence_number: 99,
job_id: 4,
nonce: 0,
ntime: 0,
version: 0,
}
.encode();
assert_eq!(
SubmitSharesStandard::decode(&wire[..8]),
Err(V2Error::Truncated)
);
}
}
+553
View File
@@ -0,0 +1,553 @@
// SPDX-License-Identifier: MIT
//! Stratum V2 session: handshake, channel, jobs and share submission.
//!
//! The codec in `stratum_v2` owns bytes; this module owns order. It drives the client half of a
//! mining connection and refuses to invent state: a job received before any `SetNewPrevHash` is
//! reported with no previous hash rather than with a zero one, and a rejected setup surfaces the
//! server's code.
use crate::stratum_v2::{
Frame, NewMiningJob, OpenStandardMiningChannel, SetNewPrevHash, SetupConnection,
SetupConnectionSuccess, SubmitSharesStandard, NEW_MINING_JOB, OPEN_MINING_CHANNEL_ERROR,
OPEN_STANDARD_MINING_CHANNEL, OPEN_STANDARD_MINING_CHANNEL_SUCCESS, SETUP_CONNECTION,
SETUP_CONNECTION_ERROR, SETUP_CONNECTION_SUCCESS, SET_NEW_PREV_HASH, SET_TARGET,
SUBMIT_SHARES_ERROR, SUBMIT_SHARES_STANDARD, SUBMIT_SHARES_SUCCESS,
};
/// A connection that carries whole frames.
pub trait V2Link {
type Error;
fn send(&mut self, frame: &Frame) -> Result<(), Self::Error>;
fn recv(&mut self) -> Result<Frame, Self::Error>;
}
/// What the client declares when it connects.
#[derive(Clone, Debug, PartialEq)]
pub struct V2Config {
pub host: String,
pub port: u16,
pub flags: u32,
pub user_identity: String,
pub nominal_hash_rate: f32,
pub max_target: [u8; 32],
pub vendor: String,
pub hardware: String,
pub firmware: String,
pub device_id: String,
}
/// An opened standard channel.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct V2Channel {
pub channel_id: u32,
pub target: [u8; 32],
pub extranonce_prefix: Vec<u8>,
pub group_channel_id: u32,
}
/// A job the miner may work on.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct V2Job {
pub job_id: u32,
pub version: u32,
pub merkle_root: [u8; 32],
pub ntime_start: Option<u32>,
pub prev_hash: Option<[u8; 32]>,
pub nbits: Option<u32>,
}
/// Something the server told us.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum V2Event {
Job(V2Job),
PrevHash {
job_id: u32,
prev_hash: [u8; 32],
ntime_start: u32,
nbits: u32,
},
Target {
channel_id: u32,
target: [u8; 32],
},
ShareAccepted {
last_sequence: u32,
accepted: u32,
},
ShareRejected {
last_sequence: u32,
},
Ignored,
}
/// A protocol-level failure, without a link error inside it.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum SessionError {
Protocol(&'static str),
Rejected(String),
}
/// A failure that may have come from the transport.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum ConnectError<E> {
Link(E),
Session(SessionError),
}
/// Run the client handshake and return the opened channel.
pub fn handshake<L: V2Link>(
link: &mut L,
config: &V2Config,
) -> Result<V2Channel, ConnectError<L::Error>> {
let setup = SetupConnection {
protocol: 0,
min_version: 2,
max_version: 2,
flags: config.flags,
endpoint_host: config.host.clone(),
endpoint_port: config.port,
vendor: config.vendor.clone(),
hardware_version: config.hardware.clone(),
firmware: config.firmware.clone(),
device_id: config.device_id.clone(),
};
link.send(&Frame::new(SETUP_CONNECTION, setup.encode()))
.map_err(ConnectError::Link)?;
let reply = link.recv().map_err(ConnectError::Link)?;
match reply.msg_type {
SETUP_CONNECTION_SUCCESS => {
let _ = SetupConnectionSuccess::decode(&reply.payload)
.map_err(|_| ConnectError::Session(SessionError::Protocol("bad setup success")))?;
}
SETUP_CONNECTION_ERROR => {
return Err(ConnectError::Session(SessionError::Rejected(
setup_error_text(&reply.payload),
)))
}
_ => {
return Err(ConnectError::Session(SessionError::Protocol(
"unexpected message before setup success",
)))
}
}
let open = OpenStandardMiningChannel {
request_id: 1,
user_identity: config.user_identity.clone(),
nominal_hash_rate: config.nominal_hash_rate,
max_target: config.max_target,
};
link.send(&Frame::new(OPEN_STANDARD_MINING_CHANNEL, open.encode()))
.map_err(ConnectError::Link)?;
let reply = link.recv().map_err(ConnectError::Link)?;
match reply.msg_type {
OPEN_STANDARD_MINING_CHANNEL_SUCCESS => {
let success =
crate::stratum_v2::OpenStandardMiningChannelSuccess::decode(&reply.payload)
.map_err(|_| {
ConnectError::Session(SessionError::Protocol("bad channel success"))
})?;
if success.request_id != 1 {
return Err(ConnectError::Session(SessionError::Protocol(
"channel response does not match the request",
)));
}
Ok(V2Channel {
channel_id: success.channel_id,
target: success.target,
extranonce_prefix: success.extranonce_prefix,
group_channel_id: success.group_channel_id,
})
}
OPEN_MINING_CHANNEL_ERROR => Err(ConnectError::Session(SessionError::Rejected(
setup_error_text(&reply.payload),
))),
_ => Err(ConnectError::Session(SessionError::Protocol(
"unexpected message while opening a channel",
))),
}
}
fn setup_error_text(payload: &[u8]) -> String {
// Error messages are a U32 flag mask followed by a STR0_255 code.
if payload.len() < 5 {
return String::from("unspecified");
}
let length = payload[4] as usize;
payload
.get(5..5 + length)
.and_then(|bytes| std::str::from_utf8(bytes).ok())
.unwrap_or("unspecified")
.to_owned()
}
/// Session state after the handshake.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct V2Session {
channel: V2Channel,
prev_hash: Option<[u8; 32]>,
nbits: Option<u32>,
sequence: u32,
}
impl V2Session {
pub fn new(channel: V2Channel) -> Self {
Self {
channel,
prev_hash: None,
nbits: None,
sequence: 0,
}
}
pub fn channel(&self) -> &V2Channel {
&self.channel
}
/// Interpret one server frame.
pub fn on_frame(&mut self, frame: &Frame) -> Result<V2Event, SessionError> {
match frame.msg_type {
NEW_MINING_JOB => {
let job = NewMiningJob::decode(&frame.payload)
.map_err(|_| SessionError::Protocol("bad NewMiningJob"))?;
Ok(V2Event::Job(V2Job {
job_id: job.job_id,
version: job.version,
merkle_root: job.merkle_root,
ntime_start: job.ntime_start,
prev_hash: self.prev_hash,
nbits: self.nbits,
}))
}
SET_NEW_PREV_HASH => {
let message = SetNewPrevHash::decode(&frame.payload)
.map_err(|_| SessionError::Protocol("bad SetNewPrevHash"))?;
self.prev_hash = Some(message.prev_hash);
self.nbits = Some(message.nbits);
Ok(V2Event::PrevHash {
job_id: message.job_id,
prev_hash: message.prev_hash,
ntime_start: message.ntime_start,
nbits: message.nbits,
})
}
SET_TARGET => {
if frame.payload.len() != 4 + 32 {
return Err(SessionError::Protocol("bad SetTarget"));
}
let channel_id = u32::from_le_bytes([
frame.payload[0],
frame.payload[1],
frame.payload[2],
frame.payload[3],
]);
let mut target = [0_u8; 32];
target.copy_from_slice(&frame.payload[4..36]);
Ok(V2Event::Target { channel_id, target })
}
SUBMIT_SHARES_SUCCESS => {
if frame.payload.len() < 20 {
return Err(SessionError::Protocol("bad SubmitShares.Success"));
}
let last_sequence = u32::from_le_bytes([
frame.payload[4],
frame.payload[5],
frame.payload[6],
frame.payload[7],
]);
let accepted = u32::from_le_bytes([
frame.payload[8],
frame.payload[9],
frame.payload[10],
frame.payload[11],
]);
Ok(V2Event::ShareAccepted {
last_sequence,
accepted,
})
}
SUBMIT_SHARES_ERROR => {
let last_sequence = if frame.payload.len() >= 8 {
u32::from_le_bytes([
frame.payload[0],
frame.payload[1],
frame.payload[2],
frame.payload[3],
])
} else {
0
};
Ok(V2Event::ShareRejected { last_sequence })
}
_ => Ok(V2Event::Ignored),
}
}
/// Submit one standard share; returns the sequence number used.
pub fn submit<L: V2Link>(
&mut self,
link: &mut L,
job_id: u32,
nonce: u32,
ntime: u32,
version: u32,
) -> Result<u32, ConnectError<L::Error>> {
self.sequence = self.sequence.wrapping_add(1);
let share = SubmitSharesStandard {
channel_id: self.channel.channel_id,
sequence_number: self.sequence,
job_id,
nonce,
ntime,
version,
};
link.send(&Frame::new(SUBMIT_SHARES_STANDARD, share.encode()))
.map_err(ConnectError::Link)?;
Ok(self.sequence)
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::collections::VecDeque;
struct Scripted {
incoming: VecDeque<Frame>,
sent: Vec<Frame>,
}
impl Scripted {
fn new(incoming: Vec<Frame>) -> Self {
Self {
incoming: incoming.into(),
sent: Vec::new(),
}
}
}
impl V2Link for Scripted {
type Error = ();
fn send(&mut self, frame: &Frame) -> Result<(), ()> {
self.sent.push(frame.clone());
Ok(())
}
fn recv(&mut self) -> Result<Frame, ()> {
self.incoming.pop_front().ok_or(())
}
}
fn config() -> V2Config {
V2Config {
host: "pool.example".into(),
port: 3333,
flags: 0,
user_identity: "worker".into(),
nominal_hash_rate: 1.0e14,
max_target: [0xff; 32],
vendor: "alkane".into(),
hardware: "bench".into(),
firmware: "alkane-os".into(),
device_id: "bench-1".into(),
}
}
fn setup_success() -> Frame {
Frame::new(
SETUP_CONNECTION_SUCCESS,
SetupConnectionSuccess {
used_version: 2,
flags: 0,
}
.encode(),
)
}
fn channel_success() -> Frame {
Frame::new(
OPEN_STANDARD_MINING_CHANNEL_SUCCESS,
crate::stratum_v2::OpenStandardMiningChannelSuccess {
request_id: 1,
channel_id: 9,
target: [0x7f; 32],
extranonce_prefix: vec![1, 2],
group_channel_id: 0,
}
.encode(),
)
}
#[test]
fn handshake_sends_setup_then_open_and_returns_the_channel() {
let mut link = Scripted::new(vec![setup_success(), channel_success()]);
let channel = handshake(&mut link, &config()).expect("handshake");
assert_eq!(channel.channel_id, 9);
assert_eq!(channel.extranonce_prefix, vec![1, 2]);
assert_eq!(link.sent.len(), 2);
assert_eq!(link.sent[0].msg_type, SETUP_CONNECTION);
assert_eq!(link.sent[1].msg_type, OPEN_STANDARD_MINING_CHANNEL);
let open = OpenStandardMiningChannel::decode(&link.sent[1].payload).expect("open");
assert_eq!(open.user_identity, "worker");
assert_eq!(open.request_id, 1);
}
#[test]
fn a_setup_error_surfaces_the_server_code() {
let mut payload = 0_u32.to_le_bytes().to_vec();
payload.push(3);
payload.extend_from_slice(b"bad");
let mut link = Scripted::new(vec![Frame::new(SETUP_CONNECTION_ERROR, payload)]);
assert_eq!(
handshake(&mut link, &config()),
Err(ConnectError::Session(SessionError::Rejected("bad".into())))
);
}
#[test]
fn an_unexpected_message_during_setup_is_a_protocol_error() {
let mut link = Scripted::new(vec![Frame::new(NEW_MINING_JOB, vec![0; 44])]);
assert_eq!(
handshake(&mut link, &config()),
Err(ConnectError::Session(SessionError::Protocol(
"unexpected message before setup success"
)))
);
}
#[test]
fn a_job_before_any_prev_hash_has_no_prev_hash() {
let mut session = V2Session::new(V2Channel {
channel_id: 9,
target: [0xff; 32],
extranonce_prefix: Vec::new(),
group_channel_id: 0,
});
let job = NewMiningJob {
channel_id: 9,
job_id: 1,
ntime_start: Some(1_700_000_000),
version: 0x2000_0000,
merkle_root: [0x11; 32],
};
let event = session
.on_frame(&Frame::new(NEW_MINING_JOB, job.encode()))
.expect("job");
match event {
V2Event::Job(parsed) => {
assert_eq!(parsed.job_id, 1);
assert_eq!(parsed.prev_hash, None);
assert_eq!(parsed.nbits, None);
}
other => panic!("unexpected event: {other:?}"),
}
}
#[test]
fn prev_hash_is_remembered_for_later_jobs() {
let mut session = V2Session::new(V2Channel {
channel_id: 9,
target: [0xff; 32],
extranonce_prefix: Vec::new(),
group_channel_id: 0,
});
let prev = SetNewPrevHash {
channel_id: 9,
job_id: 1,
prev_hash: [0x22; 32],
ntime_start: 1_700_000_100,
nbits: 0x1707_0000,
};
session
.on_frame(&Frame::new(SET_NEW_PREV_HASH, prev.encode()))
.expect("prev hash");
let job = NewMiningJob {
channel_id: 9,
job_id: 2,
ntime_start: None,
version: 0x2000_0000,
merkle_root: [0x33; 32],
};
match session
.on_frame(&Frame::new(NEW_MINING_JOB, job.encode()))
.expect("job")
{
V2Event::Job(parsed) => {
assert_eq!(parsed.prev_hash, Some([0x22; 32]));
assert_eq!(parsed.nbits, Some(0x1707_0000));
assert_eq!(parsed.ntime_start, None);
}
other => panic!("unexpected event: {other:?}"),
}
}
#[test]
fn submissions_use_the_channel_and_increasing_sequence_numbers() {
let mut session = V2Session::new(V2Channel {
channel_id: 9,
target: [0xff; 32],
extranonce_prefix: Vec::new(),
group_channel_id: 0,
});
let mut link = Scripted::new(Vec::new());
assert_eq!(
session
.submit(&mut link, 1, 0xabcd, 1_700_000_000, 0x2000_0000)
.expect("submit"),
1
);
assert_eq!(
session
.submit(&mut link, 1, 0xabce, 1_700_000_000, 0x2000_0000)
.expect("submit"),
2
);
assert_eq!(link.sent.len(), 2);
let first = SubmitSharesStandard::decode(&link.sent[0].payload).expect("share");
assert_eq!(first.channel_id, 9);
assert_eq!(first.sequence_number, 1);
assert_eq!(first.nonce, 0xabcd);
}
#[test]
fn share_success_reports_the_last_sequence() {
let mut session = V2Session::new(V2Channel {
channel_id: 9,
target: [0xff; 32],
extranonce_prefix: Vec::new(),
group_channel_id: 0,
});
let mut payload = Vec::new();
payload.extend_from_slice(&9_u32.to_le_bytes());
payload.extend_from_slice(&7_u32.to_le_bytes());
payload.extend_from_slice(&3_u32.to_le_bytes());
payload.extend_from_slice(&0_u64.to_le_bytes());
assert_eq!(
session
.on_frame(&Frame::new(SUBMIT_SHARES_SUCCESS, payload))
.expect("event"),
V2Event::ShareAccepted {
last_sequence: 7,
accepted: 3
}
);
}
#[test]
fn an_unknown_message_is_ignored_not_fatal() {
let mut session = V2Session::new(V2Channel {
channel_id: 9,
target: [0xff; 32],
extranonce_prefix: Vec::new(),
group_channel_id: 0,
});
assert_eq!(
session
.on_frame(&Frame::new(0x7e, vec![0; 4]))
.expect("event"),
V2Event::Ignored
);
}
}
+531
View File
@@ -0,0 +1,531 @@
// SPDX-License-Identifier: MIT
//! Adaptive tuning.
//!
//! The miner targets a power draw, a hashrate, or an operating point chosen for the ambient
//! temperature. Rather than picking a preset, a bounded PID moves the chain frequency inside the
//! profile envelope each control period, and a thermal guard can always override it downward.
//!
//! The controller is deliberately conservative: bounded output, rate limit, deadband, derivative
//! on the measurement (no setpoint kick) and conditional integration (no windup while saturated).
use crate::detect::Envelope;
/// What the operator asked for.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum TuningTarget {
/// Hold this DC power draw; efficiency follows from the power point.
PowerW(f32),
/// Maximise hashrate up to this value.
HashrateThs(f32),
/// Hold the hottest sensor this far above the measured ambient: efficiency at that ambient.
AmbientC { margin_mc: i32 },
/// Pin the fan at this duty and maximise hashrate under it.
MaxFan { max_pwm: u8 },
}
/// Controller tuning.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct PidConfig {
pub kp: f32,
pub ki: f32,
pub kd: f32,
pub out_min: f32,
pub out_max: f32,
/// Maximum output change per second.
pub max_step_per_s: f32,
/// Errors inside this band are ignored.
pub deadband: f32,
}
impl Default for PidConfig {
fn default() -> Self {
Self {
kp: 0.5,
ki: 0.1,
kd: 0.0,
out_min: 0.0,
out_max: 1_000.0,
max_step_per_s: 50.0,
deadband: 1.0,
}
}
}
/// A bounded PID with anti-windup and rate limiting.
#[derive(Clone, Debug)]
pub struct Pid {
config: PidConfig,
integral: f32,
last_measurement: Option<f32>,
output: f32,
}
impl Pid {
pub fn new(config: PidConfig, initial_output: f32) -> Self {
Self {
config,
integral: 0.0,
last_measurement: None,
output: initial_output.clamp(config.out_min, config.out_max),
}
}
pub fn output(&self) -> f32 {
self.output
}
/// Force the output (used by ramp modes and the thermal guard).
pub fn set_output(&mut self, value: f32) {
self.output = value.clamp(self.config.out_min, self.config.out_max);
}
/// Clear the integral and derivative history, keeping the current output.
/// Used on a target switch so error accumulated in one unit (watts) is not
/// injected into the next target's loop (millidegrees, TH/s).
pub fn reset_accumulator(&mut self) {
self.integral = 0.0;
self.last_measurement = None;
}
/// Advance one control period and return the new output.
pub fn update(&mut self, setpoint: f32, measurement: f32, dt_s: f32) -> f32 {
if !dt_s.is_finite() || dt_s <= 0.0 {
return self.output;
}
let error = setpoint - measurement;
if error.abs() <= self.config.deadband {
self.last_measurement = Some(measurement);
return self.output;
}
let derivative = match self.last_measurement {
Some(previous) => -(measurement - previous) / dt_s,
None => 0.0,
};
let candidate = self.config.kp * error + self.integral + self.config.kd * derivative;
let saturated = candidate > self.config.out_max || candidate < self.config.out_min;
// Conditional integration: never accumulate while the actuator is pinned in the direction
// of the error, or the loop unwinds slowly after a saturation episode.
let pinning = (candidate > self.config.out_max && error > 0.0)
|| (candidate < self.config.out_min && error < 0.0);
if !saturated || !pinning {
self.integral += self.config.ki * error * dt_s;
}
let mut desired = self.config.kp * error + self.integral + self.config.kd * derivative;
desired = desired.clamp(self.config.out_min, self.config.out_max);
let max_step = self.config.max_step_per_s * dt_s;
let step = (desired - self.output).clamp(-max_step, max_step);
self.output = (self.output + step).clamp(self.config.out_min, self.config.out_max);
self.last_measurement = Some(measurement);
self.output
}
}
/// What the loop needs to know each period.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Observation {
pub power_w: Option<f32>,
pub hashrate_ths: Option<f32>,
/// Hottest sensor in millidegrees, when telemetry is available.
pub hottest_mc: Option<i32>,
/// Intake/enclosure temperature in millidegrees, for the ambient target.
pub ambient_mc: Option<i32>,
}
/// What the loop wants applied this period.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Command {
pub frequency_mhz: u16,
/// `Some` only when the target owns the fan (max-fan mode).
pub fan_pwm: Option<u8>,
}
/// Why the loop could not produce a command.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum TuningError {
/// The measurement the target needs is missing this period.
NoMeasurement,
}
/// The tuning loop: one PID over chain frequency, bounded by the profile envelope.
#[derive(Clone, Debug)]
pub struct TuningLoop {
pid: Pid,
envelope: Envelope,
target: TuningTarget,
ceiling_mc: i32,
}
impl TuningLoop {
/// Start from the conservative floor of the envelope.
pub fn new(target: TuningTarget, envelope: Envelope, pid: PidConfig, ceiling_mc: i32) -> Self {
let config = PidConfig {
out_min: f32::from(envelope.f_min_mhz),
out_max: f32::from(envelope.f_max_mhz),
..pid
};
let start = f32::from(envelope.f_min_mhz);
Self {
pid: Pid::new(config, start),
envelope,
target,
ceiling_mc,
}
}
pub fn frequency_mhz(&self) -> u16 {
self.pid.output().round() as u16
}
/// The target the loop is currently chasing.
pub fn target(&self) -> TuningTarget {
self.target
}
/// Switch the operator target in place, keeping the operating point (the PID
/// output) so it carries over instead of jumping back to the floor, but
/// clearing the error accumulator: the old target's integral is in the old
/// target's units and must not drive the new loop. The thermal guard and
/// envelope bounds are unchanged.
pub fn set_target(&mut self, target: TuningTarget) {
if target != self.target {
self.pid.reset_accumulator();
}
self.target = target;
}
/// Fan duty implied by the target, if the target owns the fan.
fn target_fan(&self) -> Option<u8> {
match self.target {
TuningTarget::MaxFan { max_pwm } => Some(max_pwm),
_ => None,
}
}
fn command(&self) -> Command {
Command {
frequency_mhz: self.frequency_mhz(),
fan_pwm: self.target_fan(),
}
}
/// One control period. Returns the command to apply, inside the envelope.
pub fn step(&mut self, observation: Observation, dt_s: f32) -> Result<Command, TuningError> {
// Thermal guard: a hot sensor always derates, whatever the target says.
if let Some(hottest) = observation.hottest_mc {
if hottest >= self.ceiling_mc {
let derated = (self.pid.output() - 25.0).max(f32::from(self.envelope.f_min_mhz));
self.pid = Pid::new(
PidConfig {
out_min: f32::from(self.envelope.f_min_mhz),
out_max: f32::from(self.envelope.f_max_mhz),
..self.pid.config
},
derated,
);
return Ok(self.command());
}
}
match self.target {
TuningTarget::PowerW(setpoint) => {
let measurement = observation.power_w.ok_or(TuningError::NoMeasurement)?;
self.pid.update(setpoint, measurement, dt_s);
}
TuningTarget::HashrateThs(setpoint) => {
let measurement = observation.hashrate_ths.ok_or(TuningError::NoMeasurement)?;
self.pid.update(setpoint, measurement, dt_s);
}
TuningTarget::AmbientC { margin_mc } => {
let ambient = observation.ambient_mc.ok_or(TuningError::NoMeasurement)?;
let hottest = observation.hottest_mc.ok_or(TuningError::NoMeasurement)?;
let setpoint = ambient as f32 + margin_mc as f32;
self.pid.update(setpoint, hottest as f32, dt_s);
}
TuningTarget::MaxFan { .. } => {
// No setpoint loop here: ramp toward the envelope ceiling and let the thermal
// guard be the only thing that stops it.
let step = self.pid.config.max_step_per_s * dt_s;
let next = (self.pid.output() + step).min(f32::from(self.envelope.f_max_mhz));
self.pid.set_output(next);
}
}
Ok(self.command())
}
}
#[cfg(test)]
mod tests {
use super::*;
fn envelope() -> Envelope {
Envelope {
v_min_mv: 1100,
v_max_mv: 1500,
f_min_mhz: 300,
f_max_mhz: 700,
}
}
fn observation(hottest: i32) -> Observation {
Observation {
power_w: None,
hashrate_ths: None,
hottest_mc: Some(hottest),
ambient_mc: None,
}
}
#[test]
fn pid_drives_the_plant_to_the_setpoint() {
let mut pid = Pid::new(
PidConfig {
kp: 0.02,
ki: 0.01,
kd: 0.0,
out_min: 0.0,
out_max: 700.0,
max_step_per_s: 1_000.0,
deadband: 0.0,
},
0.0,
);
// Plant: 5 W per MHz, so 3 kW needs 600 MHz, inside the controller ceiling.
let mut power = 0.0_f32;
for _ in 0..400 {
let freq = pid.update(3_000.0, power, 1.0);
power = 5.0 * freq;
}
assert!((power - 3_000.0).abs() < 50.0, "power settled at {power}");
}
#[test]
fn output_is_rate_limited() {
let mut pid = Pid::new(
PidConfig {
kp: 1.0,
ki: 0.0,
kd: 0.0,
out_min: 0.0,
out_max: 1_000.0,
max_step_per_s: 10.0,
deadband: 0.0,
},
0.0,
);
assert!((pid.update(1_000.0, 0.0, 1.0) - 10.0).abs() < f32::EPSILON);
assert!((pid.update(1_000.0, 0.0, 1.0) - 20.0).abs() < f32::EPSILON);
}
#[test]
fn deadband_holds_the_output() {
let mut pid = Pid::new(
PidConfig {
kp: 1.0,
ki: 0.1,
kd: 0.0,
out_min: 0.0,
out_max: 1_000.0,
max_step_per_s: 100.0,
deadband: 5.0,
},
100.0,
);
let before = pid.output();
assert!((pid.update(102.0, 100.0, 1.0) - before).abs() < f32::EPSILON);
}
#[test]
fn saturation_does_not_wind_up_the_integral() {
let mut pid = Pid::new(
PidConfig {
kp: 1.0,
ki: 1.0,
kd: 0.0,
out_min: 0.0,
out_max: 100.0,
max_step_per_s: 1_000.0,
deadband: 0.0,
},
0.0,
);
for _ in 0..100 {
pid.update(1_000.0, 0.0, 1.0);
}
assert!((pid.output() - 100.0).abs() < 0.01);
for _ in 0..5 {
pid.update(0.0, 200.0, 1.0);
}
assert!(
pid.output() < 99.0,
"output stuck at the rail: {}",
pid.output()
);
}
#[test]
fn power_target_moves_frequency_inside_the_envelope() {
let mut loop_ = TuningLoop::new(
TuningTarget::PowerW(2_400.0),
envelope(),
PidConfig {
kp: 0.2,
ki: 0.05,
kd: 0.0,
out_min: 0.0,
out_max: 0.0,
max_step_per_s: 50.0,
deadband: 0.0,
},
95_000,
);
let mut freq = loop_.frequency_mhz();
for _ in 0..100 {
let power = 4.0 * f32::from(freq);
let mut obs = observation(70_000);
obs.power_w = Some(power);
freq = loop_.step(obs, 1.0).expect("step").frequency_mhz;
assert!((300..=700).contains(&freq), "out of envelope: {freq}");
}
let power = 4.0 * f32::from(freq);
assert!((power - 2_400.0).abs() < 200.0, "power settled at {power}");
}
#[test]
fn thermal_guard_derates_regardless_of_target() {
let mut loop_ = TuningLoop::new(
TuningTarget::HashrateThs(200.0),
envelope(),
PidConfig::default(),
90_000,
);
for _ in 0..50 {
let mut obs = observation(60_000);
obs.hashrate_ths = Some(10.0);
loop_.step(obs, 1.0).expect("step");
}
let hot = loop_.frequency_mhz();
let mut obs = observation(91_000);
obs.hashrate_ths = Some(10.0);
let derated = loop_.step(obs, 1.0).expect("step").frequency_mhz;
assert!(
derated < hot,
"thermal guard did not derate: {derated} vs {hot}"
);
}
#[test]
fn missing_measurement_is_an_error() {
let mut loop_ = TuningLoop::new(
TuningTarget::PowerW(3_000.0),
envelope(),
PidConfig::default(),
95_000,
);
let mut obs = observation(50_000);
obs.hashrate_ths = Some(1.0);
assert_eq!(loop_.step(obs, 1.0), Err(TuningError::NoMeasurement));
}
#[test]
fn zero_dt_holds_the_output() {
let mut pid = Pid::new(PidConfig::default(), 42.0);
assert!((pid.update(100.0, 0.0, 0.0) - 42.0).abs() < f32::EPSILON);
}
#[test]
fn ambient_target_holds_the_hottest_sensor_near_ambient_plus_margin() {
let mut loop_ = TuningLoop::new(
TuningTarget::AmbientC { margin_mc: 20_000 },
envelope(),
PidConfig {
kp: 0.5,
ki: 0.05,
kd: 0.0,
out_min: 0.0,
out_max: 0.0,
max_step_per_s: 50.0,
deadband: 0.0,
},
200_000,
);
// Plant: hottest = ambient + 50 mC per MHz.
let ambient = 40_000;
let mut freq = loop_.frequency_mhz();
for _ in 0..300 {
let hottest = ambient + 50 * i32::from(freq);
let obs = Observation {
power_w: None,
hashrate_ths: None,
hottest_mc: Some(hottest),
ambient_mc: Some(ambient),
};
freq = loop_.step(obs, 1.0).expect("step").frequency_mhz;
}
let hottest = ambient + 50 * i32::from(freq);
assert!(
(hottest - (ambient + 20_000)).abs() < 2_000,
"hottest settled at {hottest}"
);
}
#[test]
fn ambient_target_needs_an_ambient_sensor() {
let mut loop_ = TuningLoop::new(
TuningTarget::AmbientC { margin_mc: 20_000 },
envelope(),
PidConfig::default(),
95_000,
);
assert_eq!(
loop_.step(observation(50_000), 1.0),
Err(TuningError::NoMeasurement)
);
}
#[test]
fn max_fan_mode_pins_the_fan_and_ramps_frequency() {
let ramp = PidConfig {
kp: 1.0,
ki: 0.0,
kd: 0.0,
out_min: 0.0,
out_max: 0.0,
max_step_per_s: 50.0,
deadband: 0.0,
};
let mut loop_ = TuningLoop::new(
TuningTarget::MaxFan { max_pwm: 100 },
envelope(),
ramp,
120_000,
);
let start = loop_.frequency_mhz();
let mut last = start;
for _ in 0..20 {
let command = loop_.step(observation(70_000), 1.0).expect("step");
assert_eq!(command.fan_pwm, Some(100));
last = command.frequency_mhz;
}
assert!(last > start, "frequency did not ramp: {last} vs {start}");
assert!(
last == 700,
"ramp did not reach the envelope ceiling: {last}"
);
}
#[test]
fn max_fan_mode_still_respects_the_temperature_ceiling() {
let mut loop_ = TuningLoop::new(
TuningTarget::MaxFan { max_pwm: 100 },
envelope(),
PidConfig::default(),
80_000,
);
for _ in 0..50 {
loop_.step(observation(70_000), 1.0).expect("step");
}
let hot = loop_.frequency_mhz();
let command = loop_.step(observation(85_000), 1.0).expect("step");
assert!(command.frequency_mhz < hot);
assert_eq!(command.fan_pwm, Some(100));
}
}
+736
View File
@@ -0,0 +1,736 @@
// SPDX-License-Identifier: MIT
//! On-box web UI: navigation, pages, and the editable dashboard document.
//!
//! The shape follows the Warden/FLARE console: a fixed sidebar of groups and
//! items, hash-routed pages, and dashboards that are a JSON document an operator
//! edits in place. The document is stored on the box, has a default template per
//! deck, and is capped server-side so a bad save cannot grow without bound.
//!
//! The JSON API remains the interface of record: every value the pages show is
//! also available at an `/api/...` route, and the page never becomes the only
//! way to see or change the machine.
use serde_json::{json, Value};
/// Blocks a dashboard may hold. Docker rows count too, so a tidy layout cannot
/// cost an operator a widget.
pub const BLOCK_CAP: usize = 32;
/// Characters allowed in a dashboard name.
pub const NAME_MAX: usize = 120;
/// One navigable destination.
pub struct Item {
pub path: &'static str,
pub label: &'static str,
}
/// A sidebar group.
pub struct Group {
pub label: &'static str,
pub items: &'static [Item],
}
const DASHBOARD: [Item; 1] = [Item {
path: "/",
label: "Dashboard",
}];
const MINING: [Item; 4] = [
Item {
path: "/mining",
label: "Overview",
},
Item {
path: "/mining/hashboards",
label: "Hashboards",
},
Item {
path: "/mining/power",
label: "Power Supply",
},
Item {
path: "/mining/fans",
label: "Fans",
},
];
const SETTINGS: [Item; 8] = [
Item {
path: "/settings/system",
label: "System",
},
Item {
path: "/settings/drivers",
label: "Drivers",
},
Item {
path: "/settings/security",
label: "Security",
},
Item {
path: "/settings/services",
label: "Services",
},
Item {
path: "/settings/monitor",
label: "Monitor",
},
Item {
path: "/settings/logs",
label: "Logs",
},
Item {
path: "/settings/files",
label: "Files",
},
Item {
path: "/settings/terminal",
label: "Terminal",
},
];
pub const NAV: [Group; 3] = [
Group {
label: "Overview",
items: &DASHBOARD,
},
Group {
label: "Mining",
items: &MINING,
},
Group {
label: "Settings",
items: &SETTINGS,
},
];
/// The dashboard a deck starts with. Every deck has one, so a fresh box is never
/// an empty page.
pub fn default_deck(deck: &str) -> Value {
match deck {
"overview" => json!({
"version": 1,
"name": "Mining overview",
"blocks": [
{"id": "status", "kind": "status", "span": 1, "title": "State", "source": "status"},
{"id": "accepted", "kind": "metric", "span": 1, "title": "Accepted", "source": "accepted", "unit": "shares"},
{"id": "rejected", "kind": "metric", "span": 1, "title": "Rejected", "source": "rejected", "unit": "shares"},
{"id": "elapsed", "kind": "metric", "span": 1, "title": "Uptime", "source": "elapsed", "unit": "s"},
{"id": "chains", "kind": "metric", "span": 1, "title": "Active chains", "source": "active_chains", "unit": ""},
{"id": "frequency", "kind": "metric", "span": 1, "title": "Frequency", "source": "frequency", "unit": "MHz"},
{"id": "voltage", "kind": "metric", "span": 1, "title": "Voltage", "source": "voltage", "unit": "mV"},
{"id": "target", "kind": "metric", "span": 1, "title": "Target", "source": "target", "unit": ""},
{"id": "chains_table", "kind": "table", "span": 4, "title": "Hashboards", "source": "chains"}
]
}),
_ => json!({
"version": 1,
"name": "Dashboard",
"blocks": [
{"id": "status", "kind": "status", "span": 2, "title": "Miner", "source": "status"},
{"id": "accepted", "kind": "metric", "span": 1, "title": "Accepted", "source": "accepted", "unit": "shares"},
{"id": "rejected", "kind": "metric", "span": 1, "title": "Rejected", "source": "rejected", "unit": "shares"},
{"id": "hardware", "kind": "kv", "span": 2, "title": "Hardware", "source": "hardware"},
{"id": "fans", "kind": "table", "span": 2, "title": "Fan map", "source": "fans"}
]
}),
}
}
/// Validate a dashboard document the client wants to store.
///
/// Returns the parsed document, or a sentence naming the rule that failed. The
/// rules are the same ones the page enforces, so a save that the UI allowed is
/// never rejected here for a reason the operator cannot see.
pub fn validate_deck(text: &str) -> Result<Value, String> {
let doc: Value =
serde_json::from_str(text).map_err(|_| "document is not valid JSON".to_string())?;
let object = doc.as_object().ok_or("document must be an object")?;
let version = object
.get("version")
.and_then(Value::as_u64)
.ok_or("version must be a number")?;
if version != 1 {
return Err(format!("unsupported version {version}"));
}
if let Some(name) = object.get("name") {
let name = name.as_str().ok_or("name must be a string")?;
if name.chars().count() > NAME_MAX {
return Err(format!("name is longer than {NAME_MAX} characters"));
}
}
let blocks = object
.get("blocks")
.and_then(Value::as_array)
.ok_or("blocks must be a list")?;
if blocks.len() > BLOCK_CAP {
return Err(format!("more than {BLOCK_CAP} blocks"));
}
for block in blocks {
let block = block.as_object().ok_or("each block must be an object")?;
let id = block
.get("id")
.and_then(Value::as_str)
.ok_or("block id must be a string")?;
if id.is_empty() || id.len() > 64 {
return Err("block id must be 1..=64 characters".to_string());
}
let kind = block
.get("kind")
.and_then(Value::as_str)
.ok_or("block kind must be a string")?;
if !["metric", "status", "kv", "table", "text"].contains(&kind) {
return Err(format!("unknown block kind {kind}"));
}
let span = block.get("span").and_then(Value::as_u64).unwrap_or(1);
if !(1..=4).contains(&span) {
return Err("block span must be 1..=4".to_string());
}
}
Ok(doc)
}
/// Render one page inside the shell.
///
/// The rail follows the FLARE/Warden console: a 232px navy column with a 44px
/// head, one native `<details>` per group so the tree opens and closes with no
/// script, and the current page marked with `aria-current` rather than a class
/// alone. Below 901px it slides off-canvas and comes back as a `:target`
/// fragment, which is the one disclosure a locked-down page can still use.
pub fn page(active: &str, title: &str, body: &str) -> String {
format!(
"<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\">\
<meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\
<title>{title} - Alkane</title><style>{CSS}</style></head>\
<body class=\"shell\"><aside class=\"rail\" id=\"rail\">{rail_head}{nav}</aside><div class=\"rail-backdrop\" id=\"rail-backdrop\"></div>\
<main class=\"content\"><header class=\"appbar\">\
<a class=\"appbar__menu\" href=\"#rail\" aria-label=\"Open menu\">Menu</a>\
<h1 class=\"page-title\">{title}</h1><span id=\"live\" class=\"pill\">connecting</span></header>\
<div class=\"frame\">{body}</div></main>\
<script>{JS}</script></body></html>",
title = escape(title),
rail_head = rail_head(),
nav = sidebar(active),
)
}
fn rail_head() -> String {
"<div class=\"rail__head\"><span class=\"rail__brand\">Alkane</span>\
<button class=\"rail__toggle\" type=\"button\" aria-label=\"Collapse sidebar\" title=\"Collapse sidebar\">&#9776;</button>\
<a class=\"rail__close\" href=\"#\" aria-label=\"Close menu\" title=\"Close menu\">&#10005;</a></div>"
.to_string()
}
/// An 18px stroke icon for a destination, matching the rail's icon column.
fn icon(path: &str) -> &'static str {
let body = match path {
"/" => "<rect x=\"3\" y=\"3\" width=\"7\" height=\"7\" rx=\"1\"/><rect x=\"14\" y=\"3\" width=\"7\" height=\"7\" rx=\"1\"/><rect x=\"3\" y=\"14\" width=\"7\" height=\"7\" rx=\"1\"/><rect x=\"14\" y=\"14\" width=\"7\" height=\"7\" rx=\"1\"/>",
"/mining" => "<path d=\"M4 20V10M10 20V4M16 20v-7M22 20H2\"/>",
"/mining/hashboards" => "<rect x=\"5\" y=\"5\" width=\"14\" height=\"14\" rx=\"2\"/><path d=\"M9 2v3M15 2v3M9 19v3M15 19v3M2 9h3M2 15h3M19 9h3M19 15h3\"/>",
"/mining/power" => "<path d=\"M13 2 4 14h7l-1 8 9-12h-7z\"/>",
"/mining/fans" => "<circle cx=\"12\" cy=\"12\" r=\"2\"/><path d=\"M12 10c0-4 1-7 4-7 2 0 3 2 3 4 0 3-3 5-7 5M14 12c4 0 7 1 7 4 0 2-2 3-4 3-3 0-5-3-5-7M12 14c0 4-1 7-4 7-2 0-3-2-3-4 0-3 3-5 7-5M10 12c-4 0-7-1-7-4 0-2 2-3 4-3 3 0 5 3 5 7\"/>",
"/settings/system" => "<rect x=\"3\" y=\"4\" width=\"18\" height=\"6\" rx=\"1\"/><rect x=\"3\" y=\"14\" width=\"18\" height=\"6\" rx=\"1\"/><path d=\"M7 7h.01M7 17h.01\"/>",
"/settings/drivers" => "<rect x=\"4\" y=\"4\" width=\"16\" height=\"16\" rx=\"2\"/><path d=\"M9 9h6v6H9z\"/>",
"/settings/security" => "<rect x=\"4\" y=\"10\" width=\"16\" height=\"10\" rx=\"2\"/><path d=\"M8 10V7a4 4 0 0 1 8 0v3\"/>",
"/settings/services" => "<circle cx=\"12\" cy=\"12\" r=\"9\"/><path d=\"M10 8l6 4-6 4z\"/>",
"/settings/monitor" => "<path d=\"M2 12h4l3-8 4 16 3-8h6\"/>",
"/settings/logs" => "<path d=\"M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z\"/><path d=\"M14 2v6h6M8 13h8M8 17h5\"/>",
"/settings/files" => "<path d=\"M3 7a2 2 0 0 1 2-2h5l2 2h7a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z\"/>",
"/settings/terminal" => "<rect x=\"3\" y=\"4\" width=\"18\" height=\"16\" rx=\"2\"/><path d=\"M7 9l3 3-3 3M13 15h4\"/>",
_ => "<circle cx=\"12\" cy=\"12\" r=\"9\"/>",
};
// The strings above are static markup, never user input.
let html = format!(
"<svg class=\"rail__icon\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" \
stroke-width=\"1.7\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\">{body}</svg>"
);
Box::leak(html.into_boxed_str())
}
fn group_icon_svg(label: &str) -> &'static str {
let body = match label {
"Mining" => "<rect x=\"5\" y=\"5\" width=\"14\" height=\"14\" rx=\"2\"/><path d=\"M9 2v3M15 2v3M9 19v3M15 19v3M2 9h3M2 15h3M19 9h3M19 15h3\"/>",
"Settings" => "<circle cx=\"12\" cy=\"12\" r=\"3\"/><path d=\"M19.4 15a1.7 1.7 0 0 0 .3 1.9l.1.1a2 2 0 1 1-2.8 2.8l-.1-.1a1.7 1.7 0 0 0-1.9-.3 1.7 1.7 0 0 0-1 1.5V21a2 2 0 1 1-4 0v-.1a1.7 1.7 0 0 0-1.1-1.5 1.7 1.7 0 0 0-1.9.3l-.1.1a2 2 0 1 1-2.8-2.8l.1-.1a1.7 1.7 0 0 0 .3-1.9 1.7 1.7 0 0 0-1.5-1H3a2 2 0 1 1 0-4h.1A1.7 1.7 0 0 0 4.6 9a1.7 1.7 0 0 0-.3-1.9l-.1-.1a2 2 0 1 1 2.8-2.8l.1.1a1.7 1.7 0 0 0 1.9.3H9a1.7 1.7 0 0 0 1-1.5V3a2 2 0 1 1 4 0v.1a1.7 1.7 0 0 0 1 1.5 1.7 1.7 0 0 0 1.9-.3l.1-.1a2 2 0 1 1 2.8 2.8l-.1.1a1.7 1.7 0 0 0-.3 1.9V9a1.7 1.7 0 0 0 1.5 1H21a2 2 0 1 1 0 4h-.1a1.7 1.7 0 0 0-1.5 1z\"/>",
_ => "",
};
if body.is_empty() {
return "";
}
let html = format!(
"<svg class=\"rail__icon\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" \
stroke-width=\"1.7\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\">{body}</svg>"
);
Box::leak(html.into_boxed_str())
}
fn sidebar(active: &str) -> String {
let mut out = String::from("<nav class=\"rail__nav\">");
let mut first = true;
for group in NAV.iter() {
// A one-item group is a plain link, exactly as the FLARE rail renders
// Dashboard: a disclosure around a single leaf is a control that only
// hides the thing it names.
if group.items.len() == 1 {
let item = &group.items[0];
out.push_str(&rail_link(item, active, "rail__link"));
} else {
let open = group.items.iter().any(|item| item.path == active);
out.push_str(&format!(
"<details class=\"tree\"{open}>\
<summary class=\"rail__link tree__summary\">{icon}<span class=\"rail__label\">{label}</span><span class=\"rail__chevron\" aria-hidden=\"true\"></span></summary>\
<ul class=\"tree__list\">",
open = if open { " open" } else { "" },
label = escape(group.label),
icon = group_icon_svg(group.label),
));
for item in group.items {
out.push_str(&rail_link(item, active, "rail__link tree__leaf"));
}
out.push_str("</ul></details>");
}
first = false;
}
let _ = first;
out.push_str("</nav>");
out
}
fn rail_link(item: &Item, active: &str, class: &str) -> String {
let current = if item.path == active {
" aria-current=\"page\""
} else {
""
};
format!(
"<a class=\"{class}\" href=\"#{path}\"{current}>{icon}<span class=\"rail__label\">{label}</span></a>",
class = class,
path = item.path,
label = escape(item.label),
icon = icon(item.path),
)
}
/// A dashboard page: the editor chrome plus the document the client loads.
pub fn dashboard_page(deck: &str, editable: bool) -> String {
let deck = escape(deck);
format!(
"<div class=\"bar\">\
<label>Template <select id=\"deck-name\"></select></label>\
<button id=\"save\"{disabled}>Save</button>\
<button id=\"reset\"{disabled}>Reset to template</button>\
<button id=\"add\"{disabled}>Add block</button>\
<span id=\"edit-msg\" class=\"muted\"></span></div>\
<div id=\"grid\" class=\"grid\" data-deck=\"{deck}\" data-editable=\"{editable}\"></div>",
disabled = if editable { "" } else { " disabled" },
editable = if editable { "1" } else { "0" },
)
}
/// Escape text for HTML. Every user-visible string goes through this.
pub fn escape(text: &str) -> String {
let mut out = String::with_capacity(text.len());
for ch in text.chars() {
match ch {
'&' => out.push_str("&amp;"),
'<' => out.push_str("&lt;"),
'>' => out.push_str("&gt;"),
'"' => out.push_str("&quot;"),
'\'' => out.push_str("&#39;"),
other => out.push(other),
}
}
out
}
/// A definition-list page for key/value data (settings pages).
pub fn kv_page(rows: &[(&str, String)]) -> String {
let mut out = String::from("<table class=\"kv\"><tbody>");
for (key, value) in rows {
out.push_str(&format!(
"<tr><th>{}</th><td>{}</td></tr>",
escape(key),
escape(value)
));
}
out.push_str("</tbody></table>");
out
}
/// Several titled sections in one page: the settings pages' shape in the
/// Warden console, where each group (Identity, Network, ...) is its own block.
pub fn sections_page(sections: &[(&str, String)]) -> String {
let mut out = String::new();
for (title, body) in sections {
out.push_str(&format!(
"<section class=\"section\"><h2 class=\"section__title\">{}</h2>{}</section>",
escape(title),
body
));
}
out
}
/// A table page with a header row.
pub fn table_page(headers: &[&str], rows: &[Vec<String>]) -> String {
let mut out = String::from("<table><thead><tr>");
for header in headers {
out.push_str(&format!("<th>{}</th>", escape(header)));
}
out.push_str("</tr></thead><tbody>");
for row in rows {
out.push_str("<tr>");
for cell in row {
out.push_str(&format!("<td>{}</td>", escape(cell)));
}
out.push_str("</tr>");
}
if rows.is_empty() {
out.push_str(&format!(
"<tr><td colspan=\"{}\" class=\"muted\">nothing to show</td></tr>",
headers.len().max(1)
));
}
out.push_str("</tbody></table>");
out
}
const CSS: &str = r#"
:root{
color-scheme:dark;
/* FLARE tokens: navy scale, cyan action, the same steps portal.css uses. */
--navy-900:#070D1D; --navy-800:#0B1020; --navy-700:#192858; --navy-600:#1E4E90;
--cyan-400:#3ABCF8; --cyan-500:#31A2D6; --orange-500:#F26522;
--text:#FFFFFF; --text-muted:#BABABA;
--border:#192858;
--space-1:4px; --space-2:8px; --space-3:12px; --space-4:16px; --space-6:24px;
--font-display:'Creato Display','Sora','Segoe UI','Selawik',system-ui,-apple-system,sans-serif;
--font-body:'Segoe UI','Selawik',system-ui,-apple-system,sans-serif;
--text-xs:12px; --text-sm:14px; --text-base:16px;
}
*{box-sizing:border-box}
body.shell{margin:0;display:flex;min-height:100vh;background:var(--navy-900);color:var(--text);
font:var(--text-sm)/1.45 var(--font-body)}
a{color:var(--cyan-400);text-decoration:none}
:focus-visible{outline:2px solid var(--cyan-400);outline-offset:2px}
/* --- rail: the Warden console's sidebar ------------------------------- */
.rail{flex:none;width:232px;background:var(--navy-700);border-right:1px solid #1E2A4E;
display:flex;flex-direction:column;position:sticky;top:0;height:100vh;overflow-y:auto;
overscroll-behavior:contain}
.rail__head{display:flex;align-items:center;gap:var(--space-2);min-height:44px;
padding:0 var(--space-3);border-bottom:1px solid #1E2A4E}
.rail__brand{font-family:var(--font-display);font-weight:700;font-size:var(--text-base);
letter-spacing:.02em}
.rail__nav{padding:var(--space-2) 0;display:flex;flex-direction:column}
.rail__link{display:flex;align-items:center;gap:var(--space-3);min-height:36px;
padding:var(--space-2) var(--space-4);color:#E6ECF5;font-size:var(--text-sm);font-weight:600;
border-left:2px solid transparent;min-width:0}
.rail__link:hover{background:rgba(255,255,255,.06)}
.rail__link[aria-current='page']{border-left-color:var(--cyan-400);color:var(--cyan-400);
background:rgba(255,255,255,.06)}
.tree>summary{list-style:none;cursor:pointer}
.tree>summary::-webkit-details-marker{display:none}
.rail__chevron{margin-left:auto;width:0;height:0;border-left:4px solid transparent;
border-right:4px solid transparent;border-top:5px solid #9AA5BB}
.tree[open]>summary .rail__chevron{transform:rotate(180deg)}
.tree__list{list-style:none;margin:0;padding:0}
.tree__leaf{font-weight:400;color:#9AA5BB;min-height:32px;
padding-left:calc(var(--space-4) + var(--space-3))}
.tree__leaf:hover{color:#E6ECF5}
.tree__leaf[aria-current='page']{color:var(--cyan-400);font-weight:600}
.rail a:focus-visible,.rail summary:focus-visible{outline-offset:-2px}
.rail__icon{width:18px;height:18px;flex:none}
.rail__label{white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
.rail__toggle{margin-left:auto;background:transparent;border:0;color:#9AA5BB;cursor:pointer;
padding:4px;font-size:14px;line-height:1}
.rail__toggle:hover{color:#E6ECF5}
/* Collapsed: icons only, and only where the rail is docked. Labels are clipped
rather than removed so they keep their accessible name. */
@media (min-width:901px){
.shell--collapsed .rail{width:41px}
.shell--collapsed .rail__label,
.shell--collapsed .rail__brand{position:absolute;width:1px;height:1px;overflow:hidden;
clip-path:inset(50%);white-space:nowrap}
.shell--collapsed .tree__list,
.shell--collapsed .rail__chevron{display:none}
.shell--collapsed .rail__link{justify-content:center;padding-left:0;padding-right:2px}
.shell--collapsed .rail__head{justify-content:center;padding-inline:0}
}
/* --- content column ---------------------------------------------------- */
.content{flex:1;min-width:0;display:flex;flex-direction:column}
.appbar{display:flex;align-items:center;gap:var(--space-4);min-height:44px;
padding:0 var(--space-6);border-bottom:1px solid var(--border);
position:sticky;top:0;z-index:40;background:var(--navy-900)}
.page-title{font-family:var(--font-display);font-size:22px;font-weight:700;line-height:1.1;
margin:0;letter-spacing:-.01em}
.appbar__menu{display:none;font-size:var(--text-sm);color:var(--cyan-400)}
.pill{border-radius:0;margin-left:auto;font-size:var(--text-xs);padding:3px 9px;
background:var(--navy-800);color:var(--text-muted);border:1px solid var(--border)}
.pill.ok{color:#7EE787;border-color:#1F4D2C}
.pill.bad{color:#FF9B9B;border-color:#552323}
.frame{padding:var(--space-6);display:flex;flex-direction:column;gap:var(--space-6)}
/* --- blocks ------------------------------------------------------------ */
.bar{display:flex;gap:var(--space-3);align-items:center;flex-wrap:wrap}
h2,.card h2{font-family:var(--font-display);font-size:11px;font-weight:600;line-height:1.15;
text-transform:uppercase;letter-spacing:2px;color:var(--text-muted);margin:0 0 var(--space-2)}
button{border-radius:0;font:inherit;cursor:pointer;padding:7px 12px;
background:var(--navy-700);color:var(--text);border:1px solid #1E2A4E}
button:hover:not(:disabled){background:var(--navy-600)}
button:disabled{opacity:.4;cursor:default}
select,input[type=text]{border-radius:0;font:inherit;color:var(--text);background:var(--navy-900);
border:1px solid #1E2A4E;padding:6px 8px}
input[type=text]{min-width:320px;padding:8px 10px}
.grid{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:var(--space-4)}
.card{background:var(--navy-800);border:1px solid var(--border);border-radius:0;
padding:var(--space-4);min-height:96px}
.card.drag{outline:1px dashed var(--cyan-400);outline-offset:2px}
.card .big{font-family:var(--font-display);font-size:28px;font-weight:700;letter-spacing:-.5px}
.card .unit{font-size:var(--text-xs);color:var(--text-muted);margin-left:var(--space-1)}
.span2{grid-column:span 2}.span3{grid-column:span 3}.span4{grid-column:span 4}
table{width:100%;border-collapse:collapse;font-size:var(--text-sm)}
th,td{text-align:left;padding:8px 10px;border-bottom:1px solid #14203C}
th{font-family:var(--font-display);font-size:11px;font-weight:600;text-transform:uppercase;
letter-spacing:2px;color:var(--text-muted)}
table.kv th{width:220px;color:var(--text-muted);font-weight:600;text-transform:none;
letter-spacing:0;font-family:var(--font-body);font-size:var(--text-sm)}
.muted{color:var(--text-muted)}
.section{display:flex;flex-direction:column;gap:var(--space-2)}
.section__title{font-family:var(--font-display);font-size:11px;font-weight:600;line-height:1.15;
text-transform:uppercase;letter-spacing:2px;color:var(--text-muted);margin:0;
padding-bottom:var(--space-2);border-bottom:1px solid var(--border)}
pre{background:var(--navy-900);border:1px solid var(--border);border-radius:0;
padding:var(--space-4);overflow:auto;max-height:60vh;
font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace}
/* Off-canvas below 901px, reopened by the fragment so it works without a
script, exactly as portal.css does it. */
.rail__close{display:none;margin-left:var(--space-2);background:transparent;border:0;
color:#9AA5BB;font-size:16px;line-height:1;padding:6px;cursor:pointer}
.rail__close:hover{color:#E6ECF5}
.rail-backdrop{display:none}
@media (max-width:900px){
.shell{display:block}
/* Full-screen drawer, as the design's mobile menu: page background, its own
top bar with the brand and a close, rows split by 1px dividers. */
.rail{position:fixed;inset:0;width:100%;max-width:none;transform:translateX(-100%);
z-index:60;background:var(--navy-900);border-right:0}
.rail:target{transform:none}
body.drawer-open .rail{transform:none}
body.drawer-open{overflow:hidden}
body.drawer-open .rail-backdrop{display:block;position:fixed;inset:0;background:rgba(0,0,0,.6);z-index:55}
.rail__head{min-height:56px;padding:0 var(--space-4);border-bottom:1px solid var(--border)}
.rail__brand{font-size:18px}
.rail__toggle{display:none}
.rail__close{display:inline-flex}
.rail__link{padding:var(--space-4);border-bottom:1px solid var(--border);border-left:0}
.rail__link[aria-current='page']{border-left:0;background:rgba(255,255,255,.06)}
.tree__leaf{padding:var(--space-4) var(--space-4) var(--space-4) calc(var(--space-4) * 2);min-height:48px}
.appbar__menu{display:inline-flex}
.appbar{padding:0 var(--space-4)}
.frame{padding:var(--space-4)}
.grid{grid-template-columns:1fr}
.span2,.span3,.span4{grid-column:span 1}
}
"#;
const JS: &str = r#"
(function(){
"use strict";
function $(id){return document.getElementById(id)}
function esc(s){return String(s).replace(/[&<>"']/g,function(c){return {'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]})}
function route(){var p=location.hash.slice(1)||"/";return p}
function go(){location.hash=route()}
// Live status pill: the page is a convenience over the JSON API.
function poll(){fetch("/api/summary").then(function(r){return r.json()}).then(function(d){
var el=$("live"); if(!el)return; var m=(d.miner||d); el.textContent=(m.state||"up"); el.className="pill ok";
}).catch(function(){var el=$("live"); if(el){el.textContent="offline"; el.className="pill bad"}})}
setInterval(poll,5000); poll();
// Mobile drawer. The rail is full-screen below 901px; Menu opens it and the
// close control, the backdrop or Escape puts it away. Without a script the
// :target fragment still opens it, which is why the Menu link is an anchor.
(function(){
var body=document.body;
var menu=document.querySelector(".appbar__menu");
var close=document.querySelector(".rail__close");
var backdrop=document.getElementById("rail-backdrop");
function open(){body.classList.add("drawer-open")}
function shut(){body.classList.remove("drawer-open")}
if(menu)menu.addEventListener("click",function(e){e.preventDefault();open()});
if(close)close.addEventListener("click",function(e){e.preventDefault();shut()});
if(backdrop)backdrop.addEventListener("click",shut);
document.addEventListener("keydown",function(e){if(e.key==="Escape")shut()});
document.querySelectorAll(".rail__link").forEach(function(link){
link.addEventListener("click",function(){shut()});
});
})();
// Rail collapse. The state is remembered so a reload keeps the operator's
// choice; the button is the only control that needs a script.
(function(){
var key="alkane.rail.collapsed";
try{if(localStorage.getItem(key)==="1")document.body.classList.add("shell--collapsed")}catch(e){}
var toggle=document.querySelector(".rail__toggle");
if(toggle)toggle.addEventListener("click",function(){
var on=document.body.classList.toggle("shell--collapsed");
try{localStorage.setItem(key,on?"1":"0")}catch(e){}
});
})();
var grid=$("grid");
if(grid){
var deck=grid.dataset.deck, editable=grid.dataset.editable==="1", doc=null, dragId=null;
var METRICS={hashrate:["TH/s",1],power_w:["W",1],chains:["",0],chip_temp_c:["C",0],fans:["",0]};
function render(){
grid.innerHTML="";
(doc.blocks||[]).forEach(function(b){
var card=document.createElement("div");
card.className="card span"+(b.span||1);
card.draggable=editable;
card.addEventListener("dragstart",function(){dragId=b.id;card.classList.add("drag")});
card.addEventListener("dragend",function(){card.classList.remove("drag")});
card.addEventListener("dragover",function(e){e.preventDefault()});
card.addEventListener("drop",function(e){e.preventDefault(); if(!dragId||dragId===b.id)return;
var from=doc.blocks.findIndex(function(x){return x.id===dragId});
var to=doc.blocks.findIndex(function(x){return x.id===b.id});
if(from<0||to<0)return; var moved=doc.blocks.splice(from,1)[0]; doc.blocks.splice(to,0,moved); render(); msg("unsaved changes")});
var h=document.createElement("h2"); h.textContent=b.title||b.id; card.appendChild(h);
if(b.kind==="metric"||b.kind==="status"){
var big=document.createElement("div"); big.className="big"; big.textContent="--";
big.dataset.source=b.source||""; card.appendChild(big);
if(b.unit){var u=document.createElement("span"); u.className="unit"; u.textContent=b.unit; card.appendChild(u)}
} else if(b.kind==="table"){
var t=document.createElement("table");
t.dataset[b.source==="fans"?"fans":"table"]=b.source||"";
t.innerHTML="<tbody><tr><td class='muted'>loading</td></tr></tbody>";
card.appendChild(t);
} else {
var p=document.createElement("div"); p.className="muted"; p.dataset.kv=b.source||""; p.textContent="loading"; card.appendChild(p);
}
grid.appendChild(card);
});
}
function msg(text){var el=$("edit-msg"); if(el)el.textContent=text}
function fill(){
var hw=null, sm=null;
function paint(){
if(!hw||!sm)return;
var s=(sm.SUMMARY||[{}])[0];
var src={
status:(s.Status||"unknown"),
accepted:(s.Accepted||0),
rejected:(s.Rejected||0),
elapsed:(s.Elapsed||0),
active_chains:(hw.active_chains||[]).length,
frequency:(hw.frequency_mhz||0),
voltage:((hw.operating_point||{}).voltage_mv||0),
target:(hw.target||"-")
};
document.querySelectorAll("[data-source]").forEach(function(el){
var v=src[el.dataset.source];
if(v===undefined||v===null){el.textContent="not reported"; el.classList.add("muted"); return}
el.textContent=String(v);
});
document.querySelectorAll("[data-table]").forEach(function(t){
var rows=(hw.chains||[]).map(function(c){return [c.index,c.chip,c.chips_found,JSON.stringify(c.eeprom),c.response_per_mille]});
if(!rows.length){t.innerHTML="<tbody><tr><td class='muted'>no chains reported</td></tr></tbody>";return}
t.innerHTML="<thead><tr><th>#</th><th>chip</th><th>chips</th><th>eeprom</th><th>response</th></tr></thead><tbody>"+
rows.map(function(r){return "<tr>"+r.map(function(c){return "<td>"+esc(c)+"</td>"}).join("")+"</tr>"}).join("")+"</tbody>";
});
document.querySelectorAll("[data-kv]").forEach(function(el){
var rows=[["profile",hw.profile||"-"],["chip",hw.chip||"-"],["psu",hw.psu||"-"],["target",hw.target||"-"],["stopped",hw.stopped?hw.stopped:"no"]];
el.innerHTML=rows.map(function(r){return "<div><span class='muted'>"+esc(r[0])+"</span> "+esc(r[1])+"</div>"}).join("");
});
document.querySelectorAll("[data-fans]").forEach(function(t){
var rows=(hw.fan_zones||[]).map(function(z){return [z.fan,(z.zones||[]).join(", ")]});
if(!rows.length){t.innerHTML="<tbody><tr><td class='muted'>not mapped yet</td></tr></tbody>";return}
t.innerHTML="<thead><tr><th>fan</th><th>zones</th></tr></thead><tbody>"+
rows.map(function(r){return "<tr><td>"+esc(r[0])+"</td><td>"+esc(r[1])+"</td></tr>"}).join("")+"</tbody>";
});
}
fetch("/api/hardware").then(function(r){return r.json()}).then(function(h){hw=h;paint()}).catch(function(){msg("hardware unavailable")});
fetch("/api/summary").then(function(r){return r.json()}).then(function(s){sm=s;paint()}).catch(function(){});
}
fetch("/api/dashboard?deck="+encodeURIComponent(deck)).then(function(r){return r.json()}).then(function(d){doc=d;render();fill()});
if(editable){
$("save").onclick=function(){fetch("/api/dashboard?deck="+encodeURIComponent(deck),{method:"PUT",headers:{"Content-Type":"application/json"},body:JSON.stringify(doc)}).then(function(r){if(r.ok){msg("saved")}else{r.text().then(msg)}})};
$("reset").onclick=function(){fetch("/api/dashboard?deck="+encodeURIComponent(deck)+"&reset=1",{method:"PUT",headers:{"Content-Type":"application/json"},body:"{}"}).then(function(r){return r.json()}).then(function(d){doc=d;render();fill();msg("template restored")})};
$("add").onclick=function(){
if(doc.blocks.length>=32){msg("32 blocks is the limit");return}
var id="block"+(doc.blocks.length+1);
doc.blocks.push({id:id,kind:"metric",span:1,title:"New block",source:"power_w",unit:"W"});render();msg("unsaved changes")};
}
}
})();
"#;
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn every_sidebar_item_has_a_page() {
for group in NAV.iter() {
for item in group.items {
assert!(item.path.starts_with('/'), "{} has no path", item.label);
assert!(!item.label.is_empty());
}
}
assert_eq!(NAV.iter().map(|g| g.items.len()).sum::<usize>(), 13);
}
#[test]
fn default_decks_are_valid() {
for deck in ["dashboard", "overview"] {
let doc = default_deck(deck);
let text = doc.to_string();
assert!(validate_deck(&text).is_ok(), "{deck} default rejected");
}
}
#[test]
fn the_block_cap_is_enforced() {
let mut blocks = Vec::new();
for i in 0..=BLOCK_CAP {
blocks.push(json!({"id": format!("b{i}"), "kind": "metric", "span": 1}));
}
let doc = json!({"version": 1, "blocks": blocks});
assert!(validate_deck(&doc.to_string()).is_err());
}
#[test]
fn malformed_documents_are_rejected_with_a_reason() {
assert!(validate_deck("not json").is_err());
assert!(validate_deck("{}").is_err());
assert!(validate_deck(r#"{"version":2,"blocks":[]}"#).is_err());
assert!(
validate_deck(r#"{"version":1,"blocks":[{"id":"x","kind":"evil","span":1}]}"#).is_err()
);
assert!(
validate_deck(r#"{"version":1,"blocks":[{"id":"x","kind":"metric","span":9}]}"#)
.is_err()
);
}
#[test]
fn sidebar_marks_the_active_page_and_opens_its_group() {
let html = page("/mining/fans", "Fans", "");
assert!(html.contains("href=\"#/mining/fans\" aria-current=\"page\""));
// Exactly the group holding the current page is open; the other is not.
assert_eq!(html.matches("<details class=\"tree\" open>").count(), 1);
assert!(html.contains("Power Supply"));
assert!(html.contains("href=\"#/settings/terminal\""));
// A one-item group is a plain link, not a disclosure around a leaf.
assert!(html.contains("class=\"rail__link\" href=\"#/\""));
}
#[test]
fn user_text_is_escaped() {
assert_eq!(escape("<script>"), "&lt;script&gt;");
let html = kv_page(&[("note", "<b>x</b>".to_string())]);
assert!(!html.contains("<b>x</b>"));
assert!(html.contains("&lt;b&gt;"));
}
}
+1264
View File
File diff suppressed because it is too large Load Diff
+41
View File
@@ -0,0 +1,41 @@
# Third-party sources
Code we consume that is not on crates.io. Both entries are pinned, and both are
vendored rather than fetched so an image build works with no network.
## flare-ui
`flare-ui/` is a full checkout of the `flare-ui` tag recorded in
`flare-ui/flare-ui.lock` (repo, tag, commit). It is used as path dependencies:
```
flare-ui = { path = "third-party/flare-ui/crates/flare-ui" }
wschema = { path = "third-party/flare-ui/crates/wschema" }
```
The whole tree is vendored, not just `crates/`, because the crate embeds assets
from `dash-editor/` with `include_str!` and will not compile from a partial
archive.
Updating the pin:
```
git archive <new-tag> | tar -x -C third-party/flare-ui # from a flare-ui checkout
cargo vendor vendor # refresh registry deps
```
`vendor/` is a cargo directory source (see `.cargo/config.toml`), so every
registry dependency flare-ui needs - `maud`, `sha2`, `typenum`, `digest` and the
rest - must be re-vendored or the build fails offline.
## Size
`ci/check-ui-size.sh` builds two binaries for armv7 with the same profile: one
renders through flare-ui, one renders the same shape with `maud` alone. The
difference is the marginal cost. Measured 2026-11-03, release, stripped:
```
ui-baseline 323 KiB
ui-spike 771 KiB
marginal 448 KiB
```
+121
View File
@@ -0,0 +1,121 @@
name: CI
on:
push:
branches: [main, next]
pull_request:
workflow_dispatch:
concurrency:
group: ci-${{ gitea.ref }}
cancel-in-progress: true
env:
CARGO_TERM_COLOR: always
CARGO_INCREMENTAL: "0"
jobs:
check:
name: Format, lint and test
runs-on: ci-small
timeout-minutes: 30
steps:
- uses: actions/checkout@v7
# rust-toolchain.toml names one exact version. Install it, then require
# the compiler cargo will use to report that same version.
- name: Toolchain matches the pin
run: |
want="$(sed -n 's/^channel *= *"\(.*\)"/\1/p' rust-toolchain.toml)"
if command -v rustup >/dev/null 2>&1; then
rustup toolchain install "$want" --profile minimal --component clippy --component rustfmt
fi
got="$(rustc --version | cut -d' ' -f2)"
echo "pinned $want, rustc $got"
[ "$want" = "$got" ]
- name: Cache cargo registry
uses: actions/cache@v6
with:
path: |
~/.cargo/registry/index
~/.cargo/registry/cache
~/.cargo/git/db
key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.lock') }}
restore-keys: ${{ runner.os }}-cargo-
- name: Format
run: cargo fmt --check
- name: Clippy
run: cargo clippy --workspace --all-targets --locked -- -D warnings
- name: Test
run: cargo test --workspace --locked
- name: Crate owners
run: scripts/check-owners.sh
- name: Vendor script self-test
run: scripts/vendor-selftest.sh
# The panel crates must keep building for the device target.
- name: Build for the panel
run: |
if command -v rustup >/dev/null 2>&1; then
rustup target add armv7-unknown-linux-musleabihf
fi
cargo build --locked --target armv7-unknown-linux-musleabihf \
-p wschema -p warden-sync -p warden-seal -p wapp-core
# The imported dashboard editor ships plain static files; its tests
# are Node's built-in runner, no install step.
- name: Dash editor tests
run: |
cd dash-editor
node --test tests/*.test.mjs
# The automation flowchart model, same runner as the dash editor.
- name: Flow builder tests
run: |
cd flow-builder
node --test tests/*.test.mjs
- name: UI adapter tests
run: node --test crates/flare-ui/tests/js/*.test.js
browser:
name: UI browser tests
runs-on: ci-small
timeout-minutes: 15
permissions:
contents: read
env:
PLAYWRIGHT_BROWSERS_PATH: ${{ runner.tool_cache }}/flare-ui-playwright
defaults:
run:
working-directory: crates/flare-ui/tests/browser
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v4
with:
node-version: '24'
- name: Restore browser cache
id: browsers
uses: actions/cache/restore@v6
with:
path: ${{ env.PLAYWRIGHT_BROWSERS_PATH }}
key: ${{ runner.os }}-flare-ui-playwright-${{ hashFiles('crates/flare-ui/tests/browser/package-lock.json') }}
- name: Install test dependencies
run: npm ci --ignore-scripts
- name: Install headless browsers
run: npx playwright install --with-deps chromium firefox
- name: Check UI behavior
run: npm test
# Pull requests read the cache; only trusted next pushes replace it.
- name: Save browser cache
if: github.event_name == 'push' && github.ref == 'refs/heads/next' && steps.browsers.outputs.cache-hit != 'true'
uses: actions/cache/save@v6
with:
path: ${{ env.PLAYWRIGHT_BROWSERS_PATH }}
key: ${{ runner.os }}-flare-ui-playwright-${{ hashFiles('crates/flare-ui/tests/browser/package-lock.json') }}
+8
View File
@@ -0,0 +1,8 @@
/target
**/node_modules/
*.zip
.env
*.env
*.pem
*.key
+1499
View File
File diff suppressed because it is too large Load Diff
+9
View File
@@ -0,0 +1,9 @@
[workspace]
resolver = "2"
members = ["crates/*"]
[workspace.package]
version = "0.0.1"
edition = "2021"
rust-version = "1.85"
license = "MIT"
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 FLARE contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+14
View File
@@ -0,0 +1,14 @@
# One line per crate: <path> <lane>. Only the owning lane edits a crate;
# other lanes ask it through a note. Only lane LD tags (see docs/vendoring.md).
# scripts/check-owners.sh keeps this file and crates/ in step.
crates/flare-ui LD
crates/flare-ui-axum LD
crates/flare-plugin-abi LD
crates/wschema LB
crates/wschema-gen LB
crates/wschema-cli LB
crates/warden-sync LI
crates/warden-seal LI
crates/wapp-core LM
crates/wapp-pack LM
crates/flare-plugin-host LD
+81
View File
@@ -0,0 +1,81 @@
# flare-ui
Shared UI and schema crates for FLARE and the Warden console. They provide
schema forms, navigation, charts, page assets, editors and package validation.
- Licence: MIT.
- Branches: `main` and `next`, like flare. Work branches from `next`.
- Pinning: consumers vendor a tagged commit (`vN.N.N`) and record it in
`flare-ui.lock`. They never pin an untagged commit, and CI jobs hold no
cross-repo credential.
- Layout: worktree per branch, `flare-ui/.bare` plus one folder per branch,
kept in step with Gitea by `scripts/sync-worktrees.sh` (outside the repo).
- Toolchain: `rust-toolchain.toml` pins one exact version.
- Dash editor: `dash-editor/` holds the imported `flare-dash-editor` tree and
its history (lane LD owns it). Its tests: `cd dash-editor && node --test tests/*.test.mjs`.
- Flow builder: `flow-builder/` holds the automation flowchart (model, form,
view). Its tests: `cd flow-builder && node --test tests/*.test.mjs`.
- Validation corpus: `corpus/` (lane LB), described in `corpus/README.md`.
- Crates and owners: see `OWNERS`. Vendoring and tags: `docs/vendoring.md`.
## Crates
| Crate | Role |
|---|---|
| `flare-ui` | Schema forms, read-only pages, navigation, chart islands, page assets and editor assets |
| `flare-ui-axum` | Authenticated-page SSE transport, replay, stream limits, poll responses and the d04 7.4 action routes; [host contract](crates/flare-ui-axum/README.md) |
| `wschema` | Schema document model, builder DSL, canonical JSON, hashes, lint L01 to L23 |
| `wschema-cli` | `canon`, `hash`, `lint` and corpus `validate` for fragment authors and CI; `verify-lock` and `gen-lock` for consumer locks (`flare-ui.lock`, `gen.lock`) |
| `wschema-gen` | Generators: the OpenAPI `components.schemas` of an effective schema and their splice into a template |
| `warden-sync` | Sync stamps, HLC, windows, digest and planner (d03), and the wire and value limits both ends share, with golden limit vectors (`tests/vectors/limits-vectors.jsonl`) each end replays |
| `warden-seal` | Per-Warden sealing (HPKE Auth): suite, `info` and `aad` builders, padding, kid, shared vectors |
| `wapp-core` | App package format, manifests, platform checks and validation |
| `wapp-pack` | Package creation, verification, signing, index and release guard CLI |
| `flare-plugin-abi` | Reserved plugin ABI placeholder |
`wschema` depends on `serde`, `serde_json` and `sha2` only, and builds for
x86_64 and `armv7-unknown-linux-musleabihf`.
## Checks
```
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
scripts/check-owners.sh
scripts/vendor-selftest.sh
```
`cargo test` runs the JavaScript unit tests of the browser assets with `node`
(flare-ui#148): `node --test tests/js/<file>.test.js` in `crates/flare-ui`, for
actions, boot, chart, islands, live and page-live. A machine without `node`
fails those tests. A host that cannot run node sets `FLARE_UI_SKIP_NODE_TESTS=1`
to skip them. The skip is written to the test's stderr, which cargo shows only
for a failing test or with `--nocapture`, so a host that skips them runs those
six files with `node` elsewhere and records that run in its commit.
The [chart browser checks](crates/flare-ui/tests/browser/README.md) run on
Chromium and Firefox over plain HTTP, with CSP and real SSE samples.
The [live client](docs/live.md) documents typed chart props, server tier
links, accessible latest values and named series events.
The [schema page contract](docs/schema-pages.md) covers authorized read-only
snapshots, shared full/HX bodies and stable OOB fragments.
The shared crates also build for the panel:
```
cargo build --locked --target armv7-unknown-linux-musleabihf \
-p wschema -p warden-sync -p warden-seal -p wapp-core
```
The OpenAPI emitter's sample output passes an OpenAPI 3.1 validator
(`openapi-spec-validator`, not part of CI here; the consumer's CI runs it on
the real document):
```
cargo run -q -p wschema-gen --example openapi_sample > sample.yaml
openapi-spec-validator sample.yaml
```
Benchmarks for `wschema` (canonical JSON, hash, lint on a 140-setting
document): `cargo bench -p wschema --bench canon_hash`.
+49
View File
@@ -0,0 +1,49 @@
# Validation corpus
Cases that every implementation of the settings schema must answer the same
way: `wschema` (flared and the FLARE server) and anything that ports it. The
format is d02 "Corpus"; the reference is the module doc of
`crates/wschema/src/corpus.rs`.
## Files
| File | What it holds |
|---|---|
| `generic.jsonl` | One or more cases per validation stage and code: path, key, cap, scope, `write_via`, type, range, enum, length, check, the cross-field rules, permissions, resets |
| `flare-ported.jsonl` | The leaf cases of FLARE's `flare-server/src/tests_wardencfg.rs`, each with a `note` naming its test |
| `schema/warden-base.json` | The schema both files run against: the Warden base as flare-edge emits it (`data/schema/base.json`, commit f6bc5281) |
A case's `schema` member names a base id (the base alone) or a fragment id
(the base plus that fragment). Both files use `base`.
## Differences from FLARE
- An empty `system.hostname` is refused (V_LEN, d02 D25); FLARE stored it.
- `network.interfaces.Eth0` is outside the path grammar (V_PATH), so the key
check never sees it; `0eth` is the key-check case (V_KEY).
- A VPN field written alone carries the other VPN fields in `ctx.rows`, since
the `vpn` rules (all or none, allowed IPs once an address is set) now run.
## Running
```
cargo test -p wschema --test corpus
wschema-cli validate --schema corpus/schema/warden-base.json \
--corpus corpus/generic.jsonl --corpus corpus/flare-ported.jsonl
```
`validate_corpus` runs every `*.jsonl` here. It also fails when the generic
file stops reaching a validation code the base can produce, and when any one
flipped expectation goes unreported.
## Editing
Edit the JSON lines directly; one case per line, ASCII only. When flare-edge
changes a row the cases touch, refresh `schema/warden-base.json` from its
emitted `data/schema/base.json` and record the commit above. Each firmware
also emits its own corpus from the `valid` and `invalid` vectors of its
settings (`wschema::corpus::emit`). A setting that a cross-field rule
refuses in the empty context declares a `vector_ctx` (DSL `vector_path`,
`vector_row`): the concrete path and the stored rows its vectors run at.
Each emitted case carries those rows in `ctx.rows`. Like the vectors, it is
never emitted into the schema or hashed.
+57
View File
@@ -0,0 +1,57 @@
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.country", "value": "CA", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs wifi_country_is_two_uppercase_letters_or_unset"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.country", "value": "ca", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs wifi_country_is_two_uppercase_letters_or_unset"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.country", "value": "C", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs wifi_country_is_two_uppercase_letters_or_unset"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.country", "value": "CAN", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs wifi_country_is_two_uppercase_letters_or_unset"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.country", "value": "00", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs wifi_country_is_two_uppercase_letters_or_unset"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.country", "value": "C1", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs wifi_country_is_two_uppercase_letters_or_unset"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.country", "value": " CA", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs wifi_country_is_two_uppercase_letters_or_unset"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.country", "value": 12, "expect": {"code": "V_TYPE"}, "note": "flare tests_wardencfg.rs wifi_country_is_two_uppercase_letters_or_unset"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.regdomain", "value": "CA", "expect": {"code": "V_PATH"}, "note": "flare tests_wardencfg.rs wifi_country_is_two_uppercase_letters_or_unset"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.brightness", "value": 101, "expect": {"code": "V_RANGE"}, "note": "flare tests_wardencfg.rs out_of_range_values_read_like_the_wardens_own_details"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.sleep_minutes", "value": 2, "expect": {"code": "V_ENUM"}, "note": "flare tests_wardencfg.rs out_of_range_values_read_like_the_wardens_own_details"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.theme", "value": "sepia", "expect": {"code": "V_ENUM"}, "note": "flare tests_wardencfg.rs out_of_range_values_read_like_the_wardens_own_details"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "rs485.baud", "value": 9601, "expect": {"code": "V_ENUM"}, "note": "flare tests_wardencfg.rs out_of_range_values_read_like_the_wardens_own_details"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "rs485.timeout_ms", "value": 60001, "expect": {"code": "V_RANGE"}, "note": "flare tests_wardencfg.rs out_of_range_values_read_like_the_wardens_own_details"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.vpn.keepalive_seconds", "value": 65536, "expect": {"code": "V_RANGE"}, "note": "flare tests_wardencfg.rs out_of_range_values_read_like_the_wardens_own_details"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.routing.lease", "value": "2h", "expect": {"code": "V_ENUM"}, "note": "flare tests_wardencfg.rs out_of_range_values_read_like_the_wardens_own_details"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.routing.lease", "value": "12h", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs out_of_range_values_read_like_the_wardens_own_details"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.sleep_minutes", "value": 0, "expect": {"ok": true}, "note": "flare tests_wardencfg.rs out_of_range_values_read_like_the_wardens_own_details"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "system.timezone", "value": "CET-1CEST,M3.5.0,M10.5.0/3", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs timezone_is_curated_or_empty"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "system.timezone", "value": "Europe/Berlin", "expect": {"code": "V_ENUM"}, "note": "flare tests_wardencfg.rs timezone_is_curated_or_empty"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "system.hostname", "value": "warden-07", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs hostname_is_an_rfc1123_label_or_empty"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "system.hostname", "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs hostname_is_an_rfc1123_label_or_empty"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "system.hostname", "value": "", "expect": {"code": "V_LEN"}, "note": "flare tests_wardencfg.rs hostname_is_an_rfc1123_label_or_empty; d02 D25 refuses an empty hostname where FLARE stored it"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "system.hostname", "value": "-edge", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs hostname_is_an_rfc1123_label_or_empty"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "system.hostname", "value": "edge-", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs hostname_is_an_rfc1123_label_or_empty"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "system.hostname", "value": "no.dots", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs hostname_is_an_rfc1123_label_or_empty"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "system.hostname", "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs hostname_is_an_rfc1123_label_or_empty"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.address", "value": "10.0.0.1/24", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.address", "value": "10.0.0.1/31", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.address", "value": "", "expect": {"code": "V_LEN"}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.routing.lan_address", "value": "300.1.1.1/24", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.vpn.address", "value": "10.99.0.2/33", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.vpn.peer_endpoint": "hub.example.test:51820", "network.vpn.peer_public_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", "network.vpn.allowed_ips": "10.99.0.0/24"}}, "path": "network.vpn.address", "value": "10.99.0.2/32", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns; the other VPN fields set so the vpn rules hold"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.vpn.address", "value": "", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.vpn.address": "10.99.0.2/32", "network.vpn.peer_public_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", "network.vpn.allowed_ips": "10.99.0.0/24"}}, "path": "network.vpn.peer_endpoint", "value": "[2001:db8::1]:51820", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns; the other VPN fields set so the vpn rules hold"}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.vpn.address": "10.99.0.2/32", "network.vpn.peer_endpoint": "hub.example.test:51820", "network.vpn.allowed_ips": "10.99.0.0/24"}}, "path": "network.vpn.peer_public_key", "value": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns; the other VPN fields set so the vpn rules hold"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.vpn.peer_public_key", "value": "", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.proxy.pac", "value": "", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.proxy.http", "value": "proxy.example.test:3128", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.proxy.http", "value": "no-port", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.proxy.socks", "value": "spaced host:80", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.proxy.pac", "value": "http://wpad.example.test/wpad.dat", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.proxy.pac", "value": "ftp://x", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.vpn.peer_public_key", "value": "short=", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs addresses_and_endpoints_follow_the_yaml_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.vpn.allowed_ips", "value": "10.0.0.0/8, 192.168.0.0/16", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs string_byte_caps_are_the_stores_own"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.vpn.allowed_ips", "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expect": {"code": "V_LEN"}, "note": "flare tests_wardencfg.rs string_byte_caps_are_the_stores_own"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "system.ntp.server", "value": "two\nlines", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs string_byte_caps_are_the_stores_own"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.ssid", "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs string_byte_caps_are_the_stores_own"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.ssid", "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs string_byte_caps_are_the_stores_own"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.passphrase", "value": "1234567", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs string_byte_caps_are_the_stores_own"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.passphrase", "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expect": {"code": "V_LEN"}, "note": "flare tests_wardencfg.rs string_byte_caps_are_the_stores_own"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.passphrase", "value": "snowman\u2603pass", "expect": {"code": "V_CHECK"}, "note": "flare tests_wardencfg.rs string_byte_caps_are_the_stores_own"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.eth0.zone", "value": "lan", "expect": {"ok": true}, "note": "flare tests_wardencfg.rs interface_names_and_app_ids_follow_their_key_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.Eth0.zone", "value": "lan", "expect": {"code": "V_PATH"}, "note": "flare tests_wardencfg.rs interface_names_and_app_ids_follow_their_key_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.0eth.zone", "value": "lan", "expect": {"code": "V_KEY"}, "note": "flare tests_wardencfg.rs interface_names_and_app_ids_follow_their_key_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.eth-0.zone", "value": "lan", "expect": {"code": "V_KEY"}, "note": "flare tests_wardencfg.rs interface_names_and_app_ids_follow_their_key_patterns"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.abcdefghijklmnop.zone", "value": "lan", "expect": {"code": "V_KEY"}, "note": "flare tests_wardencfg.rs interface_names_and_app_ids_follow_their_key_patterns"}
+60
View File
@@ -0,0 +1,60 @@
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.regdomain", "value": "CA", "expect": {"code": "V_PATH"}, "note": "not a setting"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network..wifi", "value": "x", "expect": {"code": "V_PATH"}, "note": "malformed path"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.brightness.extra", "value": 1, "expect": {"code": "V_PATH"}, "note": "a leaf has no children"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.country", "reset": true, "expect": {"ok": true}, "note": "a reset of a synced setting from FLARE"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "$meta.fp_key", "value": "k", "expect": {"ok": true}, "note": "meta path handled before the schema"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "$meta.unknown", "value": "k", "expect": {"code": "V_PATH"}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.Eth0.zone", "value": "lan", "expect": {"code": "V_PATH"}, "note": "uppercase is outside the path grammar, so the key check never sees it"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.0eth.zone", "value": "lan", "expect": {"code": "V_KEY"}, "note": "ifname key check: starts with a letter"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "relays.8.safe_state", "value": "open", "expect": {"code": "V_KEY"}, "note": "index key above max 7"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "relays.7.safe_state", "value": "open", "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.interfaces.eth0.ipv4.method": "dhcp", "network.interfaces.eth1.ipv4.method": "dhcp", "network.interfaces.eth2.ipv4.method": "dhcp", "network.interfaces.eth3.ipv4.method": "dhcp", "network.interfaces.eth4.ipv4.method": "dhcp", "network.interfaces.eth5.ipv4.method": "dhcp", "network.interfaces.eth6.ipv4.method": "dhcp", "network.interfaces.eth7.ipv4.method": "dhcp", "network.interfaces.eth8.ipv4.method": "dhcp", "network.interfaces.eth9.ipv4.method": "dhcp", "network.interfaces.eth10.ipv4.method": "dhcp", "network.interfaces.eth11.ipv4.method": "dhcp", "network.interfaces.eth12.ipv4.method": "dhcp", "network.interfaces.eth13.ipv4.method": "dhcp", "network.interfaces.eth14.ipv4.method": "dhcp", "network.interfaces.eth15.ipv4.method": "dhcp"}}, "path": "network.interfaces.eth16.ipv4.method", "value": "dhcp", "expect": {"code": "V_CAP"}, "note": "17th entry of a 16-entry map"}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.interfaces.eth0.ipv4.method": "dhcp", "network.interfaces.eth1.ipv4.method": "dhcp", "network.interfaces.eth2.ipv4.method": "dhcp", "network.interfaces.eth3.ipv4.method": "dhcp", "network.interfaces.eth4.ipv4.method": "dhcp", "network.interfaces.eth5.ipv4.method": "dhcp", "network.interfaces.eth6.ipv4.method": "dhcp", "network.interfaces.eth7.ipv4.method": "dhcp", "network.interfaces.eth8.ipv4.method": "dhcp", "network.interfaces.eth9.ipv4.method": "dhcp", "network.interfaces.eth10.ipv4.method": "dhcp", "network.interfaces.eth11.ipv4.method": "dhcp", "network.interfaces.eth12.ipv4.method": "dhcp", "network.interfaces.eth13.ipv4.method": "dhcp", "network.interfaces.eth14.ipv4.method": "dhcp", "network.interfaces.eth15.ipv4.method": "dhcp"}}, "path": "network.interfaces.eth15.ipv4.method", "value": "dhcp", "expect": {"ok": true}, "note": "an existing entry never counts twice"}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.interfaces.eth0.ipv4.method": "dhcp", "network.interfaces.eth1.ipv4.method": "dhcp", "network.interfaces.eth2.ipv4.method": "dhcp", "network.interfaces.eth3.ipv4.method": "dhcp", "network.interfaces.eth4.ipv4.method": "dhcp", "network.interfaces.eth5.ipv4.method": "dhcp", "network.interfaces.eth6.ipv4.method": "dhcp", "network.interfaces.eth7.ipv4.method": "dhcp", "network.interfaces.eth8.ipv4.method": "dhcp", "network.interfaces.eth9.ipv4.method": "dhcp", "network.interfaces.eth10.ipv4.method": "dhcp", "network.interfaces.eth11.ipv4.method": "dhcp", "network.interfaces.eth12.ipv4.method": "dhcp", "network.interfaces.eth13.ipv4.method": "dhcp", "network.interfaces.eth14.ipv4.method": "dhcp", "network.interfaces.eth15.ipv4.method": "dhcp"}}, "path": "network.interfaces.eth16.ipv4.method", "reset": true, "expect": {"ok": true}, "note": "a reset never counts against the cap"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.debug_overlay", "value": true, "expect": {"code": "V_SCOPE"}, "note": "device_only from FLARE"}
{"schema": "base", "origin": "panel", "ctx": {}, "path": "display.debug_overlay", "value": true, "expect": {"ok": true}}
{"schema": "base", "origin": "panel", "ctx": {}, "path": "network.ap.local.password", "value": "secret12", "expect": {"code": "V_VIA"}, "note": "write_via: only the action writes it"}
{"schema": "base", "origin": "system", "ctx": {}, "path": "network.ap.local.password", "value": "secret12", "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.brightness", "value": "50", "expect": {"code": "V_TYPE"}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.brightness", "value": null, "expect": {"code": "V_TYPE"}, "note": "null is not a value; reset is the op for that"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.brightness", "value": 50.5, "expect": {"code": "V_TYPE"}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.brightness", "value": -1, "expect": {"code": "V_RANGE"}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.brightness", "value": 0, "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.theme", "value": "sepia", "expect": {"code": "V_ENUM"}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.sleep_minutes", "value": 2, "expect": {"code": "V_ENUM"}, "note": "int_set"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "relays.lease_max_s", "value": 59, "expect": {"code": "V_RANGE"}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "relays.lease_max_s", "value": 86400, "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.eth0.ipv4.dns", "value": ["1.1.1.1", "9.9.9.9"], "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.eth0.ipv4.dns", "value": ["1.1.1.1", "dns.example"], "expect": {"code": "V_CHECK"}, "note": "list item check"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.eth0.ipv4.dns", "value": ["1.1.1.1", "1.1.1.1", "1.1.1.1", "1.1.1.1", "1.1.1.1"], "expect": {"code": "V_LEN"}, "note": "max_items 4"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.eth0.ipv4.dns", "value": [1], "expect": {"code": "V_TYPE"}, "note": "list items are strings"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.scan_ranges", "value": ["10.0.0.0/8"], "expect": {"ok": true}, "note": "a CIDR counts once toward the expansion cap"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.scan_ranges", "value": ["10.0-255.0-1.1-255"], "expect": {"code": "V_CHECK"}, "note": "scan_expansion_cap: 512 /24 ranges"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.scan_ranges", "value": ["192.168.1.0/24"], "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.passphrase", "value": "short", "expect": {"code": "V_CHECK"}, "note": "secret kind with a check"}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.passphrase", "value": "12345678", "expect": {"ok": true}}
{"schema": "base", "origin": "panel", "ctx": {}, "path": "display.debug_overlay", "value": "true", "expect": {"code": "V_TYPE"}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "display.brightness", "reset": true, "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.wifi.nope", "reset": true, "expect": {"code": "V_PATH"}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.security", "value": "WPA2", "expect": {"code": "V_REQUIRES"}, "note": "PSK needs a passphrase"}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.ap.passphrase": "12345678"}}, "path": "network.ap.security", "value": "WPA2", "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.security", "value": "Open", "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.interfaces.eth0.ipv4.method", "value": "manual", "expect": {"code": "V_REQUIRES"}}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.interfaces.eth0.ipv4.address": "10.1.0.2/24"}}, "path": "network.interfaces.eth0.ipv4.method", "value": "manual", "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.interfaces.eth0.zone": "wan"}}, "path": "network.interfaces.eth1.zone", "value": "wan", "expect": {"code": "V_EXCLUSIVE"}}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.interfaces.eth0.zone": "wan"}}, "path": "network.interfaces.eth1.zone", "value": "lan", "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.interfaces.eth0.zone": "wan"}}, "path": "network.interfaces.eth0.zone", "value": "wan", "expect": {"ok": true}, "note": "rewriting the entry that holds the value"}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.routing.lan_address": "192.168.50.1/24"}}, "path": "network.ap.address", "value": "192.168.50.1/24", "expect": {"code": "V_OVERLAP"}}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.routing.lan_address": "192.168.50.1/24"}}, "path": "network.ap.address", "value": "10.254.1.1/24", "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.vpn.peer_endpoint", "value": "hub.example.test:51820", "expect": {"code": "V_ALL_OR_NONE"}, "note": "flare-ui#13: the other two hold their empty default"}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.vpn.peer_endpoint": "hub.example.test:51820", "network.vpn.peer_public_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="}}, "path": "network.vpn.address", "value": "10.99.0.2/32", "expect": {"code": "V_REQUIRES"}, "note": "flare-ui#13: allowed_ips is empty"}
{"schema": "base", "origin": "flare", "ctx": {"rows": {"network.vpn.peer_endpoint": "hub.example.test:51820", "network.vpn.peer_public_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", "network.vpn.allowed_ips": "10.99.0.0/24"}}, "path": "network.vpn.address", "value": "10.99.0.2/32", "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.vpn.address", "value": "", "expect": {"ok": true}, "note": "all three empty is the none state"}
{"schema": "base", "origin": "flare", "ctx": {"usable_wifi_credentials": false, "rows": {"network.ap.local.enabled": false}}, "path": "network.ap.security", "value": "WPA2-Enterprise", "expect": {"code": "V_RULE"}, "note": "ap_enterprise_credentials"}
{"schema": "base", "origin": "flare", "ctx": {"usable_wifi_credentials": false, "rows": {"network.ap.local.enabled": true}}, "path": "network.ap.security", "value": "WPA2-Enterprise", "expect": {"ok": true}}
{"schema": "base", "origin": "flare", "ctx": {}, "path": "network.ap.security", "value": "WPA2-Enterprise", "expect": {"ok": true}, "note": "named rules without their context input are skipped"}
{"schema": "base", "origin": "flare", "ctx": {"tls_state": "self_signed"}, "path": "network.ap.security", "value": "WPA2-Enterprise", "expect": {"code": "V_RULE"}, "note": "ap_enterprise_cert"}
{"schema": "base", "origin": "flare", "ctx": {"tls_state": "public"}, "path": "network.ap.security", "value": "WPA2-Enterprise", "expect": {"ok": true}}
{"schema": "base", "origin": "web", "ctx": {"perms": ["site.view"]}, "path": "display.brightness", "value": 50, "expect": {"code": "V_PERM"}}
{"schema": "base", "origin": "web", "ctx": {"perms": ["site.manage"]}, "path": "display.brightness", "value": 50, "expect": {"ok": true}}
{"schema": "base", "origin": "migration", "ctx": {"perms": []}, "path": "display.brightness", "value": 50, "expect": {"ok": true}, "note": "internal origins skip permissions"}
File diff suppressed because it is too large Load Diff
+20
View File
@@ -0,0 +1,20 @@
[package]
name = "flare-plugin-abi"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
description = "Plugin ABI shared by FLARE and the Warden console"
publish = false
[features]
default = ["wasm"]
# FLARE plugin (Wasm) admission. A panel build turns it off.
wasm = ["dep:wasmparser"]
# Admits dev-class signatures. Release images leave it off (d04 13.4.8, W-D4).
plugin-dev = ["wapp-core/dev-signing-key"]
[dependencies]
serde_json = "1"
wapp-core = { path = "../wapp-core" }
wasmparser = { version = "0.228", default-features = false, features = ["std", "validate", "features"], optional = true }
+46
View File
@@ -0,0 +1,46 @@
# flare-plugin-abi
Plugin and module admission shared by FLARE and the Warden console
(d04 13.3.5 and 13.4; B-13, W-D4).
| Module | Admits | Spec |
|---|---|---|
| `package` | the code inside one signed `.wapp`: `validate_full` first, then the signer class and the code checks | s12 V16, V19, V20 |
| `wmod` | panel modules (`ui/modules/*.so`, ABI `wmod/1`) before `dlopen` | d04 13.3.5 |
| `wasm` | FLARE plugin modules (`fp/1`, feature `wasm`) before compile | d04 13.4.4 |
| `fp1` | `fp/1` names, handler kinds, negative codes, op registry | d04 13.4.2 |
| `code` | reason codes shared by all of the above | s12 4.6 |
`wmod` checks the image the loader maps. The dynamic section and every table it
names (symbols, strings, relocations, hash tables, the info block) are read at
their load addresses through the PT_LOAD segments, and a section header that
names one of them must name the same file bytes. Every symbol index the loader
can reach, through a relocation or a hash chain, must be a checked symbol
(#187).
Only `platform`-signed code is admitted. The `dev` class needs the
`plugin-dev` feature and is compiled out of release images. The `partner`
class is refused until an out-of-process runtime exists (B-13).
## Amendments
Each row records a reading of frozen spec text that the code follows. The
frozen copy in `flare-edge-construction/raw/2026-10-09-rebuild-design-specs/`
is not edited.
| Id | Spec text | Reading in this crate | Why |
|---|---|---|---|
| AM-PL2-1 | d04 13.3.5 leaves the info block locator open | the block is the `.wmod_info` section, found by name (`wmod::INFO_SECTION`) | the module SDK must link it somewhere the verifier can read without running the module; `wmod_entry` is the only exported symbol |
| AM-PL2-2 | d04 13.3.5 "Info block" row gives `E_PLATFORM` for an LVGL or SDK hash mismatch; 13.3.6 and 13.3.10 give `needs_platform` | an LVGL or SDK mismatch under `LVGL_DIRECT` is `Compat::NeedsPlatform`; app_id, app_build and ABI major stay `E_PLATFORM` | 13.3.6 and 13.3.10 are the later, specific rows; s12 4.2 makes the module mismatch soft (T-WA-06) |
| AM-PL2-3 | d04 13.3.5 "Dynamic section" refuses `DT_TEXTREL` | the verifier refuses the `DT_TEXTREL` tag and `DF_TEXTREL` in `DT_FLAGS`, and a second `DT_FLAGS` entry | current linkers record text relocations as `DF_TEXTREL` in `DT_FLAGS`; a second entry could give the verifier and the loader different flag words |
| AM-PL2-4 | d04 13.4.4 "imports must be exactly `fp1.call` and `fp1.log`" | the import list may hold only those two names, each at most once with its fixed signature; a module may import one of them | a guest that never logs does not import `fp1.log`; the rule that matters is that no other import exists |
| AM-PL2-5 | d04 13.4.8 names no code for the `off` refusal of a Wasm plugin. s12 1282 gives `E_KEY` with detail `plugins_off` | `E_KEY` with detail `plugins_off`, in both `package::admit_plugin` and the host `load` gate. The host once returned `E_STATE` for this refusal, an implementation defect fixed in 42b9646 | s12 1282 is the governing text (the install pipeline the audit records use). The host test `off_mode_loads_nothing` pins the code |
| AM-PL2-6 | d04 13.3.5 "ELF header" row requires hard-float by `Tag_ABI_VFP_args` | hard-float is the `EF_ARM_ABI_FLOAT_HARD` bit of `e_flags`; the attribute section is not parsed (see `abi/fp1.md`) | the bit sits in the header the verifier already reads, so no attribute parser is needed; `d04_pl2_refuses_soft_float` pins the refusal |
## Reason codes
`code::Code` carries every wire code of the `.wapp` set and the plugin-only
codes `E_WASM`, `E_IMPORT` and `E_LIMIT`. A refusal from `wapp-core` keeps its
wire code; `t_wa_01_wire_codes_match_wapp_core` checks the mapping.
`t_wa_01_every_reason_code_has_a_refusing_module_vector` refuses a panel module
with each of the ten T-WA-01 codes (s12 4.5).
+71
View File
@@ -0,0 +1,71 @@
# fp/1 plugin ABI
Defined by d04 13.4.2 to 13.4.5. This file is the contract the crate tests
pin; the sources are `src/fp1.rs`, `src/wasm.rs` and `src/wmod.rs`.
## Guest module
Core Wasm, one import namespace, JSON messages.
| Direction | Name | Type |
|---|---|---|
| import | `fp1.call` | `(i32 i32 i32 i32) -> i32` |
| import | `fp1.log` | `(i32 i32 i32) -> ()` |
| export | `memory` | the one linear memory |
| export | `fp_alloc` | `(i32) -> i32` |
| export | `fp_free` | `(i32 i32) -> ()` |
| export | `fp_init` | `(i32 i32) -> i32` |
| export | `fp_handle` | `(i32 i32 i32) -> i64` |
## Admission (`wasm::admit`)
Refused with `E_WASM`, `E_IMPORT` or `E_LIMIT`:
- module over 2 MiB (`E_LIMIT`);
- any import other than `fp1.call` and `fp1.log`, each at most once and with
the exact type above (`E_IMPORT`); memory, table and global imports count;
- a start function, a second memory, more than one table, shared or 64-bit
memory, a memory with no declared maximum, or a maximum above
`limits.memory_mb` (`E_WASM`, the last two `E_LIMIT`);
- a missing export, an export of the wrong kind or type, or a duplicate name;
- threads, SIMD, GC, exceptions and other post-MVP features outside the
accepted set: mutable globals, sign extension, saturating conversion,
multi-value, bulk memory, reference types.
## Host ops
The registry is `fp1::OPS`. A manifest names an op or a family (`kv@1`).
Negative codes of `fp1.call` are `-1 E_OP_UNKNOWN` through `-9 E_STATE`.
`parse_call` maps a malformed request to `E_ARG`, an oversize one to
`E_LIMIT` and an unknown op to `E_OP_UNKNOWN`.
## Handler output
- Response headers pass `filter_response_header`: `content-type`,
`x-request-id`, `cache-control: no-store` and same-origin `location` only.
`set-cookie` is never allowed.
- Routes pass `route_allowed`: only `/apps/{id}/...` and
`/api/v1/apps/{id}/...`.
- Page output (UiTree, handler kind 4) is not checked in this crate yet;
the UiTree checks belong to the PL-4 page work (d04 13.4.5).
## Native modules (`wmod/1`)
`wmod::check_module` runs the ELF checks of d04 13.3.5 on a Warden module:
`ET_DYN`, ARM EABI5 hard-float, `DT_NEEDED` within the shipped libraries, no
`RPATH`, `RUNPATH` or `TEXTREL`, `BIND_NOW`, non-executable stack, exports
exactly `wmod_entry`, imports within `wmod-libc.allow` plus
`wmod_exports.list`, with the denied families (allocator, files, sockets,
`exec*`, `pthread_*`, signals, `setjmp`) refused whatever the lists say.
`Info`, `check_info` and `check_grants` cover the info block and permission
rows.
Hard-float is read from `e_flags` (`EF_ARM_ABI_FLOAT_HARD`), which the linker
derives from `Tag_ABI_VFP_args`; the attribute section is not parsed.
## Not here
Signature, key class, revocation, floor and per-file hash checks are
`wapp-core`. The wasmi runtime, fuel, store limits and the circuit breaker
are `flare-plugin-host` (built into flare); the op implementations belong to
the consumer behind its `HostOps` seam.
+145
View File
@@ -0,0 +1,145 @@
//! Reason codes for refusals (s12 4.6, d04 13.3.5, 13.4.7).
//!
//! One enum carries a refusal from either verifier. The variants named by
//! the `.wapp` set use the same spellings as `wapp_core::Code`, so a package
//! refusal from `wapp_core::validate_full` keeps its code (`E_SIG`, `E_KEY`,
//! ...). The plugin-only codes are `E_WASM`, `E_IMPORT` and `E_LIMIT`.
use std::fmt;
/// A refusal reason code, as shown in the UIs, the audit record and tests.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Code {
Reserved,
Source,
Hash,
Sig,
Key,
Revoked,
Floor,
Platform,
Deps,
Conflict,
Budget,
Grant,
Precond,
Policy,
Dependents,
Core,
Veto,
Compat,
Manifest,
Elf,
Symbols,
Snapshot,
Wasm,
Import,
Limit,
}
impl Code {
/// Every code, in declaration order.
pub const ALL: &'static [Code] = &[
Code::Reserved,
Code::Source,
Code::Hash,
Code::Sig,
Code::Key,
Code::Revoked,
Code::Floor,
Code::Platform,
Code::Deps,
Code::Conflict,
Code::Budget,
Code::Grant,
Code::Precond,
Code::Policy,
Code::Dependents,
Code::Core,
Code::Veto,
Code::Compat,
Code::Manifest,
Code::Elf,
Code::Symbols,
Code::Snapshot,
Code::Wasm,
Code::Import,
Code::Limit,
];
/// The wire spelling, for example `E_MANIFEST`.
pub fn as_str(self) -> &'static str {
match self {
Code::Reserved => "E_RESERVED",
Code::Source => "E_SOURCE",
Code::Hash => "E_HASH",
Code::Sig => "E_SIG",
Code::Key => "E_KEY",
Code::Revoked => "E_REVOKED",
Code::Floor => "E_FLOOR",
Code::Platform => "E_PLATFORM",
Code::Deps => "E_DEPS",
Code::Conflict => "E_CONFLICT",
Code::Budget => "E_BUDGET",
Code::Grant => "E_GRANT",
Code::Precond => "E_PRECOND",
Code::Policy => "E_POLICY",
Code::Dependents => "E_DEPENDENTS",
Code::Core => "E_CORE",
Code::Veto => "E_VETO",
Code::Compat => "E_COMPAT",
Code::Manifest => "E_MANIFEST",
Code::Elf => "E_ELF",
Code::Symbols => "E_SYMBOLS",
Code::Snapshot => "E_SNAPSHOT",
Code::Wasm => "E_WASM",
Code::Import => "E_IMPORT",
Code::Limit => "E_LIMIT",
}
}
/// The code with this wire spelling, if any.
pub fn from_wire(s: &str) -> Option<Code> {
Code::ALL.iter().copied().find(|c| c.as_str() == s)
}
}
impl fmt::Display for Code {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
/// A coded refusal with a plain detail line.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Error {
pub code: Code,
pub detail: String,
}
impl Error {
pub fn new(code: Code, detail: impl Into<String>) -> Self {
Error {
code,
detail: detail.into(),
}
}
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}: {}", self.code, self.detail)
}
}
impl std::error::Error for Error {}
/// A package refusal from wapp-core keeps its wire code and detail.
impl From<wapp_core::Error> for Error {
fn from(e: wapp_core::Error) -> Self {
let code = Code::from_wire(e.code.as_str()).unwrap_or(Code::Manifest);
Error::new(code, e.detail)
}
}
pub type Result<T> = std::result::Result<T, Error>;
+267
View File
@@ -0,0 +1,267 @@
//! The `fp/1` plugin ABI surface (d04 13.4.2): names, handler kinds,
//! negative codes, limits and the op registry. Pure data and validators;
//! the wasmi runtime lives in `flare-plugin-host`.
use crate::code::{Code, Error, Result};
use serde_json::Value;
pub const IMPORT_MODULE: &str = "fp1";
pub const IMPORT_CALL: &str = "call";
pub const IMPORT_LOG: &str = "log";
pub const EXPORT_MEMORY: &str = "memory";
pub const EXPORT_ALLOC: &str = "fp_alloc";
pub const EXPORT_FREE: &str = "fp_free";
pub const EXPORT_INIT: &str = "fp_init";
pub const EXPORT_HANDLE: &str = "fp_handle";
/// Largest module file (13.4.4 module admission).
pub const MAX_MODULE_BYTES: usize = 2 * 1024 * 1024;
/// Largest request or response body.
pub const MAX_MESSAGE_BYTES: usize = 1024 * 1024;
/// Host op calls per handler invocation.
pub const MAX_CALLS_PER_HANDLER: u32 = 64;
/// Longest log line.
pub const MAX_LOG_BYTES: usize = 512;
/// Wasm page size.
pub const PAGE_BYTES: u64 = 65_536;
/// Default per-call fuel budget.
pub const DEFAULT_FUEL: u64 = 50_000_000;
/// Wall-clock deadline in milliseconds for `http`, `page` and `action`.
pub const DEADLINE_FAST_MS: u64 = 250;
/// Wall-clock deadline in milliseconds for `job` and `event`.
pub const DEADLINE_SLOW_MS: u64 = 5_000;
pub const MAX_INFLIGHT_PER_PLUGIN: u32 = 4;
pub const MAX_INFLIGHT_PER_PORTAL: u32 = 32;
/// Circuit breaker: this many traps or timeouts inside the window trip it.
pub const BREAKER_TRIPS: u32 = 5;
pub const BREAKER_WINDOW_S: u64 = 60;
pub const BREAKER_FIRST_HOLD_S: u64 = 600;
pub const BREAKER_MAX_HOLD_S: u64 = 3_600;
/// Handler kinds passed as the first argument of `fp_handle`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Kind {
Http = 1,
Job = 2,
Event = 3,
Page = 4,
Action = 5,
Validate = 6,
}
impl Kind {
pub fn from_i32(n: i32) -> Option<Kind> {
Some(match n {
1 => Kind::Http,
2 => Kind::Job,
3 => Kind::Event,
4 => Kind::Page,
5 => Kind::Action,
6 => Kind::Validate,
_ => return None,
})
}
/// Wall-clock deadline for this kind.
pub fn deadline_ms(self) -> u64 {
match self {
Kind::Job | Kind::Event => DEADLINE_SLOW_MS,
_ => DEADLINE_FAST_MS,
}
}
}
/// Negative return codes of `fp1.call`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Neg {
OpUnknown = -1,
OpDenied = -2,
Arg = -3,
Limit = -4,
Timeout = -5,
Upstream = -6,
NotFound = -7,
Conflict = -8,
State = -9,
}
impl Neg {
pub fn code(self) -> i32 {
self as i32
}
pub fn from_i32(n: i32) -> Option<Neg> {
Some(match n {
-1 => Neg::OpUnknown,
-2 => Neg::OpDenied,
-3 => Neg::Arg,
-4 => Neg::Limit,
-5 => Neg::Timeout,
-6 => Neg::Upstream,
-7 => Neg::NotFound,
-8 => Neg::Conflict,
-9 => Neg::State,
_ => return None,
})
}
pub fn name(self) -> &'static str {
match self {
Neg::OpUnknown => "E_OP_UNKNOWN",
Neg::OpDenied => "E_OP_DENIED",
Neg::Arg => "E_ARG",
Neg::Limit => "E_LIMIT",
Neg::Timeout => "E_TIMEOUT",
Neg::Upstream => "E_UPSTREAM",
Neg::NotFound => "E_NOT_FOUND",
Neg::Conflict => "E_CONFLICT",
Neg::State => "E_STATE",
}
}
}
/// What a plugin needs before the host runs an op (13.4.3).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Grant {
/// No grant: the op works on the plugin's own namespace or is pure.
None,
/// The manifest sets `data.schema: true`.
Schema,
/// An admin-approved host list.
Hosts,
/// A per-site grant row.
Site,
/// A per-site grant that lists path patterns.
SitePaths,
/// A per-site grant that lists verbs; `platform` key class only.
SiteVerbs,
/// An admin-set plugin secret.
Secret,
}
/// One host op of the v1 registry.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct OpDef {
pub name: &'static str,
/// The family a manifest may name to cover this op, for example `kv@1`.
pub family: &'static str,
pub grant: Grant,
}
const fn op(name: &'static str, family: &'static str, grant: Grant) -> OpDef {
OpDef {
name,
family,
grant,
}
}
/// The v1 op registry. A manifest may name only these.
pub const OPS: &[OpDef] = &[
op("kv.get@1", "kv@1", Grant::None),
op("kv.put@1", "kv@1", Grant::None),
op("kv.delete@1", "kv@1", Grant::None),
op("kv.list@1", "kv@1", Grant::None),
op("sql.query@1", "sql@1", Grant::Schema),
op("sql.exec@1", "sql@1", Grant::Schema),
op("http.fetch@1", "http.fetch@1", Grant::Hosts),
op("telemetry.read@1", "telemetry.read@1", Grant::Site),
op("cfg.read@1", "cfg.read@1", Grant::Site),
op("cfg.write@1", "cfg.write@1", Grant::SitePaths),
op("command.send@1", "command.send@1", Grant::SiteVerbs),
op("audit@1", "audit@1", Grant::None),
op("perm.check@1", "perm.check@1", Grant::None),
op("appcred.verify@1", "appcred.verify@1", Grant::None),
op("app.request@1", "app.request@1", Grant::Site),
op("secret.get@1", "secret.get@1", Grant::Secret),
op("time.now@1", "time.now@1", Grant::None),
op("rand.bytes@1", "rand.bytes@1", Grant::None),
];
/// Look an op up by its exact name.
pub fn op_def(name: &str) -> Option<&'static OpDef> {
OPS.iter().find(|o| o.name == name)
}
/// True when `entry` (an op name or a family name) covers `op`.
pub fn covers(entry: &str, op: &str) -> bool {
op_def(op).is_some_and(|d| d.name == entry || d.family == entry)
}
/// Check a manifest op list: every entry must be a known op or family.
pub fn check_manifest_ops(entries: &[&str]) -> Result<()> {
for e in entries {
let known = OPS.iter().any(|o| o.name == *e || o.family == *e);
if !known {
return Err(Error::new(Code::Manifest, format!("unknown op {e}")));
}
}
Ok(())
}
/// A parsed `fp1.call` request.
#[derive(Clone, Debug, PartialEq)]
pub struct CallRequest {
pub op: &'static OpDef,
pub args: Value,
}
/// Parse the JSON request of `fp1.call`. Errors map to the negative code the
/// host returns to the guest.
pub fn parse_call(bytes: &[u8]) -> std::result::Result<CallRequest, Neg> {
if bytes.len() > MAX_MESSAGE_BYTES {
return Err(Neg::Limit);
}
let v: Value = serde_json::from_slice(bytes).map_err(|_| Neg::Arg)?;
let o = v.as_object().ok_or(Neg::Arg)?;
if o.keys().any(|k| k != "op" && k != "args") {
return Err(Neg::Arg);
}
let name = o.get("op").and_then(Value::as_str).ok_or(Neg::Arg)?;
let def = op_def(name).ok_or(Neg::OpUnknown)?;
let args = match o.get("args") {
None => Value::Object(Default::default()),
Some(a) if a.is_object() => a.clone(),
Some(_) => return Err(Neg::Arg),
};
Ok(CallRequest { op: def, args })
}
/// Response headers a plugin may set (13.4.2). `set-cookie` is never allowed.
/// Returns the value to emit, or `None` to drop the header.
pub fn filter_response_header(name: &str, value: &str) -> Option<String> {
let n = name.to_ascii_lowercase();
if value.bytes().any(|b| b == b'\r' || b == b'\n' || b == 0) {
return None;
}
match n.as_str() {
"content-type" | "x-request-id" => Some(value.to_string()),
"cache-control" => {
(value.trim().eq_ignore_ascii_case("no-store")).then(|| "no-store".to_string())
}
// Same origin only: a path, never a scheme, authority or `//`.
"location" => (value.starts_with('/') && !value.starts_with("//") && !value.contains('\\'))
.then(|| value.to_string()),
_ => None,
}
}
/// True when `path` is a route a plugin with id `id` may mount (13.4.2).
pub fn route_allowed(id: &str, path: &str) -> bool {
let ok_id = !id.is_empty()
&& id
.bytes()
.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-');
if !ok_id || path.contains("..") || path.contains("//") || path.contains('?') {
return false;
}
let pages = format!("/apps/{id}/");
let api = format!("/api/v1/apps/{id}/");
(path.starts_with(&pages) && path.len() > pages.len())
|| (path.starts_with(&api) && path.len() > api.len())
|| path == format!("/apps/{id}")
|| path == format!("/api/v1/apps/{id}")
}
+40
View File
@@ -0,0 +1,40 @@
//! Plugin and module admission shared by FLARE and the Warden console
//! (d04 13.3.5, 13.4; B-13, W-D4).
//!
//! - `package`: the admission entry points. Each one runs the `.wapp` package
//! checks of `wapp_core::validate_full` first, so a signature, key class,
//! hash or payload failure refuses the package before any code check runs.
//! Only `platform`-signed code is admitted (`dev` only in a `plugin-dev`
//! build, `partner` never). FLARE verifies signatures itself and refuses on
//! failure (B-13).
//! - `wmod`: the ELF verifier for panel modules (`ui/modules/*.so`, ABI
//! `wmod/1`): header, dynamic section, symbol lists, info block, grants.
//! - `wasm`: the Wasm verifier for FLARE plugins (ABI `fp/1`, feature `wasm`):
//! core Wasm validated with `wasmparser`, imports, exports and limits.
//! - `fp1`: the `fp/1` surface data: names, handler kinds, negative codes, the
//! op registry and the request and header validators.
//! - `code`: the reason codes shared by all of the above.
//!
//! The verifiers never run module code. Every check reads the bytes only.
pub mod code;
pub mod fp1;
pub mod package;
#[cfg(feature = "wasm")]
pub mod wasm;
pub mod wmod;
pub use code::{Code, Error, Result};
/// Crate name, used by consumers to check which pin they vendored.
pub const NAME: &str = "flare-plugin-abi";
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn name_is_stable() {
assert_eq!(NAME, "flare-plugin-abi");
}
}
@@ -0,0 +1,250 @@
//! Admission of the code inside one signed `.wapp` (d04 13.3.5, 13.4.8; B-13).
//!
//! Each entry point runs `wapp_core::validate::validate_full` first (V01 to
//! V09, V15 and V16), so a signature, key class, hash or payload failure
//! refuses the package here, whatever the caller checked before. The signer
//! must be `platform`. A `dev` signer is admitted only by a build with the
//! `plugin-dev` feature, and a `partner` signer is never admitted: no
//! third-party code runs before an out-of-process runtime exists (B-13).
use crate::code::{Code, Error, Result};
use crate::wmod::{self, Compat, Expect, Info, NameList, Policy};
use wapp_core::appkeys::KeyClass;
use wapp_core::json::Value;
use wapp_core::payload::Checked;
use wapp_core::validate::{validate_full, Ctx, Validated};
/// True when this build admits `dev`-class signatures (feature `plugin-dev`).
pub const DEV_COMPILED: bool = cfg!(feature = "plugin-dev");
/// The `FLARE_PLUGINS` modes (d04 13.4.8). `off` is the default.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PluginMode {
/// Wasm plugins are refused with `E_KEY plugins_off`; descriptors install.
Off,
/// Only `platform`-signed plugins load.
Signed,
/// `dev`-signed plugins load too, and only in a `plugin-dev` build.
Dev,
}
impl PluginMode {
/// The value of `FLARE_PLUGINS`, or `None` for any other text.
pub fn parse(s: &str) -> Option<PluginMode> {
match s {
"off" => Some(PluginMode::Off),
"signed" => Some(PluginMode::Signed),
"dev" => Some(PluginMode::Dev),
_ => None,
}
}
/// Startup check: a release build refuses `FLARE_PLUGINS=dev` (13.4.8).
pub fn check_startup(self) -> Result<()> {
match self {
PluginMode::Dev if !DEV_COMPILED => Err(Error::new(
Code::Key,
"FLARE_PLUGINS=dev needs a plugin-dev build",
)),
_ => Ok(()),
}
}
}
/// Refuse every signer class this build does not admit. `dev_wanted` says
/// whether the caller accepts `dev` at all.
fn check_signer(v: &Validated, dev_wanted: bool) -> Result<()> {
match v.signer.class {
KeyClass::Platform => Ok(()),
KeyClass::Dev if dev_wanted && DEV_COMPILED => Ok(()),
KeyClass::Dev => Err(Error::new(
Code::Key,
"dev key class is not admitted in this build",
)),
KeyClass::Partner => Err(Error::new(
Code::Key,
"partner key class is refused until an out-of-process runtime exists",
)),
}
}
fn missing(what: &str) -> Error {
Error::new(Code::Manifest, format!("{what} is missing"))
}
fn not_in_package(path: &str) -> Error {
Error::new(Code::Manifest, format!("{path} is not in the package"))
}
/// A FLARE plugin package admitted for install (13.4.7, `verified`).
#[cfg(feature = "wasm")]
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct PluginAdmission {
pub app_id: String,
pub app_build: i64,
pub kid: String,
pub class: KeyClass,
/// The module inside the package, for example `flare/plugin.wasm`.
pub module: String,
pub admitted: crate::wasm::Admitted,
}
/// Admit the FLARE plugin in `archive`: the package checks, the platform
/// signer, the `fp/1` block of the manifest and the Wasm module (13.4.4).
#[cfg(feature = "wasm")]
pub fn admit_plugin(mode: PluginMode, archive: &[u8], ctx: &Ctx<'_>) -> Result<PluginAdmission> {
match mode {
PluginMode::Off => return Err(Error::new(Code::Key, "plugins_off")),
PluginMode::Dev => mode.check_startup()?,
PluginMode::Signed => {}
}
let (v, checked) = validate_full(archive, ctx)?;
check_signer(&v, mode == PluginMode::Dev)?;
let flare = v
.manifest
.flare
.as_ref()
.ok_or_else(|| missing("manifest flare half"))?;
let plugin = flare
.plugin
.as_ref()
.ok_or_else(|| Error::new(Code::Manifest, "flare half is not a plugin"))?;
if plugin.get("abi").and_then(Value::as_int) != Some(1) {
return Err(Error::new(
Code::Manifest,
"flare.plugin.abi must be 1 (fp/1)",
));
}
let module = plugin
.get("module")
.and_then(Value::as_str)
.ok_or_else(|| missing("flare.plugin.module"))?;
if !module.starts_with("flare/") {
return Err(Error::new(
Code::Manifest,
"flare.plugin.module must be under flare/",
));
}
let memory_mb = plugin
.get("limits")
.and_then(|l| l.get("memory_mb"))
.and_then(Value::as_int)
.and_then(|m| u32::try_from(m).ok())
.ok_or_else(|| missing("flare.plugin.limits.memory_mb"))?;
let bytes = checked.file(module).ok_or_else(|| not_in_package(module))?;
let admitted = crate::wasm::admit(bytes, memory_mb)?;
Ok(PluginAdmission {
app_id: v.manifest.id.clone(),
app_build: v.manifest.build,
kid: v.signer.kid.clone(),
class: v.signer.class,
module: module.to_string(),
admitted,
})
}
/// What the firmware offers a panel module: the import lists, the ABI and
/// LVGL build it runs, and the permission names the install granted.
pub struct Host<'a> {
/// `wmod-libc.allow`.
pub libc_allow: &'a NameList,
/// `wmod_exports.list`: the host symbols a Layer 2 module may call.
pub host_exports: &'a NameList,
/// The manifest declares C++, so `libstdc++.so.6` may be needed.
pub cxx: bool,
pub abi_major: u16,
pub abi_minor: u16,
pub lvgl_version: &'a str,
pub sdk_hash: [u8; 32],
/// Permission names the install granted, for example `ui.native`.
pub granted: &'a [&'a str],
}
/// A panel module admitted for install (13.3.5, `verified` in 13.3.6).
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ModuleAdmission {
pub app_id: String,
pub app_build: i64,
pub kid: String,
pub class: KeyClass,
/// The module inside the package, for example `ui/modules/mining.so`.
pub module: String,
/// The libraries the module needs (DT_NEEDED).
pub needed: Vec<String>,
pub info: Info,
/// `NeedsPlatform` when a matching firmware update must come first. That
/// is still an admission: the install goes through (13.3.6).
pub compat: Compat,
}
/// Admit the panel module in `archive` (13.3.5). The package must be signed
/// by `platform` (or `dev` in a `plugin-dev` build).
pub fn admit_module(archive: &[u8], ctx: &Ctx<'_>, host: &Host<'_>) -> Result<ModuleAdmission> {
let (v, checked) = validate_full(archive, ctx)?;
admit_validated_module(&v, &checked, host)
}
/// [`admit_module`] for a package that `validate_full` has already accepted.
/// An installer holds that result by the time it checks the modules, so the
/// package is verified once, not twice.
pub fn admit_validated_module(
v: &Validated,
checked: &Checked,
host: &Host<'_>,
) -> Result<ModuleAdmission> {
check_signer(v, true)?;
let native = v
.manifest
.ui_native
.as_ref()
.ok_or_else(|| missing("ui.native block"))?;
let module = native
.get("module")
.and_then(Value::as_str)
.ok_or_else(|| missing("ui.native.module"))?;
if !module.starts_with("ui/modules/") {
return Err(Error::new(
Code::Manifest,
"ui.native.module must be under ui/modules/",
));
}
let bytes = checked.file(module).ok_or_else(|| not_in_package(module))?;
let policy = Policy {
libc_allow: host.libc_allow,
host_exports: host.host_exports,
cxx: host.cxx,
};
let needed = wmod::check_module(bytes, &policy)?;
let info = Info::parse(wmod::info_block(bytes)?)?;
let app_build = u32::try_from(v.manifest.build)
.map_err(|_| Error::new(Code::Manifest, "manifest build out of range"))?;
let compat = wmod::check_info(
&info,
&Expect {
abi_major: host.abi_major,
abi_minor: host.abi_minor,
app_id: &v.manifest.id,
app_build,
lvgl_version: host.lvgl_version,
sdk_hash: host.sdk_hash,
},
)?;
// Every platform verb the manifest declares must be granted (13.3.5).
let verbs: Vec<&str> = v
.manifest
.permissions
.iter()
.filter_map(|p| p.name.strip_prefix("platform."))
.collect();
wmod::check_grants(&info, host.granted, &verbs)?;
Ok(ModuleAdmission {
app_id: v.manifest.id.clone(),
app_build: v.manifest.build,
kid: v.signer.kid.clone(),
class: v.signer.class,
module: module.to_string(),
needed,
info,
compat,
})
}
+219
View File
@@ -0,0 +1,219 @@
//! Wasm module admission (d04 13.4.4): the checks that run before a plugin
//! module is compiled, at install and again on every load from disk.
//!
//! Admitted modules import nothing but `fp1.call` and `fp1.log` (each at most
//! once, with its fixed signature), have no start function, export the five
//! required names with the right types, declare a single memory with a
//! maximum at or below the manifest limit, use no threads or SIMD, and are at
//! most 2 MiB. A module that imports only one of the two is admitted; the
//! amendments in the crate README record that reading of 13.4.4.
use crate::code::{Code, Error, Result};
use crate::fp1::*;
use wasmparser::{
CompositeInnerType, ExternalKind, FuncType, Parser, Payload, TypeRef, ValType, Validator,
WasmFeatures,
};
/// What admission learned about a module.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Admitted {
pub memory_min_pages: u64,
pub memory_max_pages: u64,
pub imports_log: bool,
pub imports_call: bool,
}
fn wasm(m: impl Into<String>) -> Error {
Error::new(Code::Wasm, m)
}
/// Core Wasm 1.0 plus the post-MVP features rustc and clang emit by default
/// that wasmi runs (sign extension, saturating conversion, multi-value, bulk
/// memory, reference types). No threads, SIMD, GC, exceptions, memory64 or
/// relaxed SIMD.
fn features() -> WasmFeatures {
WasmFeatures::MUTABLE_GLOBAL
| WasmFeatures::SATURATING_FLOAT_TO_INT
| WasmFeatures::SIGN_EXTENSION
| WasmFeatures::MULTI_VALUE
| WasmFeatures::BULK_MEMORY
| WasmFeatures::REFERENCE_TYPES
| WasmFeatures::FLOATS
}
fn sig_is(t: &FuncType, params: &[ValType], results: &[ValType]) -> bool {
t.params() == params && t.results() == results
}
/// Admit `bytes` for a plugin whose manifest allows `memory_mb` MiB.
pub fn admit(bytes: &[u8], memory_mb: u32) -> Result<Admitted> {
if bytes.len() > MAX_MODULE_BYTES {
return Err(Error::new(Code::Limit, "module larger than 2 MiB"));
}
if memory_mb == 0 {
return Err(Error::new(
Code::Manifest,
"limits.memory_mb must be positive",
));
}
let limit_pages = u64::from(memory_mb) * 16;
let mut v = Validator::new_with_features(features());
let mut types: Vec<Option<FuncType>> = Vec::new();
// Type index of every function: imports first, then defined functions.
let mut funcs: Vec<u32> = Vec::new();
let (mut call_seen, mut log_seen) = (false, false);
let mut memory: Option<(u64, u64)> = None;
let mut tables = 0usize;
let mut exports: Vec<(String, ExternalKind, u32)> = Vec::new();
for payload in Parser::new(0).parse_all(bytes) {
let payload = payload.map_err(|e| wasm(format!("malformed module: {e}")))?;
v.payload(&payload)
.map_err(|e| wasm(format!("invalid module: {e}")))?;
match payload {
Payload::Version { encoding, .. } => {
if encoding != wasmparser::Encoding::Module {
return Err(wasm("not a core module"));
}
}
Payload::TypeSection(r) => {
for rg in r {
let rg = rg.map_err(|e| wasm(e.to_string()))?;
for st in rg.into_types() {
types.push(match st.composite_type.inner {
CompositeInnerType::Func(f) => Some(f),
_ => return Err(wasm("only function types are allowed")),
});
}
}
}
Payload::ImportSection(r) => {
for imp in r {
let imp = imp.map_err(|e| wasm(e.to_string()))?;
let TypeRef::Func(ti) = imp.ty else {
return Err(Error::new(
Code::Import,
format!("import {}.{} is not a function", imp.module, imp.name),
));
};
let t = types
.get(ti as usize)
.and_then(|t| t.as_ref())
.ok_or_else(|| wasm("import type out of range"))?;
use ValType::I32;
match (imp.module, imp.name) {
(IMPORT_MODULE, IMPORT_CALL) => {
if call_seen || !sig_is(t, &[I32, I32, I32, I32], &[I32]) {
return Err(Error::new(
Code::Import,
"fp1.call has the wrong type",
));
}
call_seen = true;
}
(IMPORT_MODULE, IMPORT_LOG) => {
if log_seen || !sig_is(t, &[I32, I32, I32], &[]) {
return Err(Error::new(Code::Import, "fp1.log has the wrong type"));
}
log_seen = true;
}
(m, n) => {
return Err(Error::new(Code::Import, format!("unknown import {m}.{n}")))
}
}
funcs.push(ti);
}
}
Payload::FunctionSection(r) => {
for ti in r {
funcs.push(ti.map_err(|e| wasm(e.to_string()))?);
}
}
Payload::TableSection(r) => {
tables += r.count() as usize;
}
Payload::MemorySection(r) => {
for m in r {
let m = m.map_err(|e| wasm(e.to_string()))?;
if memory.is_some() {
return Err(wasm("more than one memory"));
}
if m.memory64 || m.shared {
return Err(wasm("memory64 and shared memory are not allowed"));
}
let Some(max) = m.maximum else {
return Err(Error::new(Code::Limit, "memory has no declared maximum"));
};
if max > limit_pages {
return Err(Error::new(
Code::Limit,
format!("memory maximum {max} pages exceeds {limit_pages}"),
));
}
memory = Some((m.initial, max));
}
}
Payload::StartSection { .. } => return Err(wasm("start function is not allowed")),
Payload::ExportSection(r) => {
for e in r {
let e = e.map_err(|e| wasm(e.to_string()))?;
exports.push((e.name.to_string(), e.kind, e.index));
}
}
Payload::UnknownSection { .. } => return Err(wasm("unknown section")),
_ => {}
}
}
if tables > 1 {
return Err(wasm("more than one table"));
}
let Some((min, max)) = memory else {
return Err(wasm("no memory defined"));
};
if min > max {
return Err(wasm("memory minimum above maximum"));
}
let find = |name: &str| exports.iter().find(|(n, _, _)| n == name);
let func_sig = |name: &str, params: &[ValType], results: &[ValType]| -> Result<()> {
let Some((_, kind, idx)) = find(name) else {
return Err(wasm(format!("missing export {name}")));
};
if *kind != ExternalKind::Func {
return Err(wasm(format!("export {name} is not a function")));
}
let ti = funcs
.get(*idx as usize)
.ok_or_else(|| wasm("export index out of range"))?;
let t = types
.get(*ti as usize)
.and_then(|t| t.as_ref())
.ok_or_else(|| wasm("function type out of range"))?;
if sig_is(t, params, results) {
Ok(())
} else {
Err(wasm(format!("export {name} has the wrong type")))
}
};
use ValType::{I32, I64};
match find(EXPORT_MEMORY) {
Some((_, ExternalKind::Memory, 0)) => {}
_ => return Err(wasm("missing export memory")),
}
func_sig(EXPORT_ALLOC, &[I32], &[I32])?;
func_sig(EXPORT_FREE, &[I32, I32], &[])?;
func_sig(EXPORT_INIT, &[I32, I32], &[I32])?;
func_sig(EXPORT_HANDLE, &[I32, I32, I32], &[I64])?;
for (i, (n, _, _)) in exports.iter().enumerate() {
if exports[..i].iter().any(|(m, _, _)| m == n) {
return Err(wasm("duplicate export name"));
}
}
Ok(Admitted {
memory_min_pages: min,
memory_max_pages: max,
imports_call: call_seen,
imports_log: log_seen,
})
}
+923
View File
@@ -0,0 +1,923 @@
//! Warden native module admission (d04 13.3.5): the static checks on a
//! `wmod/1` shared object before `dlopen`.
//!
//! The input is attacker-shaped bytes, so every read is bounds checked and
//! every count is capped. The verifier checks the image the loader maps: the
//! dynamic section and every table it names are read at their load addresses
//! through the PT_LOAD segments. A section header that names one of those
//! tables must name the same file bytes (#187).
use crate::code::{Code, Error, Result};
use std::collections::BTreeSet;
pub const ENTRY_SYMBOL: &str = "wmod_entry";
const ET_DYN: u16 = 3;
const EM_ARM: u16 = 40;
const EF_ARM_ABI_FLOAT_HARD: u32 = 0x400;
const PT_LOAD: u32 = 1;
const PT_DYNAMIC: u32 = 2;
const PT_GNU_STACK: u32 = 0x6474_e551;
const PF_X: u32 = 1;
const STB_LOCAL: u8 = 0;
const SHT_DYNSYM: u32 = 11;
const SHT_NOBITS: u32 = 8;
const DT_NULL: u32 = 0;
const DT_NEEDED: u32 = 1;
const DT_STRTAB: u32 = 5;
const DT_SYMTAB: u32 = 6;
const DT_STRSZ: u32 = 10;
const DT_RPATH: u32 = 15;
const DT_TEXTREL: u32 = 22;
const DT_RUNPATH: u32 = 29;
const DT_FLAGS: u32 = 30;
const DT_FLAGS_1: u32 = 0x6fff_fffb;
const DF_TEXTREL: u32 = 4;
const DF_BIND_NOW: u32 = 8;
const DF_1_NOW: u32 = 1;
const MAX_PHNUM: usize = 64;
const MAX_SHNUM: usize = 512;
const MAX_DYN: usize = 512;
const MAX_SYMS: usize = 65_536;
/// Libraries a module may need. `libstdc++.so.6` only when C++ is declared.
pub const NEEDED_BASE: &[&str] = &["libc.so.0", "libm.so.0", "libgcc_s.so.1"];
pub const NEEDED_CXX: &str = "libstdc++.so.6";
/// Imports refused whatever the allow list says (13.3.5): the allocator
/// family, files and sockets, process control, signals, and bus handles.
pub const DENIED_IMPORTS: &[&str] = &[
"malloc",
"calloc",
"realloc",
"free",
"posix_memalign",
"memalign",
"aligned_alloc",
"valloc",
"open",
"openat",
"creat",
"fopen",
"fdopen",
"freopen",
"read",
"write",
"socket",
"connect",
"bind",
"listen",
"accept",
"send",
"recv",
"sendto",
"recvfrom",
"mmap",
"mmap2",
"mprotect",
"munmap",
"dlopen",
"dlsym",
"dlclose",
"fork",
"vfork",
"clone",
"system",
"popen",
"signal",
"sigaction",
"setjmp",
"longjmp",
"_setjmp",
"siglongjmp",
"sigsetjmp",
"abort",
"exit",
"_exit",
"getenv",
"setenv",
"putenv",
"kill",
"raise",
"syscall",
"prctl",
"ptrace",
"ioctl",
];
/// True for an import the verifier refuses whatever the allow list says:
/// the exact names above plus the `pthread_*` and `exec*` families.
pub fn is_denied(name: &str) -> bool {
DENIED_IMPORTS.contains(&name) || name.starts_with("pthread_") || name.starts_with("exec")
}
/// A parsed `wmod-libc.allow` or `wmod_exports.list`: names, with a trailing
/// `*` as a prefix wildcard. Lines starting with `#` and blank lines are
/// ignored.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct NameList {
exact: BTreeSet<String>,
prefix: Vec<String>,
}
impl NameList {
pub fn parse(text: &str) -> NameList {
let mut l = NameList::default();
for line in text.lines() {
let t = line.trim();
if t.is_empty() || t.starts_with('#') {
continue;
}
match t.strip_suffix('*') {
Some(p) => l.prefix.push(p.to_string()),
None => {
l.exact.insert(t.to_string());
}
}
}
l
}
pub fn contains(&self, name: &str) -> bool {
self.exact.contains(name) || self.prefix.iter().any(|p| name.starts_with(p.as_str()))
}
}
/// What the firmware tells the verifier about the module.
pub struct Policy<'a> {
/// `wmod-libc.allow`.
pub libc_allow: &'a NameList,
/// `wmod_exports.list`: host symbols a Layer 2 module may call.
pub host_exports: &'a NameList,
/// The manifest declares C++, so `libstdc++.so.6` may be needed.
pub cxx: bool,
}
fn elf<T>(m: impl Into<String>) -> Result<T> {
Err(Error::new(Code::Elf, m))
}
fn sym<T>(m: impl Into<String>) -> Result<T> {
Err(Error::new(Code::Symbols, m))
}
fn u16le(b: &[u8], o: usize) -> Option<u16> {
Some(u16::from_le_bytes(
b.get(o..o.checked_add(2)?)?.try_into().ok()?,
))
}
fn u32le(b: &[u8], o: usize) -> Option<u32> {
Some(u32::from_le_bytes(
b.get(o..o.checked_add(4)?)?.try_into().ok()?,
))
}
fn slice(b: &[u8], off: usize, len: usize) -> Option<&[u8]> {
b.get(off..off.checked_add(len)?)
}
fn cstr(table: &[u8], off: usize) -> Option<&str> {
let rest = table.get(off..)?;
let end = rest.iter().position(|&c| c == 0)?;
std::str::from_utf8(&rest[..end]).ok()
}
// Tags and flags the verifier reads beyond the constants above.
const DT_PLTRELSZ: u32 = 2;
const DT_HASH: u32 = 4;
const DT_RELA: u32 = 7;
const DT_RELASZ: u32 = 8;
const DT_RELAENT: u32 = 9;
const DT_REL: u32 = 17;
const DT_RELSZ: u32 = 18;
const DT_RELENT: u32 = 19;
const DT_PLTREL: u32 = 20;
const DT_JMPREL: u32 = 23;
const DT_GNU_HASH: u32 = 0x6fff_fef5;
const SHF_ALLOC: u32 = 2;
/// One PT_LOAD segment: the loader maps `filesz` bytes from file offset `off`
/// at `vaddr` and zero-fills up to `memsz`.
#[derive(Clone, Copy, Debug)]
struct Load {
vaddr: u32,
memsz: u32,
off: u32,
filesz: u32,
}
/// The file offset of the `len` bytes at virtual address `va`, when they all
/// lie in the file contents of one PT_LOAD segment.
///
/// The dynamic linker reads the dynamic section, the string and symbol tables,
/// the hash tables, the relocations and the info block at their load addresses.
/// A table read at any other file offset can be a different table from the one
/// that loads, so every such read goes through this mapping (13.3.5).
fn va_off(loads: &[Load], va: u32, len: usize) -> Option<usize> {
let end = u64::from(va).checked_add(len as u64)?;
loads.iter().find_map(|l| {
let seg_end = u64::from(l.vaddr) + u64::from(l.filesz);
if u64::from(va) < u64::from(l.vaddr) || end > seg_end {
return None;
}
(l.off as usize).checked_add((va - l.vaddr) as usize)
})
}
/// The u32 at `base + add`, with both the sum and the read checked.
fn u32_at(b: &[u8], base: usize, add: usize) -> Option<u32> {
u32le(b, base.checked_add(add)?)
}
/// The u32 the loader reads at address `va`.
fn va_u32(b: &[u8], loads: &[Load], va: u64) -> Result<u32> {
let Ok(va) = u32::try_from(va) else {
return elf("table address outside the 32-bit address space");
};
match va_off(loads, va, 4).and_then(|o| u32le(b, o)) {
Some(v) => Ok(v),
None => elf("table entry outside the load segments"),
}
}
/// What the loader sees of the image: its PT_LOAD segments and PT_DYNAMIC.
struct Image {
loads: Vec<Load>,
/// (p_vaddr, p_offset, p_filesz) of PT_DYNAMIC.
dynamic: Option<(u32, u32, u32)>,
}
/// The ELF header and the program headers. `check_module` and `info_block`
/// both start here, so the info block is found through the same segments as
/// the rest of the image.
fn parse_image(b: &[u8]) -> Result<Image> {
if b.len() < 52 || &b[..4] != b"\x7fELF" {
return elf("not an ELF file");
}
if b[4] != 1 || b[5] != 1 {
return elf("not 32-bit little-endian");
}
if u16le(b, 16) != Some(ET_DYN) {
return elf("not a shared object (ET_DYN)");
}
if u16le(b, 18) != Some(EM_ARM) {
return elf("not EM_ARM");
}
let flags = u32le(b, 36).unwrap_or(0);
if flags >> 24 != 5 {
return elf("not EABI5");
}
if flags & EF_ARM_ABI_FLOAT_HARD == 0 {
return elf("not hard-float (a soft-float build is refused)");
}
// Program headers.
let phoff = u32le(b, 28).unwrap_or(0) as usize;
let phentsize = u16le(b, 42).unwrap_or(0) as usize;
let phnum = u16le(b, 44).unwrap_or(0) as usize;
if phentsize != 32 || phnum == 0 || phnum > MAX_PHNUM {
return elf("bad program header table");
}
let mut loads: Vec<Load> = Vec::new();
let mut dynamic = None;
let mut stack_seen = false;
for i in 0..phnum {
// Checked: on the 32-bit panel build a hostile e_phoff must not wrap.
let Some(o) = phoff.checked_add(i * 32) else {
return elf("program header outside the file");
};
let (Some(ty), Some(off), Some(va), Some(fsz), Some(msz), Some(pf)) = (
u32_at(b, o, 0),
u32_at(b, o, 4),
u32_at(b, o, 8),
u32_at(b, o, 16),
u32_at(b, o, 20),
u32_at(b, o, 24),
) else {
return elf("program header outside the file");
};
match ty {
PT_LOAD => {
if msz < fsz {
return elf("load segment is smaller in memory than in the file");
}
if slice(b, off as usize, fsz as usize).is_none() {
return elf("load segment outside the file");
}
loads.push(Load {
vaddr: va,
memsz: msz,
off,
filesz: fsz,
});
}
PT_DYNAMIC => {
if dynamic.is_some() {
return elf("more than one dynamic segment");
}
dynamic = Some((va, off, fsz));
}
PT_GNU_STACK => {
stack_seen = true;
if pf & PF_X != 0 {
return elf("executable stack");
}
}
_ => {}
}
}
// Two segments that map the same addresses have no single loaded image.
for (i, a) in loads.iter().enumerate() {
for c in &loads[i + 1..] {
let a0 = u64::from(a.vaddr);
let a1 = a0 + u64::from(a.memsz);
let c0 = u64::from(c.vaddr);
let c1 = c0 + u64::from(c.memsz);
if a0 < c1 && c0 < a1 {
return elf("load segments overlap");
}
}
}
if !stack_seen {
return elf("no PT_GNU_STACK (stack permissions unknown)");
}
Ok(Image { loads, dynamic })
}
/// One section header.
#[derive(Clone, Copy, Debug)]
struct Shdr {
ty: u32,
flags: u32,
addr: u32,
off: u32,
size: u32,
}
/// Every section header with its name. The loader does not read section
/// headers. The verifier reads them to find each table's file bytes and to
/// check those bytes against the loaded addresses.
fn sections(b: &[u8]) -> Result<Vec<(Shdr, &str)>> {
let shoff = u32le(b, 32).unwrap_or(0) as usize;
let shentsize = u16le(b, 46).unwrap_or(0) as usize;
let shnum = u16le(b, 48).unwrap_or(0) as usize;
let shstrndx = u16le(b, 50).unwrap_or(0) as usize;
if shentsize != 40 || shnum == 0 || shnum > MAX_SHNUM {
return elf("no usable section headers");
}
let mut raw: Vec<(usize, Shdr)> = Vec::with_capacity(shnum);
for i in 0..shnum {
let Some(o) = shoff.checked_add(i * 40) else {
return elf("section header outside the file");
};
let (Some(name), Some(ty), Some(flags), Some(addr), Some(off), Some(size)) = (
u32_at(b, o, 0),
u32_at(b, o, 4),
u32_at(b, o, 8),
u32_at(b, o, 12),
u32_at(b, o, 16),
u32_at(b, o, 20),
) else {
return elf("section header outside the file");
};
raw.push((
name as usize,
Shdr {
ty,
flags,
addr,
off,
size,
},
));
}
let names: &[u8] = match raw.get(shstrndx) {
Some((_, s)) => slice(b, s.off as usize, s.size as usize).unwrap_or(&[]),
None => &[],
};
Ok(raw
.into_iter()
.map(|(name, s)| (s, cstr(names, name).unwrap_or("")))
.collect())
}
/// The dynamic entries the verifier uses, read from the loaded dynamic section.
#[derive(Default)]
struct Dynamic {
needed: Vec<usize>,
strtab: Option<u32>,
strsz: Option<u32>,
symtab: Option<u32>,
hash: Option<u32>,
gnu_hash: Option<u32>,
rel: Option<u32>,
relsz: Option<u32>,
relent: Option<u32>,
rela: Option<u32>,
relasz: Option<u32>,
relaent: Option<u32>,
jmprel: Option<u32>,
pltrelsz: Option<u32>,
pltrel: Option<u32>,
flags: u32,
flags_1: u32,
}
/// Read the dynamic section. A tag the verifier relies on may appear once: a
/// second entry is refused rather than guessed at, because the verifier and
/// the loader could otherwise read different copies.
fn read_dynamic(dyn_bytes: &[u8]) -> Result<Dynamic> {
let mut d = Dynamic::default();
let mut seen: BTreeSet<u32> = BTreeSet::new();
for (n, ent) in dyn_bytes.chunks_exact(8).enumerate() {
if n >= MAX_DYN {
return elf("dynamic section too long");
}
let tag = u32::from_le_bytes([ent[0], ent[1], ent[2], ent[3]]);
let val = u32::from_le_bytes([ent[4], ent[5], ent[6], ent[7]]);
if tag == DT_NULL {
break;
}
let once = matches!(
tag,
DT_STRTAB
| DT_STRSZ
| DT_SYMTAB
| DT_HASH
| DT_GNU_HASH
| DT_REL
| DT_RELSZ
| DT_RELENT
| DT_RELA
| DT_RELASZ
| DT_RELAENT
| DT_JMPREL
| DT_PLTRELSZ
| DT_PLTREL
| DT_FLAGS
| DT_FLAGS_1
);
if once && !seen.insert(tag) {
return elf("more than one dynamic entry for a table the verifier reads");
}
match tag {
DT_NEEDED => d.needed.push(val as usize),
DT_STRTAB => d.strtab = Some(val),
DT_STRSZ => d.strsz = Some(val),
DT_SYMTAB => d.symtab = Some(val),
DT_HASH => d.hash = Some(val),
DT_GNU_HASH => d.gnu_hash = Some(val),
DT_REL => d.rel = Some(val),
DT_RELSZ => d.relsz = Some(val),
DT_RELENT => d.relent = Some(val),
DT_RELA => d.rela = Some(val),
DT_RELASZ => d.relasz = Some(val),
DT_RELAENT => d.relaent = Some(val),
DT_JMPREL => d.jmprel = Some(val),
DT_PLTRELSZ => d.pltrelsz = Some(val),
DT_PLTREL => d.pltrel = Some(val),
DT_RPATH | DT_RUNPATH => return elf("DT_RPATH or DT_RUNPATH present"),
DT_TEXTREL => return elf("DT_TEXTREL present"),
DT_FLAGS => d.flags = val,
DT_FLAGS_1 => d.flags_1 = val,
_ => {}
}
}
Ok(d)
}
/// One relocation table, REL or RELA. The loader resolves each entry's symbol
/// index without a bounds check, so every index must name a checked symbol.
/// `nsyms` counts the checked entries, index 0 included.
fn check_relocs(
b: &[u8],
loads: &[Load],
table: Option<u32>,
size: Option<u32>,
declared_entsize: Option<u32>,
entsize: u32,
nsyms: usize,
) -> Result<()> {
if declared_entsize.is_some_and(|e| e != entsize) {
return elf("relocation entry size is not the ELF size");
}
let size = size.unwrap_or(0);
if size == 0 {
return Ok(());
}
let Some(va) = table else {
return elf("relocation size without a relocation table");
};
if size % entsize != 0 {
return elf("relocation table is not a whole number of entries");
}
let Some(base) = va_off(loads, va, size as usize) else {
return elf("relocation table is not in a load segment");
};
for k in 0..size / entsize {
// r_info is the second word of both the REL and the RELA entry.
let Some(info) = u32le(b, base + (k * entsize) as usize + 4) else {
return elf("relocation table outside the file");
};
let index = (info >> 8) as usize;
if index != 0 && index >= nsyms {
return elf("relocation names a symbol outside the checked table");
}
}
Ok(())
}
/// DT_HASH. A lookup walks these chains to find a symbol by name, so the table
/// may count no more symbols than were checked, and every bucket and chain
/// value must name a checked symbol.
fn check_sysv_hash(b: &[u8], loads: &[Load], va: u32, nsyms: usize) -> Result<()> {
let nbucket = va_u32(b, loads, u64::from(va))?;
let nchain = va_u32(b, loads, u64::from(va) + 4)?;
if nchain as usize > nsyms {
return elf("hash table counts more symbols than the checked table");
}
let words = u64::from(nbucket) + u64::from(nchain);
let Some(len) = words.checked_mul(4).and_then(|w| w.checked_add(8)) else {
return elf("hash table too large");
};
let Some(base) = usize::try_from(len).ok().and_then(|n| va_off(loads, va, n)) else {
return elf("hash table is not in one load segment");
};
let Some(body) = slice(b, base + 8, (len - 8) as usize) else {
return elf("hash table outside the file");
};
for c in body.chunks_exact(4) {
if u32::from_le_bytes([c[0], c[1], c[2], c[3]]) as usize >= nsyms {
return elf("hash table names a symbol outside the checked table");
}
}
Ok(())
}
/// DT_GNU_HASH. A lookup walks each bucket's chain from `symoffset` until a
/// chain word with its low bit set. Every index a walk reaches must name a
/// checked symbol.
fn check_gnu_hash(b: &[u8], loads: &[Load], va: u32, nsyms: usize) -> Result<()> {
let va = u64::from(va);
let nbuckets = u64::from(va_u32(b, loads, va)?);
let symoffset = va_u32(b, loads, va + 4)?;
let bloom_words = u64::from(va_u32(b, loads, va + 8)?);
let buckets = va + 16 + 4 * bloom_words;
let chains = buckets + 4 * nbuckets;
let mut seen = vec![false; nsyms];
for k in 0..nbuckets {
let mut i = va_u32(b, loads, buckets + 4 * k)?;
while i != 0 {
if i < symoffset || i as usize >= nsyms {
return elf("GNU hash chain names a symbol outside the checked table");
}
if seen[i as usize] {
// Another bucket already walked the rest of this chain.
break;
}
seen[i as usize] = true;
let link = va_u32(b, loads, chains + 4 * u64::from(i - symoffset))?;
if link & 1 != 0 {
break;
}
i += 1;
}
}
Ok(())
}
/// Admit a module, returning the `DT_NEEDED` list on success.
///
/// The loader's view is the one checked. The dynamic section and every table
/// it names are read at their load addresses through the PT_LOAD segments. A
/// section header that names one of them must name the same file bytes, and
/// the symbol checks cover every index the loader can reach.
pub fn check_module(b: &[u8], policy: &Policy<'_>) -> Result<Vec<String>> {
let image = parse_image(b)?;
let loads = &image.loads;
// The dynamic section, read where the loader maps it (p_vaddr). Its file
// offset must name the same bytes.
let Some((dva, doff, dsz)) = image.dynamic else {
return elf("no dynamic segment");
};
let Some(dyn_at) = va_off(loads, dva, dsz as usize) else {
return elf("dynamic segment is not in a load segment");
};
if dyn_at != doff as usize {
return elf("dynamic segment file offset differs from its load address");
}
let Some(dyn_bytes) = slice(b, dyn_at, dsz as usize) else {
return elf("dynamic segment outside the file");
};
let d = read_dynamic(dyn_bytes)?;
// Modern linkers record text relocations as DF_TEXTREL in DT_FLAGS rather
// than with the DT_TEXTREL tag, so both spellings are refused (13.3.5).
if d.flags & DF_TEXTREL != 0 {
return elf("DF_TEXTREL in DT_FLAGS (text relocations)");
}
if d.flags & DF_BIND_NOW == 0 && d.flags_1 & DF_1_NOW == 0 {
return elf("not linked with BIND_NOW");
}
let (Some(strtab), Some(strsz), Some(symtab)) = (d.strtab, d.strsz, d.symtab) else {
return elf("missing DT_STRTAB, DT_STRSZ or DT_SYMTAB");
};
let Some(str_at) = va_off(loads, strtab, strsz as usize) else {
return elf("string table not in a load segment");
};
let Some(strs) = slice(b, str_at, strsz as usize) else {
return elf("string table outside the file");
};
let mut needed = Vec::new();
for &o in &d.needed {
let Some(name) = cstr(strs, o) else {
return elf("bad DT_NEEDED string");
};
let ok = NEEDED_BASE.contains(&name) || (policy.cxx && name == NEEDED_CXX);
if !ok {
return elf(format!(
"needs {name}, which the firmware does not ship for modules"
));
}
needed.push(name.to_string());
}
// The dynamic symbol table is the one at DT_SYMTAB. Its section header must
// name the same file bytes, and the table is read from there.
let secs = sections(b)?;
let mut dynsym: Option<Shdr> = None;
for (s, _) in &secs {
if s.addr != symtab {
continue;
}
if s.ty == SHT_NOBITS {
return elf("dynamic symbol table has no file contents");
}
if s.ty == SHT_DYNSYM {
if dynsym.is_some() {
return elf("more than one section matches DT_SYMTAB");
}
dynsym = Some(*s);
}
}
let Some(sym_sec) = dynsym else {
return elf("no section matches DT_SYMTAB");
};
if sym_sec.size % 16 != 0 {
return elf("dynamic symbol table is not a whole number of entries");
}
let Some(sym_at) = va_off(loads, symtab, sym_sec.size as usize) else {
return elf("dynamic symbol table is not in one load segment");
};
if sym_at != sym_sec.off as usize {
return elf("dynamic symbol table section offset differs from DT_SYMTAB's load address");
}
let Some(syms) = slice(b, sym_at, sym_sec.size as usize) else {
return elf("symbol table outside the file");
};
let nsyms = syms.len() / 16;
if nsyms > MAX_SYMS {
return elf("too many symbols");
}
let mut defined = Vec::new();
let mut undefined = Vec::new();
for s in syms.chunks_exact(16).skip(1) {
let name_off = u32::from_le_bytes([s[0], s[1], s[2], s[3]]) as usize;
let bind = s[12] >> 4;
let shndx = u16::from_le_bytes([s[14], s[15]]);
// Only LOCAL symbols stay out of the checks. GNU_UNIQUE (10) and the
// OS and processor ranges (11-15) bind by name like GLOBAL and WEAK,
// so they count as global: an extra one is an extra export, and an
// unlisted one is an unlisted import. Counting only 1 and 2 let them
// skip both checks.
if bind == STB_LOCAL {
continue;
}
let Some(name) = cstr(strs, name_off) else {
return elf("bad symbol name");
};
// An empty name is still a binding the loader can use, so it is
// checked like any other name instead of being skipped.
if shndx == 0 {
undefined.push(name.to_string());
} else {
defined.push(name.to_string());
}
}
if defined.len() != 1 || defined[0] != ENTRY_SYMBOL {
return sym(format!(
"exports must be exactly {ENTRY_SYMBOL}, found {} defined global symbols",
defined.len()
));
}
for name in &undefined {
if name.is_empty() {
return sym("import with an empty name is not allowed");
}
if is_denied(name) {
return sym(format!("import {name} is forbidden"));
}
if !(policy.libc_allow.contains(name) || policy.host_exports.contains(name)) {
return sym(format!("import {name} is not allowed"));
}
}
// The loader reaches a symbol by index through relocations and by chain
// through the hash tables. Each such index must be a checked symbol.
check_relocs(b, loads, d.rel, d.relsz, d.relent, 8, nsyms)?;
check_relocs(b, loads, d.rela, d.relasz, d.relaent, 12, nsyms)?;
let plt_entsize = match d.pltrel {
Some(DT_REL) => 8,
Some(DT_RELA) => 12,
Some(_) => return elf("DT_PLTREL names neither REL nor RELA"),
None if d.jmprel.is_none() => 8,
None => return elf("DT_JMPREL without DT_PLTREL"),
};
check_relocs(b, loads, d.jmprel, d.pltrelsz, None, plt_entsize, nsyms)?;
if let Some(h) = d.hash {
check_sysv_hash(b, loads, h, nsyms)?;
}
if let Some(g) = d.gnu_hash {
check_gnu_hash(b, loads, g, nsyms)?;
}
Ok(needed)
}
/// The fixed prefix of `wmod_info_t` (d04 13.3.3), 32-bit little endian.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Info {
pub size: u32,
pub abi_major: u16,
pub abi_minor: u16,
pub app_id: String,
pub app_build: u32,
pub flags: u32,
pub lvgl_version: String,
pub sdk_hash: [u8; 32],
}
pub const INFO_SIZE_MIN: usize = 4 + 2 + 2 + 32 + 4 + 4 + 16 + 32;
pub const F_LVGL_DIRECT: u32 = 1;
fn fixed_str(b: &[u8]) -> Option<String> {
let end = b.iter().position(|&c| c == 0)?;
if !b[..end].is_ascii() {
return None;
}
Some(String::from_utf8_lossy(&b[..end]).into_owned())
}
impl Info {
/// Parse the fixed prefix. The pointer members that follow are read by
/// the host from the loaded image, not here.
pub fn parse(b: &[u8]) -> Result<Info> {
if b.len() < INFO_SIZE_MIN {
return Err(Error::new(Code::Platform, "info block too short"));
}
let size = u32le(b, 0).unwrap_or(0);
if (size as usize) < INFO_SIZE_MIN {
return Err(Error::new(
Code::Platform,
"info block size field too small",
));
}
let bad = || Error::new(Code::Platform, "info block string not terminated ASCII");
let mut hash = [0u8; 32];
hash.copy_from_slice(&b[64..96]);
Ok(Info {
size,
abi_major: u16le(b, 4).unwrap_or(0),
abi_minor: u16le(b, 6).unwrap_or(0),
app_id: fixed_str(&b[8..40]).ok_or_else(bad)?,
app_build: u32le(b, 40).unwrap_or(0),
flags: u32le(b, 44).unwrap_or(0),
lvgl_version: fixed_str(&b[48..64]).ok_or_else(bad)?,
sdk_hash: hash,
})
}
}
/// Section that holds the `wmod_info_t` block. The module SDK links the block
/// here so the verifier can read it without running the module: `wmod_entry`
/// is the only exported symbol, so no symbol can name the block (13.3.2,
/// 13.3.5). The name is an amendment to 13.3.5, which leaves the locator open.
pub const INFO_SECTION: &str = ".wmod_info";
/// The bytes of the info block, found by section name. The host reads the
/// block at its load address, so the section must be allocated, must map
/// through the PT_LOAD segments to the file bytes its header names, and must be
/// the only section of that name. The caller parses the result with
/// [`Info::parse`].
pub fn info_block(b: &[u8]) -> Result<&[u8]> {
let image = parse_image(b)?;
let secs = sections(b)?;
let mut found: Option<Shdr> = None;
for (s, name) in &secs {
if *name == INFO_SECTION {
if found.is_some() {
return elf("more than one .wmod_info section");
}
found = Some(*s);
}
}
let Some(s) = found else {
return elf("no .wmod_info section (the info block cannot be found)");
};
if s.flags & SHF_ALLOC == 0 {
return elf(".wmod_info is not allocated, so the loader does not map it");
}
let Some(at) = va_off(&image.loads, s.addr, s.size as usize) else {
return elf(".wmod_info is not in a load segment");
};
if at != s.off as usize {
return elf(".wmod_info file offset differs from its load address");
}
match slice(b, at, s.size as usize) {
Some(bytes) if bytes.len() >= INFO_SIZE_MIN => Ok(bytes),
_ => elf("info block section outside the file or too short"),
}
}
/// What the firmware and manifest expect of the info block.
pub struct Expect<'a> {
pub abi_major: u16,
pub abi_minor: u16,
pub app_id: &'a str,
pub app_build: u32,
pub lvgl_version: &'a str,
pub sdk_hash: [u8; 32],
}
/// Outcome of the info-block check: a mismatch the device can recover from by
/// a firmware update is `NeedsPlatform` (module state `needs_platform`), not
/// a refusal.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Compat {
Ok,
NeedsPlatform(String),
}
/// Check the info block (13.3.5, 13.3.6). A wrong id or build, or an ABI
/// major other than the host's, is refused with `E_PLATFORM`: the file is not
/// a module this firmware can load (13.3.10, "major mismatch refused"). A
/// newer ABI minor, or an LVGL or SDK mismatch, is `NeedsPlatform`: a firmware
/// update that matches makes the module loadable (13.3.6).
pub fn check_info(i: &Info, e: &Expect<'_>) -> Result<Compat> {
if i.app_id != e.app_id {
return Err(Error::new(
Code::Platform,
"app_id differs from the manifest",
));
}
if i.app_build != e.app_build {
return Err(Error::new(
Code::Platform,
"app_build differs from the manifest",
));
}
if i.abi_major != e.abi_major {
return Err(Error::new(
Code::Platform,
format!(
"module ABI major {} differs from the host major {}",
i.abi_major, e.abi_major
),
));
}
if i.abi_minor > e.abi_minor {
return Ok(Compat::NeedsPlatform(format!(
"module ABI minor {} is above the host minor {}",
i.abi_minor, e.abi_minor
)));
}
if i.flags & F_LVGL_DIRECT != 0
&& (i.lvgl_version != e.lvgl_version || i.sdk_hash != e.sdk_hash)
{
return Ok(Compat::NeedsPlatform(
"LVGL version or SDK hash differs".into(),
));
}
Ok(Compat::Ok)
}
/// Permission check (13.3.5): `ui.native` granted, `ui.lvgl_direct` when the
/// flag is set, and each `platform.<verb>` the module uses is granted.
pub fn check_grants(info: &Info, granted: &[&str], verbs_used: &[&str]) -> Result<()> {
let has = |p: &str| granted.contains(&p);
if !has("ui.native") {
return Err(Error::new(Code::Grant, "ui.native not granted"));
}
if info.flags & F_LVGL_DIRECT != 0 && !has("ui.lvgl_direct") {
return Err(Error::new(Code::Grant, "ui.lvgl_direct not granted"));
}
for v in verbs_used {
if !has(&format!("platform.{v}")) {
return Err(Error::new(Code::Grant, format!("platform.{v} not granted")));
}
}
Ok(())
}
@@ -0,0 +1,817 @@
//! Builders for hostile and valid inputs. Everything is generated, so the
//! vectors are reviewable as code and no binary blobs are checked in.
#![allow(dead_code)]
#![allow(unused_imports)]
use flare_plugin_abi::wmod::INFO_SIZE_MIN;
use std::collections::BTreeMap;
use wapp_core::appkeys::{AllowedIds, AppKey, KeyClass};
use wapp_core::build::{pack, public_of};
use wapp_core::json::{self, Value};
use wapp_core::platform::Platform;
use wapp_core::validate::{Ctx, Revocations};
pub fn leb(mut n: u32) -> Vec<u8> {
let mut o = Vec::new();
loop {
let b = (n & 0x7f) as u8;
n >>= 7;
if n == 0 {
o.push(b);
return o;
}
o.push(b | 0x80);
}
}
fn name(s: &str) -> Vec<u8> {
let mut o = leb(s.len() as u32);
o.extend_from_slice(s.as_bytes());
o
}
fn section(id: u8, body: Vec<u8>) -> Vec<u8> {
let mut o = vec![id];
o.extend(leb(body.len() as u32));
o.extend(body);
o
}
fn vec_of(items: Vec<Vec<u8>>) -> Vec<u8> {
let mut o = leb(items.len() as u32);
for i in items {
o.extend(i);
}
o
}
const I32: u8 = 0x7f;
const I64: u8 = 0x7e;
fn functype(p: &[u8], r: &[u8]) -> Vec<u8> {
let mut o = vec![0x60];
o.extend(leb(p.len() as u32));
o.extend_from_slice(p);
o.extend(leb(r.len() as u32));
o.extend_from_slice(r);
o
}
#[derive(Clone)]
pub struct W {
pub extra_import: Option<(&'static str, &'static str)>,
pub memory_import: bool,
pub start: bool,
/// (min, max, shared)
pub memory: Option<(u32, Option<u32>, bool)>,
pub second_memory: bool,
pub tables: usize,
pub drop_export: Option<&'static str>,
pub handle_returns_i32: bool,
pub call_sig_wrong: bool,
pub simd: bool,
pub pad: usize,
pub duplicate_log: bool,
}
impl Default for W {
fn default() -> Self {
W {
extra_import: None,
memory_import: false,
start: false,
memory: Some((1, Some(4), false)),
second_memory: false,
tables: 0,
drop_export: None,
handle_returns_i32: false,
call_sig_wrong: false,
simd: false,
pad: 0,
duplicate_log: false,
}
}
}
impl W {
pub fn build(&self) -> Vec<u8> {
let mut m = b"\0asm\x01\0\0\0".to_vec();
let t_call: Vec<u8> = if self.call_sig_wrong {
functype(&[I32, I32], &[I32])
} else {
functype(&[I32, I32, I32, I32], &[I32])
};
let mut types = vec![
t_call, // 0
functype(&[I32, I32, I32], &[]), // 1 log
functype(&[I32], &[I32]), // 2 alloc
functype(&[I32, I32], &[]), // 3 free
functype(&[I32, I32], &[I32]), // 4 init
functype(&[I32, I32, I32], &[I64]), // 5 handle
functype(&[I32, I32, I32], &[I32]), // 6 handle (wrong)
functype(&[], &[]), // 7 start
];
if self.simd {
types.push(functype(&[], &[0x7b])); // v128 result
}
m.extend(section(1, vec_of(types)));
let mut imports = vec![
[name("fp1"), name("call"), vec![0x00, 0]].concat(),
[name("fp1"), name("log"), vec![0x00, 1]].concat(),
];
if self.duplicate_log {
imports.push([name("fp1"), name("log"), vec![0x00, 1]].concat());
}
if let Some((a, b)) = self.extra_import {
imports.push([name(a), name(b), vec![0x00, 1]].concat());
}
if self.memory_import {
imports.push([name("env"), name("memory"), vec![0x02, 0x01, 1, 4]].concat());
}
let n_imp_funcs = imports.len() as u32 - u32::from(self.memory_import);
m.extend(section(2, vec_of(imports)));
let mut funcs = vec![
vec![2u8],
vec![3],
vec![4],
vec![if self.handle_returns_i32 { 6 } else { 5 }],
];
if self.start {
funcs.push(vec![7]);
}
if self.simd {
funcs.push(vec![8]);
}
let n_funcs = funcs.len();
m.extend(section(3, vec_of(funcs)));
if self.tables > 0 {
let t = (0..self.tables).map(|_| vec![0x70, 0x00, 1]).collect();
m.extend(section(4, vec_of(t)));
}
let mut mems = Vec::new();
if let Some((min, max, shared)) = self.memory {
let mut e = Vec::new();
let flag = u8::from(max.is_some()) | if shared { 2 } else { 0 };
e.push(flag);
e.extend(leb(min));
if let Some(x) = max {
e.extend(leb(x));
}
mems.push(e.clone());
if self.second_memory {
mems.push(e);
}
}
if !mems.is_empty() {
m.extend(section(5, vec_of(mems)));
}
let f0 = n_imp_funcs; // first defined function index
let mut exports = Vec::new();
let mut add = |n: &'static str, kind: u8, idx: u32| {
if self.drop_export != Some(n) {
exports.push([name(n), vec![kind], leb(idx)].concat());
}
};
add("memory", 2, 0);
add("fp_alloc", 0, f0);
add("fp_free", 0, f0 + 1);
add("fp_init", 0, f0 + 2);
add("fp_handle", 0, f0 + 3);
m.extend(section(7, vec_of(exports)));
if self.start {
m.extend(section(8, leb(f0 + 4)));
}
let mut bodies = vec![
vec![0x04, 0x00, 0x41, 0x00, 0x0b],
vec![0x02, 0x00, 0x0b],
vec![0x04, 0x00, 0x41, 0x00, 0x0b],
if self.handle_returns_i32 {
vec![0x04, 0x00, 0x41, 0x00, 0x0b]
} else {
vec![0x04, 0x00, 0x42, 0x00, 0x0b]
},
];
if self.start {
bodies.push(vec![0x02, 0x00, 0x0b]);
}
if self.simd {
// v128.const 0 (16 zero bytes)
let mut b = vec![0x00, 0xfd, 0x0c];
b.extend([0u8; 16]);
b.push(0x0b);
let mut body = leb(b.len() as u32);
body.extend(b);
bodies.push(body);
}
assert_eq!(bodies.len(), n_funcs);
m.extend(section(10, vec_of(bodies)));
if self.pad > 0 {
let mut body = name("pad");
body.extend(vec![0u8; self.pad]);
m.extend(section(0, body));
}
m
}
}
// ---- ELF ----
/// A GNU hash table for `E::gnu_hash`: `symoffset`, the bucket heads and one
/// chain word per symbol from `symoffset` (bit 0 set on the last word of each
/// chain). The bloom filter is one zero word.
#[derive(Clone)]
pub struct GnuHash {
pub symoffset: u32,
pub bucket: Vec<u32>,
pub chain: Vec<u32>,
}
pub struct E {
pub class: u8,
pub data: u8,
pub etype: u16,
pub machine: u16,
pub flags: u32,
pub needed: Vec<&'static str>,
pub rpath: bool,
pub runpath: bool,
pub textrel: bool,
/// DF_TEXTREL set in DT_FLAGS (the spelling modern linkers emit).
pub textrel_flag: bool,
/// A second DT_FLAGS entry after the first.
pub dup_dt_flags: bool,
pub bind_now: bool,
pub flags1_now: bool,
pub exec_stack: bool,
pub gnu_stack: bool,
pub defined: Vec<&'static str>,
pub undefined: Vec<&'static str>,
/// Extra defined symbols with an explicit binding nibble (10 is
/// GNU_UNIQUE, 11 to 15 the OS and processor ranges). Emitted after
/// `defined`.
pub defined_bind: Vec<(&'static str, u8)>,
/// Extra undefined symbols with an explicit binding nibble. Emitted
/// after `undefined`.
pub undefined_bind: Vec<(&'static str, u8)>,
pub no_sections: bool,
/// Contents of a `.wmod_info` section, when present.
pub info: Option<Vec<u8>>,
/// A second `.wmod_info` section with these contents, after the first.
pub info_twin: Option<Vec<u8>>,
/// A second PT_LOAD program header that maps addresses 0 to 3 again.
pub extra_load: bool,
/// A DT_REL table with one R_ARM_ABS32 relocation per symbol index here.
pub rel_syms: Vec<u32>,
/// A DT_HASH table: (nchain, bucket[0]), with a chain of zeros.
pub sysv_hash: Option<(u32, u32)>,
/// A DT_GNU_HASH table.
pub gnu_hash: Option<GnuHash>,
}
impl Default for E {
fn default() -> Self {
E {
class: 1,
data: 1,
etype: 3,
machine: 40,
flags: 0x0500_0400,
needed: vec!["libc.so.0"],
rpath: false,
runpath: false,
textrel: false,
textrel_flag: false,
dup_dt_flags: false,
bind_now: true,
flags1_now: false,
exec_stack: false,
gnu_stack: true,
defined: vec!["wmod_entry"],
undefined: vec!["memcpy", "snprintf"],
defined_bind: vec![],
undefined_bind: vec![],
no_sections: false,
info: None,
info_twin: None,
extra_load: false,
rel_syms: vec![],
sysv_hash: None,
gnu_hash: None,
}
}
}
fn p32(o: &mut Vec<u8>, v: u32) {
o.extend_from_slice(&v.to_le_bytes());
}
fn p16(o: &mut Vec<u8>, v: u16) {
o.extend_from_slice(&v.to_le_bytes());
}
impl E {
pub fn build(&self) -> Vec<u8> {
// string table: "\0" then names
let mut strs = vec![0u8];
let mut add = |s: &str| {
let o = strs.len() as u32;
strs.extend_from_slice(s.as_bytes());
strs.push(0);
o
};
let needed: Vec<u32> = self.needed.iter().map(|n| add(n)).collect();
let defs: Vec<u32> = self.defined.iter().map(|n| add(n)).collect();
let undefs: Vec<u32> = self.undefined.iter().map(|n| add(n)).collect();
let dbind: Vec<(u32, u8)> = self
.defined_bind
.iter()
.map(|(n, b)| (add(n), *b))
.collect();
let ubind: Vec<(u32, u8)> = self
.undefined_bind
.iter()
.map(|(n, b)| (add(n), *b))
.collect();
let nph = (if self.gnu_stack { 3 } else { 2 }) + usize::from(self.extra_load);
let dyn_off = 52 + 32 * nph;
let flags_word =
(if self.bind_now { 8 } else { 0 }) | (if self.textrel_flag { 4 } else { 0 });
let flag_entries =
usize::from(flags_word != 0 || self.dup_dt_flags) + usize::from(self.dup_dt_flags);
let rel_entries = if self.rel_syms.is_empty() { 0 } else { 3 };
let hash_entries =
usize::from(self.sysv_hash.is_some()) + usize::from(self.gnu_hash.is_some());
let ndyn = needed.len()
+ usize::from(self.rpath)
+ usize::from(self.runpath)
+ usize::from(self.textrel)
+ flag_entries
+ usize::from(self.flags1_now)
+ 4
+ rel_entries
+ hash_entries
+ 1;
let str_off = dyn_off + ndyn * 8;
let sym_off = (str_off + strs.len() + 3) & !3;
let nsym = 1 + defs.len() + undefs.len() + dbind.len() + ubind.len();
let sym_end = sym_off + nsym * 16;
// Optional tables after the symbols: REL entries, DT_HASH, DT_GNU_HASH.
let rel_off = (sym_end + 3) & !3;
let rel_len = 8 * self.rel_syms.len();
let hash_off = (rel_off + rel_len + 3) & !3;
let hash_len = self
.sysv_hash
.map_or(0, |(nchain, _)| 12 + 4 * nchain as usize);
let gnu_off = (hash_off + hash_len + 3) & !3;
let gnu_len = self
.gnu_hash
.as_ref()
.map_or(0, |g| 20 + 4 * g.bucket.len() + 4 * g.chain.len());
let tables_end = gnu_off + gnu_len;
let mut dynents: Vec<(u32, u32)> = needed.iter().map(|&o| (1, o)).collect();
dynents.push((5, str_off as u32));
dynents.push((10, strs.len() as u32));
dynents.push((6, sym_off as u32));
dynents.push((11, 16));
if !self.rel_syms.is_empty() {
dynents.push((17, rel_off as u32));
dynents.push((18, rel_len as u32));
dynents.push((19, 8));
}
if self.sysv_hash.is_some() {
dynents.push((4, hash_off as u32));
}
if self.gnu_hash.is_some() {
dynents.push((0x6fff_fef5, gnu_off as u32));
}
if self.rpath {
dynents.push((15, 1));
}
if self.runpath {
dynents.push((29, 1));
}
if self.textrel {
dynents.push((22, 0));
}
if flags_word != 0 || self.dup_dt_flags {
dynents.push((30, flags_word));
}
if self.dup_dt_flags {
dynents.push((30, flags_word));
}
if self.flags1_now {
dynents.push((0x6fff_fffb, 1));
}
dynents.push((0, 0));
assert_eq!(dynents.len(), ndyn);
// Names of the optional sections: ".shstrtab" at 9, ".wmod_info" at 19.
const SHSTR: &[u8] = b"\0.dynsym\0.shstrtab\0.wmod_info\0";
let (shstr_off, info_off, info2_off, sh_off, shnum): (usize, usize, usize, usize, usize) =
match &self.info {
Some(info) => {
let shstr_off = (tables_end + 3) & !3;
let info_off = (shstr_off + SHSTR.len() + 3) & !3;
let mut end = info_off + info.len();
let info2_off = match &self.info_twin {
Some(twin) => {
let at = (end + 3) & !3;
end = at + twin.len();
at
}
None => 0,
};
let sh_off = (end + 3) & !3;
let shnum = if self.info_twin.is_some() { 5 } else { 4 };
(shstr_off, info_off, info2_off, sh_off, shnum)
}
None => {
let sh_off = (tables_end + 3) & !3;
(0, 0, 0, sh_off, 2)
}
};
let total = sh_off + 40 * shnum;
let mut o = Vec::new();
o.extend_from_slice(b"\x7fELF");
o.extend_from_slice(&[self.class, self.data, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
p16(&mut o, self.etype);
p16(&mut o, self.machine);
p32(&mut o, 1);
p32(&mut o, 0);
p32(&mut o, 52);
p32(&mut o, if self.no_sections { 0 } else { sh_off as u32 });
p32(&mut o, self.flags);
p16(&mut o, 52);
p16(&mut o, 32);
p16(&mut o, nph as u16);
p16(&mut o, 40);
p16(&mut o, if self.no_sections { 0 } else { shnum as u16 });
p16(&mut o, if self.info.is_some() { 2 } else { 0 });
let ph = |o: &mut Vec<u8>, ty: u32, off: u32, sz: u32, flags: u32| {
p32(o, ty);
p32(o, off);
p32(o, off); // vaddr == offset
p32(o, off);
p32(o, sz);
p32(o, sz);
p32(o, flags);
p32(o, 4);
};
ph(&mut o, 1, 0, total as u32, 5);
ph(&mut o, 2, dyn_off as u32, (ndyn * 8) as u32, 6);
if self.gnu_stack {
let f = if self.exec_stack { 7 } else { 6 };
ph(&mut o, 0x6474_e551, 0, 0, f);
}
if self.extra_load {
ph(&mut o, 1, 0, 4, 4);
}
assert_eq!(o.len(), dyn_off);
for (t, v) in &dynents {
p32(&mut o, *t);
p32(&mut o, *v);
}
o.extend_from_slice(&strs);
o.resize(sym_off, 0);
o.extend_from_slice(&[0u8; 16]);
for &n in &defs {
p32(&mut o, n);
p32(&mut o, 0x1000);
p32(&mut o, 4);
o.push(0x12); // GLOBAL FUNC
o.push(0);
p16(&mut o, 1);
}
for &(n, bind) in &dbind {
p32(&mut o, n);
p32(&mut o, 0x1000);
p32(&mut o, 4);
o.push((bind << 4) | 2); // explicit binding, FUNC type
o.push(0);
p16(&mut o, 1);
}
for &n in &undefs {
p32(&mut o, n);
p32(&mut o, 0);
p32(&mut o, 0);
o.push(0x12);
o.push(0);
p16(&mut o, 0);
}
for &(n, bind) in &ubind {
p32(&mut o, n);
p32(&mut o, 0);
p32(&mut o, 0);
o.push((bind << 4) | 2); // explicit binding, FUNC type
o.push(0);
p16(&mut o, 0);
}
o.resize(rel_off, 0);
for &sym in &self.rel_syms {
p32(&mut o, 0x1000); // r_offset
p32(&mut o, (sym << 8) | 2); // R_ARM_ABS32 against `sym`
}
o.resize(hash_off, 0);
if let Some((nchain, bucket0)) = self.sysv_hash {
p32(&mut o, 1); // nbucket
p32(&mut o, nchain);
p32(&mut o, bucket0);
for _ in 0..nchain {
p32(&mut o, 0);
}
}
o.resize(gnu_off, 0);
if let Some(g) = &self.gnu_hash {
p32(&mut o, g.bucket.len() as u32);
p32(&mut o, g.symoffset);
p32(&mut o, 1); // bloom size
p32(&mut o, 6); // bloom shift
p32(&mut o, 0); // bloom word
for &v in &g.bucket {
p32(&mut o, v);
}
for &v in &g.chain {
p32(&mut o, v);
}
}
if let Some(info) = &self.info {
o.resize(shstr_off, 0);
o.extend_from_slice(SHSTR);
o.resize(info_off, 0);
o.extend_from_slice(info);
if let Some(twin) = &self.info_twin {
o.resize(info2_off, 0);
o.extend_from_slice(twin);
}
}
o.resize(sh_off, 0);
o.extend_from_slice(&[0u8; 40]);
// section 1: SHT_DYNSYM
p32(&mut o, 0);
p32(&mut o, 11);
p32(&mut o, 2);
p32(&mut o, sym_off as u32);
p32(&mut o, sym_off as u32);
p32(&mut o, (nsym * 16) as u32);
p32(&mut o, 0);
p32(&mut o, 1);
p32(&mut o, 4);
p32(&mut o, 16);
if let Some(info) = &self.info {
// section 2: .shstrtab
p32(&mut o, 9);
p32(&mut o, 3); // SHT_STRTAB
p32(&mut o, 0);
p32(&mut o, 0);
p32(&mut o, shstr_off as u32);
p32(&mut o, SHSTR.len() as u32);
p32(&mut o, 0);
p32(&mut o, 0);
p32(&mut o, 1);
p32(&mut o, 0);
// section 3: .wmod_info, allocated and loaded at sh_addr
p32(&mut o, 19);
p32(&mut o, 1); // SHT_PROGBITS
p32(&mut o, 2); // SHF_ALLOC
p32(&mut o, info_off as u32); // sh_addr
p32(&mut o, info_off as u32);
p32(&mut o, info.len() as u32);
p32(&mut o, 0);
p32(&mut o, 0);
p32(&mut o, 4);
p32(&mut o, 0);
if let Some(twin) = &self.info_twin {
// section 4: a second .wmod_info
p32(&mut o, 19);
p32(&mut o, 1);
p32(&mut o, 2);
p32(&mut o, info2_off as u32);
p32(&mut o, info2_off as u32);
p32(&mut o, twin.len() as u32);
p32(&mut o, 0);
p32(&mut o, 0);
p32(&mut o, 4);
p32(&mut o, 0);
}
}
assert_eq!(o.len(), total);
o
}
}
/// A `wmod_info_t` prefix (d04 13.3.3), 32-bit little endian, as the module SDK
/// links it into the `.wmod_info` section.
pub fn info_bytes(
id: &str,
build: u32,
flags: u32,
lvgl: &str,
hash: u8,
major: u16,
minor: u16,
) -> Vec<u8> {
let mut b = vec![0u8; INFO_SIZE_MIN];
b[0..4].copy_from_slice(&(INFO_SIZE_MIN as u32).to_le_bytes());
b[4..6].copy_from_slice(&major.to_le_bytes());
b[6..8].copy_from_slice(&minor.to_le_bytes());
b[8..8 + id.len()].copy_from_slice(id.as_bytes());
b[40..44].copy_from_slice(&build.to_le_bytes());
b[44..48].copy_from_slice(&flags.to_le_bytes());
b[48..48 + lvgl.len()].copy_from_slice(lvgl.as_bytes());
b[64..96].fill(hash);
b
}
// ---- signed packages (package-level tests) ----
pub const SEED: [u8; 32] = [7; 32];
pub const OTHER_SEED: [u8; 32] = [9; 32];
/// Test keys live only in test code (wapp-core contract K10).
pub fn key(seed: &[u8; 32], class: KeyClass, ids: AllowedIds) -> AppKey {
AppKey {
public: public_of(seed),
class,
allowed: ids,
}
}
pub fn platform() -> Platform {
Platform::parse(
br#"{"v":1,"platform_api":3,"bus_contract":[1],"display_api":1,"checks_api":1,
"capabilities":["rs485-bus","relay-io"],"reserved_ports":[22,53,67,80,443],
"app_ram_cap_mb":96,"uid_base":10000,"uid_max":10999}"#,
br#"{"v":1,"features":["cgroup-memory","cgroup-pids","cgroup-cpu"]}"#,
)
.unwrap()
}
/// The verifier context of one test: the key set, the platform and no
/// revocations.
pub struct Fx {
pub keys: Vec<AppKey>,
pub platform: Platform,
pub revoked: Revocations,
}
impl Fx {
/// A release-like key set: one `platform` key that signs any id.
pub fn new() -> Fx {
Fx {
keys: vec![key(&SEED, KeyClass::Platform, AllowedIds::Any)],
platform: platform(),
revoked: Revocations::default(),
}
}
pub fn ctx(&self) -> Ctx<'_> {
Ctx {
keys: &self.keys,
platform: &self.platform,
revoked: &self.revoked,
floor_build: None,
pin: None,
explicit_rollback: false,
}
}
}
impl Default for Fx {
fn default() -> Self {
Fx::new()
}
}
pub fn j(s: &str) -> Value {
json::parse(s.as_bytes()).unwrap()
}
const SOURCE: &str = r#""source":{"repo":"blueflare/flare-edge","commit":"0123456789abcdef0123456789abcdef01234567","build_date":"2026-11-07","builder":"ci","sbom_sha256":"0000000000000000000000000000000000000000000000000000000000000000"}"#;
/// A FLARE plugin package: one descriptor part whose `flare/plugin.wasm`
/// is the module under test.
pub fn plugin_template() -> Value {
j(&format!(
r#"{{"format":1,"id":"ai-test","name":"Test plugin","summary":"Plugin admission test",
"publisher":"BlueFlare Energy","version":"1.0.0","build":1,"kind":"descriptor","parts":["flare"],
"platform":{{"arch":"armv7-musl-static","min_api":1,"bus_contract":[1],"display_api":1,"checks_api":1}},
{SOURCE},
"requires":{{}},"permissions":[],
"flare":{{"plugin":{{"module":"flare/plugin.wasm","abi":1,"ops":["kv@1"],
"limits":{{"memory_mb":32,"fuel":50000000,"call_ms":250,"kv_mb":16}}}}}},
"data":{{"disk":{{"data_quota_mb":8,"cache_quota_mb":0}}}}}}"#
))
}
pub fn plugin_files(module: Vec<u8>) -> BTreeMap<String, Vec<u8>> {
let mut f = BTreeMap::new();
f.insert("flare/plugin.wasm".into(), module);
f
}
/// A panel module package: one content part with a `ui.native` block whose
/// module is `ui/modules/mining.so`.
pub fn module_template() -> Value {
j(&format!(
r#"{{"format":1,"id":"solar","name":"Solar","summary":"Solar inverter overview",
"publisher":"BlueFlare Energy","version":"1.0.0","build":1,"kind":"content",
"parts":["warden"],"default_enabled":true,
"platform":{{"arch":"armv7-musl-static","min_api":1,"bus_contract":[1],"display_api":1,"checks_api":1}},
{SOURCE},
"requires":{{"any":[["rs485-bus","relay-io"]]}},
"permissions":[{{"name":"storage.data","class":"normal","reason":"Keeps its settings"}},
{{"name":"ui.native","class":"privileged","reason":"Draws the radar"}}],
"ui":{{"native":{{"module":"ui/modules/mining.so","host":"inproc","wmod_api":[1,0],"lvgl_direct":false,"memory_max_mb":4}}}},
"schema":{{"fragment":"schema/fragment.json","data_version":1}},
"data":{{"disk":{{"data_quota_mb":8,"cache_quota_mb":0}}}}}}"#
))
}
pub fn module_files(module: Vec<u8>) -> BTreeMap<String, Vec<u8>> {
let mut f = BTreeMap::new();
f.insert("schema/fragment.json".into(), b"{\"v\":1}".to_vec());
f.insert("ui/modules/mining.so".into(), module);
f
}
/// Set a dotted path inside a template; numeric segments index arrays.
pub fn set(t: &mut Value, path: &str, v: Value) {
let parts: Vec<&str> = path.split('.').collect();
let mut cur = t;
for p in &parts[..parts.len() - 1] {
cur = step(cur, p);
}
let last = parts[parts.len() - 1];
match cur {
Value::Obj(m) => {
m.insert(last.to_string(), v);
}
Value::Arr(a) => a[last.parse::<usize>().unwrap()] = v,
_ => panic!("cannot set into a scalar"),
}
}
fn step<'a>(cur: &'a mut Value, p: &str) -> &'a mut Value {
match cur {
Value::Obj(m) => m.get_mut(p).unwrap_or_else(|| panic!("missing {p}")),
Value::Arr(a) => &mut a[p.parse::<usize>().expect("array index")],
_ => panic!("cannot step into {p}"),
}
}
/// Sign `t` and its files with `seed`.
pub fn pack_signed(t: &Value, files: &BTreeMap<String, Vec<u8>>, seed: &[u8; 32]) -> Vec<u8> {
pack(t, files, false, seed).unwrap()
}
/// A service package with two `bin/` executables, the shape of wapp-core's
/// fixtures. `bin/warden-asic` is the first service's executable.
pub fn service_template() -> Value {
j(&format!(
r#"{{"format":1,"id":"mining","name":"Mining Devices","summary":"Miner scan and Stratum proxy",
"publisher":"BlueFlare Energy","version":"1.4.0","build":140,"kind":"service",
"parts":["warden","flare"],
"platform":{{"arch":"armv7-musl-static","min_api":3,"bus_contract":[1],
"features":["cgroup-memory","cgroup-pids","cgroup-cpu"],"display_api":1,"checks_api":1}},
{SOURCE},
"requires":{{"capabilities":["network-scan","flare-link"]}},"provides":["mining-scan"],
"permissions":[
{{"name":"net.scan","class":"sensitive","reason":"Find miners on the LAN","services":["asic"]}},
{{"name":"net.listen","class":"sensitive","reason":"Miners connect to the proxy","services":["stratum"]}},
{{"name":"net.connect","class":"sensitive","reason":"Pool connections","services":["stratum"]}},
{{"name":"flare.up","class":"sensitive","reason":"Send summaries to FLARE"}},
{{"name":"secret.read:apps.mining.stratum.pass","class":"sensitive","reason":"Pool password","services":["stratum"]}}],
"bus":{{"docs":[{{"name":"devices","refresh_s":30,"public":false}},{{"name":"summary","refresh_s":30,"public":true}}],
"verbs":[{{"verb":"scan","service":"asic","idem":false,"timeout_s":10}}],"events":[],"up":[{{"name":"sessions"}}]}},
"schema":{{"fragment":"schema/fragment.json","data_version":3}},
"services":[
{{"name":"asic","exe":"bin/warden-asic","phase":"normal","restart":{{"policy":"always"}},
"resources":{{"memory_max_mb":48,"memory_typical_mb":20,"pids_max":64,"cpu_weight":100}}}},
{{"name":"stratum","exe":"bin/warden-stratum","phase":"normal","after":["asic"],"restart":{{"policy":"always"}},
"resources":{{"memory_max_mb":64,"memory_typical_mb":24,"pids_max":256,"cpu_weight":100}}}}],
"net":{{"listen":[{{"service":"stratum","proto":"tcp","port_setting":"apps.mining.proxy.port","zones":["lan"],"purpose":"Stratum proxy for miners"}}],
"connect":[{{"service":"stratum","proto":"tcp","range":[1,65535],"scope":"wan","host_hint":"pool","purpose":"Pool connection"}},
{{"service":"asic","proto":"tcp","ports":[80,443,4028,6060],"scope":"lan","purpose":"Miner scan"}}]}},
"data":{{"disk":{{"data_quota_mb":16,"cache_quota_mb":8}},"secrets":["apps.mining.stratum.pass"],
"flare":[{{"class":"pools","default":"purge"}}]}}}}"#
))
}
/// The files of `service_template`: the schema fragment and both executables.
pub fn service_files() -> BTreeMap<String, Vec<u8>> {
let mut f = BTreeMap::new();
f.insert("schema/fragment.json".into(), b"{\"v\":1}".to_vec());
let asic = wapp_core::elf::sample_arm_static();
f.insert("bin/warden-asic".into(), asic);
let mut stratum = wapp_core::elf::sample_arm_static();
stratum.extend_from_slice(b"stratum");
f.insert("bin/warden-stratum".into(), stratum);
f
}
@@ -0,0 +1,548 @@
//! d04 13.3.10 "ELF verifier vectors" for panel modules (AT-M6-13, PL-2).
//!
//! The reference module is admitted, and each hostile module is refused with
//! its reason code. Every vector is a named test, so the acceptance row can
//! cite it. The modules come from `common::E`, which writes the ELF facts that
//! 13.3.5 checks; no toolchain links them, because the module SDK (13.3.3) is
//! not built yet.
mod common;
use common::{info_bytes, GnuHash, E};
use flare_plugin_abi::wmod::*;
use flare_plugin_abi::Code;
const ALLOW: &str = "# libc\nstr*\nmem*\nsnprintf\nstrto*\nqsort\n__aeabi_*\nsin\n";
const EXPORTS: &str = "lv_*\nwarden_page_*\n";
/// The reference module: ET_DYN, EM_ARM, EABI5 hard-float, libc only, BIND_NOW,
/// a non-executable stack, one export, two imports from the allow list and the
/// info block of app `solar`, build 1, ABI 1.0.
fn reference() -> E {
E {
info: Some(info_bytes("solar", 1, 0, "9.6.0", 9, 1, 0)),
..E::default()
}
}
/// Every admission check of 13.3.5 on `bytes`, in the order flared runs them,
/// returning the first refusal code. `Ok` carries the compat outcome.
fn admit(bytes: &[u8]) -> Result<Compat, Code> {
let allow = NameList::parse(ALLOW);
let host = NameList::parse(EXPORTS);
let policy = Policy {
libc_allow: &allow,
host_exports: &host,
cxx: false,
};
check_module(bytes, &policy).map_err(|e| e.code)?;
let info = Info::parse(info_block(bytes).map_err(|e| e.code)?).map_err(|e| e.code)?;
let expect = Expect {
abi_major: 1,
abi_minor: 0,
app_id: "solar",
app_build: 1,
lvgl_version: "9.6.0",
sdk_hash: [9; 32],
};
check_info(&info, &expect).map_err(|e| e.code)
}
fn refused(e: E, want: Code) {
assert_eq!(admit(&e.build()), Err(want));
}
#[test]
fn d04_pl2_reference_module_is_admitted() {
assert_eq!(admit(&reference().build()), Ok(Compat::Ok));
}
#[test]
fn d04_pl2_refuses_musl_linked_module() {
// musl names its C library `libc.so` in DT_NEEDED.
refused(
E {
needed: vec!["libc.so"],
..reference()
},
Code::Elf,
);
}
#[test]
fn d04_pl2_refuses_glibc_linked_module() {
refused(
E {
needed: vec!["libc.so.6"],
..reference()
},
Code::Elf,
);
}
#[test]
fn d04_pl2_refuses_rpath_and_runpath() {
refused(
E {
rpath: true,
..reference()
},
Code::Elf,
);
refused(
E {
runpath: true,
..reference()
},
Code::Elf,
);
}
#[test]
fn d04_pl2_refuses_textrel() {
refused(
E {
textrel: true,
..reference()
},
Code::Elf,
);
}
/// DF_TEXTREL in DT_FLAGS is how current linkers record text relocations; the
/// DT_TEXTREL tag alone would let such a module through.
#[test]
fn d04_pl2_refuses_textrel_flag_in_dt_flags() {
refused(
E {
textrel_flag: true,
..reference()
},
Code::Elf,
);
}
#[test]
fn d04_pl2_refuses_a_second_dt_flags_entry() {
refused(
E {
dup_dt_flags: true,
..reference()
},
Code::Elf,
);
}
/// Hostile e_phoff and e_shoff near 2^32 must be refused, never wrapped into
/// a valid-looking offset (the panel builds this crate for 32-bit usize).
#[test]
fn d04_pl2_hostile_header_offsets_are_refused() {
let mut phoff = reference().build();
phoff[28..32].copy_from_slice(&0xFFFF_FFF0u32.to_le_bytes());
assert_eq!(admit(&phoff), Err(Code::Elf));
let mut shoff = reference().build();
shoff[32..36].copy_from_slice(&0xFFFF_FFF0u32.to_le_bytes());
assert_eq!(admit(&shoff), Err(Code::Elf));
}
#[test]
fn d04_pl2_refuses_extra_export() {
refused(
E {
defined: vec!["wmod_entry", "extra_export"],
..reference()
},
Code::Symbols,
);
}
#[test]
fn d04_pl2_refuses_import_outside_the_allow_list() {
refused(
E {
undefined: vec!["memcpy", "unlisted_call"],
..reference()
},
Code::Symbols,
);
// A forbidden import is refused even when a list would admit it.
refused(
E {
undefined: vec!["memcpy", "malloc"],
..reference()
},
Code::Symbols,
);
}
#[test]
fn d04_pl2_refuses_wrong_architecture() {
refused(
E {
machine: 3, // EM_386
..reference()
},
Code::Elf,
);
}
#[test]
fn d04_pl2_refuses_soft_float() {
refused(
E {
flags: 0x0500_0000,
..reference()
},
Code::Elf,
);
}
#[test]
fn d04_pl2_refuses_executable_stack() {
refused(
E {
exec_stack: true,
..reference()
},
Code::Elf,
);
}
#[test]
fn d04_pl2_refuses_abi_major_mismatch() {
refused(
E {
info: Some(info_bytes("solar", 1, 0, "9.6.0", 9, 2, 0)),
..reference()
},
Code::Platform,
);
}
#[test]
fn d04_pl2_newer_minor_needs_platform_not_refusal() {
let e = E {
info: Some(info_bytes("solar", 1, 0, "9.6.0", 9, 1, 1)),
..reference()
};
assert!(matches!(admit(&e.build()), Ok(Compat::NeedsPlatform(_))));
}
#[test]
fn d04_pl2_info_block_is_found_by_section_name() {
let bytes = reference().build();
assert_eq!(
info_block(&bytes).unwrap(),
info_bytes("solar", 1, 0, "9.6.0", 9, 1, 0).as_slice()
);
}
#[test]
fn d04_pl2_missing_or_short_info_block_is_refused() {
assert_eq!(
info_block(&E::default().build()).unwrap_err().code,
Code::Elf
);
let short = E {
info: Some(vec![0u8; 40]),
..E::default()
};
assert_eq!(info_block(&short.build()).unwrap_err().code, Code::Elf);
}
#[test]
fn d04_pl2_info_section_outside_the_file_is_refused() {
let mut b = reference().build();
// Section 3 is `.wmod_info`: its header sits at e_shoff + 3 * 40 and its
// sh_size field at +20.
let shoff = u32::from_le_bytes([b[32], b[33], b[34], b[35]]) as usize;
let at = shoff + 3 * 40 + 20;
b[at..at + 4].copy_from_slice(&0xFFFF_0000u32.to_le_bytes());
assert_eq!(info_block(&b).unwrap_err().code, Code::Elf);
}
// ---- the loader's view (#187, and the holes of the same class) ----
//
// Each decoy copies a table to a second place in the file and points a header
// at it. The loader reads the table at its load address, so the verifier must
// refuse the header rather than check the copy.
/// The word at byte offset `at` of a built module.
fn word(b: &[u8], at: usize) -> u32 {
u32::from_le_bytes([b[at], b[at + 1], b[at + 2], b[at + 3]])
}
fn put_word(b: &mut [u8], at: usize, v: u32) {
b[at..at + 4].copy_from_slice(&v.to_le_bytes());
}
/// Section header `i` of a built module: (sh_type, sh_addr, sh_offset, sh_size).
fn shdr(b: &[u8], i: usize) -> (u32, u32, u32, u32) {
let at = word(b, 32) as usize + i * 40;
(
word(b, at + 4),
word(b, at + 12),
word(b, at + 16),
word(b, at + 20),
)
}
/// Set one field of section header `i`: 8 sh_flags, 12 sh_addr, 16 sh_offset,
/// 20 sh_size.
fn set_shdr(b: &mut [u8], i: usize, field: usize, v: u32) {
let at = word(b, 32) as usize + i * 40 + field;
put_word(b, at, v);
}
/// (p_offset, p_filesz) of program header `i`.
fn phdr_range(b: &[u8], i: usize) -> (usize, usize) {
let at = word(b, 28) as usize + i * 32;
(word(b, at + 4) as usize, word(b, at + 16) as usize)
}
/// Set one field of program header `i`: 4 p_offset, 8 p_vaddr, 16 p_filesz,
/// 20 p_memsz.
fn set_phdr(b: &mut [u8], i: usize, field: usize, v: u32) {
let at = word(b, 28) as usize + i * 32 + field;
put_word(b, at, v);
}
/// Append `bytes` at a 4-byte boundary and return their file offset.
fn append(b: &mut Vec<u8>, bytes: &[u8]) -> u32 {
while b.len() % 4 != 0 {
b.push(0);
}
let at = b.len();
b.extend_from_slice(bytes);
at as u32
}
/// The 16-byte entries of the built module's `.dynsym` at the indices `keep`.
fn dynsym_entries(b: &[u8], keep: &[usize]) -> Vec<u8> {
let (_, _, off, size) = shdr(b, 1);
let table = &b[off as usize..(off + size) as usize];
keep.iter()
.flat_map(|&i| table[i * 16..i * 16 + 16].to_vec())
.collect()
}
/// The loaded `.dynsym` (at DT_SYMTAB) exports an extra symbol. The section
/// header names a benign copy of the table, which the old reader checked.
#[test]
fn d04_pl2_dynsym_header_at_a_benign_copy_is_refused() {
let mut b = E {
defined: vec!["wmod_entry", "extra_export"],
..reference()
}
.build();
// Entries 0, 1, 3 and 4: null, wmod_entry, memcpy and snprintf.
let benign = dynsym_entries(&b, &[0, 1, 3, 4]);
let at = append(&mut b, &benign);
set_shdr(&mut b, 1, 16, at);
set_shdr(&mut b, 1, 20, benign.len() as u32);
assert_eq!(admit(&b), Err(Code::Elf));
}
/// The loaded table imports `unlisted_call`. The header names a benign copy
/// without it, so the import check would pass on the copy.
#[test]
fn d04_pl2_dynsym_header_at_a_benign_copy_hides_an_import_is_refused() {
let mut b = E {
undefined: vec!["memcpy", "snprintf", "unlisted_call"],
..reference()
}
.build();
// Entries 0 to 3: null, wmod_entry, memcpy and snprintf.
let benign = dynsym_entries(&b, &[0, 1, 2, 3]);
let at = append(&mut b, &benign);
set_shdr(&mut b, 1, 16, at);
set_shdr(&mut b, 1, 20, benign.len() as u32);
assert_eq!(admit(&b), Err(Code::Elf));
}
/// The info block at the section's load address names app `other`. The header
/// names a benign copy that names `solar`.
#[test]
fn d04_pl2_info_header_at_a_benign_copy_is_refused() {
let mut b = E {
info: Some(info_bytes("other", 1, 0, "9.6.0", 9, 1, 0)),
..reference()
}
.build();
let benign = info_bytes("solar", 1, 0, "9.6.0", 9, 1, 0);
let at = append(&mut b, &benign);
set_shdr(&mut b, 3, 16, at); // .wmod_info sh_offset
assert_eq!(info_block(&b).unwrap_err().code, Code::Elf);
assert_eq!(admit(&b), Err(Code::Elf));
}
/// A loaded dynamic section that sets DF_TEXTREL. The PT_DYNAMIC program
/// header names a benign copy of the same table without it.
#[test]
fn d04_pl2_pt_dynamic_at_a_benign_copy_is_refused() {
let genuine = reference().build();
let (off, size) = phdr_range(&genuine, 1);
let benign = genuine[off..off + size].to_vec();
let mut b = E {
textrel_flag: true,
..reference()
}
.build();
let at = append(&mut b, &benign);
set_phdr(&mut b, 1, 4, at); // PT_DYNAMIC p_offset
assert_eq!(admit(&b), Err(Code::Elf));
}
/// A second DT_SYMENT tag turned into DT_SYMTAB: the verifier would read the
/// first table, and the loader may read the other.
#[test]
fn d04_pl2_duplicate_dt_symtab_is_refused() {
let mut b = reference().build();
let (off, size) = phdr_range(&b, 1);
for at in (off..off + size).step_by(8) {
if word(&b, at) == 11 {
put_word(&mut b, at, 6);
}
}
assert_eq!(admit(&b), Err(Code::Elf));
}
/// Two `.wmod_info` sections: the verifier would check the first, and the
/// block the module hands the host may be the second.
#[test]
fn d04_pl2_two_info_sections_are_refused() {
let b = E {
info_twin: Some(info_bytes("solar", 1, F_LVGL_DIRECT, "9.6.0", 9, 1, 0)),
..reference()
}
.build();
assert_eq!(info_block(&b).unwrap_err().code, Code::Elf);
}
/// The host reads the info block at its load address, so an unallocated
/// `.wmod_info` section is refused.
#[test]
fn d04_pl2_unallocated_info_section_is_refused() {
let mut b = reference().build();
set_shdr(&mut b, 3, 8, 0); // sh_flags without SHF_ALLOC
assert_eq!(info_block(&b).unwrap_err().code, Code::Elf);
}
/// The header names 4 entries, so the checked table stops at `memcpy`. A
/// relocation names the fifth entry, `unlisted_call`, which the import check
/// never saw.
#[test]
fn d04_pl2_relocation_past_the_checked_table_is_refused() {
let mut b = E {
undefined: vec!["memcpy", "snprintf", "unlisted_call"],
rel_syms: vec![4],
..reference()
}
.build();
set_shdr(&mut b, 1, 20, 4 * 16);
assert_eq!(admit(&b), Err(Code::Elf));
}
#[test]
fn d04_pl2_relocations_of_checked_symbols_are_admitted() {
let b = E {
rel_syms: vec![2, 3],
..reference()
}
.build();
assert_eq!(admit(&b), Ok(Compat::Ok));
}
/// DT_HASH counts five symbols; the section header lets the verifier check four.
#[test]
fn d04_pl2_sysv_hash_counting_more_symbols_is_refused() {
let mut b = E {
undefined: vec!["memcpy", "snprintf", "unlisted_call"],
sysv_hash: Some((5, 0)),
..reference()
}
.build();
set_shdr(&mut b, 1, 20, 4 * 16);
assert_eq!(admit(&b), Err(Code::Elf));
}
#[test]
fn d04_pl2_sysv_hash_bucket_past_the_table_is_refused() {
let b = E {
sysv_hash: Some((4, 4)),
..reference()
}
.build();
assert_eq!(admit(&b), Err(Code::Elf));
}
#[test]
fn d04_pl2_sysv_hash_within_the_table_is_admitted() {
let b = E {
sysv_hash: Some((4, 0)),
..reference()
}
.build();
assert_eq!(admit(&b), Ok(Compat::Ok));
}
/// A GNU hash chain runs from symbol 1 to symbol 4. The checked table stops at
/// symbol 3.
#[test]
fn d04_pl2_gnu_hash_chain_past_the_table_is_refused() {
let mut b = E {
undefined: vec!["memcpy", "snprintf", "unlisted_call"],
gnu_hash: Some(GnuHash {
symoffset: 1,
bucket: vec![1],
chain: vec![0, 0, 0, 1],
}),
..reference()
}
.build();
set_shdr(&mut b, 1, 20, 4 * 16);
assert_eq!(admit(&b), Err(Code::Elf));
}
#[test]
fn d04_pl2_gnu_hash_within_the_table_is_admitted() {
let b = E {
gnu_hash: Some(GnuHash {
symoffset: 1,
bucket: vec![1],
chain: vec![0, 0, 1],
}),
..reference()
}
.build();
assert_eq!(admit(&b), Ok(Compat::Ok));
}
/// A load segment whose memory size is below its file size.
#[test]
fn d04_pl2_load_smaller_in_memory_than_in_file_is_refused() {
let mut b = reference().build();
set_phdr(&mut b, 0, 20, 0); // PT_LOAD p_memsz
assert_eq!(admit(&b), Err(Code::Elf));
}
/// A second load segment that maps addresses the first one already maps.
#[test]
fn d04_pl2_overlapping_load_segments_are_refused() {
let b = E {
extra_load: true,
..reference()
}
.build();
assert_eq!(admit(&b), Err(Code::Elf));
}
/// The first load segment ends inside the symbol table, so the table is not in
/// one segment and cannot be read at the header's offset.
#[test]
fn d04_pl2_symbol_table_crossing_its_load_segment_is_refused() {
let mut b = reference().build();
let (_, _, sym_off, _) = shdr(&b, 1);
set_phdr(&mut b, 0, 16, sym_off + 8); // PT_LOAD p_filesz
assert_eq!(admit(&b), Err(Code::Elf));
}
@@ -0,0 +1,152 @@
use flare_plugin_abi::fp1::*;
#[test]
fn kinds_and_deadlines() {
for n in 1..=6 {
assert!(Kind::from_i32(n).is_some());
}
assert!(Kind::from_i32(0).is_none() && Kind::from_i32(7).is_none());
assert_eq!(Kind::Http.deadline_ms(), 250);
assert_eq!(Kind::Page.deadline_ms(), 250);
assert_eq!(Kind::Action.deadline_ms(), 250);
assert_eq!(Kind::Job.deadline_ms(), 5000);
assert_eq!(Kind::Event.deadline_ms(), 5000);
}
#[test]
fn negative_codes_round_trip() {
for n in -9..=-1 {
let c = Neg::from_i32(n).unwrap();
assert_eq!(c.code(), n);
assert!(c.name().starts_with("E_"));
}
assert!(Neg::from_i32(0).is_none() && Neg::from_i32(-10).is_none());
assert_eq!(Neg::OpDenied.name(), "E_OP_DENIED");
}
#[test]
fn registry_has_unique_names_and_known_families() {
let mut seen = std::collections::BTreeSet::new();
for o in OPS {
assert!(seen.insert(o.name), "duplicate {}", o.name);
assert!(o.name.ends_with("@1"));
}
assert_eq!(OPS.len(), 18);
assert!(covers("kv@1", "kv.get@1") && covers("kv@1", "kv.list@1"));
assert!(covers("audit@1", "audit@1"));
assert!(!covers("kv@1", "sql.query@1"));
assert!(!covers("kv@1", "kv.nope@1"));
}
#[test]
fn grants_follow_the_op_table() {
assert_eq!(op_def("kv.put@1").unwrap().grant, Grant::None);
assert_eq!(op_def("sql.exec@1").unwrap().grant, Grant::Schema);
assert_eq!(op_def("http.fetch@1").unwrap().grant, Grant::Hosts);
assert_eq!(op_def("cfg.write@1").unwrap().grant, Grant::SitePaths);
assert_eq!(op_def("command.send@1").unwrap().grant, Grant::SiteVerbs);
assert_eq!(op_def("secret.get@1").unwrap().grant, Grant::Secret);
}
#[test]
fn manifest_op_lists() {
assert!(check_manifest_ops(&["kv@1", "audit@1", "cfg.write@1"]).is_ok());
assert!(check_manifest_ops(&["kv@2"]).is_err());
assert!(check_manifest_ops(&["fs.read@1"]).is_err());
}
#[test]
fn call_requests() {
let r = parse_call(br#"{"op":"kv.get@1","args":{"scope":"global","key":"a"}}"#).unwrap();
assert_eq!(r.op.name, "kv.get@1");
assert_eq!(r.args["key"], "a");
// args default to an empty object
assert!(parse_call(br#"{"op":"time.now@1"}"#)
.unwrap()
.args
.as_object()
.unwrap()
.is_empty());
let cases: &[(&[u8], Neg)] = &[
(b"", Neg::Arg),
(b"[]", Neg::Arg),
(b"not json", Neg::Arg),
(br#"{"args":{}}"#, Neg::Arg),
(br#"{"op":5}"#, Neg::Arg),
(br#"{"op":"time.now@1","args":[]}"#, Neg::Arg),
(br#"{"op":"time.now@1","extra":1}"#, Neg::Arg),
(br#"{"op":"fs.read@1"}"#, Neg::OpUnknown),
(br#"{"op":"kv.get"}"#, Neg::OpUnknown),
];
for (b, want) in cases {
assert_eq!(
parse_call(b).unwrap_err(),
*want,
"{}",
String::from_utf8_lossy(b)
);
}
let big = vec![b' '; MAX_MESSAGE_BYTES + 1];
assert_eq!(parse_call(&big).unwrap_err(), Neg::Limit);
}
#[test]
fn response_headers_are_filtered() {
let f = filter_response_header;
assert_eq!(
f("Content-Type", "text/plain").as_deref(),
Some("text/plain")
);
assert_eq!(f("x-request-id", "abc").as_deref(), Some("abc"));
assert_eq!(f("Cache-Control", "no-store").as_deref(), Some("no-store"));
assert_eq!(f("cache-control", "public, max-age=99"), None);
assert_eq!(f("Set-Cookie", "a=b"), None);
assert_eq!(f("set-cookie", "a=b"), None);
assert_eq!(f("x-custom", "1"), None);
assert_eq!(
f("location", "/apps/x/done").as_deref(),
Some("/apps/x/done")
);
for bad in [
"https://evil.example/",
"//evil.example/",
"javascript:alert(1)",
"/\\evil",
"foo",
] {
assert_eq!(f("location", bad), None, "{bad}");
}
assert_eq!(f("content-type", "text/plain\r\nSet-Cookie: a=b"), None);
}
#[test]
fn routes_mount_only_under_the_plugin_prefix() {
assert!(route_allowed("acme", "/apps/acme/settings"));
assert!(route_allowed("acme", "/api/v1/apps/acme/hook"));
assert!(route_allowed("acme", "/apps/acme"));
for bad in [
"/apps/other/x",
"/apps/acme/../admin",
"/apps/acmex/y",
"/admin",
"/",
"/api/v1/sites",
"/apps/acme//x",
"/apps/acme/x?y=1",
"/api/v1/apps/other/x",
] {
assert!(!route_allowed("acme", bad), "{bad}");
}
assert!(!route_allowed("", "/apps//x"));
assert!(!route_allowed("A/b", "/apps/A/b/x"));
}
#[test]
fn limits_match_the_spec() {
assert_eq!(MAX_MODULE_BYTES, 2 << 20);
assert_eq!(MAX_MESSAGE_BYTES, 1 << 20);
assert_eq!(MAX_CALLS_PER_HANDLER, 64);
assert_eq!(DEFAULT_FUEL, 50_000_000);
assert_eq!((BREAKER_TRIPS, BREAKER_WINDOW_S), (5, 60));
assert_eq!((BREAKER_FIRST_HOLD_S, BREAKER_MAX_HOLD_S), (600, 3600));
}
@@ -0,0 +1,657 @@
//! Package admission (B-13, W-D4, AT-M6-13, AT-M8-08 admission errors, T-WA-01).
//!
//! The code inside a signed `.wapp` is admitted only from a `platform` key,
//! every refusal carries its reason code, and the signature is checked by the
//! verifier itself, not by the caller.
mod common;
use common::*;
use flare_plugin_abi::package::{admit_module, admit_validated_module, Host};
#[cfg(feature = "wasm")]
use flare_plugin_abi::package::{admit_plugin, PluginMode};
use flare_plugin_abi::wmod::{Compat, NameList, F_LVGL_DIRECT};
use flare_plugin_abi::{Code, Error};
use wapp_core::appkeys::{AllowedIds, KeyClass};
use wapp_core::json::Value;
#[cfg(feature = "wasm")]
use wapp_core::ustar::read_members;
/// Firmware import lists for module admission: the libc allow list and the
/// host exports a Layer 2 module may call.
fn firmware() -> (NameList, NameList) {
(
NameList::parse("# libc\nmem*\nsnprintf\n"),
NameList::parse("lv_*\n"),
)
}
fn host<'a>(libc: &'a NameList, exports: &'a NameList, granted: &'a [&'a str]) -> Host<'a> {
Host {
libc_allow: libc,
host_exports: exports,
cxx: false,
abi_major: 1,
abi_minor: 0,
lvgl_version: "9.6.0",
sdk_hash: [9; 32],
granted,
}
}
/// A panel module built with the info block of `solar`, build 1, ABI 1.0.
fn module_bytes(major: u16, minor: u16) -> Vec<u8> {
E {
info: Some(info_bytes("solar", 1, 0, "9.6.0", 9, major, minor)),
..E::default()
}
.build()
}
fn module_archive(t: &Value, module: Vec<u8>) -> Vec<u8> {
pack_signed(t, &module_files(module), &SEED)
}
#[cfg(feature = "wasm")]
fn plugin_archive(module: Vec<u8>) -> Vec<u8> {
pack_signed(&plugin_template(), &plugin_files(module), &SEED)
}
#[cfg(feature = "wasm")]
fn wasm_ok() -> Vec<u8> {
W::default().build()
}
// ---- FLARE plugins (fp/1) ----
#[cfg(feature = "wasm")]
#[test]
fn plugin_signed_by_platform_is_admitted() {
let fx = Fx::new();
let a = plugin_archive(wasm_ok());
let p = admit_plugin(PluginMode::Signed, &a, &fx.ctx()).unwrap();
assert_eq!(p.app_id, "ai-test");
assert_eq!(p.app_build, 1);
assert_eq!(p.class, KeyClass::Platform);
assert_eq!(p.module, "flare/plugin.wasm");
assert_eq!(p.admitted.memory_max_pages, 4);
}
#[cfg(feature = "wasm")]
#[test]
fn plugin_with_a_flipped_signature_bit_is_refused() {
let fx = Fx::new();
let mut a = plugin_archive(wasm_ok());
let m = read_members(&a).unwrap();
a[m.sig.start] ^= 1;
assert_eq!(
admit_plugin(PluginMode::Signed, &a, &fx.ctx())
.unwrap_err()
.code,
Code::Sig
);
}
#[cfg(feature = "wasm")]
#[test]
fn plugin_signed_by_an_unknown_key_is_refused() {
let mut fx = Fx::new();
fx.keys = vec![key(&OTHER_SEED, KeyClass::Platform, AllowedIds::Any)];
let a = plugin_archive(wasm_ok());
assert_eq!(
admit_plugin(PluginMode::Signed, &a, &fx.ctx())
.unwrap_err()
.code,
Code::Sig
);
}
#[cfg(feature = "wasm")]
#[test]
fn plugin_signed_by_a_partner_key_is_refused() {
// B-13: no third-party code runs before an out-of-process runtime exists.
let mut fx = Fx::new();
fx.keys = vec![key(&SEED, KeyClass::Partner, AllowedIds::Any)];
let a = plugin_archive(wasm_ok());
assert_eq!(
admit_plugin(PluginMode::Signed, &a, &fx.ctx())
.unwrap_err()
.code,
Code::Key
);
}
#[cfg(not(feature = "plugin-dev"))]
#[cfg(feature = "wasm")]
#[test]
fn dev_class_is_compiled_out_of_a_release_build() {
// W-D4: the dev key class is absent from a release build, so no mode admits it.
assert!(PluginMode::Dev.check_startup().is_err());
let mut fx = Fx::new();
fx.keys = vec![key(&SEED, KeyClass::Dev, AllowedIds::Any)];
let a = plugin_archive(wasm_ok());
assert_eq!(PluginMode::Dev.check_startup().unwrap_err().code, Code::Key);
assert_eq!(
admit_plugin(PluginMode::Dev, &a, &fx.ctx())
.unwrap_err()
.code,
Code::Key
);
assert_eq!(
admit_plugin(PluginMode::Signed, &a, &fx.ctx())
.unwrap_err()
.code,
Code::Key
);
}
#[cfg(feature = "plugin-dev")]
#[cfg(feature = "wasm")]
#[test]
fn dev_signed_plugin_is_admitted_only_in_dev_mode() {
assert!(PluginMode::Dev.check_startup().is_ok());
let mut fx = Fx::new();
fx.keys = vec![key(&SEED, KeyClass::Dev, AllowedIds::Any)];
let a = plugin_archive(wasm_ok());
assert_eq!(
admit_plugin(PluginMode::Signed, &a, &fx.ctx())
.unwrap_err()
.code,
Code::Key
);
let p = admit_plugin(PluginMode::Dev, &a, &fx.ctx()).unwrap();
assert_eq!(p.class, KeyClass::Dev);
}
#[cfg(feature = "wasm")]
#[test]
fn plugins_off_refuses_wasm_before_any_check() {
let fx = Fx::new();
let a = plugin_archive(wasm_ok());
let e: Error = admit_plugin(PluginMode::Off, &a, &fx.ctx()).unwrap_err();
assert_eq!((e.code, e.detail.as_str()), (Code::Key, "plugins_off"));
}
#[cfg(feature = "wasm")]
#[test]
fn plugin_mode_values_parse_exactly() {
assert_eq!(PluginMode::parse("off"), Some(PluginMode::Off));
assert_eq!(PluginMode::parse("signed"), Some(PluginMode::Signed));
assert_eq!(PluginMode::parse("dev"), Some(PluginMode::Dev));
assert_eq!(PluginMode::parse("DEV"), None);
assert_eq!(PluginMode::parse(""), None);
}
#[cfg(feature = "wasm")]
#[test]
fn plugin_admission_errors_carry_their_codes() {
// AT-M8-08: admission errors E_IMPORT, E_WASM and E_LIMIT.
let fx = Fx::new();
let cases = [
(
W {
extra_import: Some(("env", "puts")),
..W::default()
},
Code::Import,
),
(
W {
start: true,
..W::default()
},
Code::Wasm,
),
(
W {
memory: Some((1, Some(1024), false)),
..W::default()
},
Code::Limit,
),
(
W {
drop_export: Some("fp_handle"),
..W::default()
},
Code::Wasm,
),
];
for (w, want) in cases {
let a = plugin_archive(w.build());
assert_eq!(
admit_plugin(PluginMode::Signed, &a, &fx.ctx())
.unwrap_err()
.code,
want
);
}
}
#[cfg(feature = "wasm")]
#[test]
fn plugin_manifest_refusals_are_manifest_codes() {
let fx = Fx::new();
// An ABI other than fp/1.
let mut t = plugin_template();
set(&mut t, "flare.plugin.abi", Value::Int(2));
let a = pack_signed(&t, &plugin_files(wasm_ok()), &SEED);
assert_eq!(
admit_plugin(PluginMode::Signed, &a, &fx.ctx())
.unwrap_err()
.code,
Code::Manifest
);
// A flare half that names a compiled-in module, not a plugin.
let mut t = plugin_template();
set(&mut t, "flare", j(r#"{"module":"flare/plugin.wasm"}"#));
let a = pack_signed(&t, &plugin_files(wasm_ok()), &SEED);
assert_eq!(
admit_plugin(PluginMode::Signed, &a, &fx.ctx())
.unwrap_err()
.code,
Code::Manifest
);
}
// ---- panel modules (wmod/1) ----
#[test]
fn module_signed_by_platform_is_admitted() {
let fx = Fx::new();
let a = module_archive(&module_template(), module_bytes(1, 0));
let (libc, exports) = firmware();
let granted = ["ui.native"];
let m = admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted)).unwrap();
assert_eq!(m.compat, Compat::Ok);
assert_eq!(m.needed, vec!["libc.so.0".to_string()]);
assert_eq!(m.module, "ui/modules/mining.so");
assert_eq!(m.info.app_id, "solar");
assert_eq!(m.class, KeyClass::Platform);
}
/// The installer path verifies once and then runs the module check on the
/// result; it must admit exactly what `admit_module` admits.
#[test]
fn validated_module_path_matches_admit_module() {
let fx = Fx::new();
let a = module_archive(&module_template(), module_bytes(1, 0));
let (libc, exports) = firmware();
let granted = ["ui.native"];
let h = host(&libc, &exports, &granted);
let direct = admit_module(&a, &fx.ctx(), &h).unwrap();
let (v, c) = wapp_core::validate::validate_full(&a, &fx.ctx()).unwrap();
assert_eq!(admit_validated_module(&v, &c, &h).unwrap(), direct);
// Without the grant the validated path refuses too.
let no_grant: [&str; 0] = [];
let h2 = host(&libc, &exports, &no_grant);
assert_eq!(
admit_validated_module(&v, &c, &h2).unwrap_err().code,
Code::Grant
);
}
#[test]
fn module_signed_by_a_partner_key_is_refused() {
let mut fx = Fx::new();
fx.keys = vec![key(&SEED, KeyClass::Partner, AllowedIds::Any)];
let a = module_archive(&module_template(), module_bytes(1, 0));
let (libc, exports) = firmware();
let granted = ["ui.native"];
assert_eq!(
admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted))
.unwrap_err()
.code,
Code::Key
);
}
#[cfg(not(feature = "plugin-dev"))]
#[test]
fn module_dev_key_is_compiled_out_of_a_release_build() {
let mut fx = Fx::new();
fx.keys = vec![key(&SEED, KeyClass::Dev, AllowedIds::Any)];
let a = module_archive(&module_template(), module_bytes(1, 0));
let (libc, exports) = firmware();
let granted = ["ui.native"];
assert_eq!(
admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted))
.unwrap_err()
.code,
Code::Key
);
}
/// The positive side of the refusal above: in a plugin-dev build a module
/// signed by the dev key class is admitted (13.3.5).
#[cfg(feature = "plugin-dev")]
#[test]
fn module_signed_by_a_dev_key_is_admitted_in_a_plugin_dev_build() {
let mut fx = Fx::new();
fx.keys = vec![key(&SEED, KeyClass::Dev, AllowedIds::Any)];
let a = module_archive(&module_template(), module_bytes(1, 0));
let (libc, exports) = firmware();
let granted = ["ui.native"];
let adm = admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted)).unwrap();
assert_eq!(adm.app_id, "solar");
assert_eq!(adm.class, KeyClass::Dev);
}
#[test]
fn module_abi_major_mismatch_is_refused_at_install() {
let fx = Fx::new();
let a = module_archive(&module_template(), module_bytes(2, 0));
let (libc, exports) = firmware();
let granted = ["ui.native"];
assert_eq!(
admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted))
.unwrap_err()
.code,
Code::Platform
);
}
#[test]
fn module_newer_minor_is_admitted_as_needs_platform() {
// 13.3.6: the install goes through; the module waits for firmware.
let fx = Fx::new();
let a = module_archive(&module_template(), module_bytes(1, 1));
let (libc, exports) = firmware();
let granted = ["ui.native"];
let m = admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted)).unwrap();
assert!(matches!(m.compat, Compat::NeedsPlatform(_)));
}
#[test]
fn module_lvgl_mismatch_is_admitted_as_needs_platform() {
let fx = Fx::new();
let bytes = E {
info: Some(info_bytes("solar", 1, F_LVGL_DIRECT, "9.5.0", 9, 1, 0)),
..E::default()
}
.build();
let a = module_archive(&module_template(), bytes);
let (libc, exports) = firmware();
let granted = ["ui.native", "ui.lvgl_direct"];
let m = admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted)).unwrap();
assert!(matches!(m.compat, Compat::NeedsPlatform(_)));
}
#[test]
fn module_without_the_ui_native_grant_is_refused() {
let fx = Fx::new();
let a = module_archive(&module_template(), module_bytes(1, 0));
let (libc, exports) = firmware();
let granted: [&str; 0] = [];
assert_eq!(
admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted))
.unwrap_err()
.code,
Code::Grant
);
}
#[test]
fn module_platform_verbs_need_their_grant() {
let fx = Fx::new();
let mut t = module_template();
set(
&mut t,
"permissions",
j(
r#"[{"name":"storage.data","class":"normal","reason":"Keeps its settings"},
{"name":"ui.native","class":"privileged","reason":"Draws the radar"},
{"name":"platform.reboot","class":"privileged","reason":"Restarts after an update"}]"#,
),
);
let a = module_archive(&t, module_bytes(1, 0));
let (libc, exports) = firmware();
let without = ["ui.native"];
assert_eq!(
admit_module(&a, &fx.ctx(), &host(&libc, &exports, &without))
.unwrap_err()
.code,
Code::Grant
);
let with = ["ui.native", "platform.reboot"];
assert!(admit_module(&a, &fx.ctx(), &host(&libc, &exports, &with)).is_ok());
}
#[test]
fn module_info_for_another_app_is_refused() {
let fx = Fx::new();
let bytes = E {
info: Some(info_bytes("other", 1, 0, "9.6.0", 9, 1, 0)),
..E::default()
}
.build();
let a = module_archive(&module_template(), bytes);
let (libc, exports) = firmware();
let granted = ["ui.native"];
assert_eq!(
admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted))
.unwrap_err()
.code,
Code::Platform
);
}
#[test]
fn module_outside_ui_modules_is_refused() {
let fx = Fx::new();
let mut t = module_template();
set(
&mut t,
"ui.native.module",
Value::Str("bin/mining.so".into()),
);
let a = module_archive(&t, module_bytes(1, 0));
let (libc, exports) = firmware();
let granted = ["ui.native"];
assert_eq!(
admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted))
.unwrap_err()
.code,
Code::Manifest
);
}
// ---- T-WA-01: reason codes bound to refusing vectors ----
#[test]
fn t_wa_01_panel_module_elf_code_has_a_refusing_vector() {
let fx = Fx::new();
let musl = E {
needed: vec!["libc.so"],
info: Some(info_bytes("solar", 1, 0, "9.6.0", 9, 1, 0)),
..E::default()
}
.build();
let a = module_archive(&module_template(), musl);
let (libc, exports) = firmware();
let granted = ["ui.native"];
assert_eq!(
admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted))
.unwrap_err()
.code,
Code::Elf
);
}
#[test]
fn t_wa_01_panel_module_symbols_code_has_a_refusing_vector() {
let fx = Fx::new();
let extra = E {
defined: vec!["wmod_entry", "extra_export"],
info: Some(info_bytes("solar", 1, 0, "9.6.0", 9, 1, 0)),
..E::default()
}
.build();
let a = module_archive(&module_template(), extra);
let (libc, exports) = firmware();
let granted = ["ui.native"];
assert_eq!(
admit_module(&a, &fx.ctx(), &host(&libc, &exports, &granted))
.unwrap_err()
.code,
Code::Symbols
);
}
/// The code a panel-module archive is refused with. A module that is admitted
/// panics here, so each test names the one code it expects.
fn module_refusal(archive: &[u8], ctx: &wapp_core::validate::Ctx<'_>, host: &Host<'_>) -> Code {
admit_module(archive, ctx, host).unwrap_err().code
}
/// T-WA-01 (s12 4.5): every reason code of the row has a refusing vector on the
/// panel-module admission path. The list at the end names all ten codes.
#[test]
fn t_wa_01_every_reason_code_has_a_refusing_module_vector() {
let (libc, exports) = firmware();
let granted = ["ui.native"];
let h = host(&libc, &exports, &granted);
let fx = Fx::new();
let ok = module_bytes(1, 0);
let mut seen: Vec<&'static str> = Vec::new();
// E_MANIFEST: a manifest format this verifier does not read.
let mut t = module_template();
set(&mut t, "format", j("2"));
let got = module_refusal(&module_archive(&t, ok.clone()), &fx.ctx(), &h);
assert_eq!(got, Code::Manifest);
seen.push(got.as_str());
// E_RESERVED: an id that is not a valid app id.
let mut t = module_template();
set(&mut t, "id", j("\"Solar\""));
let got = module_refusal(&module_archive(&t, ok.clone()), &fx.ctx(), &h);
assert_eq!(got, Code::Reserved);
seen.push(got.as_str());
// E_SIG: one bit of the signature flipped.
let mut a = module_archive(&module_template(), ok.clone());
let m = wapp_core::ustar::read_members(&a).unwrap();
a[m.sig.start] ^= 1;
let got = module_refusal(&a, &fx.ctx(), &h);
assert_eq!(got, Code::Sig);
seen.push(got.as_str());
// E_KEY: signed by a partner key, which panel modules never admit.
let mut partner = Fx::new();
partner.keys = vec![key(&SEED, KeyClass::Partner, AllowedIds::Any)];
let a = module_archive(&module_template(), ok.clone());
let got = module_refusal(&a, &partner.ctx(), &h);
assert_eq!(got, Code::Key);
seen.push(got.as_str());
// E_REVOKED: build 1 of the app is in the revocation list.
let mut revoked = Fx::new();
revoked.revoked.builds.push(("solar".into(), 1));
let a = module_archive(&module_template(), ok.clone());
let got = module_refusal(&a, &revoked.ctx(), &h);
assert_eq!(got, Code::Revoked);
seen.push(got.as_str());
// E_FLOOR: build 1 is at or below the anti-rollback floor.
let mut floor = fx.ctx();
floor.floor_build = Some(1);
let a = module_archive(&module_template(), ok.clone());
let got = module_refusal(&a, &floor, &h);
assert_eq!(got, Code::Floor);
seen.push(got.as_str());
// E_PLATFORM: the info block names another app.
let other = E {
info: Some(info_bytes("other", 1, 0, "9.6.0", 9, 1, 0)),
..E::default()
}
.build();
let got = module_refusal(&module_archive(&module_template(), other), &fx.ctx(), &h);
assert_eq!(got, Code::Platform);
seen.push(got.as_str());
// E_HASH: one byte of the stored module changed after signing.
let mut a = module_archive(&module_template(), ok.clone());
let at = a.windows(4).position(|w| w == b"\x7fELF").unwrap();
a[at + ok.len() - 1] ^= 1;
let got = module_refusal(&a, &fx.ctx(), &h);
assert_eq!(got, Code::Hash);
seen.push(got.as_str());
// E_ELF: linked against musl.
let musl = E {
needed: vec!["libc.so"],
info: Some(info_bytes("solar", 1, 0, "9.6.0", 9, 1, 0)),
..E::default()
}
.build();
let got = module_refusal(&module_archive(&module_template(), musl), &fx.ctx(), &h);
assert_eq!(got, Code::Elf);
seen.push(got.as_str());
// E_SYMBOLS: one export beyond wmod_entry.
let extra = E {
defined: vec!["wmod_entry", "extra_export"],
info: Some(info_bytes("solar", 1, 0, "9.6.0", 9, 1, 0)),
..E::default()
}
.build();
let got = module_refusal(&module_archive(&module_template(), extra), &fx.ctx(), &h);
assert_eq!(got, Code::Symbols);
seen.push(got.as_str());
let mut want = vec![
"E_MANIFEST",
"E_RESERVED",
"E_SIG",
"E_KEY",
"E_REVOKED",
"E_FLOOR",
"E_PLATFORM",
"E_HASH",
"E_ELF",
"E_SYMBOLS",
];
seen.sort_unstable();
want.sort_unstable();
assert_eq!(seen, want);
}
#[test]
fn t_wa_01_wire_codes_match_wapp_core() {
// Every .wapp code keeps its spelling, so a package refusal reaches the UI
// with the code wapp-core chose (s12 4.6).
use wapp_core::Code as WappCode;
let wapp = [
WappCode::Reserved,
WappCode::Source,
WappCode::Hash,
WappCode::Sig,
WappCode::Key,
WappCode::Revoked,
WappCode::Floor,
WappCode::Platform,
WappCode::Deps,
WappCode::Conflict,
WappCode::Budget,
WappCode::Grant,
WappCode::Precond,
WappCode::Policy,
WappCode::Dependents,
WappCode::Core,
WappCode::Veto,
WappCode::Compat,
WappCode::Manifest,
WappCode::Elf,
WappCode::Symbols,
WappCode::Snapshot,
];
for c in wapp {
let mapped: Error = wapp_core::Error::new(c, "detail").into();
assert_eq!(mapped.code.as_str(), c.as_str());
assert_eq!(mapped.detail, "detail");
}
assert_eq!(Code::ALL.len(), 25);
assert_eq!(Code::from_wire("E_NOPE"), None);
}
@@ -0,0 +1,103 @@
//! T-WA-07 (s12 4.5 V16): ELF vectors for `bin/` and `hooks/`.
//!
//! The ELF checks are wapp-core's (`wapp_core::elf`). This file replays the
//! vector table against them, so the T-WA-07 row names a test in this crate.
//! The setuid vectors are payload-mode cases: under a valid signature, a
//! `bin/` or `hooks/` member whose tar mode carries the setuid bit is refused
//! with `Code::Manifest` ("wrong mode"), and the same archive with the expected
//! modes is admitted.
mod common;
use std::collections::BTreeMap;
use common::{j, service_files, service_template, set, Fx, E, SEED};
use wapp_core::build::seal;
use wapp_core::elf::{check_arm_static, check_script, sample_arm_static};
use wapp_core::manifest::expected_mode;
use wapp_core::ustar::{write_end, write_member};
use wapp_core::validate::validate_full;
use wapp_core::Code;
#[test]
fn t_wa_07_bin_and_hook_vectors() {
// Static ARM hard-float ELF without interpreter or needed libraries: passes.
assert!(check_arm_static(&sample_arm_static()).is_ok());
// Dynamic: DT_NEEDED names a shared library.
let dynamic = E::default().build();
assert_eq!(check_arm_static(&dynamic).unwrap_err().code, Code::Elf);
// Wrong architecture (EM_386).
let wrong_arch = E {
machine: 3,
needed: vec![],
..E::default()
}
.build();
assert_eq!(check_arm_static(&wrong_arch).unwrap_err().code, Code::Elf);
// Soft-float: EF_ARM_ABI_FLOAT_HARD is clear.
let soft = E {
flags: 0x0500_0000,
needed: vec![],
..E::default()
}
.build();
assert_eq!(check_arm_static(&soft).unwrap_err().code, Code::Elf);
// PT_INTERP: the first program header is changed to type 3.
let mut interp = sample_arm_static();
interp[52] = 3;
assert_eq!(check_arm_static(&interp).unwrap_err().code, Code::Elf);
// Shell hooks must start with #!/bin/sh.
assert!(check_script(b"#!/bin/sh\nexit 0\n").is_ok());
assert_eq!(check_script(b"#!/bin/bash\n").unwrap_err().code, Code::Elf);
}
/// The members of `files` in payload order, each with its expected mode.
/// `setuid` names one member that also gets the setuid bit.
fn payload_with_setuid(files: &BTreeMap<String, Vec<u8>>, setuid: Option<&str>) -> Vec<u8> {
let mut tar = Vec::new();
for (path, data) in files {
let mut mode = expected_mode(path);
if setuid == Some(path.as_str()) {
mode |= 0o4000;
}
write_member(&mut tar, path, mode, data);
}
write_end(&mut tar);
tar
}
#[test]
fn t_wa_07_setuid_bin_and_hook_members_are_refused() {
let fx = Fx::new();
let mut template = service_template();
set(
&mut template,
"hooks",
j(r#"{"pre_stop":{"path":"hooks/pre-stop"}}"#),
);
let mut files = service_files();
files.insert("hooks/pre-stop".into(), b"#!/bin/sh\nexit 0\n".to_vec());
// Control: the expected modes. Each refusal below differs from this
// archive in the setuid bit alone.
let payload = payload_with_setuid(&files, None);
let ok = seal(&template, &files, &payload, false, &SEED).unwrap();
if let Err(e) = validate_full(&ok, &fx.ctx()) {
panic!("control archive refused: {:?} {}", e.code, e.detail);
}
for member in ["bin/warden-asic", "hooks/pre-stop"] {
let payload = payload_with_setuid(&files, Some(member));
let forged = seal(&template, &files, &payload, false, &SEED).unwrap();
let Err(e) = validate_full(&forged, &fx.ctx()) else {
panic!("{member}: a setuid member was admitted");
};
assert_eq!(e.code, Code::Manifest, "{member}: {}", e.detail);
assert!(e.detail.contains("wrong mode"), "{member}: {}", e.detail);
}
}
@@ -0,0 +1,222 @@
#![cfg(feature = "wasm")]
mod common;
use common::W;
use flare_plugin_abi::wasm::admit;
use flare_plugin_abi::Code;
fn code(w: &W, mb: u32) -> Code {
admit(&w.build(), mb).unwrap_err().code
}
#[test]
fn valid_module_is_admitted() {
let a = admit(&W::default().build(), 4).unwrap();
assert_eq!((a.memory_min_pages, a.memory_max_pages), (1, 4));
assert!(a.imports_call && a.imports_log);
}
#[test]
fn memory_at_the_limit_is_admitted() {
// 1 MiB is 16 pages.
let w = W {
memory: Some((1, Some(16), false)),
..W::default()
};
assert!(admit(&w.build(), 1).is_ok());
}
#[test]
fn memory_above_the_limit_is_refused() {
let w = W {
memory: Some((1, Some(17), false)),
..W::default()
};
assert_eq!(code(&w, 1), Code::Limit);
}
#[test]
fn memory_without_maximum_is_refused() {
let w = W {
memory: Some((1, None, false)),
..W::default()
};
assert_eq!(code(&w, 64), Code::Limit);
}
#[test]
fn shared_memory_is_refused() {
let w = W {
memory: Some((1, Some(2), true)),
..W::default()
};
assert_eq!(code(&w, 4), Code::Wasm);
}
#[test]
fn no_memory_is_refused() {
let w = W {
memory: None,
..W::default()
};
assert_eq!(code(&w, 4), Code::Wasm);
}
#[test]
fn two_memories_are_refused() {
let w = W {
second_memory: true,
..W::default()
};
assert_eq!(code(&w, 4), Code::Wasm);
}
#[test]
fn unknown_import_is_refused() {
for (m, n) in [
("env", "abort"),
("wasi_snapshot_preview1", "fd_write"),
("fp1", "exec"),
] {
let w = W {
extra_import: Some((m, n)),
..W::default()
};
assert_eq!(code(&w, 4), Code::Import, "{m}.{n}");
}
}
#[test]
fn memory_import_is_refused() {
let w = W {
memory_import: true,
..W::default()
};
assert_eq!(code(&w, 4), Code::Import);
}
#[test]
fn wrong_import_type_is_refused() {
let w = W {
call_sig_wrong: true,
..W::default()
};
assert_eq!(code(&w, 4), Code::Import);
}
#[test]
fn duplicate_import_is_refused() {
let w = W {
duplicate_log: true,
..W::default()
};
assert_eq!(code(&w, 4), Code::Import);
}
#[test]
fn start_function_is_refused() {
let w = W {
start: true,
..W::default()
};
assert_eq!(code(&w, 4), Code::Wasm);
}
#[test]
fn each_missing_export_is_refused() {
for n in ["memory", "fp_alloc", "fp_free", "fp_init", "fp_handle"] {
let w = W {
drop_export: Some(n),
..W::default()
};
assert_eq!(code(&w, 4), Code::Wasm, "{n}");
}
}
#[test]
fn wrong_export_type_is_refused() {
let w = W {
handle_returns_i32: true,
..W::default()
};
assert_eq!(code(&w, 4), Code::Wasm);
}
#[test]
fn two_tables_are_refused() {
let w = W {
tables: 2,
..W::default()
};
assert_eq!(code(&w, 4), Code::Wasm);
let one = W {
tables: 1,
..W::default()
};
assert!(admit(&one.build(), 4).is_ok());
}
#[test]
fn simd_is_refused() {
let w = W {
simd: true,
..W::default()
};
assert_eq!(code(&w, 4), Code::Wasm);
}
#[test]
fn oversize_module_is_refused() {
let w = W {
pad: 2 * 1024 * 1024,
..W::default()
};
assert_eq!(code(&w, 4), Code::Limit);
}
#[test]
fn module_at_the_size_limit_is_admitted() {
let base = W::default().build().len();
// The custom section header costs a few bytes; fill to exactly 2 MiB.
let mut pad = 2 * 1024 * 1024 - base - 12;
let w = loop {
let w = W {
pad,
..W::default()
};
let n = w.build().len();
if n == 2 * 1024 * 1024 {
break w;
}
pad = (pad as i64 + (2 * 1024 * 1024) - n as i64) as usize;
};
assert!(admit(&w.build(), 4).is_ok());
}
#[test]
fn garbage_is_refused_not_panicked() {
for b in [
&b""[..],
b"\0asm",
b"\0asm\x01\0\0\0\x01",
b"not wasm at all",
&[0xff; 64],
] {
assert_eq!(admit(b, 4).unwrap_err().code, Code::Wasm);
}
}
#[test]
fn zero_memory_limit_is_a_manifest_error() {
assert_eq!(
admit(&W::default().build(), 0).unwrap_err().code,
Code::Manifest
);
}
#[test]
fn truncation_never_panics() {
let full = W::default().build();
for n in 0..full.len() {
let _ = admit(&full[..n], 4);
}
}
@@ -0,0 +1,383 @@
mod common;
use common::{info_bytes, E};
use flare_plugin_abi::wmod::*;
use flare_plugin_abi::Code;
const ALLOW: &str = "# libc\nstr*\nmem*\nsnprintf\nstrto*\nqsort\n__aeabi_*\nsin\n";
const EXPORTS: &str = "lv_*\nwarden_page_*\n";
fn run(e: &E, cxx: bool) -> Result<Vec<String>, flare_plugin_abi::Error> {
let allow = NameList::parse(ALLOW);
let host = NameList::parse(EXPORTS);
check_module(
&e.build(),
&Policy {
libc_allow: &allow,
host_exports: &host,
cxx,
},
)
}
fn code(e: &E) -> Code {
run(e, false).unwrap_err().code
}
#[test]
fn valid_module_is_admitted() {
assert_eq!(run(&E::default(), false).unwrap(), vec!["libc.so.0"]);
}
#[test]
fn flags_1_now_also_counts_as_bind_now() {
let e = E {
bind_now: false,
flags1_now: true,
..E::default()
};
assert!(run(&e, false).is_ok());
}
#[test]
fn header_refusals() {
let cases = [
E {
class: 2,
..E::default()
},
E {
data: 2,
..E::default()
},
E {
etype: 2,
..E::default()
},
E {
machine: 3,
..E::default()
},
E {
flags: 0x0400_0400,
..E::default()
}, // EABI4
E {
flags: 0x0500_0200,
..E::default()
}, // soft float
];
for (i, e) in cases.iter().enumerate() {
assert_eq!(code(e), Code::Elf, "case {i}");
}
}
#[test]
fn dynamic_section_refusals() {
let cases = [
E {
needed: vec!["libc.so.6"],
..E::default()
}, // glibc build
E {
needed: vec!["libpthread.so.0"],
..E::default()
},
E {
needed: vec!["libstdc++.so.6"],
..E::default()
}, // C++ not declared
E {
rpath: true,
..E::default()
},
E {
runpath: true,
..E::default()
},
E {
textrel: true,
..E::default()
},
E {
bind_now: false,
..E::default()
},
E {
exec_stack: true,
..E::default()
},
E {
gnu_stack: false,
..E::default()
},
E {
no_sections: true,
..E::default()
},
];
for (i, e) in cases.iter().enumerate() {
assert_eq!(code(e), Code::Elf, "case {i}");
}
}
#[test]
fn cxx_allows_libstdcxx_only_when_declared() {
let e = E {
needed: vec!["libc.so.0", "libm.so.0", "libgcc_s.so.1", "libstdc++.so.6"],
..E::default()
};
assert!(run(&e, true).is_ok());
assert_eq!(run(&e, false).unwrap_err().code, Code::Elf);
}
#[test]
fn exports_must_be_exactly_the_entry() {
let cases = [
E {
defined: vec![],
..E::default()
},
E {
defined: vec!["wmod_entry", "helper"],
..E::default()
},
E {
defined: vec!["wmod_main"],
..E::default()
},
];
for (i, e) in cases.iter().enumerate() {
assert_eq!(code(e), Code::Symbols, "case {i}");
}
}
#[test]
fn imports_are_checked_against_the_lists() {
// Allowed by prefix and by the host export list.
let ok = E {
undefined: vec![
"strlen",
"memset",
"__aeabi_idiv",
"lv_obj_create",
"warden_page_add",
"sin",
],
..E::default()
};
assert!(run(&ok, false).is_ok());
for bad in ["cos", "mosquitto_publish", "lvx_unknown", "unknown_fn"] {
let e = E {
undefined: vec![bad],
..E::default()
};
assert_eq!(code(&e), Code::Symbols, "{bad}");
}
}
#[test]
fn denied_imports_beat_the_allow_list() {
// Even when a list is careless enough to allow them.
let allow = NameList::parse(&format!(
"{}malloc\nsystem\nexecve\npthread_create\n",
"str*\n"
));
let host = NameList::parse("");
for bad in [
"malloc",
"calloc",
"free",
"open",
"socket",
"mmap",
"dlopen",
"fork",
"execve",
"execvp",
"system",
"pthread_create",
"pthread_mutex_lock",
"signal",
"setjmp",
"longjmp",
"abort",
"exit",
"getenv",
"kill",
"syscall",
"prctl",
] {
let e = E {
undefined: vec![bad],
..E::default()
};
let r = check_module(
&e.build(),
&Policy {
libc_allow: &allow,
host_exports: &host,
cxx: false,
},
);
assert_eq!(r.unwrap_err().code, Code::Symbols, "{bad}");
}
}
/// GNU_UNIQUE (10), the OS range (11-15) and an empty name all take part in
/// binding: each extra export below must be refused (E_SYMBOLS).
#[test]
fn exports_count_every_non_local_binding() {
for (name, bind) in [("helper", 10), ("helper", 11), ("helper", 13), ("", 1)] {
let e = E {
defined_bind: vec![(name, bind)],
..E::default()
};
assert_eq!(code(&e), Code::Symbols, "{name:?} bind {bind}");
}
}
/// The import check covers every non-local binding as well. A unique import
/// is still judged by the lists, so an allowed one is admitted (E_SYMBOLS for
/// the rest).
#[test]
fn imports_count_every_non_local_binding() {
let ok = E {
undefined_bind: vec![("strlen", 10)],
..E::default()
};
assert!(run(&ok, false).is_ok());
for (name, bind) in [("cos", 10), ("unknown_fn", 11), ("dlopen", 10), ("", 1)] {
let e = E {
undefined_bind: vec![(name, bind)],
..E::default()
};
assert_eq!(code(&e), Code::Symbols, "{name:?} bind {bind}");
}
}
#[test]
fn name_list_parsing() {
let l = NameList::parse("# c\n\n str* \nqsort\n");
assert!(l.contains("strlen") && l.contains("qsort"));
assert!(!l.contains("qsor") && !l.contains("mem"));
}
#[test]
fn truncation_and_corruption_never_panic() {
let full = E::default().build();
let allow = NameList::parse(ALLOW);
let host = NameList::parse(EXPORTS);
let p = Policy {
libc_allow: &allow,
host_exports: &host,
cxx: false,
};
for n in 0..full.len() {
let _ = check_module(&full[..n], &p);
}
// Flip every byte to a few hostile values.
for i in 0..full.len() {
for v in [0u8, 0xff, 0x7f] {
let mut b = full.clone();
b[i] = v;
let _ = check_module(&b, &p);
}
}
}
// ---- info block ----
fn expect() -> Expect<'static> {
Expect {
abi_major: 1,
abi_minor: 1,
app_id: "mining",
app_build: 7,
lvgl_version: "9.6.0",
sdk_hash: [9; 32],
}
}
#[test]
fn info_matching_is_ok() {
let i = Info::parse(&info_bytes("mining", 7, 0, "9.6.0", 9, 1, 0)).unwrap();
assert_eq!(check_info(&i, &expect()).unwrap(), Compat::Ok);
}
#[test]
fn info_id_or_build_mismatch_is_refused() {
let i = Info::parse(&info_bytes("other", 7, 0, "9.6.0", 9, 1, 0)).unwrap();
assert_eq!(check_info(&i, &expect()).unwrap_err().code, Code::Platform);
let i = Info::parse(&info_bytes("mining", 8, 0, "9.6.0", 9, 1, 0)).unwrap();
assert_eq!(check_info(&i, &expect()).unwrap_err().code, Code::Platform);
}
#[test]
fn abi_matrix() {
// Modules built for minor 0 load on hosts at minor 0 and 1 (13.3.2). A
// newer minor needs a firmware update (NeedsPlatform, 13.3.6).
for (major, minor, ok) in [(1, 0, true), (1, 1, true), (1, 2, false)] {
let i = Info::parse(&info_bytes("mining", 7, 0, "9.6.0", 9, major, minor)).unwrap();
let r = check_info(&i, &expect()).unwrap();
assert_eq!(r == Compat::Ok, ok, "{major}.{minor}");
}
// Another major is refused at install (13.3.5, 13.3.10).
for major in [0u16, 2] {
let i = Info::parse(&info_bytes("mining", 7, 0, "9.6.0", 9, major, 0)).unwrap();
assert_eq!(check_info(&i, &expect()).unwrap_err().code, Code::Platform);
}
}
#[test]
fn lvgl_direct_needs_exact_lvgl_and_hash() {
let direct = Info::parse(&info_bytes("mining", 7, F_LVGL_DIRECT, "9.6.0", 9, 1, 0)).unwrap();
assert_eq!(check_info(&direct, &expect()).unwrap(), Compat::Ok);
let wrong_hash =
Info::parse(&info_bytes("mining", 7, F_LVGL_DIRECT, "9.6.0", 3, 1, 0)).unwrap();
assert!(matches!(
check_info(&wrong_hash, &expect()).unwrap(),
Compat::NeedsPlatform(_)
));
let wrong_ver = Info::parse(&info_bytes("mining", 7, F_LVGL_DIRECT, "9.5.0", 9, 1, 0)).unwrap();
assert!(matches!(
check_info(&wrong_ver, &expect()).unwrap(),
Compat::NeedsPlatform(_)
));
// Layer 1 modules ignore the LVGL fields.
let layer1 = Info::parse(&info_bytes("mining", 7, 0, "1.0.0", 3, 1, 0)).unwrap();
assert_eq!(check_info(&layer1, &expect()).unwrap(), Compat::Ok);
}
#[test]
fn info_parse_refusals() {
assert!(Info::parse(&[0; 10]).is_err());
let mut b = info_bytes("mining", 7, 0, "9.6.0", 9, 1, 0);
b[8..40].fill(b'a'); // no terminator
assert!(Info::parse(&b).is_err());
let mut b = info_bytes("mining", 7, 0, "9.6.0", 9, 1, 0);
b[0..4].copy_from_slice(&4u32.to_le_bytes());
assert!(Info::parse(&b).is_err());
}
#[test]
fn grants() {
let plain = Info::parse(&info_bytes("mining", 7, 0, "9.6.0", 9, 1, 0)).unwrap();
let direct = Info::parse(&info_bytes("mining", 7, F_LVGL_DIRECT, "9.6.0", 9, 1, 0)).unwrap();
assert!(check_grants(&plain, &["ui.native"], &[]).is_ok());
assert_eq!(
check_grants(&plain, &[], &[]).unwrap_err().code,
Code::Grant
);
assert_eq!(
check_grants(&direct, &["ui.native"], &[]).unwrap_err().code,
Code::Grant
);
assert!(check_grants(&direct, &["ui.native", "ui.lvgl_direct"], &[]).is_ok());
assert_eq!(
check_grants(&plain, &["ui.native"], &["reboot"])
.unwrap_err()
.code,
Code::Grant
);
assert!(check_grants(&plain, &["ui.native", "platform.reboot"], &["reboot"]).is_ok());
}
@@ -0,0 +1,23 @@
[package]
name = "flare-plugin-host"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
description = "wasmi host for FLARE-side plugins (built by the flare repo only)"
publish = false
[dependencies]
flare-plugin-abi = { path = "../flare-plugin-abi" }
sha2 = "0.10"
# portable-dispatch is required: the tail-call dispatch relies on the optimizer
# for guaranteed tail calls and recurses natively without it (debug builds
# overflow the stack on a plain loop).
wasmi = { version = "=2.0.0", default-features = false, features = ["std", "validate", "portable-dispatch"] }
[dev-dependencies]
wat = "1"
[features]
# Accepts FLARE_PLUGINS=dev. Release images omit it and refuse to start in dev mode.
plugin-dev = ["flare-plugin-abi/plugin-dev"]
+34
View File
@@ -0,0 +1,34 @@
# flare-plugin-host
wasmi host for FLARE plugins (d04 13.4). Built by the flare repo only; the
panel never links it.
| Module | Role |
|---|---|
| `runtime` | `Runtime` trait, `WasmiRuntime`, limits, faults, `HostOps` |
| `load` | fail-closed load gate: mode, key class, hash, admission |
| `breaker` | 5 faults in 60 s open for 10 min, doubling to 1 h |
| `gate` | in-flight caps: 4 per plugin, 32 per portal |
## Limits per call
- Fresh store and instance each call; fuel from the manifest (default 50 M).
- Memory, one instance, one table, one memory; growth past the limit returns -1.
- Guest call depth 250.
- At most 64 `fp1.call` and 32 log lines (512 bytes each) per call.
- Messages and replies at most 1 MiB.
- Deadline checked on each host call and on return; the async caller adds its
own timeout for time blocked inside a host op.
## Build notes
- wasmi is built with `portable-dispatch`. Its default tail-call dispatch
recurses on the native stack when the optimizer does not guarantee tail
calls, so a debug build overflows on any long loop.
- `plugin-dev` accepts `FLARE_PLUGINS=dev`. Release images omit it.
## Not here
Signature, key pin, floor and revocation checks are `wapp-core`'s; the caller
passes the result as an `Attestation`. The op implementations (kv, sql, http,
cfg, command, audit) belong to the consumer behind `HostOps`.
@@ -0,0 +1,180 @@
//! Circuit breaker (d04 13.4.4): five traps or timeouts within 60 s set the
//! plugin to `failed` for 10 minutes, doubling to 1 hour. Time is passed in
//! as seconds so the state machine is deterministic.
use flare_plugin_abi::fp1::{
BREAKER_FIRST_HOLD_S, BREAKER_MAX_HOLD_S, BREAKER_TRIPS, BREAKER_WINDOW_S,
};
use std::collections::VecDeque;
/// A state change the caller audits (13.4.4: every transition is audited).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Transition {
/// The breaker opened; calls are refused until `until`.
Tripped { until: u64, hold_s: u64 },
/// The hold elapsed and calls are allowed again.
Recovered,
/// An administrator reopened the plugin early; the hold restarts at 10 min.
AdminRetry,
}
#[derive(Clone, Debug, Default)]
pub struct Breaker {
faults: VecDeque<u64>,
until: Option<u64>,
next_hold_s: u64,
}
impl Breaker {
pub fn new() -> Self {
Breaker {
faults: VecDeque::new(),
until: None,
next_hold_s: BREAKER_FIRST_HOLD_S,
}
}
/// True while the breaker is open at `now`.
pub fn is_failed(&self, now: u64) -> bool {
self.until.is_some_and(|u| now < u)
}
/// Ask whether a call may start at `now`. An elapsed hold closes the
/// breaker and reports [`Transition::Recovered`].
pub fn allow(&mut self, now: u64) -> (bool, Option<Transition>) {
match self.until {
Some(u) if now < u => (false, None),
Some(_) => {
self.until = None;
self.faults.clear();
(true, Some(Transition::Recovered))
}
None => (true, None),
}
}
/// Count a trap, fuel exhaustion, timeout or memory-limit fault.
pub fn record_fault(&mut self, now: u64) -> Option<Transition> {
if self.is_failed(now) {
return None;
}
self.faults.push_back(now);
while self
.faults
.front()
.is_some_and(|t| now.saturating_sub(*t) >= BREAKER_WINDOW_S)
{
self.faults.pop_front();
}
if (self.faults.len() as u32) < BREAKER_TRIPS {
return None;
}
let hold_s = self.next_hold_s;
let until = now + hold_s;
self.until = Some(until);
self.faults.clear();
self.next_hold_s = (hold_s * 2).min(BREAKER_MAX_HOLD_S);
Some(Transition::Tripped { until, hold_s })
}
/// The administrator retries a failed plugin before the hold ends.
pub fn admin_retry(&mut self) -> Option<Transition> {
self.until?;
self.until = None;
self.faults.clear();
self.next_hold_s = BREAKER_FIRST_HOLD_S;
Some(Transition::AdminRetry)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn trip(b: &mut Breaker, at: u64) -> Option<Transition> {
let mut last = None;
for i in 0..BREAKER_TRIPS as u64 {
last = b.record_fault(at + i);
}
last
}
#[test]
fn four_faults_do_not_trip() {
let mut b = Breaker::new();
for t in 0..4 {
assert_eq!(b.record_fault(t), None);
}
assert!(!b.is_failed(5));
}
#[test]
fn five_faults_in_window_trip_for_ten_minutes() {
let mut b = Breaker::new();
let t = trip(&mut b, 100);
assert_eq!(
t,
Some(Transition::Tripped {
until: 104 + 600,
hold_s: 600
})
);
assert!(b.is_failed(500));
assert_eq!(b.allow(500), (false, None));
}
#[test]
fn faults_outside_the_window_do_not_add_up() {
let mut b = Breaker::new();
for k in 0..10u64 {
assert_eq!(b.record_fault(k * 61), None, "fault {k}");
}
assert!(!b.is_failed(700));
}
#[test]
fn hold_doubles_to_the_cap() {
let mut b = Breaker::new();
let mut now = 0;
let mut holds = Vec::new();
for _ in 0..5 {
if let Some(Transition::Tripped { until, hold_s }) = trip(&mut b, now) {
holds.push(hold_s);
now = until;
assert_eq!(b.allow(now), (true, Some(Transition::Recovered)));
}
}
assert_eq!(holds, vec![600, 1200, 2400, 3600, 3600]);
}
#[test]
fn recovery_clears_the_fault_count() {
let mut b = Breaker::new();
let Some(Transition::Tripped { until, .. }) = trip(&mut b, 0) else {
panic!("no trip")
};
assert_eq!(b.allow(until), (true, Some(Transition::Recovered)));
for t in 0..4 {
assert_eq!(b.record_fault(until + t), None);
}
}
#[test]
fn admin_retry_reopens_and_resets_the_hold() {
let mut b = Breaker::new();
trip(&mut b, 0);
assert!(b.is_failed(10));
assert_eq!(b.admin_retry(), Some(Transition::AdminRetry));
assert!(!b.is_failed(10));
assert_eq!(b.admin_retry(), None);
let t = trip(&mut b, 20);
assert!(matches!(t, Some(Transition::Tripped { hold_s: 600, .. })));
}
#[test]
fn faults_while_failed_are_not_counted() {
let mut b = Breaker::new();
trip(&mut b, 0);
assert_eq!(b.record_fault(10), None);
}
}

Some files were not shown because too many files have changed in this diff Show More