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] 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, }