diff --git a/esp_serial_slave_link/Doxyfile b/esp_serial_slave_link/Doxyfile new file mode 100644 index 0000000000..43da504b77 --- /dev/null +++ b/esp_serial_slave_link/Doxyfile @@ -0,0 +1,29 @@ +# Set this to the header file you want +INPUT = \ + include/esp_serial_slave_link/essl_sdio.h \ + include/esp_serial_slave_link/essl_spi.h \ + include/esp_serial_slave_link/essl.h \ + +# Output goes into doxygen directory, which is added to gitignore +OUTPUT_DIRECTORY = doxygen + +# Warning-related settings, it's recommended to keep them enabled +WARN_IF_UNDOC_ENUM_VAL = YES +WARN_AS_ERROR = YES + +# Other common settings +FULL_PATH_NAMES = YES +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +OPTIMIZE_OUTPUT_FOR_C = YES +EXPAND_ONLY_PREDEF = YES +EXTRACT_ALL = YES +PREDEFINED = $(ENV_DOXYGEN_DEFINES) +HAVE_DOT = NO +GENERATE_XML = YES +XML_OUTPUT = xml +GENERATE_HTML = NO +HAVE_DOT = NO +GENERATE_LATEX = NO +QUIET = YES +MARKDOWN_SUPPORT = YES \ No newline at end of file diff --git a/esp_serial_slave_link/api.md b/esp_serial_slave_link/api.md new file mode 100644 index 0000000000..9bc49cea33 --- /dev/null +++ b/esp_serial_slave_link/api.md @@ -0,0 +1,1172 @@ +# API Reference + +## Header files + +- [include/esp_serial_slave_link/essl.h](#file-includeesp_serial_slave_linkesslh) +- [include/esp_serial_slave_link/essl_sdio.h](#file-includeesp_serial_slave_linkessl_sdioh) +- [include/esp_serial_slave_link/essl_spi.h](#file-includeesp_serial_slave_linkessl_spih) + +## File include/esp_serial_slave_link/essl.h + + + + + +## Structures and Types + +| Type | Name | +| ---: | :--- | +| typedef struct essl\_dev\_t \* | [**essl\_handle\_t**](#typedef-essl_handle_t)
_Handle of an ESSL device._ | + +## Functions + +| Type | Name | +| ---: | :--- | +| esp\_err\_t | [**essl\_clear\_intr**](#function-essl_clear_intr) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint32\_t intr\_mask, uint32\_t wait\_ms)
_Clear interrupt bits of ESSL slave. All the bits set in the mask will be cleared, while other bits will stay the same._ | +| esp\_err\_t | [**essl\_get\_intr**](#function-essl_get_intr) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint32\_t \*intr\_raw, uint32\_t \*intr\_st, uint32\_t wait\_ms)
_Get interrupt bits of ESSL slave._ | +| esp\_err\_t | [**essl\_get\_intr\_ena**](#function-essl_get_intr_ena) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint32\_t \*ena\_mask\_o, uint32\_t wait\_ms)
_Get interrupt enable bits of ESSL slave._ | +| esp\_err\_t | [**essl\_get\_packet**](#function-essl_get_packet) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, void \*out\_data, size\_t size, size\_t \*out\_length, uint32\_t wait\_ms)
_Get a packet from ESSL slave._ | +| esp\_err\_t | [**essl\_get\_rx\_data\_size**](#function-essl_get_rx_data_size) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint32\_t \*out\_rx\_size, uint32\_t wait\_ms)
_Get the size, in bytes, of the data that the ESSL slave is ready to send._ | +| esp\_err\_t | [**essl\_get\_tx\_buffer\_num**](#function-essl_get_tx_buffer_num) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint32\_t \*out\_tx\_num, uint32\_t wait\_ms)
_Get buffer num for the host to send data to the slave. The buffers are size of_ `buffer_size`_._ | +| esp\_err\_t | [**essl\_init**](#function-essl_init) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint32\_t wait\_ms)
_Initialize the slave._ | +| esp\_err\_t | [**essl\_read\_reg**](#function-essl_read_reg) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint8\_t add, uint8\_t \*value\_o, uint32\_t wait\_ms)
_Read general purpose R/W registers (8-bit) of ESSL slave._ | +| esp\_err\_t | [**essl\_reset\_cnt**](#function-essl_reset_cnt) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle)
_Reset the counters of this component. Usually you don't need to do this unless you know the slave is reset._ | +| esp\_err\_t | [**essl\_send\_packet**](#function-essl_send_packet) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, const void \*start, size\_t length, uint32\_t wait\_ms)
_Send a packet to the ESSL Slave. The Slave receives the packet into buffers whose size is_ `buffer_size`_ (configured during initialization)._ | +| esp\_err\_t | [**essl\_send\_slave\_intr**](#function-essl_send_slave_intr) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint32\_t intr\_mask, uint32\_t wait\_ms)
_Send interrupts to slave. Each bit of the interrupt will be triggered._ | +| esp\_err\_t | [**essl\_set\_intr\_ena**](#function-essl_set_intr_ena) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint32\_t ena\_mask, uint32\_t wait\_ms)
_Set interrupt enable bits of ESSL slave. The slave only sends interrupt on the line when there is a bit both the raw status and the enable are set._ | +| esp\_err\_t | [**essl\_wait\_for\_ready**](#function-essl_wait_for_ready) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint32\_t wait\_ms)
_Wait for interrupt of an ESSL slave device._ | +| esp\_err\_t | [**essl\_wait\_int**](#function-essl_wait_int) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint32\_t wait\_ms)
_wait for an interrupt of the slave_ | +| esp\_err\_t | [**essl\_write\_reg**](#function-essl_write_reg) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle, uint8\_t addr, uint8\_t value, uint8\_t \*value\_o, uint32\_t wait\_ms)
_Write general purpose R/W registers (8-bit) of ESSL slave._ | + + +## Structures and Types Documentation + +### typedef `essl_handle_t` + +_Handle of an ESSL device._ +```c +typedef struct essl_dev_t* essl_handle_t; +``` + + +## Functions Documentation + +### function `essl_clear_intr` + +_Clear interrupt bits of ESSL slave. All the bits set in the mask will be cleared, while other bits will stay the same._ +```c +esp_err_t essl_clear_intr ( + essl_handle_t handle, + uint32_t intr_mask, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `intr_mask` Mask of interrupt bits to clear. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK: Success +* ESP\_ERR\_NOT\_SUPPORTED: Current device does not support this function. +* One of the error codes from SDMMC host controller +### function `essl_get_intr` + +_Get interrupt bits of ESSL slave._ +```c +esp_err_t essl_get_intr ( + essl_handle_t handle, + uint32_t *intr_raw, + uint32_t *intr_st, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `intr_raw` Output of the raw interrupt bits. Set to NULL if only masked bits are read. +* `intr_st` Output of the masked interrupt bits. set to NULL if only raw bits are read. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK: Success +* ESP\_INVALID\_ARG: If both `intr_raw` and`intr_st` are NULL. +* ESP\_ERR\_NOT\_SUPPORTED: Current device does not support this function. +* One of the error codes from SDMMC host controller +### function `essl_get_intr_ena` + +_Get interrupt enable bits of ESSL slave._ +```c +esp_err_t essl_get_intr_ena ( + essl_handle_t handle, + uint32_t *ena_mask_o, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `ena_mask_o` Output of interrupt bit enable mask. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK Success +* One of the error codes from SDMMC host controller +### function `essl_get_packet` + +_Get a packet from ESSL slave._ +```c +esp_err_t essl_get_packet ( + essl_handle_t handle, + void *out_data, + size_t size, + size_t *out_length, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `out_data` Data output address +* `size` The size of the output buffer, if the buffer is smaller than the size of data to receive from slave, the driver returns `ESP_ERR_NOT_FINISHED` +* `out_length` Output of length the data actually received from slave. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK Success: All the data has been read from the slave. +* ESP\_ERR\_INVALID\_ARG: Invalid argument, The handle is not initialized or the other arguments are invalid. +* ESP\_ERR\_NOT\_FINISHED: Read was successful, but there is still data remaining. +* ESP\_ERR\_NOT\_FOUND: Slave is not ready to send data. +* ESP\_ERR\_NOT\_SUPPORTED: This API is not supported in this mode +* One of the error codes from SDMMC/SPI host controller. +### function `essl_get_rx_data_size` + +_Get the size, in bytes, of the data that the ESSL slave is ready to send._ +```c +esp_err_t essl_get_rx_data_size ( + essl_handle_t handle, + uint32_t *out_rx_size, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `out_rx_size` Output of data size to read from slave, in bytes +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK: Success +* ESP\_ERR\_NOT\_SUPPORTED: This API is not supported in this mode +* One of the error codes from SDMMC/SPI host controller +### function `essl_get_tx_buffer_num` + +_Get buffer num for the host to send data to the slave. The buffers are size of_ `buffer_size`_._ +```c +esp_err_t essl_get_tx_buffer_num ( + essl_handle_t handle, + uint32_t *out_tx_num, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of a ESSL device. +* `out_tx_num` Output of buffer num that host can send data to ESSL slave. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK: Success +* ESP\_ERR\_NOT\_SUPPORTED: This API is not supported in this mode +* One of the error codes from SDMMC/SPI host controller +### function `essl_init` + +_Initialize the slave._ +```c +esp_err_t essl_init ( + essl_handle_t handle, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK: If success +* ESP\_ERR\_NOT\_SUPPORTED: Current device does not support this function. +* Other value returned from lower layer `init`. +### function `essl_read_reg` + +_Read general purpose R/W registers (8-bit) of ESSL slave._ +```c +esp_err_t essl_read_reg ( + essl_handle_t handle, + uint8_t add, + uint8_t *value_o, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of a `essl` device. +* `add` Address of register to read. For SDIO, Valid address: 0-27, 32-63 (28-31 reserved, return interrupt bits on read). For SPI, see `essl_spi.h` +* `value_o` Output value read from the register. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK Success +* One of the error codes from SDMMC/SPI host controller +### function `essl_reset_cnt` + +_Reset the counters of this component. Usually you don't need to do this unless you know the slave is reset._ +```c +esp_err_t essl_reset_cnt ( + essl_handle_t handle +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. + + +**Returns:** + + + +* ESP\_OK: Success +* ESP\_ERR\_NOT\_SUPPORTED: This API is not supported in this mode +* ESP\_ERR\_INVALID\_ARG: Invalid argument, handle is not init. +### function `essl_send_packet` + +_Send a packet to the ESSL Slave. The Slave receives the packet into buffers whose size is_ `buffer_size`_ (configured during initialization)._ +```c +esp_err_t essl_send_packet ( + essl_handle_t handle, + const void *start, + size_t length, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `start` Start address of the packet to send +* `length` Length of data to send, if the packet is over-size, the it will be divided into blocks and hold into different buffers automatically. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK Success +* ESP\_ERR\_INVALID\_ARG: Invalid argument, handle is not init or other argument is not valid. +* ESP\_ERR\_TIMEOUT: No buffer to use, or error ftrom SDMMC host controller. +* ESP\_ERR\_NOT\_FOUND: Slave is not ready for receiving. +* ESP\_ERR\_NOT\_SUPPORTED: This API is not supported in this mode +* One of the error codes from SDMMC/SPI host controller. +### function `essl_send_slave_intr` + +_Send interrupts to slave. Each bit of the interrupt will be triggered._ +```c +esp_err_t essl_send_slave_intr ( + essl_handle_t handle, + uint32_t intr_mask, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `intr_mask` Mask of interrupt bits to send to slave. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK: Success +* ESP\_ERR\_NOT\_SUPPORTED: Current device does not support this function. +* One of the error codes from SDMMC host controller +### function `essl_set_intr_ena` + +_Set interrupt enable bits of ESSL slave. The slave only sends interrupt on the line when there is a bit both the raw status and the enable are set._ +```c +esp_err_t essl_set_intr_ena ( + essl_handle_t handle, + uint32_t ena_mask, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `ena_mask` Mask of the interrupt bits to enable. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK: Success +* ESP\_ERR\_NOT\_SUPPORTED: Current device does not support this function. +* One of the error codes from SDMMC host controller +### function `essl_wait_for_ready` + +_Wait for interrupt of an ESSL slave device._ +```c +esp_err_t essl_wait_for_ready ( + essl_handle_t handle, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK: If success +* ESP\_ERR\_NOT\_SUPPORTED: Current device does not support this function. +* One of the error codes from SDMMC host controller +### function `essl_wait_int` + +_wait for an interrupt of the slave_ +```c +esp_err_t essl_wait_int ( + essl_handle_t handle, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Returns:** + + + +* ESP\_OK: If interrupt is triggered. +* ESP\_ERR\_NOT\_SUPPORTED: Current device does not support this function. +* ESP\_ERR\_TIMEOUT: No interrupts before timeout. +### function `essl_write_reg` + +_Write general purpose R/W registers (8-bit) of ESSL slave._ +```c +esp_err_t essl_write_reg ( + essl_handle_t handle, + uint8_t addr, + uint8_t value, + uint8_t *value_o, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `handle` Handle of an ESSL device. +* `addr` Address of register to write. For SDIO, valid address: 0-59. For SPI, see `essl_spi.h` +* `value` Value to write to the register. +* `value_o` Output of the returned written value. +* `wait_ms` Millisecond to wait before timeout, will not wait at all if set to 0-9. + + +**Note:** + +sdio 28-31 are reserved, the lower API helps to skip. + + + +**Returns:** + + + +* ESP\_OK Success +* One of the error codes from SDMMC/SPI host controller + + +## File include/esp_serial_slave_link/essl_sdio.h + + + + + +## Structures and Types + +| Type | Name | +| ---: | :--- | +| struct | [**essl\_sdio\_config\_t**](#struct-essl_sdio_config_t)
_Configuration for the ESSL SDIO device._ | + +## Functions + +| Type | Name | +| ---: | :--- | +| esp\_err\_t | [**essl\_sdio\_deinit\_dev**](#function-essl_sdio_deinit_dev) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle)
_Deinitialize and free the space used by the ESSL SDIO device._ | +| esp\_err\_t | [**essl\_sdio\_init\_dev**](#function-essl_sdio_init_dev) ([**essl\_handle\_t**](#typedef-essl_handle_t) \*out\_handle, const [**essl\_sdio\_config\_t**](#struct-essl_sdio_config_t) \*config)
_Initialize the ESSL SDIO device and get its handle._ | + + +## Structures and Types Documentation + +### struct `essl_sdio_config_t` + +_Configuration for the ESSL SDIO device._ + +Variables: + +- sdmmc\_card\_t \* card
_The initialized sdmmc card pointer of the slave._ + +- int recv_buffer_size
_The pre-negotiated recv buffer size used by both the host and the slave._ + + +## Functions Documentation + +### function `essl_sdio_deinit_dev` + +_Deinitialize and free the space used by the ESSL SDIO device._ +```c +esp_err_t essl_sdio_deinit_dev ( + essl_handle_t handle +) +``` + + +**Parameters:** + + +* `handle` Handle of the ESSL SDIO device to deinit. + + +**Returns:** + + + +* ESP\_OK: on success +* ESP\_ERR\_INVALID\_ARG: wrong handle passed +### function `essl_sdio_init_dev` + +_Initialize the ESSL SDIO device and get its handle._ +```c +esp_err_t essl_sdio_init_dev ( + essl_handle_t *out_handle, + const essl_sdio_config_t *config +) +``` + + +**Parameters:** + + +* `out_handle` Output of the handle. +* `config` Configuration for the ESSL SDIO device. + + +**Returns:** + + + +* ESP\_OK: on success +* ESP\_ERR\_NO\_MEM: memory exhausted. + + +## File include/esp_serial_slave_link/essl_spi.h + + + + + +## Structures and Types + +| Type | Name | +| ---: | :--- | +| struct | [**essl\_spi\_config\_t**](#struct-essl_spi_config_t)
_Configuration of ESSL SPI device._ | + +## Functions + +| Type | Name | +| ---: | :--- | +| esp\_err\_t | [**essl\_spi\_deinit\_dev**](#function-essl_spi_deinit_dev) ([**essl\_handle\_t**](#typedef-essl_handle_t) handle)
_Deinitialize the ESSL SPI device and free the memory used by the device._ | +| esp\_err\_t | [**essl\_spi\_get\_packet**](#function-essl_spi_get_packet) (void \*arg, void \*out\_data, size\_t size, uint32\_t wait\_ms)
_Get a packet from Slave._ | +| esp\_err\_t | [**essl\_spi\_init\_dev**](#function-essl_spi_init_dev) ([**essl\_handle\_t**](#typedef-essl_handle_t) \*out\_handle, const [**essl\_spi\_config\_t**](#struct-essl_spi_config_t) \*init\_config)
_Initialize the ESSL SPI device function list and get its handle._ | +| esp\_err\_t | [**essl\_spi\_rdbuf**](#function-essl_spi_rdbuf) (spi\_device\_handle\_t spi, uint8\_t \*out\_data, int addr, int len, uint32\_t flags)
_Read the shared buffer from the slave in ISR way._ | +| esp\_err\_t | [**essl\_spi\_rdbuf\_polling**](#function-essl_spi_rdbuf_polling) (spi\_device\_handle\_t spi, uint8\_t \*out\_data, int addr, int len, uint32\_t flags)
_Read the shared buffer from the slave in polling way._ | +| esp\_err\_t | [**essl\_spi\_rddma**](#function-essl_spi_rddma) (spi\_device\_handle\_t spi, uint8\_t \*out\_data, int len, int seg\_len, uint32\_t flags)
_Receive long buffer in segments from the slave through its DMA._ | +| esp\_err\_t | [**essl\_spi\_rddma\_done**](#function-essl_spi_rddma_done) (spi\_device\_handle\_t spi, uint32\_t flags)
_Send the_ `rddma_done`_ command to the slave. Upon receiving this command, the slave will stop sending the current buffer even there are data unsent, and maybe prepare the next buffer to send._ | +| esp\_err\_t | [**essl\_spi\_rddma\_seg**](#function-essl_spi_rddma_seg) (spi\_device\_handle\_t spi, uint8\_t \*out\_data, int seg\_len, uint32\_t flags)
_Read one data segment from the slave through its DMA._ | +| esp\_err\_t | [**essl\_spi\_read\_reg**](#function-essl_spi_read_reg) (void \*arg, uint8\_t addr, uint8\_t \*out\_value, uint32\_t wait\_ms)
_Read from the shared registers._ | +| void | [**essl\_spi\_reset\_cnt**](#function-essl_spi_reset_cnt) (void \*arg)
_Reset the counter in Master context._ | +| esp\_err\_t | [**essl\_spi\_send\_packet**](#function-essl_spi_send_packet) (void \*arg, const void \*data, size\_t size, uint32\_t wait\_ms)
_Send a packet to Slave._ | +| esp\_err\_t | [**essl\_spi\_wrbuf**](#function-essl_spi_wrbuf) (spi\_device\_handle\_t spi, const uint8\_t \*data, int addr, int len, uint32\_t flags)
_Write the shared buffer of the slave in ISR way._ | +| esp\_err\_t | [**essl\_spi\_wrbuf\_polling**](#function-essl_spi_wrbuf_polling) (spi\_device\_handle\_t spi, const uint8\_t \*data, int addr, int len, uint32\_t flags)
_Write the shared buffer of the slave in polling way._ | +| esp\_err\_t | [**essl\_spi\_wrdma**](#function-essl_spi_wrdma) (spi\_device\_handle\_t spi, const uint8\_t \*data, int len, int seg\_len, uint32\_t flags)
_Send long buffer in segments to the slave through its DMA._ | +| esp\_err\_t | [**essl\_spi\_wrdma\_done**](#function-essl_spi_wrdma_done) (spi\_device\_handle\_t spi, uint32\_t flags)
_Send the_ `wrdma_done`_ command to the slave. Upon receiving this command, the slave will stop receiving, process the received data, and maybe prepare the next buffer to receive._ | +| esp\_err\_t | [**essl\_spi\_wrdma\_seg**](#function-essl_spi_wrdma_seg) (spi\_device\_handle\_t spi, const uint8\_t \*data, int seg\_len, uint32\_t flags)
_Send one data segment to the slave through its DMA._ | +| esp\_err\_t | [**essl\_spi\_write\_reg**](#function-essl_spi_write_reg) (void \*arg, uint8\_t addr, uint8\_t value, uint8\_t \*out\_value, uint32\_t wait\_ms)
_Write to the shared registers._ | + + +## Structures and Types Documentation + +### struct `essl_spi_config_t` + +_Configuration of ESSL SPI device._ + +Variables: + +- uint8\_t rx_sync_reg
_The pre-negotiated register ID for Master-RX-Slave-TX synchronization. 1 word (4 Bytes) will be reserved for the synchronization._ + +- spi\_device\_handle\_t \* spi
_Pointer to SPI device handle._ + +- uint32\_t tx_buf_size
_The pre-negotiated Master TX buffer size used by both the host and the slave._ + +- uint8\_t tx_sync_reg
_The pre-negotiated register ID for Master-TX-SLAVE-RX synchronization. 1 word (4 Bytes) will be reserved for the synchronization._ + + +## Functions Documentation + +### function `essl_spi_deinit_dev` + +_Deinitialize the ESSL SPI device and free the memory used by the device._ +```c +esp_err_t essl_spi_deinit_dev ( + essl_handle_t handle +) +``` + + +**Parameters:** + + +* `handle` Handle of the ESSL SPI device + + +**Returns:** + + + +* ESP\_OK: On success +* ESP\_ERR\_INVALID\_STATE: ESSL SPI is not in use +### function `essl_spi_get_packet` + +_Get a packet from Slave._ +```c +esp_err_t essl_spi_get_packet ( + void *arg, + void *out_data, + size_t size, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `arg` Context of the component. (Member `arg` from`essl_handle_t`) +* `out_data` Output data address +* `size` The size of the output data. +* `wait_ms` Time to wait before timeout (reserved for future use, user should set this to 0). + + +**Returns:** + + + +* ESP\_OK: On Success +* ESP\_ERR\_INVALID\_STATE: ESSL SPI has not been initialized. +* ESP\_ERR\_INVALID\_ARG: The output data address is neither DMA capable nor 4 byte-aligned +* ESP\_ERR\_INVALID\_SIZE: Master requires `size` bytes of data but Slave did not load enough bytes. +### function `essl_spi_init_dev` + +_Initialize the ESSL SPI device function list and get its handle._ +```c +esp_err_t essl_spi_init_dev ( + essl_handle_t *out_handle, + const essl_spi_config_t *init_config +) +``` + + +**Parameters:** + + +* `out_handle` Output of the handle +* `init_config` Configuration for the ESSL SPI device + + +**Returns:** + + + +* ESP\_OK: On success +* ESP\_ERR\_NO\_MEM: Memory exhausted +* ESP\_ERR\_INVALID\_STATE: SPI driver is not initialized +* ESP\_ERR\_INVALID\_ARG: Wrong register ID +### function `essl_spi_rdbuf` + +_Read the shared buffer from the slave in ISR way._ +```c +esp_err_t essl_spi_rdbuf ( + spi_device_handle_t spi, + uint8_t *out_data, + int addr, + int len, + uint32_t flags +) +``` + + +**Note:** + +The slave's HW doesn't guarantee the data in one SPI transaction is consistent. It sends data in unit of byte. In other words, if the slave SW attempts to update the shared register when a rdbuf SPI transaction is in-flight, the data got by the master will be the combination of bytes of different writes of slave SW. + + + +**Note:** + +`out_data` should be prepared in words and in the DRAM. The buffer may be written in words by the DMA. When a byte is written, the remaining bytes in the same word will also be overwritten, even the`len` is shorter than a word. + + + +**Parameters:** + + +* `spi` SPI device handle representing the slave +* `out_data` Buffer for read data, strongly suggested to be in the DRAM and aligned to 4 +* `addr` Address of the slave shared buffer +* `len` Length to read +* `flags` `SPI_TRANS_*` flags to control the transaction mode of the transaction to send. + + +**Returns:** + + + +* ESP\_OK: on success +* or other return value from :cpp:func:`spi_device_transmit`. +### function `essl_spi_rdbuf_polling` + +_Read the shared buffer from the slave in polling way._ +```c +esp_err_t essl_spi_rdbuf_polling ( + spi_device_handle_t spi, + uint8_t *out_data, + int addr, + int len, + uint32_t flags +) +``` + + +**Note:** + +`out_data` should be prepared in words and in the DRAM. The buffer may be written in words by the DMA. When a byte is written, the remaining bytes in the same word will also be overwritten, even the`len` is shorter than a word. + + + +**Parameters:** + + +* `spi` SPI device handle representing the slave +* `out_data` Buffer for read data, strongly suggested to be in the DRAM and aligned to 4 +* `addr` Address of the slave shared buffer +* `len` Length to read +* `flags` `SPI_TRANS_*` flags to control the transaction mode of the transaction to send. + + +**Returns:** + + + +* ESP\_OK: on success +* or other return value from :cpp:func:`spi_device_transmit`. +### function `essl_spi_rddma` + +_Receive long buffer in segments from the slave through its DMA._ +```c +esp_err_t essl_spi_rddma ( + spi_device_handle_t spi, + uint8_t *out_data, + int len, + int seg_len, + uint32_t flags +) +``` + + +**Note:** + +This function combines several :cpp:func:`essl_spi_rddma_seg` and one :cpp:func:`essl_spi_rddma_done` at the end. Used when the slave is working in segment mode. + + + +**Parameters:** + + +* `spi` SPI device handle representing the slave +* `out_data` Buffer to hold the received data, strongly suggested to be in the DRAM and aligned to 4 +* `len` Total length of data to receive. +* `seg_len` Length of each segment, which is not larger than the maximum transaction length allowed for the spi device. Suggested to be multiples of 4. When set < 0, means send all data in one segment (the `rddma_done` will still be sent.) +* `flags` `SPI_TRANS_*` flags to control the transaction mode of the transaction to send. + + +**Returns:** + + + +* ESP\_OK: success +* or other return value from :cpp:func:`spi_device_transmit`. +### function `essl_spi_rddma_done` + +_Send the_ `rddma_done`_ command to the slave. Upon receiving this command, the slave will stop sending the current buffer even there are data unsent, and maybe prepare the next buffer to send._ +```c +esp_err_t essl_spi_rddma_done ( + spi_device_handle_t spi, + uint32_t flags +) +``` + + +**Note:** + +This is required only when the slave is working in segment mode. + + + +**Parameters:** + + +* `spi` SPI device handle representing the slave +* `flags` `SPI_TRANS_*` flags to control the transaction mode of the transaction to send. + + +**Returns:** + + + +* ESP\_OK: success +* or other return value from :cpp:func:`spi_device_transmit`. +### function `essl_spi_rddma_seg` + +_Read one data segment from the slave through its DMA._ +```c +esp_err_t essl_spi_rddma_seg ( + spi_device_handle_t spi, + uint8_t *out_data, + int seg_len, + uint32_t flags +) +``` + + +**Note:** + +To read long buffer, call :cpp:func:`essl_spi_rddma` instead. + + + +**Parameters:** + + +* `spi` SPI device handle representing the slave +* `out_data` Buffer to hold the received data. strongly suggested to be in the DRAM and aligned to 4 +* `seg_len` Length of this segment +* `flags` `SPI_TRANS_*` flags to control the transaction mode of the transaction to send. + + +**Returns:** + + + +* ESP\_OK: success +* or other return value from :cpp:func:`spi_device_transmit`. +### function `essl_spi_read_reg` + +_Read from the shared registers._ +```c +esp_err_t essl_spi_read_reg ( + void *arg, + uint8_t addr, + uint8_t *out_value, + uint32_t wait_ms +) +``` + + +**Note:** + +The registers for Master/Slave synchronization are reserved. Do not use them. (see `rx_sync_reg` in`essl_spi_config_t`) + + + +**Parameters:** + + +* `arg` Context of the component. (Member `arg` from`essl_handle_t`) +* `addr` Address of the shared registers. (Valid: 0 ~ SOC\_SPI\_MAXIMUM\_BUFFER\_SIZE, registers for M/S sync are reserved, see note1). +* `out_value` Read buffer for the shared registers. +* `wait_ms` Time to wait before timeout (reserved for future use, user should set this to 0). + + +**Returns:** + + + +* ESP\_OK: success +* ESP\_ERR\_INVALID\_STATE: ESSL SPI has not been initialized. +* ESP\_ERR\_INVALID\_ARG: The address argument is not valid. See note 1. +* or other return value from :cpp:func:`spi_device_transmit`. +### function `essl_spi_reset_cnt` + +_Reset the counter in Master context._ +```c +void essl_spi_reset_cnt ( + void *arg +) +``` + + +**Note:** + +Shall only be called if the slave has reset its counter. Else, Slave and Master would be desynchronized + + + +**Parameters:** + + +* `arg` Context of the component. (Member `arg` from`essl_handle_t`) +### function `essl_spi_send_packet` + +_Send a packet to Slave._ +```c +esp_err_t essl_spi_send_packet ( + void *arg, + const void *data, + size_t size, + uint32_t wait_ms +) +``` + + +**Parameters:** + + +* `arg` Context of the component. (Member `arg` from`essl_handle_t`) +* `data` Address of the data to send +* `size` Size of the data to send. +* `wait_ms` Time to wait before timeout (reserved for future use, user should set this to 0). + + +**Returns:** + + + +* ESP\_OK: On success +* ESP\_ERR\_INVALID\_STATE: ESSL SPI has not been initialized. +* ESP\_ERR\_INVALID\_ARG: The data address is not DMA capable +* ESP\_ERR\_INVALID\_SIZE: Master will send `size` bytes of data but Slave did not load enough RX buffer +### function `essl_spi_wrbuf` + +_Write the shared buffer of the slave in ISR way._ +```c +esp_err_t essl_spi_wrbuf ( + spi_device_handle_t spi, + const uint8_t *data, + int addr, + int len, + uint32_t flags +) +``` + + +**Note:** + +`out_data` should be prepared in words and in the DRAM. The buffer may be written in words by the DMA. When a byte is written, the remaining bytes in the same word will also be overwritten, even the`len` is shorter than a word. + + + +**Parameters:** + + +* `spi` SPI device handle representing the slave +* `data` Buffer for data to send, strongly suggested to be in the DRAM +* `addr` Address of the slave shared buffer, +* `len` Length to write +* `flags` `SPI_TRANS_*` flags to control the transaction mode of the transaction to send. + + +**Returns:** + + + +* ESP\_OK: success +* or other return value from :cpp:func:`spi_device_transmit`. +### function `essl_spi_wrbuf_polling` + +_Write the shared buffer of the slave in polling way._ +```c +esp_err_t essl_spi_wrbuf_polling ( + spi_device_handle_t spi, + const uint8_t *data, + int addr, + int len, + uint32_t flags +) +``` + + +**Note:** + +`out_data` should be prepared in words and in the DRAM. The buffer may be written in words by the DMA. When a byte is written, the remaining bytes in the same word will also be overwritten, even the`len` is shorter than a word. + + + +**Parameters:** + + +* `spi` SPI device handle representing the slave +* `data` Buffer for data to send, strongly suggested to be in the DRAM +* `addr` Address of the slave shared buffer, +* `len` Length to write +* `flags` `SPI_TRANS_*` flags to control the transaction mode of the transaction to send. + + +**Returns:** + + + +* ESP\_OK: success +* or other return value from :cpp:func:`spi_device_polling_transmit`. +### function `essl_spi_wrdma` + +_Send long buffer in segments to the slave through its DMA._ +```c +esp_err_t essl_spi_wrdma ( + spi_device_handle_t spi, + const uint8_t *data, + int len, + int seg_len, + uint32_t flags +) +``` + + +**Note:** + +This function combines several :cpp:func:`essl_spi_wrdma_seg` and one :cpp:func:`essl_spi_wrdma_done` at the end. Used when the slave is working in segment mode. + + + +**Parameters:** + + +* `spi` SPI device handle representing the slave +* `data` Buffer for data to send, strongly suggested to be in the DRAM +* `len` Total length of data to send. +* `seg_len` Length of each segment, which is not larger than the maximum transaction length allowed for the spi device. Suggested to be multiples of 4. When set < 0, means send all data in one segment (the `wrdma_done` will still be sent.) +* `flags` `SPI_TRANS_*` flags to control the transaction mode of the transaction to send. + + +**Returns:** + + + +* ESP\_OK: success +* or other return value from :cpp:func:`spi_device_transmit`. +### function `essl_spi_wrdma_done` + +_Send the_ `wrdma_done`_ command to the slave. Upon receiving this command, the slave will stop receiving, process the received data, and maybe prepare the next buffer to receive._ +```c +esp_err_t essl_spi_wrdma_done ( + spi_device_handle_t spi, + uint32_t flags +) +``` + + +**Note:** + +This is required only when the slave is working in segment mode. + + + +**Parameters:** + + +* `spi` SPI device handle representing the slave +* `flags` `SPI_TRANS_*` flags to control the transaction mode of the transaction to send. + + +**Returns:** + + + +* ESP\_OK: success +* or other return value from :cpp:func:`spi_device_transmit`. +### function `essl_spi_wrdma_seg` + +_Send one data segment to the slave through its DMA._ +```c +esp_err_t essl_spi_wrdma_seg ( + spi_device_handle_t spi, + const uint8_t *data, + int seg_len, + uint32_t flags +) +``` + + +**Note:** + +To send long buffer, call :cpp:func:`essl_spi_wrdma` instead. + + + +**Parameters:** + + +* `spi` SPI device handle representing the slave +* `data` Buffer for data to send, strongly suggested to be in the DRAM +* `seg_len` Length of this segment +* `flags` `SPI_TRANS_*` flags to control the transaction mode of the transaction to send. + + +**Returns:** + + + +* ESP\_OK: success +* or other return value from :cpp:func:`spi_device_transmit`. +### function `essl_spi_write_reg` + +_Write to the shared registers._ +```c +esp_err_t essl_spi_write_reg ( + void *arg, + uint8_t addr, + uint8_t value, + uint8_t *out_value, + uint32_t wait_ms +) +``` + + +**Note:** + +The registers for Master/Slave synchronization are reserved. Do not use them. (see `tx_sync_reg` in`essl_spi_config_t`) + + + +**Note:** + +Feature of checking the actual written value (`out_value`) is not supported. + + + +**Parameters:** + + +* `arg` Context of the component. (Member `arg` from`essl_handle_t`) +* `addr` Address of the shared registers. (Valid: 0 ~ SOC\_SPI\_MAXIMUM\_BUFFER\_SIZE, registers for M/S sync are reserved, see note1) +* `value` Buffer for data to send, should be align to 4. +* `out_value` Not supported, should be set to NULL. +* `wait_ms` Time to wait before timeout (reserved for future use, user should set this to 0). + + +**Returns:** + + + +* ESP\_OK: success +* ESP\_ERR\_INVALID\_STATE: ESSL SPI has not been initialized. +* ESP\_ERR\_INVALID\_ARG: The address argument is not valid. See note 1. +* ESP\_ERR\_NOT\_SUPPORTED: Should set `out_value` to NULL. See note 2. +* or other return value from :cpp:func:`spi_device_transmit`. + + diff --git a/esp_serial_slave_link/doc/esp_sdio_slave_protocol.md b/esp_serial_slave_link/doc/esp_sdio_slave_protocol.md new file mode 100644 index 0000000000..32c0b4f798 --- /dev/null +++ b/esp_serial_slave_link/doc/esp_sdio_slave_protocol.md @@ -0,0 +1,209 @@ +Communication with ESP SDIO Slave +================================================================================================================ + +[\[中文\]](https://docs.espressif.com/zh_CN/latest/esp32/api-reference/protocols/esp_sdio_slave_protocol.html) + +This document describes the process of initialization of an ESP SDIO Slave device and then provides details on the ESP SDIO Slave protocol - a non-standard protocol that allows an SDIO Host to communicate with an ESP SDIO slave. + +The ESP SDIO Slave protocol was created to implement the communication between SDIO host and slave, because the SDIO specification only shows how to access the custom region of a card (by sending CMD52 and CMD53 to functions 1-7) without any details regarding the underlying hardware implementation. + +SDIO Slave Capabilities of Espressif Chipsto this headline") +---------------------------------------------------------------------------------------------------------------------------------- + +The services provided by the SDIO Slave peripheral of the ESP32 chip are listed in the table below: + + +|Services |ESP32 | +| --- | --- | +|SDIO slave |Y | +|[Tohost intr](about:blank#esp-sdio-slave-interrupts) |8 | +|[Frhost intr](about:blank#esp-sdio-slave-interrupts) |8 | +|[TX DMA](about:blank#esp-sdio-slave-send-fifo) |Y | +|[RX DMA](about:blank#esp-sdio-slave-rcv-fifo) |Y | +|[Shared registers](about:blank#esp-sdio-slave-shared-registers) |56\* | + +\* Not including the interrupt registers + +ESP SDIO Slave Initialization +-------------------------------------------------------------------------------------------------------- + +The host should initialize the ESP32 SDIO slave according to the standard SDIO initialization process (Section 3.1.2 of [SDIO Simplified Specification](https://www.sdcard.org/downloads/pls/)). In this specification as well as below, the SDIO slave is called an (SD)IO card. Here is a brief example of an ESP SDIO Slave initialization process: + +1. SDIO reset + + > CMD52 (Write 0x6 = 0x8) + +2. SD reset + + > CMD0 + +3. Check whether IO card (optional) + + > CMD8 + +4. Send SDIO op cond and wait for card ready + + > CMD5 arg = 0x00000000 + > + > CMD5 arg = 0x00ff8000 (according to the response above, poll until ready) + > + > **Example:** + > + > > Arg of R4 after first CMD5 (arg = 0x00000000) is 0xXXFFFF00. + > > + > > Keep sending CMD5 with arg = 0x00FFFF00 until the R4 shows card ready (arg bit 31 = 1). + +5. Set address + + > CMD3 + +6. Select card + + > CMD7 (arg address according to CMD3 response) + > + > **Example:** + > + > > Arg of R6 after CMD3 is 0x0001xxxx. + > > + > > Arg of CMD7 should be 0x00010000. + +7. Select 4-bit mode (optional) + + > CMD52 (Write 0x07 = 0x02) + +8. Enable func1 + + > CMD52 (Write 0x02 = 0x02) + +9. Enable SDIO interrupt (required if interrupt line (DAT1) is used) + + > CMD52 (Write 0x04 = 0x03) + +10. Set Func0 blocksize (optional, default value is 512 (0x200)) + + > CMD52/53 (Read 0x10 ~ 0x11) + > + > CMD52/53 (Write 0x10 = 0x00) + > + > CMD52/53 (Write 0x11 = 0x02) + > + > CMD52/53 (Read 0x10 ~ 0x11, read to check the final value) + +11. Set Func1 blocksize (optional, default value is 512 (0x200)) + + > CMD52/53 (Read 0x110 ~ 0x111) + > + > CMD52/53 (Write 0x110 = 0x00) + > + > CMD52/53 (Write 0x111 = 0x02) + > + > CMD52/53 (Read 0x110 ~ 0x111, read to check the final value) + +ESP SDIO Slave Protocol +-------------------------------------------------------------------------------------------- + +The ESP SDIO Slave protocol is based on the SDIO Specification’s I/O Read/Write commands, i.e., CMD52 and CMD53. The protocol offers the following services: + +* Sending FIFO and receiving FIFO + +* 52 8-bit R/W registers shared by host and slave (For details, see _ESP32 Technical Reference Manual_ > _SDIO Slave Controller_ > _Register Summary_ > SDIO SLC Host registers \[[PDF](https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#sdioslave-reg-summ)\]) + +* 16 general purpose interrupt sources, 8 from host to slave and 8 from slave to host + + +To begin communication, the host needs to enable the I/O Function 1 in the slave and access its registers as described below. + +Check the code example: [peripherals/sdio](https://github.com/espressif/esp-idf/tree/8fc8f3f4799/examples/peripherals/sdio) + +The [ESP Serial Slave Link](https://docs.espressif.com/esp_serial_slave_link.html) component implements the logic of this protocol for ESP32 SDIO Host when communicating with an ESP32 SDIO slave. + +### Slave Register Table + +#### 32-bit + +* 0x044 (TOKEN\_RDATA): in which bit 27-16 holds the number of the receiving buffer. + +* 0x058 (INT\_ST): holds the interrupt source bits from slave to host. + +* 0x060 (PKT\_LEN): holds the accumulated data length (in bytes) already read by host plus the data copied to the buffer but yet to be read. + +* 0x0D4 (INT\_CLR): write 1 to clear interrupt bits corresponding to INT\_ST. + +* 0x0DC (INT\_ENA): mask bits for interrupts from slave to host. + + +#### 8-bit + +Shared general purpose registers: + +* 0x06C-0x077: R/W registers 0-11 shared by slave and host. + +* 0x07A-0x07B: R/W registers 14-15 shared by slave and host. + +* 0x07E-0x07F: R/W registers 18-19 shared by slave and host. + +* 0x088-0x08B: R/W registers 24-27 shared by slave and host. + +* 0x09C-0x0BB: R/W registers 32-63 shared by slave and host. + + +Interrupt Registers: + +* 0x08D (SLAVE\_INT): bits for host to interrupt slave. auto clear. + + +#### FIFO (Sending and Receiving) + +0x090 - 0x1F7FF are reserved for FIFOs. + +The address of CMD53 is related to the length requested to read from or write to the slave in a single transfer, as demonstrated by the equation below: + +> _requested length = 0x1F800 - address_ + +The slave responds to data that has a length equal to the length field of CMD53. In cases where the data is longer than the **requested length**, the data will be zero filled (when sending) or discarded (when receiving). This includes both the block and the byte mode of CMD53. + +Note + +The function number should be set to 1, and OP Code should be set to 1 (for CMD53). + +In order to achieve higher efficiency when accessing the FIFO by an arbitrary length, the block and byte modes of CMD53 can be used in combination. For example, given that the block size is set to 512 by default, you can write or get 1031 bytes of data from the FIFO by doing the following: + +1. Send CMD53 in block mode, block count = 2 (1024 bytes) to address 0x1F3F9 = 0x1F800 - **1031**. + +2. Then send CMD53 in byte mode, byte count = 8 (or 7 if your controller supports that) to address 0x1F7F9 = 0x1F800 - **7**. + + +### Interrupts + +SDIO interrupts are “level sensitive”. For host interrupts, the slave sends an interrupt by pulling the DAT1 line down at a proper time. The host detects when the interrupt line is pulled down and reads the INT\_ST register to determine the source of the interrupt. After that, the host can clear the interrupt bits by writing the `INT_CLR` register and process the interrupt. The host can also mask unneeded sources by clearing the bits in the INT\_ENA register corresponding to the sources. If all the sources are cleared (or masked), the DAT1 line goes inactive. + +On ESP32, the corresponding `host_int` bits are: bit 0 to bit 7. + +For slave interrupts, the host sends a transfer to write the `SLAVE_INT` register. Once a bit is set to 1, the slave hardware and the driver will detect it and inform the application. + +### Receiving FIFO + +To write to the slave’s receiving FIFO, the host should complete the following steps: + +1. **Read the TOKEN1 field (bits 27-16) of the register TOKEN\_RDATA (0x044)**. The buffer number remaining is TOKEN1 minus the number of buffers used by host. + +2. **Make sure the buffer number is sufficient** (_buffer\_size_ x _buffer\_num_ is greater than the data to write, _buffer\_size_ is pre-defined between the host and the slave before the communication starts). Otherwise, keep returning to step 1 until the buffer size is sufficient. + +3. **Write to the FIFO address with CMD53**. Note that the _requested length_ should not exceed the length calculated at step 2, and the FIFO address is related to _requested length_. + +4. **Calculate used buffers**. Note that a partially-used buffer at the tail is counted as used. + + +### Sending FIFO + +To read the slave’s sending FIFO, the host should complete the following steps: + +1. **Wait for the interrupt line to become active** (optional, low by default). + +2. **Read (poll) the interrupt bits in the INT\_ST register** to monitor if new packets exist. + +3. **If new packets are ready, read the PKT\_LEN register**. Before reading the packets, determine the length of data to be read. As the host keeps the length of data already read from the slave, subtract this value from `PKT_LEN`, the result will be the maximum length of data available for reading. If no data has been added to the sending FIFO yet, wait and poll until the slave is ready and update `PKT_LEN`. + +4. **Read from the FIFO using CMD53**. Note that the **requested length** should not be greater than calculated at Step 3, and the FIFO address is related to **requested length**. + +5. **Update the read length**. diff --git a/esp_serial_slave_link/doc/esp_serial_slave_link.md b/esp_serial_slave_link/doc/esp_serial_slave_link.md new file mode 100644 index 0000000000..f417d13842 --- /dev/null +++ b/esp_serial_slave_link/doc/esp_serial_slave_link.md @@ -0,0 +1,141 @@ +## ESP Serial Slave Link + +[\[中文\]](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-reference/protocols/esp_serial_slave_link.html) + +## Overview + +Espressif provides several chips that can work as slaves. These slave devices rely on some common buses, and have their own communication protocols over those buses. The `esp_serial_slave_link` component is designed for the master to communicate with ESP slave devices through those protocols over the bus drivers. + +After an `esp_serial_slave_link` device is initialized properly, the application can use it to communicate with the ESP slave devices conveniently. + +Note + +The ESP-IDF component `esp_serial_slave_link` has been moved from ESP-IDF since version v5.0 to a separate repository: + ++ [ESSL component on GitHub](https://github.com/espressif/idf-extra-components/tree/master/esp_serial_slave_link) + + +To add ESSL component in your project, please run `idf.py add-dependency espressif/esp_serial_slave_link`. + +## Espressif Device Protocols + +For more details about Espressif device protocols, see the following documents. + ++ [Communication with ESP SDIO Slave](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_sdio_slave_protocol.html) ++ [ESP SPI Slave HD (Half Duplex) Mode Protocol](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_spi_slave_protocol.html) + +## Terminology + ++ ESSL: Abbreviation for ESP Serial Slave Link, the component described by this document. + ++ Master: The device running the `esp_serial_slave_link` component. + ++ ESSL device: a virtual device on the master associated with an ESP slave device. The device context has the knowledge of the slave protocol above the bus, relying on some bus drivers to communicate with the slave. + ++ ESSL device handle: a handle to ESSL device context containing the configuration, status and data required by the ESSL component. The context stores the driver configurations, communication state, data shared by master and slave, etc. + + > + The context should be initialized before it is used, and get deinitialized if not used any more. The master application operates on the ESSL device through this handle. + > + ++ ESP slave: the slave device connected to the bus, which ESSL component is designed to communicate with. + ++ Bus: The bus over which the master and the slave communicate with each other. + ++ Slave protocol: The special communication protocol specified by Espressif HW/SW over the bus. + ++ TX buffer num: a counter, which is on the slave and can be read by the master, indicates the accumulated buffer numbers that the slave has loaded to the hardware to receive data from the master. + ++ RX data size: a counter, which is on the slave and can be read by the master, indicates the accumulated data size that the slave has loaded to the hardware to send to the master. + + +## Services Provided by ESP Slave + +There are some common services provided by the Espressif slaves: + +1. Tohost Interrupts: The slave can inform the master about certain events by the interrupt line. (optional) + +2. Frhost Interrupts: The master can inform the slave about certain events. + +3. TX FIFO (master to slave): The slave can receive data from the master in units of receiving buffers. + + The slave updates the TX buffer num to inform the master how much data it can receive, and the master then read the TX buffer num, and take off the used buffer number to know how many buffers are remaining. + +4. RX FIFO (slave to master): The slave can send data in stream to the master. The SDIO slave can also indicate it has new data to send to master by the interrupt line. + + The slave updates the RX data size to inform the master how much data it has prepared to send, and then the master read the data size, and take off the data length it has already received to know how many data is remaining. + +5. Shared registers: The master can read some part of the registers on the slave, and also write these registers to let the slave read. + + +The services provided by the slave depends on the slave’s model. See [SDIO Slave Capabilities of Espressif Chips](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_sdio_slave_protocol.html#esp-sdio-slave-caps) and [SPI Slave Capabilities of Espressif Chips](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_spi_slave_protocol.html#esp-spi-slave-caps) for more details. + +## Initialization of ESP Serial Slave Linkheadline") + +### ESP SDIO Slave + +The ESP SDIO slave link (ESSL SDIO) devices relies on the SDMMC component. It includes the usage of communicating with ESP SDIO Slave device via the SDMMC Host or SDSPI Host feature. The ESSL device should be initialized as below: + +1. Initialize a SDMMC card (see :doc:\` Document of SDMMC driver \`) structure. + +2. Call [`sdmmc_card_init()`](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/sdmmc.html#_CPPv415sdmmc_card_initPK12sdmmc_host_tP12sdmmc_card_t "sdmmc_card_init") to initialize the card. + +3. Initialize the ESSL device with [`essl_sdio_config_t`](#_CPPv418essl_sdio_config_t "essl_sdio_config_t"). The `card` member should be the [`sdmmc_card_t`](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/sdmmc.html#_CPPv412sdmmc_card_t "sdmmc_card_t") got in step 2, and the `recv_buffer_size` member should be filled correctly according to pre-negotiated value. + +4. Call [`essl_init()`](#_CPPv49essl_init13essl_handle_t8uint32_t "essl_init") to do initialization of the SDIO part. + +5. Call [`essl_wait_for_ready()`](#_CPPv419essl_wait_for_ready13essl_handle_t8uint32_t "essl_wait_for_ready") to wait for the slave to be ready. + + +### ESP SPI Slave + +Note + +If you are communicating with the ESP SDIO Slave device through SPI interface, you should use the [SDIO interface](#essl-sdio-slave-init) instead. + +Has not been supported yet. + +## APIs + +After the initialization process above is performed, you can call the APIs below to make use of the services provided by the slave: + +### Tohost Interrupts (Optional) + +1. Call [`essl_get_intr_ena()`](#_CPPv417essl_get_intr_ena13essl_handle_tP8uint32_t8uint32_t "essl_get_intr_ena") to know which events trigger the interrupts to the master. + +2. Call [`essl_set_intr_ena()`](#_CPPv417essl_set_intr_ena13essl_handle_t8uint32_t8uint32_t "essl_set_intr_ena") to set the events that trigger interrupts to the master. + +3. Call [`essl_wait_int()`](#_CPPv413essl_wait_int13essl_handle_t8uint32_t "essl_wait_int") to wait until interrupt from the slave, or timeout. + +4. When interrupt is triggered, call [`essl_get_intr()`](#_CPPv413essl_get_intr13essl_handle_tP8uint32_tP8uint32_t8uint32_t "essl_get_intr") to know which events are active, and call [`essl_clear_intr()`](#_CPPv415essl_clear_intr13essl_handle_t8uint32_t8uint32_t "essl_clear_intr") to clear them. + + +### Frhost Interrupts + +1. Call [`essl_send_slave_intr()`](#_CPPv420essl_send_slave_intr13essl_handle_t8uint32_t8uint32_t "essl_send_slave_intr") to trigger general purpose interrupt of the slave. + + +### TX FIFO + +1. Call [`essl_get_tx_buffer_num()`](#_CPPv422essl_get_tx_buffer_num13essl_handle_tP8uint32_t8uint32_t "essl_get_tx_buffer_num") to know how many buffers the slave has prepared to receive data from the master. This is optional. The master will poll `tx_buffer_num` when it tries to send packets to the slave, until the slave has enough buffer or timeout. + +2. Call [`essl_send_packet()`](#_CPPv416essl_send_packet13essl_handle_tPKv6size_t8uint32_t "essl_send_packet") to send data to the slave. + + +### RX FIFO + +1. Call [`essl_get_rx_data_size()`](#_CPPv421essl_get_rx_data_size13essl_handle_tP8uint32_t8uint32_t "essl_get_rx_data_size") to know how many data the slave has prepared to send to the master. This is optional. When the master tries to receive data from the slave, it updates the `rx_data_size` for once, if the current `rx_data_size` is shorter than the buffer size the master prepared to receive. And it may poll the `rx_data_size` if the `rx_data_size` keeps 0, until timeout. + +2. Call [`essl_get_packet()`](#_CPPv415essl_get_packet13essl_handle_tPv6size_tP6size_t8uint32_t "essl_get_packet") to receive data from the slave. + + +### Reset Counters (Optional) + +Call [`essl_reset_cnt()`](#_CPPv414essl_reset_cnt13essl_handle_t "essl_reset_cnt") to reset the internal counter if you find the slave has reset its counter. + +## Application Example + +The example below shows how ESP32 SDIO host and slave communicate with each other. The host uses the ESSL SDIO: + +[peripherals/sdio](https://github.com/espressif/esp-idf/tree/8fc8f3f4799/examples/peripherals/sdio) + +Please refer to the specific example README.md for details. \ No newline at end of file diff --git a/esp_serial_slave_link/doc/esp_spi_slave_protocol.md b/esp_serial_slave_link/doc/esp_spi_slave_protocol.md new file mode 100644 index 0000000000..74c5414969 --- /dev/null +++ b/esp_serial_slave_link/doc/esp_spi_slave_protocol.md @@ -0,0 +1,107 @@ +## ESP SPI Slave HD (Half Duplex) Mode Protocol + +[\[中文\]](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-reference/protocols/esp_spi_slave_protocol.html) + +Warning + +ESP32 does not support this feature. + +## SPI Slave Capabilities of Espressif Chips + +

ESP32

ESP32-S2

ESP32-C3

ESP32-S3

ESP32-C2

ESP32-C6

ESP32-H2

SPI Slave HD

N

Y (v2)

Y (v2)

Y (v2)

Y (v2)

Y (v2)

Y (v2)

Tohost intr

N

N

N

N

N

N

Frhost intr

2 *

2 *

2 *

2 *

2 *

2 *

TX DMA

Y

Y

Y

Y

Y

Y

RX DMA

Y

Y

Y

Y

Y

Y

Shared registers

72

64

64

64

64

64

+ +## Introduction + +In the half duplex mode, the master has to use the protocol defined by the slave to communicate with the slave. Each transaction may consist of the following phases (listed by the order they should exist): + ++ Command: 8-bit, master to slave + + > This phase determines the rest phases of the transactions. See [Supported Commands](#spi-slave-hd-supported-cmds). + ++ Address: 8-bit, master to slave, optional + + > For some commands (WRBUF, RDBUF), this phase specifies the address of the shared register to write to/read from. For other commands with this phase, they are meaningless but still have to exist in the transaction. + ++ Dummy: 8-bit, floating, optional + + > This phase is the turnaround time between the master and the slave on the bus, and also provides enough time for the slave to prepare the data to send to the master. + ++ Data: variable length, the direction is also determined by the command. + + > This may be a data OUT phase, in which the direction is slave to master, or a data IN phase, in which the direction is master to slave. + + +The **direction** means which side (master or slave) controls the MOSI, MISO, WP, and HD pins. + +## Data IO Modes + +In some IO modes, more data wires can be used to send the data. As a result, the SPI clock cycles required for the same amount of data will be less than in the 1-bit mode. For example, in QIO mode, address and data (IN and OUT) should be sent on all 4 data wires (MOSI, MISO, WP, and HD). Here are the modes supported by the ESP32-S2 SPI slave and the wire number (WN) used in corresponding modes. + + +|Mode |Command WN |Address WN |Dummy cycles |Data WN | +| --- | --- | --- | --- | --- | +|1-bit |1 |1 |1 |1 | +|DOUT |1 |1 |4 |2 | +|DIO |1 |2 |4 |2 | +|QOUT |1 |1 |4 |4 | +|QIO |1 |4 |4 |4 | +|QPI |4 |4 |4 |4 | + +Normally, which mode is used is determined by the command sent by the master (See [Supported Commands](#spi-slave-hd-supported-cmds)), except the QPI mode. + +### QPI Mode + +The QPI mode is a special state of the SPI Slave. The master can send the ENQPI command to put the slave into the QPI mode state. In the QPI mode, the command is also sent in 4-bit, thus it is not compatible with the normal modes. The master should only send QPI commands when the slave is in QPI mode. To exit from the QPI mode, master can send the EXQPI command. + +## Supported Commands + +Note + +The command name is in a master-oriented direction. For example, WRBUF means master writes the buffer of slave. + + +|Name |Description |Command |Address |Data | +| --- | --- | --- | --- | --- | +|WRBUF |Write buffer |0x01 |Buf addr |master to slave, no longer than buffer size | +|RDBUF |Read buffer |0x02 |Buf addr |slave to master, no longer than buffer size | +|WRDMA |Write DMA |0x03 |8 bits |master to slave, no longer than length provided by slave | +|RDDMA |Read DMA |0x04 |8 bits |slave to master, no longer than length provided by slave | +|SEG\_DONE |Segments done |0x05 | | | +|ENQPI |Enter QPI mode |0x06 | | | +|WR\_DONE |Write segments done |0x07 | | | +|CMD8 |Interrupt |0x08 | | | +|CMD9 |Interrupt |0x09 | | | +|CMDA |Interrupt |0x0A | | | +|EXQPI |Exit QPI mode |0xDD | | | + +Moreover, WRBUF, RDBUF, WRDMA, and RDDMA commands have their 2-bit and 4-bit version. To do transactions in 2-bit or 4-bit mode, send the original command ORed by the corresponding command mask below. For example, command 0xA1 means WRBUF in QIO mode. + + +|Mode |Mask | +| --- | --- | +|1-bit |0x00 | +|DOUT |0x10 | +|DIO |0x50 | +|QOUT |0x20 | +|QIO |0xA0 | +|QPI |0xA0 | + +## Segment Transaction Mode + +Segment transaction mode is the only mode supported by the SPI Slave HD driver for now. In this mode, for a transaction the slave loads onto the DMA, the master is allowed to read or write in segments. In this way, the master does not have to prepare a large buffer as the size of data provided by the slave. After the master finishes reading/writing a buffer, it has to send the corresponding termination command to the slave as a synchronization signal. The slave driver will update new data (if exist) onto the DMA upon seeing the termination command. + +The termination command is WR\_DONE (0x07) for WRDMA and CMD8 (0x08) for RDDMA. + +Here is an example for the flow the master read data from the slave DMA: + +1. The slave loads 4092 bytes of data onto the RDDMA. + +2. The master do seven RDDMA transactions, each of them is 512 bytes long, and reads the first 3584 bytes from the slave. + +3. The master do the last RDDMA transaction of 512 bytes (equal, longer, or shorter than the total length loaded by the slave are all allowed). The first 508 bytes are valid data from the slave, while the last 4 bytes are meaningless bytes. + +4. The master sends CMD8 to the slave. + +5. The slave loads another 4092 bytes of data onto the RDDMA. + +6. The master can start new reading transactions after it sends the CMD8. \ No newline at end of file diff --git a/esp_serial_slave_link/include/esp_serial_slave_link/essl.h b/esp_serial_slave_link/include/esp_serial_slave_link/essl.h index 9afed86d73..fc9b48b111 100644 --- a/esp_serial_slave_link/include/esp_serial_slave_link/essl.h +++ b/esp_serial_slave_link/include/esp_serial_slave_link/essl.h @@ -29,7 +29,8 @@ typedef struct essl_dev_t *essl_handle_t; */ esp_err_t essl_init(essl_handle_t handle, uint32_t wait_ms); -/** Wait for interrupt of an ESSL slave device. +/** + * @brief Wait for interrupt of an ESSL slave device. * * @param handle Handle of an ESSL device. * @param wait_ms Millisecond to wait before timeout, will not wait at all if set to 0-9. @@ -41,7 +42,8 @@ esp_err_t essl_init(essl_handle_t handle, uint32_t wait_ms); */ esp_err_t essl_wait_for_ready(essl_handle_t handle, uint32_t wait_ms); -/** Get buffer num for the host to send data to the slave. The buffers are size of ``buffer_size``. +/** + * @brief Get buffer num for the host to send data to the slave. The buffers are size of ``buffer_size``. * * @param handle Handle of a ESSL device. * @param out_tx_num Output of buffer num that host can send data to ESSL slave. @@ -54,7 +56,8 @@ esp_err_t essl_wait_for_ready(essl_handle_t handle, uint32_t wait_ms); */ esp_err_t essl_get_tx_buffer_num(essl_handle_t handle, uint32_t *out_tx_num, uint32_t wait_ms); -/** Get the size, in bytes, of the data that the ESSL slave is ready to send +/** + * @brief Get the size, in bytes, of the data that the ESSL slave is ready to send * * @param handle Handle of an ESSL device. * @param out_rx_size Output of data size to read from slave, in bytes @@ -68,7 +71,8 @@ esp_err_t essl_get_tx_buffer_num(essl_handle_t handle, uint32_t *out_tx_num, uin esp_err_t essl_get_rx_data_size(essl_handle_t handle, uint32_t *out_rx_size, uint32_t wait_ms); -/** Reset the counters of this component. Usually you don't need to do this unless you know the slave is reset. +/** + * @brief Reset the counters of this component. Usually you don't need to do this unless you know the slave is reset. * * @param handle Handle of an ESSL device. * @@ -79,7 +83,8 @@ esp_err_t essl_get_rx_data_size(essl_handle_t handle, uint32_t *out_rx_size, uin */ esp_err_t essl_reset_cnt(essl_handle_t handle); -/** Send a packet to the ESSL Slave. The Slave receives the packet into buffers whose size is ``buffer_size`` (configured during initialization). +/** + * @brief Send a packet to the ESSL Slave. The Slave receives the packet into buffers whose size is ``buffer_size`` (configured during initialization). * * @param handle Handle of an ESSL device. * @param start Start address of the packet to send @@ -96,7 +101,8 @@ esp_err_t essl_reset_cnt(essl_handle_t handle); */ esp_err_t essl_send_packet(essl_handle_t handle, const void *start, size_t length, uint32_t wait_ms); -/** Get a packet from ESSL slave. +/** + * @brief Get a packet from ESSL slave. * * @param handle Handle of an ESSL device. * @param[out] out_data Data output address @@ -114,7 +120,8 @@ esp_err_t essl_send_packet(essl_handle_t handle, const void *start, size_t lengt */ esp_err_t essl_get_packet(essl_handle_t handle, void *out_data, size_t size, size_t *out_length, uint32_t wait_ms); -/** Write general purpose R/W registers (8-bit) of ESSL slave. +/** + * @brief Write general purpose R/W registers (8-bit) of ESSL slave. * * @param handle Handle of an ESSL device. * @param addr Address of register to write. For SDIO, valid address: 0-59. For SPI, see ``essl_spi.h`` @@ -130,7 +137,8 @@ esp_err_t essl_get_packet(essl_handle_t handle, void *out_data, size_t size, siz */ esp_err_t essl_write_reg(essl_handle_t handle, uint8_t addr, uint8_t value, uint8_t *value_o, uint32_t wait_ms); -/** Read general purpose R/W registers (8-bit) of ESSL slave. +/** + * @brief Read general purpose R/W registers (8-bit) of ESSL slave. * * @param handle Handle of a ``essl`` device. * @param add Address of register to read. For SDIO, Valid address: 0-27, 32-63 (28-31 reserved, return interrupt bits on read). For SPI, see ``essl_spi.h`` @@ -143,7 +151,8 @@ esp_err_t essl_write_reg(essl_handle_t handle, uint8_t addr, uint8_t value, uint */ esp_err_t essl_read_reg(essl_handle_t handle, uint8_t add, uint8_t *value_o, uint32_t wait_ms); -/** wait for an interrupt of the slave +/** + * @brief wait for an interrupt of the slave * * @param handle Handle of an ESSL device. * @param wait_ms Millisecond to wait before timeout, will not wait at all if set to 0-9. @@ -155,7 +164,8 @@ esp_err_t essl_read_reg(essl_handle_t handle, uint8_t add, uint8_t *value_o, uin */ esp_err_t essl_wait_int(essl_handle_t handle, uint32_t wait_ms); -/** Clear interrupt bits of ESSL slave. All the bits set in the mask will be cleared, while other bits will stay the same. +/** + * @brief Clear interrupt bits of ESSL slave. All the bits set in the mask will be cleared, while other bits will stay the same. * * @param handle Handle of an ESSL device. * @param intr_mask Mask of interrupt bits to clear. @@ -168,7 +178,8 @@ esp_err_t essl_wait_int(essl_handle_t handle, uint32_t wait_ms); */ esp_err_t essl_clear_intr(essl_handle_t handle, uint32_t intr_mask, uint32_t wait_ms); -/** Get interrupt bits of ESSL slave. +/** + * @brief Get interrupt bits of ESSL slave. * * @param handle Handle of an ESSL device. * @param intr_raw Output of the raw interrupt bits. Set to NULL if only masked bits are read. @@ -183,7 +194,8 @@ esp_err_t essl_clear_intr(essl_handle_t handle, uint32_t intr_mask, uint32_t wai */ esp_err_t essl_get_intr(essl_handle_t handle, uint32_t *intr_raw, uint32_t *intr_st, uint32_t wait_ms); -/** Set interrupt enable bits of ESSL slave. The slave only sends interrupt on the line when there is a bit both the raw status and the enable are set. +/** + * @brief Set interrupt enable bits of ESSL slave. The slave only sends interrupt on the line when there is a bit both the raw status and the enable are set. * * @param handle Handle of an ESSL device. * @param ena_mask Mask of the interrupt bits to enable. @@ -196,7 +208,8 @@ esp_err_t essl_get_intr(essl_handle_t handle, uint32_t *intr_raw, uint32_t *intr */ esp_err_t essl_set_intr_ena(essl_handle_t handle, uint32_t ena_mask, uint32_t wait_ms); -/** Get interrupt enable bits of ESSL slave. +/** + * @brief Get interrupt enable bits of ESSL slave. * * @param handle Handle of an ESSL device. * @param ena_mask_o Output of interrupt bit enable mask. @@ -208,7 +221,8 @@ esp_err_t essl_set_intr_ena(essl_handle_t handle, uint32_t ena_mask, uint32_t wa */ esp_err_t essl_get_intr_ena(essl_handle_t handle, uint32_t *ena_mask_o, uint32_t wait_ms); -/** Send interrupts to slave. Each bit of the interrupt will be triggered. +/** + * @brief Send interrupts to slave. Each bit of the interrupt will be triggered. * * @param handle Handle of an ESSL device. * @param intr_mask Mask of interrupt bits to send to slave. diff --git a/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h b/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h index 6b0a04bc8f..1d01e2a397 100644 --- a/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h +++ b/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h @@ -50,7 +50,7 @@ esp_err_t essl_sdio_deinit_dev(essl_handle_t handle); //Please call `essl_` functions witout `sdio` instead of calling these functions directly. /** @cond */ /** - * SDIO Initialize process of an ESSL SDIO slave device. + * @brief SDIO Initialize process of an ESSL SDIO slave device. * * @param arg Context of the ``essl`` component. Send to other functions later. * @param wait_ms Time to wait before operation is done, in ms. @@ -62,7 +62,7 @@ esp_err_t essl_sdio_deinit_dev(essl_handle_t handle); esp_err_t essl_sdio_init(void *arg, uint32_t wait_ms); /** - * Wait for interrupt of an ESSL SDIO slave device. + * @brief Wait for interrupt of an ESSL SDIO slave device. * * @param arg Context of the ``essl`` component. * @param wait_ms Time to wait before operation is done, in ms. @@ -74,7 +74,7 @@ esp_err_t essl_sdio_init(void *arg, uint32_t wait_ms); esp_err_t essl_sdio_wait_for_ready(void *arg, uint32_t wait_ms); /** - * Get buffer num for the host to send data to the slave. The buffers are size of ``buffer_size``. + * @brief Get buffer num for the host to send data to the slave. The buffers are size of ``buffer_size``. * * @param arg Context of the component. * @@ -84,7 +84,8 @@ esp_err_t essl_sdio_wait_for_ready(void *arg, uint32_t wait_ms); */ uint32_t essl_sdio_get_tx_buffer_num(void *arg); -/** Get amount of data the ESSL SDIO slave preparing to send to host. +/** + * @brief Get amount of data the ESSL SDIO slave preparing to send to host. * * @param arg Context of the component. * @@ -95,7 +96,7 @@ uint32_t essl_sdio_get_tx_buffer_num(void *arg); uint32_t essl_sdio_get_rx_data_size(void *arg); /** - * Send a packet to the ESSL SDIO slave. The slave receive the packet into buffers whose size is ``buffer_size`` in the arg. + * @brief Send a packet to the ESSL SDIO slave. The slave receive the packet into buffers whose size is ``buffer_size`` in the arg. * * @param arg Context of the component. * @param start Start address of the packet to send @@ -110,7 +111,7 @@ uint32_t essl_sdio_get_rx_data_size(void *arg); esp_err_t essl_sdio_send_packet(void *arg, const void *start, size_t length, uint32_t wait_ms); /** - * Get a packet from an ESSL SDIO slave. + * @brief Get a packet from an ESSL SDIO slave. * * @param arg Context of the component. * @param[out] out_data Data output address @@ -125,7 +126,7 @@ esp_err_t essl_sdio_send_packet(void *arg, const void *start, size_t length, uin esp_err_t essl_sdio_get_packet(void *arg, void *out_data, size_t size, uint32_t wait_ms); /** - * Wait for the interrupt from the SDIO slave. + * @brief Wait for the interrupt from the SDIO slave. * * @param arg Context of the component. * @param wait_ms Time to wait before timeout, in ms. @@ -138,7 +139,7 @@ esp_err_t essl_sdio_get_packet(void *arg, void *out_data, size_t size, uint32_t esp_err_t essl_sdio_wait_int(void *arg, uint32_t wait_ms); /** - * Clear interrupt bits of an ESSL SDIO slave. All the bits set in the mask will be cleared, while other bits will stay the same. + * @brief Clear interrupt bits of an ESSL SDIO slave. All the bits set in the mask will be cleared, while other bits will stay the same. * * @param arg Context of the component. * @param intr_mask Mask of interrupt bits to clear. @@ -151,7 +152,7 @@ esp_err_t essl_sdio_wait_int(void *arg, uint32_t wait_ms); esp_err_t essl_sdio_clear_intr(void *arg, uint32_t intr_mask, uint32_t wait_ms); /** - * Get interrupt bits of an ESSL SDIO slave. + * @brief Get interrupt bits of an ESSL SDIO slave. * * @param arg Context of the component. * @param intr_raw Output of the raw interrupt bits. Set to NULL if only masked bits are read. @@ -166,7 +167,7 @@ esp_err_t essl_sdio_clear_intr(void *arg, uint32_t intr_mask, uint32_t wait_ms); esp_err_t essl_sdio_get_intr(void *arg, uint32_t *intr_raw, uint32_t *intr_st, uint32_t wait_ms); /** - * Set interrupt enable bits of an ESSL SDIO slave. The slave only sends interrupt on the line when there is a bit both the raw status and the enable are set. + * @brief Set interrupt enable bits of an ESSL SDIO slave. The slave only sends interrupt on the line when there is a bit both the raw status and the enable are set. * * @param arg Context of the component. * @param ena_mask Mask of the interrupt bits to enable. @@ -179,7 +180,7 @@ esp_err_t essl_sdio_get_intr(void *arg, uint32_t *intr_raw, uint32_t *intr_st, u esp_err_t essl_sdio_set_intr_ena(void *arg, uint32_t ena_mask, uint32_t wait_ms); /** - * Get interrupt enable bits of an ESSL SDIO slave. + * @brief Get interrupt enable bits of an ESSL SDIO slave. * * @param arg Context of the component. * @param ena_mask_o Output of interrupt bit enable mask. @@ -192,7 +193,7 @@ esp_err_t essl_sdio_set_intr_ena(void *arg, uint32_t ena_mask, uint32_t wait_ms) esp_err_t essl_sdio_get_intr_ena(void *arg, uint32_t *ena_mask_o, uint32_t wait_ms); /** - * Write general purpose R/W registers (8-bit) of an ESSL SDIO slave. + * @brief Write general purpose R/W registers (8-bit) of an ESSL SDIO slave. * * @param arg Context of the component. * @param addr Address of register to write. Valid address: 0-27, 32-63 (28-31 reserved). @@ -207,7 +208,7 @@ esp_err_t essl_sdio_get_intr_ena(void *arg, uint32_t *ena_mask_o, uint32_t wait_ esp_err_t essl_sdio_write_reg(void *arg, uint8_t addr, uint8_t value, uint8_t *value_o, uint32_t wait_ms); /** - * Read general purpose R/W registers (8-bit) of an ESSL SDIO slave. + * @brief Read general purpose R/W registers (8-bit) of an ESSL SDIO slave. * * @param arg Context of the component. * @param add Address of register to read. Valid address: 0-27, 32-63 (28-31 reserved, return interrupt bits on read). @@ -222,7 +223,7 @@ esp_err_t essl_sdio_write_reg(void *arg, uint8_t addr, uint8_t value, uint8_t *v esp_err_t essl_sdio_read_reg(void *arg, uint8_t add, uint8_t *value_o, uint32_t wait_ms); /** - * Send interrupts to slave. Each bit of the interrupt will be triggered. + * @brief Send interrupts to slave. Each bit of the interrupt will be triggered. * * @param arg Context of the component. * @param intr_mask Mask of interrupt bits to send to slave.