Merge remote-tracking branch 'upstream/main' into i8080_move_api

# Conflicts:
#	esp-hal/src/dma/mod.rs

.github/workflows/documentation.yml

@@ -2,12 +2,33 @@ name: Documentation
 
 on:
   workflow_dispatch:
+    inputs:
+      esp-hal:
+        description: "esp-hal tag"
+        required: true
+      esp-wifi:
+        description: "esp-wifi tag"
+        required: true
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      packages: '[
+            { "name": "esp-hal",  "tag": "${{ github.event.inputs.esp-hal }}" },
+            { "name": "esp-wifi", "tag": "esp-wifi-${{ github.event.inputs.esp-wifi }}" }
+          ]'
+    steps:
+      - run: echo "Setup complete!"
   build:
+    needs: setup
+    strategy:
+      fail-fast: true
+      matrix:
+        packages: ${{ fromJson(needs.setup.outputs.packages) }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -16,21 +37,48 @@ jobs:
           default: true
           ldproxy: false
 
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          repository: esp-rs/esp-hal
+          ref: ${{ matrix.packages.tag }}
+
       - name: Build documentation
-        run: cargo xtask build-documentation --packages=esp-hal,esp-wifi
+        run: cargo xtask build-documentation --packages=${{ matrix.packages.name }}
 
       # https://github.com/actions/deploy-pages/issues/303#issuecomment-1951207879
       - name: Remove problematic '.lock' files
         run: find docs -name ".lock" -exec rm -f {} \;
 
+      - name: Upload docs for ${{ matrix.packages.name }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.packages.name }}
+          path: "docs/${{ matrix.packages.name }}"
+
+  assemble:
+    needs: [setup, build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Prepare
+        run: mkdir docs
+      - name: Download all docs
+        uses: actions/download-artifact@v4
+        with:
+          path: "docs/"
+
+      - name: Create index.html
+        run: "cargo xtask build-documentation-index --packages=$(echo '${{ needs.setup.outputs.packages }}' | jq -r '[.[].name] | join(\",\")')"
+
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: "docs"
+          path: "docs/"
 
   deploy:
-    # Add a dependency to the build job:
-    needs: build
+    # Add a dependency to the assemble job:
+    needs: assemble
 
     # Grant GITHUB_TOKEN the permissions required to make a Pages deployment:
     permissions:

esp-config/src/generate.rs

@@ -126,14 +126,18 @@ fn env_change_work_around() {
 
     let dotcargo = out_dir.join(".cargo/");
     if dotcargo.exists() {
-        println!(
-            "cargo:rerun-if-changed={}",
-            dotcargo.clone().join("config.toml").to_str().unwrap()
-        );
-        println!(
-            "cargo:rerun-if-changed={}",
-            dotcargo.clone().join("config").to_str().unwrap()
-        );
+        if dotcargo.join("config.toml").exists() {
+            println!(
+                "cargo:rerun-if-changed={}",
+                dotcargo.join("config.toml").display()
+            );
+        }
+        if dotcargo.join("config").exists() {
+            println!(
+                "cargo:rerun-if-changed={}",
+                dotcargo.join("config").display()
+            );
+        }
     }
 }
 

esp-hal/CHANGELOG.md

@@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Implement `TryFrom<u32>` for `ledc::timer::config::Duty` (#1984)
 - Expose `RtcClock::get_xtal_freq` and `RtcClock::get_slow_freq` publically for all chips (#2183)
 - TWAI support for ESP32-H2 (#2199)
+- Make `DmaDescriptor` methods public (#2237)
 - Added a way to configure watchdogs in `esp_hal::init` (#2180)
 - Implement `embedded_hal_async::delay::DelayNs` for `TIMGx` timers (#2084)
 
@@ -73,6 +74,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - SPI: Fixed an issue where `wait` has returned before the DMA has finished writing the memory (#2179)
 - SPI: Fixed an issue where repeated calls to `dma_transfer` may end up looping indefinitely (#2179)
 - SPI: Fixed an issue that prevented correctly reading the first byte in a transaction (#2179)
+- SPI: ESP32: Send address with correct data mode even when no data is sent. (#2231)
 - PARL_IO: Fixed an issue that caused garbage to be output at the start of some requests (#2211)
 - TWAI on ESP32 (#2207)
 

esp-hal/build.rs

@@ -128,11 +128,18 @@ fn main() -> Result<(), Box<dyn Error>> {
     // emit config
     generate_config(
         "esp_hal",
-        &[(
-            "place-spi-driver-in-ram",
-            Value::Bool(false),
-            "Places the SPI driver in RAM for better performance",
-        )],
+        &[
+            (
+                "place-spi-driver-in-ram",
+                Value::Bool(false),
+                "Places the SPI driver in RAM for better performance",
+            ),
+            (
+                "spi-address-workaround",
+                Value::Bool(true),
+                "(ESP32 only) Enables a workaround for the issue where SPI in half-duplex mode incorrectly transmits the address on a single line if the data buffer is empty.",
+            ),
+        ],
         true,
     );
 

esp-hal/src/dma/gdma.rs

@@ -231,6 +231,12 @@ impl<const N: u8> RegisterAccess for Channel<N> {
             .modify(|_, w| w.inlink_start().set_bit());
     }
 
+    fn stop_in() {
+        Self::ch()
+            .in_link()
+            .modify(|_, w| w.inlink_stop().set_bit());
+    }
+
     fn listen_out(interrupts: impl Into<EnumSet<DmaTxInterrupt>>) {
         Self::out_int().ena().modify(|_, w| {
             for interrupt in interrupts.into() {

esp-hal/src/dma/mod.rs

@@ -203,15 +203,36 @@ where
 }
 
 bitfield::bitfield! {
-    #[doc(hidden)]
+    /// DMA descriptor flags.
     #[derive(Clone, Copy)]
     pub struct DmaDescriptorFlags(u32);
 
     u16;
-    size, set_size: 11, 0;
-    length, set_length: 23, 12;
-    suc_eof, set_suc_eof: 30;
-    owner, set_owner: 31;
+
+    /// Specifies the size of the buffer that this descriptor points to.
+    pub size, set_size: 11, 0;
+
+    /// Specifies the number of valid bytes in the buffer that this descriptor points to.
+    ///
+    /// This field in a transmit descriptor is written by software and indicates how many bytes can
+    /// be read from the buffer.
+    ///
+    /// This field in a receive descriptor is written by hardware automatically and indicates how
+    /// many valid bytes have been stored into the buffer.
+    pub length, set_length: 23, 12;
+
+    /// For receive descriptors, software needs to clear this bit to 0, and hardware will set it to 1 after receiving
+    /// data containing the EOF flag.
+    /// For transmit descriptors, software needs to set this bit to 1 as needed.
+    /// If software configures this bit to 1 in a descriptor, the DMA will include the EOF flag in the data sent to
+    /// the corresponding peripheral, indicating to the peripheral that this data segment marks the end of one
+    /// transfer phase.
+    pub suc_eof, set_suc_eof: 30;
+
+    /// Specifies who is allowed to access the buffer that this descriptor points to.
+    /// - 0: CPU can access the buffer;
+    /// - 1: The GDMA controller can access the buffer.
+    pub owner, set_owner: 31;
 }
 
 impl Debug for DmaDescriptorFlags {
@@ -243,9 +264,16 @@ impl defmt::Format for DmaDescriptorFlags {
 #[derive(Clone, Copy, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct DmaDescriptor {
-    pub(crate) flags: DmaDescriptorFlags,
-    pub(crate) buffer: *mut u8,
-    pub(crate) next: *mut DmaDescriptor,
+    /// Descriptor flags.
+    pub flags: DmaDescriptorFlags,
+
+    /// Address of the buffer.
+    pub buffer: *mut u8,
+
+    /// Address of the next descriptor.
+    /// If the current descriptor is the last one, this value is 0.
+    /// This field can only point to internal RAM.
+    pub next: *mut DmaDescriptor,
 }
 
 impl DmaDescriptor {
@@ -256,36 +284,43 @@ impl DmaDescriptor {
         next: core::ptr::null_mut(),
     };
 
-    fn set_size(&mut self, len: usize) {
+    /// Set the size of the buffer. See [DmaDescriptorFlags::size].
+    pub fn set_size(&mut self, len: usize) {
         self.flags.set_size(len as u16)
     }
 
-    fn set_length(&mut self, len: usize) {
+    /// Set the length of the descriptor. See [DmaDescriptorFlags::length].
+    pub fn set_length(&mut self, len: usize) {
         self.flags.set_length(len as u16)
     }
 
-    #[allow(unused)]
-    fn size(&self) -> usize {
+    /// Returns the size of the buffer. See [DmaDescriptorFlags::size].
+    pub fn size(&self) -> usize {
         self.flags.size() as usize
     }
 
-    fn len(&self) -> usize {
+    /// Returns the length of the descriptor. See [DmaDescriptorFlags::length].
+    #[allow(clippy::len_without_is_empty)]
+    pub fn len(&self) -> usize {
         self.flags.length() as usize
     }
 
-    fn set_suc_eof(&mut self, suc_eof: bool) {
+    /// Set the suc_eof bit. See [DmaDescriptorFlags::suc_eof].
+    pub fn set_suc_eof(&mut self, suc_eof: bool) {
         self.flags.set_suc_eof(suc_eof)
     }
 
-    fn set_owner(&mut self, owner: Owner) {
+    /// Set the owner. See [DmaDescriptorFlags::owner].
+    pub fn set_owner(&mut self, owner: Owner) {
         let owner = match owner {
             Owner::Cpu => false,
             Owner::Dma => true,
         };
         self.flags.set_owner(owner)
     }
 
-    fn owner(&self) -> Owner {
+    /// Returns the owner. See [DmaDescriptorFlags::owner].
+    pub fn owner(&self) -> Owner {
         match self.flags.owner() {
             false => Owner::Cpu,
             true => Owner::Dma,
@@ -479,7 +514,7 @@ macro_rules! declare_aligned_dma_buffer {
 #[doc(hidden)]
 #[macro_export]
 macro_rules! as_mut_byte_array {
-    ($name:ident, $size:expr) => {
+    ($name:expr, $size:expr) => {
         unsafe { &mut *($name.as_mut_ptr() as *mut [u8; $size]) }
     };
 }
@@ -696,6 +731,18 @@ pub enum DmaError {
     InvalidChunkSize,
 }
 
+impl From<DmaBufError> for DmaError {
+    fn from(error: DmaBufError) -> Self {
+        // FIXME: use nested errors
+        match error {
+            DmaBufError::InsufficientDescriptors => DmaError::OutOfDescriptors,
+            DmaBufError::UnsupportedMemoryRegion => DmaError::UnsupportedMemoryRegion,
+            DmaBufError::InvalidAlignment => DmaError::InvalidAlignment,
+            DmaBufError::InvalidChunkSize => DmaError::InvalidChunkSize,
+        }
+    }
+}
+
 /// DMA Priorities
 #[cfg(gdma)]
 #[derive(Debug, Clone, Copy, PartialEq)]
@@ -780,9 +827,12 @@ pub enum DmaPeripheral {
     Mem2Mem15 = 15,
 }
 
+/// The owner bit of a DMA descriptor.
 #[derive(PartialEq, PartialOrd)]
-enum Owner {
+pub enum Owner {
+    /// Owned by CPU
     Cpu = 0,
+    /// Owned by DMA
     Dma = 1,
 }
 
@@ -1328,6 +1378,8 @@ pub trait Rx: crate::private::Sealed {
 
     fn start_transfer(&mut self) -> Result<(), DmaError>;
 
+    fn stop_transfer(&mut self);
+
     #[cfg(esp32s3)]
     fn set_ext_mem_block_size(&self, size: DmaExtMemBKSize);
 
@@ -1405,6 +1457,10 @@ where
         }
     }
 
+    fn stop_transfer(&mut self) {
+        R::stop_in();
+    }
+
     fn waker() -> &'static embassy_sync::waitqueue::AtomicWaker;
 }
 
@@ -1499,6 +1555,10 @@ where
         self.rx_impl.start_transfer()
     }
 
+    fn stop_transfer(&mut self) {
+        self.rx_impl.stop_transfer()
+    }
+
     #[cfg(esp32s3)]
     fn set_ext_mem_block_size(&self, size: DmaExtMemBKSize) {
         CH::Channel::set_in_ext_mem_block_size(size);
@@ -1630,7 +1690,7 @@ where
     }
 
     fn stop_transfer(&mut self) {
-        R::stop_out()
+        R::stop_out();
     }
 
     fn listen_out(&self, interrupts: impl Into<EnumSet<DmaTxInterrupt>>) {
@@ -1740,7 +1800,7 @@ where
     }
 
     fn stop_transfer(&mut self) {
-        self.tx_impl.stop_transfer();
+        self.tx_impl.stop_transfer()
     }
 
     #[cfg(esp32s3)]
@@ -1819,6 +1879,7 @@ pub trait RegisterAccess: crate::private::Sealed {
     fn set_in_descriptors(address: u32);
     fn set_in_peripheral(peripheral: u8);
     fn start_in();
+    fn stop_in();
 }
 
 /// DMA Channel