Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

20.1 KB
Raw Blame
//! The Windows half of harness-serial: SetupAPI and CfgMgr32 find the dial, an overlapped COM handle moves its
//! bytes. Every long-running command ends at end of stdin, which is how it ends with the daemon that started it,
//! however that daemon ends (a crash, TerminateProcess, an update handoff).

use std::ffi::c_void;
use std::io::{Read, Write};
use std::sync::{Arc, mpsc};
use std::time::{Duration, Instant};

use windows_sys::Win32::Devices::Communication::{
    CLRDTR, CLRRTS, COMMTIMEOUTS, DCB, EscapeCommFunction, GetCommState, NOPARITY, ONESTOPBIT,
    SETRTS, SetCommState, SetCommTimeouts,
};
use windows_sys::Win32::Devices::DeviceAndDriverInstallation::{
    CM_Get_DevNode_PropertyW, CM_Get_Device_IDW, CM_Get_Parent, CM_NOTIFY_ACTION,
    CM_NOTIFY_EVENT_DATA, CM_NOTIFY_FILTER, CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE,
    CM_Register_Notification, CM_Unregister_Notification, CR_SUCCESS, DICS_FLAG_GLOBAL,
    DIGCF_DEVICEINTERFACE, DIGCF_PRESENT, DIREG_DEV, HCMNOTIFICATION, HDEVINFO, SP_DEVINFO_DATA,
    SetupDiDestroyDeviceInfoList, SetupDiEnumDeviceInfo, SetupDiGetClassDevsW,
    SetupDiGetDeviceInstanceIdW, SetupDiOpenDevRegKey,
};
use windows_sys::Win32::Devices::Properties::{
    DEVPKEY_Device_LastArrivalDate, DEVPROP_TYPE_FILETIME, DEVPROPTYPE,
};
use windows_sys::Win32::Foundation::{
    CloseHandle, ERROR_IO_PENDING, ERROR_NO_MORE_ITEMS, ERROR_SUCCESS, GENERIC_READ, GENERIC_WRITE,
    GetLastError, HANDLE, INVALID_HANDLE_VALUE,
};
use windows_sys::Win32::Storage::FileSystem::{
    CreateFileW, FILE_FLAG_OVERLAPPED, OPEN_EXISTING, ReadFile, WriteFile,
};
use windows_sys::Win32::System::IO::{GetOverlappedResult, OVERLAPPED};
use windows_sys::Win32::System::Ioctl::GUID_DEVINTERFACE_COMPORT;
use windows_sys::Win32::System::Registry::{KEY_READ, REG_SZ, RegCloseKey, RegQueryValueExW};
use windows_sys::Win32::System::RemoteDesktop::{
    ProcessIdToSessionId, WTSGetActiveConsoleSessionId,
};
use windows_sys::Win32::System::Threading::{CreateEventW, GetCurrentProcessId};

use crate::model::{self, Command, OpenFailure, Port, State};

pub fn run(command: Command) -> i32 {
    match command {
        Command::Watch => watch(),
        Command::Open(name) => open(&name),
        Command::Probe(name) => probe(&name),
        Command::Reset(name) => reset(&name),
        Command::Version => 0,
    }
}

// ---- finding the dial ---------------------------------------------------------------------------------------

fn wide(text: &str) -> Vec<u16> {
    text.encode_utf16().chain(Some(0)).collect()
}

fn from_wide(buffer: &[u16]) -> String {
    let end = buffer
        .iter()
        .position(|&unit| unit == 0)
        .unwrap_or(buffer.len());
    String::from_utf16_lossy(&buffer[..end])
}

fn describe(code: u32) -> String {
    std::io::Error::from_raw_os_error(code as i32).to_string()
}

struct DeviceInfo(HDEVINFO);

impl Drop for DeviceInfo {
    fn drop(&mut self) {
        unsafe { SetupDiDestroyDeviceInfoList(self.0) };
    }
}

