docs: document usb-logger and usb-dfu

This commit is contained in:
Ulf Lilleengen 2023-12-19 16:33:05 +01:00
parent c995732b0e
commit 9ddf8b08e4
6 changed files with 53 additions and 6 deletions

20
embassy-usb-dfu/README.md Normal file
View File

@ -0,0 +1,20 @@
# embassy-usb-dfu
An implementation of the USB DFU 1.1 protocol using embassy-boot. It has 2 components depending on which feature is enabled by the user.
* DFU protocol mode, enabled by the `dfu` feature. This mode corresponds to the transfer phase DFU protocol described by the USB IF. It supports DFU_DNLOAD requests if marked by the user, and will automatically reset the chip once a DFU transaction has been completed. It also responds to DFU_GETSTATUS, DFU_GETSTATE, DFU_ABORT, and DFU_CLRSTATUS with no user intervention.
* DFU runtime mode, enabled by the `application feature`. This mode allows users to expose a DFU interface on their USB device, informing the host of the capability to DFU over USB, and allowing the host to reset the device into its bootloader to complete a DFU operation. Supports DFU_GETSTATUS and DFU_DETACH. When detach/reset is seen by the device as described by the standard, will write a new DFU magic number into the bootloader state in flash, and reset the system.
## Minimum supported Rust version (MSRV)
Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.
## License
This work is licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
<http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
at your option.

View File

