Merge branch 'docs/sdio_slave_sending_seqdiag' into 'master'

sdio_slave: add some documentation about impl in the source code

See merge request espressif/esp-idf!17572

components/driver/sdio_slave/README.md

@@ -0,0 +1,60 @@
+# SDIO workflow
+
+This README is a supplement to the comments in the SDIO slave driver. For more details, see `sdio_slave.c`.
+
+The diagram are described in mermaid format. You can view the diagrams on Github or with any mermaid renders.
+
+## Sending direction
+
+```mermaid
+sequenceDiagram
+    actor task
+    participant ISR
+    participant HW
+    Note right of HW: always: rx_done.raw = 1, rx_eof.ena= 1
+
+    task-->>ISR: Prepare transfers
+    task->>HW: rx_done.ena=1
+    activate HW
+
+    %% First ISR triggering transfer
+    HW->>ISR: trigger
+    activate ISR
+
+    ISR->>HW: rx_done.ena=0
+    deactivate HW
+
+    loop every finished descriptor
+    note over task, HW: skipped, see below
+    end
+
+    opt HW idle && new transfer prepared
+    ISR->>HW: Load transfer
+    end
+    deactivate ISR
+
+    activate HW
+    HW->>HW: Host doing RX transfer
+    deactivate HW
+
+    HW->>HW: rx_eof.raw=1
+    activate HW
+
+    %% Second ISR recycling transfer
+    HW->>ISR: trigger
+    activate ISR
+
+    ISR-->>HW: rx_done.ena=0
+
+    loop every finished descriptor
+    ISR->>HW: rx_eof.raw=0
+    deactivate HW
+    ISR-->>task: inform
+    end
+
+    opt HW idle && new transfer prepared
+    note over ISR, HW: Load next transfer if there is...
+    end
+
+    deactivate ISR
+```

components/driver/sdio_slave/sdio_slave.c

@@ -10,6 +10,7 @@ Architecture:
 The whole SDIO slave peripheral consists of three parts: the registers (including the control registers of
 interrupts and shared registers), the sending FIFO and the receiving FIFO. A document ``esp_slave_protocol.rst``
 describes the functionality of the peripheral detailedly.
+
 The host can access only one of those parts at once, and the hardware functions of these parts are totally
 independent. Hence this driver is designed into these three independent parts. The shared registers are quite
 simple. As well as the interrupts: when a slave interrupt is written by the host, the slave gets an interrupt;
@@ -42,7 +43,8 @@ The driver of FIFOs works as below:
     The receiving driver sends a counting semaphore to the app for each buffer finished receiving. A task can only
     check the linked list and fetch one finished buffer for a received semaphore.
 
-2.  The sending driver is slightly different due to different hardware working styles.
+2.  The sending driver is slightly different due to different hardware working styles. (See README.md in the same folder
+    for the diagram how task and ISR work concurrently)
     (TODO: re-write this part if the stitch mode is released)
     The hardware has a cache, so that once a descriptor is loaded onto the linked-list, it cannot be modified
     until returned (used) by the hardware. This forbids us from loading descriptors onto the linked list during