/// Every present COM port that is the dial's serial interface, with its serial number and attachment.
fn dial_ports() -> Result<Vec<Port>, String> {
    let set: HDEVINFO = unsafe {
        SetupDiGetClassDevsW(
            &GUID_DEVINTERFACE_COMPORT,
            std::ptr::null(),
            std::ptr::null_mut(),
            DIGCF_PRESENT | DIGCF_DEVICEINTERFACE,
        )
    };
    if set == -1 {
        return Err(format!(
            "SetupDiGetClassDevsW: {}",
            describe(unsafe { GetLastError() })
        ));
    }
    let set = DeviceInfo(set);
    let mut ports = Vec::new();
    let mut index = 0;
    loop {
        let mut info: SP_DEVINFO_DATA = unsafe { std::mem::zeroed() };
        info.cbSize = std::mem::size_of::<SP_DEVINFO_DATA>() as u32;
        if unsafe { SetupDiEnumDeviceInfo(set.0, index, &mut info) } == 0 {
            let code = unsafe { GetLastError() };
            if code == ERROR_NO_MORE_ITEMS {
                break;
            }
            return Err(format!("SetupDiEnumDeviceInfo: {}", describe(code)));
        }
        index += 1;
        let mut id = [0u16; 512];
        if unsafe {
            SetupDiGetDeviceInstanceIdW(
                set.0,
                &info,
                id.as_mut_ptr(),
                id.len() as u32,
                std::ptr::null_mut(),
            )
        } == 0
        {
            continue;
        }
        if !model::is_dial_interface(&from_wide(&id)) {
            continue;
        }
        // An arrival can be reported before usbser writes PortName; `watch` looks again 500 ms later.
        let Some(path) = port_name(set.0, &info) else {
            continue;
        };
        let mut parent = 0u32;
        let (serial_number, session) =
            if unsafe { CM_Get_Parent(&mut parent, info.DevInst, 0) } == CR_SUCCESS {
                (
                    device_id(parent).and_then(|id| model::serial_from_parent(&id)),
                    last_arrival(parent),
                )
            } else {
                (None, None)
            };
        ports.push(Port {
            path,
            serial_number,
            session,
        });
    }
    Ok(ports)
}

/// `Device Parameters\PortName`, as usbser wrote it: `COM3`.
fn port_name(set: HDEVINFO, info: &SP_DEVINFO_DATA) -> Option<String> {
    let key = unsafe { SetupDiOpenDevRegKey(set, info, DICS_FLAG_GLOBAL, 0, DIREG_DEV, KEY_READ) };
    if key as isize == -1 || key.is_null() {
        return None;
    }
    let name = wide("PortName");
    let mut buffer = [0u16; 32];
    let mut size = (buffer.len() * 2) as u32;
    let mut kind = 0u32;
    let status = unsafe {
        RegQueryValueExW(
            key,
            name.as_ptr(),
            std::ptr::null(),
            &mut kind,
            buffer.as_mut_ptr() as *mut u8,
            &mut size,
        )
    };
    unsafe { RegCloseKey(key) };
    if status != ERROR_SUCCESS || kind != REG_SZ {
        return None;
    }
    let port = from_wide(&buffer).to_ascii_uppercase();
    model::is_com_name(&port).then_some(port)
}

fn device_id(devinst: u32) -> Option<String> {
    let mut buffer = [0u16; 512];
    (unsafe { CM_Get_Device_IDW(devinst, buffer.as_mut_ptr(), buffer.len() as u32, 0) }
        == CR_SUCCESS)
        .then(|| from_wide(&buffer))
}

/// The composite device's DEVPKEY_Device_LastArrivalDate: when it was last plugged in.
fn last_arrival(devinst: u32) -> Option<String> {
    let mut kind: DEVPROPTYPE = 0;
    let mut value = 0u64;
    let mut size = 8u32;
    let status = unsafe {
        CM_Get_DevNode_PropertyW(
            devinst,
            &DEVPKEY_Device_LastArrivalDate,
            &mut kind,
            &mut value as *mut u64 as *mut u8,
            &mut size,
            0,
        )
    };
    (status == CR_SUCCESS && kind == DEVPROP_TYPE_FILETIME && size == 8).then(|| value.to_string())
}

/// Whether this process's session is the one at the screen. A Remote Desktop session is not; a user switched
/// away from is not. That user's daemon releases the dial (cable/cableFleet.ts, canUseUsb).
fn at_console() -> bool {
    let mut mine = 0u32;
    unsafe {
        ProcessIdToSessionId(GetCurrentProcessId(), &mut mine) != 0
            && WTSGetActiveConsoleSessionId() == mine
    }
}

// ---- watch --------------------------------------------------------------------------------------------------

/// The CLI scans every 2 s; reading the console that often costs one call into the kernel.
const CONSOLE_EVERY: Duration = Duration::from_secs(2);
/// An arrival can come before usbser writes PortName.
const LOOK_AGAIN_AFTER: Duration = Duration::from_millis(500);
/// A missed notification is caught within this, as macOS's DIAL_RESCAN_MS.
const SAFETY_NET: Duration = Duration::from_secs(300);

