services/usb-device-xous: implement HIDv2 device

Allows apps to expose HID devices from userspace.

Documentation coming soon.
This commit is contained in:
Gianguido Sora 2023-12-26 18:37:41 +01:00
parent b62912914b
commit 26740a44f6
7 changed files with 378 additions and 26 deletions

25
Cargo.lock generated
View file

@ -1889,9 +1889,9 @@ dependencies = [
[[package]]
name = "frunk_core"
version = "0.4.0"
version = "0.4.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1246cf43ec80bf8b2505b5c360b8fb999c97dabd17dbb604d85558d5cbc25482"
checksum = "af2469fab0bd07e64ccf0ad57a1438f63160c69b2e57f04a439653d68eb558d6"
[[package]]
name = "frunk_derives"
@ -2299,6 +2299,24 @@ dependencies = [
"pkg-config",
]
[[package]]
name = "hidv2"
version = "0.1.0"
dependencies = [
"gam",
"graphics-server",
"locales",
"log",
"num-derive",
"num-traits",
"tts-frontend",
"usb-device-xous",
"xous 0.9.55 (registry+https://github.com/rust-lang/crates.io-index)",
"xous-api-log",
"xous-api-names",
"xous-ipc 0.9.55 (registry+https://github.com/rust-lang/crates.io-index)",
]
[[package]]
name = "hkdf"
version = "0.11.0"
@ -5274,6 +5292,7 @@ version = "0.1.0"
dependencies = [
"bitfield",
"embedded-time",
"fugit",
"ghostfat",
"keyboard",
"llio",
@ -6283,7 +6302,7 @@ dependencies = [
[[package]]
name = "xous-usb-hid"
version = "0.4.3"
source = "git+https://github.com/betrusted-io/xous-usb-hid.git#eba35e886d08e504cf10026221aec0fbfc63e201"
source = "git+https://github.com/betrusted-io/xous-usb-hid.git#793ec00243c525f2d17dc1d3a185abdeec57aaf6"
dependencies = [
"frunk",
"fugit",

View file

@ -39,6 +39,7 @@ usbd_mass_storage = { path = "../../libs/mass-storage/usbd_mass_storage", option
usbd-serial = "0.1.1"
ghostfat = "0.5.0"
fugit = "0.3.7"
[dependencies.usb-device]
# see top level Cargo.toml for patch.crates-io directive to help with dev work

View file

@ -59,6 +59,19 @@ pub(crate) enum Opcode {
#[cfg(feature="mass-storage")]
ResetBlockDevice = 1026,
// HIDv2
/// Read a HID report
HIDReadReport = 1027,
/// Write a HID report
HIDWriteReport = 1028,
/// Set the HID descriptor to be pushed to the USB host
HIDSetDescriptor = 1029,
/// Unset HID descriptor and reset HIDv2 state
HIDUnsetDescriptor = 1030,
/// Handle the USB interrupt
UsbIrqHandler = 2048,
/// Suspend/resume callback
@ -107,8 +120,10 @@ pub enum UsbDeviceType {
#[cfg(feature="mass-storage")]
MassStorage = 3,
Serial = 4,
HIDv2 = 5,
}
use std::convert::TryFrom;
impl TryFrom<usize> for UsbDeviceType {
type Error = &'static str;
@ -120,6 +135,7 @@ impl TryFrom<usize> for UsbDeviceType {
#[cfg(feature="mass-storage")]
3 => Ok(UsbDeviceType::MassStorage),
4 => Ok(UsbDeviceType::Serial),
5 => Ok(UsbDeviceType::HIDv2),
_ => Err("Invalid UsbDeviceType specifier"),
}
}
@ -138,3 +154,26 @@ pub struct UsbSerialBinary {
pub d: [u8; SERIAL_BINARY_BUFLEN],
pub len: usize,
}
pub const MAX_HID_REPORT_DESCRIPTOR_LEN: usize = 1024;
#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize, Copy, Clone)]
pub struct HIDReportDescriptorMessage {
pub descriptor: [u8; MAX_HID_REPORT_DESCRIPTOR_LEN],
pub len: usize,
}
#[derive(Copy, Clone, Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)]
pub struct HIDReport(pub [u8; 64]);
impl Default for HIDReport {
fn default() -> Self {
return Self([0u8; 64])
}
}
#[derive(Debug, Default, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize, Copy, Clone)]
pub struct HIDReportMessage {
pub data: HIDReport,
pub has_data: bool,
}

View file

@ -0,0 +1,91 @@
use usb_device::class_prelude::{UsbBus, UsbBusAllocator};
use xous_usb_hid::{
device::DeviceClass,
interface::{
HeapInterface, HeapInterfaceBuilder, HeapInterfaceConfig, InBytes64, OutBytes64,
ReportSingle, UsbAllocatable,
},
UsbHidError,
};
use crate::api::HIDReport;
use fugit::ExtU32;
pub struct AppHID<'a, B: UsbBus> {
interface: HeapInterface<'a, B, InBytes64, OutBytes64, ReportSingle>,
}
impl<'a, B: UsbBus> AppHID<'a, B> {
pub fn write_report(&mut self, report: &HIDReport) -> Result<(), UsbHidError> {
self.interface
.write_report(&report.0)
.map(|_| ())
.map_err(UsbHidError::from)
}
pub fn read_report(&mut self) -> usb_device::Result<HIDReport> {
let mut report = HIDReport::default();
match self.interface.read_report(&mut report.0) {
Err(e) => Err(e),
Ok(_) => Ok(report),
}
}
pub fn set_device_descriptor(
&mut self,
descriptor: Vec<u8>,
) -> Result<(), usb_device::UsbError> {
self.interface.set_report_descriptor(descriptor)
}
}
impl<'a, B: UsbBus> DeviceClass<'a> for AppHID<'a, B> {
type I = HeapInterface<'a, B, InBytes64, OutBytes64, ReportSingle>;
fn interface(&mut self) -> &mut Self::I {
&mut self.interface
}
fn reset(&mut self) {}
fn tick(&mut self) -> Result<(), UsbHidError> {
Ok(())
}
}
pub struct AppHIDConfig<'a> {
interface: HeapInterfaceConfig<'a, InBytes64, OutBytes64, ReportSingle>,
}
impl<'a> Default for AppHIDConfig<'a> {
#[must_use]
fn default() -> Self {
let iface = HeapInterfaceBuilder::new(vec![0])
.unwrap()
.description("Xous HID application")
.in_endpoint(5.millis())
.unwrap()
.with_out_endpoint(5.millis())
.unwrap()
.build();
Self::new(iface)
}
}
impl<'a> AppHIDConfig<'a> {
#[must_use]
pub fn new(interface: HeapInterfaceConfig<'a, InBytes64, OutBytes64, ReportSingle>) -> Self {
Self { interface }
}
}
impl<'a, B: UsbBus + 'a> UsbAllocatable<'a, B> for AppHIDConfig<'a> {
type Allocated = AppHID<'a, B>;
fn allocate(self, usb_alloc: &'a UsbBusAllocator<B>) -> Self::Allocated {
Self::Allocated {
interface: HeapInterface::new(usb_alloc, self.interface),
}
}
}

View file

@ -411,6 +411,68 @@ impl UsbHid {
)
).unwrap();
}
// HID v2
pub fn connect_hid_app(&self, descriptor: Vec<u8>) -> Result<(), xous::Error> {
if descriptor.len() > MAX_HID_REPORT_DESCRIPTOR_LEN {
return Err(xous::Error::OutOfMemory)
}
let mut container = HIDReportDescriptorMessage{
descriptor: [0u8; MAX_HID_REPORT_DESCRIPTOR_LEN],
len: descriptor.len(),
};
for (place, element) in container.descriptor.iter_mut().zip(descriptor.iter()) {
*place = *element;
}
let mut buf = Buffer::into_buf(container).or(Err(xous::Error::InternalError))?;
buf.lend_mut(self.conn, Opcode::HIDSetDescriptor.to_u32().unwrap()).map(|_| ())?;
Ok(())
}
pub fn disconnect_hid_app(&self) -> Result<(), xous::Error> {
match send_message(self.conn, Message::new_blocking_scalar(
Opcode::HIDUnsetDescriptor.to_usize().unwrap(),
0, 0, 0, 0)
) {
Ok(_) => Ok(()),
Err(err) => Err(err),
}
}
pub fn read_report(&self) -> Result<HIDReport, xous::Error> {
let report = HIDReportMessage::default();
let mut buf = Buffer::into_buf(report).or(Err(xous::Error::InternalError))?;
buf.lend_mut(self.conn, Opcode::HIDReadReport.to_u32().unwrap()).map(|_| ())?;
let report = buf.as_flat::<HIDReportMessage, _>().unwrap();
match report.has_data {
true => {
let mut ret = HIDReport::default();
// copy the data back
for (&s, d) in report.data.0[..report.data.0.len() as usize].iter().zip(ret.0.iter_mut()) {
*d = s;
}
Ok(ret)
},
false => Err(xous::Error::UnknownError),
}
}
pub fn write_report(&self, report: HIDReport) -> Result<(), xous::Error> {
let buf = Buffer::into_buf(report).or(Err(xous::Error::InternalError))?;
buf.lend(self.conn, Opcode::HIDWriteReport.to_u32().unwrap()).map(|_| ())?;
Ok(())
}
}
use core::sync::atomic::{AtomicU32, Ordering};

