Convert MS OS descriptor builder to a writer API

This brings it inline with the other embassy-usb descriptor APIs and allows it to integrate well with the Builder to allow class constructors to add MS OS descriptors.

Also adds a `usb_serial_winusb` example to demonstrate how to use the API.

2 files changed, 145 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..443379a07
--- /dev/null
+++ b/examples/nrf52840/src/bin/usb_serial_winusb.rs
@@ -0,0 +1,139 @@
+#![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, Instance, PowerUsb, UsbSupply};
+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 _};
+
+const DEVICE_INTERFACE_GUIDS: &[u16] = {
+    // Can't use defmt::panic in constant expressions (inside u16str!)
+    macro_rules! panic {
+            ($($x:tt)*) => {
+                {
+                    ::core::panic!($($x)*);
+                }
+            };
+        }
+    msos::u16str!("{EAA9A5DC-30BA-44BC-9232-606CDC875321}\0\0").as_slice()
+};
+
+#[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, PowerUsb::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_multi_string(
+        msos::RegistryPropertyFeatureDescriptor::DEVICE_INTERFACE_GUIDS_NAME,
+        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: UsbSupply + '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?;
+    }
+}