From 4b809af90538b83de42d60eb6ac5b8509feaeecf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Kr=C3=B3lczyk?= Date: Mon, 10 Feb 2025 16:14:51 +0100 Subject: [PATCH 1/3] fix: #3760 - typo in docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Krzysztof Królczyk --- docs/pages/layer_by_layer.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/layer_by_layer.adoc b/docs/pages/layer_by_layer.adoc index 7852d27b7..7dba11b5e 100644 --- a/docs/pages/layer_by_layer.adoc +++ b/docs/pages/layer_by_layer.adoc @@ -76,7 +76,7 @@ The async version looks very similar to the HAL version, apart from a few minor * The peripheral initialization is done by the main macro, and is handed to the main task. * Before checking the button state, the application is awaiting a transition in the pin state (low -> high or high -> low). -When `button.await_for_any_edge().await` is called, the executor will pause the main task and put the microcontroller in sleep mode, unless there are other tasks that can run. Internally, the Embassy HAL has configured the interrupt handler for the button (in `ExtiInput`), so that whenever an interrupt is raised, the task awaiting the button will be woken up. +When `button.wait_for_any_edge().await` is called, the executor will pause the main task and put the microcontroller in sleep mode, unless there are other tasks that can run. Internally, the Embassy HAL has configured the interrupt handler for the button (in `ExtiInput`), so that whenever an interrupt is raised, the task awaiting the button will be woken up. The minimal overhead of the executor and the ability to run multiple tasks "concurrently" combined with the enormous simplification of the application, makes `async` a great fit for embedded. From e173db1151585702912b572c5195bd23fb4267fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Kr=C3=B3lczyk?= Date: Mon, 10 Feb 2025 17:32:16 +0100 Subject: [PATCH 2/3] doc: add docu strings for dfu MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Krzysztof Królczyk --- embassy-usb-dfu/src/consts.rs | 46 ++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/embassy-usb-dfu/src/consts.rs b/embassy-usb-dfu/src/consts.rs index 190b5ad5a..8701dabc4 100644 --- a/embassy-usb-dfu/src/consts.rs +++ b/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, } From 01b7ff8ff04af62cc04331a229f5305d320907fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Kr=C3=B3lczyk?= Date: Mon, 10 Feb 2025 17:38:39 +0100 Subject: [PATCH 3/3] fix: layer-by-layer examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit closes: #3794 #3793 Remove 'blinky-irq' from workspace. During linking from workspace level - embassy-stm32 and example code redefine EXTI15_10 symbol Building it separately, outside of workspace works Signed-off-by: Krzysztof Królczyk --- docs/examples/layer-by-layer/Cargo.toml | 1 - docs/examples/layer-by-layer/blinky-async/Cargo.toml | 2 +- docs/examples/layer-by-layer/blinky-hal/Cargo.toml | 2 +- docs/examples/layer-by-layer/blinky-irq/Cargo.toml | 4 +++- docs/examples/layer-by-layer/blinky-pac/Cargo.toml | 2 +- docs/examples/layer-by-layer/memory.x | 5 +++++ 6 files changed, 11 insertions(+), 5 deletions(-) create mode 100644 docs/examples/layer-by-layer/memory.x diff --git a/docs/examples/layer-by-layer/Cargo.toml b/docs/examples/layer-by-layer/Cargo.toml index f18c9e7e4..01666ec6e 100644 --- a/docs/examples/layer-by-layer/Cargo.toml +++ b/docs/examples/layer-by-layer/Cargo.toml @@ -3,7 +3,6 @@ resolver = "2" members = [ "blinky-pac", "blinky-hal", - "blinky-irq", "blinky-async", ] diff --git a/docs/examples/layer-by-layer/blinky-async/Cargo.toml b/docs/examples/layer-by-layer/blinky-async/Cargo.toml index 51ddf87d4..541eb6edf 100644 --- a/docs/examples/layer-by-layer/blinky-async/Cargo.toml +++ b/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"] } diff --git a/docs/examples/layer-by-layer/blinky-hal/Cargo.toml b/docs/examples/layer-by-layer/blinky-hal/Cargo.toml index 1e292e6b4..dd574c3e7 100644 --- a/docs/examples/layer-by-layer/blinky-hal/Cargo.toml +++ b/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" diff --git a/docs/examples/layer-by-layer/blinky-irq/Cargo.toml b/docs/examples/layer-by-layer/blinky-irq/Cargo.toml index 04ffc23ba..8733ee894 100644 --- a/docs/examples/layer-by-layer/blinky-irq/Cargo.toml +++ b/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"] } diff --git a/docs/examples/layer-by-layer/blinky-pac/Cargo.toml b/docs/examples/layer-by-layer/blinky-pac/Cargo.toml index cf2d7fede..155c41ec6 100644 --- a/docs/examples/layer-by-layer/blinky-pac/Cargo.toml +++ b/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"] } diff --git a/docs/examples/layer-by-layer/memory.x b/docs/examples/layer-by-layer/memory.x new file mode 100644 index 000000000..69f5b28a1 --- /dev/null +++ b/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 */ +}