diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4702cf30c64..78a2a8b259f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -59,7 +59,7 @@ jobs: run: cd esp-hal-smartled/ && cargo +esp check --features=esp32s3 # Ensure documentation can be built (requires a chip feature!) - name: rustdoc - run: cd esp-hal-smartled/ && cargo doc --features=esp32c3 + run: cd esp-hal-smartled/ && cargo doc --features=esp32c3,esp-hal-common/eh1 esp32-hal: runs-on: ubuntu-latest @@ -93,7 +93,7 @@ jobs: run: cd esp32-hal/ && cargo check --example=embassy_i2c --features=embassy,embassy-time-timg0,async # Ensure documentation can be built - name: rustdoc - run: cd esp32-hal/ && cargo doc + run: cd esp32-hal/ && cargo doc --features=eh1 esp32c2-hal: runs-on: ubuntu-latest @@ -135,7 +135,7 @@ jobs: run: cd esp32c2-hal/ && cargo check --example=interrupt_preemption --features=interrupt-preemption # Ensure documentation can be built - name: rustdoc - run: cd esp32c2-hal/ && cargo doc + run: cd esp32c2-hal/ && cargo doc --features=eh1 esp32c3-hal: runs-on: ubuntu-latest @@ -179,7 +179,7 @@ jobs: run: cd esp32c3-hal/ && cargo check --example=interrupt_preemption --features=interrupt-preemption # Ensure documentation can be built - name: rustdoc - run: cd esp32c3-hal/ && cargo doc + run: cd esp32c3-hal/ && cargo doc --features=eh1 esp32c6-hal: runs-on: ubuntu-latest @@ -221,7 +221,7 @@ jobs: run: cd esp32c6-hal/ && cargo check --example=interrupt_preemption --features=interrupt-preemption # Ensure documentation can be built - name: rustdoc - run: cd esp32c6-hal/ && cargo doc + run: cd esp32c6-hal/ && cargo doc --features=eh1 esp32h2-hal: runs-on: ubuntu-latest @@ -263,7 +263,7 @@ jobs: run: cd esp32h2-hal/ && cargo check --example=interrupt_preemption --features=interrupt-preemption # Ensure documentation can be built - name: rustdoc - run: cd esp32h2-hal/ && cargo doc + run: cd esp32h2-hal/ && cargo doc --features=eh1 esp32s2-hal: runs-on: ubuntu-latest @@ -300,7 +300,7 @@ jobs: run: cd esp32s2-hal/ && cargo check --example=embassy_i2c --features=embassy,embassy-time-timg0,async # Ensure documentation can be built - name: rustdoc - run: cd esp32s2-hal/ && cargo doc + run: cd esp32s2-hal/ && cargo doc --features=eh1 esp32s3-hal: runs-on: ubuntu-latest @@ -342,7 +342,7 @@ jobs: run: cd esp32s3-hal/ && cargo check --example=octal_psram --features=opsram_2m --release # This example requires release! # Ensure documentation can be built - name: rustdoc - run: cd esp32s3-hal/ && cargo doc + run: cd esp32s3-hal/ && cargo doc --features=eh1 esp-riscv-rt: runs-on: ubuntu-latest diff --git a/esp-hal-common/build.rs b/esp-hal-common/build.rs index 5981d1d7f87..240f853575a 100644 --- a/esp-hal-common/build.rs +++ b/esp-hal-common/build.rs @@ -250,6 +250,7 @@ fn gen_efuse_table(device_name: &str, out_dir: impl AsRef) { fields.next().map(|s| s.trim()), ) { (Some(name), Some(block), Some(bit_off), Some(bit_len), Some(desc)) => { + let desc = desc.replace('[', "`[").replace(']', "]`"); writeln!(writer, "/// {desc}").unwrap(); writeln!( writer, diff --git a/esp-hal-common/src/analog/adc/cal_curve.rs b/esp-hal-common/src/analog/adc/cal_curve.rs index 1beaa542a82..9809d63e152 100644 --- a/esp-hal-common/src/analog/adc/cal_curve.rs +++ b/esp-hal-common/src/analog/adc/cal_curve.rs @@ -38,8 +38,8 @@ pub trait AdcHasCurveCal { /// This scheme implements final polynomial error correction using predefined /// coefficient sets for each attenuation. /// -/// This scheme also includes basic calibration ([`AdcCalBasic`]) and line -/// fitting ([`AdcCalLine`]). +/// This scheme also includes basic calibration ([`super::AdcCalBasic`]) and +/// line fitting ([`AdcCalLine`]). #[derive(Clone, Copy)] pub struct AdcCalCurve { line: AdcCalLine, @@ -131,7 +131,7 @@ mod impls { } coeff_tables! { - /// Error curve coefficients derived from https://github.com/espressif/esp-idf/blob/903af13e8/components/esp_adc/esp32c3/curve_fitting_coefficients.c + /// Error curve coefficients derived from #[cfg(esp32c3)] CURVES_COEFFS1 [ Attenuation0dB => [ @@ -158,7 +158,7 @@ mod impls { ], ]; - /// Error curve coefficients derived from https://github.com/espressif/esp-idf/blob/903af13e8/components/esp_adc/esp32c6/curve_fitting_coefficients.c + /// Error curve coefficients derived from #[cfg(esp32c6)] CURVES_COEFFS1 [ Attenuation0dB => [ @@ -183,7 +183,7 @@ mod impls { ], ]; - /// Error curve coefficients derived from https://github.com/espressif/esp-idf/blob/903af13e8/components/esp_adc/esp32s3/curve_fitting_coefficients.c + /// Error curve coefficients derived from #[cfg(esp32s3)] CURVES_COEFFS1 [ Attenuation0dB => [ @@ -210,7 +210,7 @@ mod impls { ], ]; - /// Error curve coefficients derived from https://github.com/espressif/esp-idf/blob/903af13e8/components/esp_adc/esp32s3/curve_fitting_coefficients.c + /// Error curve coefficients derived from #[cfg(esp32s3)] CURVES_COEFFS2 [ Attenuation0dB => [ diff --git a/esp-hal-common/src/soc/esp32c2/efuse.rs b/esp-hal-common/src/soc/esp32c2/efuse.rs index 7519566c940..8e456a47cf0 100644 --- a/esp-hal-common/src/soc/esp32c2/efuse.rs +++ b/esp-hal-common/src/soc/esp32c2/efuse.rs @@ -39,10 +39,10 @@ impl Efuse { /// Get efuse block version /// - /// see https://github.com/espressif/esp-idf/blob/dc016f5987/components/hal/efuse_hal.c#L27-L30 + /// see pub fn get_block_version() -> (u8, u8) { - // see https://github.com/espressif/esp-idf/blob/dc016f5987/components/hal/esp32c2/include/hal/efuse_ll.h#L65-L73 - // https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_table.csv#L90-L91 + // see + // ( Self::read_field_le::(BLK_VERSION_MAJOR), Self::read_field_le::(BLK_VERSION_MINOR), @@ -51,7 +51,7 @@ impl Efuse { /// Get version of RTC calibration block /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_rtc_calib.c#L14 + /// see pub fn get_rtc_calib_version() -> u8 { let (major, _minor) = Self::get_block_version(); if major == 0 { @@ -63,7 +63,7 @@ impl Efuse { /// Get ADC initial code for specified attenuation from efuse /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_rtc_calib.c#L27 + /// see pub fn get_rtc_calib_init_code(_unit: u8, atten: Attenuation) -> Option { let version = Self::get_rtc_calib_version(); @@ -71,7 +71,7 @@ impl Efuse { return None; } - // see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_table.csv#L94 + // see let diff_code0: u16 = Self::read_field_le(ADC1_INIT_CODE_ATTEN0); let code0 = if diff_code0 & (1 << 7) != 0 { 2160 - (diff_code0 & 0x7f) @@ -83,7 +83,7 @@ impl Efuse { return Some(code0); } - // see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_table.csv#L95 + // see let diff_code11: u16 = Self::read_field_le(ADC1_INIT_CODE_ATTEN3); let code11 = code0 + diff_code11; @@ -92,7 +92,7 @@ impl Efuse { /// Get ADC reference point voltage for specified attenuation in millivolts /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_rtc_calib.c#L65 + /// see pub fn get_rtc_calib_cal_mv(_unit: u8, atten: Attenuation) -> u16 { match atten { Attenuation::Attenuation0dB => 400, @@ -102,7 +102,7 @@ impl Efuse { /// Get ADC reference point digital code for specified attenuation /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_rtc_calib.c#L65 + /// see pub fn get_rtc_calib_cal_code(_unit: u8, atten: Attenuation) -> Option { let version = Self::get_rtc_calib_version(); @@ -110,7 +110,7 @@ impl Efuse { return None; } - // see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_table.csv#L96 + // see let diff_code0: u16 = Self::read_field_le(ADC1_CAL_VOL_ATTEN0); let code0 = if diff_code0 & (1 << 7) != 0 { 1540 - (diff_code0 & 0x7f) @@ -122,7 +122,7 @@ impl Efuse { return Some(code0); } - // see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_table.csv#L97 + // see let diff_code11: u16 = Self::read_field_le(ADC1_CAL_VOL_ATTEN3); let code11 = if diff_code0 & (1 << 5) != 0 { code0 - (diff_code11 & 0x1f) diff --git a/esp-hal-common/src/soc/esp32c3/efuse.rs b/esp-hal-common/src/soc/esp32c3/efuse.rs index 25a4b61f98a..5fd1501202b 100644 --- a/esp-hal-common/src/soc/esp32c3/efuse.rs +++ b/esp-hal-common/src/soc/esp32c3/efuse.rs @@ -39,11 +39,11 @@ impl Efuse { /// Get efuse block version /// - /// see https://github.com/espressif/esp-idf/blob/dc016f5987/components/hal/efuse_hal.c#L27-L30 + /// see pub fn get_block_version() -> (u8, u8) { - // see https://github.com/espressif/esp-idf/blob/dc016f5987/components/hal/esp32c3/include/hal/efuse_ll.h#L70-L78 - // https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_table.csv#L163 - // https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_table.csv#L173 + // see + // + // ( Self::read_field_le::(BLK_VERSION_MAJOR), Self::read_field_le::(BLK_VERSION_MINOR), @@ -52,7 +52,7 @@ impl Efuse { /// Get version of RTC calibration block /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_rtc_calib.c#L12 + /// see pub fn get_rtc_calib_version() -> u8 { let (major, _minor) = Self::get_block_version(); if major == 1 { @@ -64,7 +64,7 @@ impl Efuse { /// Get ADC initial code for specified attenuation from efuse /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_rtc_calib.c#L25 + /// see pub fn get_rtc_calib_init_code(_unit: u8, atten: Attenuation) -> Option { let version = Self::get_rtc_calib_version(); @@ -72,7 +72,7 @@ impl Efuse { return None; } - // See https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_table.csv#L176-L179 + // See let init_code: u16 = Self::read_field_le(match atten { Attenuation::Attenuation0dB => ADC1_INIT_CODE_ATTEN0, Attenuation::Attenuation2p5dB => ADC1_INIT_CODE_ATTEN1, @@ -85,7 +85,7 @@ impl Efuse { /// Get ADC reference point voltage for specified attenuation in millivolts /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_rtc_calib.c#L49 + /// see pub fn get_rtc_calib_cal_mv(_unit: u8, atten: Attenuation) -> u16 { match atten { Attenuation::Attenuation0dB => 400, @@ -97,7 +97,7 @@ impl Efuse { /// Get ADC reference point digital code for specified attenuation /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_rtc_calib.c#L49 + /// see pub fn get_rtc_calib_cal_code(_unit: u8, atten: Attenuation) -> Option { let version = Self::get_rtc_calib_version(); @@ -105,7 +105,7 @@ impl Efuse { return None; } - // See https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_table.csv#L180-L183 + // See let cal_code: u16 = Self::read_field_le(match atten { Attenuation::Attenuation0dB => ADC1_CAL_VOL_ATTEN0, Attenuation::Attenuation2p5dB => ADC1_CAL_VOL_ATTEN1, diff --git a/esp-hal-common/src/soc/esp32c6/efuse.rs b/esp-hal-common/src/soc/esp32c6/efuse.rs index bb502c822b5..4f22dc9f9ae 100644 --- a/esp-hal-common/src/soc/esp32c6/efuse.rs +++ b/esp-hal-common/src/soc/esp32c6/efuse.rs @@ -39,10 +39,10 @@ impl Efuse { /// Get efuse block version /// - /// see https://github.com/espressif/esp-idf/blob/dc016f5987/components/hal/efuse_hal.c#L27-L30 + /// see pub fn get_block_version() -> (u8, u8) { - // see https://github.com/espressif/esp-idf/blob/dc016f5987/components/hal/esp32c6/include/hal/efuse_ll.h#L65-L73 - // https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_table.csv#L156 + // see + // ( Self::read_field_le::(BLK_VERSION_MAJOR), Self::read_field_le::(BLK_VERSION_MINOR), @@ -51,7 +51,7 @@ impl Efuse { /// Get version of RTC calibration block /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_rtc_calib.c#L20 + /// see pub fn get_rtc_calib_version() -> u8 { let (_major, minor) = Self::get_block_version(); if minor >= 1 { @@ -63,7 +63,7 @@ impl Efuse { /// Get ADC initial code for specified attenuation from efuse /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_rtc_calib.c#L32 + /// see pub fn get_rtc_calib_init_code(_unit: u8, atten: Attenuation) -> Option { let version = Self::get_rtc_calib_version(); @@ -71,7 +71,7 @@ impl Efuse { return None; } - // See https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_table.csv#L147-L152 + // See let init_code: u16 = Self::read_field_le(match atten { Attenuation::Attenuation0dB => ADC1_INIT_CODE_ATTEN0, Attenuation::Attenuation2p5dB => ADC1_INIT_CODE_ATTEN1, @@ -84,7 +84,7 @@ impl Efuse { /// Get ADC reference point voltage for specified attenuation in millivolts /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_rtc_calib.c#L42 + /// see pub fn get_rtc_calib_cal_mv(_unit: u8, atten: Attenuation) -> u16 { match atten { Attenuation::Attenuation0dB => 400, @@ -96,7 +96,7 @@ impl Efuse { /// Get ADC reference point digital code for specified attenuation /// - /// see https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_rtc_calib.c#L42 + /// see pub fn get_rtc_calib_cal_code(_unit: u8, atten: Attenuation) -> Option { let version = Self::get_rtc_calib_version(); @@ -104,7 +104,7 @@ impl Efuse { return None; } - // See https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_table.csv#L153-L156 + // See let cal_code: u16 = Self::read_field_le(match atten { Attenuation::Attenuation0dB => ADC1_CAL_VOL_ATTEN0, Attenuation::Attenuation2p5dB => ADC1_CAL_VOL_ATTEN1, diff --git a/esp-hal-common/src/spi.rs b/esp-hal-common/src/spi.rs index 35b47bbc815..3420bcf6e59 100644 --- a/esp-hal-common/src/spi.rs +++ b/esp-hal-common/src/spi.rs @@ -34,17 +34,16 @@ //! - Use the [`SpiBus`](embedded_hal_1::spi::SpiBus) trait (requires the "eh1" //! feature) and its associated functions to initiate transactions with //! simultaneous reads and writes, or -//! - Use the [`SpiBusWrite`](embedded_hal_1::spi::SpiBusWrite) and -//! [`SpiBusRead`](embedded_hal_1::spi::SpiBusRead) traits (requires the "eh1" -//! feature) and their associated functions to read or write mutiple bytes at -//! a time. +// TODO async moved to embedded-hal-bus: +//! - Use the `ExclusiveDevice` struct from `embedded-hal-bus` or +//! `embedded-hal-async` (recommended). //! //! //! ## Shared SPI access //! //! If you have multiple devices on the same SPI bus that each have their own CS -//! line, you may want to have a look at the [`SpiBusController`] and -//! [`SpiBusDevice`] implemented here. These give exclusive access to the +//! line, you may want to have a look at the [`ehal1::SpiBusController`] and +//! [`ehal1::SpiBusDevice`] implemented here. These give exclusive access to the //! underlying SPI bus by means of a Mutex. This ensures that device //! transactions do not interfere with each other. @@ -2408,7 +2407,7 @@ pub trait Instance { /// sequential transfers are performed. This function will return before /// all bytes of the last chunk to transmit have been sent to the wire. If /// you must ensure that the whole messages was written correctly, use - /// [`flush`]. + /// [`Self::flush`]. // FIXME: See below. fn write_bytes(&mut self, words: &[u8]) -> Result<(), Error> { let reg_block = self.register_block(); @@ -2472,7 +2471,7 @@ pub trait Instance { /// /// Sends out a stuffing byte for every byte to read. This function doesn't /// perform flushing. If you want to read the response to something you - /// have written before, consider using [`transfer`] instead. + /// have written before, consider using [`Self::transfer`] instead. fn read_bytes(&mut self, words: &mut [u8]) -> Result<(), Error> { let empty_array = [EMPTY_WRITE_PAD; FIFO_SIZE]; @@ -2488,7 +2487,7 @@ pub trait Instance { /// /// Copies the contents of the SPI receive FIFO into `words`. This function /// doesn't perform flushing. If you want to read the response to - /// something you have written before, consider using [`transfer`] + /// something you have written before, consider using [`Self::transfer`] /// instead. // FIXME: Using something like `core::slice::from_raw_parts` and // `copy_from_slice` on the receive registers works only for the esp32 and