Merge pull request #3870 from kkrolczyk/kk/mostly-docu-changes-and-examples-fix

dfu documentation update, fix a couple issues

docs/examples/layer-by-layer/Cargo.toml

@@ -3,7 +3,6 @@ resolver = "2"
 members = [
     "blinky-pac",
     "blinky-hal",
-    "blinky-irq",
     "blinky-async",
 ]
 

docs/examples/layer-by-layer/blinky-async/Cargo.toml

@@ -5,7 +5,7 @@ edition = "2021"
 license = "MIT OR Apache-2.0"
 
 [dependencies]
-cortex-m = "0.7"
+cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
 cortex-m-rt = "0.7"
 embassy-stm32 = { version = "0.2.0", path = "../../../../embassy-stm32", features = ["stm32l475vg", "memory-x", "exti"]  }
 embassy-executor = { version = "0.7.0", path = "../../../../embassy-executor", features = ["arch-cortex-m", "executor-thread"] }

docs/examples/layer-by-layer/blinky-hal/Cargo.toml

@@ -5,8 +5,8 @@ edition = "2021"
 license = "MIT OR Apache-2.0"
 
 [dependencies]
-cortex-m = "0.7"
 cortex-m-rt = "0.7"
+cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
 embassy-stm32 = { version = "0.2.0", path = "../../../../embassy-stm32", features = ["stm32l475vg", "memory-x"] }
 
 defmt = "0.3"

docs/examples/layer-by-layer/blinky-irq/Cargo.toml

@@ -1,3 +1,5 @@
+[workspace]
+
 [package]
 name = "blinky-irq"
 version = "0.1.0"
@@ -5,7 +7,7 @@ edition = "2021"
 license = "MIT OR Apache-2.0"
 
 [dependencies]
-cortex-m = "0.7"
+cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
 cortex-m-rt = { version = "0.7" }
 embassy-stm32 = { version = "0.2.0", path = "../../../../embassy-stm32", features = ["stm32l475vg", "memory-x", "unstable-pac"] }
 

docs/examples/layer-by-layer/blinky-pac/Cargo.toml

@@ -5,7 +5,7 @@ edition = "2021"
 license = "MIT OR Apache-2.0"
 
 [dependencies]
-cortex-m = "0.7"
+cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
 cortex-m-rt = "0.7"
 stm32-metapac = { version = "16", features = ["stm32l475vg"] }
 

docs/examples/layer-by-layer/memory.x

@@ -0,0 +1,5 @@
+MEMORY
+{
+    FLASH : ORIGIN = 0x08000000, LENGTH = 2048K /* BANK_1 */
+    RAM   : ORIGIN = 0x20000000, LENGTH =  640K /* SRAM */
+}

embassy-usb-dfu/src/consts.rs

@@ -1,10 +1,16 @@
-//! USB DFU constants.
+//! USB DFU constants, taken from
+//! https://www.usb.org/sites/default/files/DFU_1.1.pdf
+/// Device Firmware Upgrade class, App specific
 pub(crate) const USB_CLASS_APPN_SPEC: u8 = 0xFE;
+/// Device Firmware Upgrade subclass, App specific
 pub(crate) const APPN_SPEC_SUBCLASS_DFU: u8 = 0x01;
 #[allow(unused)]
+/// USB interface alternative setting
 pub(crate) const DFU_PROTOCOL_DFU: u8 = 0x02;
 #[allow(unused)]
+/// DFU runtime class
 pub(crate) const DFU_PROTOCOL_RT: u8 = 0x01;
+/// DFU functional descriptor
 pub(crate) const DESC_DFU_FUNCTIONAL: u8 = 0x21;
 
 macro_rules! define_dfu_attributes {
@@ -34,51 +40,89 @@ define_dfu_attributes!(bitflags::bitflags);
 #[derive(Copy, Clone, PartialEq, Eq)]
 #[repr(u8)]
 #[allow(unused)]
+/// An indication of the state that the device is going to enter immediately following transmission of this response.
 pub(crate) enum State {
+    /// Device is running its normal application.
     AppIdle = 0,
+    /// Device is running its normal application, has received the DFU_DETACH request, and is waiting for a USB reset.
     AppDetach = 1,
+    /// Device is operating in the DFU mode and is waiting for requests.
     DfuIdle = 2,
+    /// Device has received a block and is waiting for the host to solicit the status via DFU_GETSTATUS.
     DlSync = 3,
+    /// Device is programming a control-write block into its nonvolatile memories.
     DlBusy = 4,
+    /// Device is processing a download operation. Expecting DFU_DNLOAD requests.
     Download = 5,
+    /// Device has received the final block of firmware from the host, waits for DFU_GETSTATUS to start Manifestation phase or completed this phase
     ManifestSync = 6,
+    /// Device is in the Manifestation phase. Not all devices will be able to respond to DFU_GETSTATUS when in this state.
     Manifest = 7,
+    /// Device has programmed its memories and is waiting for a USB reset or a power on reset.
     ManifestWaitReset = 8,
+    /// The device is processing an upload operation. Expecting DFU_UPLOAD requests.
     UploadIdle = 9,
+    /// An error has occurred. Awaiting the DFU_CLRSTATUS request.
     Error = 10,
 }
 
 #[derive(Copy, Clone, PartialEq, Eq)]
 #[repr(u8)]
 #[allow(unused)]
+/// An indication of the status resulting from the execution of the most recent request.
 pub(crate) enum Status {
+    /// No error
     Ok = 0x00,
+    /// File is not targeted for use by this device
     ErrTarget = 0x01,
+    /// File is for this device but fails some vendor-specific verification test
     ErrFile = 0x02,
+    /// Device is unable to write memory
     ErrWrite = 0x03,
+    /// Memory erase function failed
     ErrErase = 0x04,
+    /// Memory erase check failed
     ErrCheckErased = 0x05,
+    /// Program memory function failed
     ErrProg = 0x06,
+    /// Programmed memory failed verification
     ErrVerify = 0x07,
+    /// Cannot program memory due to received address that is out of range
     ErrAddress = 0x08,
+    /// Received DFU_DNLOAD with wLength = 0, but device does not think it has all of the data yet
     ErrNotDone = 0x09,
+    /// Device’s firmware is corrupt. It cannot return to run-time (non-DFU) operations
     ErrFirmware = 0x0A,
+    /// iString indicates a vendor-specific error
     ErrVendor = 0x0B,
+    /// Device detected unexpected USB reset signaling
     ErrUsbr = 0x0C,
+    /// Device detected unexpected power on reset
     ErrPor = 0x0D,
+    /// Something went wrong, but the device does not know what
     ErrUnknown = 0x0E,
+    /// Device stalled an unexpected request
     ErrStalledPkt = 0x0F,
 }
 
 #[derive(Copy, Clone, PartialEq, Eq)]
 #[repr(u8)]
+/// DFU requests
 pub(crate) enum Request {
+    /// Host instructs the device to generate a detach-attach sequence
     Detach = 0,
+    /// Host initiates control-write transfers with this request, and sends a DFU_DNLOAD request
+    /// with  wLength = 0 to indicate that it has completed transferring the firmware image file
     Dnload = 1,
+    /// The DFU_UPLOAD request is employed by the host to solicit firmware from the device.
     Upload = 2,
+    /// The host employs the DFU_GETSTATUS request to facilitate synchronization with the device.
     GetStatus = 3,
+    ///  Any time the device detects an error, it waits with transition until ClrStatus
     ClrStatus = 4,
+    /// Requests a report about a state of the device
     GetState = 5,
+    /// Enables the host to exit from certain states and return to the DFU_IDLE state
     Abort = 6,
 }