@ -24,6 +24,7 @@ pub struct Control<'d, STATE: NorFlash, RST: Reset> {
} }
impl<'d, STATE: NorFlash, RST: Reset> Control<'d, STATE, RST> { impl<'d, STATE: NorFlash, RST: Reset> Control<'d, STATE, RST> {
/// Create a new DFU instance to expose a DFU interface.
pub fn new(firmware_state: BlockingFirmwareState<'d, STATE>, attrs: DfuAttributes) -> Self { pub fn new(firmware_state: BlockingFirmwareState<'d, STATE>, attrs: DfuAttributes) -> Self {
Control { Control {
firmware_state, firmware_state,

View File

@ -1,3 +1,4 @@
//! USB DFU constants.
pub(crate) const USB_CLASS_APPN_SPEC: u8 = 0xFE; pub(crate) const USB_CLASS_APPN_SPEC: u8 = 0xFE;
pub(crate) const APPN_SPEC_SUBCLASS_DFU: u8 = 0x01; pub(crate) const APPN_SPEC_SUBCLASS_DFU: u8 = 0x01;
#[allow(unused)] #[allow(unused)]
@ -18,10 +19,15 @@ defmt::bitflags! {
#[cfg(not(feature = "defmt"))] #[cfg(not(feature = "defmt"))]
bitflags::bitflags! { bitflags::bitflags! {
/// Attributes supported by the DFU controller.
pub struct DfuAttributes: u8 { pub struct DfuAttributes: u8 {
/// Generate WillDetache sequence on bus.
const WILL_DETACH = 0b0000_1000; const WILL_DETACH = 0b0000_1000;
/// Device can communicate during manifestation phase.
const MANIFESTATION_TOLERANT = 0b0000_0100; const MANIFESTATION_TOLERANT = 0b0000_0100;
/// Capable of upload.
const CAN_UPLOAD = 0b0000_0010; const CAN_UPLOAD = 0b0000_0010;
/// Capable of download.
const CAN_DOWNLOAD = 0b0000_0001; const CAN_DOWNLOAD = 0b0000_0001;
} }
} }
@ -29,7 +35,7 @@ bitflags::bitflags! {
#[derive(Copy, Clone, PartialEq, Eq)] #[derive(Copy, Clone, PartialEq, Eq)]
#[repr(u8)] #[repr(u8)]
#[allow(unused)] #[allow(unused)]
pub enum State { pub(crate) enum State {
AppIdle = 0, AppIdle = 0,
AppDetach = 1, AppDetach = 1,
DfuIdle = 2, DfuIdle = 2,
@ -46,7 +52,7 @@ pub enum State {
#[derive(Copy, Clone, PartialEq, Eq)] #[derive(Copy, Clone, PartialEq, Eq)]
#[repr(u8)] #[repr(u8)]
#[allow(unused)] #[allow(unused)]
pub enum Status { pub(crate) enum Status {
Ok = 0x00, Ok = 0x00,
ErrTarget = 0x01, ErrTarget = 0x01,
ErrFile = 0x02, ErrFile = 0x02,
@ -67,7 +73,7 @@ pub enum Status {
#[derive(Copy, Clone, PartialEq, Eq)] #[derive(Copy, Clone, PartialEq, Eq)]
#[repr(u8)] #[repr(u8)]
pub enum Request { pub(crate) enum Request {
Detach = 0, Detach = 0,
Dnload = 1, Dnload = 1,
Upload = 2, Upload = 2,

View File

@ -23,6 +23,7 @@ pub struct Control<'d, DFU: NorFlash, STATE: NorFlash, RST: Reset, const BLOCK_S
} }
impl<'d, DFU: NorFlash, STATE: NorFlash, RST: Reset, const BLOCK_SIZE: usize> Control<'d, DFU, STATE, RST, BLOCK_SIZE> { impl<'d, DFU: NorFlash, STATE: NorFlash, RST: Reset, const BLOCK_SIZE: usize> Control<'d, DFU, STATE, RST, BLOCK_SIZE> {
/// Create a new DFU instance to handle DFU transfers.
pub fn new(updater: BlockingFirmwareUpdater<'d, DFU, STATE>, attrs: DfuAttributes) -> Self { pub fn new(updater: BlockingFirmwareUpdater<'d, DFU, STATE>, attrs: DfuAttributes) -> Self {
Self { Self {
updater, updater,

View File

@ -1,12 +1,14 @@
#![no_std] #![no_std]
#![doc = include_str!("../README.md")]
#![warn(missing_docs)]
mod fmt; mod fmt;
pub mod consts; pub mod consts;
#[cfg(feature = "dfu")] #[cfg(feature = "dfu")]
mod bootloader; mod dfu;
#[cfg(feature = "dfu")] #[cfg(feature = "dfu")]
pub use self::bootloader::*; pub use self::dfu::*;
#[cfg(feature = "application")] #[cfg(feature = "application")]
mod application; mod application;
@ -17,7 +19,7 @@ pub use self::application::*;
all(feature = "dfu", feature = "application"), all(feature = "dfu", feature = "application"),
not(any(feature = "dfu", feature = "application")) not(any(feature = "dfu", feature = "application"))
))] ))]
compile_error!("usb-dfu must be compiled with exactly one of `bootloader`, or `application` features"); compile_error!("usb-dfu must be compiled with exactly one of `dfu`, or `application` features");
/// Provides a platform-agnostic interface for initiating a system reset. /// Provides a platform-agnostic interface for initiating a system reset.
/// ///
@ -26,9 +28,11 @@ compile_error!("usb-dfu must be compiled with exactly one of `bootloader`, or `a
/// ///
/// If alternate behaviour is desired, a custom implementation of Reset can be provided as a type argument to the usb_dfu function. /// If alternate behaviour is desired, a custom implementation of Reset can be provided as a type argument to the usb_dfu function.
pub trait Reset { pub trait Reset {
/// Reset the device.
fn sys_reset() -> !; fn sys_reset() -> !;
} }
/// Reset immediately.
#[cfg(feature = "esp32c3-hal")] #[cfg(feature = "esp32c3-hal")]
pub struct ResetImmediate; pub struct ResetImmediate;
@ -40,6 +44,7 @@ impl Reset for ResetImmediate {
} }
} }
/// Reset immediately.
#[cfg(feature = "cortex-m")] #[cfg(feature = "cortex-m")]
pub struct ResetImmediate; pub struct ResetImmediate;

View File

@ -13,3 +13,17 @@ async fn logger_task(driver: Driver<'static, USB>) {
embassy_usb_logger::run!(1024, log::LevelFilter::Info, driver); embassy_usb_logger::run!(1024, log::LevelFilter::Info, driver);
} }
``` ```
## Minimum supported Rust version (MSRV)
Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.
## License
This work is licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
<http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
at your option.