Add fail-safe BM1366 mining session
next-build / build (push) Canceled after 0s

This commit is contained in:
2026-10-14 19:53:40 -06:00
parent 81d726cca2
commit 9f7d8ebb51
6 changed files with 489 additions and 23 deletions
+6 -1
View File
@@ -35,12 +35,17 @@ board adapter is installed in an image yet.
The library can also verify an ASIC-reported SHA-256d share against an exact
pool target, including BM13xx version rolling. A test checks a BM1366 nonce
captured from real silicon at difficulty 1588. This verifies reports only;
work distribution, pool communication, and mining control are still pending.
pool communication and continuous job scheduling are still pending.
The `simulator_replay_probe` example sends that captured job through the Rust
HAL client to the SDK's host-only C/Python replay server, then verifies the
returned nonce. From this repository, run it with
`cargo run --example simulator_replay_probe -- SOCKET_PATH` after starting
the SDK server. It is a simulator check and sends work to the named socket.
The first BM1366 mining session sequences fan, temperature, PSU, reset,
work submission, and nonce polling through the HAL. It rejects stale work IDs,
malformed reports, and hashes below the caller's pool target. Sensor or HAL
failure stops the PSU. The caller must provide a board-validated temperature
limit.
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
+8 -21
View File
@@ -1,10 +1,8 @@
// SPDX-License-Identifier: MIT
//! Exercise the SDK's host-only BM1366 HAL simulator with a captured job.
use alkane_os::bm1366::{decode_nonce_report, encode_work, REPORT_BYTES};
use alkane_os::hal_wire::HalClient;
use alkane_os::pow::verify_sha256_report;
use alkane_os::HardwareBackend;
use alkane_os::miner::Bm1366Miner;
use std::error::Error;
const HEADER: [u8; 80] = [
@@ -20,26 +18,15 @@ fn main() -> Result<(), Box<dyn Error>> {
.nth(1)
.ok_or("usage: simulator_replay_probe SOCKET_PATH")?;
let mut backend = HalClient::connect(path)?;
backend.set_psu_enabled(true)?;
backend.set_chain_reset(0, true)?;
backend.set_chain_reset(0, false)?;
backend.send_frame(0, &encode_work(&HEADER, 0x18).ok_or("invalid work header")?)?;
let mut buffer = [0_u8; REPORT_BYTES];
let length = backend.receive_frame(0, &mut buffer)?;
if length != REPORT_BYTES {
return Err("missing BM1366 nonce report".into());
}
let report = decode_nonce_report(&buffer).map_err(|_| "invalid BM1366 nonce report")?;
if report.work_id != 0x18 {
return Err("stale BM1366 work ID".into());
}
let mut miner = Bm1366Miner::new(&mut backend, 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);
let result = verify_sha256_report(&HEADER, report.nonce, report.version_field, &target);
backend.set_psu_enabled(false)?;
if !result.meets_target {
return Err("captured nonce does not meet difficulty 1".into());
}
miner.submit(HEADER, target, 0x18)?;
let share = miner.poll()?.ok_or("missing BM1366 nonce report")?;
miner.stop()?;
assert_eq!(share.nonce, 0xedad_ff38);
println!("BM1366 captured report verified at difficulty 1");
Ok(())
}
+1
View File
@@ -5,6 +5,7 @@
pub mod bm1366;
pub mod hal_wire;
pub mod miner;
pub mod pow;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+231
View File
@@ -0,0 +1,231 @@
// SPDX-License-Identifier: MIT
//! One-chain BM1366 mining control built on the SDK hardware backend.
//! This module never searches for nonces or chooses board safety thresholds.
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(Debug, Eq, PartialEq)]
pub enum MinerError<E> {
Backend(E),
AlreadyRunning,
NotRunning,
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::UnsafeTemperature(value) => write!(f, "unsafe temperature: {value} mC"),
Self::InvalidWork => f.write_str("invalid BM1366 work"),
Self::InvalidReport(error) => write!(f, "invalid BM1366 report: {error:?}"),
Self::StaleReport => f.write_str("stale BM1366 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,
chain: u8,
sensor: u8,
fan: u8,
fan_percent: u8,
max_temperature_mc: i32,
running: bool,
work: Option<Work>,
}
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> {
if fan_percent == 0 || fan_percent > 100 || max_temperature_mc <= 0 {
return None;
}
Some(Self {
backend,
chain,
sensor,
fan,
fan_percent,
max_temperature_mc,
running: false,
work: None,
})
}
fn power_off(&mut self) -> Result<(), B::Error> {
self.work = None;
match self.backend.set_psu_enabled(false) {
Ok(()) => {
self.running = false;
Ok(())
}
Err(error) => {
// The backend may have left power on. Drop retries shutdown.
self.running = 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()
}
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);
}
let frame = encode_work(&header, work_id).ok_or(MinerError::InvalidWork)?;
self.check_temperature()?;
if let Err(error) = self.backend.send_frame(self.chain, &frame) {
let _ = self.power_off();
return Err(MinerError::Backend(error));
}
self.work = Some(Work {
header,
target_le,
id: work_id,
});
Ok(())
}
pub fn poll(&mut self) -> Result<Option<ValidShare>, MinerError<B::Error>> {
if !self.running {
return Err(MinerError::NotRunning);
}
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 else {
let _ = self.power_off();
return Err(MinerError::StaleReport);
};
if report.work_id != work.id {
let _ = self.power_off();
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,
}))
}
}
impl<B: HardwareBackend> Drop for Bm1366Miner<'_, B> {
fn drop(&mut self) {
if self.running {
let _ = self.power_off();
}
}
}
+45 -1
View File
@@ -1,6 +1,7 @@
use alkane_os::bm1366::{decode_nonce_report, encode_work};
use alkane_os::miner::Bm1366Miner;
use alkane_os::pow::verify_sha256_report;
use alkane_os::{power_decision, target_matrix};
use alkane_os::{power_decision, target_matrix, HardwareBackend};
use std::hint::black_box;
use std::time::Instant;
@@ -67,3 +68,46 @@ fn bench_bm1366_report_decode() {
let _ = black_box(decode_nonce_report(black_box(&report)));
});
}
struct BenchBackend;
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> {
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;
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();
});
}
+198
View File
@@ -0,0 +1,198 @@
// SPDX-License-Identifier: MIT
use alkane_os::bm1366::REPORT_BYTES;
use alkane_os::miner::{Bm1366Miner, 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,
report: Option<[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() {
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.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 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_and_stale_report_fail_closed() {
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, 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(), 0x20).unwrap();
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);
}