From 2ff28b14b58d3d726aafc0456143e5022b06f0e6 Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov <62840029+playfulFence@users.noreply.github.com> Date: Tue, 28 Jan 2025 09:55:06 +0100 Subject: [PATCH] Resolve `C-FAILURE` violations (#3036) * progress towards C-FAILURE issues fmt * reviews dumb0 * I2C: FIFO cannot be exceeded fmt --- esp-hal/src/gpio/mod.rs | 24 ++++++++++++++++++++ esp-hal/src/i2c/master/mod.rs | 42 +++++++++++++++++++++++++++++++++++ esp-hal/src/spi/master.rs | 24 ++++++++++++++++++++ esp-hal/src/uart.rs | 16 +++++++++++++ 4 files changed, 106 insertions(+) diff --git a/esp-hal/src/gpio/mod.rs b/esp-hal/src/gpio/mod.rs index af0f1733485..e0309950654 100644 --- a/esp-hal/src/gpio/mod.rs +++ b/esp-hal/src/gpio/mod.rs @@ -743,6 +743,11 @@ impl Io { } /// Set the interrupt priority for GPIO interrupts. + /// + /// # Panics + /// + /// Panics if passed interrupt handler is invalid (e.g. has priority + /// `None`) #[instability::unstable] pub fn set_interrupt_priority(&self, prio: Priority) { unwrap!(interrupt::enable(Interrupt::GPIO, prio)); @@ -761,6 +766,11 @@ impl Io { /// we clear the interrupt status register for you. This is NOT the case /// if you register the interrupt handler directly, by defining a /// `#[no_mangle] unsafe extern "C" fn GPIO()` function. + /// + /// # Panics + /// + /// Panics if passed interrupt handler is invalid (e.g. has priority + /// `None`) #[instability::unstable] pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) { for core in crate::Cpu::other() { @@ -1173,6 +1183,7 @@ impl<'d> Output<'d> { /// blink_once(&mut led, &mut delay); /// # } /// ``` + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. #[inline] pub fn new( pin: impl Peripheral

+ 'd, @@ -1247,6 +1258,7 @@ impl<'d> Output<'d> { } /// Change the configuration. + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. #[inline] pub fn apply_config(&mut self, config: &OutputConfig) { self.pin.apply_output_config(config) @@ -1384,6 +1396,7 @@ impl<'d> Input<'d> { /// print_when_pressed(&mut button, &mut delay); /// # } /// ``` + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. #[inline] pub fn new(pin: impl Peripheral

+ 'd, config: InputConfig) -> Self { let mut pin = Flex::new(pin); @@ -1432,6 +1445,7 @@ impl<'d> Input<'d> { } /// Change the configuration. + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. pub fn apply_config(&mut self, config: &InputConfig) { self.pin.apply_input_config(config) } @@ -1536,6 +1550,11 @@ impl<'d> Input<'d> { /// Enable as a wake-up source. /// /// This will unlisten for interrupts + /// + /// # Error + /// Configuring pin to wake up from light sleep on an edge + /// trigger is currently not supported, corresponding variant of + /// [`WakeConfigError`] will be returned. #[instability::unstable] #[inline] pub fn wakeup_enable(&mut self, enable: bool, event: WakeEvent) -> Result<(), WakeConfigError> { @@ -1746,6 +1765,11 @@ impl<'d> Flex<'d> { /// Enable as a wake-up source. /// /// This will unlisten for interrupts + /// + /// # Error + /// Configuring pin to wake up from light sleep on an edge + /// trigger is currently not supported, corresponding variant of + /// [`WakeConfigError`] will be returned. #[inline] #[instability::unstable] pub fn wakeup_enable(&mut self, enable: bool, event: WakeEvent) -> Result<(), WakeConfigError> { diff --git a/esp-hal/src/i2c/master/mod.rs b/esp-hal/src/i2c/master/mod.rs index a4bca672468..a754c223eb6 100644 --- a/esp-hal/src/i2c/master/mod.rs +++ b/esp-hal/src/i2c/master/mod.rs @@ -496,6 +496,11 @@ impl<'d, Dm: DriverMode> I2c<'d, Dm> { } /// Applies a new configuration. + /// + /// # Errors + /// + /// A [`ConfigError`] variant will be returned if bus frequency or timeout + /// passed in config is invalid. pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> { self.driver().setup(config)?; self.config = *config; @@ -595,6 +600,11 @@ impl<'d, Dm: DriverMode> I2c<'d, Dm> { impl<'d> I2c<'d, Blocking> { /// Create a new I2C instance. + /// + /// # Errors + /// + /// A [`ConfigError`] variant will be returned if bus frequency or timeout + /// passed in config is invalid. pub fn new( i2c: impl Peripheral

+ 'd, config: Config, @@ -634,6 +644,11 @@ impl<'d> I2c<'d, Blocking> { /// /// You can restore the default/unhandled interrupt handler by using /// [crate::DEFAULT_INTERRUPT_HANDLER] + /// + /// # Panics + /// + /// Panics if passed interrupt handler is invalid (e.g. has priority + /// `None`) #[instability::unstable] pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) { self.i2c.info().set_interrupt_handler(handler); @@ -710,6 +725,10 @@ impl<'d> I2c<'d, Blocking> { /// i2c.read(DEVICE_ADDR, &mut data).ok(); /// # } /// ``` + /// + /// # Errors + /// + /// The corresponding error variant from [`Error`] will be returned if the passed buffer has zero length. pub fn read>( &mut self, address: A, @@ -735,6 +754,10 @@ impl<'d> I2c<'d, Blocking> { /// i2c.write_read(DEVICE_ADDR, &[0xaa], &mut data).ok(); /// # } /// ``` + /// + /// # Errors + /// + /// The corresponding error variant from [`Error`] will be returned if the passed buffer has zero length. pub fn write_read>( &mut self, address: A, @@ -789,6 +812,10 @@ impl<'d> I2c<'d, Blocking> { /// ).ok(); /// # } /// ``` + /// + /// # Errors + /// + /// The corresponding error variant from [`Error`] will be returned if the buffer passed to an [`Operation`] has zero length. pub fn transaction<'a, A: Into>( &mut self, address: A, @@ -944,6 +971,11 @@ impl<'d> I2c<'d, Async> { } /// Reads enough bytes from slave with `address` to fill `buffer` + /// + /// # Errors + /// + /// The corresponding error variant from [`Error`] will be returned if the + /// passed buffer has zero length. pub async fn read>( &mut self, address: A, @@ -957,6 +989,11 @@ impl<'d> I2c<'d, Async> { /// Writes bytes to slave with address `address` and then reads enough /// bytes to fill `buffer` *in a single transaction* + /// + /// # Errors + /// + /// The corresponding error variant from [`Error`] will be returned if the + /// passed buffer has zero length. pub async fn write_read>( &mut self, address: A, @@ -997,6 +1034,11 @@ impl<'d> I2c<'d, Async> { /// to indicate writing /// - `SR` = repeated start condition /// - `SP` = stop condition + /// + /// # Errors + /// + /// The corresponding error variant from [`Error`] will be returned if the + /// buffer passed to an [`Operation`] has zero length. pub async fn transaction<'a, A: Into>( &mut self, address: A, diff --git a/esp-hal/src/spi/master.rs b/esp-hal/src/spi/master.rs index 2049004d265..b8cd3aadf4d 100644 --- a/esp-hal/src/spi/master.rs +++ b/esp-hal/src/spi/master.rs @@ -534,6 +534,7 @@ where impl<'d> Spi<'d, Blocking> { /// Constructs an SPI instance in 8bit dataframe mode. + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. pub fn new( spi: impl Peripheral

+ 'd, config: Config, @@ -658,6 +659,11 @@ impl<'d> Spi<'d, Blocking> { /// /// You can restore the default/unhandled interrupt handler by using /// [crate::interrupt::DEFAULT_INTERRUPT_HANDLER] + /// + /// # Panics + /// + /// Panics if passed interrupt handler is invalid (e.g. has priority + /// `None`) #[instability::unstable] pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) { let interrupt = self.driver().info.interrupt; @@ -843,6 +849,7 @@ where } /// Change the bus configuration. + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> { self.driver().apply_config(config) } @@ -928,6 +935,12 @@ where Dm: DriverMode, { /// Half-duplex read. + /// + /// # Errors + /// + /// The corresponding error variant from [`Error`] will be returned if + /// passed buffer is bigger than FIFO size or if buffer is empty (currently + /// unsupported). #[instability::unstable] pub fn half_duplex_read( &mut self, @@ -962,6 +975,15 @@ where } /// Half-duplex write. + /// + /// # Errors + /// + /// The corresponding error variant from [`Error`] will be returned if + /// passed buffer is bigger than FIFO size. + #[cfg_attr( + esp32, + doc = "Dummy phase configuration is currently not supported, only value `0` is valid (see issue [#2240](https://github.com/esp-rs/esp-hal/issues/2240))." + )] #[instability::unstable] pub fn half_duplex_write( &mut self, @@ -1402,6 +1424,7 @@ mod dma { } /// Change the bus configuration. + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. #[instability::unstable] pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> { self.driver().apply_config(config) @@ -1864,6 +1887,7 @@ mod dma { } /// Change the bus configuration. + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. #[instability::unstable] pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> { self.spi_dma.apply_config(config) diff --git a/esp-hal/src/uart.rs b/esp-hal/src/uart.rs index 06d97eeac81..143cf66aceb 100644 --- a/esp-hal/src/uart.rs +++ b/esp-hal/src/uart.rs @@ -559,6 +559,7 @@ where /// Change the configuration. /// /// Note that this also changes the configuration of the RX half. + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. #[instability::unstable] pub fn apply_config(&mut self, _config: &Config) -> Result<(), ConfigError> { // Nothing to do so far. @@ -752,6 +753,7 @@ where /// Change the configuration. /// /// Note that this also changes the configuration of the TX half. + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. #[instability::unstable] pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> { self.uart @@ -986,6 +988,7 @@ impl<'d> Uart<'d, Blocking> { /// .with_tx(peripherals.GPIO2); /// # } /// ``` + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. pub fn new( uart: impl Peripheral

+ 'd, config: Config, @@ -1176,6 +1179,7 @@ where } /// Change the configuration. + // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry. pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> { self.rx.apply_config(config)?; self.tx.apply_config(config)?; @@ -1853,6 +1857,12 @@ pub mod lp_uart { impl LpUart { /// Initialize the UART driver using the provided configuration + /// + /// # Panics + /// + /// [`Apb`] is a wrong clock source for LP_UART + /// + /// [`Apb`]: super::ClockSource::Apb // TODO: CTS and RTS pins pub fn new( uart: LP_UART, @@ -1988,6 +1998,12 @@ pub mod lp_uart { } /// Modify UART baud rate and reset TX/RX fifo. + /// + /// # Panics + /// + /// [`Apb`] is a wrong clock source for LP_UART + /// + /// [`Apb`]: super::ClockSource::Apb pub fn change_baud(&mut self, baudrate: u32, clock_source: super::ClockSource) { self.change_baud_internal(baudrate, clock_source); self.txfifo_reset();