Trait usbd_dfu::DFUMemIO

pub trait DFUMemIO {
    const INITIAL_ADDRESS_POINTER: u32;
    const MEM_INFO_STRING: &'static str;
    const HAS_DOWNLOAD: bool;
    const HAS_UPLOAD: bool;
    const MANIFESTATION_TOLERANT: bool;
    const PAGE_PROGRAM_TIME_MS: u32;
    const PAGE_ERASE_TIME_MS: u32;
    const FULL_ERASE_TIME_MS: u32;
    const MANIFESTATION_TIME_MS: u32;
    const DETACH_TIMEOUT: u16;
    const TRANSFER_SIZE: u16;

    fn store_write_buffer(&mut self, src: &[u8]) -> Result<(), ()>;
    fn read_block(
        &mut self, 
        address: u32, 
        length: usize
    ) -> Result<&[u8], DFUMemError>;
    fn program_block(
        &mut self, 
        address: u32, 
        length: usize
    ) -> Result<(), DFUMemError>;
    fn erase_block(&mut self, address: u32) -> Result<(), DFUMemError>;
    fn erase_all_blocks(&mut self) -> Result<(), DFUMemError>;
    fn manifestation(&mut self) -> Result<(), DFUManifestationError>;

    fn usb_reset(&mut self) { ... }
}

Trait that describes the abstraction used to access memory on a device. DFUClass will call corresponding functions and will use provided constants to tailor DFU features and, for example time interval values that are used in the protocol.

Associated Constants

const INITIAL_ADDRESS_POINTER: u32

Specifies the default value of Address Pointer

Usually, it’s start address of a memory region.

const MEM_INFO_STRING: &'static str

Specifies USB interface descriptor string. It should describe a memory region this interface works with.

Disclaimer: I haven’t found the specification, this is what it looks like from dfu-util sources.

The string is formatted as follows:

@ name/address/area[,area…]

@ (at sign), / (slash), , (coma) symbols

name - Region name, e.g. “Flash”

address - Memory address of a regions, e.g. “0x08000000”

area - count of blocks, block size, and supported operations for the region, e.g. 8*1Ke - 8 blocks of 1024 bytes, available for reading and writing.

Block size supports these suffixes: K, M, G

And a letter that specifies region’s supported operation:

letter	Read	Erase	Write
a	+
b		+
c	+	+
d			+
e	+		+
f		+	+
g	+	+	+

For example:

@Flash/0x08000000/16*1Ka,48*1Kg

Denotes a memory region named “Flash”, with a starting address 0x08000000, the first 16 blocks with a size 1K are available only for reading, and the next 48 1K-blocks are avaiable for reading, erase, and write operations.

const HAS_DOWNLOAD: bool

If set, DFU descriptor will have bitCanDnload bit set. Default is true.

Should be set to true if firmware download (host to device) is supported.

const HAS_UPLOAD: bool

If set, DFU descriptor will have bitCanUpload bit set. Default is true.

Should be set to true if firmware upload (device to host) is supported.

const MANIFESTATION_TOLERANT: bool

If set, DFU descriptor will have bitManifestationTolerant bit set. Default is true.

See also MANIFESTATION_TIME_MS.

const PAGE_PROGRAM_TIME_MS: u32

Time in milliseconds host must wait before issuing the next command after block program request.

This is the time that program of one block or TRANSFER_SIZE bytes takes.

DFU programs data as follows:

1. Host transfers TRANSFER_SIZE bytes to a device
2. Device stores this data in a buffer
3. Host issues DFU_GETSTATUS command, confirms that device state is correct, and checks the reply for 24-bit value how much time it must wait before issuing the next command. Device, after submitting a reply starts program operation.
4. After waiting for a specified number of milliseconds, host continues to send new commands.

const PAGE_ERASE_TIME_MS: u32

Similar to PAGE_PROGRAM_TIME_MS, but for a block erase operation.

const FULL_ERASE_TIME_MS: u32

Similar to PAGE_PROGRAM_TIME_MS, but for a full erase operation.

const MANIFESTATION_TIME_MS: u32

Time in milliseconds host must wait after submitting the final firware download (host to device) command. Default is 1 ms.

DFU protocol allows the device to enter a Manifestation state when it can activate the uploaded firmware.

After the activation is completed, device may need to reset (if MANIFESTATION_TOLERANT is false), or it can return to IDLE state (if MANIFESTATION_TOLERANT is true)

See also PAGE_PROGRAM_TIME_MS.

const DETACH_TIMEOUT: u16

wDetachTimeOut field in DFU descriptor. Default value: 250 ms.

Probably unused if device does not support DFU in run-time mode to handle DFU_DETACH command.

Time in milliseconds that device will wait after receipt of DFU_DETACH request if USB reset request is not received before reverting to a normal operation.

const TRANSFER_SIZE: u16

Maximum allowed transfer size. Default value: 128 bytes.

This is the maximum size of a block for read_block() and program_block() functions.

All DFU transfers use Control endpoint only.

Warning: must be less or equal of usb-device’s control endpoint buffer size (usually 128 bytes), otherwise data transfers may fail for no obvious reason.

Loading content...

Required methods

fn store_write_buffer(&mut self, src: &[u8]) -> Result<(), ()>

Collect data which comes from USB, possibly in chunks, to a buffer in RAM.

DFUClass does not have an internal memory buffer for a read/write operations, incoming data should be stored in a buffer managed by this trait’s implementation.

This function should not write data to Flash or trigger memory Erase.

The same buffer may be shared for both write and read operations. DFU protocol will not trigger block write while sending data to host, and will ensure that buffer has valid data before program operation is requested.

This function is called from usb_dev.poll([]) (USB interrupt context).

fn read_block(
    &mut self,
    address: u32,
    length: usize
) -> Result<&[u8], DFUMemError>

Read memory and return it to device.

If Upload operation is supported (HAS_UPLOAD is true), this function returns memory contents to a host.

Implementation must check that address is in a target region and that the whole block fits in this region too.

This function is called from usb_dev.poll([]) (USB interrupt context).

fn program_block(
    &mut self,
    address: u32,
    length: usize
) -> Result<(), DFUMemError>

Trigger block program

Implementation must check that address is in a target region and that the whole block fits in this region too.

This function is called from usb_dev.poll([]) (USB interrupt context).

fn erase_block(&mut self, address: u32) -> Result<(), DFUMemError>

Trigger block erase.

Implementation must ensure that address is valid, or return an error.

This function is called from usb_dev.poll([]) (USB interrupt context).

fn erase_all_blocks(&mut self) -> Result<(), DFUMemError>

Trigger full erase.

This function is called from usb_dev.poll([]) (USB interrupt context).

fn manifestation(&mut self) -> Result<(), DFUManifestationError>

Finish writing firmware to a persistent storage, and optionally activate it.

This funciton should return if MANIFESTATION_TOLERANT is true.

This funciton should not return Ok() if MANIFESTATION_TOLERANT is false. Instead device should activate and start new main firmware.

This function is called from usb_dev.poll([]) (USB interrupt context).

Loading content...

Provided methods

fn usb_reset(&mut self)

Called if USB is reset.

Device should switch to an application firmware if it’s possible and this function should not return.

If firmware is corrupt, this funciton should return and DFU will switch to ERROR state so host could try to recover. This is the default.

This function is called from usb_dev.poll([]) (USB interrupt context).

Loading content...

Implementors

Loading content...