use std::ffi::{c_char, c_int, c_long, c_uchar, c_ulong, c_void, CStr, CString};
use std::fmt;
use std::fmt::Write as _;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
use libloading::Library;
use serde_json::{json, Value};
use crate::{
io_err, reg, reply_from, stream_regs, Addr, DeviceInfo, Error, HostErr, RegBind, Reply, Stream,
TransportKind, RESP_LEN_DIGITS, RESP_SENTINEL, USB3_MSG, USB3_READ_ALIGNMENT, USB3_STREAM,
};
#[derive(Debug)]
pub struct SdkErr(pub String);
impl fmt::Display for SdkErr {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "device driver: {}", self.0)
}
}
fn sdk(msg: impl Into<String>) -> Error {
Error::Sdk(SdkErr(msg.into()))
}
const DRIVER_DIR_ENV: &str = "KDI_DRIVER_DIR";
type Handle = *mut c_void;
const OK_NO_ERROR: c_int = 0;
struct Fp {
devices_construct: unsafe extern "C" fn(*const c_char, *mut c_void) -> Handle,
devices_destruct: unsafe extern "C" fn(Handle),
devices_get_count: unsafe extern "C" fn(Handle) -> c_int,
devices_get_serial: unsafe extern "C" fn(Handle, c_int, *mut c_char),
devices_open: unsafe extern "C" fn(Handle, *const c_char) -> Handle,
destruct: unsafe extern "C" fn(Handle),
close: unsafe extern "C" fn(Handle),
configure_from_memory: Option<unsafe extern "C" fn(Handle, *const c_uchar, c_ulong) -> c_int>,
get_data_port: unsafe extern "C" fn(Handle, *mut Handle) -> c_int,
update_wire_outs: unsafe extern "C" fn(Handle) -> c_int,
get_wire_out_value: unsafe extern "C" fn(Handle, c_int) -> u32,
set_wire_in_value: unsafe extern "C" fn(Handle, c_int, u32, u32) -> c_int,
update_wire_ins: unsafe extern "C" fn(Handle) -> c_int,
activate_trigger_in: unsafe extern "C" fn(Handle, c_int, c_int) -> c_int,
read_from_pipe_out: unsafe extern "C" fn(Handle, c_int, c_long, *mut u8) -> c_long,
read_from_block_pipe_out: unsafe extern "C" fn(Handle, c_int, c_int, c_long, *mut u8) -> c_long,
_lib: Library,
}
unsafe fn sym<T: Copy>(lib: &Library, name: &str) -> Result<T, Error> {
let s: libloading::Symbol<T> = lib
.get(CString::new(name).unwrap().as_bytes_with_nul())
.map_err(|_| sdk(name))?;
Ok(*s)
}
impl Fp {
fn load(driver_dir: Option<&Path>) -> Result<Fp, Error> {
let names: &[&str] = if cfg!(target_os = "windows") {
&["okFrontPanel.dll"]
} else if cfg!(target_os = "macos") {
&["libokFrontPanel.dylib"]
} else {
&["libokFrontPanel.so"]
};
let staged: &[&str] = if cfg!(target_os = "windows") {
&["kdi_driver.dll"]
} else if cfg!(target_os = "macos") {
&["libkdi_driver.dylib"]
} else {
&["libkdi_driver.so"]
};
let mut dirs: Vec<PathBuf> = driver_dir.into_iter().map(PathBuf::from).collect();
if let Some(p) = std::env::var_os(DRIVER_DIR_ENV) {
dirs.extend(std::env::split_paths(&p));
}
let mut tried = Vec::new();
let lib = 'found: {
for d in &dirs {
for n in names.iter().chain(staged.iter()) {
let path = d.join(n);
match unsafe { Library::new(&path) } {
Ok(l) => break 'found l,
Err(_) => tried.push(d.display().to_string()),
}
}
}
#[cfg(feature = "bundled")]
{
let path = crate::bundled::staged_path().map_err(|e| {
io_err(
e.kind(),
format!(
"the bundled device driver could not be unpacked: {e}. Set \
${DRIVER_DIR_ENV} to a directory holding the driver to bypass it."
),
)
})?;
match unsafe { Library::new(&path) } {
Ok(l) => break 'found l,
Err(_) => tried.push(format!(
"{} (embedded copy)",
path.parent().unwrap_or(path.as_path()).display()
)),
}
}
for n in names {
match unsafe { Library::new(n) } {
Ok(l) => break 'found l,
Err(_) => tried.push("the OS search path".into()),
}
}
return Err(io_err(
std::io::ErrorKind::NotFound,
format!(
"no device driver loaded (set ${DRIVER_DIR_ENV} to the directory holding it); \
tried {}",
tried.join("; ")
),
));
};
unsafe {
Ok(Fp {
devices_construct: sym(&lib, "okFrontPanelDevices_Construct")?,
devices_destruct: sym(&lib, "okFrontPanelDevices_Destruct")?,
devices_get_count: sym(&lib, "okFrontPanelDevices_GetCount")?,
devices_get_serial: sym(&lib, "okFrontPanelDevices_GetSerial")?,
devices_open: sym(&lib, "okFrontPanelDevices_Open")?,
destruct: sym(&lib, "okFrontPanel_Destruct")?,
close: sym(&lib, "okFrontPanel_Close")?,
configure_from_memory: sym(&lib, "okFrontPanel_ConfigureFPGAFromMemory").ok(),
get_data_port: sym(&lib, "okFrontPanel_GetFPGADataPortClassic")?,
update_wire_outs: sym(&lib, "okFPGADataPortClassic_UpdateWireOuts")?,
get_wire_out_value: sym(&lib, "okFPGADataPortClassic_GetWireOutValue")?,
set_wire_in_value: sym(&lib, "okFPGADataPortClassic_SetWireInValue")?,
update_wire_ins: sym(&lib, "okFPGADataPortClassic_UpdateWireIns")?,
activate_trigger_in: sym(&lib, "okFPGADataPortClassic_ActivateTriggerIn")?,
read_from_pipe_out: sym(&lib, "okFPGADataPortClassic_ReadFromPipeOut")?,
read_from_block_pipe_out: sym(&lib, "okFPGADataPortClassic_ReadFromBlockPipeOut")?,
_lib: lib,
})
}
}
}
impl Fp {
unsafe fn devices(&self) -> Result<Handle, Error> {
let h = unsafe { (self.devices_construct)(c"".as_ptr(), std::ptr::null_mut()) };
if h.is_null() {
return Err(sdk("the device manager could not be constructed"));
}
Ok(h)
}
fn close_device(&self, hnd: Handle) {
unsafe {
(self.close)(hnd);
(self.destruct)(hnd);
}
}
}
pub(crate) struct Usb3 {
fp: Fp,
hnd: Handle,
port: Handle,
serial: String,
console: Vec<u8>,
}
impl Usb3 {
pub(crate) fn open(
serial: &str,
driver_dir: Option<&Path>,
image: Option<&[u8]>,
) -> Result<Usb3, Error> {
let image = match image {
Some([]) => {
return Err(io_err(
std::io::ErrorKind::InvalidInput,
"empty gateware image",
))
}
Some(img) => Some((
img,
img.len().try_into().map_err(|_| {
io_err(
std::io::ErrorKind::InvalidInput,
"gateware image is too large to send",
)
})?,
)),
None => None,
};
let c = CString::new(serial)
.map_err(|_| io_err(std::io::ErrorKind::InvalidInput, "serial contains a NUL"))?;
let fp = Fp::load(driver_dir)?;
let devs = unsafe { fp.devices()? };
let hnd = unsafe { (fp.devices_open)(devs, c.as_ptr()) };
unsafe { (fp.devices_destruct)(devs) };
if hnd.is_null() {
return Err(sdk(format!("opening device {serial:?} returned no handle")));
}
if let Some((img, len)) = image {
let Some(configure) = fp.configure_from_memory else {
fp.close_device(hnd);
return Err(sdk(
"this device driver cannot configure a device from memory; \
bind an already-configured board with open_usb3 instead",
));
};
let rc = unsafe { configure(hnd, img.as_ptr().cast::<c_uchar>(), len) };
if rc != OK_NO_ERROR {
fp.close_device(hnd);
return Err(sdk(format!(
"configuring the device with a {} byte gateware image failed (rc = {rc}); \
the board is still running whatever was resident",
img.len()
)));
}
}
let mut port: Handle = std::ptr::null_mut();
let rc = unsafe { (fp.get_data_port)(hnd, &mut port) };
if port.is_null() {
fp.close_device(hnd);
return Err(sdk(format!(
"the device exposes no classic data port (rc = {rc})"
)));
}
Ok(Usb3 {
fp,
hnd,
port,
serial: serial.to_string(),
console: Vec::new(),
})
}
pub(crate) fn identity(&self) -> Value {
json!({"serial": self.serial, "transport": "usb3"})
}
pub(crate) fn reg_read(&mut self, r: RegBind) -> Result<u32, Error> {
let rc = unsafe { (self.fp.update_wire_outs)(self.port) };
if rc != OK_NO_ERROR {
return Err(sdk(format!("register-block read failed (rc = {rc})")));
}
let v = unsafe { (self.fp.get_wire_out_value)(self.port, c_int::from(r.addr)) };
Ok((v & r.mask()) >> r.lo)
}
pub(crate) fn reg_write(&mut self, r: RegBind, word: u32) -> Result<(), Error> {
match r.kind {
"wirein" => {
let rc = unsafe {
(self.fp.set_wire_in_value)(self.port, c_int::from(r.addr), word, u32::MAX)
};
if rc != OK_NO_ERROR {
return Err(sdk(format!(
"register 0x{:02x} write failed (rc = {rc})",
r.addr
)));
}
let rc = unsafe { (self.fp.update_wire_ins)(self.port) };
if rc != OK_NO_ERROR {
return Err(sdk(format!("register-block write failed (rc = {rc})")));
}
Ok(())
}
"triggerin" => self.trigger(r.addr, r.lo),
k => Err(io_err(
std::io::ErrorKind::InvalidInput,
format!("{k} endpoints are not writable"),
)),
}
}
fn trigger(&mut self, addr: u8, bit: u8) -> Result<(), Error> {
let rc = unsafe {
(self.fp.activate_trigger_in)(self.port, c_int::from(addr), c_int::from(bit))
};
if rc != OK_NO_ERROR {
return Err(sdk(format!(
"trigger 0x{addr:02x}.{bit} failed (rc = {rc})"
)));
}
Ok(())
}
pub(crate) fn stream_read(&mut self, s: Stream, buf: &mut [u8]) -> Result<usize, Error> {
let (kind, addr) = stream_ep(s)?;
let avail = self.reg_read(reg(stream_regs(s).2)?)? & 0xFFFF;
let mut n = (avail as usize * 4).min(buf.len());
n -= n % USB3_READ_ALIGNMENT;
if n == 0 {
return Ok(0);
}
let rc = if kind.eq_ignore_ascii_case("okbtpipeout") {
unsafe {
(self.fp.read_from_block_pipe_out)(
self.port,
c_int::from(addr),
USB3_READ_ALIGNMENT as c_int,
n as c_long,
buf.as_mut_ptr(),
)
}
} else {
unsafe {
(self.fp.read_from_pipe_out)(
self.port,
c_int::from(addr),
n as c_long,
buf.as_mut_ptr(),
)
}
};
if rc < 0 {
return Err(sdk(format!("stream pipe 0x{addr:02x} read {n} = {rc}")));
}
let got = rc as usize;
if got < n {
return Err(Error::Host(HostErr::HostShortRead));
}
Ok(got.min(buf.len()))
}
pub(crate) fn message(
&mut self,
id: &str,
name: &str,
args: &[(&str, crate::Arg<'_>)],
_token: &str,
) -> Result<Reply, Error> {
let line = request_line(id, name, args);
self.drain()?;
self.console.clear();
self.send(&line, Duration::from_secs(2))?;
let worst = crate::spec::WORST_MS
.iter()
.find(|(n, _)| *n == name)
.map_or(0, |(_, ms)| *ms);
let deadline = Instant::now() + Duration::from_millis(4_000.max(2 * worst));
let mut scanned = 0usize;
loop {
let got = self.drain()?;
if got == 0 {
if Instant::now() >= deadline {
return Err(Error::Host(HostErr::HostTimeout));
}
std::thread::sleep(Duration::from_millis(2));
continue;
}
while let Some((v, end)) = next_frame(&self.console, scanned) {
scanned = end;
if let Ok(r) = reply_from(v) {
if r.id == id {
return Ok(r);
}
}
}
}
}
fn send(&mut self, s: &str, timeout: Duration) -> Result<(), Error> {
let rx_data = msg_ep("rx_data")?;
let rx_count = msg_ep("rx_count")?;
let rx_push = msg_ep("rx_push")?;
let deadline = Instant::now() + timeout;
for chunk in s.as_bytes().chunks(4) {
loop {
if self.status()? >> 16 >= chunk.len() as u32 {
break;
}
if Instant::now() >= deadline {
return Err(Error::Host(HostErr::HostTimeout));
}
std::thread::sleep(Duration::from_millis(2));
}
let word = chunk
.iter()
.enumerate()
.fold(0u32, |w, (i, b)| w | u32::from(*b) << (8 * i));
self.reg_write(rx_data, word)?;
self.reg_write(rx_count, chunk.len() as u32)?;
self.trigger(rx_push.addr, rx_push.lo)?;
}
Ok(())
}
fn status(&mut self) -> Result<u32, Error> {
self.reg_read(msg_ep("status")?)
}
fn drain(&mut self) -> Result<usize, Error> {
let words = self.status()? & 0xFFFF;
if words == 0 {
return Ok(0);
}
let tx = msg_ep("tx_pipe")?;
let want =
(words.min(256) as usize * 4).div_ceil(USB3_READ_ALIGNMENT) * USB3_READ_ALIGNMENT;
let mut raw = vec![0u8; want];
let rc = unsafe {
(self.fp.read_from_pipe_out)(
self.port,
c_int::from(tx.addr),
want as c_long,
raw.as_mut_ptr(),
)
};
if rc < 0 {
return Err(sdk(format!("console pipe 0x{:02x} read = {rc}", tx.addr)));
}
if rc % 4 != 0 {
return Err(sdk(format!(
"console pipe 0x{:02x} read = {rc} (not a whole number of words)",
tx.addr
)));
}
let mut n = 0;
for w in raw[..(rc as usize).min(raw.len())].chunks_exact(4) {
let cnt = (w[0] as usize).min(3);
self.console.extend_from_slice(&w[1..1 + cnt]);
n += cnt;
}
Ok(n)
}
}
impl Drop for Usb3 {
fn drop(&mut self) {
self.fp.close_device(self.hnd);
}
}
fn next_frame(cap: &[u8], from: usize) -> Option<(Value, usize)> {
let mut i = from.min(cap.len());
while let Some(rel) = cap[i..].iter().position(|b| *b == RESP_SENTINEL) {
let at = i + rel;
let body_at = at + 1 + RESP_LEN_DIGITS;
if body_at > cap.len() {
return None; }
let len = std::str::from_utf8(&cap[at + 1..body_at])
.ok()
.and_then(|s| usize::from_str_radix(s, 16).ok());
if let Some(len) = len {
if body_at + len > cap.len() {
return None; }
if let Ok(v) = serde_json::from_slice::<Value>(&cap[body_at..body_at + len]) {
return Some((v, body_at + len));
}
}
i = at + 1;
}
None
}
fn stream_ep(s: Stream) -> Result<(&'static str, u8), Error> {
USB3_STREAM
.iter()
.find(|(n, ..)| *n == s.token())
.map(|&(_, kind, addr)| (kind, addr))
.ok_or_else(|| {
io_err(
std::io::ErrorKind::InvalidInput,
format!("the usb3 binding maps no stream {}", s.token()),
)
})
}
fn msg_ep(role: &str) -> Result<RegBind, Error> {
USB3_MSG
.iter()
.find(|(r, ..)| *r == role)
.map(|&(_, kind, addr, bit)| RegBind {
kind,
addr,
lo: bit.unwrap_or(0),
width: if bit.is_some() { 1 } else { 32 },
})
.ok_or_else(|| {
io_err(
std::io::ErrorKind::InvalidInput,
format!("the usb3 message channel declares no {role} endpoint"),
)
})
}
pub(crate) fn enumerate() -> Result<Vec<DeviceInfo>, Error> {
let fp = match Fp::load(None) {
Ok(fp) => fp,
Err(Error::Io(e)) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
Err(e) => return Err(e),
};
let hnd = unsafe { fp.devices()? };
let n = unsafe { (fp.devices_get_count)(hnd) };
let mut out = Vec::new();
for i in 0..n.max(0) {
let mut raw = [0 as c_char; 32];
unsafe { (fp.devices_get_serial)(hnd, i, raw.as_mut_ptr()) };
let serial = unsafe { CStr::from_ptr(raw.as_ptr()) }
.to_string_lossy()
.into_owned();
out.push(DeviceInfo {
serial: serial.clone(),
vendor: String::new(),
compatible: String::new(),
board_id: None,
kdi: None,
transport: TransportKind::Usb3,
addr: Addr::Serial(serial),
});
}
unsafe { (fp.devices_destruct)(hnd) };
Ok(out)
}
fn request_line(id: &str, name: &str, args: &[(&str, crate::Arg<'_>)]) -> String {
let mut line = String::from(crate::REQ_TAG);
line.push_str(id);
line.push(' ');
line.push_str(name);
for (_, a) in args {
line.push(' ');
let _ = write!(line, "{a}");
}
line.push('\r');
line
}
#[cfg(test)]
mod tests {
use crate::Arg::{Int, Text};
#[test]
fn the_line_carries_the_values_positionally_and_drops_the_names() {
let args = [
("bus", Text("module")),
("ch", Int(0)),
("addr", Int(0x52)),
("data", Text("02")),
];
assert_eq!(
super::request_line("7", "x.y", &args),
"kdi 7 x.y module 0 82 02\r"
);
let swapped = [args[1], args[0], args[2], args[3]];
assert_ne!(
super::request_line("7", "x.y", &swapped),
super::request_line("7", "x.y", &args)
);
assert_eq!(
super::request_line("1", "sys.hello", &[]),
"kdi 1 sys.hello\r"
);
}
#[test]
fn an_empty_image_is_rejected_before_the_driver_is_loaded() {
let Err(crate::Error::Io(e)) = super::Usb3::open("", None, Some(&[])) else {
panic!("an empty image reached the device driver");
};
assert_eq!(e.kind(), std::io::ErrorKind::InvalidInput);
assert!(e.to_string().contains("empty"));
}
}