313 lines
15 KiB
C
313 lines
15 KiB
C
/*
|
|
* SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include "esp_err.h"
|
|
#include "driver/spi_master.h"
|
|
|
|
#include "esp_serial_slave_link/essl.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/// Configuration of ESSL SPI device
|
|
typedef struct {
|
|
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.
|
|
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.
|
|
} essl_spi_config_t;
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
// APIs for DMA Append Mode
|
|
// This mode has a better performance for continuous Half Duplex SPI transactions.
|
|
//
|
|
// * You can use the ``essl_spi_init_dev`` and ``essl_spi_deinit_dev`` together with APIs in ``essl.h`` to communicate
|
|
// with ESP SPI Slaves in Half Duplex DMA Append Mode. See example for SPI SLAVE HALFDUPLEX APPEND MODE.
|
|
// * You can also use the following APIs to create your own logic.
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
/**
|
|
* @brief Initialize the ESSL SPI device function list and get its handle
|
|
*
|
|
* @param[out] out_handle Output of the handle
|
|
* @param init_config Configuration for the ESSL SPI device
|
|
* @return
|
|
* - 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
|
|
*/
|
|
esp_err_t essl_spi_init_dev(essl_handle_t *out_handle, const essl_spi_config_t *init_config);
|
|
|
|
/**
|
|
* @brief Deinitialize the ESSL SPI device and free the memory used by the device
|
|
*
|
|
* @param handle Handle of the ESSL SPI device
|
|
* @return
|
|
* - ESP_OK: On success
|
|
* - ESP_ERR_INVALID_STATE: ESSL SPI is not in use
|
|
*/
|
|
esp_err_t essl_spi_deinit_dev(essl_handle_t handle);
|
|
|
|
/**
|
|
* @brief Read from the shared registers
|
|
*
|
|
* @note The registers for Master/Slave synchronization are reserved. Do not use them. (see `rx_sync_reg` in `essl_spi_config_t`)
|
|
*
|
|
* @param arg Context of the component. (Member ``arg`` from ``essl_handle_t``)
|
|
* @param addr Address of the shared registers. (Valid: 0 ~ SOC_SPI_MAXIMUM_BUFFER_SIZE, registers for M/S sync are reserved, see note1).
|
|
* @param[out] out_value Read buffer for the shared registers.
|
|
* @param wait_ms Time to wait before timeout (reserved for future use, user should set this to 0).
|
|
* @return
|
|
* - 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`.
|
|
*/
|
|
esp_err_t essl_spi_read_reg(void *arg, uint8_t addr, uint8_t *out_value, uint32_t wait_ms);
|
|
|
|
/**
|
|
* @brief Get a packet from Slave
|
|
*
|
|
* @param arg Context of the component. (Member ``arg`` from ``essl_handle_t``)
|
|
* @param[out] out_data Output data address
|
|
* @param size The size of the output data.
|
|
* @param wait_ms Time to wait before timeout (reserved for future use, user should set this to 0).
|
|
* @return
|
|
* - 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.
|
|
*/
|
|
esp_err_t essl_spi_get_packet(void *arg, void *out_data, size_t size, uint32_t wait_ms);
|
|
|
|
/**
|
|
* @brief Write to the shared registers
|
|
*
|
|
* @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.
|
|
*
|
|
* @param arg Context of the component. (Member ``arg`` from ``essl_handle_t``)
|
|
* @param addr Address of the shared registers. (Valid: 0 ~ SOC_SPI_MAXIMUM_BUFFER_SIZE, registers for M/S sync are reserved, see note1)
|
|
* @param value Buffer for data to send, should be align to 4.
|
|
* @param[out] out_value Not supported, should be set to NULL.
|
|
* @param wait_ms Time to wait before timeout (reserved for future use, user should set this to 0).
|
|
* @return
|
|
* - 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`.
|
|
*
|
|
*/
|
|
esp_err_t essl_spi_write_reg(void *arg, uint8_t addr, uint8_t value, uint8_t *out_value, uint32_t wait_ms);
|
|
|
|
/**
|
|
* @brief Send a packet to Slave
|
|
*
|
|
* @param arg Context of the component. (Member ``arg`` from ``essl_handle_t``)
|
|
* @param data Address of the data to send
|
|
* @param size Size of the data to send.
|
|
* @param wait_ms Time to wait before timeout (reserved for future use, user should set this to 0).
|
|
* @return
|
|
* - 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
|
|
*/
|
|
esp_err_t essl_spi_send_packet(void *arg, const void *data, size_t size, uint32_t wait_ms);
|
|
|
|
/**
|
|
* @brief Reset the counter in Master context
|
|
*
|
|
* @note Shall only be called if the slave has reset its counter. Else, Slave and Master would be desynchronized
|
|
*
|
|
* @param arg Context of the component. (Member ``arg`` from ``essl_handle_t``)
|
|
*/
|
|
void essl_spi_reset_cnt(void *arg);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
// Basic commands to communicate with the SPI Slave HD on ESP32-S2
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/**
|
|
* @brief Read the shared buffer from the slave in ISR way
|
|
*
|
|
* @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.
|
|
*
|
|
* @param spi SPI device handle representing the slave
|
|
* @param[out] out_data Buffer for read data, strongly suggested to be in the DRAM and aligned to 4
|
|
* @param addr Address of the slave shared buffer
|
|
* @param len Length to read
|
|
* @param flags `SPI_TRANS_*` flags to control the transaction mode of the transaction to send.
|
|
* @return
|
|
* - ESP_OK: on success
|
|
* - or other return value from :cpp:func:`spi_device_transmit`.
|
|
*/
|
|
esp_err_t essl_spi_rdbuf(spi_device_handle_t spi, uint8_t *out_data, int addr, int len, uint32_t flags);
|
|
|
|
/**
|
|
* @brief Read the shared buffer from the slave in polling way
|
|
*
|
|
* @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.
|
|
*
|
|
* @param spi SPI device handle representing the slave
|
|
* @param[out] out_data Buffer for read data, strongly suggested to be in the DRAM and aligned to 4
|
|
* @param addr Address of the slave shared buffer
|
|
* @param len Length to read
|
|
* @param flags `SPI_TRANS_*` flags to control the transaction mode of the transaction to send.
|
|
* @return
|
|
* - ESP_OK: on success
|
|
* - or other return value from :cpp:func:`spi_device_transmit`.
|
|
*/
|
|
esp_err_t essl_spi_rdbuf_polling(spi_device_handle_t spi, uint8_t *out_data, int addr, int len, uint32_t flags);
|
|
|
|
/**
|
|
* @brief Write the shared buffer of the slave in ISR way
|
|
*
|
|
* @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.
|
|
*
|
|
* @param spi SPI device handle representing the slave
|
|
* @param data Buffer for data to send, strongly suggested to be in the DRAM
|
|
* @param addr Address of the slave shared buffer,
|
|
* @param len Length to write
|
|
* @param flags `SPI_TRANS_*` flags to control the transaction mode of the transaction to send.
|
|
* @return
|
|
* - ESP_OK: success
|
|
* - or other return value from :cpp:func:`spi_device_transmit`.
|
|
*/
|
|
esp_err_t essl_spi_wrbuf(spi_device_handle_t spi, const uint8_t *data, int addr, int len, uint32_t flags);
|
|
|
|
/**
|
|
* @brief Write the shared buffer of the slave in polling way
|
|
*
|
|
* @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.
|
|
*
|
|
* @param spi SPI device handle representing the slave
|
|
* @param data Buffer for data to send, strongly suggested to be in the DRAM
|
|
* @param addr Address of the slave shared buffer,
|
|
* @param len Length to write
|
|
* @param flags `SPI_TRANS_*` flags to control the transaction mode of the transaction to send.
|
|
* @return
|
|
* - ESP_OK: success
|
|
* - or other return value from :cpp:func:`spi_device_polling_transmit`.
|
|
*/
|
|
esp_err_t essl_spi_wrbuf_polling(spi_device_handle_t spi, const uint8_t *data, int addr, int len, uint32_t flags);
|
|
|
|
/**
|
|
* @brief Receive long buffer in segments from the slave through its DMA.
|
|
*
|
|
* @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.
|
|
*
|
|
* @param spi SPI device handle representing the slave
|
|
* @param[out] out_data Buffer to hold the received data, strongly suggested to be in the DRAM and aligned to 4
|
|
* @param len Total length of data to receive.
|
|
* @param 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.)
|
|
* @param flags `SPI_TRANS_*` flags to control the transaction mode of the transaction to send.
|
|
* @return
|
|
* - ESP_OK: success
|
|
* - or other return value from :cpp:func:`spi_device_transmit`.
|
|
*/
|
|
esp_err_t essl_spi_rddma(spi_device_handle_t spi, uint8_t *out_data, int len, int seg_len, uint32_t flags);
|
|
|
|
/**
|
|
* @brief Read one data segment from the slave through its DMA.
|
|
*
|
|
* @note To read long buffer, call :cpp:func:`essl_spi_rddma` instead.
|
|
*
|
|
* @param spi SPI device handle representing the slave
|
|
* @param[out] out_data Buffer to hold the received data. strongly suggested to be in the DRAM and aligned to 4
|
|
* @param seg_len Length of this segment
|
|
* @param flags `SPI_TRANS_*` flags to control the transaction mode of the transaction to send.
|
|
* @return
|
|
* - ESP_OK: success
|
|
* - or other return value from :cpp:func:`spi_device_transmit`.
|
|
*/
|
|
esp_err_t essl_spi_rddma_seg(spi_device_handle_t spi, uint8_t *out_data, int seg_len, uint32_t flags);
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @note This is required only when the slave is working in segment mode.
|
|
*
|
|
* @param spi SPI device handle representing the slave
|
|
* @param flags `SPI_TRANS_*` flags to control the transaction mode of the transaction to send.
|
|
* @return
|
|
* - ESP_OK: success
|
|
* - or other return value from :cpp:func:`spi_device_transmit`.
|
|
*/
|
|
esp_err_t essl_spi_rddma_done(spi_device_handle_t spi, uint32_t flags);
|
|
|
|
/**
|
|
* @brief Send long buffer in segments to the slave through its DMA.
|
|
*
|
|
* @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.
|
|
*
|
|
* @param spi SPI device handle representing the slave
|
|
* @param data Buffer for data to send, strongly suggested to be in the DRAM
|
|
* @param len Total length of data to send.
|
|
* @param 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.)
|
|
* @param flags `SPI_TRANS_*` flags to control the transaction mode of the transaction to send.
|
|
* @return
|
|
* - ESP_OK: success
|
|
* - or other return value from :cpp:func:`spi_device_transmit`.
|
|
*/
|
|
esp_err_t essl_spi_wrdma(spi_device_handle_t spi, const uint8_t *data, int len, int seg_len, uint32_t flags);
|
|
|
|
/**
|
|
* @brief Send one data segment to the slave through its DMA.
|
|
*
|
|
* @note To send long buffer, call :cpp:func:`essl_spi_wrdma` instead.
|
|
*
|
|
* @param spi SPI device handle representing the slave
|
|
* @param data Buffer for data to send, strongly suggested to be in the DRAM
|
|
* @param seg_len Length of this segment
|
|
* @param flags `SPI_TRANS_*` flags to control the transaction mode of the transaction to send.
|
|
* @return
|
|
* - ESP_OK: success
|
|
* - or other return value from :cpp:func:`spi_device_transmit`.
|
|
*/
|
|
esp_err_t essl_spi_wrdma_seg(spi_device_handle_t spi, const uint8_t *data, int seg_len, uint32_t flags);
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @note This is required only when the slave is working in segment mode.
|
|
*
|
|
* @param spi SPI device handle representing the slave
|
|
* @param flags `SPI_TRANS_*` flags to control the transaction mode of the transaction to send.
|
|
* @return
|
|
* - ESP_OK: success
|
|
* - or other return value from :cpp:func:`spi_device_transmit`.
|
|
*/
|
|
esp_err_t essl_spi_wrdma_done(spi_device_handle_t spi, uint32_t flags);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|