#![deny(missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]
mod commands;
mod release;
mod spec;
mod stream;
pub use commands::*;
pub use release::*;
pub use spec::*;
pub(crate) use spec::{STREAM_REGS, USB3_REG};
#[cfg(feature = "usb3")]
pub(crate) use spec::{USB3_MSG, USB3_STREAM};
pub use stream::*;
#[doc(hidden)]
pub mod codec;
pub mod bundled;
mod udp;
#[cfg(feature = "usb3")]
mod usb3;
#[cfg(feature = "sim")]
mod simlink;
use std::collections::HashMap;
use std::fmt;
use std::io;
use std::net::SocketAddr;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
use serde_json::Value;
#[cfg(feature = "usb3")]
#[cfg_attr(docsrs, doc(cfg(feature = "usb3")))]
pub use usb3::SdkErr;
#[derive(Clone, Debug)]
pub struct DeviceInfo {
pub serial: String,
pub vendor: String,
pub compatible: String,
pub board_id: Option<u32>,
pub kdi: Option<(u16, u16)>,
pub transport: TransportKind,
pub addr: Addr,
}
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum TransportKind {
Udp,
Usb3,
#[cfg(feature = "sim")]
#[cfg_attr(docsrs, doc(cfg(feature = "sim")))]
Sim,
}
impl TransportKind {
fn token(self) -> &'static str {
match self {
TransportKind::Udp => "udp",
TransportKind::Usb3 => "usb3",
#[cfg(feature = "sim")]
TransportKind::Sim => "sim",
}
}
}
#[derive(Clone, Debug)]
#[non_exhaustive]
pub enum Addr {
Socket(SocketAddr),
Serial(String),
}
#[derive(Clone, Default, Debug)]
pub struct Filter {
pub serial: Option<String>,
pub compatible: Option<String>,
pub board_id: Option<u32>,
pub transport: Option<TransportKind>,
}
impl Filter {
fn matches(&self, i: &DeviceInfo) -> bool {
if let Some(s) = &self.serial {
if *s != i.serial {
return false;
}
}
if let Some(c) = &self.compatible {
if *c != i.compatible {
return false;
}
}
if let Some(b) = self.board_id {
if Some(b) != i.board_id {
return false;
}
}
if let Some(t) = self.transport {
if t != i.transport {
return false;
}
}
true
}
}
pub fn find(f: &Filter) -> (Vec<DeviceInfo>, Vec<Error>) {
let mut found = Vec::new();
let mut errs = Vec::new();
let dir = std::env::var_os("KDI_DISCOVERY_DIR")
.map(PathBuf::from)
.unwrap_or_else(|| std::env::temp_dir().join("kdi-discovery"));
match std::fs::read_dir(&dir) {
Ok(entries) => {
for e in entries {
match e {
Ok(e) if e.path().extension().is_some_and(|x| x == "json") => {
match announced(&e.path()) {
Ok(Some(info)) => found.push(info),
Ok(None) => {} Err(err) => errs.push(err),
}
}
Ok(_) => {}
Err(err) => errs.push(Error::Io(err)),
}
}
}
Err(e) if e.kind() == io::ErrorKind::NotFound => {}
Err(e) => errs.push(Error::Io(e)),
}
#[cfg(feature = "usb3")]
match usb3::enumerate() {
Ok(list) => found.extend(list),
Err(e) => errs.push(e),
}
found.retain(|i| f.matches(i));
(found, errs)
}
fn announced(path: &Path) -> Result<Option<DeviceInfo>, Error> {
let text = std::fs::read_to_string(path).map_err(Error::Io)?;
let v: Value = serde_json::from_str(&text).map_err(|e| {
io_err(
io::ErrorKind::InvalidData,
format!("{}: {e}", path.display()),
)
})?;
if v.get("transport").and_then(Value::as_str) != Some(TransportKind::Udp.token()) {
return Ok(None);
}
let (Some(host), Some(port)) = (
v.get("host").and_then(Value::as_str),
v.get("port").and_then(Value::as_u64),
) else {
return Ok(None);
};
let addr: SocketAddr = match format!("{host}:{port}").parse() {
Ok(a) => a,
Err(e) => return Err(io_err(io::ErrorKind::InvalidData, e.to_string())),
};
match udp::probe(addr, Duration::from_millis(300)) {
Ok(live) => Ok(info_from(&live, addr)),
Err(Error::Host(HostErr::HostTimeout)) => Ok(None),
Err(e) => Err(e),
}
}
fn info_from(v: &Value, addr: SocketAddr) -> Option<DeviceInfo> {
let s = |k: &str| v.get(k).and_then(Value::as_str).unwrap_or("").to_string();
Some(DeviceInfo {
serial: match v.get("serial").and_then(Value::as_str) {
Some(s) if !s.is_empty() => s.to_string(),
_ => return None,
},
vendor: s("vendor"),
compatible: s("compatible"),
board_id: v.get("board_id").and_then(Value::as_u64).map(|b| b as u32),
kdi: parse_kdi(&s("kdi")),
transport: TransportKind::Udp,
addr: Addr::Socket(addr),
})
}
fn parse_kdi(s: &str) -> Option<(u16, u16)> {
let (a, b) = s.split_once('.')?;
Some((a.parse().ok()?, b.parse().ok()?))
}
#[derive(Clone)]
pub struct ConnectOpts {
pub need_caps: Vec<Cap>,
pub ready_timeout: Duration,
}
impl Default for ConnectOpts {
fn default() -> Self {
Self {
need_caps: Vec::new(),
ready_timeout: Duration::from_millis(READY_TIMEOUT_MS),
}
}
}
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum Lease {
Held,
Unsupported,
}
fn mint_token() -> String {
let here = 0u8;
let nanos = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map_or(0, |d| d.as_nanos() as u64);
let entropy = nanos ^ (&here as *const u8 as usize as u64);
format!("host-{}-{entropy:x}", std::process::id())
}
const RATE_APPLY_TRIES: u32 = 4;
pub struct Device {
link: Link,
info: DeviceInfo,
caps: Caps,
gateware_sha: u32,
kdi: (u16, u16),
wire_in: HashMap<u8, u32>,
next_id: u32,
token: String,
lease: Lease,
}
impl Device {
pub fn open(info: &DeviceInfo, opts: &ConnectOpts) -> Result<Device, Error> {
match (&info.addr, info.transport) {
(Addr::Socket(a), TransportKind::Udp) => {
let link = Link::Udp(udp::Udp::connect(*a, opts.ready_timeout)?);
Device::bind(link, info.clone(), opts)
}
#[cfg(feature = "usb3")]
(Addr::Serial(s), TransportKind::Usb3) => {
let link = Link::Usb3(usb3::Usb3::open(s, None, None)?);
Device::bind(link, info.clone(), opts)
}
_ => Err(io_err(
io::ErrorKind::Unsupported,
format!(
"no binding for transport {} in this build (usb3 needs --features usb3)",
info.transport.token()
),
)),
}
}
pub fn connect_udp(addr: SocketAddr, timeout: Duration) -> Result<Device, Error> {
let mut link = Link::Udp(udp::Udp::connect(addr, timeout)?);
let ident = link.discover()?;
let info = info_from(&ident, addr).unwrap_or(DeviceInfo {
serial: String::new(),
vendor: String::new(),
compatible: String::new(),
board_id: None,
kdi: None,
transport: TransportKind::Udp,
addr: Addr::Socket(addr),
});
Device::bind(
link,
info,
&ConnectOpts {
need_caps: Vec::new(),
ready_timeout: timeout,
},
)
}
#[cfg(feature = "usb3")]
#[cfg_attr(docsrs, doc(cfg(feature = "usb3")))]
pub fn open_usb3(serial: &str, driver_dir: Option<&Path>) -> Result<Device, Error> {
Device::usb3(serial, driver_dir, None)
}
#[cfg(feature = "usb3")]
#[cfg_attr(docsrs, doc(cfg(feature = "usb3")))]
pub fn open_usb3_configured(serial: &str, image: &[u8]) -> Result<Device, Error> {
Device::usb3(serial, None, Some(image))
}
#[cfg(feature = "usb3")]
fn usb3(
serial: &str,
driver_dir: Option<&Path>,
image: Option<&[u8]>,
) -> Result<Device, Error> {
let link = Link::Usb3(usb3::Usb3::open(serial, driver_dir, image)?);
let info = DeviceInfo {
serial: serial.to_string(),
vendor: String::new(),
compatible: String::new(),
board_id: None,
kdi: None,
transport: TransportKind::Usb3,
addr: Addr::Serial(serial.to_string()),
};
Device::bind(link, info, &ConnectOpts::default())
}
fn bind(link: Link, info: DeviceInfo, opts: &ConnectOpts) -> Result<Device, Error> {
let mut d = Device {
link,
info,
caps: Caps(0),
gateware_sha: 0,
kdi: (0, 0),
wire_in: HashMap::new(),
next_id: 0,
token: mint_token(),
lease: Lease::Unsupported,
};
let cv = d.read_reg("contract_version")?;
if cv == 0 {
return Err(Error::Skew(Skew::NotKdi));
}
let (major, minor) = ((cv >> 16) as u16, cv as u16);
if major != KDI_MAJOR {
return Err(Error::Skew(Skew::Major {
device: major,
host: KDI_MAJOR,
}));
}
d.kdi = (major, minor);
d.info.kdi = Some((major, minor));
d.wait_ready(opts.ready_timeout)?;
d.caps = Caps(d.read_reg("caps")?);
let missing: Vec<Cap> = opts
.need_caps
.iter()
.copied()
.filter(|c| !d.caps.has(*c))
.collect();
if !missing.is_empty() {
return Err(Error::Skew(Skew::MissingCaps(missing)));
}
d.gateware_sha = d.read_reg("gateware_sha")?;
d.lease = if d.caps.has(Cap::CommandProtocol) {
d.claim()?
} else {
Lease::Unsupported
};
Ok(d)
}
fn claim(&mut self) -> Result<Lease, Error> {
if !self.link.has_message() {
return Ok(Lease::Unsupported);
}
match self.raw_cmd("sys.claim", &[]) {
Ok(r) if r.ok() => Ok(Lease::Held),
Ok(r) if r.err == Some(DeviceErr::UnknownCmd) => Ok(Lease::Unsupported),
Ok(r) => Err(Error::Skew(Skew::Busy(r))),
Err(e) => Err(e),
}
}
pub fn info(&self) -> &DeviceInfo {
&self.info
}
pub fn lease(&self) -> Lease {
self.lease
}
pub fn kdi(&self) -> (u16, u16) {
self.kdi
}
pub fn caps(&self) -> Caps {
self.caps
}
pub fn gateware_sha(&self) -> u32 {
self.gateware_sha
}
pub fn wait_ready(&mut self, timeout: Duration) -> Result<(), Error> {
let deadline = Instant::now() + timeout;
loop {
if self.read_reg("contract_ready")? != 0 {
return Ok(());
}
if Instant::now() >= deadline {
return Err(Error::Skew(Skew::NotReady));
}
std::thread::sleep(Duration::from_millis(20));
}
}
pub fn raw_cmd(&mut self, name: &str, args: &[&str]) -> Result<Reply, Error> {
if !args.iter().all(|a| safe_token(a)) {
return Err(Error::Host(HostErr::HostUnsafeArg));
}
self.send(name, &positional(name, args))
}
pub fn raw_cmd_named(&mut self, name: &str, args: &[(&str, Arg<'_>)]) -> Result<Reply, Error> {
if !args.iter().all(|(k, v)| safe_token(k) && v.is_safe()) {
return Err(Error::Host(HostErr::HostUnsafeArg));
}
self.send(name, args)
}
fn send(&mut self, name: &str, args: &[(&str, Arg<'_>)]) -> Result<Reply, Error> {
if !safe_token(name) {
return Err(Error::Host(HostErr::HostUnsafeArg));
}
self.next_id = self.next_id.wrapping_add(1);
let id = format!("{:x}", self.next_id);
debug_assert!(safe_token(&id));
self.link.message(&id, name, args, &self.token)
}
pub fn unlock_with(
&mut self,
tier: &str,
sign: impl FnOnce(&[u8]) -> [u8; 64],
) -> Result<Reply, Error> {
let ch = self.raw_cmd("sys.challenge", &[])?;
if !ch.ok() {
return Err(Error::Device(ch));
}
let int = |k: &str| ch.get(k).and_then(Value::as_u64);
let (nonce, dna) = match (int("nonce").and_then(|n| u32::try_from(n).ok()), int("dna")) {
(Some(n), Some(d)) => (n, d),
_ => {
let why = format!("sys.challenge: no u32 `nonce` + u64 `dna` in {}", ch.body());
return Err(io_err(io::ErrorKind::InvalidData, why));
}
};
let sig: String = sign(&grant_bytes(tier, nonce, dna))
.iter()
.map(|b| format!("{b:02x}"))
.collect();
let args = [tier, &nonce.to_string(), &dna.to_string(), &sig];
let r = self.raw_cmd("sys.unlock", &args)?;
if r.ok() {
Ok(r)
} else {
Err(Error::Device(r))
}
}
pub fn close(mut self) -> Result<(), Error> {
let _ = self.quiesce();
if self.lease == Lease::Held {
let _ = self.raw_cmd("sys.release", &[]);
}
drop(self);
Ok(())
}
pub fn quiesce(&mut self) -> Result<(), Error> {
for s in [Stream::Samples, Stream::Digital] {
let _ = self.write_field(crate::stream::run_reg(s), 0);
}
self.write_field("quiesce", 1)?;
self.write_field("quiesce", 0)
}
pub fn rate_ready(&mut self) -> Result<bool, Error> {
Ok(self.read_reg("rate_ready")? & 1 != 0)
}
pub fn set_rate(&mut self, m: u8, d: u8) -> Result<(), Error> {
if !self.caps().has(Cap::RateControl) {
return Err(io_err(
io::ErrorKind::Unsupported,
"this device does not advertise rate_control; its rate cannot be configured or verified",
));
}
let md = (u32::from(m) << 8) | u32::from(d);
for _ in 0..RATE_APPLY_TRIES {
self.write_field("rate_md", md)?;
self.write_field("rate_apply", 1)?;
std::thread::sleep(Duration::from_millis(20));
if self.rate_ready()? {
return Ok(());
}
}
Err(io_err(
io::ErrorKind::TimedOut,
format!(
"rate_ready stayed clear after {RATE_APPLY_TRIES} attempts to program the rate"
),
))
}
pub fn set_miso_delay(&mut self, taps: [u8; 8]) -> Result<(), Error> {
let mut word = 0u32;
for (port, &tap) in taps.iter().enumerate() {
if tap > 15 {
return Err(io_err(
io::ErrorKind::InvalidInput,
format!(
"miso_delay tap for port {} is {tap}; the field is 4 bits, so 0..=15",
(b'A' + port as u8) as char
),
));
}
word |= u32::from(tap) << (port * 4);
}
self.write_field("miso_delay", word)
}
pub fn miso_delay(&mut self) -> Result<[u8; 8], Error> {
let word = self.read_reg("miso_delay")?;
let mut taps = [0u8; 8];
for (port, tap) in taps.iter_mut().enumerate() {
*tap = ((word >> (port * 4)) & 0xf) as u8;
}
Ok(taps)
}
fn read_reg(&mut self, name: &str) -> Result<u32, Error> {
let r = reg(name)?;
if r.kind != "wireout" {
return Err(io_err(
io::ErrorKind::InvalidInput,
format!("{name} is a {} - not readable", r.kind),
));
}
self.link.reg_read(name, r)
}
fn write_field(&mut self, name: &str, value: u32) -> Result<(), Error> {
let r = reg(name)?;
if r.kind == "wireout" {
return Err(io_err(
io::ErrorKind::InvalidInput,
format!("{name} is a wireout - not writable"),
));
}
let word = self.wire_in.entry(r.addr).or_default();
*word = apply_field(*word, r, value);
let word = *word;
self.link.reg_write(name, r, value, word)
}
}
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
struct RegBind {
kind: &'static str,
addr: u8,
lo: u8,
width: u8,
}
impl RegBind {
fn mask(self) -> u32 {
if self.width >= 32 {
u32::MAX
} else {
((1u32 << self.width) - 1) << self.lo
}
}
}
fn reg(name: &str) -> Result<RegBind, Error> {
USB3_REG
.iter()
.find(|(n, ..)| *n == name)
.map(|&(_, kind, addr, lo, width)| RegBind {
kind,
addr,
lo: lo.unwrap_or(0),
width,
})
.ok_or_else(|| {
io_err(
io::ErrorKind::InvalidInput,
format!("no register named {name} in this contract"),
)
})
}
fn apply_field(word: u32, r: RegBind, value: u32) -> u32 {
let m = r.mask();
(word & !m) | ((value << r.lo) & m)
}
fn stream_regs(
s: Stream,
) -> (
&'static str,
&'static str,
&'static str,
Option<&'static str>,
) {
STREAM_REGS
.iter()
.find(|(n, ..)| *n == s.token())
.map(|&(_, run, burst, status, lanes)| (run, burst, status, lanes))
.expect("STREAM_REGS and Stream are generated from the same contract")
}
enum Link {
Udp(udp::Udp),
#[cfg(feature = "usb3")]
Usb3(usb3::Usb3),
#[cfg(feature = "sim")]
Sim(simlink::Sim),
}
impl Link {
fn discover(&mut self) -> Result<Value, Error> {
match self {
Link::Udp(u) => u.discover(),
#[cfg(feature = "usb3")]
Link::Usb3(u) => Ok(u.identity()),
#[cfg(feature = "sim")]
Link::Sim(u) => Ok(u.identity()),
}
}
#[cfg_attr(not(any(feature = "usb3", feature = "sim")), allow(unused_variables))]
fn reg_read(&mut self, name: &str, r: RegBind) -> Result<u32, Error> {
match self {
Link::Udp(u) => u.reg_read(name),
#[cfg(feature = "usb3")]
Link::Usb3(u) => u.reg_read(r),
#[cfg(feature = "sim")]
Link::Sim(u) => u.reg_read(r),
}
}
#[cfg_attr(not(any(feature = "usb3", feature = "sim")), allow(unused_variables))]
fn reg_write(&mut self, name: &str, r: RegBind, field: u32, word: u32) -> Result<(), Error> {
match self {
Link::Udp(u) => u.reg_write(name, field),
#[cfg(feature = "usb3")]
Link::Usb3(u) => u.reg_write(r, word),
#[cfg(feature = "sim")]
Link::Sim(u) => u.reg_write(r, word),
}
}
fn stream_read(&mut self, s: Stream, buf: &mut [u8]) -> Result<usize, Error> {
match self {
Link::Udp(u) => u.stream_read(s.token(), buf),
#[cfg(feature = "usb3")]
Link::Usb3(u) => u.stream_read(s, buf),
#[cfg(feature = "sim")]
Link::Sim(u) => u.stream_read(s, buf),
}
}
fn message(
&mut self,
id: &str,
name: &str,
args: &[(&str, Arg<'_>)],
token: &str,
) -> Result<Reply, Error> {
match self {
Link::Udp(u) => u.message(id, name, args, token),
#[cfg(feature = "usb3")]
Link::Usb3(u) => u.message(id, name, args, token),
#[cfg(feature = "sim")]
Link::Sim(u) => u.message(id, name, args, token),
}
}
fn has_message(&self) -> bool {
match self {
Link::Udp(_) => true,
#[cfg(feature = "usb3")]
Link::Usb3(_) => true,
#[cfg(feature = "sim")]
Link::Sim(_) => false,
}
}
}
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub struct Caps(pub u32);
const ALL_CAPS: [Cap; 9] = [
Cap::CleanFrame,
Cap::CommandProtocol,
Cap::Ddr3,
Cap::Adio,
Cap::Grounding,
Cap::TtlIn,
Cap::SlotHealth,
Cap::FieldUpdate,
Cap::RateControl,
];
impl Caps {
pub fn has(self, c: Cap) -> bool {
self.0 >> c.bit() & 1 != 0
}
pub fn iter(self) -> impl Iterator<Item = Cap> {
ALL_CAPS.into_iter().filter(move |c| self.has(*c))
}
}
#[must_use]
#[derive(Clone, Debug)]
pub struct Reply {
pub id: String,
pub rc: i32,
pub err: Option<DeviceErr>,
body: Value,
raw: String,
}
impl Reply {
pub fn ok(&self) -> bool {
self.rc == 0
}
pub fn get(&self, k: &str) -> Option<&Value> {
self.body.get(k)
}
pub fn body(&self) -> &str {
&self.raw
}
}
fn reply_from(v: Value) -> Result<Reply, Error> {
if !v.is_object() {
return Err(io_err(
io::ErrorKind::InvalidData,
format!("reply is not a JSON object: {v}"),
));
}
let id = match v.get("id") {
Some(Value::String(s)) => s.clone(),
Some(other) => other.to_string(),
None => String::new(),
};
Ok(Reply {
id,
rc: v.get("rc").and_then(Value::as_i64).unwrap_or(-1) as i32,
err: v
.get("err")
.and_then(Value::as_str)
.and_then(DeviceErr::from_token),
raw: v.to_string(),
body: v,
})
}
impl DeviceErr {
pub fn retryable(self) -> bool {
match self {
DeviceErr::NoDevice => true, DeviceErr::Busy => true, DeviceErr::NotReady => true, DeviceErr::I2cNak => true, DeviceErr::BadArgs => false,
DeviceErr::UnknownCmd => false,
DeviceErr::TierLocked => false,
DeviceErr::NotPresent => false,
DeviceErr::NoIp => false,
DeviceErr::Internal => false,
DeviceErr::NotClaimed => false,
DeviceErr::ConfirmRequired => false,
DeviceErr::RoRegister => false,
DeviceErr::NoSuchRegister => false,
DeviceErr::ResponseTooLarge => false,
DeviceErr::I2cTimeout => false, }
}
}
#[derive(Debug)]
#[non_exhaustive]
pub enum Error {
Device(Reply),
Host(HostErr),
Skew(Skew),
Io(io::Error),
#[cfg(feature = "usb3")]
#[cfg_attr(docsrs, doc(cfg(feature = "usb3")))]
Sdk(SdkErr),
}
#[derive(Debug)]
#[non_exhaustive]
pub enum Skew {
NotKdi,
Major {
device: u16,
host: u16,
},
NotReady,
MissingCaps(Vec<Cap>),
Busy(Reply),
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Error::Device(r) => write!(
f,
"device refused: {} (rc {})",
r.err.map_or("?", DeviceErr::token),
r.rc
),
Error::Host(h) => write!(f, "{}", h.token()),
Error::Skew(s) => write!(f, "{s}"),
Error::Io(e) => write!(f, "{e}"),
#[cfg(feature = "usb3")]
Error::Sdk(e) => write!(f, "{e}"),
}
}
}
impl fmt::Display for Skew {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Skew::NotKdi => write!(
f,
"device does not speak KDI (contract_version reads 0) - flash a KDI bitstream"
),
Skew::Major { device, host } => write!(
f,
"device contract major {device}, this host needs {host} - flash the matching release"
),
Skew::NotReady => write!(
f,
"device never became contract_ready (boot/calibration window exceeded)"
),
Skew::MissingCaps(c) => {
let names: Vec<&str> = c.iter().map(|c| c.token()).collect();
write!(f, "device lacks required capabilities: {}", names.join(", "))
}
Skew::Busy(r) => write!(
f,
"device busy, held by another host ({}) - one holder at a time",
r.err.map_or("?", DeviceErr::token)
),
}
}
}
impl std::error::Error for Error {}
fn io_err(kind: io::ErrorKind, msg: impl Into<String>) -> Error {
Error::Io(io::Error::new(kind, msg.into()))
}
pub(crate) fn io_or_timeout(e: io::Error) -> Error {
match e.kind() {
io::ErrorKind::WouldBlock | io::ErrorKind::TimedOut => Error::Host(HostErr::HostTimeout),
_ => Error::Io(e),
}
}
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub enum Arg<'a> {
Int(i64),
Text(&'a str),
}
impl Arg<'_> {
fn is_safe(&self) -> bool {
match self {
Arg::Int(_) => true,
Arg::Text(t) => safe_token(t),
}
}
pub(crate) fn json(&self) -> Value {
match *self {
Arg::Int(n) => Value::from(n),
Arg::Text(t) => Value::from(t),
}
}
}
impl fmt::Display for Arg<'_> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Arg::Int(n) => write!(f, "{n}"),
Arg::Text(t) => f.write_str(t),
}
}
}
fn positional<'a>(name: &str, args: &'a [&'a str]) -> Vec<(&'a str, Arg<'a>)> {
let keys = COMMANDS
.iter()
.find(|(n, _)| *n == name)
.map(|(_, k)| *k)
.filter(|k| args.len() <= k.len())
.unwrap_or(&[]);
args.iter()
.enumerate()
.map(|(i, a)| {
let v = a.parse::<i64>().map_or(Arg::Text(a), Arg::Int);
(keys.get(i).copied().unwrap_or(""), v)
})
.collect()
}
fn safe_token(t: &str) -> bool {
!t.is_empty()
&& t.bytes()
.all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'.' || b == b'-')
}
pub fn grant_bytes(tier: &str, nonce: u32, dna: u64) -> Vec<u8> {
serde_json::json!({"dna": dna, "nonce": nonce, "tier": tier})
.to_string()
.into_bytes()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn charset_matches_spec() {
assert_eq!(ARG_CHARSET, "[A-Za-z0-9_.-]+");
assert!(safe_token("adio.mode") && safe_token("0") && safe_token("a-b_c"));
assert!(!safe_token("0\rkv power up"));
assert!(!safe_token("0\nkv"));
assert!(!safe_token("\u{1e}003{}"));
assert!(!safe_token("a b") && !safe_token(""));
}
#[test]
fn field_writes_do_not_clear_their_neighbour() {
let (run_s, run_d) = (reg("run_samples").unwrap(), reg("run_digital").unwrap());
assert_eq!(run_s.addr, run_d.addr, "both run bits share one WireIn");
let word = apply_field(0, run_d, 1);
let word = apply_field(word, run_s, 1);
assert_eq!(word, (1 << run_d.lo) | (1 << run_s.lo));
assert_eq!(apply_field(word, run_s, 0), 1 << run_d.lo);
let (b_s, b_d) = (reg("burst_samples").unwrap(), reg("burst_digital").unwrap());
assert_eq!(b_s.addr, b_d.addr, "both burst bounds share one WireIn");
let word = apply_field(apply_field(0, b_d, 0xFFFF), b_s, 8);
assert_eq!(word, (8 << b_s.lo) | 0xFFFF);
assert_eq!(apply_field(word, b_s, 0x1_0000), 0xFFFF);
}
#[test]
fn whole_word_registers_mask_the_whole_word() {
let lanes = reg("lanes_samples").unwrap();
assert_eq!(lanes.width, 32);
assert_eq!(apply_field(0xdead_beef, lanes, 0), 0);
assert_eq!(apply_field(0, lanes, u32::MAX), u32::MAX);
}
#[test]
fn caps_list_is_complete() {
for c in ALL_CAPS {
match c {
Cap::CleanFrame
| Cap::CommandProtocol
| Cap::Ddr3
| Cap::Adio
| Cap::Grounding
| Cap::TtlIn
| Cap::SlotHealth
| Cap::FieldUpdate
| Cap::RateControl => {}
}
}
assert!(ALL_CAPS.windows(2).all(|w| w[0].bit() < w[1].bit()));
let all = Caps(u32::MAX);
assert_eq!(all.iter().count(), ALL_CAPS.len());
assert_eq!(Caps(0).iter().count(), 0);
let one = Caps(1 << Cap::Ddr3.bit());
assert!(one.has(Cap::Ddr3) && !one.has(Cap::Adio));
assert_eq!(one.iter().collect::<Vec<_>>(), vec![Cap::Ddr3]);
}
#[test]
fn stream_registers_resolve_for_every_stream() {
for s in [Stream::Samples, Stream::Digital] {
let (run, burst, status, lanes) = stream_regs(s);
assert_eq!(reg(run).unwrap().kind, "wirein");
assert_eq!(reg(burst).unwrap().kind, "wirein");
assert_eq!(reg(status).unwrap().kind, "wireout");
assert_eq!(lanes.is_some(), s == Stream::Samples);
if let Some(lanes) = lanes {
assert_eq!(reg(lanes).unwrap().kind, "wirein");
}
}
}
#[test]
fn retryable_matches_the_contract() {
assert!(DeviceErr::Busy.retryable() && DeviceErr::NotReady.retryable());
assert!(!DeviceErr::NotPresent.retryable() && !DeviceErr::BadArgs.retryable());
}
}