struct Notification(HCMNOTIFICATION);

impl Drop for Notification {
    fn drop(&mut self) {
        unsafe { CM_Unregister_Notification(self.0) };
    }
}

unsafe extern "system" fn on_change(
    _notification: HCMNOTIFICATION,
    context: *const c_void,
    _action: CM_NOTIFY_ACTION,
    _data: *const CM_NOTIFY_EVENT_DATA,
    _size: u32,
) -> u32 {
    // The context is the leaked Sender below; it lives for the whole process.
    let sender = unsafe { &*(context as *const mpsc::Sender<()>) };
    let _ = sender.send(());
    ERROR_SUCCESS
}

/// Arrivals and removals of any COM port interface. Called back on a system thread.
fn notify_changes(sender: mpsc::Sender<()>) -> Result<Notification, String> {
    let context: &'static mpsc::Sender<()> = Box::leak(Box::new(sender));
    let mut filter: CM_NOTIFY_FILTER = unsafe { std::mem::zeroed() };
    filter.cbSize = std::mem::size_of::<CM_NOTIFY_FILTER>() as u32;
    filter.FilterType = CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE;
    filter.u.DeviceInterface.ClassGuid = GUID_DEVINTERFACE_COMPORT;
    let mut handle: HCMNOTIFICATION = std::ptr::null_mut();
    let status = unsafe {
        CM_Register_Notification(
            &filter,
            context as *const mpsc::Sender<()> as *const c_void,
            Some(on_change),
            &mut handle,
        )
    };
    if status != CR_SUCCESS {
        return Err(format!("CM_Register_Notification failed ({status})"));
    }
    Ok(Notification(handle))
}

/// End the process at end of stdin: the daemon closed the pipe, or the daemon is gone.
fn exit_at_end_of_stdin() {
    std::thread::spawn(|| {
        let mut sink = [0u8; 256];
        let mut stdin = std::io::stdin().lock();
        loop {
            match stdin.read(&mut sink) {
                Ok(0) | Err(_) => std::process::exit(0),
                Ok(_) => {}
            }
        }
    });
}

fn print_line(line: &str) -> bool {
    let mut out = std::io::stdout().lock();
    writeln!(out, "{line}").and_then(|_| out.flush()).is_ok()
}

fn watch() -> i32 {
    exit_at_end_of_stdin();
    let (sender, changes) = mpsc::channel();
    let _notification = match notify_changes(sender) {
        Ok(notification) => notification,
        Err(why) => {
            eprintln!("error: {why}");
            return model::EXIT_FAILED;
        }
    };
    let mut ports = match dial_ports() {
        Ok(ports) => ports,
        Err(why) => {
            eprintln!("error: {why}");
            return model::EXIT_FAILED;
        }
    };
    let mut looked = Instant::now();
    let mut again: Option<Instant> = None;
    let mut printed: Option<String> = None;
    loop {
        let line = State {
            console: at_console(),
            ports: ports.clone(),
        }
        .line();
        if printed.as_deref() != Some(line.as_str()) {
            if !print_line(&line) {
                return 0; // nobody is reading
            }
            printed = Some(line);
        }
        let wait = again.map_or(CONSOLE_EVERY, |at| {
            at.saturating_duration_since(Instant::now())
                .min(CONSOLE_EVERY)
        });
        let changed = match changes.recv_timeout(wait) {
            Ok(()) => {
                while changes.try_recv().is_ok() {}
                again = Some(Instant::now() + LOOK_AGAIN_AFTER);
                true
            }
            Err(mpsc::RecvTimeoutError::Timeout) => false,
            Err(mpsc::RecvTimeoutError::Disconnected) => return 0,
        };
        let due = again.is_some_and(|at| Instant::now() >= at);
        if due {
            again = None;
        }
        if changed || due || looked.elapsed() >= SAFETY_NET {
            match dial_ports() {
                Ok(next) => {
                    ports = next;
                    looked = Instant::now();
                }
                Err(why) => {
                    eprintln!("error: {why}");
                    return model::EXIT_FAILED;
                }
            }
        }
    }
}

// ---- open and probe -----------------------------------------------------------------------------------------

struct ComPort(HANDLE);

