itsscb/esp-hal
1
0
Fork 0
mirror of https://github.com/esp-rs/esp-hal.git synced 2025-10-01 06:11:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation fixes (#668)

Browse Source 
* Rustdoc improvements

* Format efuse bracketed names as code

* Fix SPI docs
This commit is contained in:
Dániel Buga 2023-07-24 21:16:48 +02:00 committed by GitHub
parent 2472b6d7a9
commit adeb3c67c8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 53 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.github/workflows/ci.yml vendored
View File

@ -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

1
esp-hal-common/build.rs
View File

@ -250,6 +250,7 @@ fn gen_efuse_table(device_name: &str, out_dir: impl AsRef<Path>) {
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,

12
esp-hal-common/src/analog/adc/cal_curve.rs
View File

@ -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<ADCI> {
line: AdcCalLine<ADCI>,
@ -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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/esp_adc/esp32c3/curve_fitting_coefficients.c>
#[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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/esp_adc/esp32c6/curve_fitting_coefficients.c>
#[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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/esp_adc/esp32s3/curve_fitting_coefficients.c>
#[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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/esp_adc/esp32s3/curve_fitting_coefficients.c>
#[cfg(esp32s3)]
CURVES_COEFFS2 [
Attenuation0dB => [

22
esp-hal-common/src/soc/esp32c2/efuse.rs
View File

@ -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 <https://github.com/espressif/esp-idf/blob/dc016f5987/components/hal/efuse_hal.c#L27-L30>
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 <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>
(
Self::read_field_le::<u8>(BLK_VERSION_MAJOR),
Self::read_field_le::<u8>(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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_rtc_calib.c#L14>
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_rtc_calib.c#L27>
pub fn get_rtc_calib_init_code(_unit: u8, atten: Attenuation) -> Option<u16> {
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_table.csv#L94>
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_table.csv#L95>
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_rtc_calib.c#L65>
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_rtc_calib.c#L65>
pub fn get_rtc_calib_cal_code(_unit: u8, atten: Attenuation) -> Option<u16> {
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_table.csv#L96>
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c2/esp_efuse_table.csv#L97>
let diff_code11: u16 = Self::read_field_le(ADC1_CAL_VOL_ATTEN3);
let code11 = if diff_code0 & (1 << 5) != 0 {
code0 - (diff_code11 & 0x1f)

20
esp-hal-common/src/soc/esp32c3/efuse.rs
View File

@ -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 <https://github.com/espressif/esp-idf/blob/dc016f5987/components/hal/efuse_hal.c#L27-L30>
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 <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>
(
Self::read_field_le::<u8>(BLK_VERSION_MAJOR),
Self::read_field_le::<u8>(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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_rtc_calib.c#L12>
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_rtc_calib.c#L25>
pub fn get_rtc_calib_init_code(_unit: u8, atten: Attenuation) -> Option<u16> {
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_table.csv#L176-L179>
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_rtc_calib.c#L49>
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_rtc_calib.c#L49>
pub fn get_rtc_calib_cal_code(_unit: u8, atten: Attenuation) -> Option<u16> {
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c3/esp_efuse_table.csv#L180-L183>
let cal_code: u16 = Self::read_field_le(match atten {
Attenuation::Attenuation0dB => ADC1_CAL_VOL_ATTEN0,
Attenuation::Attenuation2p5dB => ADC1_CAL_VOL_ATTEN1,

18
esp-hal-common/src/soc/esp32c6/efuse.rs
View File

@ -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 <https://github.com/espressif/esp-idf/blob/dc016f5987/components/hal/efuse_hal.c#L27-L30>
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 <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>
(
Self::read_field_le::<u8>(BLK_VERSION_MAJOR),
Self::read_field_le::<u8>(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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_rtc_calib.c#L20>
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_rtc_calib.c#L32>
pub fn get_rtc_calib_init_code(_unit: u8, atten: Attenuation) -> Option<u16> {
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_table.csv#L147-L152>
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_rtc_calib.c#L42>
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_rtc_calib.c#L42>
pub fn get_rtc_calib_cal_code(_unit: u8, atten: Attenuation) -> Option<u16> {
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 <https://github.com/espressif/esp-idf/blob/903af13e8/components/efuse/esp32c6/esp_efuse_table.csv#L153-L156>
let cal_code: u16 = Self::read_field_le(match atten {
Attenuation::Attenuation0dB => ADC1_CAL_VOL_ATTEN0,
Attenuation::Attenuation2p5dB => ADC1_CAL_VOL_ATTEN1,

17
esp-hal-common/src/spi.rs
View File

@ -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.
@ -2440,7 +2439,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();
@ -2504,7 +2503,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];
@ -2520,7 +2519,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