Merge #304

304: Add optional support for printing some types with defmt r=mattico a=mattico

> `defmt` ("de format", short for "deferred formatting") is a highly efficient logging framework that targets resource-constrained devices, like microcontrollers.

https://defmt.ferrous-systems.com/

I've been maintaining this support in my fork for some time, it hasn't been burdensome. defmt has become popular enough that I think it is worthwhile to upstream this. Supporting defmt formatting in this library makes it easier to print error messages (don't need to use `defmt::Debug2Format`) and eliminates the code bloat of the `core::fmt` machinery. We could similarly move `Debug` derives behind a feature flag to help people who are trying to eliminate `core::fmt`, but I don't particularly care.

Co-authored-by: Matt Ickstadt <[email protected]>

Author: bors[bot]

.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
           - stm32h7b0
           - stm32h735
     env:                        # Peripheral Feature flags
-      FLAGS: rt,xspi,sdmmc,sdmmc-fatfs,fmc,usb_hs,rtc,ethernet,ltdc,crc,rand
+      FLAGS: rt,xspi,sdmmc,sdmmc-fatfs,fmc,usb_hs,rtc,ethernet,ltdc,crc,rand,defmt
 
     steps:
       - uses: actions/checkout@v2

Cargo.toml

@@ -21,13 +21,14 @@ readme = "README.md"
 exclude = [".gitignore"]
 
 [package.metadata.docs.rs]
-features = ["stm32h743v", "rt", "xspi", "sdmmc", "fmc", "usb_hs", "rtc", "ethernet", "ltdc", "crc", "rand"]
+features = ["stm32h743v", "rt", "xspi", "sdmmc", "fmc", "usb_hs", "rtc", "ethernet", "ltdc", "crc", "rand", "defmt"]
 targets = ["thumbv7em-none-eabihf"]
 
 [dependencies]
 embedded-hal = "0.2.6"
 embedded-dma = "0.1.2"
 cortex-m = "^0.7.1"
+defmt = { version = ">=0.2.0,<0.4", optional = true }
 stm32h7 = { version = "^0.14.0", default-features = false }
 void = { version = "1.0.2", default-features = false }
 cast = { version = "0.3.0", default-features = false }

src/adc.rs

@@ -88,6 +88,7 @@ pub struct Adc<ADC, ED> {
 //
 // Refer to RM0433 Rev 6 - Chapter 24.4.13
 #[derive(Clone, Copy, Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[allow(non_camel_case_types)]
 pub enum AdcSampleTime {
     /// 1.5 cycles sampling time
@@ -134,6 +135,7 @@ impl From<AdcSampleTime> for u8 {
 ///
 /// Only values in range of 0..=15 are allowed.
 #[derive(Clone, Copy, Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct AdcLshift(u8);
 
 impl AdcLshift {
@@ -155,6 +157,7 @@ impl AdcLshift {
 }
 
 #[derive(Clone, Copy, Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct AdcCalOffset(u16);
 
 impl AdcCalOffset {
@@ -164,6 +167,7 @@ impl AdcCalOffset {
 }
 
 #[derive(Clone, Copy, Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct AdcCalLinear([u32; 6]);
 
 impl AdcCalLinear {
@@ -326,6 +330,19 @@ pub trait AdcExt<ADC>: Sized {
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub struct StoredConfig(AdcSampleTime, Resolution, AdcLshift);
 
+#[cfg(feature = "defmt")]
+impl defmt::Format for StoredConfig {
+    fn format(&self, fmt: defmt::Formatter) {
+        defmt::write!(
+            fmt,
+            "StoredConfig({:?}, {:?}, {:?})",
+            self.0,
+            defmt::Debug2Format(&self.1),
+            self.2
+        )
+    }
+}
+
 /// Get and check the adc_ker_ck_input
 fn check_clock(prec: &impl AdcClkSelGetter, clocks: &CoreClocks) -> Hertz {
     // Select Kernel Clock

src/crc.rs

@@ -161,6 +161,7 @@ mod macros {
 /// A polynomial being even means that the least significant bit is `0`
 /// in the polynomial's normal representation.
 #[derive(Copy, Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Polynomial(Poly);
 
 impl Polynomial {
@@ -252,6 +253,7 @@ impl Default for Polynomial {
 
 /// Errors generated when trying to create invalid polynomials.
 #[derive(Copy, Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum PolynomialError {
     /// Tried to create an even polynomial.
     /// The hardware CRC unit only supports odd polynomials.
@@ -274,6 +276,7 @@ impl fmt::Display for PolynomialError {
 
 /// Internal representation of a polynomial.
 #[derive(Copy, Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 enum Poly {
     /// 7-bit polynomial
     B7(u8),
@@ -291,6 +294,7 @@ enum Poly {
 /// 'reflection' it most likely wants [`BitReversal::Byte`] and output reversal
 /// enabled.
 #[derive(Copy, Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
 pub enum BitReversal {
     /// Each input byte has its bits reversed. `0x1A2B3C4D` becomes `0x58D43CB2`.
@@ -303,6 +307,7 @@ pub enum BitReversal {
 
 /// CRC unit configuration.
 #[derive(Clone, Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Config {
     poly: Polynomial,
     initial: u32,

src/dma/bdma.rs

@@ -87,6 +87,7 @@ impl Instance for BDMA2 {
 
 /// BDMA interrupts
 #[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct BdmaInterrupts {
     transfer_complete: bool,
     transfer_error: bool,
@@ -95,6 +96,7 @@ pub struct BdmaInterrupts {
 
 /// Contains the complete set of configuration for a DMA stream.
 #[derive(Debug, Default, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct BdmaConfig {
     pub(crate) priority: config::Priority,
     pub(crate) memory_increment: bool,

src/dma/dma.rs

@@ -73,6 +73,7 @@ impl Instance for DMA2 {
 
 /// DMA interrupts
 #[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct DmaInterrupts {
     transfer_complete: bool,
     transfer_error: bool,
@@ -83,6 +84,7 @@ pub struct DmaInterrupts {
 
 /// Contains configuration for a DMA stream
 #[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct DmaConfig {
     pub(crate) priority: config::Priority,
     pub(crate) memory_increment: bool,

src/dma/mdma.rs

@@ -94,6 +94,7 @@ impl Instance for MDMA {
 
 /// MDMA Stream Transfer Requests
 #[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum MdmaTransferRequest {
     Dma1Tcif0 = 0,
     Dma1Tcif1,
@@ -161,6 +162,7 @@ pub enum MdmaTransferRequest {
 
 /// MDMA Source/Destination sizes
 #[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum MdmaSize {
     /// Byte (8-bit)
     Byte = 0,
@@ -206,6 +208,7 @@ impl MdmaSize {
 
 /// MDMA increment mode
 #[derive(Debug, Clone, Copy, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum MdmaIncrement {
     Fixed,
     /// Increment by one source/destination element each element
@@ -262,9 +265,20 @@ impl fmt::Debug for MdmaBurstSize {
         }
     }
 }
+#[cfg(feature = "defmt")]
+impl defmt::Format for MdmaBurstSize {
+    fn format(&self, fmt: defmt::Formatter) {
+        if self.0 > 0 {
+            defmt::write!(fmt, "{=u32}", 1 << self.0);
+        } else {
+            defmt::intern!("single").format(fmt);
+        }
+    }
+}
 
 /// MDMA Packing/Alignment mode
 #[derive(Debug, Clone, Copy, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum MdmaPackingAlignment {
     /// Source data is packed/unpacked into the destination data size
     Packed,
@@ -292,6 +306,7 @@ impl Default for MdmaPackingAlignment {
 
 /// MDMA trigger mode
 #[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum MdmaTrigger {
     /// Each MDMA request triggers a buffer transfer
     Buffer = 0b00,
@@ -310,6 +325,7 @@ impl Default for MdmaTrigger {
 
 /// MDMA interrupts
 #[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct MdmaInterrupts {
     transfer_complete: bool,
     transfer_error: bool,
@@ -320,6 +336,7 @@ pub struct MdmaInterrupts {
 
 /// Contains the complete set of configuration for a MDMA stream.
 #[derive(Debug, Default, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct MdmaConfig {
     pub(crate) priority: config::Priority,
     pub(crate) destination_increment: MdmaIncrement,

src/dma/mod.rs

@@ -117,6 +117,7 @@ use traits::{
 
 /// Errors.
 #[derive(PartialEq, Debug, Copy, Clone)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum DMAError {
     /// DMA not ready to change buffers.
     NotReady,
@@ -128,6 +129,7 @@ pub enum DMAError {
 
 /// Possible DMA's directions.
 #[derive(Debug, Clone, Copy, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum DmaDirection {
     /// Memory to Memory transfer.
     MemoryToMemory,
@@ -139,6 +141,7 @@ pub enum DmaDirection {
 
 /// DMA from a peripheral to a memory location.
 #[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct PeripheralToMemory;
 
 impl Direction for PeripheralToMemory {
@@ -153,6 +156,7 @@ impl Direction for PeripheralToMemory {
 
 /// DMA from one memory location to another memory location.
 #[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct MemoryToMemory<T> {
     _data: PhantomData<T>,
 }
@@ -169,6 +173,7 @@ impl<T> Direction for MemoryToMemory<T> {
 
 /// DMA from a memory location to a peripheral.
 #[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct MemoryToPeripheral;
 
 impl Direction for MemoryToPeripheral {
@@ -203,6 +208,7 @@ unsafe impl TargetAddress<Self> for MemoryToMemory<u32> {
 
 /// How full the DMA stream's fifo is.
 #[derive(Debug, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum FifoLevel {
     /// 0 < fifo_level < 1/4.
     GtZeroLtQuarter,
@@ -236,6 +242,7 @@ impl From<u8> for FifoLevel {
 
 /// Which DMA buffer is in use.
 #[derive(Debug, Clone, Copy, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum CurrentBuffer {
     /// The first buffer (m0ar).
     Buffer0 = 0,
@@ -264,6 +271,7 @@ pub mod config {
     /// priority over the stream with the higher number. For example, Stream 2
     /// takes priority over Stream 4.
     #[derive(Debug, Clone, Copy)]
+    #[cfg_attr(feature = "defmt", derive(defmt::Format))]
     pub enum Priority {
         /// Low priority.
         Low,
@@ -293,6 +301,7 @@ pub mod config {
 
     /// The level to fill the fifo to before performing the transaction.
     #[derive(Debug, Clone, Copy)]
+    #[cfg_attr(feature = "defmt", derive(defmt::Format))]
     pub enum FifoThreshold {
         /// 1/4 full.
         QuarterFull,
@@ -318,6 +327,7 @@ pub mod config {
     /// How burst transfers are done, requires fifo enabled. Check datasheet for
     /// valid combinations.
     #[derive(Debug, Clone, Copy)]
+    #[cfg_attr(feature = "defmt", derive(defmt::Format))]
     pub enum BurstMode {
         /// Single transfer, no burst.
         NoBurst,

src/i2c.rs

@@ -54,6 +54,7 @@ pub enum Stop {
 
 /// I2C error
 #[derive(Debug)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
 pub enum Error {
     /// Bus error
@@ -96,6 +97,7 @@ where
 }
 
 #[derive(Debug)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct I2c<I2C> {
     i2c: I2C,
 }

src/lib.rs

@@ -47,13 +47,18 @@
 //! * [Cyclic Redundancy Check (CRC)](crate::crc) Feature gate `crc`
 //! * [Random Number Generator](crate::rng) ([rand_core::RngCore](rand_core::RngCore) is implemented under the `rand` feature gate)
 //! * [System Window Watchdog](crate::watchdog)
+//!
+//! Cargo Features
+//!
+//! * [`defmt`](https://defmt.ferrous-systems.com/) formatting for some types can be enabled with the feature `defmt`.
 
 #![cfg_attr(not(test), no_std)]
 #![allow(non_camel_case_types)]
 
 extern crate paste;
 
 #[derive(Debug)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Never {}
 
 #[cfg(not(feature = "device-selected"))]