Add a HAL conformance harness for family backends
source-pr / source (pull_request) Successful in 12s
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.
This commit is contained in:
@@ -0,0 +1,207 @@
|
||||
// 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(_) => match client.read_power_w() {
|
||||
Ok(watts) if watts <= 10_000 => Check::pass(NAME, format!("{watts} W")),
|
||||
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));
|
||||
}
|
||||
}
|
||||
@@ -13,6 +13,7 @@ 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;
|
||||
|
||||
+26
-1
@@ -334,6 +334,31 @@ fn main() {
|
||||
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}");
|
||||
@@ -347,7 +372,7 @@ fn main() {
|
||||
}
|
||||
}
|
||||
_ => {
|
||||
eprintln!("usage: alkane-os --list-targets | --version | --self-check | --boot HAL_SOCKET PROFILES.json TARGET [PIC|NOPIC] [TICKS] | --sim-hal SOCKET | --mine-simulator HAL_SOCKET POOL_ADDRESS WORKER BM1362|BM1366 [MAX_ACCEPTS]");
|
||||
eprintln!("usage: alkane-os --list-targets | --version | --self-check | --boot HAL_SOCKET PROFILES.json TARGET [PIC|NOPIC] [TICKS] | --sim-hal SOCKET | --check-hal SOCKET | --mine-simulator HAL_SOCKET POOL_ADDRESS WORKER BM1362|BM1366 [MAX_ACCEPTS]");
|
||||
eprintln!(
|
||||
"env: ALKANE_API_LISTEN=ADDR ALKANE_WEB_LISTEN=ADDR ALKANE_POOL_PASSWORD=..."
|
||||
);
|
||||
|
||||
Reference in New Issue
Block a user