// The handle is used from the reader thread and the writer thread at once, which overlapped I/O allows.
unsafe impl Send for ComPort {}
unsafe impl Sync for ComPort {}

impl Drop for ComPort {
    fn drop(&mut self) {
        unsafe { CloseHandle(self.0) };
    }
}

/// Share mode 0: a COM port is exclusive, and asking for that makes another program's open the error we see.
fn create(name: &str) -> Result<ComPort, u32> {
    let path = wide(&model::device_path(name));
    let handle = unsafe {
        CreateFileW(
            path.as_ptr(),
            GENERIC_READ | GENERIC_WRITE,
            0,
            std::ptr::null(),
            OPEN_EXISTING,
            FILE_FLAG_OVERLAPPED,
            std::ptr::null_mut(),
        )
    };
    if handle == INVALID_HANDLE_VALUE {
        Err(unsafe { GetLastError() })
    } else {
        Ok(ComPort(handle))
    }
}

fn refuse(code: u32) -> i32 {
    match model::open_failure(code) {
        OpenFailure::Busy => {
            eprintln!("busy");
            model::EXIT_BUSY
        }
        OpenFailure::Gone => {
            eprintln!("gone");
            model::EXIT_GONE
        }
        OpenFailure::Other => {
            eprintln!("error: {}", describe(code));
            model::EXIT_CLOSED
        }
    }
}

/// Raw, with DTR/RTS set together in this one call (model::DCB_RAW says why). Reads return as soon as any
/// byte is there, or after 1 s with none, so the reader wakes once a second at most while the dial is quiet.
fn configure(port: &ComPort) -> Result<(), String> {
    let mut dcb: DCB = unsafe { std::mem::zeroed() };
    dcb.DCBlength = std::mem::size_of::<DCB>() as u32;
    if unsafe { GetCommState(port.0, &mut dcb) } == 0 {
        return Err(format!(
            "GetCommState: {}",
            describe(unsafe { GetLastError() })
        ));
    }
    dcb.BaudRate = 115_200; // USB-Serial/JTAG ignores it; a driver that checks it gets a real one
    dcb._bitfield = model::DCB_RAW;
    dcb.ByteSize = 8;
    dcb.Parity = NOPARITY;
    dcb.StopBits = ONESTOPBIT;
    if unsafe { SetCommState(port.0, &dcb) } == 0 {
        return Err(format!(
            "SetCommState: {}",
            describe(unsafe { GetLastError() })
        ));
    }
    let timeouts = COMMTIMEOUTS {
        ReadIntervalTimeout: u32::MAX,
        ReadTotalTimeoutMultiplier: u32::MAX,
        ReadTotalTimeoutConstant: 1000,
        WriteTotalTimeoutMultiplier: 0,
        WriteTotalTimeoutConstant: 0,
    };
    if unsafe { SetCommTimeouts(port.0, &timeouts) } == 0 {
        return Err(format!(
            "SetCommTimeouts: {}",
            describe(unsafe { GetLastError() })
        ));
    }
    Ok(())
}

struct Event(HANDLE);

impl Event {
    fn new() -> Event {
        let handle = unsafe { CreateEventW(std::ptr::null(), 1, 0, std::ptr::null()) };
        if handle.is_null() {
            closed(unsafe { GetLastError() });
        }
        Event(handle)
    }
}

impl Drop for Event {
    fn drop(&mut self) {
        unsafe { CloseHandle(self.0) };
    }
}

/// One overlapped ReadFile or WriteFile, waited for. Ok(bytes) or Err(the Windows error).
fn overlapped(
    port: &ComPort,
    event: &Event,
    start: impl FnOnce(*mut OVERLAPPED) -> i32,
) -> Result<u32, u32> {
    let mut request: OVERLAPPED = unsafe { std::mem::zeroed() };
    request.hEvent = event.0;
    if start(&mut request) == 0 {
        let code = unsafe { GetLastError() };
        if code != ERROR_IO_PENDING {
            return Err(code);
        }
    }
    let mut done = 0u32;
    if unsafe { GetOverlappedResult(port.0, &request, &mut done, 1) } == 0 {
        return Err(unsafe { GetLastError() });
    }
    Ok(done)
}

fn closed(code: u32) -> ! {
    eprintln!("closed: {}", describe(code));
    std::process::exit(model::EXIT_CLOSED)
}