View file

@ -23,6 +23,8 @@ use spinal_udc::*;
#[cfg(all(any(feature="precursor", feature="renode"),feature="mass-storage"))]
mod apps_block_device;
#[cfg(any(feature="precursor", feature="renode"))]
mod hid;
#[cfg(not(target_os = "xous"))]
mod hosted;
#[cfg(not(target_os = "xous"))]

View file

@ -1,5 +1,6 @@
use crate::*;
use crate::hid::AppHID;
use crate::hid::AppHIDConfig;
use num_traits::*;
use usb_device_xous::KeyboardLedsReport;
use usb_device_xous::UsbDeviceType;
@ -13,6 +14,7 @@ use xous_semver::SemVer;
use core::num::NonZeroU8;
use core::sync::atomic::{AtomicU32, AtomicBool, Ordering};
use std::sync::Arc;
use std::sync::Mutex;
use utralib::generated::*;
use usb_device::prelude::*;
@ -32,7 +34,7 @@ use usbd_serial::SerialPort;
/// Time allowed for switchover between device core types. It's longer because some hosts
/// get really confused when you have the same VID/PID show up with a different set of endpoints.
const EXTENDED_CORE_RESET_MS: usize = 4000;
#[derive(Eq, PartialEq)]
#[derive(Eq, PartialEq, Debug)]
#[repr(usize)]
enum Views {
FidoWithKbd = 0,
@ -40,6 +42,7 @@ enum Views {
#[cfg(feature="mass-storage")]
MassStorage = 2,
Serial = 3,
HIDv2 = 4,
}
#[derive(num_derive::FromPrimitive, num_derive::ToPrimitive, Debug)]
@ -185,7 +188,7 @@ pub(crate) fn main_hw() -> ! {
let mut usbmgmt = usb_fidokbd_dev.get_iface();
// before doing any allocs, clone a copy of the hardware access structure so we can build a second
// view into the hardware with only FIDO descriptors
let usb_fido_dev = SpinalUsbDevice::new(usbdev_sid, usb.clone(), csr.clone());
let usb_fido_dev: SpinalUsbDevice = SpinalUsbDevice::new(usbdev_sid, usb.clone(), csr.clone());
usb_fido_dev.init();
// do the same thing for mass storage
#[cfg(feature="mass-storage")]
@ -292,6 +295,27 @@ pub(crate) fn main_hw() -> ! {
const TRNG_BACKOFF_MS: u32 = 1;
const TRNG_BACKOFF_MAX_MS: u32 = 1000; // cap on how far we backoff the polling rate
// stores the descriptor that has been selected for the current HIDv2 view.
let selected_hidv2_descriptor = Arc::new(Mutex::new(None));
let usb_hidv2_dev = SpinalUsbDevice::new(usbdev_sid, usb.clone(), csr.clone());
let hidv2_alloc = UsbBusAllocator::new(usb_hidv2_dev);
let mut hidv2_class = UsbHidClassBuilder::new()
.add_device(
AppHIDConfig::default(),
)
.build(&hidv2_alloc);
let mut hidv2_dev = UsbDeviceBuilder::new(&hidv2_alloc, UsbVidPid(0x1209, 0x3613))
.manufacturer("Kosagi")
.product("Precursor")
.serial_number(&serial_number)
.build();
let mut hidv2_queue = VecDeque::<HIDReport>::new();
let mut led_state: KeyboardLedsReport = KeyboardLedsReport::default();
let mut fido_listener: Option<xous::MessageEnvelope> = None;
// under the theory that PIDs cannot be forged. TODO: check that PIDs cannot be forged.
@ -434,32 +458,25 @@ pub(crate) fn main_hw() -> ! {
usbmgmt.xous_resume1();
match view {
Views::FidoWithKbd => {
match usb_dev.force_reset() {
Err(e) => log::warn!("USB reset on resume failed: {:?}", e),
_ => ()
};
usb_dev.force_reset()
}
Views::FidoOnly => {
match fido_dev.force_reset() {
Err(e) => log::warn!("USB reset on resume failed: {:?}", e),
_ => ()
};
fido_dev.force_reset()
}
#[cfg(feature="mass-storage")]
Views::MassStorage => {
// TODO: test this
match ums_device.force_reset() {
Err(e) => log::warn!("USB reset on resume failed: {:?}", e),
_ => ()
};
ums_device.force_reset()
}
Views::Serial => {
match serial_device.force_reset() {
Err(e) => log::warn!("USB reset on resume failed: {:?}", e),
_ => ()
}
serial_device.force_reset()
},
Views::HIDv2 => {
hidv2_dev.force_reset()
}
}
}.unwrap_or_else(|err| {
log::warn!("USB reset for view {:?} on resume failed: {:?}", view, err)
});
// resume2 brings us to our last application state
usbmgmt.xous_resume2();
lockstatus_force_update = true; // notify the status bar that yes, it does need to redraw the lock status, even if the value hasn't changed since the last read
@ -543,6 +560,7 @@ pub(crate) fn main_hw() -> ! {
#[cfg(feature="mass-storage")]
Views::MassStorage => panic!("did not expect u2f tx when in mass storage mode!"),
Views::Serial => panic!("did not expect u2f tx while in serial mode!"),
Views::HIDv2 => panic!("did not expect u2f tx while in hidv2 mode!"),
};
u2f.write_report(&u2f_msg).ok();
log::debug!("sent U2F packet {:x?}", u2f_ipc.data);
@ -584,7 +602,7 @@ pub(crate) fn main_hw() -> ! {
},
Views::Serial => {
if serial_device.poll(&mut [&mut serial_port]) {
let mut data = [0u8; SERIAL_BUF_LEN];
let mut data: [u8; 1024] = [0u8; SERIAL_BUF_LEN];
match serial_listen_mode {
SerialListenMode::NoListener => {
match serial_port.read(&mut data) {
@ -685,6 +703,25 @@ pub(crate) fn main_hw() -> ! {
}
None
},
Views::HIDv2 => {
if hidv2_dev.poll(&mut [&mut hidv2_class]) {
if selected_hidv2_descriptor.lock().unwrap().is_none() {
continue;
}
let hidv2_device = hidv2_class.device::<AppHID<'_, _>, _>();
match hidv2_device.read_report(){
Ok(report) => {
hidv2_queue.push_back(report);
log::info!("report pushed to vecdeque: {:?}", report);
}
Err(err) => log::debug!("hidv2 read report error: {:?}", err),
}
}
None
}
};
if let Some(u2f) = maybe_u2f {
match u2f.read_report() {
@ -715,6 +752,7 @@ pub(crate) fn main_hw() -> ! {
#[cfg(feature="mass-storage")]
Views::MassStorage => ums_device.state() == UsbDeviceState::Suspend,
Views::Serial => serial_device.state() == UsbDeviceState::Suspend,
Views::HIDv2 => hidv2_dev.state() == UsbDeviceState::Suspend,
};
if is_suspend {
log::info!("suspend detected");
@ -822,6 +860,20 @@ pub(crate) fn main_hw() -> ! {
usbmgmt.ll_reset(false);
}
}
},
UsbDeviceType::HIDv2 => {
log::info!("Connectiing HIDv2 device");
match view {
Views::HIDv2 => usbmgmt.connect_device_core(true),
_ => {
view = Views::HIDv2;
usbmgmt.ll_reset(true);
tt.sleep_ms(1000).ok();
usbmgmt.ll_connect_device_core(true);
tt.sleep_ms(EXTENDED_CORE_RESET_MS).ok();
usbmgmt.ll_reset(false);
}
}
}
}
xous::return_scalar(msg.sender, 0).unwrap();
@ -931,6 +983,22 @@ pub(crate) fn main_hw() -> ! {
}
}
}
UsbDeviceType::HIDv2 => {
log::info!("Ensuring HIDv2 device");
if !usbmgmt.is_device_connected() {
view = Views::HIDv2;
usbmgmt.connect_device_core(true);
} else {
if view != Views::HIDv2 {
view = Views::HIDv2;
usbmgmt.ll_reset(true);
tt.sleep_ms(1000).ok();
usbmgmt.ll_connect_device_core(true);
tt.sleep_ms(EXTENDED_CORE_RESET_MS).ok();
usbmgmt.ll_reset(false);
}
}
}
}
xous::return_scalar(msg.sender, 0).unwrap();
}),
@ -942,6 +1010,7 @@ pub(crate) fn main_hw() -> ! {
#[cfg(feature="mass-storage")]
Views::MassStorage => xous::return_scalar(msg.sender, UsbDeviceType::MassStorage as usize).unwrap(),
Views::Serial => xous::return_scalar(msg.sender, UsbDeviceType::Serial as usize).unwrap(),
Views::HIDv2 => xous::return_scalar(msg.sender, UsbDeviceType::HIDv2 as usize).unwrap(),
}
} else {
xous::return_scalar(msg.sender, UsbDeviceType::Debug as usize).unwrap();
@ -998,6 +1067,7 @@ pub(crate) fn main_hw() -> ! {
#[cfg(feature="mass-storage")]
Views::MassStorage => xous::return_scalar(msg.sender, ums_device.state() as usize).unwrap(),
Views::Serial => xous::return_scalar(msg.sender, serial_device.state() as usize).unwrap(),
Views::HIDv2 => xous::return_scalar(msg.sender, hidv2_dev.state() as usize).unwrap(),
}
}),
Some(Opcode::SendKeyCode) => msg_blocking_scalar_unpack!(msg, code0, code1, code2, autoup, {
@ -1409,6 +1479,74 @@ pub(crate) fn main_hw() -> ! {
serial_trng_interval.store(TRNG_REFILL_DELAY_MS, Ordering::SeqCst);
}
}
Some(Opcode::HIDSetDescriptor) => {
let buffer = unsafe {
Buffer::from_memory_message_mut(msg.body.memory_message_mut().unwrap())
};
let data = buffer.to_original::<HIDReportDescriptorMessage, _>().unwrap();
let mut selected_hidv2_descriptor = selected_hidv2_descriptor.lock().unwrap();
*selected_hidv2_descriptor = Some(Vec::from(&data.descriptor[..data.len]));
log::debug!("descriptor being set: {:?}", &selected_hidv2_descriptor.as_ref().unwrap()[..data.len]);
let hidv2_device = hidv2_class.device::<AppHID<'_, _>, _>();
match hidv2_device.set_device_descriptor(selected_hidv2_descriptor.as_ref().unwrap().clone()) {
Ok(_) => (),
Err(err) => {
log::error!("can't set hidv2 device descriptor: {:?}", err);
continue;
},
};
log::debug!("successfully set new hidv2 descriptor");
hidv2_dev.force_reset().ok();
}
Some(Opcode::HIDUnsetDescriptor) => {
*selected_hidv2_descriptor.lock().unwrap() = None;
hidv2_queue.clear();
hidv2_dev.force_reset().ok();
xous::return_scalar(msg.sender, 0).expect("cannot return hid app unset descriptor to sender")
}
Some(Opcode::HIDReadReport) => {
let mut buffer = unsafe {
Buffer::from_memory_message_mut(msg.body.memory_message_mut().unwrap())
};
let mut data = buffer.to_original::<HIDReportMessage, _>().unwrap();
if selected_hidv2_descriptor.lock().unwrap().is_none() {
buffer.replace(HIDReportMessage::default()).expect("couldn't serialize return");
continue
} else {
match hidv2_queue.pop_front() {
Some(report) => {
data.data = report;
data.has_data = true;
}
_ => ()
}
}
buffer.replace(data).expect("couldn't serialize return");
},
Some(Opcode::HIDWriteReport) => {
if selected_hidv2_descriptor.lock().unwrap().is_none() {
log::warn!("trying to write a HID report with no descriptor set!");
continue
}
let buffer = unsafe {
Buffer::from_memory_message(msg.body.memory_message().unwrap())
};
let data = buffer.to_original::<HIDReport, _>().unwrap();
log::info!("HIDWriteReport: {:?}", data);
let hidv2_device = hidv2_class.device::<AppHID<'_, _>, _>();
hidv2_device.write_report(&data).ok();
},
Some(Opcode::Quit) => {
log::warn!("Quit received, goodbye world!");
break;
@ -1424,4 +1562,4 @@ pub(crate) fn main_hw() -> ! {
xous::destroy_server(usbdev_sid).unwrap();
log::trace!("quitting");
xous::terminate_process(0)
}
}