API Reference

Header files

• include/esp_serial_slave_link/essl.h
• include/esp_serial_slave_link/essl_sdio.h
• include/esp_serial_slave_link/essl_sdio_defs.h
• include/esp_serial_slave_link/essl_spi.h

File include/esp_serial_slave_link/essl.h

Structures and Types

Functions

Structures and Types Documentation

typedef essl_handle_t

Handle of an ESSL device.

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.

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.

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 andintr_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.

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.

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.

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.

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.

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.

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.

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)._

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.

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.

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.

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

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.

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

Functions

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.

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.

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_sdio_defs.h

Structures and Types

Structures and Types Documentation

struct essl_sdio_def_t

This file contains SDIO Slave hardware specific requirements

Variables:

• uint32_t new_packet_intr_mask

File include/esp_serial_slave_link/essl_spi.h

Structures and Types

Functions

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.

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.

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 fromessl_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.

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.

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 thelen 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.

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 thelen 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.

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._

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.

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.

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 inessl_spi_config_t)

Parameters:

• arg Context of the component. (Member arg fromessl_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.

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 fromessl_handle_t)

function essl_spi_send_packet

Send a packet to Slave.

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 fromessl_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.

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 thelen 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.

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 thelen 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.

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._

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.

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.

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 inessl_spi_config_t)

Note:

Feature of checking the actual written value (out_value) is not supported.

Parameters:

• arg Context of the component. (Member arg fromessl_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.