Merge #1189

1189: USB: Add MS OS Descriptors (alternate implementation) r=Dirbaio a=alexmoon

This is an alternate API for #1152 based on the work of `@mattico.` By switching to a writer-style API instead of a builder API some compile-time guarantees are lost, but it integrates better into the usb `Builder` and makes an api that can be used by USB device class implementations.

It also adds a feature flag so there is zero cost to the MS OS descriptors for devices that don't need to use them.

I've added an example based on `usb_serial` which tells Windows to use the generic `WinUSB` driver instead of the serial port driver for the device.

Comments are welcome. It would be nice to see either this or #1152 merged as my project is going to require the MS OS Descriptors soon.

Co-authored-by: Matt Ickstadt <[email protected]>
Co-authored-by: alexmoon <[email protected]>

2 files changed, 136 insertions, 1 deletions

diff --git a/examples/nrf52840/Cargo.toml b/examples/nrf52840/Cargo.toml
index 95d939873..cfdda076e 100644
--- a/examples/nrf52840/Cargo.toml
+++ b/examples/nrf52840/Cargo.toml
@@ -6,6 +6,7 @@ license = "MIT OR Apache-2.0"
 
 [features]
 default = ["nightly"]
+msos-descriptor = ["embassy-usb/msos-descriptor"]
 nightly = ["embassy-executor/nightly", "embassy-nrf/nightly", "embassy-net/nightly", "embassy-nrf/unstable-traits", "embassy-usb", "embedded-io/async", "embassy-net",
            "embassy-lora", "lorawan-device", "lorawan"]
 
@@ -34,4 +35,8 @@ futures = { version = "0.3.17", default-features = false, features = ["async-awa
 rand = { version = "0.8.4", default-features = false }
 embedded-storage = "0.3.0"
 usbd-hid = "0.6.0"
-serde = { version = "1.0.136", default-features = false }
\ No newline at end of file
+serde = { version = "1.0.136", default-features = false }
+
+[[bin]]
+name = "usb_serial_winusb"
+required-features = ["msos-descriptor"]
diff --git a/examples/nrf52840/src/bin/usb_serial_winusb.rs b/examples/nrf52840/src/bin/usb_serial_winusb.rs
new file mode 100644
index 000000000..f4b828de6
--- /dev/null
+++ b/examples/nrf52840/src/bin/usb_serial_winusb.rs
@@ -0,0 +1,130 @@
+#![no_std]
+#![no_main]
+#![feature(type_alias_impl_trait)]
+
+use core::mem;
+
+use defmt::{info, panic};
+use embassy_executor::Spawner;
+use embassy_futures::join::join;
+use embassy_nrf::usb::{Driver, HardwareVbusDetect, Instance, VbusDetect};
+use embassy_nrf::{interrupt, pac};
+use embassy_usb::class::cdc_acm::{CdcAcmClass, State};
+use embassy_usb::driver::EndpointError;
+use embassy_usb::msos::{self, windows_version};
+use embassy_usb::{Builder, Config};
+use {defmt_rtt as _, panic_probe as _};
+
+// This is a randomly generated GUID to allow clients on Windows to find our device
+const DEVICE_INTERFACE_GUIDS: &[&str] = &["{EAA9A5DC-30BA-44BC-9232-606CDC875321}"];
+
+#[embassy_executor::main]
+async fn main(_spawner: Spawner) {
+    let p = embassy_nrf::init(Default::default());
+    let clock: pac::CLOCK = unsafe { mem::transmute(()) };
+
+    info!("Enabling ext hfosc...");
+    clock.tasks_hfclkstart.write(|w| unsafe { w.bits(1) });
+    while clock.events_hfclkstarted.read().bits() != 1 {}
+
+    // Create the driver, from the HAL.
+    let irq = interrupt::take!(USBD);
+    let power_irq = interrupt::take!(POWER_CLOCK);
+    let driver = Driver::new(p.USBD, irq, HardwareVbusDetect::new(power_irq));
+
+    // Create embassy-usb Config
+    let mut config = Config::new(0xc0de, 0xcafe);
+    config.manufacturer = Some("Embassy");
+    config.product = Some("USB-serial example");
+    config.serial_number = Some("12345678");
+    config.max_power = 100;
+    config.max_packet_size_0 = 64;
+
+    // Required for windows compatiblity.
+    // https://developer.nordicsemi.com/nRF_Connect_SDK/doc/1.9.1/kconfig/CONFIG_CDC_ACM_IAD.html#help
+    config.device_class = 0xEF;
+    config.device_sub_class = 0x02;
+    config.device_protocol = 0x01;
+    config.composite_with_iads = true;
+
+    // Create embassy-usb DeviceBuilder using the driver and config.
+    // It needs some buffers for building the descriptors.
+    let mut device_descriptor = [0; 256];
+    let mut config_descriptor = [0; 256];
+    let mut bos_descriptor = [0; 256];
+    let mut msos_descriptor = [0; 256];
+    let mut control_buf = [0; 64];
+
+    let mut state = State::new();
+
+    let mut builder = Builder::new(
+        driver,
+        config,
+        &mut device_descriptor,
+        &mut config_descriptor,
+        &mut bos_descriptor,
+        &mut msos_descriptor,
+        &mut control_buf,
+        None,
+    );
+
+    builder.msos_descriptor(windows_version::WIN8_1, 2);
+
+    // Create classes on the builder.
+    let mut class = CdcAcmClass::new(&mut builder, &mut state, 64);
+
+    // Since we want to create MS OS feature descriptors that apply to a function that has already been added to the
+    // builder, need to get the MsOsDescriptorWriter from the builder and manually add those descriptors.
+    // Inside a class constructor, you would just need to call `FunctionBuilder::msos_feature` instead.
+    let msos_writer = builder.msos_writer();
+    msos_writer.configuration(0);
+    msos_writer.function(0);
+    msos_writer.function_feature(msos::CompatibleIdFeatureDescriptor::new("WINUSB", ""));
+    msos_writer.function_feature(msos::RegistryPropertyFeatureDescriptor::new(
+        "DeviceInterfaceGUIDs",
+        msos::PropertyData::RegMultiSz(DEVICE_INTERFACE_GUIDS),
+    ));
+
+    // Build the builder.
+    let mut usb = builder.build();
+
+    // Run the USB device.
+    let usb_fut = usb.run();
+
+    // Do stuff with the class!
+    let echo_fut = async {
+        loop {
+            class.wait_connection().await;
+            info!("Connected");
+            let _ = echo(&mut class).await;
+            info!("Disconnected");
+        }
+    };
+
+    // Run everything concurrently.
+    // If we had made everything `'static` above instead, we could do this using separate tasks instead.
+    join(usb_fut, echo_fut).await;
+}
+
+struct Disconnected {}
+
+impl From<EndpointError> for Disconnected {
+    fn from(val: EndpointError) -> Self {
+        match val {
+            EndpointError::BufferOverflow => panic!("Buffer overflow"),
+            EndpointError::Disabled => Disconnected {},
+        }
+    }
+}
+
+async fn echo<'d, T: Instance + 'd, P: VbusDetect + 'd>(
+    class: &mut CdcAcmClass<'d, Driver<'d, T, P>>,
+) -> Result<(), Disconnected> {
+    let mut buf = [0; 64];
+    loop {
+        let n = class.read_packet(&mut buf).await?;
+        let data = &buf[..n];
+        info!("data: {:x}", data);
+        class.write_packet(data).await?;
+    }
+}