/// Port to stdout until the port fails (an unplug: the process ends, exit 5).
fn pump_out(port: &ComPort) {
    let event = Event::new();
    let mut buffer = vec![0u8; 16 * 1024];
    let mut stdout = std::io::stdout().lock();
    loop {
        let into = buffer.as_mut_ptr();
        let size = buffer.len() as u32;
        match overlapped(port, &event, |request| unsafe {
            ReadFile(port.0, into, size, std::ptr::null_mut(), request)
        }) {
            Ok(0) => {} // a quiet second
            Ok(read) => {
                if stdout
                    .write_all(&buffer[..read as usize])
                    .and_then(|_| stdout.flush())
                    .is_err()
                {
                    std::process::exit(0); // nobody is reading
                }
            }
            Err(code) => closed(code),
        }
    }
}

/// Read stdin independently of a possibly stalled COM write: EOF must release the port even then.
/// As for watch, process exit closes all handles and outstanding I/O without a cancellation race.
fn stdin_chunks() -> mpsc::Receiver<Vec<u8>> {
    let (sender, incoming) = mpsc::channel();
    std::thread::spawn(move || {
        let mut buffer = [0u8; 16 * 1024];
        let mut stdin = std::io::stdin().lock();
        loop {
            match stdin.read(&mut buffer) {
                Ok(0) | Err(_) => std::process::exit(0),
                Ok(read) => {
                    if sender.send(buffer[..read].to_vec()).is_err() {
                        return;
                    }
                }
            }
        }
    });
    incoming
}

/// Write each stdin chunk whole before the next; EOF closes the process independently of writer progress.
fn pump_in(port: &ComPort, incoming: mpsc::Receiver<Vec<u8>>) {
    let event = Event::new();
    for buffer in incoming {
        let read = buffer.len();
        let mut sent = 0;
        while sent < read {
            let chunk = &buffer[sent..read];
            match overlapped(port, &event, |request| unsafe {
                WriteFile(
                    port.0,
                    chunk.as_ptr(),
                    chunk.len() as u32,
                    std::ptr::null_mut(),
                    request,
                )
            }) {
                Ok(0) => closed(1167), // nothing taken: the device is not there
                Ok(written) => sent += written as usize,
                Err(code) => closed(code),
            }
        }
    }
}

fn open(name: &str) -> i32 {
    let port = match create(name) {
        Ok(port) => port,
        Err(code) => return refuse(code),
    };
    if let Err(why) = configure(&port) {
        eprintln!("error: {why}");
        return model::EXIT_CLOSED;
    }
    eprintln!("open");
    let port = Arc::new(port);
    {
        let port = port.clone();
        std::thread::spawn(move || pump_out(&port));
    }
    pump_in(&port, stdin_chunks());
    0
}

/// Reset a board over its cable, the pulse esptool calls a hard reset (cli cable/boardReset.ts): RTS high with DTR low
/// holds the chip in reset, then both low let it boot normally. DTR stays low throughout, as high would ask for the
/// ROM's download mode.
fn reset(name: &str) -> i32 {
    let port = match create(name) {
        Ok(port) => port,
        Err(code) => {
            return match model::open_failure(code) {
                OpenFailure::Busy => model::EXIT_BUSY,
                OpenFailure::Gone => model::EXIT_GONE,
                OpenFailure::Other => {
                    eprintln!("error: {}", describe(code));
                    model::EXIT_CLOSED
                }
            };
        }
    };
    if let Err(why) = configure(&port) {
        eprintln!("error: {why}");
        return model::EXIT_CLOSED;
    }
    let lines = |function| unsafe { EscapeCommFunction(port.0, function) } != 0;
    if !lines(CLRDTR) || !lines(SETRTS) {
        return model::EXIT_CLOSED;
    }
    std::thread::sleep(Duration::from_millis(200));
    if !lines(CLRRTS) {
        return model::EXIT_CLOSED;
    }
    std::thread::sleep(Duration::from_millis(200));
    0
}

/// Whether another program holds the port: configure it exactly as open does, then close without moving bytes.
fn probe(name: &str) -> i32 {
    match create(name) {
        Ok(port) => {
            if let Err(why) = configure(&port) {
                eprintln!("error: {why}");
                return model::EXIT_CLOSED;
            }
            0
        }
        Err(code) => match model::open_failure(code) {
            OpenFailure::Busy => model::EXIT_BUSY,
            OpenFailure::Gone => model::EXIT_GONE,
            OpenFailure::Other => {
                eprintln!("error: {}", describe(code));
                model::EXIT_CLOSED
            }
        },
    }
}