Merge pull request #3 from vitalyvb/pre-v011

Fix DFUManifestationError, prepare for 0.1.1

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2021-05-15
+### Added
+- CI using GitHub Actions
+
+### Fixed
+- `DFUManifestationError::File` error status incorrectly returned `errTarget` to host
+- `DFUManifestationError::Target` error status incorrectly returned `errFile` to host
+- Clippy errors and some warnings
+
+### Changed
+- Code formatting to follow rustfmt
+- Clarified the behavior of `DFUMemIO::usb_reset` in the documentation
+- Documentation updates
+
+## [0.1.0] - 2021-04-16
+
+First version.
+
+[Unreleased]: https://github.com/vitalyvb/usbd-dfu/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/vitalyvb/usbd-dfu/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/vitalyvb/usbd-dfu/releases/tag/v0.1.0

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "usbd-dfu"
 description = "DFU protocol for a `usb-device device."
-version = "0.1.0"
+version = "0.1.1"
 authors = ["Vitalii Bursov <vitaly@bursov.com>"]
 edition = "2018"
 readme = "README.md"

README.md

@@ -78,10 +78,10 @@ struct MyMem {
 
 impl DFUMemIO for MyMem {
  const MEM_INFO_STRING: &'static str = "@Flash/0x00000000/1*1Kg";
- const INITIAL_ADDRESS_POINTER : u32 = 0x0;
- const PAGE_PROGRAM_TIME_MS : u32 = 8;
- const PAGE_ERASE_TIME_MS : u32 = 50;
- const FULL_ERASE_TIME_MS : u32 = 50;
+ const INITIAL_ADDRESS_POINTER: u32 = 0x0;
+ const PAGE_PROGRAM_TIME_MS: u32 = 8;
+ const PAGE_ERASE_TIME_MS: u32 = 50;
+ const FULL_ERASE_TIME_MS: u32 = 50;
  const TRANSFER_SIZE: u16 = 64;
 
  fn read_block(&mut self, address: u32, length: usize) -> Result<&[u8], DFUMemError> {

src/class.rs

@@ -168,7 +168,7 @@ pub trait DFUMemIO {
  ///
  /// > *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**
+ /// Block size supports these suffixes: **K**, **M**, **G**, or ` ` (space) for bytes.
  ///
  /// And a letter that specifies region's supported operation:
  ///
@@ -339,10 +339,14 @@ pub trait DFUMemIO {
  ///
  fn manifestation(&mut self) -> Result<(), DFUManifestationError>;
 
- /// Called if USB is reset.
+ /// Called every time when USB is reset.
  ///
- /// Device should switch to an application firmware if it's possible and this
- /// function should not return.
+ /// After firmware update is done, device should switch to an application
+ /// firmware if it's possible and this function should not return.
+ ///
+ /// Handler will need to distinguish between actual host resets and
+ /// when the device connects the first time at startup to avoid
+ /// device reset and revert to main firmware at boot.
  ///
  /// 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.
@@ -376,8 +380,8 @@ impl From<DFUManifestationError> for DFUStatusCode {
  DFUManifestationError::Firmware => DFUStatusCode::ErrFirmware,
  DFUManifestationError::Unknown => DFUStatusCode::ErrUnknown,
  DFUManifestationError::ErrVendor => DFUStatusCode::ErrVendor,
- DFUManifestationError::File => DFUStatusCode::ErrTarget,
- DFUManifestationError::Target => DFUStatusCode::ErrFile,
+ DFUManifestationError::File => DFUStatusCode::ErrFile,
+ DFUManifestationError::Target => DFUStatusCode::ErrTarget,
  }
  }
 }

src/lib.rs

@@ -1,4 +1,5 @@
 #![cfg_attr(not(test), no_std)]
+#![warn(missing_docs)]
 //!
 //! Implements DFU protocol version 1.1a for a `usb-device` device.
 //!
@@ -83,10 +84,10 @@
 //!
 //! impl DFUMemIO for MyMem {
 //! const MEM_INFO_STRING: &'static str = "@Flash/0x00000000/1*1Kg";
-//! const INITIAL_ADDRESS_POINTER : u32 = 0x0;
-//! const PAGE_PROGRAM_TIME_MS : u32 = 8;
-//! const PAGE_ERASE_TIME_MS : u32 = 50;
-//! const FULL_ERASE_TIME_MS : u32 = 50;
+//! const INITIAL_ADDRESS_POINTER: u32 = 0x0;
+//! const PAGE_PROGRAM_TIME_MS: u32 = 8;
+//! const PAGE_ERASE_TIME_MS: u32 = 50;
+//! const FULL_ERASE_TIME_MS: u32 = 50;
 //! const TRANSFER_SIZE: u16 = 64;
 //!
 //! fn read_block(&mut self, address: u32, length: usize) -> Result<&[u8], DFUMemError> {
@@ -146,7 +147,12 @@
 //! usb_dev.poll(&mut [&mut dfu]);
 //! ```
 //!
+//! ### Example bootloader implementation
+//!
+//! See [usbd-dfu-example](https://github.com/vitalyvb/usbd-dfu-example) for a functioning example.
+//!
 
+/// DFU protocol module
 pub mod class;
 
 #[doc(inline)]

tests/mockusb/mod.rs

@@ -23,6 +23,7 @@ struct EP {
  write: [u8; 1024],
  write_done: bool,
  setup: bool,
+ max_size: usize,
 }
 impl EP {
  fn new() -> Self {
@@ -36,6 +37,7 @@ impl EP {
  write: [0; 1024],
  write_done: false,
  setup: false,
+ max_size: 0,
  }
  }
 
@@ -144,7 +146,7 @@ impl usb_device::bus::UsbBus for TestBus {
  _ep_dir: UsbDirection,
  ep_addr: Option<EndpointAddress>,
  _ep_type: EndpointType,
- _max_packet_size: u16,
+ max_packet_size: u16,
  _interval: u8,
  ) -> Result<EndpointAddress> {
  if let Some(ea) = ep_addr {
@@ -153,6 +155,7 @@ impl usb_device::bus::UsbBus for TestBus {
  assert!(!sep.alloc);
  sep.alloc = true;
  sep.stall = false;
+ sep.max_size = max_packet_size as usize;
 
  Ok(ea)
  } else {
@@ -193,12 +196,12 @@ impl usb_device::bus::UsbBus for TestBus {
  fn read(&self, ep_addr: EndpointAddress, buf: &mut [u8]) -> Result<usize> {
  let io = self.io().borrow();
  let mut ep = io.epidx(ep_addr).borrow_mut();
- let len = min(buf.len(), ep.read_len);
+ let len = min(buf.len(), min(ep.read_len, ep.max_size));
 
- dbg!("read len from", buf.len(), ep.read_len, ep_addr);
+ dbg!("read len from", buf.len(), len, ep_addr);
 
  if len == 0 {
- //return (Err(UsbError::WouldBlock))
+ return Err(UsbError::WouldBlock);
  }
 
  buf[..len].clone_from_slice(&ep.read[..len]);
@@ -238,6 +241,10 @@ impl usb_device::bus::UsbBus for TestBus {
 
  dbg!("write", buf.len());
 
+ if buf.len() > ep.max_size {
+ return Err(UsbError::BufferOverflow);
+ }
+
  for (i, e) in ep.write[offset..].iter_mut().enumerate() {
  if i >= buf.len() {
  break;
@@ -318,8 +325,16 @@ pub fn with_usb<T, M>(
 
  if let Some(val) = data {
  usb.borrow().set_read(out0, val, false);
- dev.poll(&mut [d]);
- maker.poll(d);
+ for i in 1..100 {
+ let res = dev.poll(&mut [d]);
+ maker.poll(d);
+ if !res {
+ break;
+ }
+ if i >= 99 {
+ panic!("read too much");
+ }
+ }
  if usb.borrow().stalled0() {
  return Err(EPErr::Stalled);
  }