Compare commits

...
Author SHA1 Message Date
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 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 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 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
3478 changed files with 1262085 additions and 118 deletions
+5
View File
@@ -0,0 +1,5 @@
[source.crates-io]
replace-with = "vendored-sources"
[source.vendored-sources]
directory = "vendor"
+36
View File
@@ -0,0 +1,36 @@
name: public-benchmark-pages
on:
schedule:
- cron: '*/15 * * * *'
workflow_dispatch:
concurrency:
group: alkane-os-public-benchmark-pages
cancel-in-progress: false
jobs:
publish:
runs-on: alkane-verify
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:9d2a992bbcb91014af3c85d2e1ec8c5990701cecf83fd06c8d46f9ef13dbd948
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- name: Install SSH client
run: |
apt-get update -qq
apt-get install -y -qq --no-install-recommends openssh-client
- name: Render measured benchmark history
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/bench_history.py render
- name: Publish public benchmark page
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
BENCH_PAGES_DEPLOY_KEY: ${{ secrets.BENCH_PAGES_DEPLOY_KEY }}
run: python3 ci/publish-bench-pages.py os
- name: Clean generated page
if: always()
run: python3 ci/cleanup-generated.py
+23
View File
@@ -0,0 +1,23 @@
name: completed-ci-badge
on:
schedule:
- cron: '*/15 * * * *'
workflow_dispatch:
concurrency:
group: alkane-os-completed-ci-badge
cancel-in-progress: false
jobs:
publish:
runs-on: alkane-ci
permissions:
actions: read
contents: write
steps:
- uses: actions/checkout@v4
- name: Publish last completed attempts
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/last-attempt-badge.py
+66 -4
View File
@@ -4,19 +4,55 @@ on:
push:
branches: [main]
concurrency:
group: alkane-os-main
cancel-in-progress: false
jobs:
verify-and-release:
runs-on: alkane-ci
env:
CARGO_TARGET_DIR: target
permissions:
contents: write
actions: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Pages SSH client
run: |
apt-get update -qq
apt-get install -y -qq --no-install-recommends openssh-client
- name: Install Rust quality tools
run: rustup component add rustfmt clippy
- name: Image safety gate
run: sh ci/check-image-safety.sh
- name: Formatting
run: cargo fmt --check
- name: Last-attempt badge checks
run: python3 ci/test-last-attempt-badge.py
- name: Benchmark history checks
run: python3 ci/test-bench-history.py
- name: Metric badge checks
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
run: cargo clippy --all-targets --locked -- -D warnings
run: |
cargo clippy --all-targets --locked -- -D warnings
printf '{"format":true,"clippy_warnings_denied":true}\n' > quality-current.json
- name: Build
run: cargo build --release --locked
- name: Unit and workflow tests
@@ -26,7 +62,7 @@ jobs:
- name: Microbenchmarks
run: |
set -o pipefail
cargo test --release --locked -- --ignored --nocapture | tee bench-current.txt
cargo test --release --locked -- --ignored --nocapture --test-threads=1 | tee bench-current.txt
- name: Coverage tool
run: |
rustup component add llvm-tools-preview
@@ -42,19 +78,42 @@ jobs:
run: |
CARGO_TARGET_DIR=target/coverage-bench cargo llvm-cov --json \
--output-path coverage/bench.json --locked -- --ignored
- name: Load previous main benchmark measurement
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/bench_history.py prepare
- name: Generate measured badges
run: |
python3 ci/metrics.py --tests-output tests-current.txt \
--tests-coverage coverage/tests.json --bench-output bench-current.txt \
--bench-coverage coverage/bench.json
- uses: actions/upload-artifact@v4
--bench-coverage coverage/bench.json --quality-gate quality-current.json
- uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
with:
name: alkane-os-metrics
path: |
badges/metrics.json
quality-current.json
coverage/tests.json
coverage/bench.json
bench-current.txt
- name: Publish measured badges privately
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/publish-metrics.py
- name: Record private benchmark history
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/bench_history.py publish
- uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
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
@@ -72,3 +131,6 @@ jobs:
env:
GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: python3 ci/release.py "${{ steps.version.outputs.tag }}" false "dist/alkane-os-${{ steps.version.outputs.version }}-source.tar.gz" dist/alkane-os dist/bench-current.txt
- name: Clean generated build and benchmark work
if: always()
run: python3 ci/cleanup-generated.py
+11 -2
View File
@@ -6,13 +6,19 @@ on:
jobs:
build:
runs-on: alkane-ci
runs-on: alkane-verify
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:9d2a992bbcb91014af3c85d2e1ec8c5990701cecf83fd06c8d46f9ef13dbd948
env:
CARGO_TARGET_DIR: target
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Image safety gate
run: sh ci/check-image-safety.sh
- 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"
@@ -27,3 +33,6 @@ jobs:
env:
GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: python3 ci/release.py "${{ steps.version.outputs.tag }}" true "dist/alkane-os-${{ steps.version.outputs.version }}-source.tar.gz" dist/alkane-os
- name: Clean generated candidate build
if: always()
run: python3 ci/cleanup-generated.py
+57
View File
@@ -0,0 +1,57 @@
name: source-pr
on:
pull_request:
branches: [next, main]
workflow_dispatch:
concurrency:
group: alkane-os-source-pr-${{ github.ref }}
cancel-in-progress: true
jobs:
source:
runs-on: alkane-fast
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:9d2a992bbcb91014af3c85d2e1ec8c5990701cecf83fd06c8d46f9ef13dbd948
env:
CARGO_TARGET_DIR: target
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Detect changed surface
id: surface
run: python3 ci/pr_surface.py >> "$GITHUB_OUTPUT"
- name: Check patch whitespace
run: |
if [ "${GITHUB_EVENT_NAME:-}" = pull_request ]; then
base="$(git merge-base HEAD "origin/$GITHUB_BASE_REF")"
git diff --check "$base" HEAD
else
git diff --check HEAD^ HEAD
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: Install source formatter
if: steps.surface.outputs.surface == 'rust'
run: rustup component add rustfmt
- name: Check source formatting
if: steps.surface.outputs.surface == 'rust'
run: cargo fmt --check
- name: Check changed Rust source
if: steps.surface.outputs.surface == 'rust'
run: |
if [ "${GITHUB_BASE_REF:-}" = main ]; then
cargo build --release --offline --locked
else
cargo check --offline --locked
fi
- name: Clean generated build
if: always()
run: python3 ci/cleanup-generated.py
+7
View File
@@ -0,0 +1,7 @@
# Alkane OS working rules
- Keep the project MIT-licensed and preserve third-party licenses in vendored dependencies.
- Use run-scoped Cargo output for one-off work. In CI, set `CARGO_TARGET_DIR=target` and remove generated target, coverage, benchmark, and release staging after artifact publication, including failed runs.
- Keep the main release gate on all seven boards, all 64 same-vendor pairings, unmodified stock firmware evidence, and genuine pool acceptance from real captured silicon nonces. Do not promote host-only probes to board conformance.
- Keep mining, tuning, HAL, API, protocol parsing, and on-device runtime logic in Rust. Use Python only for host tests, CI, release work, and disposable diagnostics unless a documented interface requires it.
- No emojis in files or persisted text.
Generated
+541
View File
@@ -2,6 +2,547 @@
# 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]]
name = "itoa"
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"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
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"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
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"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
dependencies = [
"serde_core",
"serde_derive",
]
[[package]]
name = "serde_core"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
dependencies = [
"serde_derive",
]
[[package]]
name = "serde_derive"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.9",
]
[[package]]
name = "serde_json"
version = "1.0.154"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
dependencies = [
"itoa",
"memchr",
"serde",
"serde_core",
"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"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
dependencies = [
"proc-macro2",
"quote",
"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"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
+15 -1
View File
@@ -8,7 +8,21 @@ description = "Portable mining and tuning core for Alkane control boards"
[lib]
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
codegen-units = 1
+50 -36
View File
@@ -1,51 +1,65 @@
# Alkane OS
[![CI](https://gitea.bluefla.re/blueflare/alkane-os/actions/workflows/main.yml/badge.svg?branch=main)](https://gitea.bluefla.re/blueflare/alkane-os/actions)
![tests](badges/tests.svg)
![coverage](badges/coverage.svg)
![bench](badges/bench.svg)
![bench coverage](badges/bench-coverage.svg)
![lines of code](badges/loc.svg)
![dependencies](badges/dependencies.svg)
![code quality](badges/quality.svg)
![license](badges/license.svg)
[![CI](https://gitea.bluefla.re/blueflare/alkane-os/raw/branch/ci-badges/main.svg)](https://gitea.bluefla.re/blueflare/alkane-os/actions)
![tests](https://gitea.bluefla.re/blueflare/alkane-os/raw/branch/ci-badges/badges/tests.svg)
![coverage](https://gitea.bluefla.re/blueflare/alkane-os/raw/branch/ci-badges/badges/coverage.svg)
![bench](https://gitea.bluefla.re/blueflare/alkane-os/raw/branch/ci-badges/badges/bench.svg)
![bench coverage](https://gitea.bluefla.re/blueflare/alkane-os/raw/branch/ci-badges/badges/bench-coverage.svg)
![lines of code](https://gitea.bluefla.re/blueflare/alkane-os/raw/branch/ci-badges/badges/loc.svg)
![dependencies](https://gitea.bluefla.re/blueflare/alkane-os/raw/branch/ci-badges/badges/dependencies.svg)
![code quality](https://gitea.bluefla.re/blueflare/alkane-os/raw/branch/ci-badges/badges/quality.svg)
![license](https://gitea.bluefla.re/blueflare/alkane-os/raw/branch/ci-badges/badges/license.svg)
Portable mining, tuning, and management logic for Alkane control boards. The
source is MIT licensed. `alkane-sdk` owns the board images and supplies the
hardware backend at build time. This repository has no on-board web frontend;
the intended management surfaces are SSH, cgminer-compatible port 4028, and a
minimal API.
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.
## Status
This is the initial interface and release tooling. It does not mine yet. A
target in the matrix is an obligation to implement and validate, not a claim
of support. All 64 theoretical same-vendor controller/chip pairings are in
scope: 52 Bitmain and 12 WhatsMiner. For pairings a stock image rejects, the
simulator must record the first genuine rejection gate and Alkane OS must mine.
No live board is required by CI. Bench devices supply captures and independent
validation of the simulator.
The host miner supports BM1362 and BM1366 through the SDK's simulator HAL and
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 current executable lists target obligations (`alkane-os --list-targets`)
and its version. It does not start a miner or a network service.
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 `main` branch has full tests and a conformance gate; releases are created
only after every required cell passes. `next` runs a build check and produces
release candidates. `ci/version-x.txt` is the manually edited major version.
For this repository, Y changes when the mining protocol, HAL contract, tuning
policy or API changes; Z changes for compatible fixes and packaging updates.
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
Litecoin Scrypt proof verification are implemented; Scrypt chip report
handling and mining remain open.
Run `alkane-os --list-targets` for the target matrix. Set `POOL_PASSWORD` to
the pool password, then mine with a simulator HAL socket and Stratum V1 pool:
```sh
ALKANE_POOL_PASSWORD="$POOL_PASSWORD" alkane-os --mine-simulator HAL_SOCKET POOL_ADDRESS WORKER BM1366
```
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.
## Release gate
`main` runs tests, benchmarks, and conformance before release; `next` builds
release candidates. The release gate is red. It requires all 64 same-vendor
pairings (52 Bitmain, 12 WhatsMiner), unmodified stock firmware, captured
silicon nonces, difficulty-1 pool acceptance, and bench-validated models.
Stock firmware may faithfully reject a pairing; Alkane OS must mine it.
See the [evidence contract](ci/CONFORMANCE.md).
Badges cover host code, not board conformance. See the public
[benchmark history](https://blueflare.gitea.bluefla.re/alkane-benchmarks/os/).
## Local checks
```sh
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
python3 ci/check-conformance.py
CARGO_TARGET_DIR=/var/tmp/alkane-os-target cargo test --locked
```
The last command currently fails because simulator and device evidence are
still pending. It is a release gate, not a unit test.
Use an executable target directory if the source mount is `noexec`.
The badges record measured host-side checks for this initial core. They do
not imply that any board image or mining target has passed conformance.
## License
[MIT](LICENSE). Vendored dependencies keep their own licenses.
+63
View File
@@ -0,0 +1,63 @@
# Release conformance evidence
`check-conformance.py` is a release gate for all 64 same-vendor cells. It
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
current workflow. It records `stock_firmware_modified: false`,
`simulator_booted_stock: true`, and a `stock_result` of `mines` or `rejects`.
For a rejection, `stock_first_rejection` names the first genuine firmware
gate. Reports for stock mining also reference `stock_pool_accept_capture`.
The report references files under `ci/evidence/` with objects containing
`path` and `sha256`: `sdk_image`, `stock_image`, `simulator_trace`,
`simulator_model`, `control_capture`, `chip_capture`,
`alkane_share_accept_capture`, and `bench_validation`.
The checker opens and hashes each file. It loads the trace and capture JSON,
checks the current run/image/cell identities, verifies SHA-256d or Litecoin
Scrypt nonces against
a pool target at difficulty 1 or higher, and requires a matching
`mining.submit` and pool ACCEPT response ID. A SHA-256 capture must include
the matching `subscription` (`extranonce1`, `extranonce2_size`), full
`notify` message, exact decimal `difficulty`, and a `configure_response`
with an accepted BIP310 mask when version bits were submitted. A later
`version_mask_event` may supply the effective `mining.set_version_mask`.
The checker reconstructs
the coinbase, merkle root, and complete submitted header; its 80 bytes and
calculated difficulty target must match the capture. The trace binds
the capture digests.
The Scrypt verifier uses [Litecoin's 80-byte, N=1024, r=1, p=1 proof hash](https://github.com/litecoin-project/litecoin/blob/master/src/crypto/scrypt.cpp).
Equihash proof verification remains pending, so its cells fail closed.
Scrypt cells also remain pending until real silicon reports, stock behavior,
and pool acceptance are captured for those chips.
Bench calibration names the physical control-board and chip devices, their
capture digests, and the simulator model digest. It can be reused across OS
commits until the model or a physical capture changes.
The fixed digests and artifact paths also appear in `conformance.json` so
source review can track what each cell claims.
The simulator runner must generate these reports by booting pristine stock
firmware and Alkane OS in a machine model, with nonce data replayed from
real-silicon captures. A rejected stock pairing must show its first rejection
in the simulator trace while Alkane OS reaches pool ACCEPT. Bench devices
provide independent observations for model validation, not CI dependencies.
The checker verifies its input artifacts and reported nonce. It cannot prove
that a self-asserted pool response came from a real pool or turn a report into
physical evidence. The capture producer must preserve raw request/response
bytes and independent provenance. Capture provenance and faithful machine
models remain release blockers until the runner and bench validation are built.
+54
View File
@@ -0,0 +1,54 @@
# SPDX-License-Identifier: MIT
"""Write small badge artifacts to the private Gitea CI badge branch."""
import base64
import json
from urllib.error import HTTPError
from urllib.parse import quote
from urllib.request import Request, urlopen
BADGE_BRANCH = "ci-badges"
def request_json(url: str, token: str, method: str = "GET",
payload: dict | None = None) -> dict:
body = None if payload is None else json.dumps(payload).encode()
request = Request(url, data=body, method=method,
headers={"Authorization": f"token {token}",
"Content-Type": "application/json"})
with urlopen(request, timeout=20) as response:
return json.load(response)
def publish_file(api: str, repo: str, filename: str, data: bytes,
token: str, message: str, max_bytes: int = 65_536) -> None:
if not filename or filename.startswith("/") or any(
part in ("", ".", "..") for part in filename.split("/")):
raise ValueError("invalid badge path")
if len(data) > max_bytes:
raise ValueError("artifact exceeds size limit")
path = f"{api}/repos/{repo}/contents/{quote(filename, safe='/')}"
encoded = base64.b64encode(data).decode("ascii")
for attempt in range(3):
try:
current = request_json(path + "?ref=" + BADGE_BRANCH, token)
if base64.b64decode(current["content"]) == data:
return
sha = current["sha"]
method = "PUT"
except HTTPError as error:
if error.code != 404:
raise
sha = None
method = "POST"
payload = {"branch": BADGE_BRANCH, "content": encoded,
"message": message + " [skip ci]"}
if sha is not None:
payload["sha"] = sha
try:
request_json(path, token, method, payload)
return
except HTTPError as error:
if error.code not in (409, 422) or attempt == 2:
raise
raise RuntimeError("badge write did not complete")
+159
View File
@@ -0,0 +1,159 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Keep measured main-branch benchmarks in the private CI artifact branch."""
import argparse
import base64
from datetime import datetime, timezone
import html
import json
import math
import os
from pathlib import Path
import re
import subprocess
from urllib.error import HTTPError
from urllib.parse import quote
from badge_store import BADGE_BRANCH, publish_file, request_json
from bench_host import identity as benchmark_host
INDEX = "history/index.json"
MAX_INDEX_ENTRIES = 50
def read_artifact(api: str, repo: str, token: str, filename: str):
url = f"{api}/repos/{repo}/contents/{quote(filename, safe='/')}?ref={BADGE_BRANCH}"
try:
value = request_json(url, token)
except HTTPError as error:
if error.code == 404:
return None
raise
return json.loads(base64.b64decode(value["content"]))
def valid_benches(metrics: dict) -> dict[str, float]:
values = metrics.get("bench_ns_per_op")
if not isinstance(values, dict) or not values:
raise ValueError("benchmark measurements are missing")
if any(not isinstance(key, str) or not re.fullmatch(r"[A-Za-z0-9_]+", key)
or not isinstance(value, (float, int)) or isinstance(value, bool)
or not math.isfinite(value) or value <= 0 for key, value in values.items()):
raise ValueError("benchmark measurements are invalid")
return values
def git_distance(ancestor: str, sha: str) -> int | None:
result = subprocess.run(("git", "rev-list", "--count", f"{ancestor}..{sha}"),
capture_output=True, text=True, check=False)
if result.returncode != 0:
return None
ancestor_check = subprocess.run(("git", "merge-base", "--is-ancestor", ancestor, sha),
capture_output=True, check=False)
return int(result.stdout.strip()) if ancestor_check.returncode == 0 else None
def previous_measurement(index: dict, sha: str, distance=None, host=None) -> dict:
distance = distance or git_distance
choices = []
for entry in index.get("entries", []):
ancestor = entry.get("sha")
if ancestor == sha or not isinstance(ancestor, str):
continue
if host is not None and entry.get("metrics", {}).get("bench_host") != host:
continue
gap = distance(ancestor, sha)
if gap is not None and gap > 0:
choices.append((gap, entry))
if not choices:
return {}
return valid_benches(min(choices, key=lambda item: item[0])[1]["metrics"])
def updated_index(index: dict, sha: str, metrics: dict, timestamp: str) -> dict:
if not re.fullmatch(r"[0-9a-f]{40}", sha):
raise ValueError("invalid commit SHA")
valid_benches(metrics)
entries = [entry for entry in index.get("entries", []) if entry.get("sha") != sha]
entries.append({"sha": sha, "timestamp": timestamp, "metrics": metrics})
return {"schema": 1, "entries": entries[-MAX_INDEX_ENTRIES:]}
def render_html(index: dict) -> str:
entries = list(reversed(index.get("entries", [])))
names = sorted({name for entry in entries
for name in valid_benches(entry["metrics"])})
rows = []
for entry in entries:
sha = entry["sha"]
if not re.fullmatch(r"[0-9a-f]{40}", sha):
raise ValueError("invalid commit SHA in history")
cells = [f'<td><a href="https://gitea.bluefla.re/blueflare/alkane-os/commit/{sha}">{sha[:10]}</a></td>',
f'<td>{html.escape(entry["timestamp"])}</td>']
values = valid_benches(entry["metrics"])
host = entry["metrics"].get("bench_host", {})
host_label = host.get("cpu_model", "unknown") if isinstance(host, dict) else "unknown"
cells.append(f'<td>{html.escape(str(host_label))}</td>')
cells += [f'<td>{values[name]:.3f}</td>' if name in values else '<td>new</td>'
for name in names]
rows.append("<tr>" + "".join(cells) + "</tr>")
headings = "".join(f"<th scope=\"col\">{html.escape(name)} (ns/op)</th>" for name in names)
return ("<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\">"
"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">"
"<title>Alkane OS benchmarks</title><style>"
"body{font:16px system-ui,sans-serif;max-width:1100px;margin:2rem auto;padding:0 1rem;color:#17212b}"
"h1{font-size:2rem}p{max-width:70ch;line-height:1.5}"
"table{border-collapse:collapse;min-width:100%}th,td{padding:.5rem;border-bottom:1px solid #ccd3da;text-align:right}"
"th:first-child,td:first-child{text-align:left}th:nth-child(2),td:nth-child(2){text-align:left}"
"th{background:#edf2f6;position:sticky;top:0}a{color:#145a9a}"
".scroll{overflow-x:auto}small{color:#55616d}</style></head><body>"
"<h1>Alkane OS microbenchmarks</h1>"
"<p>Measured on main CI. Lower ns/op is faster. Results depend on runner load and are "
"not board performance. A new benchmark has no earlier comparison.</p>"
f"<p><small>Most recent {len(entries)} measured commits. Full per-commit JSON is retained "
"in the private ci-badges branch.</small></p>"
f"<div class=\"scroll\"><table><thead><tr><th scope=\"col\">Commit</th>"
f"<th scope=\"col\">UTC</th><th scope=\"col\">CPU</th>{headings}</tr></thead><tbody>{''.join(rows)}"
"</tbody></table></div></body></html>\n")
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument("action", choices=("prepare", "publish", "render"))
args = parser.parse_args()
api = os.environ["GITHUB_API_URL"].rstrip("/")
repo = os.environ["GITHUB_REPOSITORY"]
token = os.environ["GITEA_TOKEN"]
sha = os.environ["GITHUB_SHA"]
index = read_artifact(api, repo, token, INDEX) or {"schema": 1, "entries": []}
if index.get("schema") != 1 or not isinstance(index.get("entries"), list):
raise ValueError("unsupported benchmark history index")
if args.action == "prepare":
baseline = previous_measurement(index, sha, host=benchmark_host())
Path("badges").mkdir(exist_ok=True)
Path("badges/bench-baseline.json").write_text(json.dumps(baseline) + "\n")
print(f"Loaded {len(baseline)} prior benchmark measurements")
return
if args.action == "render":
if not index["entries"]:
raise ValueError("no measured benchmark history to publish")
Path("bench-site").mkdir(exist_ok=True)
Path("bench-site/index.html").write_text(render_html(index))
print(f"Rendered {len(index['entries'])} measured benchmark commits")
return
metrics = json.loads(Path("badges/metrics.json").read_text())
timestamp = datetime.now(timezone.utc).isoformat(timespec="seconds")
index = updated_index(index, sha, metrics, timestamp)
record = json.dumps(index["entries"][-1], indent=2).encode() + b"\n"
publish_file(api, repo, f"history/{sha}.json", record, token,
"Record Alkane OS benchmarks", max_bytes=1_048_576)
publish_file(api, repo, INDEX, json.dumps(index, indent=2).encode() + b"\n",
token, "Update Alkane OS benchmark index", max_bytes=1_048_576)
Path("bench-site").mkdir(exist_ok=True)
Path("bench-site/index.html").write_text(render_html(index))
print(f"Recorded benchmarks for {sha[:10]}")
if __name__ == "__main__":
main()
+19
View File
@@ -0,0 +1,19 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Identify the CPU class used for comparable CI microbenchmark baselines."""
import os
import platform
from pathlib import Path
def identity() -> dict[str, object]:
model = "unknown"
cpuinfo = Path("/proc/cpuinfo")
if cpuinfo.is_file():
for line in cpuinfo.read_text(errors="replace").splitlines():
if line.startswith(("model name\t", "Hardware\t", "Processor\t")):
model = line.partition(":")[2].strip()[:160]
break
return {"architecture": platform.machine(), "cpu_model": model,
"logical_cpus": os.cpu_count() or 1}
+394 -26
View File
@@ -1,33 +1,401 @@
#!/usr/bin/env python3
"""Fail the final release gate until every target has traceable evidence."""
# SPDX-License-Identifier: MIT
"""Require the binary target matrix and traceable per-cell release evidence."""
import argparse
from decimal import Decimal, InvalidOperation
import hashlib
import json
import os
import pathlib
import re
import subprocess
import sys
manifest = json.loads(pathlib.Path("ci/conformance.json").read_text())
rows = manifest["targets"]
expected = {(board, chip) for board in manifest["boards"] for chip in manifest["chips"]
if manifest["vendors"][board] == manifest["vendors"][chip]}
actual = {(row["board"], row["chip"]) for row in rows}
if actual != expected or len(rows) != len(expected):
sys.exit(f"matrix mismatch: {len(actual)} present, {len(expected)} expected")
required = ("sdk_image_sha256", "stock_image_sha256", "stock_result",
"alkane_share_accept_capture", "simulator_trace_sha256",
"bench_validation")
incomplete = []
for row in rows:
missing = [field for field in required if not row.get(field)]
if row.get("stock_result") not in (None, "mines", "rejects"):
missing.append("stock_result invalid")
if row.get("stock_result") == "rejects" and not row.get("stock_first_rejection"):
missing.append("stock_first_rejection")
if missing:
incomplete.append((row["board"], row["chip"], missing))
if incomplete:
print(f"Conformance pending: {len(incomplete)}/{len(rows)} targets")
for board, chip, missing in incomplete[:8]:
print(f" {board} x {chip}: {', '.join(missing)}")
sys.exit(1)
print(f"Conformance complete: {len(rows)} targets")
REQUIRED_BOARDS = {
"am335x-bb": "bitmain",
"zynq-7010": "bitmain",
"cv1835": "bitmain",
"a113d": "bitmain",
"allwinner-h3": "whatsminer",
"allwinner-h6": "whatsminer",
"allwinner-h616": "whatsminer",
}
REQUIRED_CHIPS = {
**{chip: "bitmain" for chip in (
"BM1384", "BM1387", "BM1360", "BM1362", "BM1366", "BM1368",
"BM1370", "BM1396", "BM1397", "BM1398", "BM1489", "BM1491", "BM1746",
)},
**{chip: "whatsminer" for chip in (
"KF1950", "ID-1968", "ID-1980", "ID-1990",
)},
}
REQUIRED_ALGORITHMS = {
**{chip: "Sha256" for chip in REQUIRED_CHIPS if chip not in
("BM1489", "BM1491", "BM1746")},
"BM1489": "Scrypt", "BM1491": "Scrypt", "BM1746": "Equihash",
}
DIGEST = re.compile(r"[0-9a-f]{64}\Z")
COMMIT = re.compile(r"[0-9a-f]{40}\Z")
DIFF_ONE_TARGET = 0xffff << (8 * (0x1d - 3))
MAX_REPORT_BYTES = 1_048_576
def sha256_file(path: pathlib.Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as source:
for chunk in iter(lambda: source.read(1_048_576), b""):
digest.update(chunk)
return digest.hexdigest()
def load_report(path: pathlib.Path) -> dict:
if path.stat().st_size > MAX_REPORT_BYTES:
raise ValueError("evidence report exceeds 1 MiB")
value = json.loads(path.read_text())
if not isinstance(value, dict):
raise ValueError("evidence report is not an object")
return value
def artifact(root: pathlib.Path, value: object) -> pathlib.Path:
if not isinstance(value, dict) or not isinstance(value.get("path"), str):
raise ValueError("artifact reference is missing")
digest = value.get("sha256")
if not isinstance(digest, str) or not DIGEST.fullmatch(digest):
raise ValueError("artifact digest is invalid")
path = (root / value["path"]).resolve()
if not path.is_relative_to(root.resolve()) or not path.is_file():
raise ValueError("artifact is missing or outside evidence directory")
if sha256_file(path) != digest:
raise ValueError("artifact digest mismatch")
return path
def hex_field(value: object, size: int | None = None) -> bytes:
if (not isinstance(value, str) or len(value) & 1
or len(value) > 131_072 or not re.fullmatch(r"[0-9a-fA-F]*", value)
or (size is not None and len(value) != size * 2)):
raise ValueError("invalid Stratum hex field")
return bytes.fromhex(value)
def u32_hex(value: object) -> int:
return int.from_bytes(hex_field(value, 4), "big")
def reconstructed_header(capture: dict, params: list[str]) -> tuple[bytes, int]:
subscription = capture.get("subscription")
notify = capture.get("notify")
if not isinstance(subscription, dict) or not isinstance(notify, dict):
raise ValueError("subscription and notify are required to bind the share")
extra1 = hex_field(subscription.get("extranonce1"))
extra_size = subscription.get("extranonce2_size")
if (len(extra1) > 32 or type(extra_size) is not int
or not 0 <= extra_size <= 32):
raise ValueError("invalid subscription extranonce")
extra2 = hex_field(params[2], extra_size)
job = notify.get("params")
if (notify.get("method") != "mining.notify" or not isinstance(job, list)
or len(job) != 9 or job[0] != params[1]
or not isinstance(job[4], list) or len(job[4]) > 64
or type(job[8]) is not bool):
raise ValueError("submission is not bound to a matching notify")
prevhash = hex_field(job[1], 32)
coinbase = hex_field(job[2]) + extra1 + extra2 + hex_field(job[3])
if len(coinbase) > 65_536:
raise ValueError("coinbase exceeds supported size")
root = hashlib.sha256(hashlib.sha256(coinbase).digest()).digest()
for branch in job[4]:
pair = root + hex_field(branch, 32)
root = hashlib.sha256(hashlib.sha256(pair).digest()).digest()
base_version = u32_hex(job[5])
nbits = u32_hex(job[6])
u32_hex(job[7])
submitted_ntime = u32_hex(params[3])
submitted_nonce = u32_hex(params[4])
if len(params) == 6:
configure = capture.get("configure_response")
result = configure.get("result") if isinstance(configure, dict) else None
if not isinstance(result, dict) or result.get("version-rolling") is not True:
raise ValueError("version rolling was not negotiated")
mask_text = result.get("version-rolling.mask")
mask_event = capture.get("version_mask_event")
if mask_event is not None:
fields = mask_event.get("params") if isinstance(mask_event, dict) else None
if (not isinstance(mask_event, dict)
or mask_event.get("method") != "mining.set_version_mask"
or not isinstance(fields, list) or len(fields) != 1):
raise ValueError("invalid effective version mask event")
mask_text = fields[0]
mask = u32_hex(mask_text)
bits = u32_hex(params[5])
if bits & ~mask:
raise ValueError("submitted version bits exceed negotiated mask")
version = (base_version & ~mask) | bits
else:
if capture.get("configure_response") is not None or capture.get("version_mask_event") is not None:
raise ValueError("negotiated version mask requires submission bits")
version = base_version
header = bytearray()
header.extend(version.to_bytes(4, "little"))
for offset in range(0, 32, 4):
header.extend(prevhash[offset:offset + 4][::-1])
header.extend(root)
header.extend(submitted_ntime.to_bytes(4, "little"))
header.extend(nbits.to_bytes(4, "little"))
header.extend(submitted_nonce.to_bytes(4, "little"))
return bytes(header), submitted_nonce
def proof_digest(header: bytes, algorithm: str) -> bytes:
if algorithm == "Sha256":
return hashlib.sha256(hashlib.sha256(header).digest()).digest()
if algorithm == "Scrypt":
return hashlib.scrypt(header, salt=header, n=1024, r=1, p=1, dklen=32)
raise ValueError(f"{algorithm} share verifier is not implemented")
def verify_accept(capture: dict, algorithm: str) -> None:
if algorithm not in ("Sha256", "Scrypt"):
raise ValueError(f"{algorithm} share verifier is not implemented")
if capture.get("nonce_source") != "real_silicon_capture":
raise ValueError("share was not sourced from captured silicon")
header_hex = capture.get("header80")
target_hex = capture.get("pool_target_le")
nonce = capture.get("nonce")
if (not isinstance(header_hex, str) or len(header_hex) != 160
or not isinstance(target_hex, str) or not DIGEST.fullmatch(target_hex)
or type(nonce) is not int or not 0 <= nonce <= 0xffffffff):
raise ValueError("invalid accepted share work")
try:
header = bytearray.fromhex(header_hex)
except ValueError as error:
raise ValueError("invalid accepted share header") from error
if int.from_bytes(header[76:80], "little") != nonce:
raise ValueError("nonce differs from submitted header")
submission = capture.get("submission")
response = capture.get("pool_response")
params = submission.get("params") if isinstance(submission, dict) else None
if (not isinstance(params, list) or len(params) not in (5, 6)
or not all(isinstance(value, str) for value in params)
or not params[0] or not params[1]
or params[3].lower() != f"{int.from_bytes(header[68:72], 'little'):08x}"
or params[4].lower() != f"{nonce:08x}"
or (len(params) == 6 and not re.fullmatch(r"[0-9a-f]{8}", params[5].lower()))
or not isinstance(response, dict)
or submission.get("method") != "mining.submit"
or type(submission.get("id")) is not int
or response.get("id") != submission["id"]
or response.get("result") is not True
or response.get("error") is not None):
raise ValueError("no matching pool ACCEPT for submitted nonce")
target = int.from_bytes(bytes.fromhex(target_hex), "little")
if not 0 < target <= DIFF_ONE_TARGET:
raise ValueError("pool target is below difficulty one")
difficulty_text = capture.get("difficulty")
if not isinstance(difficulty_text, str) or len(difficulty_text) > 128:
raise ValueError("effective pool difficulty is missing")
try:
difficulty = Decimal(difficulty_text)
except InvalidOperation as error:
raise ValueError("invalid pool difficulty") from error
if not difficulty.is_finite() or difficulty < 1:
raise ValueError("pool difficulty is below one")
if abs(difficulty.as_tuple().exponent) > 64:
raise ValueError("pool difficulty exceeds supported range")
numerator, denominator = difficulty.as_integer_ratio()
expected_target = DIFF_ONE_TARGET * denominator // numerator
if target != expected_target:
raise ValueError("pool target differs from effective difficulty")
rebuilt, submitted_nonce = reconstructed_header(capture, params)
if submitted_nonce != nonce or rebuilt != header:
raise ValueError("submitted Stratum job differs from captured header")
hash_bytes = proof_digest(header, algorithm)
if int.from_bytes(hash_bytes, "little") > target:
raise ValueError("captured nonce misses the pool target")
def verify_cell(row: dict, root: pathlib.Path, run_id: str,
source_commit: str, binary_digest: str,
algorithm: str) -> None:
board, chip = row["board"], row["chip"]
report_path = (root / run_id / board / f"{chip}.json").resolve()
if not report_path.is_relative_to(root.resolve()):
raise ValueError("evidence report is outside evidence directory")
report = load_report(report_path)
identity = {"schema": 1, "run_id": run_id, "source_commit": source_commit,
"os_binary_sha256": binary_digest, "board": board, "chip": chip,
"stock_firmware_modified": False, "algorithm": algorithm}
if any(report.get(key) != value for key, value in identity.items()):
raise ValueError("evidence belongs to a different run, source, binary, or cell")
if report.get("stock_result") != row.get("stock_result"):
raise ValueError("stock result differs from manifest")
if report.get("stock_first_rejection") != row.get("stock_first_rejection"):
raise ValueError("stock rejection differs from manifest")
if report["stock_result"] == "rejects" and not report.get("stock_first_rejection"):
raise ValueError("stock rejection gate is missing")
if report.get("simulator_booted_stock") is not True:
raise ValueError("unmodified stock boot is unverified")
paths = {}
for field, digest_field in (("sdk_image", "sdk_image_sha256"),
("stock_image", "stock_image_sha256"),
("simulator_trace", "simulator_trace_sha256")):
paths[field] = artifact(root, report.get(field))
if report[field]["sha256"] != row.get(digest_field):
raise ValueError(f"{field} digest differs from manifest")
artifact(root, report.get("simulator_model"))
model_digest = report["simulator_model"]["sha256"]
for field in ("control_capture", "chip_capture"):
artifact(root, report.get(field))
trace = load_report(paths["simulator_trace"])
trace_identity = {"run_id": run_id, "source_commit": source_commit,
"board": board, "chip": chip,
"sdk_image_sha256": row["sdk_image_sha256"],
"stock_image_sha256": row["stock_image_sha256"],
"stock_firmware_modified": False,
"stock_result": row["stock_result"],
"algorithm": algorithm,
"simulator_model_sha256": model_digest}
if any(trace.get(key) != value for key, value in trace_identity.items()):
raise ValueError("simulator trace does not bind stock image and current run")
if report["stock_result"] == "rejects":
if trace.get("first_rejection") != row["stock_first_rejection"]:
raise ValueError("stock rejection gate is absent from simulator trace")
else:
stock_capture = load_report(artifact(root, report.get("stock_pool_accept_capture")))
if trace.get("stock_pool_accept_capture_sha256") != report["stock_pool_accept_capture"]["sha256"]:
raise ValueError("stock pool acceptance is not linked to simulator trace")
if (stock_capture.get("board") != board or stock_capture.get("chip") != chip
or stock_capture.get("firmware") != "stock"):
raise ValueError("stock pool acceptance belongs to another firmware or cell")
verify_accept(stock_capture, algorithm)
capture = load_report(artifact(root, report.get("alkane_share_accept_capture")))
if report["alkane_share_accept_capture"]["path"] != row.get("alkane_share_accept_capture"):
raise ValueError("accepted share artifact differs from manifest")
if trace.get("alkane_share_accept_capture_sha256") != report["alkane_share_accept_capture"]["sha256"]:
raise ValueError("Alkane pool acceptance is not linked to simulator trace")
if (capture.get("board") != board or capture.get("chip") != chip
or capture.get("firmware") != "alkane"):
raise ValueError("accepted share belongs to another cell")
verify_accept(capture, algorithm)
bench = load_report(artifact(root, report.get("bench_validation")))
if report["bench_validation"]["path"] != row.get("bench_validation"):
raise ValueError("bench artifact differs from manifest")
if (bench.get("board") != board or bench.get("chip") != chip
or bench.get("validated") is not True
or bench.get("simulator_model_sha256") != model_digest
or any(bench.get(f"{field}_sha256") != report[field]["sha256"]
for field in ("control_capture", "chip_capture"))
or any(not isinstance(bench.get(f"{name}_device_id"), str)
or not bench[f"{name}_device_id"]
for name in ("control", "chip"))):
raise ValueError("bench validation is missing or belongs to another cell")
def binary_targets(path: pathlib.Path) -> dict[tuple[str, str], str]:
output = subprocess.run(
[str(path), "--list-targets"],
check=True, capture_output=True, text=True, timeout=15,
).stdout.splitlines()
if not output or output[0] != "control_board,hash_chip,algorithm":
raise ValueError("Alkane OS binary has no target matrix header")
targets = {}
for line in output[1:]:
parts = line.split(",")
if len(parts) != 3 or not all(parts):
raise ValueError(f"invalid binary target row: {line!r}")
cell = (parts[0], parts[1])
if cell in targets:
raise ValueError("duplicate binary target")
targets[cell] = parts[2]
return targets
def validate(manifest: dict, built_targets: dict[tuple[str, str], str],
evidence_root: pathlib.Path = pathlib.Path("ci/evidence"),
run_id: str = "", source_commit: str = "",
binary_digest: str = "") -> list[str]:
errors = []
if manifest.get("schema") != 1:
errors.append("unsupported conformance manifest schema")
boards = set(manifest["boards"])
chips = set(manifest["chips"])
vendors = manifest["vendors"]
if len(boards) != len(manifest["boards"]) or len(chips) != len(manifest["chips"]):
errors.append("duplicate board or chip in manifest")
for name, vendor in {**REQUIRED_BOARDS, **REQUIRED_CHIPS}.items():
if name not in boards | chips or vendors.get(name) != vendor:
errors.append(f"required target identity changed: {name}")
if set(vendors) != boards | chips:
errors.append("vendor map differs from board and chip lists")
expected = {(board, chip) for board in boards for chip in chips
if vendors.get(board) == vendors.get(chip)}
rows = manifest["targets"]
actual = {(row["board"], row["chip"]) for row in rows}
if len(expected) < 64 or actual != expected or len(rows) != len(expected):
errors.append(f"manifest matrix mismatch: {len(actual)} present, {len(expected)} expected")
if set(built_targets) != expected:
errors.append(f"binary matrix mismatch: {len(built_targets)} built, {len(expected)} expected")
for (board, chip), algorithm in built_targets.items():
if chip in REQUIRED_ALGORITHMS and algorithm != REQUIRED_ALGORITHMS[chip]:
errors.append(f"binary algorithm mismatch: {board} x {chip}")
if (not run_id.isdecimal() or not COMMIT.fullmatch(source_commit)
or not DIGEST.fullmatch(binary_digest)):
errors.append("current run, source commit, or binary digest is unbound")
required = ("sdk_image_sha256", "stock_image_sha256", "stock_result",
"alkane_share_accept_capture", "simulator_trace_sha256",
"bench_validation")
for row in rows:
cell = f"{row['board']} x {row['chip']}"
missing = [field for field in required if not row.get(field)]
if row.get("stock_result") not in (None, "mines", "rejects"):
missing.append("stock_result invalid")
if row.get("stock_result") == "rejects" and not row.get("stock_first_rejection"):
missing.append("stock_first_rejection")
for field in ("sdk_image_sha256", "stock_image_sha256", "simulator_trace_sha256"):
value = row.get(field)
if value and (not isinstance(value, str) or not DIGEST.fullmatch(value)):
missing.append(f"{field} invalid")
if missing:
errors.append(f"{cell}: {', '.join(missing)}")
elif run_id.isdecimal() and COMMIT.fullmatch(source_commit) and DIGEST.fullmatch(binary_digest):
try:
verify_cell(row, evidence_root, run_id, source_commit, binary_digest,
built_targets.get((row["board"], row["chip"]), "unknown"))
except (OSError, ValueError, KeyError, TypeError, json.JSONDecodeError) as error:
errors.append(f"{cell}: evidence invalid: {error}")
return errors
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--manifest", type=pathlib.Path,
default=pathlib.Path("ci/conformance.json"))
parser.add_argument("--binary", type=pathlib.Path,
default=pathlib.Path(os.environ.get("CARGO_TARGET_DIR", "target"))
/ "release/alkane-os")
parser.add_argument("--evidence-dir", type=pathlib.Path,
default=pathlib.Path("ci/evidence"))
parser.add_argument("--run-id", default=os.environ.get("GITHUB_RUN_ID", ""))
args = parser.parse_args()
manifest = json.loads(args.manifest.read_text())
try:
built_targets = binary_targets(args.binary.resolve())
except (OSError, subprocess.SubprocessError, ValueError) as error:
sys.exit(f"cannot verify Alkane OS binary target matrix: {error}")
source_commit = subprocess.run(["git", "rev-parse", "HEAD"], check=True,
capture_output=True, text=True).stdout.strip()
errors = validate(manifest, built_targets, args.evidence_dir, args.run_id,
source_commit, sha256_file(args.binary.resolve()))
if errors:
print(f"Conformance pending: {len(errors)} issues across {len(manifest['targets'])} targets")
for error in errors[:8]:
print(f" {error}")
sys.exit(1)
print(f"Conformance complete: {len(manifest['targets'])} targets")
if __name__ == "__main__":
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"
+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))
+43
View File
@@ -0,0 +1,43 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Remove generated Alkane OS CI files after tests and release upload."""
import os
from pathlib import Path
import shutil
import sys
ROOT = Path(__file__).resolve().parents[1]
DIRECTORIES = ("target", "coverage", "dist", "bench-site")
FILES = ("tests-current.txt", "bench-current.txt", "quality-current.json",
"evidence-status-current.json")
def cleanup() -> None:
if not os.environ.get("GITHUB_RUN_ID"):
raise ValueError("cleanup is restricted to CI runs")
for name in DIRECTORIES:
path = ROOT / name
if path.is_symlink() or path.parent.resolve() != ROOT.resolve():
raise ValueError(f"unsafe generated directory: {path}")
if path.is_dir():
shutil.rmtree(path)
print(f"Removed generated directory: {name}")
elif path.exists():
raise ValueError(f"expected a generated directory: {path}")
for name in FILES:
path = ROOT / name
if path.is_symlink() or path.parent.resolve() != ROOT.resolve():
raise ValueError(f"unsafe generated file: {path}")
if path.is_file():
path.unlink()
print(f"Removed generated file: {name}")
if __name__ == "__main__":
try:
cleanup()
except (OSError, ValueError) as error:
print(f"ERROR: Alkane OS cleanup: {error}", file=sys.stderr)
raise SystemExit(1)
+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()
+73
View File
@@ -0,0 +1,73 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Publish the last completed main/next CI result to a private badge branch."""
import os
from urllib.parse import quote, urlencode
from badge_store import publish_file, request_json
WORKFLOWS = {"main.yml": "main", "next.yml": "next"}
def badge(branch: str, conclusion: str, run_id: int) -> bytes:
passed = conclusion == "success"
word = "pass" if passed else "fail"
color = "#2ea043" if passed else "#d1242f"
title = f"CI {branch}: last completed attempt {word} (run {run_id})"
return (f'<svg xmlns="http://www.w3.org/2000/svg" width="102" height="20" '
f'role="img" aria-label="{title}"><title>{title}</title>'
'<rect width="102" height="20" rx="3" fill="#555"/>'
f'<path d="M39 0h60a3 3 0 0 1 3 3v14a3 3 0 0 1-3 3H39z" fill="{color}"/>'
'<text x="20" y="14" fill="#fff" text-anchor="middle" '
'font-family="sans-serif" font-size="11">CI</text>'
f'<text x="70" y="14" fill="#fff" text-anchor="middle" '
f'font-family="sans-serif" font-size="11">{word}</text></svg>\n').encode()
def latest_completed(api: str, repo: str, workflow: str, branch: str,
token: str) -> tuple[int, str]:
path = quote(workflow, safe="")
latest = None
for page in range(1, 21):
query = urlencode({"branch": branch, "limit": 50, "page": page})
url = f"{api}/repos/{repo}/actions/workflows/{path}/runs?{query}"
runs = request_json(url, token).get("workflow_runs", [])
for run in runs:
if run.get("head_branch") != branch or run.get("status") != "completed":
continue
if run.get("conclusion") not in ("success", "failure"):
continue
candidate = (int(run["id"]), run["conclusion"])
if latest is None or candidate[0] > latest[0]:
latest = candidate
if len(runs) < 50:
break
if latest is None:
raise RuntimeError(f"no completed {branch} run found for {workflow}")
return latest
def publish(api: str, repo: str, branch: str, data: bytes, token: str) -> None:
publish_file(api, repo, f"{branch}.svg", data, token,
f"Record completed {branch} CI attempt")
def main() -> None:
if os.environ["GITHUB_EVENT_NAME"] not in ("schedule", "workflow_dispatch"):
raise RuntimeError("badge publisher must run on a timer or manual dispatch")
if os.environ["GITHUB_REF"] != "refs/heads/main":
raise RuntimeError("badge publisher must use the main branch")
repo = os.environ["GITHUB_REPOSITORY"]
api = os.environ["GITHUB_API_URL"].rstrip("/")
token = os.environ["GITEA_TOKEN"]
completed = {branch: latest_completed(api, repo, workflow, branch, token)
for workflow, branch in WORKFLOWS.items()}
for branch, (run_id, conclusion) in completed.items():
publish(api, repo, branch, badge(branch, conclusion, run_id), token)
print(f"{branch} badge records completed run {run_id}: {conclusion}")
if __name__ == "__main__":
main()
+68
View File
@@ -0,0 +1,68 @@
#!/bin/sh
# Build an .afw firmware package for one control board and architecture.
#
# Modelled on the Warden `.wfw` bundle (scada/flare-edge/docs/firmware-format.md):
# one file, a strict POSIX ustar tar, a JSON manifest first, then the payload,
# with the payload's size and sha256 in the manifest so the device can verify
# before it touches flash.
#
# Differences from .wfw, both deliberate:
#
# * the payload is COMPRESSED (`payload.tar.gz`) because these images ship to
# boards over metered links, and a firmware bundle is mostly redundant;
# * the manifest carries `board` and `arch`, and both go in the file name, so a
# bundle can never be mistaken for another board family. Flashing the wrong
# family is how boards are lost.
#
# Signature: `.wfw` carries an Ed25519 detached signature. We have no release
# key yet, so `.afw` currently ships `members=2` and says so in the manifest
# (`signature: "unsigned"`). Do not claim integrity beyond the sha256 until a
# key exists.
#
# usage: make-afw.sh BOARD ARCH VERSION INPUT_DIR [OUTPUT_DIR]
# e.g. make-afw.sh am335x-bb armv7 0.1.0 /tmp/release
set -eu
BOARD=${1:?board family, e.g. am335x-bb}
ARCH=${2:?architecture, e.g. armv7 or aarch64}
VERSION=${3:?version, e.g. 0.1.0}
INPUT=${4:?directory holding the release files}
OUTPUT=${5:-dist}
mkdir -p "$OUTPUT"
WORK=$(mktemp -d)
trap 'rm -rf "$WORK"' EXIT
# The payload is a tar of the release tree, gzipped at maximum.
tar --format=ustar --owner=0 --group=0 --numeric-owner \
--create --file "$WORK/payload.tar" -C "$INPUT" .
gzip -9 -n -c "$WORK/payload.tar" > "$WORK/payload.tar.gz"
PAYLOAD_SIZE=$(wc -c < "$WORK/payload.tar.gz")
PAYLOAD_SHA=$(sha256sum "$WORK/payload.tar.gz" | cut -d' ' -f1)
BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
cat > "$WORK/manifest.json" <<MANIFEST
{
"schema": 1,
"format": "afw",
"board": "$BOARD",
"arch": "$ARCH",
"version": "$VERSION",
"build_date": "$BUILD_DATE",
"compression": "gzip",
"signature": "unsigned",
"payload": {
"file": "payload.tar.gz",
"size": $PAYLOAD_SIZE,
"sha256": "$PAYLOAD_SHA"
}
}
MANIFEST
NAME="alkane-os-$VERSION-$BOARD-$ARCH.afw"
(cd "$WORK" && tar --format=ustar --owner=0 --group=0 --numeric-owner \
--create --file "$OUTPUT/$NAME" manifest.json payload.tar.gz)
printf '%s\n' "$OUTPUT/$NAME"
printf 'board %s\narch %s\npayload %s bytes\nsha256 %s\n' \
"$BOARD" "$ARCH" "$PAYLOAD_SIZE" "$PAYLOAD_SHA"
+61 -10
View File
@@ -4,9 +4,25 @@
import argparse
import html
import json
import math
import pathlib
import re
import tomllib
from bench_host import identity as benchmark_host
EXPECTED_BENCHES = frozenset({
"target_matrix", "power_policy", "share_verification",
"scrypt_share_verification", "bm1366_work_encoding", "bm1362_commands",
"bm1362_job_encoding", "bm1366_report_decode", "stratum_header",
"stratum_submission", "stratum_authorize_format", "stratum_notify_parse",
"stratum_control_parse", "stratum_configure_parse", "difficulty_target",
"stratum_job_issue", "bm1366_session_cycle", "bm1362_work_encoding",
"stratum_configure_format", "stratum_subscribe_format",
"stratum_subscription_parse", "stratum_accept_parse",
"hal_socket_exchange", "stratum_socket_round_trip",
"bm13xx_crc5", "bm13xx_crc16", "bm1366_captured_report_poll",
})
BENCH_LINE = re.compile(r"\bBENCH ([A-Za-z0-9_]+) ([0-9]+(?:\.[0-9]+)?) ns/op\Z")
def coverage(path):
@@ -15,8 +31,40 @@ def coverage(path):
def bench_results(path):
text = pathlib.Path(path).read_text()
return {name: float(ns) for name, ns in re.findall(r"BENCH (\w+) ([0-9.]+) ns/op", text)}
results = {}
for line in pathlib.Path(path).read_text().splitlines():
if "BENCH " not in line:
continue
match = BENCH_LINE.search(line)
if match is None:
raise ValueError("malformed microbenchmark result")
name, value = match.groups()
measurement = float(value)
if name in results or not math.isfinite(measurement) or measurement <= 0:
raise ValueError("duplicate or invalid microbenchmark result")
results[name] = measurement
return results
def benchmark_delta(current, baseline):
if set(current) != EXPECTED_BENCHES:
raise ValueError("microbenchmark set differs from the declared suite")
if not isinstance(baseline, dict) or not set(baseline).issubset(current):
raise ValueError("baseline contains retired or invalid benchmarks")
if any(not isinstance(value, (int, float)) or isinstance(value, bool)
or not math.isfinite(value) or value <= 0 for value in baseline.values()):
raise ValueError("baseline contains invalid measurements")
if not baseline:
return None
return sum((baseline[name] - current[name]) / baseline[name]
for name in baseline) / len(baseline) * 100
def quality_grade(path):
checks = json.loads(pathlib.Path(path).read_text())
if checks != {"format": True, "clippy_warnings_denied": True}:
raise ValueError("format and strict Clippy must pass before publishing quality")
return "A"
def compact(number):
@@ -51,19 +99,17 @@ def main():
parser.add_argument("--tests-coverage", required=True)
parser.add_argument("--bench-output", required=True)
parser.add_argument("--bench-coverage", required=True)
parser.add_argument("--quality-gate", required=True)
parser.add_argument("--bench-baseline", default="badges/bench-baseline.json")
args = parser.parse_args()
test_output = pathlib.Path(args.tests_output).read_text()
tests = sum(map(int, re.findall(r"test result: ok\. (\d+) passed", test_output)))
if tests < 1:
raise SystemExit("no passing tests parsed")
current = bench_results(args.bench_output)
if not current or any(value <= 0 for value in current.values()):
raise SystemExit("microbenchmark result missing or zero")
base_path = pathlib.Path("badges/bench-baseline.json")
base_path = pathlib.Path(args.bench_baseline)
baseline = json.loads(base_path.read_text()) if base_path.exists() else {}
common = [name for name in current if name in baseline and baseline[name] > 0]
delta = (sum((baseline[name] - current[name]) / baseline[name] for name in common)
/ len(common) * 100) if common else None
delta = benchmark_delta(current, baseline)
line_coverage = coverage(args.tests_coverage)
bench_coverage = coverage(args.bench_coverage)
loc = sum(len(path.read_text().splitlines()) for parent in (pathlib.Path("src"), pathlib.Path("ci"))
@@ -73,8 +119,11 @@ def main():
metrics = {"tests": tests, "line_coverage_pct": round(line_coverage, 1),
"bench_coverage_pct": round(bench_coverage, 1),
"bench_ns_per_op": current, "bench_improvement_pct": delta,
"bench_host": benchmark_host(),
"lines_of_code": loc, "dependencies": dependencies,
"code_quality": "A", "license": "MIT"}
"code_quality": quality_grade(args.quality_gate),
"quality_scope": "main CI passed cargo fmt and warnings-denied Clippy on all targets",
"license": "MIT"}
pathlib.Path("badges").mkdir(exist_ok=True)
pathlib.Path("badges/metrics.json").write_text(json.dumps(metrics, indent=2) + "\n")
badges = {
@@ -84,7 +133,9 @@ def main():
"bench": ("bench", "baseline set" if delta is None else f"{delta:+.1f}% vs prev", "#007ec6"),
"loc": ("lines of code", compact(loc), "#007ec6"),
"dependencies": ("dependencies", str(dependencies), "#007ec6"),
"quality": ("code quality", "A", "#4c1"),
"quality": ("code quality", metrics["code_quality"],
{"A": "#4c1", "B": "#97ca00", "C": "#dfb317",
"D": "#fe7d37", "F": "#e05d44"}[metrics["code_quality"]]),
"license": ("license", "MIT", "#007ec6"),
}
for name, (label, value, color) in badges.items():
+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")
+121
View File
@@ -0,0 +1,121 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Publish a measured benchmark page to the public, data-only Pages repo."""
import argparse
import json
import os
from pathlib import Path
import shlex
import subprocess
import tempfile
from urllib.request import Request, urlopen
PAGES_REPO = "ssh://git@gitea.bluefla.re:2222/blueflare/alkane-benchmarks.git"
GUARD_REPO = "https://gitea.bluefla.re/blueflare/alkane-benchmarks.git"
GUARD_COMMIT = "ea160545c49bc419a245692deda8dd7db7a611eb"
PAGES_HOST = "gitea.bluefla.re"
PAGES_HOST_FINGERPRINT = "SHA256:lqB5cmC9E5HNeg/lkzdOwQ++I8A70Wx7lnNs6liN24g"
PAGES_HOST_KEY = "[gitea.bluefla.re]:2222 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIO1II6NkmRW+QAd+Wj+7qbNrA8Oo+/N/WRog4hELskn/"
def run(*args: str, env: dict[str, str] | None = None,
cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
return subprocess.run(args, env=env, cwd=cwd, text=True,
capture_output=True, check=True)
def current_main_sha() -> str:
api = os.environ["GITHUB_API_URL"].rstrip("/")
repo = os.environ["GITHUB_REPOSITORY"]
token = os.environ["GITEA_TOKEN"]
request = Request(f"{api}/repos/{repo}/branches/main",
headers={"Authorization": f"token {token}"})
with urlopen(request, timeout=20) as response:
branch = json.load(response)
return branch["commit"]["id"]
def publish(site: str) -> None:
if os.environ.get("GITHUB_REF") != "refs/heads/main":
raise ValueError("benchmark Pages publication requires main")
sha = os.environ["GITHUB_SHA"]
if current_main_sha() != sha:
print("Skipping benchmark page from a superseded main commit")
return
page = Path("bench-site/index.html").read_bytes()
if not page.startswith(b"<!doctype html>") or len(page) > 1_048_576:
raise ValueError("invalid benchmark page")
with tempfile.TemporaryDirectory(prefix="alkane-pages-") as directory:
temporary = Path(directory)
guard_checkout = temporary / "guard"
run("git", "clone", "--quiet", "--single-branch", "--branch", "next",
GUARD_REPO, str(guard_checkout))
guard_source = run("git", "show", f"{GUARD_COMMIT}:ci/validate_site.py",
cwd=guard_checkout).stdout
guard_script = temporary / "validate_site.py"
guard_script.write_text(guard_source)
run("python3", str(guard_script), "--page", site,
str(Path("bench-site/index.html").resolve()))
key = os.environ["BENCH_PAGES_DEPLOY_KEY"]
if not key.startswith("-----BEGIN OPENSSH PRIVATE KEY-----"):
raise ValueError("missing benchmark Pages deploy key")
key_path = temporary / "deploy_key"
key_path.write_text(key.rstrip("\n") + "\n")
key_path.chmod(0o600)
known_hosts = temporary / "known_hosts"
known_hosts.write_text(PAGES_HOST_KEY + "\n")
fingerprint = run("ssh-keygen", "-lf", str(known_hosts)).stdout.split()[1]
if fingerprint != PAGES_HOST_FINGERPRINT:
raise ValueError("benchmark Pages SSH host key changed")
git_env = os.environ.copy()
ssh_command = (f"ssh -i {shlex.quote(str(key_path))} -o IdentitiesOnly=yes "
f"-o UserKnownHostsFile={shlex.quote(str(known_hosts))} "
"-o StrictHostKeyChecking=yes -o ConnectTimeout=10")
git_env["GIT_SSH_COMMAND"] = ssh_command
git_env["GIT_TERMINAL_PROMPT"] = "0"
checkout = temporary / "site"
run("git", "clone", "--quiet", "--single-branch", "--branch", "gh-pages",
PAGES_REPO, str(checkout), env=git_env)
run("git", "config", "user.name", "Alkane CI", cwd=checkout)
run("git", "config", "user.email", "ci@bluefla.re", cwd=checkout)
for attempt in range(3):
if current_main_sha() != sha:
print("Skipping benchmark page from a superseded main commit")
return
run("git", "fetch", "--quiet", "origin", "gh-pages", env=git_env,
cwd=checkout)
run("git", "checkout", "-q", "-B", "bench-publish", "origin/gh-pages",
cwd=checkout)
destination = checkout / site / "index.html"
destination.parent.mkdir(exist_ok=True)
destination.write_bytes(page)
run("git", "add", f"{site}/index.html", cwd=checkout)
changed = subprocess.run(("git", "diff", "--cached", "--quiet"),
cwd=checkout, check=False)
if changed.returncode == 0:
print(f"{site} benchmark page is already current")
return
if changed.returncode != 1:
raise RuntimeError("cannot compare benchmark page")
run("git", "commit", "-q", "-m",
f"Update {site} benchmarks for {sha[:10]} [skip ci]", cwd=checkout)
pushed = subprocess.run(("git", "push", "--quiet", "origin",
"HEAD:gh-pages"), env=git_env, cwd=checkout,
text=True, capture_output=True, check=False)
if pushed.returncode == 0:
print(f"Published {site} benchmark page for {sha[:10]}")
return
if attempt == 2:
raise RuntimeError(f"benchmark Pages push failed: {pushed.stderr.strip()}")
raise RuntimeError("benchmark Pages publication did not complete")
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument("site", choices=("sdk", "os", "toolkit"))
publish(parser.parse_args().site)
if __name__ == "__main__":
main()
+32
View File
@@ -0,0 +1,32 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Publish measured main-branch metric badges to the private badge branch."""
import os
from pathlib import Path
from badge_store import publish_file
ROOT = Path(__file__).resolve().parents[1]
NAMES = ("tests", "coverage", "bench", "bench-coverage", "loc",
"dependencies", "quality", "license")
def main() -> None:
api = os.environ["GITHUB_API_URL"].rstrip("/")
repo = os.environ["GITHUB_REPOSITORY"]
token = os.environ["GITEA_TOKEN"]
for name in NAMES:
data = (ROOT / "badges" / f"{name}.svg").read_bytes()
if not data.lstrip().startswith(b"<svg"):
raise ValueError(f"invalid {name} SVG")
publish_file(api, repo, f"badges/{name}.svg", data, token,
f"Update measured {name} badge")
data = (ROOT / "badges/metrics.json").read_bytes()
publish_file(api, repo, "badges/metrics.json", data, token,
"Update measured badge data")
print(f"Published {len(NAMES)} measured badge SVGs and metrics.json")
if __name__ == "__main__":
main()
+138 -33
View File
@@ -1,7 +1,9 @@
#!/usr/bin/env python3
"""Create one Gitea release and attach files using the runner's scoped token."""
# SPDX-License-Identifier: MIT
"""Publish a complete Gitea release after all assets are attached to a draft."""
import json
import hashlib
import os
import pathlib
import sys
@@ -10,45 +12,148 @@ import urllib.parse
import urllib.request
def request(url, payload, content_type):
headers = {
"Authorization": "token " + os.environ["GITEA_TOKEN"],
"Content-Type": content_type,
def request(url, method="GET", payload=None, content_type=None):
headers = {"Authorization": "token " + os.environ["GITEA_TOKEN"]}
if content_type:
headers["Content-Type"] = content_type
operation = urllib.request.Request(url, data=payload, headers=headers, method=method)
with urllib.request.urlopen(operation, timeout=60) as response:
body = response.read()
return json.loads(body) if body else None
def json_request(url, method, value):
return request(url, method, json.dumps(value).encode(), "application/json")
def files_to_publish(names):
paths = [pathlib.Path(name) for name in names]
if not paths or len({path.name for path in paths}) != len(paths):
raise ValueError("release assets must have distinct basenames")
for path in paths:
if not path.is_file() or path.stat().st_size == 0:
raise ValueError(f"release asset missing or empty: {path}")
return paths
def sha256_file(path):
digest = hashlib.sha256()
with path.open("rb") as source:
for chunk in iter(lambda: source.read(1_048_576), b""):
digest.update(chunk)
return digest.hexdigest()
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, request, fp, code, message, headers, new_url):
return None
def asset_digest(asset, api):
url = asset["browser_download_url"]
remote = urllib.parse.urlsplit(url)
expected = urllib.parse.urlsplit(api)
if remote.scheme != "https" or remote.netloc != expected.netloc:
raise ValueError("asset download is outside the trusted Gitea host")
operation = urllib.request.Request(
url, headers={"Authorization": "token " + os.environ["GITEA_TOKEN"]})
digest = hashlib.sha256()
with urllib.request.build_opener(NoRedirect).open(operation, timeout=60) as response:
for chunk in iter(lambda: response.read(1_048_576), b""):
digest.update(chunk)
return digest.hexdigest()
def get_release(url):
try:
return request(url)
except urllib.error.HTTPError as error:
if error.code == 404:
return None
raise
def check_tag_commit(api, repo, tag, sha):
url = f"{api}/repos/{repo}/tags/{urllib.parse.quote(tag, safe='')}"
try:
remote_tag = request(url)
except urllib.error.HTTPError as error:
if error.code == 404:
return False
raise
if not isinstance(remote_tag, dict) or remote_tag.get("commit", {}).get("sha") != sha:
raise ValueError("Git tag points to a different or unknown commit")
return True
def publish(tag, prerelease, paths, api, repo, sha):
base = f"{api}/repos/{repo}/releases"
tag_url = f"{base}/tags/{urllib.parse.quote(tag, safe='')}"
metadata = {
"tag_name": tag,
"target_commitish": sha,
"name": tag,
"body": f"Automated Alkane OS build from {sha}. Conformance results are in the repository.",
"prerelease": prerelease,
}
req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
with urllib.request.urlopen(req, timeout=60) as response:
return json.load(response)
check_tag_commit(api, repo, tag, sha)
release = get_release(tag_url)
if release is None:
release = json_request(base, "POST", {**metadata, "draft": True})
elif release.get("target_commitish") != sha:
raise ValueError("release tag already belongs to another source revision")
release_url = f"{base}/{release['id']}"
assets_url = f"{release_url}/assets"
existing = request(assets_url)
wanted = {path.name: path.stat().st_size for path in paths}
digests = {path.name: sha256_file(path) for path in paths}
present = {asset["name"]: asset for asset in existing}
if not release.get("draft") and all(
(asset := present.get(name)) is not None and asset["size"] == size
and asset_digest(asset, api) == digests[name]
for name, size in wanted.items()
):
if not check_tag_commit(api, repo, tag, sha):
raise ValueError("published release has no Git tag")
print(f"Release {tag} is already complete")
return
if not release.get("draft"):
release = json_request(release_url, "PATCH", {**metadata, "draft": True})
if not release.get("draft"):
raise ValueError("incomplete release could not be returned to draft")
for asset in existing:
if asset["name"] in wanted:
request(f"{assets_url}/{asset['id']}", "DELETE")
for path in paths:
query = urllib.parse.urlencode({"name": path.name})
request(f"{assets_url}?{query}", "POST", path.read_bytes(),
"application/octet-stream")
uploaded = request(assets_url)
actual = {asset["name"]: asset for asset in uploaded}
if any((asset := actual.get(name)) is None or asset["size"] != size
or asset_digest(asset, api) != digests[name]
for name, size in wanted.items()):
raise ValueError("draft release asset verification failed")
check_tag_commit(api, repo, tag, sha)
release = json_request(release_url, "PATCH", {**metadata, "draft": False})
if release.get("draft"):
raise ValueError("release remained a draft after publishing")
if not check_tag_commit(api, repo, tag, sha):
raise ValueError("published release did not create the expected Git tag")
print(f"Published {tag} with {len(paths)} assets")
def main():
if len(sys.argv) < 4:
sys.exit("usage: release.py TAG PRERELEASE FILE [FILE ...]")
tag, prerelease, *files = sys.argv[1:]
api = os.environ.get("GITHUB_API_URL", "https://gitea.bluefla.re/api/v1").rstrip("/")
repo = os.environ["GITHUB_REPOSITORY"]
sha = os.environ["GITHUB_SHA"]
body = f"Automated Alkane OS build from {sha}. Conformance results are in the repository."
metadata = {
"tag_name": tag,
"target_commitish": sha,
"name": tag,
"body": body,
"prerelease": prerelease.lower() == "true",
}
tag, prerelease, *names = sys.argv[1:]
try:
release = request(f"{api}/repos/{repo}/releases", json.dumps(metadata).encode(), "application/json")
except urllib.error.HTTPError as exc:
sys.exit(f"release creation failed: HTTP {exc.code}")
release_id = release["id"]
for name in files:
path = pathlib.Path(name)
query = urllib.parse.urlencode({"name": path.name})
try:
request(f"{api}/repos/{repo}/releases/{release_id}/assets?{query}",
path.read_bytes(), "application/octet-stream")
except urllib.error.HTTPError as exc:
sys.exit(f"asset upload failed for {path.name}: HTTP {exc.code}")
print(f"Created {tag} with {len(files)} assets")
paths = files_to_publish(names)
api = os.environ.get("GITHUB_API_URL", "https://gitea.bluefla.re/api/v1").rstrip("/")
publish(tag, prerelease.lower() == "true", paths, api,
os.environ["GITHUB_REPOSITORY"], os.environ["GITHUB_SHA"])
except (ValueError, OSError, urllib.error.HTTPError) as error:
sys.exit(f"release publication failed: {error}")
if __name__ == "__main__":
+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"
}
]
}
+58
View File
@@ -0,0 +1,58 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Exercise benchmark history selection and safe site rendering."""
import sys
from pathlib import Path
import unittest
sys.path.insert(0, str(Path(__file__).resolve().parent))
from bench_history import previous_measurement, render_html, updated_index
class HistoryTests(unittest.TestCase):
def test_retry_uses_previous_commit(self):
first = "a" * 40
second = "b" * 40
index = {"schema": 1, "entries": [
{"sha": first, "timestamp": "2026-01-01T00:00:00+00:00",
"metrics": {"bench_ns_per_op": {"hash": 10.0}}},
{"sha": second, "timestamp": "2026-01-02T00:00:00+00:00",
"metrics": {"bench_ns_per_op": {"hash": 8.0}}}]}
self.assertEqual(previous_measurement(index, second,
lambda ancestor, sha: 1 if ancestor == first else None),
{"hash": 10.0})
updated = updated_index(index, second, {"bench_ns_per_op": {"hash": 7.5}},
"2026-01-03T00:00:00+00:00")
self.assertEqual(len(updated["entries"]), 2)
self.assertEqual(updated["entries"][-1]["metrics"]["bench_ns_per_op"]["hash"], 7.5)
def test_invalid_measurement_and_sha_rejected(self):
with self.assertRaises(ValueError):
updated_index({}, "bad", {"bench_ns_per_op": {"hash": 1}}, "now")
with self.assertRaises(ValueError):
updated_index({}, "a" * 40, {"bench_ns_per_op": {"hash": -1}}, "now")
def test_baseline_must_match_cpu_class(self):
first = "a" * 40
host = {"architecture": "x86_64", "cpu_model": "A", "logical_cpus": 8}
other = {"architecture": "x86_64", "cpu_model": "B", "logical_cpus": 8}
index = {"entries": [{"sha": first, "metrics": {
"bench_ns_per_op": {"hash": 10.0}, "bench_host": host}}]}
distance = lambda _ancestor, _sha: 1
self.assertEqual(previous_measurement(index, "b" * 40, distance, host),
{"hash": 10.0})
self.assertEqual(previous_measurement(index, "b" * 40, distance, other), {})
def test_site_escapes_history_content(self):
entry = {"sha": "a" * 40, "timestamp": "<script>alert(1)</script>",
"metrics": {"bench_ns_per_op": {"hash": 10.0},
"bench_host": {"cpu_model": "<script>cpu</script>"}}}
page = render_html({"entries": [entry]})
self.assertIn("&lt;script&gt;", page)
self.assertNotIn("<script>", page)
self.assertIn("10.000", page)
if __name__ == "__main__":
unittest.main()
+50
View File
@@ -0,0 +1,50 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Verify cleanup removes only generated files inside the CI checkout."""
import importlib.util
import os
from pathlib import Path
import tempfile
from unittest.mock import patch
SPEC = importlib.util.spec_from_file_location(
"cleanup_generated", Path(__file__).resolve().with_name("cleanup-generated.py"))
CLEANUP = importlib.util.module_from_spec(SPEC)
SPEC.loader.exec_module(CLEANUP)
def main() -> None:
with tempfile.TemporaryDirectory(prefix="alkane-os-cleanup-") as temporary:
root = Path(temporary)
outside = root.parent / (root.name + "-outside")
outside.mkdir()
(outside / "keep").write_bytes(b"safe")
previous = CLEANUP.ROOT
CLEANUP.ROOT = root
try:
with patch.dict(os.environ, {"GITHUB_RUN_ID": "123"}):
(root / "target").mkdir()
(root / "target/build").write_bytes(b"generated")
(root / "bench-current.txt").write_bytes(b"generated")
CLEANUP.cleanup()
assert not (root / "target").exists()
assert not (root / "bench-current.txt").exists()
(root / "target").symlink_to(outside, target_is_directory=True)
try:
CLEANUP.cleanup()
except ValueError:
pass
else:
raise AssertionError("cleanup followed a symlink")
assert (outside / "keep").read_bytes() == b"safe"
finally:
CLEANUP.ROOT = previous
(outside / "keep").unlink()
outside.rmdir()
print("Alkane OS CI cleanup containment: PASS")
if __name__ == "__main__":
main()
+115
View File
@@ -0,0 +1,115 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Regression checks for the fail-closed release evidence gate."""
import copy
import importlib.util
import json
from pathlib import Path
from tempfile import TemporaryDirectory
import unittest
SCRIPT = Path(__file__).with_name("check-conformance.py")
spec = importlib.util.spec_from_file_location("check_conformance", SCRIPT)
gate = importlib.util.module_from_spec(spec)
spec.loader.exec_module(gate)
MANIFEST = json.loads(Path(__file__).with_name("conformance.json").read_text())
TARGETS = {(row["board"], row["chip"]): gate.REQUIRED_ALGORITHMS[row["chip"]]
for row in MANIFEST["targets"]}
class ConformanceGateTest(unittest.TestCase):
def test_placeholder_matrix_cannot_pass_without_current_run_artifacts(self):
manifest = copy.deepcopy(MANIFEST)
for row in manifest["targets"]:
row.update(sdk_image_sha256="0" * 64,
stock_image_sha256="0" * 64,
simulator_trace_sha256="0" * 64,
stock_result="mines",
alkane_share_accept_capture="does-not-exist.json",
bench_validation="not-run")
with TemporaryDirectory() as directory:
errors = gate.validate(manifest, TARGETS, Path(directory), "123",
"a" * 40, "b" * 64)
self.assertEqual(len(errors), 64)
self.assertTrue(all("evidence invalid" in error for error in errors))
def test_stale_source_identity_is_rejected(self):
row = copy.deepcopy(MANIFEST["targets"][0])
row["stock_result"] = "mines"
with TemporaryDirectory() as directory:
root = Path(directory)
report = root / "123" / row["board"] / f"{row['chip']}.json"
report.parent.mkdir(parents=True)
report.write_text(json.dumps({"schema": 1, "run_id": "123",
"source_commit": "f" * 40,
"os_binary_sha256": "b" * 64,
"board": row["board"], "chip": row["chip"],
"stock_firmware_modified": False}))
with self.assertRaisesRegex(ValueError, "different run, source"):
gate.verify_cell(row, root, "123", "a" * 40, "b" * 64,
TARGETS[(row["board"], row["chip"])])
def test_share_accept_requires_real_difficulty_one_work(self):
capture = {"nonce_source": "real_silicon_capture",
"header80": "00" * 80,
"pool_target_le": "ff" * 32, "nonce": 0,
"submission": {"id": 4, "method": "mining.submit",
"params": ["worker", "job", "", "00000000", "00000000"]},
"pool_response": {"id": 4, "result": True, "error": None}}
with self.assertRaisesRegex(ValueError, "below difficulty one"):
gate.verify_accept(capture, "Sha256")
capture["submission"]["params"][4] = "00000001"
with self.assertRaisesRegex(ValueError, "submitted nonce"):
gate.verify_accept(capture, "Sha256")
def test_scrypt_proof_matches_litecoin_and_independent_vectors(self):
header = bytes.fromhex(
"01000000f615f7ce3b4fc6b8f61e8f89aedb1d0852507650533a9e3b10b9bbcc30639f27"
"9fcaa86746e1ef52d3edb3c4ad8259920d509bd073605c9bf1d59983752a6b06b817bb4"
"ea78e011d012d59d4"
)
self.assertEqual(len(header), 80)
self.assertEqual(
gate.proof_digest(header, "Scrypt")[::-1].hex(),
"0000000110c8357966576df46f3b802ca897deb7ad18b12f1c24ecff6386ebd9",
)
self.assertEqual(
gate.proof_digest(bytes(range(80)), "Scrypt").hex(),
"bc540a1a801df96e493005c71e010e2d387607fbf0fec416fd3c2645aa1ba9d2",
)
def test_equihash_cells_still_need_an_algorithm_specific_verifier(self):
with self.assertRaisesRegex(ValueError, "Equihash share verifier"):
gate.verify_accept({}, "Equihash")
def test_submitted_header_reconstruction_rejects_version_and_extranonce_changes(self):
capture = {
"subscription": {"extranonce1": "aa", "extranonce2_size": 1},
"notify": {"method": "mining.notify", "params": [
"job", "11" * 32, "01", "02", [],
"20000000", "1d00ffff", "12345678", True]},
"configure_response": {"result": {
"version-rolling": True, "version-rolling.mask": "1fffe000"}},
}
params = ["worker", "job", "bb", "12345678", "00000001", "00002000"]
header, _ = gate.reconstructed_header(capture, params)
self.assertEqual(len(header), 80)
self.assertEqual(header[:4], (0x20002000).to_bytes(4, "little"))
self.assertEqual(header[4:8], b"\x11" * 4)
changed = params.copy()
changed[5] = "ffffffff"
with self.assertRaisesRegex(ValueError, "version bits"):
gate.reconstructed_header(capture, changed)
changed[5] = params[5]
changed[2] = "f"
with self.assertRaisesRegex(ValueError, "Stratum hex"):
gate.reconstructed_header(capture, changed)
changed[2] = "cc"
rebuilt, _ = gate.reconstructed_header(capture, changed)
self.assertNotEqual(rebuilt, header)
if __name__ == "__main__":
unittest.main()
+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()
+67
View File
@@ -0,0 +1,67 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Check that queued CI runs do not displace the last completed result."""
import importlib.util
import os
from pathlib import Path
from unittest.mock import patch
import xml.etree.ElementTree as ET
from badge_store import publish_file
path = Path(__file__).with_name("last-attempt-badge.py")
spec = importlib.util.spec_from_file_location("last_attempt_badge", path)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
def runs(_url, _token):
return {"workflow_runs": [
{"id": 105, "head_branch": "main", "status": "completed", "conclusion": "cancelled"},
{"id": 104, "head_branch": "main", "status": "queued", "conclusion": None},
{"id": 103, "head_branch": "main", "status": "completed", "conclusion": "failure"},
{"id": 102, "head_branch": "main", "status": "completed", "conclusion": "success"},
]}
with patch.object(module, "request_json", runs):
assert module.latest_completed("https://example.invalid/api/v1", "owner/repo",
"main.yml", "main", "token") == (103, "failure")
svg = module.badge("main", "failure", 103)
root = ET.fromstring(svg)
assert root.attrib["aria-label"] == "CI main: last completed attempt fail (run 103)"
assert b">fail</text>" in svg
assert b"#d1242f" in svg
assert b">pass</text>" in module.badge("next", "success", 108)
environment = {
"GITHUB_EVENT_NAME": "schedule",
"GITHUB_REF": "refs/heads/main",
"GITHUB_REPOSITORY": "owner/repo",
"GITHUB_API_URL": "https://example.invalid/api/v1",
"GITEA_TOKEN": "test-token",
}
with patch.dict(os.environ, environment), \
patch.object(module, "latest_completed", side_effect=[(201, "success"),
(202, "failure")]) as latest, \
patch.object(module, "publish") as published:
module.main()
assert latest.call_count == 2
assert [call.args[2] for call in published.call_args_list] == ["main", "next"]
with patch.dict(os.environ, {**environment, "GITHUB_EVENT_NAME": "workflow_run"}):
try:
module.main()
except RuntimeError as error:
assert "timer or manual dispatch" in str(error)
else:
raise AssertionError("workflow_run event entered badge publisher")
for invalid in ("", "/main.svg", "../main.svg", "badges//main.svg"):
try:
publish_file("https://example.invalid/api/v1", "owner/repo", invalid,
b"<svg/>", "token", "test")
except ValueError:
pass
else:
raise AssertionError(f"unsafe badge path accepted: {invalid}")
print("last completed CI badge: queued run ignored, pass/fail SVGs valid")
+51
View File
@@ -0,0 +1,51 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Regression checks for measured benchmark and quality badges."""
import sys
import json
from pathlib import Path
from tempfile import TemporaryDirectory
import unittest
sys.path.insert(0, str(Path(__file__).resolve().parent))
from metrics import EXPECTED_BENCHES, bench_results, benchmark_delta, compact, quality_grade
class MetricTests(unittest.TestCase):
def test_quality_requires_both_static_checks(self):
with TemporaryDirectory() as directory:
path = Path(directory) / "quality.json"
path.write_text(json.dumps({"format": True, "clippy_warnings_denied": True}))
self.assertEqual(quality_grade(path), "A")
path.write_text(json.dumps({"format": True, "clippy_warnings_denied": False}))
with self.assertRaises(ValueError):
quality_grade(path)
def test_benchmark_parser_and_short_si_badge(self):
with TemporaryDirectory() as directory:
path = Path(directory) / "bench.txt"
path.write_text("test bench_sha ... BENCH sha 42.125 ns/op\n")
self.assertEqual(bench_results(path), {"sha": 42.125})
path.write_text("BENCH sha 42.125 ns/op\nBENCH sha 40.000 ns/op\n")
with self.assertRaisesRegex(ValueError, "duplicate"):
bench_results(path)
path.write_text("BENCH sha 42.125 ns/op\nBENCH broken nan ns/op\n")
with self.assertRaisesRegex(ValueError, "malformed"):
bench_results(path)
self.assertEqual(compact(1234567), "1.23M")
def test_benchmark_suite_and_baseline_must_be_complete(self):
current = {name: 10.0 for name in EXPECTED_BENCHES}
self.assertIsNone(benchmark_delta(current, {}))
self.assertEqual(benchmark_delta(current, {"target_matrix": 20.0}), 50.0)
with self.assertRaisesRegex(ValueError, "declared suite"):
benchmark_delta({"target_matrix": 10.0}, {})
with self.assertRaisesRegex(ValueError, "retired"):
benchmark_delta(current, {"removed_bench": 20.0})
with self.assertRaisesRegex(ValueError, "invalid measurements"):
benchmark_delta(current, {"target_matrix": float("inf")})
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()
+133
View File
@@ -0,0 +1,133 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Check draft release recovery without making network requests."""
import importlib.util
import hashlib
import urllib.error
from pathlib import Path
from tempfile import TemporaryDirectory
import unittest
from unittest.mock import patch
SCRIPT = Path(__file__).with_name("release.py")
spec = importlib.util.spec_from_file_location("release", SCRIPT)
release = importlib.util.module_from_spec(spec)
spec.loader.exec_module(release)
class FakeGitea:
def __init__(self):
self.release = None
self.assets = []
self.blobs = {}
self.fail_second_upload = True
self.uploads = 0
self.tag_sha = None
def request(self, url, method="GET", payload=None, content_type=None):
if "/tags/" in url and "/releases/" not in url:
if self.tag_sha is None:
raise urllib.error.HTTPError(url, 404, "missing", {}, None)
return {"commit": {"sha": self.tag_sha}}
if "/assets" in url:
if method == "GET":
return list(self.assets)
if method == "DELETE":
asset_id = int(url.rsplit("/", 1)[1])
self.assets = [item for item in self.assets if item["id"] != asset_id]
self.blobs.pop(asset_id, None)
return None
self.uploads += 1
if self.fail_second_upload and self.uploads == 2:
raise OSError("injected upload failure")
name = release.urllib.parse.parse_qs(url.split("?", 1)[1])["name"][0]
item = {"id": self.uploads, "name": name, "size": len(payload),
"browser_download_url": f"https://api/download/{self.uploads}"}
self.assets.append(item)
self.blobs[self.uploads] = payload
return item
if method == "GET":
return self.release
if method == "POST":
assert self.release is None
self.release = {**release.json.loads(payload), "id": 7}
return dict(self.release)
if method == "PATCH":
self.release.update(release.json.loads(payload))
if not self.release["draft"] and self.tag_sha is None:
self.tag_sha = self.release["target_commitish"]
return dict(self.release)
raise AssertionError((method, url))
class ReleaseTest(unittest.TestCase):
def test_retry_after_partial_upload_keeps_release_draft_until_complete(self):
with TemporaryDirectory() as directory:
paths = [Path(directory) / "source.tar.gz", Path(directory) / "bench.txt"]
for path in paths:
path.write_bytes(path.name.encode())
fake = FakeGitea()
def digest(asset, _api):
return hashlib.sha256(fake.blobs[asset["id"]]).hexdigest()
with patch.object(release, "request", fake.request), \
patch.object(release, "asset_digest", digest):
with self.assertRaisesRegex(OSError, "injected upload failure"):
release.publish("v1.2.3", False, paths, "https://api", "org/repo", "a" * 40)
self.assertTrue(fake.release["draft"])
self.assertEqual(len(fake.assets), 1)
fake.fail_second_upload = False
release.publish("v1.2.3", False, paths, "https://api", "org/repo", "a" * 40)
self.assertFalse(fake.release["draft"])
self.assertEqual({item["name"] for item in fake.assets},
{path.name for path in paths})
fake.assets[0]["size"] = len(fake.blobs[fake.assets[0]["id"]])
fake.blobs[fake.assets[0]["id"]] = b"x" * fake.assets[0]["size"]
release.publish("v1.2.3", False, paths, "https://api", "org/repo", "a" * 40)
self.assertFalse(fake.release["draft"])
self.assertEqual(digest(fake.assets[0], "https://api"),
release.sha256_file(paths[0]))
def test_preflight_rejects_missing_and_duplicate_assets(self):
with TemporaryDirectory() as directory:
path = Path(directory) / "one"
with self.assertRaisesRegex(ValueError, "missing or empty"):
release.files_to_publish([str(path)])
path.write_bytes(b"x")
with self.assertRaisesRegex(ValueError, "distinct"):
release.files_to_publish([str(path), str(path)])
def test_existing_git_tag_mismatch_blocks_release_without_changes(self):
with TemporaryDirectory() as directory:
path = Path(directory) / "image.tar.gz"
path.write_bytes(b"image")
fake = FakeGitea()
fake.tag_sha = "b" * 40
fake.release = {"id": 7, "tag_name": "v1.2.3",
"target_commitish": "a" * 40, "draft": False}
with patch.object(release, "request", fake.request):
with self.assertRaisesRegex(ValueError, "Git tag points"):
release.publish("v1.2.3", False, [path], "https://api",
"org/repo", "a" * 40)
self.assertEqual(fake.uploads, 0)
self.assertFalse(fake.release["draft"])
def test_complete_release_without_git_tag_is_not_accepted(self):
with TemporaryDirectory() as directory:
path = Path(directory) / "image.tar.gz"
path.write_bytes(b"image")
fake = FakeGitea()
fake.release = {"id": 7, "tag_name": "v1.2.3",
"target_commitish": "a" * 40, "draft": False}
fake.assets = [{"id": 1, "name": path.name, "size": path.stat().st_size}]
with patch.object(release, "request", fake.request), \
patch.object(release, "asset_digest", lambda *_: release.sha256_file(path)):
with self.assertRaisesRegex(ValueError, "no Git tag"):
release.publish("v1.2.3", False, [path], "https://api",
"org/repo", "a" * 40)
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:
+116
View File
@@ -0,0 +1,116 @@
// SPDX-License-Identifier: MIT
//! Bounded host-only check: captured BM13xx report through HAL to a strict pool.
use alkane_os::hal_wire::HalClient;
use alkane_os::miner::Bm1366Miner;
use alkane_os::stratum_client::{PoolConnection, PoolEvent, ReportEvent};
use std::error::Error;
use std::io;
use std::net::SocketAddr;
use std::time::{Duration, Instant};
const CAPTURED_HEADER: [u8; 80] = [
0x00, 0x00, 0x00, 0x20, 0xfc, 0x3a, 0xb8, 0xd4, 0x30, 0x21, 0xf4, 0x5e, 0xb6, 0x62, 0x38, 0x9d,
0x0f, 0x79, 0x1f, 0x65, 0x7d, 0xbf, 0x75, 0xa5, 0xcb, 0x93, 0x67, 0x0b, 0x57, 0xb6, 0xc2, 0x25,
0x03, 0xb4, 0x21, 0x3a, 0x43, 0xae, 0x10, 0x52, 0xeb, 0xd4, 0x44, 0x43, 0x06, 0x8f, 0xe1, 0x78,
0xe2, 0xc6, 0x1c, 0xa4, 0x99, 0x48, 0x46, 0xfd, 0x13, 0x3a, 0xdd, 0xb0, 0x4a, 0xab, 0x2b, 0x38,
0x2c, 0x5b, 0x4c, 0x74, 0xc1, 0x01, 0x2e, 0x6a, 0x8f, 0x06, 0x02, 0x17, 0x00, 0x00, 0x00, 0x00,
];
const BM1362_HEADER_HEX: &str = concat!(
"00000020fc3ab8d43021f45eb662389d0f791f657dbf75a5cb93670b57b6c22503",
"b4213a0503969b7384e1215aace8cfc65dae22d8493ad48fec0b7ac3b0ad7b4e7",
"fb0c5c0012e6a8f06021700000000"
);
fn bm1362_header() -> Result<[u8; 80], io::Error> {
let mut header = [0_u8; 80];
for (index, pair) in BM1362_HEADER_HEX.as_bytes().chunks_exact(2).enumerate() {
let digits = std::str::from_utf8(pair).map_err(io::Error::other)?;
header[index] = u8::from_str_radix(digits, 16).map_err(io::Error::other)?;
}
Ok(header)
}
fn failure(message: impl Into<String>) -> io::Error {
io::Error::other(message.into())
}
fn main() -> Result<(), Box<dyn Error>> {
let mut args = std::env::args().skip(1);
let socket = args.next().ok_or_else(|| {
failure("usage: simulator_pool_replay_probe HAL_SOCKET POOL_ADDRESS [SHARES] [CHIP]")
})?;
let address: SocketAddr = args
.next()
.ok_or_else(|| failure("missing pool address"))?
.parse()?;
let expected_accepts: usize = args.next().map_or(Ok(1), |value| value.parse())?;
if !(1..=64).contains(&expected_accepts) {
return Err(failure("SHARES must be between 1 and 64").into());
}
let chip = args.next().unwrap_or_else(|| "BM1366".to_owned());
let first_header = match chip.as_str() {
"BM1366" => CAPTURED_HEADER,
"BM1362" if expected_accepts == 1 => bm1362_header()?,
"BM1362" => return Err(failure("BM1362 has one captured header").into()),
_ => return Err(failure("unsupported captured chip").into()),
};
if args.next().is_some() {
return Err(failure("unexpected argument").into());
}
if !address.ip().is_loopback() {
return Err(failure("probe pool must be on loopback").into());
}
let mut backend = HalClient::connect(socket)?;
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000)
.ok_or_else(|| failure("invalid simulator configuration"))?;
let mut pool = PoolConnection::connect(
address,
"alkane-simulator-probe",
"alkane.test",
"x",
Duration::from_secs(2),
Duration::from_secs(5),
)
.map_err(|error| failure(format!("pool handshake: {error:?}")))?;
miner.start()?;
let deadline = Instant::now() + Duration::from_secs(10 + 2 * expected_accepts as u64);
let mut issued = 0;
let mut submitted = 0;
let mut accepted = 0;
while Instant::now() < deadline {
let (event, reports) = pool
.cycle(&mut miner)
.map_err(|error| failure(format!("mining cycle: {error:?}")))?;
submitted += reports
.iter()
.filter(|report| matches!(report, ReportEvent::Submitted(_)))
.count();
match event {
PoolEvent::Work(work) => {
if issued == 0 && work.header != first_header {
return Err(failure("pool job differs from real-silicon capture").into());
}
issued += 1;
}
PoolEvent::ShareAccepted(_) => {
if accepted >= submitted || accepted >= issued {
return Err(failure("unattributed pool acceptance").into());
}
accepted += 1;
if accepted == expected_accepts {
miner.stop()?;
println!(
"{chip} real captured nonce accepted by strict loopback pool ({accepted} shares)"
);
return Ok(());
}
}
PoolEvent::ShareRejected(_) => return Err(failure("pool rejected share").into()),
_ => {}
}
}
Err(failure("captured share was not accepted before deadline").into())
}
+59
View File
@@ -0,0 +1,59 @@
// SPDX-License-Identifier: MIT
//! Exercise the SDK's host-only BM13xx HAL simulator with a captured job.
use alkane_os::hal_wire::HalClient;
use alkane_os::miner::{Bm1366Miner, ChipModel};
use std::error::Error;
use std::io;
const HEADER: [u8; 80] = [
0x00, 0x00, 0x00, 0x20, 0xfc, 0x3a, 0xb8, 0xd4, 0x30, 0x21, 0xf4, 0x5e, 0xb6, 0x62, 0x38, 0x9d,
0x0f, 0x79, 0x1f, 0x65, 0x7d, 0xbf, 0x75, 0xa5, 0xcb, 0x93, 0x67, 0x0b, 0x57, 0xb6, 0xc2, 0x25,
0x03, 0xb4, 0x21, 0x3a, 0x43, 0xae, 0x10, 0x52, 0xeb, 0xd4, 0x44, 0x43, 0x06, 0x8f, 0xe1, 0x78,
0xe2, 0xc6, 0x1c, 0xa4, 0x99, 0x48, 0x46, 0xfd, 0x13, 0x3a, 0xdd, 0xb0, 0x4a, 0xab, 0x2b, 0x38,
0x2c, 0x5b, 0x4c, 0x74, 0xc1, 0x01, 0x2e, 0x6a, 0x8f, 0x06, 0x02, 0x17, 0x00, 0x00, 0x00, 0x00,
];
const BM1362_HEADER_HEX: &str = concat!(
"00000020fc3ab8d43021f45eb662389d0f791f657dbf75a5cb93670b57b6c22503",
"b4213a0503969b7384e1215aace8cfc65dae22d8493ad48fec0b7ac3b0ad7b4e7",
"fb0c5c0012e6a8f06021700000000"
);
fn bm1362_header() -> Result<[u8; 80], io::Error> {
let mut header = [0_u8; 80];
for (index, pair) in BM1362_HEADER_HEX.as_bytes().chunks_exact(2).enumerate() {
let digits = std::str::from_utf8(pair).map_err(io::Error::other)?;
header[index] = u8::from_str_radix(digits, 16).map_err(io::Error::other)?;
}
Ok(header)
}
fn main() -> Result<(), Box<dyn Error>> {
let mut args = std::env::args().skip(1);
let path = args
.next()
.ok_or("usage: simulator_replay_probe SOCKET_PATH [BM1366|BM1362]")?;
let chip = args.next().unwrap_or_else(|| "BM1366".to_owned());
if args.next().is_some() {
return Err("unexpected argument".into());
}
let (header, nonce, model) = match chip.as_str() {
"BM1366" => (HEADER, 0xedad_ff38, ChipModel::Bm1366),
"BM1362" => (bm1362_header()?, 0x630b_2533, ChipModel::Bm1362),
_ => return Err("unsupported captured chip".into()),
};
let mut backend = HalClient::connect(path)?;
// Chip initialization is outside this host-only check.
let mut miner = Bm1366Miner::new_for_chip(&mut backend, model, 0, 0, 0, 100, 80_000)
.ok_or("invalid simulator probe configuration")?;
miner.start()?;
let mut target = [0_u8; 32];
target[26..28].fill(0xff);
miner.submit(header, target, 0x18)?;
let share = miner.poll()?.ok_or("missing captured nonce report")?;
miner.stop()?;
assert_eq!(share.nonce, nonce);
println!("{chip} captured report verified at difficulty 1");
Ok(())
}
+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}
}
]
}
+618
View File
@@ -0,0 +1,618 @@
{
"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/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": []
}
+589
View File
@@ -0,0 +1,589 @@
// 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::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>,
) -> 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 snapshot = Arc::clone(&status);
handles.push(std::thread::spawn(move || {
if let Err(error) = web::serve_listener(listener, snapshot) {
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 servers = start(
Arc::clone(&status),
Some("127.0.0.1:0".parse().unwrap()),
Some("127.0.0.1:0".parse().unwrap()),
)
.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).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(_))
));
}
}
+21
View File
@@ -0,0 +1,21 @@
// 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()}));
}
+68
View File
@@ -0,0 +1,68 @@
// 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}");
}
}
+232
View File
@@ -0,0 +1,232 @@
// SPDX-License-Identifier: MIT
//! BM1362 frame encoding from captured command and job traffic.
//!
//! These pure encoders do not initialize a chain. PLL fields, voltage, and
//! model-specific operating points still require silicon-backed validation.
use crate::bm13xx::{crc16, crc5, reverse_words};
pub const JOB_BYTES: usize = 88;
pub const CHIP_ADDRESS_STEP: u8 = 2;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ModelGeometry {
chips_per_chain: u8,
ticket_mask: u8,
}
pub const S19J_PRO: ModelGeometry = ModelGeometry {
chips_per_chain: 126,
ticket_mask: 0x7f,
};
pub const S19J: ModelGeometry = ModelGeometry {
chips_per_chain: 108,
ticket_mask: 0x7f,
};
pub const S19_88: ModelGeometry = ModelGeometry {
chips_per_chain: 88,
ticket_mask: 0x3f,
};
impl ModelGeometry {
pub const fn new(chips_per_chain: u8, ticket_mask: u8) -> Option<Self> {
if chips_per_chain == 0 || chips_per_chain > 128 {
return None;
}
Some(Self {
chips_per_chain,
ticket_mask,
})
}
pub const fn chips_per_chain(self) -> u8 {
self.chips_per_chain
}
pub const fn ticket_mask(self) -> u8 {
self.ticket_mask
}
/// Addresses for an observed two-address-step enumeration walk.
pub fn chip_addresses(self) -> impl Iterator<Item = u8> {
(0..self.chips_per_chain).map(|index| index * CHIP_ADDRESS_STEP)
}
}
fn short_command(code: u8, address: u8, register: u8) -> [u8; 7] {
let mut frame = [0x55, 0xaa, code, 0x05, address, register, 0];
frame[6] = crc5(&frame[2..6]);
frame
}
fn long_command(code: u8, address: u8, register: u8, value: u32) -> [u8; 11] {
let mut frame = [0_u8; 11];
frame[..6].copy_from_slice(&[0x55, 0xaa, code, 0x09, address, register]);
frame[6..10].copy_from_slice(&value.to_be_bytes());
frame[10] = crc5(&frame[2..10]);
frame
}
pub fn chain_inactive() -> [u8; 7] {
short_command(0x53, 0, 0)
}
pub fn set_chip_address(address: u8) -> [u8; 7] {
short_command(0x40, address, 0)
}
pub fn read_register(address: u8, register: u8) -> [u8; 7] {
short_command(0x42, address, register)
}
pub fn read_register_all(register: u8) -> [u8; 7] {
short_command(0x52, 0, register)
}
pub fn write_register(address: u8, register: u8, value: u32) -> [u8; 11] {
long_command(0x41, address, register, value)
}
pub fn write_register_all(register: u8, value: u32) -> [u8; 11] {
long_command(0x51, 0, register, value)
}
/// Raw header fields in BM1362 wire order. The caller owns work-ID allocation
/// and must supply roots and hashes in the order established by its capture.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Job {
pub work_id: u8,
pub num_midstates: u8,
pub start_nonce: u32,
pub nbits: u32,
pub ntime: u32,
pub merkle_root: [u8; 32],
pub previous_hash: [u8; 32],
pub version: u32,
}
/// Encode the 88-byte SEND_JOB form with the true-length tag observed on wire.
pub fn encode_job(job: &Job) -> [u8; JOB_BYTES] {
let mut frame = [0_u8; JOB_BYTES];
frame[..6].copy_from_slice(&[0x55, 0xaa, 0x21, 0x56, job.work_id, job.num_midstates]);
frame[6..10].copy_from_slice(&job.start_nonce.to_le_bytes());
frame[10..14].copy_from_slice(&job.nbits.to_le_bytes());
frame[14..18].copy_from_slice(&job.ntime.to_le_bytes());
frame[18..50].copy_from_slice(&job.merkle_root);
frame[50..82].copy_from_slice(&job.previous_hash);
frame[82..86].copy_from_slice(&job.version.to_le_bytes());
let checksum = crc16(&frame[2..86]);
frame[86..88].copy_from_slice(&checksum.to_be_bytes());
frame
}
/// Encode one nonce-zero pool header in the observed raw-header job layout.
/// This covers work delivery; chain initialization still needs board evidence.
pub fn encode_work(header: &[u8; 80], work_id: u8) -> Option<[u8; JOB_BYTES]> {
if header[76..80] != [0; 4] || work_id & 7 != 0 {
return None;
}
Some(encode_job(&Job {
work_id,
num_midstates: 1,
start_nonce: 0,
nbits: u32::from_le_bytes(header[72..76].try_into().expect("nbits")),
ntime: u32::from_le_bytes(header[68..72].try_into().expect("ntime")),
merkle_root: reverse_words(&header[36..68]),
previous_hash: reverse_words(&header[4..36]),
version: u32::from_le_bytes(header[..4].try_into().expect("version")),
}))
}
/// BT8D for a 25 MHz input clock with BCLK_SEL=0. A model must still choose
/// the actual target baud and confirm switching on silicon.
pub fn bt8d_for_baud(baud: u32) -> Option<u8> {
if baud == 0 || baud > 3_125_000 {
return None;
}
let divider = 25_000_000_u64 / (8 * u64::from(baud));
u8::try_from(divider - 1).ok()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn captured_command_frames() {
assert_eq!(chain_inactive(), [0x55, 0xaa, 0x53, 5, 0, 0, 3]);
assert_eq!(set_chip_address(0), [0x55, 0xaa, 0x40, 5, 0, 0, 0x1c]);
assert_eq!(set_chip_address(8), [0x55, 0xaa, 0x40, 5, 8, 0, 7]);
assert_eq!(read_register_all(0), [0x55, 0xaa, 0x52, 5, 0, 0, 0x0a]);
assert_eq!(
read_register(0x40, 0x1c),
[0x55, 0xaa, 0x42, 5, 0x40, 0x1c, 0x0b]
);
assert_eq!(
write_register_all(0x80, 0),
[0x55, 0xaa, 0x51, 9, 0, 0x80, 0, 0, 0, 0, 0x1c]
);
assert_eq!(
write_register(0x40, 0x18, 0x7a31),
[0x55, 0xaa, 0x41, 9, 0x40, 0x18, 0, 0, 0x7a, 0x31, 0x11]
);
}
#[test]
fn model_address_limits() {
assert_eq!(ModelGeometry::new(0, 0), None);
assert_eq!(ModelGeometry::new(129, 0), None);
assert_eq!(
ModelGeometry::new(128, 0).unwrap().chip_addresses().last(),
Some(0xfe)
);
assert_eq!(S19J_PRO.chip_addresses().last(), Some(0xfa));
assert_eq!(S19J.chip_addresses().last(), Some(0xd6));
assert_eq!(S19_88.chip_addresses().last(), Some(0xae));
}
#[test]
fn job_frame_layout() {
let mut merkle_root = [0_u8; 32];
let mut previous_hash = [0_u8; 32];
for index in 0..32 {
merkle_root[index] = 0xa0 + index as u8;
previous_hash[index] = 0x10 + index as u8;
}
let frame = encode_job(&Job {
work_id: 8,
num_midstates: 1,
start_nonce: 0,
nbits: 0x1a1f_2c34,
ntime: 0x5e9b_3cd4,
merkle_root,
previous_hash,
version: 0x2000_0000,
});
assert_eq!(
&frame[..18],
&[
0x55, 0xaa, 0x21, 0x56, 8, 1, 0, 0, 0, 0, 0x34, 0x2c, 0x1f, 0x1a, 0xd4, 0x3c, 0x9b,
0x5e
]
);
assert_eq!(&frame[18..50], &merkle_root);
assert_eq!(&frame[50..82], &previous_hash);
assert_eq!(&frame[82..86], &[0, 0, 0, 0x20]);
assert_eq!(&frame[86..88], &[0xc2, 0xbd]);
assert_eq!(
u16::from_be_bytes([frame[86], frame[87]]),
crc16(&frame[2..86])
);
}
#[test]
fn baud_dividers() {
assert_eq!(bt8d_for_baud(0), None);
assert_eq!(bt8d_for_baud(3_000_000), Some(0));
assert_eq!(bt8d_for_baud(115_200), Some(26));
assert_eq!(bt8d_for_baud(1), None);
assert_eq!(bt8d_for_baud(3_125_001), None);
assert_eq!(bt8d_for_baud(u32::MAX), None);
}
}
+120
View File
@@ -0,0 +1,120 @@
// SPDX-License-Identifier: MIT
//! BM1366 work and response framing. Nonces only come from a device or replay.
pub const WORK_BYTES: usize = 88;
pub const REPORT_BYTES: usize = 11;
pub use crate::bm13xx::crc16;
use crate::bm13xx::{crc5, reverse_words};
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct NonceReport {
pub nonce: u32,
pub work_id: u8,
pub version_field: u16,
pub chip_address: u8,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ReportError {
Length,
Preamble,
RegisterResponse,
Checksum,
}
/// Encode a nonce-zero Bitcoin header for the observed 88-byte SEND_JOB form.
/// The low three work-ID bits are reserved by the BM1366 response format.
pub fn encode_work(header: &[u8; 80], work_id: u8) -> Option<[u8; WORK_BYTES]> {
if header[76..80] != [0; 4] || work_id & 7 != 0 {
return None;
}
let mut frame = [0_u8; WORK_BYTES];
frame[..4].copy_from_slice(&[0x55, 0xaa, 0x21, 0x54]);
frame[4] = work_id;
// The captured 88-byte on-die-midstate job uses one midstate.
frame[5] = 1;
frame[10..14].copy_from_slice(&header[72..76]);
frame[14..18].copy_from_slice(&header[68..72]);
frame[18..50].copy_from_slice(&reverse_words(&header[36..68]));
frame[50..82].copy_from_slice(&reverse_words(&header[4..36]));
frame[82..86].copy_from_slice(&header[..4]);
let checksum = crc16(&frame[2..86]);
frame[86..88].copy_from_slice(&checksum.to_be_bytes());
Some(frame)
}
/// Parse an observed nonce report; register replies must use a separate path.
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")),
chip_address: frame[6],
work_id: frame[7] & 0xf8,
version_field: u16::from_be_bytes(frame[8..10].try_into().expect("version field")),
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn crc16_reference_vector() {
assert_eq!(crc16(b"123456789"), 0x29b1);
}
#[test]
fn captured_work_and_response() {
let header: [u8; 80] = hex_header();
let frame = encode_work(&header, 0x18).unwrap();
assert_eq!(&frame[..5], &[0x55, 0xaa, 0x21, 0x54, 0x18]);
assert_eq!(frame[5], 1);
assert_eq!(
crc16(&frame[2..86]),
u16::from_be_bytes([frame[86], frame[87]])
);
assert_eq!(&frame[10..14], &header[72..76]);
assert_eq!(&frame[82..86], &header[..4]);
assert!(encode_work(&header, 0x19).is_none());
let mut with_nonce = header;
with_nonce[76] = 1;
assert!(encode_work(&with_nonce, 0x18).is_none());
let report = [
0xaa, 0x55, 0x38, 0xff, 0xad, 0xed, 0, 0x18, 0x04, 0xb3, 0x94,
];
let parsed = decode_nonce_report(&report).unwrap();
assert_eq!(parsed.nonce, 0xedad_ff38);
assert_eq!(parsed.work_id, 0x18);
assert_eq!(parsed.version_field, 0x04b3);
let mut corrupt = report;
corrupt[4] ^= 1;
assert_eq!(decode_nonce_report(&corrupt), Err(ReportError::Checksum));
}
fn hex_header() -> [u8; 80] {
let input = concat!(
"00000020fc3ab8d43021f45eb662389d0f791f657dbf75a5cb93670b57b6c22503",
"b4213a43ae1052ebd44443068fe178e2c61ca4994846fd133addb04aab2b382c5",
"b4c74c1012e6a8f06021700000000"
);
let mut header = [0_u8; 80];
for (index, bytes) in input.as_bytes().chunks_exact(2).enumerate() {
let pair = std::str::from_utf8(bytes).unwrap();
header[index] = u8::from_str_radix(pair, 16).unwrap();
}
header
}
}
+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());
}
}
+66
View File
@@ -0,0 +1,66 @@
// SPDX-License-Identifier: MIT
//! Shared BM13xx wire checksums. This module never generates mining nonces.
/// Reverse the eight 32-bit header words for the observed SEND_JOB layout.
pub(crate) fn reverse_words(input: &[u8]) -> [u8; 32] {
let mut output = [0_u8; 32];
for index in 0..8 {
output[index * 4..index * 4 + 4].copy_from_slice(&input[(7 - index) * 4..(8 - index) * 4]);
}
output
}
/// CRC5 used by command and nonce-report frames, initial value 0x1f.
pub fn crc5(bytes: &[u8]) -> u8 {
let mut state = 0x1f_u8;
for &byte in bytes {
for bit in (0..8).rev() {
let feedback = ((state >> 4) ^ (byte >> bit)) & 1;
state = ((state << 1) | feedback) & 0x1f;
state ^= feedback << 2;
}
}
state
}
/// CRC16-CCITT-FALSE used by 88-byte SEND_JOB frames.
pub fn crc16(bytes: &[u8]) -> u16 {
let mut state = 0xffff_u16;
for &byte in bytes {
state ^= u16::from(byte) << 8;
for _ in 0..8 {
state = if state & 0x8000 == 0 {
state << 1
} else {
(state << 1) ^ 0x1021
};
}
}
state
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn captured_command_checksums() {
let vectors: &[(&[u8], u8)] = &[
(&[0x53, 0x05, 0, 0], 0x03),
(&[0x40, 0x05, 0, 0], 0x1c),
(&[0x52, 0x05, 0, 0], 0x0a),
(&[0x40, 0x05, 8, 0], 0x07),
(&[0x42, 0x05, 0x40, 0x1c], 0x0b),
(&[0x51, 0x09, 0, 0x80, 0, 0, 0, 0], 0x1c),
(&[0x41, 0x09, 0x40, 0x18, 0, 0, 0x7a, 0x31], 0x11),
];
for &(body, expected) in vectors {
assert_eq!(crc5(body), expected);
}
}
#[test]
fn standard_crc16_check() {
assert_eq!(crc16(b"123456789"), 0x29b1);
}
}
+364
View File
@@ -0,0 +1,364 @@
// 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::url::Routes;
use flare_ui::render::{self, View};
use flare_ui::shell::{self, Active};
use flare_ui::tokens;
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());
if let Some(parent) = self.path.parent() {
let _ = fs::create_dir_all(parent);
}
// Persist only after validation passed; a failed write leaves the rows
// changed in memory but never on disk, which the API reports.
let _ = fs::write(&self.path, text);
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 = percent_decode(raw_key);
let raw = 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 percent_decode(text: &str) -> String {
let bytes = text.as_bytes();
let mut out = Vec::with_capacity(bytes.len());
let mut index = 0;
while index < bytes.len() {
match bytes[index] {
b'+' => {
out.push(b' ');
index += 1;
}
b'%' if index + 2 < bytes.len() => {
let high = (bytes[index + 1] as char).to_digit(16);
let low = (bytes[index + 2] as char).to_digit(16);
match (high, low) {
(Some(high), Some(low)) => {
out.push((high * 16 + low) as u8);
index += 3;
}
_ => {
out.push(bytes[index]);
index += 1;
}
}
}
byte => {
out.push(byte);
index += 1;
}
}
}
String::from_utf8_lossy(&out).into_owned()
}
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(), 17);
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);
}
#[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!(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);
}
}
+120
View File
@@ -0,0 +1,120 @@
// SPDX-License-Identifier: MIT
//! Exact Bitcoin Stratum share target conversion; no floating point or nonce search.
use serde_json::Number;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum DifficultyError {
Invalid,
OutOfRange,
}
/// A positive decimal difficulty represented exactly as numerator/denominator.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct PoolDifficulty {
numerator: u64,
denominator: u64,
}
impl PoolDifficulty {
pub fn from_json_number(number: &Number) -> Result<Self, DifficultyError> {
let text = number.as_str();
if text.len() > 128 || text.starts_with('-') {
return Err(DifficultyError::OutOfRange);
}
let (mantissa, exponent) = match text.split_once(['e', 'E']) {
Some((base, exponent)) => (
base,
exponent
.parse::<i32>()
.map_err(|_| DifficultyError::OutOfRange)?,
),
None => (text, 0),
};
let mut digits = Vec::with_capacity(mantissa.len());
let mut fractional = 0_i32;
let mut after_dot = false;
for byte in mantissa.bytes() {
match byte {
b'.' if !after_dot => after_dot = true,
b'0'..=b'9' => {
digits.push(byte - b'0');
if after_dot {
fractional += 1;
}
}
_ => return Err(DifficultyError::Invalid),
}
}
let first = digits
.iter()
.position(|digit| *digit != 0)
.ok_or(DifficultyError::Invalid)?;
let last = digits
.iter()
.rposition(|digit| *digit != 0)
.expect("nonzero digit");
let trailing = (digits.len() - last - 1) as i32;
let mut numerator = 0_u64;
for digit in &digits[first..=last] {
numerator = numerator
.checked_mul(10)
.and_then(|value| value.checked_add(u64::from(*digit)))
.ok_or(DifficultyError::OutOfRange)?;
}
let shift = exponent
.checked_sub(fractional)
.and_then(|value| value.checked_add(trailing))
.ok_or(DifficultyError::OutOfRange)?;
if !(-19..=19).contains(&shift) {
return Err(DifficultyError::OutOfRange);
}
let mut denominator = 1_u64;
if shift >= 0 {
for _ in 0..shift {
numerator = numerator
.checked_mul(10)
.ok_or(DifficultyError::OutOfRange)?;
}
} else {
for _ in 0..-shift {
denominator = denominator
.checked_mul(10)
.ok_or(DifficultyError::OutOfRange)?;
}
}
Ok(Self {
numerator,
denominator,
})
}
/// floor((0xFFFF << 208) / difficulty), capped at the 256-bit maximum.
/// The 320-bit intermediate permits all supported decimal denominators.
pub fn target_le(self) -> [u8; 32] {
let mut product = [0_u8; 40];
let mut carry = 0_u128;
for (index, byte) in product.iter_mut().enumerate() {
let diff_one_byte = if index == 26 || index == 27 { 0xff } else { 0 };
let value = (diff_one_byte as u128) * u128::from(self.denominator) + carry;
*byte = value as u8;
carry = value >> 8;
}
debug_assert_eq!(carry, 0);
let mut quotient = [0_u8; 40];
let mut remainder = 0_u128;
for index in (0..320).rev() {
let bit = (product[index / 8] >> (index % 8)) & 1;
remainder = (remainder << 1) | u128::from(bit);
if remainder >= u128::from(self.numerator) {
remainder -= u128::from(self.numerator);
quotient[index / 8] |= 1 << (index % 8);
}
}
if quotient[32..].iter().any(|byte| *byte != 0) {
return [0xff; 32];
}
quotient[..32].try_into().expect("256-bit quotient")
}
}
+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]);
}
}
+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");
}
}
+691
View File
@@ -0,0 +1,691 @@
// 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};
use std::net::Shutdown;
use std::os::fd::{AsRawFd, FromRawFd, OwnedFd};
use std::os::unix::ffi::OsStrExt;
use std::os::unix::net::UnixStream;
use std::path::Path;
use std::time::{Duration, Instant};
const MAGIC: [u8; 4] = *b"ALKH";
const VERSION: u8 = 1;
const RESPONSE: u16 = 1;
const HEADER_LEN: usize = 16;
const MAX_PAYLOAD: usize = 4096;
const IO_TIMEOUT: Duration = Duration::from_secs(2);
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;
/// 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");
#[cfg(target_os = "linux")]
mod sys {
pub use std::ffi::{c_char as CChar, c_int as CInt, c_void as CVoid};
pub type SaFamily = u16;
pub type SocklenT = u32;
pub const AF_UNIX: CInt = 1;
pub const SOCK_STREAM: CInt = 1;
pub const SOCK_NONBLOCK: CInt = 0x800;
pub const SOCK_CLOEXEC: CInt = 0x80000;
pub const SOL_SOCKET: CInt = 1;
pub const SO_ERROR: CInt = 4;
pub const POLLOUT: i16 = 4;
pub const EAGAIN: CInt = 11;
pub const EISCONN: CInt = 106;
pub const EINPROGRESS: CInt = 115;
#[repr(C)]
pub struct SockaddrUn {
pub sun_family: SaFamily,
pub sun_path: [CChar; 108],
}
#[repr(C)]
pub struct PollFd {
pub fd: CInt,
pub events: i16,
pub revents: i16,
}
extern "C" {
pub fn socket(domain: CInt, socket_type: CInt, protocol: CInt) -> CInt;
pub fn connect(fd: CInt, address: *const CVoid, length: SocklenT) -> CInt;
pub fn poll(fds: *mut PollFd, count: usize, timeout_ms: CInt) -> CInt;
pub fn getsockopt(
fd: CInt,
level: CInt,
name: CInt,
value: *mut CVoid,
length: *mut SocklenT,
) -> CInt;
}
}
#[derive(Debug)]
pub enum HalError {
Io(io::Error),
Protocol(&'static str),
Device(u8),
FrameTooLong,
InvalidFanPercent,
}
impl fmt::Display for HalError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Io(error) => write!(f, "HAL I/O: {error}"),
Self::Protocol(message) => write!(f, "HAL protocol: {message}"),
Self::Device(code) => write!(f, "HAL device error: {code}"),
Self::FrameTooLong => f.write_str("HAL frame exceeds the wire limit"),
Self::InvalidFanPercent => f.write_str("HAL fan target exceeds 100 percent"),
}
}
}
impl std::error::Error for HalError {}
impl From<io::Error> for HalError {
fn from(error: io::Error) -> Self {
Self::Io(error)
}
}
/// Local client for the privileged board backend supplied by the SDK image.
pub struct HalClient {
stream: UnixStream,
sequence: u32,
poisoned: bool,
}
impl HalClient {
fn poison(&mut self) {
self.poisoned = true;
let _ = self.stream.shutdown(Shutdown::Both);
}
pub fn connect(path: impl AsRef<Path>) -> Result<Self, HalError> {
let stream = connect_until(path.as_ref(), Instant::now() + IO_TIMEOUT)?;
Self::from_stream(stream)
}
pub fn from_stream(stream: UnixStream) -> Result<Self, HalError> {
stream.set_read_timeout(Some(IO_TIMEOUT))?;
stream.set_write_timeout(Some(IO_TIMEOUT))?;
Ok(Self {
stream,
sequence: 0,
poisoned: false,
})
}
fn exchange(&mut self, opcode: u8, payload: &[u8]) -> Result<Vec<u8>, HalError> {
if self.poisoned {
return Err(HalError::Protocol("connection is unusable"));
}
if payload.len() > MAX_PAYLOAD {
return Err(HalError::FrameTooLong);
}
let result = self.exchange_inner(opcode, payload);
if let Err(ref error) = result {
if !matches!(error, HalError::Device(_)) {
self.poison();
// A backend power lease must expire on disconnect. Reusing a
// desynchronized stream could silently discard an off request.
}
}
result
}
fn exchange_inner(&mut self, opcode: u8, payload: &[u8]) -> Result<Vec<u8>, HalError> {
let deadline = Instant::now() + IO_TIMEOUT;
self.sequence = self.sequence.wrapping_add(1);
let sequence = self.sequence;
let mut header = [0_u8; HEADER_LEN];
header[..4].copy_from_slice(&MAGIC);
header[4] = VERSION;
header[5] = opcode;
header[8..12].copy_from_slice(&sequence.to_le_bytes());
header[12..16].copy_from_slice(&(payload.len() as u32).to_le_bytes());
write_all_until(&mut self.stream, &header, deadline)?;
write_all_until(&mut self.stream, payload, deadline)?;
read_exact_until(&mut self.stream, &mut header, deadline)?;
if header[..4] != MAGIC || header[4] != VERSION || header[5] != opcode {
return Err(HalError::Protocol("response identity mismatch"));
}
if u16::from_le_bytes([header[6], header[7]]) != RESPONSE {
return Err(HalError::Protocol("response flag missing"));
}
if u32::from_le_bytes(header[8..12].try_into().unwrap()) != sequence {
return Err(HalError::Protocol("response sequence mismatch"));
}
let length = u32::from_le_bytes(header[12..16].try_into().unwrap()) as usize;
if !(1..=MAX_PAYLOAD).contains(&length) {
return Err(HalError::Protocol("invalid response length"));
}
let mut body = vec![0_u8; length];
read_exact_until(&mut self.stream, &mut body, deadline)?;
if body[0] != 0 {
if !matches!(body[0], 1..=3) || body.len() != 1 {
return Err(HalError::Protocol("invalid error response"));
}
return Err(HalError::Device(body[0]));
}
Ok(body[1..].to_vec())
}
fn empty_reply(&mut self, opcode: u8, payload: &[u8]) -> Result<(), HalError> {
if !self.exchange(opcode, payload)?.is_empty() {
self.poison();
return Err(HalError::Protocol("unexpected response data"));
}
Ok(())
}
}
fn timeout_error() -> io::Error {
io::Error::new(io::ErrorKind::TimedOut, "HAL operation timed out")
}
fn remaining(deadline: Instant) -> io::Result<Duration> {
deadline
.checked_duration_since(Instant::now())
.filter(|duration| !duration.is_zero())
.ok_or_else(timeout_error)
}
fn write_all_until(stream: &mut UnixStream, mut data: &[u8], deadline: Instant) -> io::Result<()> {
while !data.is_empty() {
stream.set_write_timeout(Some(remaining(deadline)?))?;
match stream.write(data) {
Ok(0) => {
return Err(io::Error::new(
io::ErrorKind::WriteZero,
"HAL socket closed",
))
}
Ok(count) => data = &data[count..],
Err(error) if error.kind() == io::ErrorKind::Interrupted => continue,
Err(error) => return Err(error),
}
}
Ok(())
}
fn read_exact_until(
stream: &mut UnixStream,
mut data: &mut [u8],
deadline: Instant,
) -> io::Result<()> {
while !data.is_empty() {
stream.set_read_timeout(Some(remaining(deadline)?))?;
match stream.read(data) {
Ok(0) => {
return Err(io::Error::new(
io::ErrorKind::UnexpectedEof,
"HAL socket closed",
))
}
Ok(count) => data = &mut data[count..],
Err(error) if error.kind() == io::ErrorKind::Interrupted => continue,
Err(error) => return Err(error),
}
}
Ok(())
}
fn connect_until(path: &Path, deadline: Instant) -> io::Result<UnixStream> {
let bytes = path.as_os_str().as_bytes();
let max_path =
std::mem::size_of::<sys::SockaddrUn>() - std::mem::offset_of!(sys::SockaddrUn, sun_path);
if bytes.is_empty() || bytes.len() >= max_path || bytes.contains(&0) {
return Err(io::Error::new(
io::ErrorKind::InvalidInput,
"invalid HAL socket path",
));
}
let raw = unsafe {
sys::socket(
sys::AF_UNIX,
sys::SOCK_STREAM | sys::SOCK_NONBLOCK | sys::SOCK_CLOEXEC,
0,
)
};
if raw < 0 {
return Err(io::Error::last_os_error());
}
let fd = unsafe { OwnedFd::from_raw_fd(raw) };
let mut address: sys::SockaddrUn = unsafe { std::mem::zeroed() };
address.sun_family = sys::AF_UNIX as sys::SaFamily;
for (destination, source) in address.sun_path.iter_mut().zip(bytes) {
*destination = *source as sys::CChar;
}
let length =
(std::mem::offset_of!(sys::SockaddrUn, sun_path) + bytes.len() + 1) as sys::SocklenT;
loop {
let result = unsafe {
sys::connect(
fd.as_raw_fd(),
&address as *const _ as *const sys::CVoid,
length,
)
};
if result == 0 {
break;
}
let error = io::Error::last_os_error();
if error.raw_os_error() == Some(sys::EISCONN) {
break;
}
if !matches!(
error.raw_os_error(),
Some(sys::EINPROGRESS) | Some(sys::EAGAIN)
) {
return Err(error);
}
let mut poll_fd = sys::PollFd {
fd: fd.as_raw_fd(),
events: sys::POLLOUT,
revents: 0,
};
let wait = remaining(deadline)?.as_millis().min(i32::MAX as u128) as i32;
let polled = unsafe { sys::poll(&mut poll_fd, 1, wait.max(1)) };
if polled < 0 {
let error = io::Error::last_os_error();
if error.kind() == io::ErrorKind::Interrupted {
continue;
}
return Err(error);
}
if polled == 0 {
return Err(timeout_error());
}
let mut socket_error: sys::CInt = 0;
let mut socket_error_len = std::mem::size_of_val(&socket_error) as sys::SocklenT;
if unsafe {
sys::getsockopt(
fd.as_raw_fd(),
sys::SOL_SOCKET,
sys::SO_ERROR,
&mut socket_error as *mut _ as *mut sys::CVoid,
&mut socket_error_len,
)
} < 0
{
return Err(io::Error::last_os_error());
}
if socket_error != 0 {
return Err(io::Error::from_raw_os_error(socket_error));
}
if error.raw_os_error() == Some(sys::EINPROGRESS) {
break;
}
}
let stream = UnixStream::from(fd);
stream.set_nonblocking(false)?;
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;
fn send_frame(&mut self, chain: u8, frame: &[u8]) -> Result<(), Self::Error> {
if frame.len() > MAX_PAYLOAD - 3 {
return Err(HalError::FrameTooLong);
}
let mut body = Vec::with_capacity(frame.len() + 3);
body.push(chain);
body.extend_from_slice(&(frame.len() as u16).to_le_bytes());
body.extend_from_slice(frame);
self.empty_reply(SEND_FRAME, &body)
}
fn receive_frame(&mut self, chain: u8, frame: &mut [u8]) -> Result<usize, Self::Error> {
if frame.len() > MAX_PAYLOAD - 3 {
return Err(HalError::FrameTooLong);
}
let mut request = [0_u8; 3];
request[0] = chain;
request[1..].copy_from_slice(&(frame.len() as u16).to_le_bytes());
let body = self.exchange(RECEIVE_FRAME, &request)?;
if body.len() < 2 {
self.poison();
return Err(HalError::Protocol("missing receive length"));
}
let count = u16::from_le_bytes([body[0], body[1]]) as usize;
if count > frame.len() || body.len() != count + 2 {
self.poison();
return Err(HalError::Protocol("invalid received frame size"));
}
frame[..count].copy_from_slice(&body[2..]);
Ok(count)
}
fn set_chain_reset(&mut self, chain: u8, asserted: bool) -> Result<(), Self::Error> {
self.empty_reply(SET_CHAIN_RESET, &[chain, u8::from(asserted)])
}
fn set_fan_target(&mut self, fan: u8, percent: u8) -> Result<(), Self::Error> {
if percent > 100 {
return Err(HalError::InvalidFanPercent);
}
self.empty_reply(SET_FAN_TARGET, &[fan, percent])
}
fn read_temperature_mc(&mut self, sensor: u8) -> Result<i32, Self::Error> {
let body = self.exchange(READ_TEMPERATURE, &[sensor])?;
let bytes: [u8; 4] = match body.try_into() {
Ok(bytes) => bytes,
Err(_) => {
self.poison();
return Err(HalError::Protocol("invalid temperature response"));
}
};
Ok(i32::from_le_bytes(bytes))
}
fn set_psu_enabled(&mut self, enabled: bool) -> Result<(), Self::Error> {
let result = self.empty_reply(SET_PSU_ENABLED, &[u8::from(enabled)]);
if !enabled && result.is_err() {
self.poison();
}
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");
}
}
+34
View File
@@ -3,6 +3,40 @@
//! 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 bm1362;
pub mod bm1366;
pub mod bm1370;
pub mod bm13xx;
pub mod detect;
pub mod dashboard;
pub mod difficulty;
pub mod fanmap;
pub mod fanmap_store;
pub mod fault;
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 runtime;
pub mod scrypt_pow;
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 {
Bitmain,
+431 -2
View File
@@ -1,7 +1,343 @@
// SPDX-License-Identifier: MIT
use alkane_os::app;
use alkane_os::detect::{
ChipModel as DetectedChip, DetectionBackend, EepromState, Envelope, ProbeBudget, ProbeOutcome,
PsuCapability, SensorTopology,
};
use alkane_os::hal_wire::HalClient;
use alkane_os::management::MiningStatus;
use alkane_os::miner::{Bm1366Miner, ChipModel};
use alkane_os::runtime::{Tick, TickOutcome};
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;
use std::sync::Arc;
use std::time::Duration;
fn sim_mine(mut args: impl Iterator<Item = String>) -> Result<(), Box<dyn Error>> {
let socket = args.next().ok_or("missing HAL socket")?;
let address: SocketAddr = args.next().ok_or("missing pool address")?.parse()?;
let worker = args.next().ok_or("missing pool worker")?;
let chip = match args.next().as_deref() {
Some("BM1362") => ChipModel::Bm1362,
Some("BM1366") => ChipModel::Bm1366,
_ => return Err("select BM1362 or BM1366".into()),
};
let max_accepts: Option<u64> = args.next().map(|value| value.parse()).transpose()?;
if args.next().is_some() || worker.is_empty() || max_accepts == Some(0) {
return Err("invalid simulator mining arguments".into());
}
let password = std::env::var("ALKANE_POOL_PASSWORD")
.map_err(|_| "set ALKANE_POOL_PASSWORD in the environment")?;
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 servers = app::start(Arc::clone(&status), api, web)?;
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
// power lease and cuts power if this process stalls or disconnects.
let mut pool = PoolConnection::connect(
address,
concat!("alkane-os/", env!("CARGO_PKG_VERSION")),
&worker,
&password,
Duration::from_secs(2),
Duration::from_secs(5),
)
.map_err(|error| io::Error::other(format!("pool handshake: {error:?}")))?;
let mut backend = HalClient::connect(socket)?;
let mut miner = Bm1366Miner::new_for_chip(&mut backend, chip, 0, 0, 0, 100, 80_000)
.ok_or("invalid simulator safety configuration")?;
miner.start()?;
status.set_running(true);
let mut accepted = 0_u64;
loop {
let (event, reports) = pool
.cycle(&mut miner)
.map_err(|error| io::Error::other(format!("mining cycle: {error:?}")))?;
match event {
PoolEvent::ShareAccepted(_) => {
accepted += 1;
status.share_accepted();
if max_accepts == Some(accepted) {
miner.stop()?;
status.set_running(false);
println!("simulator shares accepted: {accepted}");
return Ok(());
}
}
PoolEvent::ShareRejected(id) => {
status.share_rejected();
eprintln!("pool rejected share request {id}");
}
_ => {}
}
if matches!(event, PoolEvent::Idle) && reports.is_empty() {
std::thread::sleep(Duration::from_millis(10));
}
}
}
/// 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 servers = app::start(Arc::clone(&status), api, web)?;
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));
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 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()?;
let api = api.or(Some("0.0.0.0:4028".parse()?));
let servers = app::start(Arc::clone(&status), api, web_listen()?)?;
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() {
match std::env::args().nth(1).as_deref() {
let mut args = std::env::args().skip(1);
match args.next().as_deref() {
Some("--list-targets") => {
println!("control_board,hash_chip,algorithm");
for target in target_matrix() {
@@ -12,8 +348,101 @@ 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("--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}");
std::process::exit(1);
}
}
_ => {
eprintln!("usage: alkane-os --list-targets | --version");
eprintln!("usage: alkane-os --list-targets | --version | --self-check | --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);
}
}
+445
View File
@@ -0,0 +1,445 @@
// 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 {
fn default() -> Self {
Self::new()
}
}
impl MiningStatus {
pub fn new() -> Self {
Self {
started: Instant::now(),
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);
}
pub fn share_accepted(&self) {
self.accepted.fetch_add(1, Ordering::Relaxed);
}
pub fn share_rejected(&self) {
self.rejected.fetch_add(1, Ordering::Relaxed);
}
fn response(&self, command: &str) -> Value {
let now = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap_or_default()
.as_secs();
let (code, description, payload) = match command {
"summary" => (
"S",
"Summary",
json!({"SUMMARY": [{
"Elapsed": self.started.elapsed().as_secs(),
"Accepted": self.accepted.load(Ordering::Relaxed),
"Rejected": self.rejected.load(Ordering::Relaxed),
"Status": if self.running.load(Ordering::Relaxed) { "Mining" } else { "Stopped" }
}]}),
),
"version" => (
"S",
"Version",
json!({"VERSION": [{
"Miner": concat!("alkane-os/", env!("CARGO_PKG_VERSION")),
"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": [{
"STATUS": code,
"When": now,
"Code": if code == "S" { 0 } else { 14 },
"Msg": description,
"Description": "alkane-os"
}]});
response
.as_object_mut()
.unwrap()
.extend(payload.as_object().unwrap().clone());
response
}
}
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('{') {
let value: Value = serde_json::from_str(request).ok()?;
let command = value.get("command")?.as_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"),
}
}
}
fn handle(mut stream: TcpStream, status: &MiningStatus) -> io::Result<()> {
stream.set_write_timeout(Some(CLIENT_TIMEOUT))?;
let mut request = Vec::new();
let mut chunk = [0_u8; 256];
let deadline = Instant::now() + REQUEST_DEADLINE;
loop {
let remaining = deadline.saturating_duration_since(Instant::now());
if remaining.is_zero() {
return Err(io::Error::new(
io::ErrorKind::TimedOut,
"management request deadline",
));
}
stream.set_read_timeout(Some(CLIENT_TIMEOUT.min(remaining)))?;
let count = match stream.read(&mut chunk) {
Ok(count) => count,
Err(error) if error.kind() == io::ErrorKind::TimedOut && !request.is_empty() => break,
Err(error) if error.kind() == io::ErrorKind::WouldBlock && !request.is_empty() => break,
Err(error) => return Err(error),
};
if count == 0 {
break;
}
if request.len() + count > MAX_REQUEST_BYTES {
return Err(io::Error::new(
io::ErrorKind::InvalidData,
"management request too large",
));
}
request.extend_from_slice(&chunk[..count]);
if request.contains(&b'\n') || request.contains(&0) {
break;
}
if matches!(request_command(&request), Some("summary" | "version"))
|| serde_json::from_slice::<Value>(&request).is_ok()
{
break;
}
}
let end = request
.iter()
.position(|byte| *byte == 0 || *byte == b'\n')
.unwrap_or(request.len());
let command = request_command(&request[..end]).unwrap_or("unknown");
let mut reply = serde_json::to_vec(&status.response(command)).map_err(io::Error::other)?;
reply.push(0);
stream.write_all(&reply)
}
/// Bind only to loopback. The board management plane can be reached through SSH.
pub fn bind_local(address: SocketAddr) -> io::Result<TcpListener> {
if !address.ip().is_loopback() {
return Err(io::Error::new(
io::ErrorKind::InvalidInput,
"management API requires loopback address",
));
}
TcpListener::bind(address)
}
pub fn serve(listener: TcpListener, status: Arc<MiningStatus>) -> io::Result<()> {
for stream in listener.incoming() {
let stream = stream?;
if let Err(error) = handle(stream, &status) {
eprintln!("management request failed: {error}");
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use std::net::TcpStream;
#[test]
fn refuses_nonlocal_bind() {
let address = "0.0.0.0:0".parse().unwrap();
assert_eq!(
bind_local(address).unwrap_err().kind(),
io::ErrorKind::InvalidInput
);
}
#[test]
fn reports_only_observed_share_counts() {
let status = MiningStatus::new();
status.set_running(true);
status.share_accepted();
status.share_rejected();
let reply = status.response("summary");
assert_eq!(reply["SUMMARY"][0]["Accepted"], 1);
assert_eq!(reply["SUMMARY"][0]["Rejected"], 1);
assert_eq!(reply["SUMMARY"][0]["Status"], "Mining");
assert!(reply["SUMMARY"][0].get("MHS av").is_none());
}
#[test]
fn local_socket_uses_nul_terminated_cgminer_envelope() {
let listener = bind_local("127.0.0.1:0".parse().unwrap()).unwrap();
let address = listener.local_addr().unwrap();
let status = Arc::new(MiningStatus::new());
let worker = std::thread::spawn(move || {
let (stream, _) = listener.accept().unwrap();
handle(stream, &status).unwrap();
});
let mut client = TcpStream::connect(address).unwrap();
client.write_all(b"{\"command\":\"summary\"}\n").unwrap();
let mut reply = Vec::new();
client.read_to_end(&mut reply).unwrap();
assert_eq!(reply.pop(), Some(0));
let parsed: Value = serde_json::from_slice(&reply).unwrap();
assert_eq!(parsed["STATUS"][0]["STATUS"], "S");
assert_eq!(parsed["SUMMARY"][0]["Status"], "Stopped");
worker.join().unwrap();
}
#[test]
fn fragmented_plain_command_is_not_answered_early() {
let listener = bind_local("127.0.0.1:0".parse().unwrap()).unwrap();
let address = listener.local_addr().unwrap();
let status = Arc::new(MiningStatus::new());
let worker = std::thread::spawn(move || {
let (stream, _) = listener.accept().unwrap();
handle(stream, &status).unwrap();
});
let mut client = TcpStream::connect(address).unwrap();
client.write_all(b"sum").unwrap();
std::thread::sleep(Duration::from_millis(10));
client.write_all(b"mary").unwrap();
let mut reply = Vec::new();
client.read_to_end(&mut reply).unwrap();
assert_eq!(reply.pop(), Some(0));
let parsed: Value = serde_json::from_slice(&reply).unwrap();
assert_eq!(parsed["STATUS"][0]["STATUS"], "S");
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");
}
}
+327
View File
@@ -0,0 +1,327 @@
// SPDX-License-Identifier: MIT
//! One-chain BM13xx mining control built on the SDK hardware backend.
//! This module never searches for nonces or chooses board safety thresholds.
use crate::bm1362;
use crate::bm1366::{decode_nonce_report, encode_work, ReportError, REPORT_BYTES};
use crate::pow::verify_sha256_report;
use crate::{power_decision, HardwareBackend, PowerDecision};
use std::fmt;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ChipModel {
Bm1362,
Bm1366,
}
#[derive(Debug, Eq, PartialEq)]
pub enum MinerError<E> {
Backend(E),
AlreadyRunning,
NotRunning,
Faulted,
WorkIdInUse(u8),
UnsafeTemperature(i32),
InvalidWork,
InvalidReport(ReportError),
StaleReport,
BelowTarget,
}
impl<E: fmt::Display> fmt::Display for MinerError<E> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Backend(error) => write!(f, "hardware backend: {error}"),
Self::AlreadyRunning => f.write_str("miner is already running"),
Self::NotRunning => f.write_str("miner is not running"),
Self::Faulted => f.write_str("miner shutdown is unconfirmed"),
Self::WorkIdInUse(id) => write!(f, "BM13xx work ID {id} is still in use"),
Self::UnsafeTemperature(value) => write!(f, "unsafe temperature: {value} mC"),
Self::InvalidWork => f.write_str("invalid BM13xx work"),
Self::InvalidReport(error) => write!(f, "invalid BM13xx report: {error:?}"),
Self::StaleReport => f.write_str("stale BM13xx work ID"),
Self::BelowTarget => f.write_str("nonce is below the pool target"),
}
}
}
impl<E: std::error::Error + 'static> std::error::Error for MinerError<E> {}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ValidShare {
pub nonce: u32,
pub work_id: u8,
pub rolled_version: u32,
pub hash_le: [u8; 32],
}
#[derive(Clone, Copy)]
struct Work {
header: [u8; 80],
target_le: [u8; 32],
id: u8,
}
pub struct Bm1366Miner<'a, B: HardwareBackend> {
backend: &'a mut B,
chip: ChipModel,
chain: u8,
sensor: u8,
fan: u8,
fan_percent: u8,
max_temperature_mc: i32,
running: bool,
faulted: bool,
work: [Option<Work>; 32],
used_work_ids: [bool; 32],
}
impl<'a, B: HardwareBackend> Bm1366Miner<'a, B> {
/// The caller supplies a threshold validated for this board revision.
pub fn new(
backend: &'a mut B,
chain: u8,
sensor: u8,
fan: u8,
fan_percent: u8,
max_temperature_mc: i32,
) -> Option<Self> {
Self::new_for_chip(
backend,
ChipModel::Bm1366,
chain,
sensor,
fan,
fan_percent,
max_temperature_mc,
)
}
/// Select the captured BM1362 or BM1366 work format explicitly.
pub fn new_for_chip(
backend: &'a mut B,
chip: ChipModel,
chain: u8,
sensor: u8,
fan: u8,
fan_percent: u8,
max_temperature_mc: i32,
) -> Option<Self> {
if fan_percent == 0 || fan_percent > 100 || max_temperature_mc <= 0 {
return None;
}
Some(Self {
backend,
chip,
chain,
sensor,
fan,
fan_percent,
max_temperature_mc,
running: false,
faulted: false,
work: [None; 32],
used_work_ids: [false; 32],
})
}
fn power_off(&mut self) -> Result<(), B::Error> {
self.work = [None; 32];
match self.backend.set_psu_enabled(false) {
Ok(()) => {
self.running = false;
self.faulted = false;
self.used_work_ids = [false; 32];
Ok(())
}
Err(error) => {
// The backend may have left power on. Drop retries shutdown.
self.running = true;
self.faulted = true;
Err(error)
}
}
}
fn check_temperature(&mut self) -> Result<(), MinerError<B::Error>> {
let value = match self.backend.read_temperature_mc(self.sensor) {
Ok(value) => value,
Err(error) => {
let _ = self.power_off();
return Err(MinerError::Backend(error));
}
};
if power_decision(Some(value), self.max_temperature_mc) == PowerDecision::Stop {
let _ = self.power_off();
return Err(MinerError::UnsafeTemperature(value));
}
Ok(())
}
pub fn start(&mut self) -> Result<(), MinerError<B::Error>> {
if self.running {
return Err(MinerError::AlreadyRunning);
}
self.power_off().map_err(MinerError::Backend)?;
self.check_temperature()?;
self.backend
.set_fan_target(self.fan, self.fan_percent)
.map_err(MinerError::Backend)?;
if let Err(error) = self.backend.set_psu_enabled(true) {
let _ = self.power_off();
return Err(MinerError::Backend(error));
}
self.running = true;
if let Err(error) = self.backend.set_chain_reset(self.chain, true) {
let _ = self.power_off();
return Err(MinerError::Backend(error));
}
if let Err(error) = self.backend.set_chain_reset(self.chain, false) {
let _ = self.power_off();
return Err(MinerError::Backend(error));
}
Ok(())
}
pub fn stop(&mut self) -> Result<(), B::Error> {
self.power_off()
}
/// Flush the ASIC's in-flight work before reusing any work IDs. A reset
/// failure shuts the PSU down because old reports may still arrive.
pub fn reset_chain(&mut self) -> Result<(), MinerError<B::Error>> {
if !self.running {
return Err(MinerError::NotRunning);
}
if self.faulted {
return Err(MinerError::Faulted);
}
self.work = [None; 32];
self.check_temperature()?;
if let Err(error) = self.backend.set_chain_reset(self.chain, true) {
let _ = self.power_off();
return Err(MinerError::Backend(error));
}
if let Err(error) = self.backend.set_chain_reset(self.chain, false) {
let _ = self.power_off();
return Err(MinerError::Backend(error));
}
self.used_work_ids = [false; 32];
Ok(())
}
pub fn submit(
&mut self,
header: [u8; 80],
target_le: [u8; 32],
work_id: u8,
) -> Result<(), MinerError<B::Error>> {
if !self.running {
return Err(MinerError::NotRunning);
}
if self.faulted {
return Err(MinerError::Faulted);
}
self.check_temperature()?;
let frame = match self.chip {
ChipModel::Bm1362 => bm1362::encode_work(&header, work_id),
ChipModel::Bm1366 => encode_work(&header, work_id),
}
.ok_or(MinerError::InvalidWork)?;
let slot = usize::from(work_id >> 3);
if self.used_work_ids[slot] {
return Err(MinerError::WorkIdInUse(work_id));
}
// A failed send may still have reached the ASIC, so reserve first.
self.used_work_ids[slot] = true;
if let Err(error) = self.backend.send_frame(self.chain, &frame) {
let _ = self.power_off();
return Err(MinerError::Backend(error));
}
self.work[slot] = Some(Work {
header,
target_le,
id: work_id,
});
Ok(())
}
/// Forget prior pool jobs after `clean_jobs`, while leaving the ASIC powered.
/// Reports already in flight are then classified as stale. Their work IDs
/// remain reserved until a confirmed chain reset or PSU shutdown.
pub fn clear_work(&mut self) {
self.work = [None; 32];
}
pub fn poll(&mut self) -> Result<Option<ValidShare>, MinerError<B::Error>> {
if !self.running {
return Err(MinerError::NotRunning);
}
if self.faulted {
return Err(MinerError::Faulted);
}
self.check_temperature()?;
let mut frame = [0_u8; REPORT_BYTES];
let length = match self.backend.receive_frame(self.chain, &mut frame) {
Ok(length) => length,
Err(error) => {
let _ = self.power_off();
return Err(MinerError::Backend(error));
}
};
if length == 0 {
return Ok(None);
}
let report = match decode_nonce_report(&frame[..length.min(REPORT_BYTES)]) {
Ok(report) if length == REPORT_BYTES => report,
Ok(_) => {
let _ = self.power_off();
return Err(MinerError::InvalidReport(ReportError::Length));
}
Err(error) => {
let _ = self.power_off();
return Err(MinerError::InvalidReport(error));
}
};
let Some(work) = self.work[usize::from(report.work_id >> 3)] else {
return Err(MinerError::StaleReport);
};
if report.work_id != work.id {
return Err(MinerError::StaleReport);
}
let check = verify_sha256_report(
&work.header,
report.nonce,
report.version_field,
&work.target_le,
);
if !check.meets_target {
return Err(MinerError::BelowTarget);
}
Ok(Some(ValidShare {
nonce: report.nonce,
work_id: report.work_id,
rolled_version: check.rolled_version,
hash_le: check.hash_le,
}))
}
/// Keep thermal supervision active while pool share replies are pending.
pub fn supervise(&mut self) -> Result<(), MinerError<B::Error>> {
if !self.running {
return Err(MinerError::NotRunning);
}
if self.faulted {
return Err(MinerError::Faulted);
}
self.check_temperature()
}
}
impl<B: HardwareBackend> Drop for Bm1366Miner<'_, B> {
fn drop(&mut self) {
if self.running {
let _ = self.power_off();
}
}
}
+238
View File
@@ -0,0 +1,238 @@
// SPDX-License-Identifier: MIT
//! Verify reported SHA-256d shares. This module does not search for nonces.
const BM1366_VERSION_BITS: u32 = 0x1FFF_E000;
const ROUND: [u32; 64] = [
0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
];
const INITIAL: [u32; 8] = [
0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
];
fn compress(state: &mut [u32; 8], block: &[u8]) {
let mut words = [0_u32; 64];
for (index, part) in block.chunks_exact(4).enumerate() {
words[index] = u32::from_be_bytes(part.try_into().expect("four-byte word"));
}
for index in 16..64 {
let a = words[index - 15];
let b = words[index - 2];
let small_zero = a.rotate_right(7) ^ a.rotate_right(18) ^ (a >> 3);
let small_one = b.rotate_right(17) ^ b.rotate_right(19) ^ (b >> 10);
words[index] = words[index - 16]
.wrapping_add(small_zero)
.wrapping_add(words[index - 7])
.wrapping_add(small_one);
}
let [mut a, mut b, mut c, mut d, mut e, mut f, mut g, mut h] = *state;
for index in 0..64 {
let choose = (e & f) ^ (!e & g);
let majority = (a & b) ^ (a & c) ^ (b & c);
let big_one = e.rotate_right(6) ^ e.rotate_right(11) ^ e.rotate_right(25);
let big_zero = a.rotate_right(2) ^ a.rotate_right(13) ^ a.rotate_right(22);
let first = h
.wrapping_add(big_one)
.wrapping_add(choose)
.wrapping_add(ROUND[index])
.wrapping_add(words[index]);
let second = big_zero.wrapping_add(majority);
h = g;
g = f;
f = e;
e = d.wrapping_add(first);
d = c;
c = b;
b = a;
a = first.wrapping_add(second);
}
for (current, result) in state.iter_mut().zip([a, b, c, d, e, f, g, h]) {
*current = current.wrapping_add(result);
}
}
/// Compute SHA-256 for a message whose length fits the standard 64-bit field.
pub fn sha256(message: &[u8]) -> [u8; 32] {
let mut state = INITIAL;
let chunks = message.chunks_exact(64);
let remainder = chunks.remainder();
for chunk in chunks {
compress(&mut state, chunk);
}
let final_size = if remainder.len() >= 56 { 128 } else { 64 };
let mut final_blocks = [0_u8; 128];
final_blocks[..remainder.len()].copy_from_slice(remainder);
final_blocks[remainder.len()] = 0x80;
final_blocks[final_size - 8..final_size]
.copy_from_slice(&((message.len() as u64).wrapping_mul(8)).to_be_bytes());
for chunk in final_blocks[..final_size].chunks_exact(64) {
compress(&mut state, chunk);
}
let mut digest = [0_u8; 32];
for (word, bytes) in state.into_iter().zip(digest.chunks_exact_mut(4)) {
bytes.copy_from_slice(&word.to_be_bytes());
}
digest
}
/// Compute one double hash for verification, never for nonce search.
pub fn sha256d(message: &[u8]) -> [u8; 32] {
sha256(&sha256(message))
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ShareCheck {
pub rolled_version: u32,
pub hash_le: [u8; 32],
pub meets_target: bool,
}
/// Decode the raw BM1366 version extension against the version sent to the ASIC.
/// The chip reports additional set bits; pool submission uses a separate mask.
pub fn decode_bm1366_version(job_version: u32, version_field: u16) -> u32 {
job_version | ((u32::from(version_field) << 13) & BM1366_VERSION_BITS)
}
/// The BIP310 mask negotiated with a pool, limited to BM1366 rolling bits.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct VersionMask(u32);
impl VersionMask {
pub fn new(mask: u32) -> Option<Self> {
(mask & !BM1366_VERSION_BITS == 0).then_some(Self(mask))
}
pub fn apply_submission_bits(self, base_version: u32, version_bits: u32) -> Option<u32> {
(version_bits & !self.0 == 0).then_some((base_version & !self.0) | version_bits)
}
pub fn bits(self) -> u32 {
self.0
}
}
/// Check one ASIC-reported nonce against a little-endian 256-bit pool target.
pub fn verify_sha256_report(
nonce_zero_header: &[u8; 80],
nonce: u32,
version_field: u16,
target_le: &[u8; 32],
) -> ShareCheck {
let mut header = *nonce_zero_header;
let base_version = u32::from_le_bytes(header[..4].try_into().expect("version field"));
let rolled_version = decode_bm1366_version(base_version, version_field);
header[..4].copy_from_slice(&rolled_version.to_le_bytes());
header[76..80].copy_from_slice(&nonce.to_le_bytes());
let hash_le = sha256d(&header);
let meets_target = hash_le.iter().rev().cmp(target_le.iter().rev()).is_le();
ShareCheck {
rolled_version,
hash_le,
meets_target,
}
}
#[cfg(test)]
mod tests {
use super::*;
fn hex(bytes: &[u8]) -> String {
bytes.iter().map(|byte| format!("{byte:02x}")).collect()
}
#[test]
fn sha256_matches_standard_padding_vectors() {
let vectors: [(&[u8], &str); 6] = [
(
b"",
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
),
(
b"abc",
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
),
(
&(0_u8..55).collect::<Vec<_>>(),
"463eb28e72f82e0a96c0a4cc53690c571281131f672aa229e0d45ae59b598b59",
),
(
&(0_u8..56).collect::<Vec<_>>(),
"da2ae4d6b36748f2a318f23e7ab1dfdf45acdc9d049bd80e59de82a60895f562",
),
(
&(0_u8..64).collect::<Vec<_>>(),
"fdeab9acf3710362bd2658cdc9a29e8f9c757fcf9811603a8c447cd1d9151108",
),
(
&(0_u8..100).collect::<Vec<_>>(),
"bce0aff19cf5aa6a7469a30d61d04e4376e4bbf6381052ee9e7f33925c954d52",
),
];
for (message, expected) in vectors {
assert_eq!(hex(&sha256(message)), expected);
}
}
#[test]
fn captured_bm1366_report_meets_diff_one_only_with_rolled_version() {
let header = [
0x00, 0x00, 0x00, 0x20, 0xfc, 0x3a, 0xb8, 0xd4, 0x30, 0x21, 0xf4, 0x5e, 0xb6, 0x62,
0x38, 0x9d, 0x0f, 0x79, 0x1f, 0x65, 0x7d, 0xbf, 0x75, 0xa5, 0xcb, 0x93, 0x67, 0x0b,
0x57, 0xb6, 0xc2, 0x25, 0x03, 0xb4, 0x21, 0x3a, 0x43, 0xae, 0x10, 0x52, 0xeb, 0xd4,
0x44, 0x43, 0x06, 0x8f, 0xe1, 0x78, 0xe2, 0xc6, 0x1c, 0xa4, 0x99, 0x48, 0x46, 0xfd,
0x13, 0x3a, 0xdd, 0xb0, 0x4a, 0xab, 0x2b, 0x38, 0x2c, 0x5b, 0x4c, 0x74, 0xc1, 0x01,
0x2e, 0x6a, 0x8f, 0x06, 0x02, 0x17, 0x00, 0x00, 0x00, 0x00,
];
let mut diff_one = [0_u8; 32];
diff_one[26..28].fill(0xff);
let result = verify_sha256_report(&header, 0xEDAD_FF38, 0x04B3, &diff_one);
assert_eq!(result.rolled_version, 0x2096_6000);
assert_eq!(
hex(&result.hash_le),
"4b5e00850cf9de9809f822f8858eda39e49996d9d40f634f1043290000000000"
);
assert!(result.meets_target);
assert!(!verify_sha256_report(&header, 0xEDAD_FF38, 0, &diff_one).meets_target);
assert!(!verify_sha256_report(&header, 0xEDAD_FF39, 0x04B3, &diff_one).meets_target);
assert!(verify_sha256_report(&header, 0xEDAD_FF38, 0x04B3, &[0xff; 32]).meets_target);
assert!(!verify_sha256_report(&header, 0xEDAD_FF38, 0x04B3, &[0; 32]).meets_target);
}
#[test]
fn raw_asic_version_preserves_bits_sent_to_chip() {
assert_eq!(decode_bm1366_version(0x2100_0004, 1), 0x2100_2004);
assert_eq!(decode_bm1366_version(0x2000_0000, 0), 0x2000_0000);
}
#[test]
fn pool_version_bits_replace_only_negotiated_mask() {
let mask = VersionMask::new(0x0060_0000).expect("valid restricted mask");
assert_eq!(
mask.apply_submission_bits(0x2160_0004, 0x0020_0000),
Some(0x2120_0004)
);
assert_eq!(mask.apply_submission_bits(0x2160_0004, 0x0080_0000), None);
assert_eq!(
VersionMask::new(0)
.unwrap()
.apply_submission_bits(0x2100_0004, 0),
Some(0x2100_0004)
);
assert_eq!(
VersionMask::new(BM1366_VERSION_BITS)
.unwrap()
.apply_submission_bits(0x2160_0004, 0),
Some(0x2000_0004)
);
assert!(VersionMask::new(0x8000_0000).is_none());
}
}
+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(_))
));
}
}
+287
View File
@@ -0,0 +1,287 @@
// 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()
}
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 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);
}
}
+170
View File
@@ -0,0 +1,170 @@
// SPDX-License-Identifier: MIT
//! Litecoin's fixed scrypt proof-of-work hash for validating reported shares.
//! This module hashes one supplied header and never searches for a nonce.
use crate::pow::sha256;
const N: usize = 1024;
fn hmac_sha256(key: &[u8], message: &[u8]) -> [u8; 32] {
let mut block = [0_u8; 64];
if key.len() > block.len() {
block[..32].copy_from_slice(&sha256(key));
} else {
block[..key.len()].copy_from_slice(key);
}
let mut inner = Vec::with_capacity(64 + message.len());
inner.extend(block.iter().map(|byte| byte ^ 0x36));
inner.extend_from_slice(message);
let inner_hash = sha256(&inner);
let mut outer = [0_u8; 96];
for (destination, byte) in outer[..64].iter_mut().zip(block) {
*destination = byte ^ 0x5c;
}
outer[64..].copy_from_slice(&inner_hash);
sha256(&outer)
}
// PBKDF2-HMAC-SHA256 with the fixed single iteration specified for scrypt.
fn pbkdf2_one(password: &[u8], salt: &[u8], output: &mut [u8]) {
let mut message = Vec::with_capacity(salt.len() + 4);
message.extend_from_slice(salt);
message.extend_from_slice(&[0_u8; 4]);
for (index, chunk) in output.chunks_mut(32).enumerate() {
let block = u32::try_from(index + 1).expect("fixed scrypt output fits u32");
message[salt.len()..].copy_from_slice(&block.to_be_bytes());
chunk.copy_from_slice(&hmac_sha256(password, &message)[..chunk.len()]);
}
}
fn salsa20_8(input: &mut [u32; 16]) {
let original = *input;
let mut x = original;
for _ in 0..4 {
x[4] ^= x[0].wrapping_add(x[12]).rotate_left(7);
x[8] ^= x[4].wrapping_add(x[0]).rotate_left(9);
x[12] ^= x[8].wrapping_add(x[4]).rotate_left(13);
x[0] ^= x[12].wrapping_add(x[8]).rotate_left(18);
x[9] ^= x[5].wrapping_add(x[1]).rotate_left(7);
x[13] ^= x[9].wrapping_add(x[5]).rotate_left(9);
x[1] ^= x[13].wrapping_add(x[9]).rotate_left(13);
x[5] ^= x[1].wrapping_add(x[13]).rotate_left(18);
x[14] ^= x[10].wrapping_add(x[6]).rotate_left(7);
x[2] ^= x[14].wrapping_add(x[10]).rotate_left(9);
x[6] ^= x[2].wrapping_add(x[14]).rotate_left(13);
x[10] ^= x[6].wrapping_add(x[2]).rotate_left(18);
x[3] ^= x[15].wrapping_add(x[11]).rotate_left(7);
x[7] ^= x[3].wrapping_add(x[15]).rotate_left(9);
x[11] ^= x[7].wrapping_add(x[3]).rotate_left(13);
x[15] ^= x[11].wrapping_add(x[7]).rotate_left(18);
x[1] ^= x[0].wrapping_add(x[3]).rotate_left(7);
x[2] ^= x[1].wrapping_add(x[0]).rotate_left(9);
x[3] ^= x[2].wrapping_add(x[1]).rotate_left(13);
x[0] ^= x[3].wrapping_add(x[2]).rotate_left(18);
x[6] ^= x[5].wrapping_add(x[4]).rotate_left(7);
x[7] ^= x[6].wrapping_add(x[5]).rotate_left(9);
x[4] ^= x[7].wrapping_add(x[6]).rotate_left(13);
x[5] ^= x[4].wrapping_add(x[7]).rotate_left(18);
x[11] ^= x[10].wrapping_add(x[9]).rotate_left(7);
x[8] ^= x[11].wrapping_add(x[10]).rotate_left(9);
x[9] ^= x[8].wrapping_add(x[11]).rotate_left(13);
x[10] ^= x[9].wrapping_add(x[8]).rotate_left(18);
x[12] ^= x[15].wrapping_add(x[14]).rotate_left(7);
x[13] ^= x[12].wrapping_add(x[15]).rotate_left(9);
x[14] ^= x[13].wrapping_add(x[12]).rotate_left(13);
x[15] ^= x[14].wrapping_add(x[13]).rotate_left(18);
}
for ((word, initial), mixed) in input.iter_mut().zip(original).zip(x) {
*word = initial.wrapping_add(mixed);
}
}
fn block_mix(input: &[u32; 32]) -> [u32; 32] {
let mut x: [u32; 16] = input[16..].try_into().expect("fixed block size");
let mut output = [0_u32; 32];
for (index, chunk) in input.chunks_exact(16).enumerate() {
for (word, source) in x.iter_mut().zip(chunk) {
*word ^= source;
}
salsa20_8(&mut x);
output[index * 16..(index + 1) * 16].copy_from_slice(&x);
}
output
}
/// Hash one 80-byte Litecoin header with scrypt(N=1024, r=1, p=1, dkLen=32).
/// The return value is the raw little-endian PoW digest.
pub fn scrypt_1024_1_1_256(header: &[u8; 80]) -> [u8; 32] {
let mut initial = [0_u8; 128];
pbkdf2_one(header, header, &mut initial);
let mut x = [0_u32; 32];
for (word, bytes) in x.iter_mut().zip(initial.chunks_exact(4)) {
*word = u32::from_le_bytes(bytes.try_into().expect("four-byte word"));
}
let mut memory = vec![[0_u32; 32]; N];
for saved in &mut memory {
*saved = x;
x = block_mix(&x);
}
for _ in 0..N {
let index = x[16] as usize & (N - 1);
for (word, saved) in x.iter_mut().zip(memory[index]) {
*word ^= saved;
}
x = block_mix(&x);
}
for (word, bytes) in x.iter().zip(initial.chunks_exact_mut(4)) {
bytes.copy_from_slice(&word.to_le_bytes());
}
let mut digest = [0_u8; 32];
pbkdf2_one(header, &initial, &mut digest);
digest
}
/// Validate one supplied header against an exact little-endian pool target.
pub fn verify_scrypt_header(header: &[u8; 80], target_le: &[u8; 32]) -> ([u8; 32], bool) {
let digest = scrypt_1024_1_1_256(header);
let meets_target = digest.iter().rev().cmp(target_le.iter().rev()).is_le();
(digest, meets_target)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn litecoin_block_29255_matches_published_scrypt_pow() {
let header_hex = concat!(
"01000000f615f7ce3b4fc6b8f61e8f89aedb1d0852507650533a9e3b10b9bbcc30639f27",
"9fcaa86746e1ef52d3edb3c4ad8259920d509bd073605c9bf1d59983752a6b06b817bb4",
"ea78e011d012d59d4"
);
let mut header = [0_u8; 80];
for (byte, pair) in header.iter_mut().zip(header_hex.as_bytes().chunks_exact(2)) {
*byte = u8::from_str_radix(std::str::from_utf8(pair).unwrap(), 16).unwrap();
}
let expected_big = "0000000110c8357966576df46f3b802ca897deb7ad18b12f1c24ecff6386ebd9";
let mut expected = [0_u8; 32];
for (byte, pair) in expected
.iter_mut()
.rev()
.zip(expected_big.as_bytes().chunks_exact(2))
{
*byte = u8::from_str_radix(std::str::from_utf8(pair).unwrap(), 16).unwrap();
}
let (digest, accepted) = verify_scrypt_header(&header, &expected);
assert_eq!(digest, expected);
assert!(accepted);
assert!(!verify_scrypt_header(&header, &[0_u8; 32]).1);
}
#[test]
fn fixed_header_matches_independent_openssl_scrypt() {
let header = core::array::from_fn(|index| index as u8);
let expected = "bc540a1a801df96e493005c71e010e2d387607fbf0fec416fd3c2645aa1ba9d2";
let actual = scrypt_1024_1_1_256(&header);
let actual_hex: String = actual.iter().map(|byte| format!("{byte:02x}")).collect();
assert_eq!(actual_hex, expected);
}
}
+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);
}
}
+510
View File
@@ -0,0 +1,510 @@
// SPDX-License-Identifier: MIT
//! One bounded pool connection with ordered jobs and verified share replies.
use crate::miner::{Bm1366Miner, MinerError, ValidShare};
use crate::stratum_session::{DispatchError, IssuedWork, PoolSession, SessionError};
use crate::stratum_v1::{parse_boolean_response, PoolMessageError};
use crate::stratum_wire::{HandshakeError, PoolHandshake, StratumWire, WireError};
use crate::HardwareBackend;
use serde_json::Value;
use std::collections::VecDeque;
use std::net::SocketAddr;
use std::time::{Duration, Instant};
const MAX_PENDING_SHARES: usize = 32;
const SHARE_REPLY_TIMEOUT: Duration = Duration::from_secs(30);
const MAX_REPORTS_PER_CYCLE: usize = 256;
const POOL_WRITE_DEADLINE: Duration = Duration::from_millis(100);
#[derive(Debug)]
pub enum ClientError<E> {
Wire(WireError),
Pool(PoolMessageError),
Session(SessionError),
Dispatch(DispatchError<E>),
UnexpectedResponse,
TooManyPending,
RequestIdsExhausted,
ShareReplyTimeout,
EmergencyShutdown(E),
}
#[derive(Debug)]
pub enum PoolEvent {
Idle,
Control,
Work(IssuedWork),
ShareAccepted(u64),
ShareRejected(u64),
}
#[derive(Debug, Eq, PartialEq)]
pub enum ReportEvent {
Stale,
BelowTarget,
Submitted(u64),
Backpressured,
}
#[derive(Debug)]
pub enum CycleError<E> {
Pool(ClientError<E>),
Miner(MinerError<E>),
Submit(ClientError<()>),
EmergencyShutdown(E),
}
pub struct PoolConnection {
wire: StratumWire,
session: PoolSession,
worker: String,
early: VecDeque<Vec<u8>>,
next_request_id: u64,
pending: Vec<PendingShare>,
accepted: u64,
rejected: u64,
}
struct PendingShare {
id: u64,
sent_at: Instant,
}
impl PoolConnection {
pub fn connect(
address: SocketAddr,
agent: &str,
worker: &str,
password: &str,
io_timeout: Duration,
handshake_timeout: Duration,
) -> Result<Self, HandshakeError> {
let mut wire = StratumWire::connect(address, io_timeout).map_err(HandshakeError::Wire)?;
let handshake = wire.handshake(agent, worker, password, handshake_timeout)?;
Self::from_handshake(wire, handshake, worker)
.map_err(|_| HandshakeError::Pool(PoolMessageError::InvalidField))
}
fn from_handshake(
mut wire: StratumWire,
handshake: PoolHandshake,
worker: &str,
) -> Result<Self, SessionError> {
let session = PoolSession::new(
handshake.subscription,
handshake.configure.version_mask,
handshake.configure.subscribe_extranonce,
)?;
wire.cap_write_timeout(POOL_WRITE_DEADLINE);
Ok(Self {
wire,
session,
worker: worker.to_owned(),
early: handshake.early_notifications.into(),
next_request_id: 4,
pending: Vec::new(),
accepted: 0,
rejected: 0,
})
}
pub fn step<B: HardwareBackend>(
&mut self,
miner: &mut Bm1366Miner<'_, B>,
) -> Result<PoolEvent, ClientError<B::Error>> {
let result = self.step_inner(miner);
if result.is_err() {
self.wire.close();
if let Err(error) = miner.stop() {
return Err(ClientError::EmergencyShutdown(error));
}
}
result
}
fn step_inner<B: HardwareBackend>(
&mut self,
miner: &mut Bm1366Miner<'_, B>,
) -> Result<PoolEvent, ClientError<B::Error>> {
if self
.pending
.first()
.is_some_and(|share| share.sent_at.elapsed() >= SHARE_REPLY_TIMEOUT)
{
return Err(ClientError::ShareReplyTimeout);
}
let line = if let Some(line) = self.early.pop_front() {
line
} else {
match self.wire.try_read_line() {
Ok(Some(line)) => line,
Ok(None) => return Ok(PoolEvent::Idle),
Err(error) => return Err(ClientError::Wire(error)),
}
};
let message: Value =
serde_json::from_slice(&line).map_err(|_| ClientError::Pool(PoolMessageError::Json))?;
if let Some(id) = message.get("id").and_then(Value::as_u64) {
if !self.pending.iter().any(|share| share.id == id) {
return Err(ClientError::UnexpectedResponse);
}
let accepted = parse_boolean_response(&line, id).map_err(ClientError::Pool)?;
self.pending.retain(|pending| pending.id != id);
if accepted {
self.accepted = self.accepted.saturating_add(1);
return Ok(PoolEvent::ShareAccepted(id));
}
self.rejected = self.rejected.saturating_add(1);
return Ok(PoolEvent::ShareRejected(id));
}
if !message.get("id").is_none_or(Value::is_null) {
return Err(ClientError::Pool(PoolMessageError::WrongMessage));
}
match message.get("method").and_then(Value::as_str) {
Some("mining.notify") => {
let issued = match self.session.issue_to_miner(miner, &line) {
Err(DispatchError::Session(SessionError::WorkIdsExhausted)) => {
miner
.reset_chain()
.map_err(|error| ClientError::Dispatch(DispatchError::Miner(error)))?;
self.after_hardware_reset(miner);
self.session.issue_to_miner(miner, &line)
}
result => result,
};
issued.map(PoolEvent::Work).map_err(ClientError::Dispatch)
}
Some("mining.set_difficulty" | "mining.set_version_mask" | "mining.set_extranonce") => {
self.session
.control_with_miner(miner, &line)
.map_err(ClientError::Session)?;
Ok(PoolEvent::Control)
}
_ => Err(ClientError::Pool(PoolMessageError::WrongMessage)),
}
}
/// Send only a nonce already verified by the miner and session. A sent
/// request remains pending until its matching boolean pool reply arrives.
pub fn submit_share(&mut self, share: ValidShare) -> Result<u64, ClientError<()>> {
if self.pending.len() >= MAX_PENDING_SHARES {
return Err(ClientError::TooManyPending);
}
let id = self.next_request_id;
let next = id.checked_add(1).ok_or(ClientError::RequestIdsExhausted)?;
let line = self
.session
.submission(share, &self.worker, id)
.map_err(ClientError::Session)?;
self.wire
.send_line(line.as_bytes())
.map_err(ClientError::Wire)?;
self.next_request_id = next;
self.pending.push(PendingShare {
id,
sent_at: Instant::now(),
});
Ok(id)
}
pub fn share_counts(&self) -> (u64, u64, usize) {
(self.accepted, self.rejected, self.pending.len())
}
/// Process one pool message, then drain a bounded burst of ASIC reports.
/// A reported nonce is verified before sending. The caller must cycle
/// continuously; hardware still requires an independent power watchdog.
pub fn cycle<B: HardwareBackend>(
&mut self,
miner: &mut Bm1366Miner<'_, B>,
) -> Result<(PoolEvent, Vec<ReportEvent>), CycleError<B::Error>> {
let pool = self.step(miner).map_err(CycleError::Pool)?;
let mut reports = Vec::new();
for _ in 0..MAX_REPORTS_PER_CYCLE {
if self.pending.len() >= MAX_PENDING_SHARES {
miner.supervise().map_err(CycleError::Miner)?;
reports.push(ReportEvent::Backpressured);
break;
}
let event = match miner.poll() {
Ok(None) => break,
Ok(Some(share)) => {
let id = match self.submit_share(share) {
Ok(id) => id,
Err(error) => {
self.wire.close();
miner.stop().map_err(CycleError::EmergencyShutdown)?;
return Err(CycleError::Submit(error));
}
};
ReportEvent::Submitted(id)
}
Err(MinerError::StaleReport) => ReportEvent::Stale,
Err(MinerError::BelowTarget) => ReportEvent::BelowTarget,
Err(error) => return Err(CycleError::Miner(error)),
};
reports.push(event);
}
Ok((pool, reports))
}
/// Call only after an actual chain reset flushes old hardware reports.
pub fn after_hardware_reset<B: HardwareBackend>(&mut self, miner: &mut Bm1366Miner<'_, B>) {
miner.clear_work();
self.session.after_hardware_reset();
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::stratum_v1::Subscription;
use std::cell::Cell;
use std::io::Write;
use std::net::{TcpListener, TcpStream};
use std::rc::Rc;
use std::sync::mpsc;
use std::thread;
#[derive(Default)]
struct Backend {
sent: Vec<Vec<u8>>,
powered: Rc<Cell<bool>>,
reports_remaining: usize,
reset_assertions: usize,
}
impl HardwareBackend for Backend {
type Error = ();
fn send_frame(&mut self, _chain: u8, frame: &[u8]) -> Result<(), Self::Error> {
self.sent.push(frame.to_vec());
Ok(())
}
fn receive_frame(&mut self, _chain: u8, frame: &mut [u8]) -> Result<usize, Self::Error> {
if self.reports_remaining == 0 {
return Ok(0);
}
self.reports_remaining -= 1;
frame[..11].copy_from_slice(&[
0xaa, 0x55, 0x38, 0xff, 0xad, 0xed, 0, 0x18, 0x04, 0xb3, 0x94,
]);
Ok(11)
}
fn set_chain_reset(&mut self, _chain: u8, asserted: bool) -> Result<(), Self::Error> {
if asserted {
self.reset_assertions += 1;
}
Ok(())
}
fn set_fan_target(&mut self, _fan: u8, _percent: u8) -> Result<(), Self::Error> {
Ok(())
}
fn read_temperature_mc(&mut self, _sensor: u8) -> Result<i32, Self::Error> {
Ok(50_000)
}
fn set_psu_enabled(&mut self, enabled: bool) -> Result<(), Self::Error> {
self.powered.set(enabled);
Ok(())
}
}
fn test_link(input: &'static [u8]) -> (PoolConnection, thread::JoinHandle<()>) {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let (ready, received) = mpsc::channel();
let server = thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
stream.write_all(input).unwrap();
ready.send(()).unwrap();
});
let stream = TcpStream::connect(address).unwrap();
let wire = StratumWire::from_stream(stream, Duration::from_secs(2)).unwrap();
received.recv_timeout(Duration::from_secs(2)).unwrap();
let handshake = PoolHandshake {
subscription: Subscription {
extranonce1: vec![1, 2, 3, 4],
extranonce2_size: 4,
},
configure: crate::stratum_v1::ConfigureResult {
version_mask: None,
subscribe_extranonce: false,
},
early_notifications: Vec::new(),
};
(
PoolConnection::from_handshake(wire, handshake, "miner.worker").unwrap(),
server,
)
}
#[test]
fn pool_controls_then_dispatches_one_synthetic_job() {
let (mut link, server) = test_link(
concat!(
"{\"id\":null,\"method\":\"mining.set_difficulty\",\"params\":[1]}\n",
"{\"id\":null,\"method\":\"mining.notify\",\"params\":[\"job-1\",",
"\"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f\",",
"\"616263\",\"78797a\",[],\"20000000\",\"1d00ffff\",\"66554433\",true]}\n"
)
.as_bytes(),
);
let mut backend = Backend::default();
{
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
assert!(matches!(
link.cycle(&mut miner).unwrap(),
(PoolEvent::Control, reports) if reports.is_empty()
));
match link.cycle(&mut miner).unwrap() {
(PoolEvent::Work(work), reports) if reports.is_empty() => {
assert_eq!(work.work_id, 0)
}
_ => panic!("expected job"),
}
}
assert_eq!(backend.sent.len(), 1);
server.join().unwrap();
}
#[test]
fn thirty_third_job_flushes_asic_before_reusing_work_id() {
let (mut link, server) = test_link(b"");
link.early.push_back(
b"{\"id\":null,\"method\":\"mining.set_difficulty\",\"params\":[1]}\n".to_vec(),
);
let notify = concat!(
"{\"id\":null,\"method\":\"mining.notify\",\"params\":[\"job\",",
"\"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f\",",
"\"616263\",\"78797a\",[],\"20000000\",\"1d00ffff\",\"66554433\",true]}\n"
);
for _ in 0..33 {
link.early.push_back(notify.as_bytes().to_vec());
}
let mut backend = Backend::default();
let powered = Rc::clone(&backend.powered);
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
assert!(matches!(link.step(&mut miner), Ok(PoolEvent::Control)));
let mut first_header = None;
for index in 0..33 {
let PoolEvent::Work(work) = link.step(&mut miner).unwrap() else {
panic!("expected work");
};
if index == 0 {
first_header = Some(work.header);
}
if index == 32 {
assert_eq!(work.work_id, 0);
assert_ne!(Some(work.header), first_header);
}
}
assert!(powered.get());
miner.stop().unwrap();
drop(miner);
assert_eq!(backend.reset_assertions, 2);
assert_eq!(backend.sent.len(), 33);
server.join().unwrap();
}
#[test]
fn share_replies_match_pending_ids_and_count_accepts_separately() {
let (mut link, server) = test_link(
concat!(
"{\"id\":4,\"result\":true,\"error\":null}\n",
"{\"id\":5,\"result\":false,\"error\":[23,\"stale\"]}\n",
"{\"id\":6,\"result\":true,\"error\":null}\n"
)
.as_bytes(),
);
link.pending.extend([4, 5].map(|id| PendingShare {
id,
sent_at: Instant::now(),
}));
let mut backend = Backend::default();
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
assert!(matches!(
link.step(&mut miner).unwrap(),
PoolEvent::ShareAccepted(4)
));
assert!(matches!(
link.step(&mut miner).unwrap(),
PoolEvent::ShareRejected(5)
));
assert_eq!(link.share_counts(), (1, 1, 0));
assert!(matches!(
link.step(&mut miner),
Err(ClientError::UnexpectedResponse)
));
server.join().unwrap();
}
#[test]
fn untracked_report_cannot_be_sent_to_pool() {
let (mut link, server) = test_link(b"");
let report = ValidShare {
nonce: 1,
work_id: 0,
rolled_version: 0x2000_0000,
hash_le: [0; 32],
};
assert!(matches!(
link.submit_share(report),
Err(ClientError::Session(SessionError::StaleShare))
));
assert_eq!(link.share_counts(), (0, 0, 0));
server.join().unwrap();
}
#[test]
fn unanswered_share_closes_pool_connection() {
let (mut link, server) = test_link(b"");
link.pending.push(PendingShare {
id: 4,
sent_at: Instant::now() - SHARE_REPLY_TIMEOUT - Duration::from_secs(1),
});
let mut backend = Backend::default();
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
assert!(matches!(
link.step(&mut miner),
Err(ClientError::ShareReplyTimeout)
));
assert!(link.wire.is_closed());
server.join().unwrap();
}
#[test]
fn malformed_pool_message_stops_miner_before_returning() {
let (mut link, server) = test_link(b"{}\n");
let mut backend = Backend::default();
let powered = Rc::clone(&backend.powered);
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
assert!(powered.get());
assert!(matches!(link.cycle(&mut miner), Err(CycleError::Pool(_))));
assert!(!powered.get());
server.join().unwrap();
}
#[test]
fn idle_pool_does_not_limit_asic_report_burst_to_one() {
let (mut link, server) =
test_link(b"{\"id\":null,\"method\":\"mining.set_difficulty\",\"params\":[1]}\n");
let mut backend = Backend {
reports_remaining: MAX_REPORTS_PER_CYCLE + 3,
..Backend::default()
};
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
let (pool, reports) = link.cycle(&mut miner).unwrap();
assert!(matches!(pool, PoolEvent::Control));
assert_eq!(reports.len(), MAX_REPORTS_PER_CYCLE);
assert!(reports
.iter()
.all(|event| matches!(event, ReportEvent::Stale)));
drop(miner);
assert_eq!(backend.reports_remaining, 3);
server.join().unwrap();
}
}
+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
}
);
}
}
+378
View File
@@ -0,0 +1,378 @@
// SPDX-License-Identifier: MIT
//! Bounded pool-job bookkeeping for one BM1366 chain and one Stratum V1 session.
use crate::difficulty::PoolDifficulty;
use crate::miner::{Bm1366Miner, MinerError, ValidShare};
use crate::pow::{sha256d, VersionMask};
use crate::stratum_submit::{format_submission, Submission, SubmitError};
use crate::stratum_v1::{
parse_control_notification, parse_notify, PoolMessageError, PoolNotification, Subscription,
};
use crate::stratum_work::JobError;
use crate::HardwareBackend;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum SessionError {
InvalidSubscription,
Pool(PoolMessageError),
Work(JobError),
MissingDifficulty,
ExtranonceExhausted,
WorkIdsExhausted,
StaleShare,
UnverifiedShare,
Submit(SubmitError),
}
#[derive(Debug, Eq, PartialEq)]
pub enum DispatchError<E> {
Session(SessionError),
Miner(MinerError<E>),
}
#[derive(Debug)]
pub struct IssuedWork {
pub work_id: u8,
pub header: [u8; 80],
pub target_le: [u8; 32],
/// The hardware miner must forget prior work before submitting this job.
pub clean_jobs: bool,
}
struct TrackedWork {
job_id: String,
header: [u8; 80],
target_le: [u8; 32],
extranonce2: Vec<u8>,
ntime: u32,
base_version: u32,
}
struct NonceSpace {
template: [u8; 80],
next: [u8; 32],
exhausted: bool,
}
const MAX_NONCE_SPACES: usize = 4096;
pub struct PoolSession {
subscription: Subscription,
version_mask: Option<VersionMask>,
subscribe_extranonce: bool,
pending_difficulty: Option<PoolDifficulty>,
active_difficulty: Option<PoolDifficulty>,
nonce_spaces: Vec<NonceSpace>,
zero_extranonce_headers: Vec<[u8; 80]>,
tracked: [Option<TrackedWork>; 32],
next_slot: usize,
}
impl PoolSession {
pub fn new(
subscription: Subscription,
version_mask: Option<VersionMask>,
subscribe_extranonce: bool,
) -> Result<Self, SessionError> {
if subscription.extranonce1.len() > 32 || subscription.extranonce2_size > 32 {
return Err(SessionError::InvalidSubscription);
}
Ok(Self {
subscription,
version_mask,
subscribe_extranonce,
pending_difficulty: None,
active_difficulty: None,
nonce_spaces: Vec::new(),
zero_extranonce_headers: Vec::new(),
tracked: std::array::from_fn(|_| None),
next_slot: 0,
})
}
/// Apply a control message in wire order. A true result means the caller
/// must call the hardware miner's `clear_work` before accepting reports.
pub fn control(&mut self, line: &[u8]) -> Result<bool, SessionError> {
let control = parse_control_notification(
line,
self.version_mask.is_some(),
self.subscribe_extranonce,
)
.map_err(SessionError::Pool)?;
match control {
PoolNotification::SetDifficulty(difficulty) => {
self.pending_difficulty = Some(difficulty);
Ok(false)
}
PoolNotification::SetVersionMask(mask) => {
if self.version_mask == Some(mask) {
return Ok(false);
}
self.version_mask = Some(mask);
self.tracked = std::array::from_fn(|_| None);
Ok(true)
}
PoolNotification::SetExtranonce(subscription) => {
self.subscription = subscription;
self.nonce_spaces.clear();
self.zero_extranonce_headers.clear();
self.tracked = std::array::from_fn(|_| None);
Ok(true)
}
}
}
/// Apply a pool control message and invalidate the hardware miner's work
/// when an extranonce or version-mask change makes earlier jobs stale.
pub fn control_with_miner<B: HardwareBackend>(
&mut self,
miner: &mut Bm1366Miner<'_, B>,
line: &[u8],
) -> Result<(), SessionError> {
if self.control(line)? {
miner.clear_work();
}
Ok(())
}
/// Allocate one unique extranonce and ASIC work ID for a pool job. The
/// caller must pass this header, target, and ID to `Bm1366Miner::submit`.
/// On `clean_jobs`, clear the hardware miner's work first. Work IDs are
/// never reused on the same chain without an explicit hardware reset.
pub fn issue_notify(&mut self, line: &[u8]) -> Result<IssuedWork, SessionError> {
let job = parse_notify(line, &self.subscription).map_err(SessionError::Pool)?;
let difficulty = self
.pending_difficulty
.or(self.active_difficulty)
.ok_or(SessionError::MissingDifficulty)?;
if self.next_slot == self.tracked.len() {
return Err(SessionError::WorkIdsExhausted);
}
let size = self.subscription.extranonce2_size;
let template = if size == 0 {
None
} else {
Some(
job.work
.nonce_zero_header(&vec![0; size], job.work.ntime)
.map_err(SessionError::Work)?,
)
};
let space_index = template.and_then(|header| {
self.nonce_spaces
.iter()
.position(|space| space.template == header)
});
if size != 0 && space_index.is_none() && self.nonce_spaces.len() == MAX_NONCE_SPACES {
return Err(SessionError::ExtranonceExhausted);
}
let extranonce2 = match space_index {
Some(index) if self.nonce_spaces[index].exhausted => {
return Err(SessionError::ExtranonceExhausted)
}
Some(index) => self.nonce_spaces[index].next[..size].to_vec(),
None => vec![0; size],
};
let header = job
.work
.nonce_zero_header(&extranonce2, job.work.ntime)
.map_err(SessionError::Work)?;
if size == 0 && self.zero_extranonce_headers.contains(&header) {
return Err(SessionError::ExtranonceExhausted);
}
let target_le = difficulty.target_le();
if job.clean_jobs {
self.tracked = std::array::from_fn(|_| None);
}
self.active_difficulty = Some(difficulty);
self.pending_difficulty = None;
let slot = self.next_slot;
self.next_slot += 1;
self.tracked[slot] = Some(TrackedWork {
job_id: job.id,
header,
target_le,
extranonce2,
ntime: job.work.ntime,
base_version: job.work.version,
});
if size == 0 {
self.zero_extranonce_headers.push(header);
} else {
let space = match space_index {
Some(index) => &mut self.nonce_spaces[index],
None => {
self.nonce_spaces.push(NonceSpace {
template: template.expect("nonzero extranonce has a template"),
next: [0; 32],
exhausted: false,
});
self.nonce_spaces.last_mut().expect("just pushed")
}
};
let mut carry = true;
for byte in space.next[..size].iter_mut().rev() {
let (new, overflow) = byte.overflowing_add(u8::from(carry));
*byte = new;
carry = overflow;
if !carry {
break;
}
}
space.exhausted = carry;
}
Ok(IssuedWork {
work_id: (slot as u8) << 3,
header,
target_le,
clean_jobs: job.clean_jobs,
})
}
/// Preserve pool-message order while dispatching one job to the hardware
/// miner. A failed dispatch consumes its ASIC work ID to avoid ambiguity
/// with any frame that may have reached the device before the error.
pub fn issue_to_miner<B: HardwareBackend>(
&mut self,
miner: &mut Bm1366Miner<'_, B>,
line: &[u8],
) -> Result<IssuedWork, DispatchError<B::Error>> {
let issued = self.issue_notify(line).map_err(DispatchError::Session)?;
if issued.clean_jobs {
miner.clear_work();
}
if let Err(error) = miner.submit(issued.header, issued.target_le, issued.work_id) {
self.tracked[usize::from(issued.work_id >> 3)] = None;
return Err(DispatchError::Miner(error));
}
Ok(issued)
}
/// Recheck the hardware-reported share and format its pool submission.
/// This method verifies one reported nonce; it never searches for one.
pub fn submission(
&self,
share: ValidShare,
worker: &str,
request_id: u64,
) -> Result<String, SessionError> {
let tracked = self
.tracked
.get(usize::from(share.work_id >> 3))
.and_then(Option::as_ref)
.ok_or(SessionError::StaleShare)?;
if share.work_id & 7 != 0 {
return Err(SessionError::StaleShare);
}
let mut header = tracked.header;
header[..4].copy_from_slice(&share.rolled_version.to_le_bytes());
header[76..80].copy_from_slice(&share.nonce.to_le_bytes());
let hash_le = sha256d(&header);
if hash_le != share.hash_le
|| hash_le
.iter()
.rev()
.cmp(tracked.target_le.iter().rev())
.is_gt()
{
return Err(SessionError::UnverifiedShare);
}
format_submission(&Submission {
request_id,
worker,
job_id: &tracked.job_id,
extranonce2: &tracked.extranonce2,
ntime: tracked.ntime,
nonce: share.nonce,
base_version: tracked.base_version,
rolled_version: share.rolled_version,
version_mask: self.version_mask,
})
.map_err(SessionError::Submit)
}
/// Call only after the chain has actually reset and prior reports cannot
/// arrive. A pool `clean_jobs` notification alone is insufficient.
pub fn after_hardware_reset(&mut self) {
self.tracked = std::array::from_fn(|_| None);
self.next_slot = 0;
self.zero_extranonce_headers.clear();
}
}
#[cfg(test)]
mod tests {
use super::*;
fn bytes(text: &str) -> Vec<u8> {
text.as_bytes()
.chunks_exact(2)
.map(|part| u8::from_str_radix(std::str::from_utf8(part).unwrap(), 16).unwrap())
.collect()
}
#[test]
fn captured_report_is_rechecked_and_formatted_for_pool() {
let header: [u8; 80] = bytes(concat!(
"00000020fc3ab8d43021f45eb662389d0f791f657dbf75a5cb93670b57b6c22503",
"b4213a43ae1052ebd44443068fe178e2c61ca4994846fd133addb04aab2b382c5",
"b4c74c1012e6a8f06021700000000"
))
.try_into()
.unwrap();
let hash_le: [u8; 32] =
bytes("4b5e00850cf9de9809f822f8858eda39e49996d9d40f634f1043290000000000")
.try_into()
.unwrap();
let mut target_le = [0_u8; 32];
target_le[26..28].fill(0xff);
let mut session = PoolSession::new(
Subscription {
extranonce1: vec![],
extranonce2_size: 4,
},
VersionMask::new(0x1fff_e000),
false,
)
.unwrap();
session.tracked[3] = Some(TrackedWork {
job_id: "captured-job".into(),
header,
target_le,
extranonce2: vec![0, 0, 0, 1],
ntime: u32::from_le_bytes(header[68..72].try_into().unwrap()),
base_version: 0x2000_0000,
});
let share = ValidShare {
nonce: 0xedad_ff38,
work_id: 0x18,
rolled_version: 0x2096_6000,
hash_le,
};
let submit = session.submission(share, "miner.worker", 7).unwrap();
assert!(submit.contains("\"mining.submit\""));
assert!(submit.contains("\"captured-job\""));
assert!(submit.contains("\"edadff38\",\"00966000\""));
assert_eq!(
session.submission(
ValidShare {
hash_le: [0; 32],
..share
},
"miner.worker",
8
),
Err(SessionError::UnverifiedShare)
);
assert_eq!(
session.control(
b"{\"id\":null,\"method\":\"mining.set_version_mask\",\"params\":[\"00002000\"]}"
),
Ok(true)
);
assert_eq!(
session.submission(share, "miner.worker", 8),
Err(SessionError::StaleShare)
);
}
}
+92
View File
@@ -0,0 +1,92 @@
// SPDX-License-Identifier: MIT
//! Format one verified share for Stratum V1 and negotiated BIP310 submission.
//! Pool I/O and request tracking are owned by the caller.
use crate::pow::VersionMask;
use std::fmt::Write;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum SubmitError {
EmptyWorker,
EmptyJobId,
FieldTooLong,
ExtranonceTooLong,
UnrepresentableVersion,
}
pub struct Submission<'a> {
pub request_id: u64,
pub worker: &'a str,
pub job_id: &'a str,
pub extranonce2: &'a [u8],
pub ntime: u32,
pub nonce: u32,
pub base_version: u32,
pub rolled_version: u32,
/// The last pool mask, only after version rolling was accepted.
pub version_mask: Option<VersionMask>,
}
fn json_string(out: &mut String, value: &str) {
out.push('"');
for ch in value.chars() {
match ch {
'"' => out.push_str("\\\""),
'\\' => out.push_str("\\\\"),
'\n' => out.push_str("\\n"),
'\r' => out.push_str("\\r"),
'\t' => out.push_str("\\t"),
c if c <= '\u{001f}' => {
write!(out, "\\u{:04x}", c as u32).expect("write to String");
}
c => out.push(c),
}
}
out.push('"');
}
/// Emit one newline-terminated JSON request. The caller must have checked the
/// ASIC report against the pool target and retained the original job metadata.
pub fn format_submission(share: &Submission<'_>) -> Result<String, SubmitError> {
if share.worker.is_empty() {
return Err(SubmitError::EmptyWorker);
}
if share.job_id.is_empty() {
return Err(SubmitError::EmptyJobId);
}
if share.worker.len() > 128 || share.job_id.len() > 128 {
return Err(SubmitError::FieldTooLong);
}
if share.extranonce2.len() > 32 {
return Err(SubmitError::ExtranonceTooLong);
}
let version_bits = match share.version_mask {
Some(mask) => {
let bits = share.rolled_version & mask.bits();
if mask.apply_submission_bits(share.base_version, bits) != Some(share.rolled_version) {
return Err(SubmitError::UnrepresentableVersion);
}
Some(bits)
}
None if share.rolled_version == share.base_version => None,
None => return Err(SubmitError::UnrepresentableVersion),
};
let mut out = format!(
"{{\"id\":{},\"method\":\"mining.submit\",\"params\":[",
share.request_id
);
json_string(&mut out, share.worker);
out.push(',');
json_string(&mut out, share.job_id);
out.push_str(",\"");
for byte in share.extranonce2 {
write!(out, "{byte:02x}").expect("write to String");
}
write!(out, "\",\"{:08x}\",\"{:08x}\"", share.ntime, share.nonce).expect("write to String");
if let Some(bits) = version_bits {
write!(out, ",\"{bits:08x}\"").expect("write to String");
}
out.push_str("]}\n");
Ok(out)
}
+308
View File
@@ -0,0 +1,308 @@
// SPDX-License-Identifier: MIT
//! Bounded decoding of Bitcoin Stratum V1 subscription and job messages.
//! The network client must enforce a line limit before passing data here.
use crate::difficulty::PoolDifficulty;
use crate::pow::VersionMask;
use crate::stratum_work::{JobError, Sha256Job};
use serde_json::Value;
pub const MAX_POOL_LINE_BYTES: usize = 131_072;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PoolMessageError {
TooLarge,
Json,
WrongMessage,
Unnegotiated,
InvalidField,
InvalidHex,
InvalidWork(JobError),
}
#[derive(Debug, Eq, PartialEq)]
pub struct Subscription {
pub extranonce1: Vec<u8>,
pub extranonce2_size: usize,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ConfigureResult {
pub version_mask: Option<VersionMask>,
pub subscribe_extranonce: bool,
}
#[derive(Debug, Eq, PartialEq)]
pub enum PoolNotification {
SetDifficulty(PoolDifficulty),
SetExtranonce(Subscription),
SetVersionMask(VersionMask),
}
pub struct PoolJob {
pub id: String,
pub clean_jobs: bool,
pub work: Sha256Job,
}
fn parse_json(line: &[u8]) -> Result<Value, PoolMessageError> {
if line.len() > MAX_POOL_LINE_BYTES {
return Err(PoolMessageError::TooLarge);
}
serde_json::from_slice(line).map_err(|_| PoolMessageError::Json)
}
fn hex_bytes(text: &str) -> Result<Vec<u8>, PoolMessageError> {
let bytes = text.as_bytes();
if bytes.len() & 1 != 0 {
return Err(PoolMessageError::InvalidHex);
}
let mut result = Vec::with_capacity(bytes.len() / 2);
for pair in bytes.chunks_exact(2) {
let high = (pair[0] as char)
.to_digit(16)
.ok_or(PoolMessageError::InvalidHex)?;
let low = (pair[1] as char)
.to_digit(16)
.ok_or(PoolMessageError::InvalidHex)?;
result.push(((high << 4) | low) as u8);
}
Ok(result)
}
fn hex_fixed<const N: usize>(field: &Value) -> Result<[u8; N], PoolMessageError> {
let text = field.as_str().ok_or(PoolMessageError::InvalidField)?;
if text.len() != N * 2 {
return Err(PoolMessageError::InvalidField);
}
hex_bytes(text)?
.try_into()
.map_err(|_| PoolMessageError::InvalidField)
}
fn hex_u32(field: &Value) -> Result<u32, PoolMessageError> {
let text = field.as_str().ok_or(PoolMessageError::InvalidField)?;
if text.len() != 8 {
return Err(PoolMessageError::InvalidField);
}
u32::from_str_radix(text, 16).map_err(|_| PoolMessageError::InvalidHex)
}
fn valid_subscription(
extranonce1: Vec<u8>,
extranonce2_size: u64,
) -> Result<Subscription, PoolMessageError> {
if extranonce1.len() > 32 || extranonce2_size > 32 {
return Err(PoolMessageError::InvalidField);
}
Ok(Subscription {
extranonce1,
extranonce2_size: extranonce2_size as usize,
})
}
/// Parse the response to a matching `mining.subscribe` request.
pub fn parse_subscription(line: &[u8], request_id: u64) -> Result<Subscription, PoolMessageError> {
let message = parse_json(line)?;
if message.get("id").and_then(Value::as_u64) != Some(request_id)
|| !message.get("error").is_none_or(Value::is_null)
{
return Err(PoolMessageError::WrongMessage);
}
let result = message
.get("result")
.and_then(Value::as_array)
.ok_or(PoolMessageError::InvalidField)?;
if result.len() != 3 || !result[0].is_array() {
return Err(PoolMessageError::InvalidField);
}
let extranonce1 = hex_bytes(result[1].as_str().ok_or(PoolMessageError::InvalidField)?)?;
let extranonce2_size = result[2].as_u64().ok_or(PoolMessageError::InvalidField)?;
valid_subscription(extranonce1, extranonce2_size)
}
/// Decode the response to a BIP310 configure request that offered version
/// rolling. A pool mask outside this ASIC's changeable bits is unusable: the
/// pool would reconstruct a different block version for submitted shares.
pub fn parse_configure_response(
line: &[u8],
request_id: u64,
) -> Result<Option<VersionMask>, PoolMessageError> {
let message = parse_json(line)?;
if message.get("id").and_then(Value::as_u64) != Some(request_id)
|| !message.get("error").is_none_or(Value::is_null)
{
return Err(PoolMessageError::WrongMessage);
}
let result = message
.get("result")
.and_then(Value::as_object)
.ok_or(PoolMessageError::InvalidField)?;
match result.get("version-rolling") {
Some(Value::Bool(false) | Value::String(_)) => Ok(None),
Some(Value::Bool(true)) => {
let mask = hex_u32(
result
.get("version-rolling.mask")
.ok_or(PoolMessageError::InvalidField)?,
)?;
VersionMask::new(mask)
.map(Some)
.ok_or(PoolMessageError::InvalidField)
}
_ => Err(PoolMessageError::InvalidField),
}
}
/// Decode both offered BIP310 extensions. An omitted extranonce extension is
/// unsupported; its notifications cannot be used without an explicit grant.
pub fn parse_configure_result(
line: &[u8],
request_id: u64,
) -> Result<ConfigureResult, PoolMessageError> {
let version_mask = parse_configure_response(line, request_id)?;
let message = parse_json(line)?;
let result = message
.get("result")
.and_then(Value::as_object)
.ok_or(PoolMessageError::InvalidField)?;
let subscribe_extranonce = match result.get("subscribe-extranonce") {
Some(Value::Bool(value)) => *value,
Some(Value::String(_)) | None => false,
_ => return Err(PoolMessageError::InvalidField),
};
Ok(ConfigureResult {
version_mask,
subscribe_extranonce,
})
}
/// Decode a matching authorization or share-submission result. A false
/// result is an ordinary pool rejection and must not count as an accept.
pub fn parse_boolean_response(line: &[u8], request_id: u64) -> Result<bool, PoolMessageError> {
let message = parse_json(line)?;
if message.get("id").and_then(Value::as_u64) != Some(request_id) {
return Err(PoolMessageError::WrongMessage);
}
match message.get("result") {
Some(Value::Bool(true)) if message.get("error").is_none_or(Value::is_null) => Ok(true),
Some(Value::Bool(false)) => Ok(false),
Some(Value::Null) if !message.get("error").is_none_or(Value::is_null) => Ok(false),
_ => Err(PoolMessageError::InvalidField),
}
}
/// Decode pool control notifications. The caller applies them in stream order:
/// difficulty to the next job, extranonce to subsequent work, and the version
/// mask immediately to all pending submissions.
pub fn parse_control_notification(
line: &[u8],
version_rolling: bool,
subscribe_extranonce: bool,
) -> Result<PoolNotification, PoolMessageError> {
let message = parse_json(line)?;
if !message.get("id").is_none_or(Value::is_null) {
return Err(PoolMessageError::WrongMessage);
}
let method = message
.get("method")
.and_then(Value::as_str)
.ok_or(PoolMessageError::WrongMessage)?;
let params = message
.get("params")
.and_then(Value::as_array)
.ok_or(PoolMessageError::InvalidField)?;
match method {
"mining.set_difficulty" if params.len() == 1 => {
let number = params[0]
.as_number()
.ok_or(PoolMessageError::InvalidField)?;
let difficulty = PoolDifficulty::from_json_number(number)
.map_err(|_| PoolMessageError::InvalidField)?;
Ok(PoolNotification::SetDifficulty(difficulty))
}
"mining.set_version_mask" if params.len() == 1 => {
if !version_rolling {
return Err(PoolMessageError::Unnegotiated);
}
let mask = hex_u32(&params[0])?;
let mask = VersionMask::new(mask).ok_or(PoolMessageError::InvalidField)?;
Ok(PoolNotification::SetVersionMask(mask))
}
"mining.set_extranonce" if params.len() == 2 => {
if !subscribe_extranonce {
return Err(PoolMessageError::Unnegotiated);
}
let extranonce1 = hex_bytes(params[0].as_str().ok_or(PoolMessageError::InvalidField)?)?;
let size = params[1].as_u64().ok_or(PoolMessageError::InvalidField)?;
Ok(PoolNotification::SetExtranonce(valid_subscription(
extranonce1,
size,
)?))
}
"mining.set_difficulty" | "mining.set_version_mask" | "mining.set_extranonce" => {
Err(PoolMessageError::InvalidField)
}
_ => Err(PoolMessageError::WrongMessage),
}
}
/// Parse exactly the nine Bitcoin `mining.notify` parameters into work.
pub fn parse_notify(line: &[u8], subscription: &Subscription) -> Result<PoolJob, PoolMessageError> {
let message = parse_json(line)?;
if message.get("method").and_then(Value::as_str) != Some("mining.notify")
|| !message.get("id").is_none_or(Value::is_null)
{
return Err(PoolMessageError::WrongMessage);
}
let params = message
.get("params")
.and_then(Value::as_array)
.ok_or(PoolMessageError::InvalidField)?;
if params.len() != 9 {
return Err(PoolMessageError::InvalidField);
}
let id = params[0].as_str().ok_or(PoolMessageError::InvalidField)?;
if id.is_empty() || id.len() > 128 {
return Err(PoolMessageError::InvalidField);
}
let branches = params[4].as_array().ok_or(PoolMessageError::InvalidField)?;
if branches.len() > 64 {
return Err(PoolMessageError::InvalidField);
}
let mut merkle_branches = Vec::with_capacity(branches.len());
for branch in branches {
merkle_branches.push(hex_fixed::<32>(branch)?);
}
let work = Sha256Job {
prevhash_stratum: hex_fixed::<32>(&params[1])?,
coinb1: hex_bytes(params[2].as_str().ok_or(PoolMessageError::InvalidField)?)?,
coinb2: hex_bytes(params[3].as_str().ok_or(PoolMessageError::InvalidField)?)?,
merkle_branches,
version: hex_u32(&params[5])?,
nbits: hex_u32(&params[6])?,
ntime: hex_u32(&params[7])?,
extranonce1: subscription.extranonce1.clone(),
extranonce2_size: subscription.extranonce2_size,
};
work.validate().map_err(PoolMessageError::InvalidWork)?;
let clean_jobs = params[8].as_bool().ok_or(PoolMessageError::InvalidField)?;
Ok(PoolJob {
id: id.to_owned(),
clean_jobs,
work,
})
}
#[cfg(test)]
mod configure_tests {
use super::*;
#[test]
fn omitted_extranonce_extension_is_unsupported() {
let line = br#"{"id":1,"result":{"version-rolling":true,"version-rolling.mask":"1fffe000"},"error":null}"#;
let result = parse_configure_result(line, 1).unwrap();
assert!(result.version_mask.is_some());
assert!(!result.subscribe_extranonce);
}
}
+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
);
}
}
+408
View File
@@ -0,0 +1,408 @@
// SPDX-License-Identifier: MIT
//! Bounded newline-framed TCP transport for Bitcoin Stratum V1 pools.
use crate::stratum_v1::MAX_POOL_LINE_BYTES;
use crate::stratum_v1::{
parse_boolean_response, parse_configure_result, parse_subscription, ConfigureResult,
PoolMessageError, Subscription,
};
use serde_json::json;
use std::io::{self, Read, Write};
use std::net::{Shutdown, SocketAddr, TcpStream};
use std::time::{Duration, Instant};
const MAX_EARLY_NOTIFICATIONS: usize = 32;
const MAX_EARLY_NOTIFICATION_BYTES: usize = 262_144;
const READ_SLICE: Duration = Duration::from_millis(1);
const MAX_PARTIAL_AGE: Duration = Duration::from_secs(2);
#[derive(Debug)]
pub enum WireError {
InvalidRequest,
LineTooLong,
Timeout,
Eof,
Closed,
Io(io::Error),
}
#[derive(Debug)]
pub enum HandshakeError {
Wire(WireError),
Pool(PoolMessageError),
Rejected,
TooManyNotifications,
}
pub struct PoolHandshake {
pub subscription: Subscription,
pub configure: ConfigureResult,
/// Notifications received during negotiation, in original wire order.
pub early_notifications: Vec<Vec<u8>>,
}
pub struct StratumWire {
stream: TcpStream,
buffered: Vec<u8>,
partial_started: Option<Instant>,
timeout: Duration,
write_timeout: Duration,
closed: bool,
}
impl StratumWire {
pub fn connect(address: SocketAddr, timeout: Duration) -> Result<Self, WireError> {
if timeout.is_zero() || Instant::now().checked_add(timeout).is_none() {
return Err(WireError::InvalidRequest);
}
let stream = TcpStream::connect_timeout(&address, timeout).map_err(WireError::Io)?;
stream.set_nodelay(true).map_err(WireError::Io)?;
Ok(Self {
stream,
buffered: Vec::new(),
partial_started: None,
timeout,
write_timeout: timeout,
closed: false,
})
}
pub fn from_stream(stream: TcpStream, timeout: Duration) -> Result<Self, WireError> {
if timeout.is_zero() || Instant::now().checked_add(timeout).is_none() {
return Err(WireError::InvalidRequest);
}
stream.set_nodelay(true).map_err(WireError::Io)?;
Ok(Self {
stream,
buffered: Vec::new(),
partial_started: None,
timeout,
write_timeout: timeout,
closed: false,
})
}
pub(crate) fn close(&mut self) {
self.closed = true;
let _ = self.stream.shutdown(Shutdown::Both);
}
pub fn is_closed(&self) -> bool {
self.closed
}
pub(crate) fn cap_write_timeout(&mut self, limit: Duration) {
self.write_timeout = self.write_timeout.min(limit);
}
fn remaining(deadline: Instant) -> Result<Duration, WireError> {
deadline
.checked_duration_since(Instant::now())
.filter(|remaining| !remaining.is_zero())
.ok_or(WireError::Timeout)
}
fn transport_error(error: io::Error) -> WireError {
match error.kind() {
io::ErrorKind::TimedOut | io::ErrorKind::WouldBlock => WireError::Timeout,
_ => WireError::Io(error),
}
}
fn read_line_before(&mut self, deadline: Instant) -> Result<Vec<u8>, WireError> {
if self.closed {
return Err(WireError::Closed);
}
loop {
if let Some(end) = self.buffered.iter().position(|byte| *byte == b'\n') {
if end + 1 > MAX_POOL_LINE_BYTES {
self.close();
return Err(WireError::LineTooLong);
}
let line = self.buffered.drain(..=end).collect();
self.partial_started = if self.buffered.is_empty() {
None
} else {
self.partial_started.or_else(|| Some(Instant::now()))
};
return Ok(line);
}
if self.buffered.len() >= MAX_POOL_LINE_BYTES {
self.close();
return Err(WireError::LineTooLong);
}
let remaining = match Self::remaining(deadline) {
Ok(value) => value,
Err(error) => {
if !self.buffered.is_empty() {
self.close();
}
return Err(error);
}
};
if let Err(error) = self.stream.set_read_timeout(Some(remaining)) {
self.close();
return Err(WireError::Io(error));
}
let mut chunk = [0_u8; 4096];
match self.stream.read(&mut chunk) {
Ok(0) => {
self.close();
return Err(WireError::Eof);
}
Ok(length) => {
if self.buffered.is_empty() {
self.partial_started = Some(Instant::now());
}
self.buffered.extend_from_slice(&chunk[..length]);
}
Err(error) => {
let error = Self::transport_error(error);
if !matches!(error, WireError::Timeout) || !self.buffered.is_empty() {
self.close();
}
return Err(error);
}
}
}
}
pub fn read_line(&mut self) -> Result<Vec<u8>, WireError> {
self.read_line_before(Instant::now() + self.timeout)
}
/// Check one socket slice without coupling ASIC polling to pool silence.
/// An unfinished line has its own absolute deadline across calls.
pub fn try_read_line(&mut self) -> Result<Option<Vec<u8>>, WireError> {
if self.closed {
return Err(WireError::Closed);
}
if let Some(line) = self.try_read_line_buffered()? {
return Ok(Some(line));
}
if self
.partial_started
.is_some_and(|start| start.elapsed() >= MAX_PARTIAL_AGE)
{
self.close();
return Err(WireError::Timeout);
}
self.stream
.set_read_timeout(Some(READ_SLICE))
.map_err(WireError::Io)?;
let mut chunk = [0_u8; 4096];
match self.stream.read(&mut chunk) {
Ok(0) => {
self.close();
Err(WireError::Eof)
}
Ok(length) => {
if self.buffered.is_empty() {
self.partial_started = Some(Instant::now());
}
self.buffered.extend_from_slice(&chunk[..length]);
self.try_read_line_buffered()
}
Err(error)
if matches!(
error.kind(),
io::ErrorKind::TimedOut | io::ErrorKind::WouldBlock
) =>
{
Ok(None)
}
Err(error) => {
self.close();
Err(WireError::Io(error))
}
}
}
fn try_read_line_buffered(&mut self) -> Result<Option<Vec<u8>>, WireError> {
if let Some(end) = self.buffered.iter().position(|byte| *byte == b'\n') {
if end + 1 > MAX_POOL_LINE_BYTES {
self.close();
return Err(WireError::LineTooLong);
}
let line = self.buffered.drain(..=end).collect();
self.partial_started = if self.buffered.is_empty() {
None
} else {
self.partial_started.or_else(|| Some(Instant::now()))
};
return Ok(Some(line));
}
if self.buffered.len() >= MAX_POOL_LINE_BYTES {
self.close();
return Err(WireError::LineTooLong);
}
Ok(None)
}
fn send_line_before(&mut self, line: &[u8], deadline: Instant) -> Result<(), WireError> {
if self.closed {
return Err(WireError::Closed);
}
if line.is_empty()
|| line.len() > MAX_POOL_LINE_BYTES
|| line.last() != Some(&b'\n')
|| line[..line.len() - 1].contains(&b'\n')
{
return Err(WireError::InvalidRequest);
}
let mut sent = 0;
while sent < line.len() {
let remaining = match Self::remaining(deadline) {
Ok(value) => value,
Err(error) => {
self.close();
return Err(error);
}
};
if let Err(error) = self.stream.set_write_timeout(Some(remaining)) {
self.close();
return Err(WireError::Io(error));
}
match self.stream.write(&line[sent..]) {
Ok(0) => {
self.close();
return Err(WireError::Eof);
}
Ok(length) => sent += length,
Err(error) => {
self.close();
return Err(Self::transport_error(error));
}
}
}
Ok(())
}
pub fn send_line(&mut self, line: &[u8]) -> Result<(), WireError> {
self.send_line_before(line, Instant::now() + self.write_timeout)
}
fn read_reply(
&mut self,
request_id: u64,
deadline: Instant,
early: &mut Vec<Vec<u8>>,
early_bytes: &mut usize,
) -> Result<Vec<u8>, HandshakeError> {
loop {
let line = self
.read_line_before(deadline)
.map_err(HandshakeError::Wire)?;
let message: serde_json::Value = serde_json::from_slice(&line)
.map_err(|_| HandshakeError::Pool(PoolMessageError::Json))?;
if message.get("id").and_then(serde_json::Value::as_u64) == Some(request_id) {
return Ok(line);
}
if !message.get("id").is_none_or(serde_json::Value::is_null)
|| !matches!(
message.get("method").and_then(serde_json::Value::as_str),
Some(
"mining.set_difficulty"
| "mining.set_version_mask"
| "mining.set_extranonce"
| "mining.notify"
)
)
{
return Err(HandshakeError::Pool(PoolMessageError::WrongMessage));
}
*early_bytes += line.len();
if early.len() >= MAX_EARLY_NOTIFICATIONS || *early_bytes > MAX_EARLY_NOTIFICATION_BYTES
{
return Err(HandshakeError::TooManyNotifications);
}
early.push(line);
}
}
/// Negotiate BIP310, subscribe, and authorize in that order. The entire
/// handshake shares one absolute deadline; early notifications are kept
/// for the caller to apply before reading new pool lines.
pub fn handshake(
&mut self,
agent: &str,
worker: &str,
password: &str,
timeout: Duration,
) -> Result<PoolHandshake, HandshakeError> {
let result = self.handshake_inner(agent, worker, password, timeout);
if result.is_err() {
self.close();
}
result
}
fn handshake_inner(
&mut self,
agent: &str,
worker: &str,
password: &str,
timeout: Duration,
) -> Result<PoolHandshake, HandshakeError> {
let deadline = Instant::now()
.checked_add(timeout)
.filter(|_| !timeout.is_zero())
.ok_or(HandshakeError::Wire(WireError::InvalidRequest))?;
let subscribe = subscribe_request(2, agent).map_err(HandshakeError::Wire)?;
let authorize = authorize_request(3, worker, password).map_err(HandshakeError::Wire)?;
let mut early_notifications = Vec::new();
let mut early_bytes = 0;
self.send_line_before(configure_request(1).as_bytes(), deadline)
.map_err(HandshakeError::Wire)?;
let configure = self.read_reply(1, deadline, &mut early_notifications, &mut early_bytes)?;
let configure = parse_configure_result(&configure, 1).map_err(HandshakeError::Pool)?;
self.send_line_before(subscribe.as_bytes(), deadline)
.map_err(HandshakeError::Wire)?;
let subscription =
self.read_reply(2, deadline, &mut early_notifications, &mut early_bytes)?;
let subscription = parse_subscription(&subscription, 2).map_err(HandshakeError::Pool)?;
self.send_line_before(authorize.as_bytes(), deadline)
.map_err(HandshakeError::Wire)?;
let authorized =
self.read_reply(3, deadline, &mut early_notifications, &mut early_bytes)?;
if !parse_boolean_response(&authorized, 3).map_err(HandshakeError::Pool)? {
return Err(HandshakeError::Rejected);
}
Ok(PoolHandshake {
subscription,
configure,
early_notifications,
})
}
}
/// Offer BIP310 version rolling and extranonce updates before subscribing.
pub fn configure_request(id: u64) -> String {
json!({
"id": id,
"method": "mining.configure",
"params": [
["version-rolling", "subscribe-extranonce"],
{"version-rolling.mask": "1fffe000", "version-rolling.min-bit-count": 0}
]
})
.to_string()
+ "\n"
}
pub fn subscribe_request(id: u64, agent: &str) -> Result<String, WireError> {
if agent.is_empty() || agent.len() > 128 {
return Err(WireError::InvalidRequest);
}
Ok(json!({"id": id, "method": "mining.subscribe", "params": [agent]}).to_string() + "\n")
}
pub fn authorize_request(id: u64, worker: &str, password: &str) -> Result<String, WireError> {
if worker.is_empty() || worker.len() > 128 || password.len() > 256 {
return Err(WireError::InvalidRequest);
}
Ok(
json!({"id": id, "method": "mining.authorize", "params": [worker, password]}).to_string()
+ "\n",
)
}
+83
View File
@@ -0,0 +1,83 @@
// SPDX-License-Identifier: MIT
//! Construct SHA-256 Stratum V1 work after a protocol client decodes notify.
//! This module assembles headers; it never searches for nonces.
use crate::pow::sha256d;
const MAX_COINBASE_BYTES: usize = 65_536;
const MAX_MERKLE_BRANCHES: usize = 64;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum JobError {
InvalidExtranonceSize,
CoinbaseTooLarge,
TooManyMerkleBranches,
ExtranonceLength,
}
/// Binary fields from `mining.notify`, plus `mining.subscribe` extranonce data.
/// `prevhash_stratum` is the eight word-swapped 32-bit words sent on the wire.
pub struct Sha256Job {
pub prevhash_stratum: [u8; 32],
pub coinb1: Vec<u8>,
pub coinb2: Vec<u8>,
pub merkle_branches: Vec<[u8; 32]>,
pub version: u32,
pub nbits: u32,
pub ntime: u32,
pub extranonce1: Vec<u8>,
pub extranonce2_size: usize,
}
impl Sha256Job {
pub fn validate(&self) -> Result<(), JobError> {
if self.extranonce1.len() > 32 || self.extranonce2_size > 32 {
return Err(JobError::InvalidExtranonceSize);
}
let total = self
.coinb1
.len()
.checked_add(self.extranonce1.len())
.and_then(|sum| sum.checked_add(self.extranonce2_size))
.and_then(|sum| sum.checked_add(self.coinb2.len()));
if total.is_none_or(|sum| sum > MAX_COINBASE_BYTES) {
return Err(JobError::CoinbaseTooLarge);
}
if self.merkle_branches.len() > MAX_MERKLE_BRANCHES {
return Err(JobError::TooManyMerkleBranches);
}
Ok(())
}
pub fn nonce_zero_header(&self, extranonce2: &[u8], ntime: u32) -> Result<[u8; 80], JobError> {
self.validate()?;
if extranonce2.len() != self.extranonce2_size {
return Err(JobError::ExtranonceLength);
}
let mut coinbase = Vec::with_capacity(
self.coinb1.len() + self.extranonce1.len() + extranonce2.len() + self.coinb2.len(),
);
coinbase.extend_from_slice(&self.coinb1);
coinbase.extend_from_slice(&self.extranonce1);
coinbase.extend_from_slice(extranonce2);
coinbase.extend_from_slice(&self.coinb2);
let mut root = sha256d(&coinbase);
for branch in &self.merkle_branches {
let mut pair = [0_u8; 64];
pair[..32].copy_from_slice(&root);
pair[32..].copy_from_slice(branch);
root = sha256d(&pair);
}
let mut header = [0_u8; 80];
header[..4].copy_from_slice(&self.version.to_le_bytes());
for (index, word) in self.prevhash_stratum.chunks_exact(4).enumerate() {
for (offset, byte) in word.iter().rev().enumerate() {
header[4 + index * 4 + offset] = *byte;
}
}
header[36..68].copy_from_slice(&root);
header[68..72].copy_from_slice(&ntime.to_le_bytes());
header[72..76].copy_from_slice(&self.nbits.to_le_bytes());
Ok(header)
}
}
+506
View File
@@ -0,0 +1,506 @@
// 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);
}
/// 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
}
/// 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;"));
}
}
+975
View File
@@ -0,0 +1,975 @@
// SPDX-License-Identifier: MIT
//! On-box web UI and its API.
//!
//! The page is a convenience; `/api/...` stays the interface of record, so every
//! value the UI shows is also available as JSON and nothing is reachable only
//! through the browser.
//!
//! No framework and no dependency: the request parser is bounded, only the
//! methods each route needs are accepted, and every response closes the
//! connection. Files and Terminal are gated on a token so a shared network
//! cannot silently use them.
use crate::management::MiningStatus;
use crate::ui;
use serde_json::{json, Value};
use std::fs;
use std::io::{self, Read, Write};
use std::net::{SocketAddr, TcpListener, TcpStream};
use std::path::{Path, PathBuf};
use std::process::Command;
use std::sync::Arc;
use std::time::Duration;
const MAX_HEAD: usize = 8192;
const MAX_BODY: usize = 64 * 1024;
const CLIENT_TIMEOUT: Duration = Duration::from_millis(2000);
const DECK_DIR: &str = "/var/lib/alkane/decks";
const TOKEN_FILE: &str = "/var/lib/alkane/ui-token";
const LOG_FILE: &str = "/var/log/messages";
/// Bind and serve until the listener fails.
pub fn serve(bind: SocketAddr, status: Arc<MiningStatus>) -> io::Result<()> {
let listener = TcpListener::bind(bind)?;
serve_listener(listener, status)
}
/// Serve on an already-bound listener.
pub fn serve_listener(listener: TcpListener, status: Arc<MiningStatus>) -> io::Result<()> {
for stream in listener.incoming() {
let Ok(stream) = stream else { continue };
let status = Arc::clone(&status);
std::thread::spawn(move || {
let _ = handle(stream, &status);
});
}
Ok(())
}
struct Request {
method: String,
path: String,
query: String,
body: String,
}
impl Request {
fn param(&self, key: &str) -> Option<String> {
self.query.split('&').find_map(|pair| {
let (k, v) = pair.split_once('=')?;
if k == key {
Some(percent_decode(v))
} else {
None
}
})
}
fn param_or(&self, key: &str, fallback: &str) -> String {
self.param(key).unwrap_or_else(|| fallback.to_string())
}
}
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()
}
/// Handle one HTTP request.
pub fn handle(mut stream: TcpStream, status: &MiningStatus) -> io::Result<()> {
stream.set_read_timeout(Some(CLIENT_TIMEOUT))?;
stream.set_write_timeout(Some(CLIENT_TIMEOUT))?;
let mut raw = Vec::new();
let mut chunk = [0_u8; 1024];
let mut head_end = None;
while head_end.is_none() {
let count = stream.read(&mut chunk)?;
if count == 0 {
break;
}
raw.extend_from_slice(&chunk[..count]);
if raw.len() > MAX_HEAD {
return respond(&mut stream, 431, "text/plain", b"request head too large");
}
head_end = raw.windows(4).position(|w| w == b"\r\n\r\n").map(|i| i + 4);
}
let Some(head_end) = head_end else {
return respond(&mut stream, 400, "text/plain", b"bad request");
};
let head = String::from_utf8_lossy(&raw[..head_end]).into_owned();
let mut lines = head.lines();
let mut first = lines.next().unwrap_or("").split_whitespace();
let method = first.next().unwrap_or("").to_string();
let target = first.next().unwrap_or("/").to_string();
let (path, query) = match target.split_once('?') {
Some((p, q)) => (p.to_string(), q.to_string()),
None => (target.clone(), String::new()),
};
let length = lines
.find_map(|line| {
let (name, value) = line.split_once(':')?;
if name.eq_ignore_ascii_case("content-length") {
value.trim().parse::<usize>().ok()
} else {
None
}
})
.unwrap_or(0);
if length > MAX_BODY {
return respond(&mut stream, 413, "text/plain", b"body too large");
}
let mut body = raw[head_end..].to_vec();
while body.len() < length {
let count = stream.read(&mut chunk)?;
if count == 0 {
break;
}
body.extend_from_slice(&chunk[..count]);
}
let request = Request {
method,
path,
query,
body: String::from_utf8_lossy(&body).into_owned(),
};
route(&mut stream, status, &request)
}
fn route(stream: &mut TcpStream, status: &MiningStatus, request: &Request) -> io::Result<()> {
if dashboard_route(stream, request)? {
return Ok(());
}
match (request.method.as_str(), request.path.as_str()) {
("GET", "/") => html(stream, "Dashboard", &ui::dashboard_page("dashboard", true)),
("GET", "/mining") => html(
stream,
"Mining overview",
&ui::dashboard_page("overview", true),
),
("GET", "/mining/hashboards") => {
let hw = status.hardware_document();
let rows: Vec<Vec<String>> = hw["chains"]
.as_array()
.map(|chains| {
chains
.iter()
.map(|chain| {
vec![
chain["index"].to_string(),
chain["chip"].as_str().unwrap_or("-").to_string(),
chain["chips_found"].to_string(),
chain["eeprom"].to_string(),
chain["response_per_mille"].to_string(),
]
})
.collect()
})
.unwrap_or_default();
html(
stream,
"Hashboards",
&ui::table_page(
&["#", "chip", "chips", "eeprom", "response per mille"],
&rows,
),
)
}
("GET", "/mining/power") => {
let hw = status.hardware_document();
let point = &hw["operating_point"];
html(
stream,
"Power supply",
&ui::kv_page(&[
(
"supply",
hw["psu"].as_str().unwrap_or("not identified").to_string(),
),
(
"voltage range (mV)",
format!(
"{} - {}",
hw["envelope"]["v_min_mv"], hw["envelope"]["v_max_mv"]
),
),
(
"frequency range (MHz)",
format!(
"{} - {}",
hw["envelope"]["f_min_mhz"], hw["envelope"]["f_max_mhz"]
),
),
(
"running at",
format!(
"{} mV / {} MHz",
point["voltage_mv"], point["frequency_mhz"]
),
),
("target", hw["target"].as_str().unwrap_or("-").to_string()),
]),
)
}
("GET", "/mining/fans") => {
let hw = status.hardware_document();
let rows: Vec<Vec<String>> = hw["fan_zones"]
.as_array()
.map(|zones| {
zones
.iter()
.map(|zone| vec![zone["fan"].to_string(), zone["zones"].to_string()])
.collect()
})
.unwrap_or_default();
html(
stream,
"Fans",
&ui::table_page(&["fan", "zones it cools"], &rows),
)
}
("GET", "/settings/system") => html(
stream,
"System",
&ui::sections_page(&[
("Identity", ui::kv_page(&system_rows())),
("Network", ui::kv_page(&network_rows())),
("Updates", ui::kv_page(&update_rows())),
]),
),
("GET", "/settings/drivers") => html(
stream,
"Drivers",
&ui::sections_page(&[
("Chains", ui::kv_page(&driver_rows(status))),
("Firmware", ui::kv_page(&update_rows())),
]),
),
("GET", "/settings/security") => html(stream, "Security", &ui::kv_page(&security_rows())),
("GET", "/settings/services") => html(
stream,
"Services",
&ui::table_page(&["service", "running"], &service_rows()),
),
("GET", "/settings/monitor") => {
html(stream, "Monitor", &ui::kv_page(&monitor_rows(status)))
}
("GET", "/settings/logs") => {
let lines = request
.param_or("lines", "200")
.parse::<usize>()
.unwrap_or(200)
.min(2000);
let tail = tail_file(Path::new(LOG_FILE), lines);
html(
stream,
"Logs",
&format!(
"<p class=\"muted\">{}</p><pre>{}</pre>",
ui::escape(LOG_FILE),
ui::escape(&tail)
),
)
}
("GET", "/settings/files") => {
let path = request.param_or("path", "/");
html(stream, "Files", &files_page(&path))
}
("GET", "/settings/terminal") => html(stream, "Terminal", &terminal_page()),
("POST", "/api/terminal") => {
if !authorised(request) {
return respond(stream, 403, "text/plain", b"terminal requires a token");
}
let command = request.param_or("cmd", "");
let output = run_shell(&command);
respond(stream, 200, "text/plain; charset=utf-8", output.as_bytes())
}
("GET", "/api/hardware") => json_response(stream, &status.hardware_document()),
("GET", "/api/summary") => json_response(stream, &status.summary_document()),
("GET", "/api/dashboard") => {
let deck = request.param_or("deck", "dashboard");
json_response(stream, &load_deck(&deck))
}
("PUT", "/api/dashboard") => {
let deck = request.param_or("deck", "dashboard");
if request.param("reset").is_some() {
let doc = ui::default_deck(&deck);
let _ = save_deck(&deck, &doc);
return json_response(stream, &doc);
}
match ui::validate_deck(&request.body) {
Ok(doc) => match save_deck(&deck, &doc) {
Ok(()) => json_response(stream, &doc),
Err(error) => respond(stream, 500, "text/plain", error.as_bytes()),
},
Err(reason) => respond(stream, 400, "text/plain", reason.as_bytes()),
}
}
("GET", "/api/logs") => {
let lines = request
.param_or("lines", "200")
.parse::<usize>()
.unwrap_or(200)
.min(2000);
let tail = tail_file(Path::new(LOG_FILE), lines);
json_response(
stream,
&json!({"file": LOG_FILE, "lines": tail.lines().collect::<Vec<_>>()}),
)
}
("GET", "/api/files") => {
let path = request.param_or("path", "/");
json_response(stream, &files_document(&path))
}
("GET", "/api/file") => {
let path = request.param_or("path", "");
match read_text(Path::new(&path)) {
Some(text) => respond(stream, 200, "text/plain; charset=utf-8", text.as_bytes()),
None => respond(stream, 404, "text/plain", b"not a readable text file"),
}
}
_ => respond(stream, 404, "text/plain", b"not found"),
}
}
/// Where the dashboard keeps operator settings.
fn settings_path() -> std::path::PathBuf {
let etc = std::path::Path::new("/etc/alkane/settings.json");
if etc.exists() || std::path::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")
}
/// Serve the schema-driven UI: assets, pages and the settings form.
///
/// Returns `None` when the path is not a dashboard path, so the hand-written
/// API routes below keep working unchanged.
fn dashboard_route(stream: &mut TcpStream, request: &Request) -> io::Result<bool> {
let path = request.path.clone();
if let Some(name) = path.strip_prefix("/assets/") {
for (file, css) in crate::dashboard::Dashboard::stylesheets() {
if name == file {
return respond(stream, 200, "text/css; charset=utf-8", css.as_bytes()).map(|_| true);
}
}
return Ok(false);
}
if request.method == "POST" && path == "/settings" {
let mut dash = crate::dashboard::Dashboard::load(settings_path());
return match dash.submit(&request.body) {
Ok(()) => respond(stream, 303, "text/plain", b"see /").map(|_| true),
Err(failures) => {
let mut text = String::new();
for (key, why) in failures {
text.push_str(&format!("{key}: {why}\n"));
}
respond(stream, 422, "text/plain; charset=utf-8", text.as_bytes()).map(|_| true)
}
};
}
if request.method != "GET" {
return Ok(false);
}
let mut parts = path.trim_start_matches('/').split('/');
let section = match parts.next() {
Some(section) if !section.is_empty() => section,
_ => return Ok(false),
};
let dash = crate::dashboard::Dashboard::load(settings_path());
let nav = match dash.nav() {
Ok(nav) => nav,
Err(_) => return Ok(false),
};
let known = nav.sections.iter().find(|s| s.slug == section);
let known = match known {
Some(section) => section,
None => return Ok(false),
};
let tab = parts.next().unwrap_or_else(|| {
known.tabs.first().map(|tab| tab.slug.as_str()).unwrap_or("")
});
if !known.tabs.iter().any(|t| t.slug == tab) {
return Ok(false);
}
let html = dash.page(section, tab, &std::collections::BTreeMap::new()).into_string();
respond(stream, 200, "text/html; charset=utf-8", html.as_bytes()).map(|_| true)
}
fn html(stream: &mut TcpStream, title: &str, body: &str) -> io::Result<()> {
let page = ui::page(path_for(title), title, body);
respond(stream, 200, "text/html; charset=utf-8", page.as_bytes())
}
fn path_for(title: &str) -> &'static str {
match title {
"Dashboard" => "/",
"Mining overview" => "/mining",
"Hashboards" => "/mining/hashboards",
"Power supply" => "/mining/power",
"Fans" => "/mining/fans",
"System" => "/settings/system",
"Drivers" => "/settings/drivers",
"Security" => "/settings/security",
"Services" => "/settings/services",
"Monitor" => "/settings/monitor",
"Logs" => "/settings/logs",
"Files" => "/settings/files",
"Terminal" => "/settings/terminal",
_ => "/",
}
}
fn json_response(stream: &mut TcpStream, value: &Value) -> io::Result<()> {
respond(
stream,
200,
"application/json",
value.to_string().as_bytes(),
)
}
// --- dashboard storage -------------------------------------------------------
fn deck_path(deck: &str) -> PathBuf {
let safe: String = deck
.chars()
.filter(|c| c.is_ascii_alphanumeric() || *c == '-' || *c == '_')
.collect();
Path::new(DECK_DIR).join(format!("{safe}.json"))
}
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())?;
fs::write(&path, text).map_err(|e| format!("cannot write {}: {e}", path.display()))
}
// --- page data ---------------------------------------------------------------
fn system_rows() -> Vec<(&'static str, String)> {
vec![
(
"hostname",
read_trim("/proc/sys/kernel/hostname").unwrap_or_else(|| "unknown".into()),
),
(
"kernel",
read_trim("/proc/sys/kernel/osrelease").unwrap_or_else(|| "unknown".into()),
),
(
"machine",
read_trim("/proc/device-tree/model").unwrap_or_else(|| "unknown".into()),
),
(
"uptime",
read_trim("/proc/uptime")
.and_then(|s| s.split_whitespace().next().map(|v| v.to_string()))
.map(|s| format!("{s} s"))
.unwrap_or_else(|| "unknown".into()),
),
(
"load",
read_trim("/proc/loadavg").unwrap_or_else(|| "unknown".into()),
),
(
"memory",
fs::read_to_string("/proc/meminfo")
.ok()
.and_then(|text| {
let total = text
.lines()
.find(|l| l.starts_with("MemTotal:"))?
.split_whitespace()
.nth(1)?;
let free = text
.lines()
.find(|l| l.starts_with("MemAvailable:"))?
.split_whitespace()
.nth(1)?;
Some(format!("{free} kB available of {total} kB"))
})
.unwrap_or_else(|| "unknown".into()),
),
(
"api",
"JSON under /api is the interface of record".to_string(),
),
]
}
fn network_rows() -> Vec<(&'static str, String)> {
let mut rows: Vec<(&'static str, String)> = Vec::new();
if let Ok(text) = fs::read_to_string("/proc/net/route") {
let default: Vec<String> = text
.lines()
.skip(1)
.filter_map(|line| {
let mut fields = line.split_whitespace();
let iface = fields.next()?.to_string();
let dest = fields.next().unwrap_or("");
if dest == "00000000" {
Some(iface)
} else {
None
}
})
.collect();
rows.push((
"default route",
if default.is_empty() {
"none".into()
} else {
default.join(", ")
},
));
}
for iface in ["eth0", "wlan0"] {
if let Ok(text) = fs::read_to_string("/proc/net/dev") {
if let Some(line) = text.lines().find(|l| l.trim_start().starts_with(iface)) {
let counters: Vec<&str> = line.split_whitespace().collect();
if counters.len() > 9 {
rows.push((
iface,
format!("rx {} bytes, tx {} bytes", counters[1], counters[9]),
));
}
}
}
}
rows.push((
"ssh",
if running("dropbear") {
"listening".into()
} else {
"not running".into()
},
));
rows
}
fn update_rows() -> Vec<(&'static str, String)> {
vec![
(
"image",
read_trim("/etc/alkane-version").unwrap_or_else(|| "alkane-os".into()),
),
(
"kernel",
read_trim("/proc/sys/kernel/osrelease").unwrap_or_else(|| "unknown".into()),
),
(
"binary",
read_trim("/etc/alkane-build").unwrap_or_else(|| "unknown".into()),
),
(
"update channel",
"manual (no updater installed yet)".to_string(),
),
]
}
fn driver_rows(status: &MiningStatus) -> Vec<(&'static str, String)> {
let hw = status.hardware_document();
vec![
(
"chain driver",
hw["chip"].as_str().unwrap_or("not identified").to_string(),
),
(
"board profile",
hw["profile"]
.as_str()
.unwrap_or("not identified")
.to_string(),
),
(
"power supply",
hw["psu"].as_str().unwrap_or("not identified").to_string(),
),
(
"chains detected",
hw["chains"]
.as_array()
.map(|c| c.len())
.unwrap_or(0)
.to_string(),
),
(
"chains active",
hw["active_chains"]
.as_array()
.map(|c| c.len())
.unwrap_or(0)
.to_string(),
),
(
"stopped",
if hw["stopped"].is_null() {
"no".into()
} else {
hw["stopped"].to_string()
},
),
]
}
fn security_rows() -> Vec<(&'static str, String)> {
let users = fs::read_to_string("/etc/passwd")
.map(|text| {
text.lines()
.filter_map(|line| line.split(':').next())
.collect::<Vec<_>>()
.join(", ")
})
.unwrap_or_else(|_| "unreadable".into());
let keys = fs::read_to_string("/root/.ssh/authorized_keys")
.map(|text| {
text.lines()
.filter(|l| !l.trim().is_empty())
.count()
.to_string()
})
.unwrap_or_else(|_| "0".into());
let dropbear = if running("dropbear") {
"running"
} else {
"not running"
};
vec![
("accounts", users),
("root ssh keys", keys),
("dropbear", dropbear.to_string()),
(
"web files and terminal",
if ui_token().is_some() {
"token configured".into()
} else {
"disabled until a token exists".into()
},
),
]
}
fn service_rows() -> Vec<Vec<String>> {
let mut rows = Vec::new();
if let Ok(entries) = fs::read_dir("/etc/init.d") {
for entry in entries.flatten() {
let name = entry.file_name().to_string_lossy().into_owned();
if let Some(service) = name.strip_prefix('S') {
let label = service
.trim_start_matches(|c: char| c.is_ascii_digit())
.to_string();
rows.push(vec![
label.clone(),
if running(&label) { "yes" } else { "no" }.to_string(),
]);
}
}
}
rows.sort();
rows
}
fn monitor_rows(status: &MiningStatus) -> Vec<(&'static str, String)> {
let hw = status.hardware_document();
let point = &hw["operating_point"];
vec![
(
"load",
read_trim("/proc/loadavg").unwrap_or_else(|| "-".into()),
),
("frequency", format!("{} MHz", hw["frequency_mhz"])),
("voltage", format!("{} mV", point["voltage_mv"])),
("target", hw["target"].as_str().unwrap_or("-").to_string()),
(
"chains",
format!(
"{} active",
hw["active_chains"].as_array().map(|c| c.len()).unwrap_or(0)
),
),
(
"memory",
read_trim("/proc/meminfo")
.and_then(|t| {
t.lines()
.find(|l| l.starts_with("MemAvailable:"))
.map(|l| l.trim().to_string())
})
.unwrap_or_else(|| "-".into()),
),
]
}
fn files_page(path: &str) -> String {
let doc = files_document(path);
let mut rows = Vec::new();
if let Some(entries) = doc["entries"].as_array() {
for entry in entries {
rows.push(vec![
entry["name"].as_str().unwrap_or("-").to_string(),
entry["kind"].as_str().unwrap_or("-").to_string(),
entry["size"].to_string(),
]);
}
}
format!(
"<div class=\"bar\"><input type=\"text\" id=\"path\" value=\"{}\"><span class=\"muted\">read-only listing; individual text files are at /api/file?path=</span></div>{}",
ui::escape(path),
ui::table_page(&["name", "kind", "size"], &rows)
)
}
fn terminal_page() -> String {
if ui_token().is_none() {
return format!(
"<p class=\"muted\">Terminal is disabled until a token exists at {}. Create one with \
<code>head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \\n' &gt; {}; chmod 600 {}</code>.</p>",
TOKEN_FILE, TOKEN_FILE, TOKEN_FILE
);
}
"<div class=\"bar\"><input type=\"text\" id=\"cmd\" placeholder=\"command\"><button id=\"run\">Run</button>\
<span class=\"muted\">commands run as root on this miner</span></div><pre id=\"out\">ready</pre>\
<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>"
.to_string()
}
fn files_document(path: &str) -> Value {
let root = Path::new(path);
let mut entries = Vec::new();
if let Ok(listing) = fs::read_dir(root) {
for entry in listing.flatten() {
let meta = entry.metadata().ok();
entries.push(json!({
"name": entry.file_name().to_string_lossy(),
"kind": if meta.as_ref().map(|m| m.is_dir()).unwrap_or(false) { "dir" } else { "file" },
"size": meta.map(|m| m.len()).unwrap_or(0),
}));
}
}
entries.sort_by(|a, b| a["name"].as_str().cmp(&b["name"].as_str()));
json!({"path": path, "entries": entries})
}
fn read_text(path: &Path) -> Option<String> {
let meta = fs::metadata(path).ok()?;
if !meta.is_file() || meta.len() > 256 * 1024 {
return None;
}
String::from_utf8(fs::read(path).ok()?).ok()
}
fn tail_file(path: &Path, lines: usize) -> String {
let text = match read_text(path) {
Some(text) => text,
None => return String::from("no readable log yet"),
};
let all: Vec<&str> = text.lines().collect();
let start = all.len().saturating_sub(lines);
all[start..].join("\n")
}
fn read_trim(path: &str) -> Option<String> {
fs::read_to_string(path)
.ok()
.map(|text| text.trim().replace('\0', ""))
}
fn running(name: &str) -> bool {
Command::new("pgrep")
.arg("-x")
.arg(name)
.output()
.map(|out| out.status.success())
.unwrap_or(false)
}
fn run_shell(command: &str) -> String {
if command.trim().is_empty() {
return "no command".to_string();
}
match Command::new("/bin/sh").arg("-c").arg(command).output() {
Ok(out) => {
let mut text = String::from_utf8_lossy(&out.stdout).into_owned();
text.push_str(&String::from_utf8_lossy(&out.stderr));
if text.len() > 64 * 1024 {
text.truncate(64 * 1024);
}
text
}
Err(error) => format!("cannot run: {error}"),
}
}
// --- access control ----------------------------------------------------------
fn ui_token() -> Option<String> {
if let Ok(token) = std::env::var("ALKANE_UI_TOKEN") {
if !token.is_empty() {
return Some(token);
}
}
fs::read_to_string(TOKEN_FILE)
.ok()
.map(|t| t.trim().to_string())
.filter(|t| !t.is_empty())
}
fn authorised(request: &Request) -> bool {
match (ui_token(), request.param("token")) {
(Some(expected), Some(given)) => given == expected,
_ => false,
}
}
fn respond(stream: &mut TcpStream, code: u16, content_type: &str, body: &[u8]) -> io::Result<()> {
let reason = match code {
200 => "OK",
400 => "Bad Request",
403 => "Forbidden",
404 => "Not Found",
413 => "Payload Too Large",
431 => "Request Header Fields Too Large",
500 => "Internal Server Error",
_ => "Error",
};
let header = format!(
"HTTP/1.1 {code} {reason}\r\nContent-Type: {content_type}\r\nContent-Length: {}\r\nConnection: close\r\nCache-Control: no-store\r\n\r\n",
body.len()
);
stream.write_all(header.as_bytes())?;
stream.write_all(body)?;
stream.flush()
}
#[cfg(test)]
mod tests {
use super::*;
fn client(request: &str) -> String {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let addr = listener.local_addr().unwrap();
let status = Arc::new(MiningStatus::new());
let worker = std::thread::spawn(move || {
let (stream, _) = listener.accept().unwrap();
handle(stream, &status).unwrap();
});
let mut stream = TcpStream::connect(addr).unwrap();
stream.write_all(request.as_bytes()).unwrap();
let mut reply = String::new();
stream.read_to_string(&mut reply).unwrap();
worker.join().unwrap();
reply
}
#[test]
fn the_dashboard_serves_a_page_with_the_sidebar() {
let reply = client("GET / HTTP/1.1\r\nHost: x\r\n\r\n");
assert!(reply.starts_with("HTTP/1.1 200 OK"));
assert!(reply.contains("Power Supply"));
assert!(reply.contains("Terminal"));
assert!(reply.contains("text/html"));
}
#[test]
fn every_page_answers() {
for path in [
"/mining",
"/mining/hashboards",
"/mining/power",
"/mining/fans",
"/settings/system",
"/settings/drivers",
"/settings/security",
"/settings/services",
"/settings/monitor",
"/settings/logs",
"/settings/files",
"/settings/terminal",
] {
let reply = client(&format!("GET {path} HTTP/1.1\r\nHost: x\r\n\r\n"));
assert!(reply.starts_with("HTTP/1.1 200 OK"), "{path}: {reply}");
}
}
#[test]
fn the_dashboard_api_serves_the_default_template() {
let reply = client("GET /api/dashboard?deck=bogus HTTP/1.1\r\nHost: x\r\n\r\n");
let body = reply.split("\r\n\r\n").nth(1).unwrap_or("");
let doc: Value = serde_json::from_str(body).unwrap_or_else(|_| json!({}));
assert_eq!(doc["version"], 1);
assert!(doc["blocks"]
.as_array()
.map(|b| !b.is_empty())
.unwrap_or(false));
}
#[test]
fn the_dashboard_api_rejects_a_bad_document() {
let body = "not json";
let reply = client(&format!(
"PUT /api/dashboard?deck=test HTTP/1.1\r\nHost: x\r\nContent-Length: {}\r\n\r\n{body}",
body.len()
));
assert!(reply.starts_with("HTTP/1.1 400"), "{reply}");
}
#[test]
fn the_terminal_is_forbidden_without_a_token() {
std::env::remove_var("ALKANE_UI_TOKEN");
let reply =
client("POST /api/terminal?cmd=id HTTP/1.1\r\nHost: x\r\nContent-Length: 0\r\n\r\n");
assert!(reply.starts_with("HTTP/1.1 403"), "{reply}");
}
#[test]
fn the_api_still_serves_hardware_and_summary() {
for path in ["/api/hardware", "/api/summary"] {
let reply = client(&format!("GET {path} HTTP/1.1\r\nHost: x\r\n\r\n"));
assert!(reply.starts_with("HTTP/1.1 200 OK"), "{path}");
assert!(reply.contains("application/json"));
}
}
}
+441 -4
View File
@@ -1,13 +1,55 @@
use alkane_os::{power_decision, target_matrix};
use alkane_os::bm1362::{
bt8d_for_baud, chain_inactive, encode_job, encode_work as encode_bm1362_work, read_register,
read_register_all, set_chip_address, write_register, write_register_all, Job, S19J_PRO,
};
use alkane_os::bm1366::{decode_nonce_report, encode_work};
use alkane_os::bm13xx::{crc16, crc5};
use alkane_os::difficulty::PoolDifficulty;
use alkane_os::hal_wire::HalClient;
use alkane_os::miner::Bm1366Miner;
use alkane_os::pow::verify_sha256_report;
use alkane_os::pow::VersionMask;
use alkane_os::scrypt_pow::verify_scrypt_header;
use alkane_os::stratum_session::PoolSession;
use alkane_os::stratum_submit::{format_submission, Submission};
use alkane_os::stratum_v1::{
parse_boolean_response, parse_configure_result, parse_control_notification, parse_notify,
parse_subscription, Subscription,
};
use alkane_os::stratum_wire::{
authorize_request, configure_request, subscribe_request, StratumWire,
};
use alkane_os::stratum_work::Sha256Job;
use alkane_os::{power_decision, target_matrix, HardwareBackend};
use std::hint::black_box;
use std::time::Instant;
use std::io::{Read, Write};
use std::net::TcpListener;
use std::os::unix::net::UnixStream;
use std::thread;
use std::time::{Duration, Instant};
fn measure(name: &str, iterations: u64, mut f: impl FnMut()) {
fn sample(iterations: u64, f: &mut impl FnMut()) -> Duration {
let started = Instant::now();
for _ in 0..iterations {
f();
}
let ns = started.elapsed().as_nanos() as f64 / iterations as f64;
started.elapsed()
}
fn measure(name: &str, minimum_iterations: u64, mut f: impl FnMut()) {
for _ in 0..minimum_iterations.min(1000) {
f();
}
let mut iterations = minimum_iterations.max(1);
while sample(iterations, &mut f) < Duration::from_millis(20) && iterations < 100_000_000 {
iterations = (iterations * 2).min(100_000_000);
}
let mut measurements = [0_f64; 7];
for value in &mut measurements {
*value = sample(iterations, &mut f).as_nanos() as f64 / iterations as f64;
}
measurements.sort_by(f64::total_cmp);
let ns = measurements[measurements.len() / 2];
println!("BENCH {name} {ns:.3} ns/op");
}
@@ -30,3 +72,398 @@ fn bench_power_policy() {
black_box(power_decision(black_box(Some(64_000)), 80_000));
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_bm13xx_crc5() {
let command = [0x53, 0x05, 0, 0];
measure("bm13xx_crc5", 100_000, || {
black_box(crc5(black_box(&command)));
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_bm13xx_crc16() {
let job = [0x21_u8; 84];
measure("bm13xx_crc16", 20_000, || {
black_box(crc16(black_box(&job)));
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_share_verification() {
let header = [0_u8; 80];
let target = [0xff_u8; 32];
measure("share_verification", 20_000, || {
black_box(verify_sha256_report(
black_box(&header),
black_box(0xEDAD_FF38),
black_box(0x04B3),
black_box(&target),
));
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_scrypt_share_verification() {
let header = [0_u8; 80];
let target = [0xff_u8; 32];
measure("scrypt_share_verification", 4, || {
black_box(verify_scrypt_header(black_box(&header), black_box(&target)));
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_bm1366_work_encoding() {
let header = [0_u8; 80];
measure("bm1366_work_encoding", 20_000, || {
black_box(encode_work(black_box(&header), black_box(0x18)));
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_bm1362_commands() {
measure("bm1362_commands", 20_000, || {
black_box(chain_inactive());
black_box(set_chip_address(black_box(8)));
black_box(read_register(black_box(0x40), 0x1c));
black_box(read_register_all(0));
black_box(write_register(black_box(0x40), 0x18, 0x7a31));
black_box(write_register_all(0x80, 0));
black_box(bt8d_for_baud(black_box(115_200)));
black_box(S19J_PRO.chip_addresses().last());
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_bm1362_job_encoding() {
let job = Job {
work_id: 8,
num_midstates: 1,
start_nonce: 0,
nbits: 0x1a1f_2c34,
ntime: 0x5e9b_3cd4,
merkle_root: [0xa5; 32],
previous_hash: [0x5a; 32],
version: 0x2000_0000,
};
measure("bm1362_job_encoding", 20_000, || {
black_box(encode_job(black_box(&job)));
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_bm1362_work_encoding() {
let header = [0_u8; 80];
measure("bm1362_work_encoding", 20_000, || {
black_box(encode_bm1362_work(black_box(&header), black_box(8)));
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_bm1366_report_decode() {
let report = [
0xaa, 0x55, 0x38, 0xff, 0xad, 0xed, 0, 0x18, 0x04, 0xb3, 0x94,
];
measure("bm1366_report_decode", 100_000, || {
let _ = black_box(decode_nonce_report(black_box(&report)));
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_header() {
let job = Sha256Job {
prevhash_stratum: [0; 32],
coinb1: vec![0; 48],
coinb2: vec![0; 64],
merkle_branches: vec![[0; 32]; 4],
version: 0x2000_0000,
nbits: 0x1d00_ffff,
ntime: 0x6655_4433,
extranonce1: vec![0; 4],
extranonce2_size: 8,
};
measure("stratum_header", 5_000, || {
black_box(
job.nonce_zero_header(black_box(&[0; 8]), job.ntime)
.unwrap(),
);
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_submission() {
let share = Submission {
request_id: 1,
worker: "miner.worker",
job_id: "job-123",
extranonce2: &[0; 8],
ntime: 0x680f_6a2e,
nonce: 0xedad_ff38,
base_version: 0x2000_0000,
rolled_version: 0x2096_6000,
version_mask: Some(VersionMask::new(0x1fff_e000).unwrap()),
};
measure("stratum_submission", 20_000, || {
black_box(format_submission(black_box(&share)).unwrap());
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_authorize_format() {
measure("stratum_authorize_format", 20_000, || {
black_box(authorize_request(black_box(3), "miner.worker", "password").unwrap());
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_configure_format() {
measure("stratum_configure_format", 20_000, || {
black_box(configure_request(black_box(1)));
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_subscribe_format() {
measure("stratum_subscribe_format", 20_000, || {
black_box(subscribe_request(black_box(2), "alkane-os/0.1").unwrap());
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_subscription_parse() {
let line = br#"{"id":1,"result":[[["mining.notify","session"]],"01020304",4],"error":null}"#;
measure("stratum_subscription_parse", 20_000, || {
black_box(parse_subscription(black_box(line), black_box(1)).unwrap());
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_accept_parse() {
let line = br#"{"id":5,"result":true,"error":null}"#;
measure("stratum_accept_parse", 20_000, || {
black_box(parse_boolean_response(black_box(line), black_box(5)).unwrap());
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_notify_parse() {
let line = serde_json::json!({
"id": null,
"method": "mining.notify",
"params": [
"job-1",
"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
"616263", "78797a", [], "20000000", "1d00ffff", "66554433", true
]
})
.to_string();
let subscription = Subscription {
extranonce1: vec![1, 2, 3, 4],
extranonce2_size: 4,
};
measure("stratum_notify_parse", 20_000, || {
black_box(parse_notify(black_box(line.as_bytes()), &subscription).unwrap());
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_control_parse() {
let line = br#"{"id":null,"method":"mining.set_difficulty","params":[2048.5]}"#;
measure("stratum_control_parse", 20_000, || {
black_box(parse_control_notification(black_box(line), false, false).unwrap());
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_configure_parse() {
let line = br#"{"id":1,"result":{"version-rolling":true,"version-rolling.mask":"1fffe000","subscribe-extranonce":true},"error":null}"#;
measure("stratum_configure_parse", 20_000, || {
black_box(parse_configure_result(black_box(line), 1).unwrap());
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_difficulty_target() {
let number = serde_json::from_str("2048.5").unwrap();
let difficulty = PoolDifficulty::from_json_number(&number).unwrap();
measure("difficulty_target", 20_000, || {
black_box(black_box(difficulty).target_le());
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_job_issue() {
let line = serde_json::json!({
"id": null,
"method": "mining.notify",
"params": [
"job-1", "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
"616263", "78797a", [], "20000000", "1d00ffff", "66554433", true
]
})
.to_string();
let mut session = PoolSession::new(
Subscription {
extranonce1: vec![1, 2, 3, 4],
extranonce2_size: 4,
},
None,
false,
)
.unwrap();
session
.control(br#"{"id":null,"method":"mining.set_difficulty","params":[1]}"#)
.unwrap();
measure("stratum_job_issue", 5_000, || {
session.after_hardware_reset();
black_box(session.issue_notify(black_box(line.as_bytes())).unwrap());
});
}
struct BenchBackend {
report: Option<[u8; 11]>,
}
impl HardwareBackend for BenchBackend {
type Error = ();
fn send_frame(&mut self, _chain: u8, frame: &[u8]) -> Result<(), Self::Error> {
black_box(frame);
Ok(())
}
fn receive_frame(&mut self, _chain: u8, frame: &mut [u8]) -> Result<usize, Self::Error> {
if let Some(report) = self.report {
frame[..report.len()].copy_from_slice(&report);
Ok(report.len())
} else {
Ok(0)
}
}
fn set_chain_reset(&mut self, _chain: u8, _asserted: bool) -> Result<(), Self::Error> {
Ok(())
}
fn set_fan_target(&mut self, _fan: u8, _percent: u8) -> Result<(), Self::Error> {
Ok(())
}
fn read_temperature_mc(&mut self, _sensor: u8) -> Result<i32, Self::Error> {
Ok(50_000)
}
fn set_psu_enabled(&mut self, _enabled: bool) -> Result<(), Self::Error> {
Ok(())
}
}
#[test]
#[ignore = "microbenchmark"]
fn bench_bm1366_session_cycle() {
let header = [0_u8; 80];
let target = [0xff_u8; 32];
measure("bm1366_session_cycle", 20_000, || {
let mut backend = BenchBackend { report: None };
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
miner
.submit(black_box(header), black_box(target), 0x18)
.unwrap();
black_box(miner.poll().unwrap());
miner.stop().unwrap();
});
}
#[test]
#[ignore = "microbenchmark"]
fn bench_bm1366_captured_report_poll() {
let header = [
0x00, 0x00, 0x00, 0x20, 0xfc, 0x3a, 0xb8, 0xd4, 0x30, 0x21, 0xf4, 0x5e, 0xb6, 0x62, 0x38,
0x9d, 0x0f, 0x79, 0x1f, 0x65, 0x7d, 0xbf, 0x75, 0xa5, 0xcb, 0x93, 0x67, 0x0b, 0x57, 0xb6,
0xc2, 0x25, 0x03, 0xb4, 0x21, 0x3a, 0x43, 0xae, 0x10, 0x52, 0xeb, 0xd4, 0x44, 0x43, 0x06,
0x8f, 0xe1, 0x78, 0xe2, 0xc6, 0x1c, 0xa4, 0x99, 0x48, 0x46, 0xfd, 0x13, 0x3a, 0xdd, 0xb0,
0x4a, 0xab, 0x2b, 0x38, 0x2c, 0x5b, 0x4c, 0x74, 0xc1, 0x01, 0x2e, 0x6a, 0x8f, 0x06, 0x02,
0x17, 0x00, 0x00, 0x00, 0x00,
];
let report = [
0xaa, 0x55, 0x38, 0xff, 0xad, 0xed, 0, 0x18, 0x04, 0xb3, 0x94,
];
let mut target = [0_u8; 32];
target[26..28].fill(0xff);
let mut backend = BenchBackend {
report: Some(report),
};
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
miner.submit(header, target, 0x18).unwrap();
measure("bm1366_captured_report_poll", 20_000, || {
let share = miner.poll().unwrap().unwrap();
assert_eq!(black_box(share).nonce, 0xedad_ff38);
});
miner.stop().unwrap();
}
#[test]
#[ignore = "microbenchmark"]
fn bench_hal_socket_exchange() {
let (client, mut server) = UnixStream::pair().unwrap();
let worker = thread::spawn(move || {
let mut header = [0_u8; 16];
let mut payload = [0_u8; 2];
while server.read_exact(&mut header).is_ok() {
assert_eq!(&header[..6], b"ALKH\x01\x04");
assert_eq!(u32::from_le_bytes(header[12..16].try_into().unwrap()), 2);
server.read_exact(&mut payload).unwrap();
assert_eq!(payload, [0, 80]);
header[6..8].copy_from_slice(&1_u16.to_le_bytes());
header[12..16].copy_from_slice(&1_u32.to_le_bytes());
server.write_all(&header).unwrap();
server.write_all(&[0]).unwrap();
}
});
let mut backend = HalClient::from_stream(client).unwrap();
measure("hal_socket_exchange", 100, || {
backend.set_fan_target(black_box(0), black_box(80)).unwrap();
});
drop(backend);
worker.join().unwrap();
}
#[test]
#[ignore = "microbenchmark"]
fn bench_stratum_socket_round_trip() {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let worker = thread::spawn(move || {
let (mut server, _) = listener.accept().unwrap();
let mut request = [0_u8; 3];
while server.read_exact(&mut request).is_ok() {
assert_eq!(&request, b"{}\n");
server.write_all(b"{}\n").unwrap();
}
});
let mut wire = StratumWire::connect(address, Duration::from_secs(2)).unwrap();
measure("stratum_socket_round_trip", 100, || {
wire.send_line(black_box(b"{}\n")).unwrap();
black_box(wire.read_line().unwrap());
});
drop(wire);
worker.join().unwrap();
}
+73
View File
@@ -0,0 +1,73 @@
// SPDX-License-Identifier: MIT
use alkane_os::difficulty::{DifficultyError, PoolDifficulty};
fn target(decimal: &str) -> String {
let number = serde_json::from_str(decimal).unwrap();
PoolDifficulty::from_json_number(&number)
.unwrap()
.target_le()
.iter()
.rev()
.map(|byte| format!("{byte:02x}"))
.collect()
}
#[test]
fn exact_share_targets_match_integer_reference() {
for (difficulty, expected) in [
(
"1",
"00000000ffff0000000000000000000000000000000000000000000000000000",
),
(
"2",
"000000007fff8000000000000000000000000000000000000000000000000000",
),
(
"0.5",
"00000001fffe0000000000000000000000000000000000000000000000000000",
),
(
"1.25",
"00000000cccc0000000000000000000000000000000000000000000000000000",
),
(
"2048.5",
"00000000001ffde021fde021fde021fde021fde021fde021fde021fde021fde0",
),
(
"0.000001",
"000f4230bdc00000000000000000000000000000000000000000000000000000",
),
(
"1000000000000000000",
"000000000000000000000012724b5f7471d95d3bbefee5e602a7b17261180d8e",
),
] {
assert_eq!(target(difficulty), expected, "difficulty {difficulty}");
}
assert_eq!(target("1.2e3"), target("1200"));
assert_eq!(target("1e-19"), "ff".repeat(32));
}
#[test]
fn invalid_or_unrepresentable_difficulty_is_rejected() {
let zero = serde_json::from_str("0").unwrap();
assert_eq!(
PoolDifficulty::from_json_number(&zero),
Err(DifficultyError::Invalid)
);
let negative = serde_json::from_str("-1").unwrap();
assert_eq!(
PoolDifficulty::from_json_number(&negative),
Err(DifficultyError::OutOfRange)
);
for value in ["1e20", "1e-20", "1.00000000000000000001"] {
let number = serde_json::from_str(value).unwrap();
assert_eq!(
PoolDifficulty::from_json_number(&number),
Err(DifficultyError::OutOfRange),
"difficulty {value}"
);
}
}
+214
View File
@@ -0,0 +1,214 @@
// SPDX-License-Identifier: MIT
use alkane_os::hal_wire::{HalClient, HalError};
use alkane_os::HardwareBackend;
use std::io::{Read, Write};
use std::os::unix::net::{UnixListener, UnixStream};
use std::thread;
use std::time::{Duration, Instant};
fn reply(socket: &mut UnixStream, request: &[u8; 16], body: &[u8]) {
let mut header = *request;
header[6..8].copy_from_slice(&1_u16.to_le_bytes());
header[12..16].copy_from_slice(&(body.len() as u32).to_le_bytes());
socket.write_all(&header).unwrap();
socket.write_all(body).unwrap();
}
#[test]
fn sdk_backend_round_trip_and_safety_limits() {
let (client, mut server) = UnixStream::pair().unwrap();
let worker = thread::spawn(move || {
let expected = [
(1, vec![2, 3, 0, 0x55, 0xaa, 0x21], vec![0]),
(2, vec![2, 8, 0], vec![0, 3, 0, 0xaa, 0x55, 0x01]),
(3, vec![2, 1], vec![0]),
(4, vec![0, 90], vec![0]),
(
5,
vec![1],
[vec![0], 72_500_i32.to_le_bytes().to_vec()].concat(),
),
(6, vec![1], vec![0]),
];
for (index, (opcode, request_body, response_body)) in expected.iter().enumerate() {
let mut header = [0_u8; 16];
server.read_exact(&mut header).unwrap();
assert_eq!(&header[..4], b"ALKH");
assert_eq!(header[4], 1);
assert_eq!(header[5], *opcode);
assert_eq!(
u32::from_le_bytes(header[8..12].try_into().unwrap()),
index as u32 + 1
);
let length = u32::from_le_bytes(header[12..16].try_into().unwrap()) as usize;
let mut body = vec![0_u8; length];
server.read_exact(&mut body).unwrap();
assert_eq!(&body, request_body);
reply(&mut server, &header, response_body);
}
});
let mut backend = HalClient::from_stream(client).unwrap();
backend.send_frame(2, &[0x55, 0xaa, 0x21]).unwrap();
let mut buffer = [0_u8; 8];
assert_eq!(backend.receive_frame(2, &mut buffer).unwrap(), 3);
assert_eq!(&buffer[..3], &[0xaa, 0x55, 0x01]);
backend.set_chain_reset(2, true).unwrap();
backend.set_fan_target(0, 90).unwrap();
assert_eq!(backend.read_temperature_mc(1).unwrap(), 72_500);
backend.set_psu_enabled(true).unwrap();
assert!(matches!(
backend.set_fan_target(0, 101),
Err(HalError::InvalidFanPercent)
));
assert!(matches!(
backend.send_frame(0, &[0_u8; 4094]),
Err(HalError::FrameTooLong)
));
worker.join().unwrap();
}
#[test]
fn rejects_wrong_response_sequence() {
let (client, mut server) = UnixStream::pair().unwrap();
let worker = thread::spawn(move || {
let mut header = [0_u8; 16];
server.read_exact(&mut header).unwrap();
let mut body = [0_u8; 1];
server.read_exact(&mut body).unwrap();
header[8..12].copy_from_slice(&2_u32.to_le_bytes());
header[6..8].copy_from_slice(&1_u16.to_le_bytes());
header[12..16].copy_from_slice(&1_u32.to_le_bytes());
server.write_all(&header).unwrap();
let mut one = [0_u8; 1];
assert_eq!(server.read(&mut one).unwrap(), 0);
});
let mut backend = HalClient::from_stream(client).unwrap();
assert!(matches!(
backend.set_psu_enabled(true),
Err(HalError::Protocol("response sequence mismatch"))
));
assert!(matches!(
backend.set_psu_enabled(true),
Err(HalError::Protocol("connection is unusable"))
));
worker.join().unwrap();
}
#[test]
fn failed_power_off_ends_backend_power_lease() {
let (client, mut server) = UnixStream::pair().unwrap();
let worker = thread::spawn(move || {
let mut header = [0_u8; 16];
server.read_exact(&mut header).unwrap();
let mut body = [0_u8; 1];
server.read_exact(&mut body).unwrap();
assert_eq!(header[5], 6);
assert_eq!(body, [0]);
reply(&mut server, &header, &[3]);
assert_eq!(server.read(&mut body).unwrap(), 0);
});
let mut backend = HalClient::from_stream(client).unwrap();
assert!(matches!(
backend.set_psu_enabled(false),
Err(HalError::Device(3))
));
worker.join().unwrap();
}
#[test]
fn malformed_temperature_response_disconnects_power_lease() {
let (client, mut server) = UnixStream::pair().unwrap();
let worker = thread::spawn(move || {
let mut header = [0_u8; 16];
server.read_exact(&mut header).unwrap();
let mut request = [0_u8; 1];
server.read_exact(&mut request).unwrap();
assert_eq!(header[5], 5);
reply(&mut server, &header, &[0, 1]);
assert_eq!(server.read(&mut request).unwrap(), 0);
});
let mut backend = HalClient::from_stream(client).unwrap();
assert!(matches!(
backend.read_temperature_mc(1),
Err(HalError::Protocol("invalid temperature response"))
));
worker.join().unwrap();
}
#[test]
fn rejects_malformed_error_response_and_poisoned_connection() {
for body in [&[4_u8][..], &[3_u8, 99][..]] {
let (client, mut server) = UnixStream::pair().unwrap();
let response = body.to_vec();
let worker = thread::spawn(move || {
let mut header = [0_u8; 16];
server.read_exact(&mut header).unwrap();
let mut request = [0_u8; 1];
server.read_exact(&mut request).unwrap();
reply(&mut server, &header, &response);
});
let mut backend = HalClient::from_stream(client).unwrap();
assert!(matches!(
backend.set_psu_enabled(true),
Err(HalError::Protocol("invalid error response"))
));
assert!(matches!(
backend.set_psu_enabled(true),
Err(HalError::Protocol("connection is unusable"))
));
worker.join().unwrap();
}
}
#[test]
fn slow_partial_response_hits_absolute_exchange_deadline() {
let (client, mut server) = UnixStream::pair().unwrap();
let worker = thread::spawn(move || {
let mut header = [0_u8; 16];
server.read_exact(&mut header).unwrap();
let mut request = [0_u8; 1];
server.read_exact(&mut request).unwrap();
header[6..8].copy_from_slice(&1_u16.to_le_bytes());
header[12..16].copy_from_slice(&1_u32.to_le_bytes());
for byte in header.into_iter().chain([0]) {
if server.write_all(&[byte]).is_err() {
break;
}
thread::sleep(Duration::from_millis(250));
}
});
let mut backend = HalClient::from_stream(client).unwrap();
let start = Instant::now();
assert!(matches!(
backend.set_psu_enabled(true),
Err(HalError::Io(_))
));
assert!(start.elapsed() < Duration::from_secs(4));
drop(backend);
worker.join().unwrap();
}
#[test]
fn connects_to_a_local_backend_socket() {
let path = std::env::temp_dir().join(format!(
"alkane-hal-{}-{}.sock",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
));
let listener = UnixListener::bind(&path).unwrap();
let worker = thread::spawn(move || {
let (mut server, _) = listener.accept().unwrap();
let mut header = [0_u8; 16];
server.read_exact(&mut header).unwrap();
let mut request = [0_u8; 1];
server.read_exact(&mut request).unwrap();
reply(&mut server, &header, &[0]);
});
let mut backend = HalClient::connect(&path).unwrap();
backend.set_psu_enabled(true).unwrap();
worker.join().unwrap();
std::fs::remove_file(path).unwrap();
}
+360
View File
@@ -0,0 +1,360 @@
// SPDX-License-Identifier: MIT
use alkane_os::bm1366::REPORT_BYTES;
use alkane_os::miner::{Bm1366Miner, ChipModel, MinerError};
use alkane_os::HardwareBackend;
const HEADER: [u8; 80] = [
0x00, 0x00, 0x00, 0x20, 0xfc, 0x3a, 0xb8, 0xd4, 0x30, 0x21, 0xf4, 0x5e, 0xb6, 0x62, 0x38, 0x9d,
0x0f, 0x79, 0x1f, 0x65, 0x7d, 0xbf, 0x75, 0xa5, 0xcb, 0x93, 0x67, 0x0b, 0x57, 0xb6, 0xc2, 0x25,
0x03, 0xb4, 0x21, 0x3a, 0x43, 0xae, 0x10, 0x52, 0xeb, 0xd4, 0x44, 0x43, 0x06, 0x8f, 0xe1, 0x78,
0xe2, 0xc6, 0x1c, 0xa4, 0x99, 0x48, 0x46, 0xfd, 0x13, 0x3a, 0xdd, 0xb0, 0x4a, 0xab, 0x2b, 0x38,
0x2c, 0x5b, 0x4c, 0x74, 0xc1, 0x01, 0x2e, 0x6a, 0x8f, 0x06, 0x02, 0x17, 0x00, 0x00, 0x00, 0x00,
];
const REPORT: [u8; REPORT_BYTES] = [
0xaa, 0x55, 0x38, 0xff, 0xad, 0xed, 0, 0x18, 0x04, 0xb3, 0x94,
];
fn diff_one() -> [u8; 32] {
let mut target = [0_u8; 32];
target[26..28].fill(0xff);
target
}
#[derive(Default)]
struct FakeBackend {
events: Vec<&'static str>,
temperatures: Vec<i32>,
powered: bool,
fail_off_call: usize,
off_calls: usize,
fail_reset_call: usize,
reset_calls: usize,
report: Option<[u8; REPORT_BYTES]>,
additional_reports: Vec<[u8; REPORT_BYTES]>,
sent: Vec<u8>,
}
impl HardwareBackend for FakeBackend {
type Error = &'static str;
fn send_frame(&mut self, _chain: u8, frame: &[u8]) -> Result<(), Self::Error> {
assert!(self.powered);
self.events.push("send");
self.sent = frame.to_vec();
Ok(())
}
fn receive_frame(&mut self, _chain: u8, frame: &mut [u8]) -> Result<usize, Self::Error> {
self.events.push("receive");
if let Some(report) = self.report.take().or_else(|| self.additional_reports.pop()) {
frame[..REPORT_BYTES].copy_from_slice(&report);
Ok(REPORT_BYTES)
} else {
Ok(0)
}
}
fn set_chain_reset(&mut self, _chain: u8, asserted: bool) -> Result<(), Self::Error> {
assert!(self.powered);
self.reset_calls += 1;
if self.reset_calls == self.fail_reset_call {
return Err("reset failed");
}
self.events
.push(if asserted { "reset-on" } else { "reset-off" });
Ok(())
}
fn set_fan_target(&mut self, _fan: u8, percent: u8) -> Result<(), Self::Error> {
assert!(percent > 0);
self.events.push("fan");
Ok(())
}
fn read_temperature_mc(&mut self, _sensor: u8) -> Result<i32, Self::Error> {
self.events.push("temperature");
if self.temperatures.is_empty() {
return Err("sensor unavailable");
}
Ok(self.temperatures.remove(0))
}
fn set_psu_enabled(&mut self, enabled: bool) -> Result<(), Self::Error> {
self.events.push(if enabled { "psu-on" } else { "psu-off" });
if !enabled {
self.off_calls += 1;
if self.off_calls == self.fail_off_call {
return Err("power-off did not complete");
}
}
self.powered = enabled;
Ok(())
}
}
#[test]
fn captured_nonce_passes_a_started_miner() {
let mut backend = FakeBackend {
temperatures: vec![50_000, 50_000, 50_000],
report: Some(REPORT),
..Default::default()
};
{
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
miner.submit(HEADER, diff_one(), 0x18).unwrap();
let share = miner.poll().unwrap().unwrap();
assert_eq!(share.nonce, 0xedad_ff38);
assert_eq!(share.work_id, 0x18);
assert_eq!(share.rolled_version, 0x2096_6000);
miner.stop().unwrap();
}
assert!(!backend.powered);
assert_eq!(&backend.sent[..5], &[0x55, 0xaa, 0x21, 0x54, 0x18]);
assert_eq!(
&backend.events[..6],
&[
"psu-off",
"temperature",
"fan",
"psu-on",
"reset-on",
"reset-off"
]
);
}
#[test]
fn real_bm1362_capture_uses_its_job_format_and_shared_report() {
// SDK capture bm1362-real-nonces.txt: one real-silicon pool-accepted share.
// This checks host framing and proof only; board initialization is separate.
let header_hex = concat!(
"00000020fc3ab8d43021f45eb662389d0f791f657dbf75a5cb93670b57b6c22503b4213a",
"0503969b7384e1215aace8cfc65dae22d8493ad48fec0b7ac3b0ad7b4e7fb0c5",
"c0012e6a8f06021700000000"
);
let mut header = [0_u8; 80];
for (byte, pair) in header.iter_mut().zip(header_hex.as_bytes().chunks_exact(2)) {
*byte = u8::from_str_radix(std::str::from_utf8(pair).unwrap(), 16).unwrap();
}
let report = [
0xaa, 0x55, 0x33, 0x25, 0x0b, 0x63, 0x00, 0x18, 0x67, 0x6b, 0x95,
];
let mut backend = FakeBackend {
temperatures: vec![50_000; 3],
report: Some(report),
..Default::default()
};
{
let mut miner =
Bm1366Miner::new_for_chip(&mut backend, ChipModel::Bm1362, 0, 0, 0, 100, 80_000)
.unwrap();
miner.start().unwrap();
miner.submit(header, diff_one(), 0x18).unwrap();
let share = miner.poll().unwrap().unwrap();
assert_eq!(share.nonce, 0x630b_2533);
assert_eq!(share.work_id, 0x18);
assert_eq!(share.rolled_version, 0x2ced_6000);
miner.stop().unwrap();
}
assert!(!backend.powered);
assert_eq!(&backend.sent[..6], &[0x55, 0xaa, 0x21, 0x56, 0x18, 1]);
assert_eq!(&backend.sent[10..14], &header[72..76]);
}
#[test]
fn hot_or_missing_sensor_stops_power() {
let mut hot = FakeBackend {
temperatures: vec![80_000],
..Default::default()
};
let mut miner = Bm1366Miner::new(&mut hot, 0, 0, 0, 100, 80_000).unwrap();
assert_eq!(miner.start(), Err(MinerError::UnsafeTemperature(80_000)));
drop(miner);
assert!(!hot.powered);
assert!(!hot.events.contains(&"psu-on"));
let mut missing = FakeBackend::default();
let mut miner = Bm1366Miner::new(&mut missing, 0, 0, 0, 100, 80_000).unwrap();
assert_eq!(
miner.start(),
Err(MinerError::Backend("sensor unavailable"))
);
drop(miner);
assert!(!missing.powered);
}
#[test]
fn temperature_rise_stops_power_and_stale_reports_preserve_mining() {
let mut backend = FakeBackend {
temperatures: vec![50_000, 50_000, 90_000],
report: Some(REPORT),
..Default::default()
};
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
miner.submit(HEADER, diff_one(), 0x18).unwrap();
assert_eq!(miner.poll(), Err(MinerError::UnsafeTemperature(90_000)));
assert_eq!(miner.poll(), Err(MinerError::NotRunning));
drop(miner);
assert!(!backend.powered);
let mut backend = FakeBackend {
temperatures: vec![50_000; 5],
report: Some(REPORT),
..Default::default()
};
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
miner.submit(HEADER, diff_one(), 0x20).unwrap();
assert_eq!(miner.poll(), Err(MinerError::StaleReport));
miner.submit(HEADER, diff_one(), 0x18).unwrap();
assert_eq!(miner.poll(), Ok(None));
drop(miner);
assert!(!backend.powered);
}
#[test]
fn earlier_in_flight_job_is_checked_against_its_own_target() {
let mut backend = FakeBackend {
temperatures: vec![50_000; 5],
report: Some(REPORT),
additional_reports: vec![REPORT],
..Default::default()
};
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
miner.submit(HEADER, diff_one(), 0x18).unwrap();
miner.submit(HEADER, [0; 32], 0x20).unwrap();
assert_eq!(miner.poll().unwrap().unwrap().work_id, 0x18);
miner.clear_work();
assert_eq!(miner.poll(), Err(MinerError::StaleReport));
drop(miner);
assert!(!backend.powered);
}
#[test]
fn below_target_is_rejected_without_misreporting_a_share() {
let mut backend = FakeBackend {
temperatures: vec![50_000, 50_000, 50_000],
report: Some(REPORT),
..Default::default()
};
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
miner.submit(HEADER, [0; 32], 0x18).unwrap();
assert_eq!(miner.poll(), Err(MinerError::BelowTarget));
drop(miner);
assert!(!backend.powered);
}
#[test]
fn failed_power_off_is_retried_on_drop() {
let mut backend = FakeBackend {
temperatures: vec![50_000],
fail_off_call: 2,
..Default::default()
};
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
assert_eq!(miner.stop(), Err("power-off did not complete"));
drop(miner);
assert_eq!(backend.off_calls, 3);
assert!(!backend.powered);
}
#[test]
fn failed_chain_flush_powers_off_before_work_id_reuse() {
let mut backend = FakeBackend {
temperatures: vec![50_000, 50_000],
fail_reset_call: 3,
..Default::default()
};
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
assert_eq!(
miner.reset_chain(),
Err(MinerError::Backend("reset failed"))
);
assert_eq!(
miner.submit(HEADER, diff_one(), 0),
Err(MinerError::NotRunning)
);
drop(miner);
assert!(!backend.powered);
}
#[test]
fn work_id_stays_reserved_until_confirmed_chain_reset() {
let mut backend = FakeBackend {
temperatures: vec![50_000; 6],
..Default::default()
};
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
miner.submit(HEADER, diff_one(), 0x18).unwrap();
assert_eq!(
miner.submit(HEADER, diff_one(), 0x18),
Err(MinerError::WorkIdInUse(0x18))
);
miner.clear_work();
assert_eq!(
miner.submit(HEADER, diff_one(), 0x18),
Err(MinerError::WorkIdInUse(0x18))
);
miner.reset_chain().unwrap();
miner.submit(HEADER, diff_one(), 0x18).unwrap();
miner.stop().unwrap();
drop(miner);
assert_eq!(
backend
.events
.iter()
.filter(|event| **event == "send")
.count(),
2
);
assert!(!backend.powered);
}
#[test]
fn duplicate_work_request_still_checks_temperature() {
let mut backend = FakeBackend {
temperatures: vec![50_000, 50_000, 90_000],
..Default::default()
};
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
miner.submit(HEADER, diff_one(), 0x18).unwrap();
assert_eq!(
miner.submit(HEADER, diff_one(), 0x18),
Err(MinerError::UnsafeTemperature(90_000))
);
drop(miner);
assert!(!backend.powered);
}
#[test]
fn unconfirmed_power_off_blocks_mining_until_shutdown_retries() {
let mut backend = FakeBackend {
temperatures: vec![50_000],
fail_off_call: 2,
..Default::default()
};
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
assert_eq!(miner.stop(), Err("power-off did not complete"));
assert_eq!(
miner.submit(HEADER, diff_one(), 0),
Err(MinerError::Faulted)
);
assert_eq!(miner.poll(), Err(MinerError::Faulted));
assert_eq!(miner.reset_chain(), Err(MinerError::Faulted));
miner.stop().unwrap();
assert_eq!(
miner.submit(HEADER, diff_one(), 0),
Err(MinerError::NotRunning)
);
drop(miner);
assert!(!backend.powered);
}
+260
View File
@@ -0,0 +1,260 @@
// SPDX-License-Identifier: MIT
use alkane_os::miner::{Bm1366Miner, MinerError, ValidShare};
use alkane_os::pow::VersionMask;
use alkane_os::stratum_session::{DispatchError, PoolSession, SessionError};
use alkane_os::stratum_v1::Subscription;
use alkane_os::HardwareBackend;
fn session() -> PoolSession {
PoolSession::new(
Subscription {
extranonce1: vec![1, 2, 3, 4],
extranonce2_size: 4,
},
Some(VersionMask::new(0x1fff_e000).unwrap()),
true,
)
.unwrap()
}
fn notify(id: &str, clean: bool) -> String {
serde_json::json!({
"id": null,
"method": "mining.notify",
"params": [
id,
"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
"616263", "78797a", [], "20000000", "1d00ffff", "66554433", clean
]
})
.to_string()
}
#[test]
fn difficulty_changes_on_next_job_and_old_work_keeps_its_target() {
let mut pool = session();
assert_eq!(
pool.issue_notify(notify("early", true).as_bytes()).err(),
Some(SessionError::MissingDifficulty)
);
pool.control(br#"{"id":null,"method":"mining.set_difficulty","params":[1]}"#)
.unwrap();
let first = pool.issue_notify(notify("first", true).as_bytes()).unwrap();
assert!(first.clean_jobs);
assert_eq!(first.work_id, 0);
assert_eq!(&first.target_le[26..28], &[0xff, 0xff]);
pool.control(br#"{"id":null,"method":"mining.set_difficulty","params":[2]}"#)
.unwrap();
let second = pool
.issue_notify(notify("second", false).as_bytes())
.unwrap();
assert!(!second.clean_jobs);
assert_eq!(second.work_id, 8);
assert_eq!(&second.target_le[26..28], &[0xff, 0x7f]);
assert_ne!(first.header, second.header);
assert_eq!(
pool.control(br#"{"id":null,"method":"mining.set_version_mask","params":["00006000"]}"#),
Ok(true)
);
assert_eq!(
pool.submission(
ValidShare {
nonce: 0xedad_ff38,
work_id: first.work_id,
rolled_version: 0x2000_0000,
hash_le: [0; 32],
},
"worker",
10,
),
Err(SessionError::StaleShare)
);
assert_eq!(
pool.control(br#"{"id":null,"method":"mining.set_version_mask","params":["00006000"]}"#),
Ok(false)
);
let clean = pool.issue_notify(notify("third", true).as_bytes()).unwrap();
assert!(clean.clean_jobs);
assert_eq!(clean.work_id, 16);
let old = ValidShare {
nonce: 0xedad_ff38,
work_id: first.work_id,
rolled_version: 0x2000_0000,
hash_le: [0; 32],
};
assert_eq!(
pool.submission(old, "worker", 10),
Err(SessionError::StaleShare)
);
}
#[test]
fn extranonce_change_invalidates_jobs_without_reusing_asic_ids() {
let mut pool = session();
pool.control(br#"{"id":null,"method":"mining.set_difficulty","params":[1]}"#)
.unwrap();
let old = pool.issue_notify(notify("old", true).as_bytes()).unwrap();
assert!(pool
.control(br#"{"id":null,"method":"mining.set_extranonce","params":["aabbccdd",4]}"#)
.unwrap());
let new = pool.issue_notify(notify("new", false).as_bytes()).unwrap();
assert_eq!(new.work_id, 8);
assert_ne!(old.header, new.header);
for index in 2..32 {
let work = pool.issue_notify(notify("more", false).as_bytes()).unwrap();
assert_eq!(work.work_id, (index as u8) << 3);
}
assert_eq!(
pool.issue_notify(notify("exhausted", false).as_bytes())
.err(),
Some(SessionError::WorkIdsExhausted)
);
pool.after_hardware_reset();
assert_eq!(
pool.issue_notify(notify("after-reset", false).as_bytes())
.unwrap()
.work_id,
0
);
}
#[test]
fn zero_length_extranonce_requires_distinct_header_until_hardware_reset() {
let mut pool = PoolSession::new(
Subscription {
extranonce1: vec![1],
extranonce2_size: 0,
},
None,
false,
)
.unwrap();
pool.control(br#"{"id":null,"method":"mining.set_difficulty","params":[1]}"#)
.unwrap();
pool.issue_notify(notify("one", true).as_bytes()).unwrap();
assert_eq!(
pool.issue_notify(notify("two", false).as_bytes()).err(),
Some(SessionError::ExtranonceExhausted)
);
let distinct = notify("two", true).replace("66554433", "66554434");
pool.issue_notify(distinct.as_bytes()).unwrap();
pool.after_hardware_reset();
pool.issue_notify(notify("three", true).as_bytes()).unwrap();
}
#[test]
fn one_byte_extranonce_restarts_only_for_a_distinct_header_template() {
let mut pool = PoolSession::new(
Subscription {
extranonce1: vec![1],
extranonce2_size: 1,
},
None,
false,
)
.unwrap();
pool.control(br#"{"id":null,"method":"mining.set_difficulty","params":[1]}"#)
.unwrap();
for index in 0..256 {
if index != 0 && index % 32 == 0 {
pool.after_hardware_reset();
}
pool.issue_notify(notify("same", false).as_bytes()).unwrap();
}
pool.after_hardware_reset();
assert_eq!(
pool.issue_notify(notify("same", false).as_bytes()).err(),
Some(SessionError::ExtranonceExhausted)
);
let distinct = notify("new", false).replace("66554433", "66554434");
pool.issue_notify(distinct.as_bytes()).unwrap();
pool.after_hardware_reset();
for index in 0..256_u32 {
if index != 0 && index % 32 == 0 {
pool.after_hardware_reset();
}
let ntime = format!("{index:08x}");
let next = notify("fresh", false).replace("66554433", &ntime);
pool.issue_notify(next.as_bytes()).unwrap();
}
}
struct FakeBackend {
powered: bool,
sent: usize,
report: Option<[u8; 11]>,
}
impl HardwareBackend for FakeBackend {
type Error = &'static str;
fn send_frame(&mut self, _chain: u8, frame: &[u8]) -> Result<(), Self::Error> {
assert!(self.powered);
assert_eq!(&frame[..4], &[0x55, 0xaa, 0x21, 0x54]);
self.sent += 1;
Ok(())
}
fn receive_frame(&mut self, _chain: u8, frame: &mut [u8]) -> Result<usize, Self::Error> {
match self.report.take() {
Some(report) => {
frame[..11].copy_from_slice(&report);
Ok(11)
}
None => Ok(0),
}
}
fn set_chain_reset(&mut self, _chain: u8, _asserted: bool) -> Result<(), Self::Error> {
Ok(())
}
fn set_fan_target(&mut self, _fan: u8, _percent: u8) -> Result<(), Self::Error> {
Ok(())
}
fn read_temperature_mc(&mut self, _sensor: u8) -> Result<i32, Self::Error> {
Ok(50_000)
}
fn set_psu_enabled(&mut self, enabled: bool) -> Result<(), Self::Error> {
self.powered = enabled;
Ok(())
}
}
#[test]
fn pool_job_dispatch_and_version_mask_invalidation_reach_the_miner() {
let mut backend = FakeBackend {
powered: false,
sent: 0,
report: Some([
0xaa, 0x55, 0x38, 0xff, 0xad, 0xed, 0, 0x18, 0x04, 0xb3, 0x94,
]),
};
{
let mut miner = Bm1366Miner::new(&mut backend, 0, 0, 0, 100, 80_000).unwrap();
miner.start().unwrap();
let mut pool = session();
pool.control_with_miner(
&mut miner,
br#"{"id":null,"method":"mining.set_difficulty","params":[1]}"#,
)
.unwrap();
for index in 0..4 {
let work = pool
.issue_to_miner(&mut miner, notify("job", index == 0).as_bytes())
.unwrap();
assert_eq!(work.work_id, (index as u8) << 3);
}
pool.control_with_miner(
&mut miner,
br#"{"id":null,"method":"mining.set_version_mask","params":["00006000"]}"#,
)
.unwrap();
assert_eq!(miner.poll(), Err(MinerError::StaleReport));
miner.stop().unwrap();
assert_eq!(
pool.issue_to_miner(&mut miner, notify("stopped", false).as_bytes())
.err(),
Some(DispatchError::Miner(MinerError::NotRunning))
);
}
assert!(!backend.powered);
assert_eq!(backend.sent, 4);
}
+67
View File
@@ -0,0 +1,67 @@
// SPDX-License-Identifier: MIT
use alkane_os::pow::VersionMask;
use alkane_os::stratum_submit::{format_submission, Submission, SubmitError};
fn share() -> Submission<'static> {
Submission {
request_id: 7,
worker: "miner.worker",
job_id: "pool-job",
extranonce2: &[0, 1, 0xfe, 0xff],
ntime: 0x680f6a2e,
nonce: 0xedadff38,
base_version: 0x20000000,
rolled_version: 0x20966000,
version_mask: Some(VersionMask::new(0x1fffe000).unwrap()),
}
}
#[test]
fn captured_bm1366_version_is_represented_under_negotiated_mask() {
assert_eq!(
format_submission(&share()).unwrap(),
"{\"id\":7,\"method\":\"mining.submit\",\"params\":[\"miner.worker\",\"pool-job\",\"0001feff\",\"680f6a2e\",\"edadff38\",\"00966000\"]}\n"
);
}
#[test]
fn unnegotiated_or_narrow_mask_rejects_rolled_share() {
let mut value = share();
value.version_mask = None;
assert_eq!(
format_submission(&value),
Err(SubmitError::UnrepresentableVersion)
);
value.version_mask = Some(VersionMask::new(0x0060_0000).unwrap());
assert_eq!(
format_submission(&value),
Err(SubmitError::UnrepresentableVersion)
);
value.rolled_version = value.base_version;
value.version_mask = None;
assert_eq!(
format_submission(&value).unwrap(),
"{\"id\":7,\"method\":\"mining.submit\",\"params\":[\"miner.worker\",\"pool-job\",\"0001feff\",\"680f6a2e\",\"edadff38\"]}\n"
);
}
#[test]
fn pool_fields_are_escaped_and_bounded() {
let mut value = share();
value.worker = "worker\"\\\n";
value.job_id = "job\t\u{0001}";
let wire = format_submission(&value).unwrap();
assert!(wire.contains("\"worker\\\"\\\\\\n\""));
assert!(wire.contains("\"job\\t\\u0001\""));
value.worker = "";
assert_eq!(format_submission(&value), Err(SubmitError::EmptyWorker));
value.worker = "worker";
value.job_id = "";
assert_eq!(format_submission(&value), Err(SubmitError::EmptyJobId));
value.job_id = "job";
value.extranonce2 = &[0; 33];
assert_eq!(
format_submission(&value),
Err(SubmitError::ExtranonceTooLong)
);
}
+208
View File
@@ -0,0 +1,208 @@
// SPDX-License-Identifier: MIT
use alkane_os::difficulty::PoolDifficulty;
use alkane_os::stratum_v1::{
parse_boolean_response, parse_configure_response, parse_configure_result,
parse_control_notification, parse_notify, parse_subscription, PoolMessageError,
PoolNotification, Subscription,
};
const SUBSCRIBE: &str =
r#"{"id":1,"result":[[["mining.notify","session"]],"01020304",4],"error":null}"#;
fn notify() -> String {
serde_json::json!({
"id": null,
"method": "mining.notify",
"params": [
"job-1",
"000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
"616263", "78797a",
["202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f"],
"20000000", "1d00ffff", "66554433", true
]
})
.to_string()
}
#[test]
fn subscribe_and_notify_construct_expected_asic_header() {
let subscription = parse_subscription(SUBSCRIBE.as_bytes(), 1).unwrap();
let line = notify();
let job = parse_notify(line.as_bytes(), &subscription).unwrap();
assert_eq!(job.id, "job-1");
assert!(job.clean_jobs);
let header = job
.work
.nonce_zero_header(&[5, 6, 7, 8], job.work.ntime)
.unwrap();
let hex: String = header.iter().map(|byte| format!("{byte:02x}")).collect();
assert_eq!(
hex,
concat!(
"0000002003020100070605040b0a09080f0e0d0c13121110171615141b1a19181f1e1d1c",
"9b9bc91f078af83ff63d00c6da09b5bc4dd26e2d8c0df8ab16b933a259a05881",
"33445566ffff001d00000000"
)
);
}
#[test]
fn malformed_pool_messages_fail_before_work_issuance() {
assert!(matches!(
parse_subscription(SUBSCRIBE.as_bytes(), 2),
Err(PoolMessageError::WrongMessage)
));
let subscription = parse_subscription(SUBSCRIBE.as_bytes(), 1).unwrap();
let malformed = notify().replace("66554433", "6655443g");
assert!(matches!(
parse_notify(malformed.as_bytes(), &subscription),
Err(PoolMessageError::InvalidHex)
));
let wrong_method = notify().replace("mining.notify", "mining.submit");
assert!(matches!(
parse_notify(wrong_method.as_bytes(), &subscription),
Err(PoolMessageError::WrongMessage)
));
let too_large = vec![b' '; 131_073];
assert!(matches!(
parse_notify(&too_large, &subscription),
Err(PoolMessageError::TooLarge)
));
let too_large_coinbase = notify().replace("616263", &"aa".repeat(65_537));
assert!(matches!(
parse_notify(too_large_coinbase.as_bytes(), &subscription),
Err(PoolMessageError::TooLarge)
));
}
#[test]
fn version_rolling_negotiation_and_immediate_mask_change() {
let response = br#"{"id":3,"result":{"version-rolling":true,"version-rolling.mask":"1fffe000"},"error":null}"#;
let mask = parse_configure_response(response, 3).unwrap().unwrap();
assert_eq!(mask.bits(), 0x1fff_e000);
let update = br#"{"id":null,"method":"mining.set_version_mask","params":["00006000"]}"#;
assert_eq!(
parse_control_notification(update, true, false).unwrap(),
PoolNotification::SetVersionMask(alkane_os::pow::VersionMask::new(0x6000).unwrap())
);
assert_eq!(
parse_control_notification(update, false, false),
Err(PoolMessageError::Unnegotiated)
);
assert_eq!(
parse_configure_response(response, 4),
Err(PoolMessageError::WrongMessage)
);
let declined = br#"{"id":3,"result":{"version-rolling":false},"error":null}"#;
assert_eq!(parse_configure_response(declined, 3), Ok(None));
let unsafe_mask = br#"{"id":3,"result":{"version-rolling":true,"version-rolling.mask":"ffffffff"},"error":null}"#;
assert_eq!(
parse_configure_response(unsafe_mask, 3),
Err(PoolMessageError::InvalidField)
);
let absent_mask = br#"{"id":3,"result":{"version-rolling":true},"error":null}"#;
assert_eq!(
parse_configure_response(absent_mask, 3),
Err(PoolMessageError::InvalidField)
);
}
#[test]
fn both_bip310_extensions_and_boolean_responses_are_checked() {
let accepted = br#"{"id":3,"result":{"version-rolling":true,"version-rolling.mask":"1fffe000","subscribe-extranonce":true},"error":null}"#;
let result = parse_configure_result(accepted, 3).unwrap();
assert_eq!(result.version_mask.unwrap().bits(), 0x1fff_e000);
assert!(result.subscribe_extranonce);
let declined =
br#"{"id":3,"result":{"version-rolling":false,"subscribe-extranonce":false},"error":null}"#;
let result = parse_configure_result(declined, 3).unwrap();
assert_eq!(result.version_mask, None);
assert!(!result.subscribe_extranonce);
let unavailable = br#"{"id":3,"result":{"version-rolling":"unavailable","subscribe-extranonce":"unsupported"},"error":null}"#;
let result = parse_configure_result(unavailable, 3).unwrap();
assert_eq!(result.version_mask, None);
assert!(!result.subscribe_extranonce);
assert_eq!(
parse_configure_result(
br#"{"id":3,"result":{"version-rolling":false},"error":null}"#,
3
),
Ok(alkane_os::stratum_v1::ConfigureResult {
version_mask: None,
subscribe_extranonce: false,
})
);
assert_eq!(
parse_configure_result(
br#"{"id":3,"result":{"version-rolling":false,"subscribe-extranonce":null},"error":null}"#,
3
),
Err(PoolMessageError::InvalidField)
);
assert_eq!(
parse_boolean_response(br#"{"id":5,"result":true,"error":null}"#, 5),
Ok(true)
);
assert_eq!(
parse_boolean_response(br#"{"id":5,"result":false,"error":[23,"stale"]}"#, 5),
Ok(false)
);
assert_eq!(
parse_boolean_response(
br#"{"id":5,"result":null,"error":[21,"Job not found",null]}"#,
5
),
Ok(false)
);
assert_eq!(
parse_boolean_response(br#"{"id":5,"result":true,"error":[23,"stale"]}"#, 5),
Err(PoolMessageError::InvalidField)
);
assert_eq!(
parse_boolean_response(br#"{"id":6,"result":true,"error":null}"#, 5),
Err(PoolMessageError::WrongMessage)
);
}
#[test]
fn difficulty_and_extranonce_notifications_validate_shape_and_negotiation() {
let difficulty = br#"{"id":null,"method":"mining.set_difficulty","params":[2048.5]}"#;
assert_eq!(
parse_control_notification(difficulty, false, false),
Ok(PoolNotification::SetDifficulty(
PoolDifficulty::from_json_number(&serde_json::from_str("2048.5").unwrap()).unwrap()
))
);
let extranonce = br#"{"id":null,"method":"mining.set_extranonce","params":["aabbccdd",4]}"#;
assert_eq!(
parse_control_notification(extranonce, false, true),
Ok(PoolNotification::SetExtranonce(Subscription {
extranonce1: vec![0xaa, 0xbb, 0xcc, 0xdd],
extranonce2_size: 4,
}))
);
assert_eq!(
parse_control_notification(extranonce, false, false),
Err(PoolMessageError::Unnegotiated)
);
for value in ["0", "-1", "\"2\"", "null"] {
let line =
format!("{{\"id\":null,\"method\":\"mining.set_difficulty\",\"params\":[{value}]}}");
assert_eq!(
parse_control_notification(line.as_bytes(), false, false),
Err(PoolMessageError::InvalidField)
);
}
let oversize = format!(
"{{\"id\":null,\"method\":\"mining.set_extranonce\",\"params\":[\"{}\",1]}}",
"ab".repeat(33)
);
assert_eq!(
parse_control_notification(oversize.as_bytes(), false, true),
Err(PoolMessageError::InvalidField)
);
let response_id = br#"{"id":5,"method":"mining.set_difficulty","params":[2]}"#;
assert_eq!(
parse_control_notification(response_id, false, false),
Err(PoolMessageError::WrongMessage)
);
}
+249
View File
@@ -0,0 +1,249 @@
// SPDX-License-Identifier: MIT
use alkane_os::stratum_v1::MAX_POOL_LINE_BYTES;
use alkane_os::stratum_wire::{
authorize_request, configure_request, subscribe_request, HandshakeError, StratumWire, WireError,
};
use serde_json::Value;
use std::io::{BufRead, BufReader, Read, Write};
use std::net::TcpListener;
use std::thread;
use std::time::Duration;
#[test]
fn request_frames_escape_pool_credentials_and_advertise_supported_bits() {
let configure: Value = serde_json::from_str(&configure_request(1)).unwrap();
assert_eq!(configure["method"], "mining.configure");
assert_eq!(configure["params"][1]["version-rolling.mask"], "1fffe000");
assert_eq!(configure["params"][0][1], "subscribe-extranonce");
let subscribe: Value =
serde_json::from_str(&subscribe_request(2, "alkane-os/0.1").unwrap()).unwrap();
assert_eq!(subscribe["params"][0], "alkane-os/0.1");
let authorized = authorize_request(3, "worker\"name", "secret\nvalue").unwrap();
assert_eq!(authorized.as_bytes().last(), Some(&b'\n'));
let authorize: Value = serde_json::from_str(&authorized).unwrap();
assert_eq!(authorize["params"][0], "worker\"name");
assert_eq!(authorize["params"][1], "secret\nvalue");
assert!(matches!(
subscribe_request(2, ""),
Err(WireError::InvalidRequest)
));
assert!(matches!(
authorize_request(3, "", "pass"),
Err(WireError::InvalidRequest)
));
}
#[test]
fn loopback_frames_preserve_pipelined_lines_and_reject_invalid_sends() {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let server = thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
stream.write_all(b"{\"id\":1}\n{\"id\":2}\n").unwrap();
let mut request = [0_u8; 3];
stream.read_exact(&mut request).unwrap();
assert_eq!(&request, b"{}\n");
});
let mut wire = StratumWire::connect(address, Duration::from_secs(2)).unwrap();
assert_eq!(wire.read_line().unwrap(), b"{\"id\":1}\n");
assert_eq!(wire.read_line().unwrap(), b"{\"id\":2}\n");
assert!(matches!(
wire.send_line(b"bad\nline\n"),
Err(WireError::InvalidRequest)
));
wire.send_line(b"{}\n").unwrap();
server.join().unwrap();
}
#[test]
fn oversized_pool_line_poison_closes_the_connection() {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let server = thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
let mut line = vec![b'a'; MAX_POOL_LINE_BYTES];
line.push(b'\n');
let _ = stream.write_all(&line);
});
let mut wire = StratumWire::connect(address, Duration::from_secs(2)).unwrap();
assert!(matches!(wire.read_line(), Err(WireError::LineTooLong)));
assert!(matches!(wire.read_line(), Err(WireError::Closed)));
server.join().unwrap();
}
#[test]
fn trickled_pool_line_hits_the_absolute_deadline() {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let server = thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
for byte in b"{123}\n" {
if stream.write_all(&[*byte]).is_err() {
break;
}
thread::sleep(Duration::from_millis(60));
}
});
let mut wire = StratumWire::connect(address, Duration::from_millis(130)).unwrap();
assert!(matches!(wire.read_line(), Err(WireError::Timeout)));
assert!(matches!(wire.send_line(b"{}\n"), Err(WireError::Closed)));
server.join().unwrap();
}
#[test]
fn buffered_complete_lines_do_not_extend_a_partial_line_deadline() {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let server = thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
stream.write_all(b"first\nsecond\nunfinished").unwrap();
thread::sleep(Duration::from_secs(3));
});
let mut wire = StratumWire::connect(address, Duration::from_secs(2)).unwrap();
let first = loop {
if let Some(line) = wire.try_read_line().unwrap() {
break line;
}
};
assert_eq!(first, b"first\n");
thread::sleep(Duration::from_millis(1300));
assert_eq!(wire.try_read_line().unwrap(), Some(b"second\n".to_vec()));
thread::sleep(Duration::from_millis(800));
assert!(matches!(wire.try_read_line(), Err(WireError::Timeout)));
assert!(wire.is_closed());
server.join().unwrap();
}
#[test]
fn idle_timeout_keeps_connection_available_for_later_messages() {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let (release, wait) = std::sync::mpsc::channel();
let server = thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
wait.recv().unwrap();
stream
.write_all(b"{\"id\":null,\"method\":\"mining.set_difficulty\",\"params\":[1]}\n")
.unwrap();
});
let mut wire = StratumWire::connect(address, Duration::from_millis(130)).unwrap();
assert!(matches!(wire.read_line(), Err(WireError::Timeout)));
release.send(()).unwrap();
assert_eq!(
serde_json::from_slice::<Value>(&wire.read_line().unwrap()).unwrap()["method"],
"mining.set_difficulty"
);
server.join().unwrap();
}
#[test]
fn handshake_preserves_early_notifications_and_authorizes_worker() {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let server = thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
let mut input = BufReader::new(stream.try_clone().unwrap());
let mut line = String::new();
input.read_line(&mut line).unwrap();
assert_eq!(
serde_json::from_str::<Value>(&line).unwrap()["method"],
"mining.configure"
);
stream.write_all(b"{\"id\":1,\"result\":{\"version-rolling\":true,\"version-rolling.mask\":\"1fffe000\",\"subscribe-extranonce\":true},\"error\":null}\n").unwrap();
line.clear();
input.read_line(&mut line).unwrap();
assert_eq!(
serde_json::from_str::<Value>(&line).unwrap()["method"],
"mining.subscribe"
);
stream.write_all(b"{\"id\":null,\"method\":\"mining.set_difficulty\",\"params\":[1]}\n{\"id\":2,\"result\":[[],\"01020304\",4],\"error\":null}\n").unwrap();
line.clear();
input.read_line(&mut line).unwrap();
assert_eq!(
serde_json::from_str::<Value>(&line).unwrap()["method"],
"mining.authorize"
);
stream
.write_all(b"{\"id\":3,\"result\":true,\"error\":null}\n")
.unwrap();
});
let mut wire = StratumWire::connect(address, Duration::from_secs(2)).unwrap();
let result = wire
.handshake(
"alkane-os/0.1",
"miner.worker",
"password",
Duration::from_secs(2),
)
.unwrap();
assert_eq!(result.subscription.extranonce1, [1, 2, 3, 4]);
assert_eq!(result.subscription.extranonce2_size, 4);
assert!(result.configure.subscribe_extranonce);
assert_eq!(result.configure.version_mask.unwrap().bits(), 0x1fff_e000);
assert_eq!(result.early_notifications.len(), 1);
assert_eq!(
serde_json::from_slice::<Value>(&result.early_notifications[0]).unwrap()["method"],
"mining.set_difficulty"
);
server.join().unwrap();
}
#[test]
fn rejected_worker_closes_the_handshake_connection() {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let server = thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
let mut input = BufReader::new(stream.try_clone().unwrap());
let mut line = String::new();
input.read_line(&mut line).unwrap();
stream.write_all(b"{\"id\":1,\"result\":{\"version-rolling\":false,\"subscribe-extranonce\":false},\"error\":null}\n").unwrap();
line.clear();
input.read_line(&mut line).unwrap();
stream
.write_all(b"{\"id\":2,\"result\":[[],\"01020304\",4],\"error\":null}\n")
.unwrap();
line.clear();
input.read_line(&mut line).unwrap();
stream
.write_all(b"{\"id\":3,\"result\":false,\"error\":[24,\"unauthorized\"]}\n")
.unwrap();
});
let mut wire = StratumWire::connect(address, Duration::from_secs(2)).unwrap();
assert!(matches!(
wire.handshake("alkane-os/0.1", "bad", "password", Duration::from_secs(2)),
Err(HandshakeError::Rejected)
));
assert!(matches!(wire.read_line(), Err(WireError::Closed)));
server.join().unwrap();
}
#[test]
fn wrong_handshake_reply_id_is_rejected_and_connection_closed() {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let address = listener.local_addr().unwrap();
let server = thread::spawn(move || {
let (mut stream, _) = listener.accept().unwrap();
let mut line = String::new();
BufReader::new(stream.try_clone().unwrap())
.read_line(&mut line)
.unwrap();
stream
.write_all(b"{\"id\":9,\"result\":true,\"error\":null}\n")
.unwrap();
});
let mut wire = StratumWire::connect(address, Duration::from_secs(2)).unwrap();
assert!(matches!(
wire.handshake(
"alkane-os/0.1",
"miner.worker",
"password",
Duration::from_secs(2)
),
Err(HandshakeError::Pool(
alkane_os::stratum_v1::PoolMessageError::WrongMessage
))
));
assert!(matches!(wire.read_line(), Err(WireError::Closed)));
server.join().unwrap();
}
+57
View File
@@ -0,0 +1,57 @@
// SPDX-License-Identifier: MIT
use alkane_os::bm1366::encode_work;
use alkane_os::stratum_work::{JobError, Sha256Job};
fn fixture() -> Sha256Job {
let mut prevhash_stratum = [0_u8; 32];
let mut branch = [0_u8; 32];
for (index, byte) in prevhash_stratum.iter_mut().enumerate() {
*byte = index as u8;
}
for (index, byte) in branch.iter_mut().enumerate() {
*byte = (index + 32) as u8;
}
Sha256Job {
prevhash_stratum,
coinb1: b"abc".to_vec(),
coinb2: b"xyz".to_vec(),
merkle_branches: vec![branch],
version: 0x2000_0000,
nbits: 0x1d00_ffff,
ntime: 0x6655_4433,
extranonce1: vec![1, 2, 3, 4],
extranonce2_size: 4,
}
}
#[test]
fn builds_cross_checked_header_and_asic_work() {
let job = fixture();
let header = job.nonce_zero_header(&[5, 6, 7, 8], job.ntime).unwrap();
let expected = concat!(
"0000002003020100070605040b0a09080f0e0d0c13121110171615141b1a19181f1e1d1c",
"9b9bc91f078af83ff63d00c6da09b5bc4dd26e2d8c0df8ab16b933a259a05881",
"33445566ffff001d00000000"
);
let actual: String = header.iter().map(|byte| format!("{byte:02x}")).collect();
assert_eq!(actual, expected);
let frame = encode_work(&header, 0x18).unwrap();
assert_eq!(&frame[10..14], &header[72..76]);
}
#[test]
fn rejects_invalid_pool_work_before_hashing() {
let mut job = fixture();
assert_eq!(
job.nonce_zero_header(&[5, 6], job.ntime),
Err(JobError::ExtranonceLength)
);
job.extranonce2_size = 33;
assert_eq!(job.validate(), Err(JobError::InvalidExtranonceSize));
job.extranonce2_size = 4;
job.coinb1.resize(65_536, 0);
assert_eq!(job.validate(), Err(JobError::CoinbaseTooLarge));
job.coinb1 = b"abc".to_vec();
job.merkle_branches.resize(65, [0; 32]);
assert_eq!(job.validate(), Err(JobError::TooManyMerkleBranches));
}
+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
+942
View File
@@ -0,0 +1,942 @@
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4
[[package]]
name = "adler2"
version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
[[package]]
name = "aead"
version = "0.5.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0"
dependencies = [
"crypto-common",
"generic-array",
]
[[package]]
name = "aes"
version = "0.8.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"
dependencies = [
"cfg-if",
"cipher",
"cpufeatures",
]
[[package]]
name = "aes-gcm"
version = "0.10.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "831010a0f742e1209b3bcea8fab6a8e149051ba6099432c8cb2cc117dec3ead1"
dependencies = [
"aead",
"aes",
"cipher",
"ctr",
"ghash",
"subtle",
]
[[package]]
name = "aho-corasick"
version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
dependencies = [
"memchr",
]
[[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 = "base64"
version = "0.22.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
[[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 = "chacha20"
version = "0.9.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c3613f74bd2eac03dad61bd53dbe620703d4371614fe0bc3b9f04dd36fe4e818"
dependencies = [
"cfg-if",
"cipher",
"cpufeatures",
]
[[package]]
name = "chacha20poly1305"
version = "0.10.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "10cd79432192d1c0f4e1a0fef9527696cc039165d729fb41b3f4f4f354c2dc35"
dependencies = [
"aead",
"chacha20",
"cipher",
"poly1305",
"zeroize",
]
[[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 = "cipher"
version = "0.4.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
dependencies = [
"crypto-common",
"inout",
"zeroize",
]
[[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 = "crc32fast"
version = "1.5.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "01a7799fd6b852db0e61728dde9a204c423b44d689dbd432522543614b490e78"
dependencies = [
"cfg-if",
]
[[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",
"rand_core 0.6.4",
"typenum",
]
[[package]]
name = "ctr"
version = "0.9.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0369ee1ad671834580515889b80f2ea915f23b8be8d0daa4bbaf2ac5c7590835"
dependencies = [
"cipher",
]
[[package]]
name = "curve25519-dalek"
version = "4.1.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "97fb8b7c4503de7d6ae7b42ab72a5a59857b4c937ec27a3d4539dba95b5ab2be"
dependencies = [
"cfg-if",
"cpufeatures",
"curve25519-dalek-derive",
"fiat-crypto",
"rustc_version",
"subtle",
]
[[package]]
name = "curve25519-dalek-derive"
version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f46882e17999c6cc590af592290432be3bce0428cb0d5f8b6715e4dc7b383eb3"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]]
name = "digest"
version = "0.10.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
dependencies = [
"block-buffer",
"crypto-common",
"subtle",
]
[[package]]
name = "ed25519-compact"
version = "2.6.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1454db4f2edb7f0e8fe0c5b375b0c978fc63244cc9f010d160e417eb10139aa8"
[[package]]
name = "either"
version = "1.19.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
[[package]]
name = "fiat-crypto"
version = "0.2.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "28dea519a9695b9977216879a3ebfddf92f1c08c05d984f8996aecd6ecdc811d"
[[package]]
name = "flare-plugin-abi"
version = "0.0.1"
[[package]]
name = "flare-ui"
version = "0.0.1"
dependencies = [
"criterion",
"maud",
"serde_json",
"wschema",
]
[[package]]
name = "flate2"
version = "1.1.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
dependencies = [
"crc32fast",
"miniz_oxide",
]
[[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 = "getrandom"
version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
dependencies = [
"cfg-if",
"libc",
"wasi",
]
[[package]]
name = "ghash"
version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0d8a4362ccb29cb0b265253fb0a2728f592895ee6854fd9bc13f2ffda266ff1"
dependencies = [
"opaque-debug",
"polyval",
]
[[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 = "hkdf"
version = "0.12.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7b5f8eb2ad728638ea2c7d47a21db23b7b58a72ed6a38256b8a1849f15fbbdf7"
dependencies = [
"hmac",
]
[[package]]
name = "hmac"
version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6c49c37c09c17a53d937dfbb742eb3a961d65a994e6bcdcf37e7399d0cc8ab5e"
dependencies = [
"digest",
]
[[package]]
name = "hpke"
version = "0.13.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f65d16b699dd1a1fa2d851c970b0c971b388eeeb40f744252b8de48860980c8f"
dependencies = [
"aead",
"aes-gcm",
"chacha20poly1305",
"digest",
"generic-array",
"hkdf",
"hmac",
"rand_core 0.9.5",
"sha2",
"subtle",
"x25519-dalek",
"zeroize",
]
[[package]]
name = "inout"
version = "0.1.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
dependencies = [
"generic-array",
]
[[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]]
name = "itoa"
version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "libc"
version = "0.2.190"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
[[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 = "miniz_oxide"
version = "0.9.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"
dependencies = [
"adler2",
"simd-adler32",
]
[[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 = "opaque-debug"
version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
[[package]]
name = "poly1305"
version = "0.8.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8159bd90725d2df49889a078b54f4f79e87f1f8a8444194cdca81d38f5393abf"
dependencies = [
"cpufeatures",
"opaque-debug",
"universal-hash",
]
[[package]]
name = "polyval"
version = "0.6.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25"
dependencies = [
"cfg-if",
"cpufeatures",
"opaque-debug",
"universal-hash",
]
[[package]]
name = "proc-macro2"
version = "1.0.107"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
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"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
dependencies = [
"proc-macro2",
]
[[package]]
name = "rand_core"
version = "0.6.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
dependencies = [
"getrandom",
]
[[package]]
name = "rand_core"
version = "0.9.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
[[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 = "rustc_version"
version = "0.4.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
dependencies = [
"semver",
]
[[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 = "semver"
version = "1.0.28"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
[[package]]
name = "serde"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
dependencies = [
"serde_core",
"serde_derive",
]
[[package]]
name = "serde_core"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
dependencies = [
"serde_derive",
]
[[package]]
name = "serde_derive"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.9",
]
[[package]]
name = "serde_json"
version = "1.0.154"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
dependencies = [
"itoa",
"memchr",
"serde",
"serde_core",
"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 = "simd-adler32"
version = "0.3.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
[[package]]
name = "subtle"
version = "2.6.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
[[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"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
dependencies = [
"proc-macro2",
"quote",
"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 = "universal-hash"
version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea"
dependencies = [
"crypto-common",
"subtle",
]
[[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 = "wapp-core"
version = "0.0.1"
dependencies = [
"ed25519-compact",
"flate2",
"sha2",
]
[[package]]
name = "wapp-pack"
version = "0.0.1"
dependencies = [
"sha2",
"wapp-core",
"wschema",
]
[[package]]
name = "warden-seal"
version = "0.0.1"
dependencies = [
"base64",
"hpke",
"serde",
"serde_json",
"sha2",
"zeroize",
]
[[package]]
name = "warden-sync"
version = "0.0.1"
dependencies = [
"criterion",
"serde_json",
"sha2",
]
[[package]]
name = "wasi"
version = "0.11.1+wasi-snapshot-preview1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
[[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 = "wschema-cli"
version = "0.0.1"
dependencies = [
"serde_json",
"wschema",
]
[[package]]
name = "wschema-gen"
version = "0.0.1"
dependencies = [
"regex",
"serde_json",
"wschema",
]
[[package]]
name = "x25519-dalek"
version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c7e468321c81fb07fa7f4c636c3972b9100f0346e5b6a9f2bd0603a52f7ed277"
dependencies = [
"curve25519-dalek",
"rand_core 0.6.4",
]
[[package]]
name = "zerocopy"
version = "0.8.62"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "86502bf56ac7c77571a32e2647bb2a15894565e981fb2a48d7bde2d91c965a9d"
dependencies = [
"zerocopy-derive",
]
[[package]]
name = "zerocopy-derive"
version = "0.8.62"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5457206954b06561e2608c7e19cf58b1926586d999c246eebe4502f7e2039d1a"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]]
name = "zeroize"
version = "1.9.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879"
dependencies = [
"zeroize_derive",
]
[[package]]
name = "zeroize_derive"
version = "1.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3c50655cbb0fe3fc43170059e702f1ce5e19b84cec58dc87b037a09935c2f328"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]]
name = "zmij"
version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
+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.
+12
View File
@@ -0,0 +1,12 @@
# 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-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
+70
View File
@@ -0,0 +1,70 @@
# 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, navigation, chart islands, page assets and editor assets |
| `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
```
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 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"}

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