esp-idf/components/esp_driver_spi/include/driver/spi_slave_hd.h

/*
 * SPDX-FileCopyrightText: 2010-2021 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#pragma once

#include "esp_types.h"
#include "soc/soc_caps.h"
#include "freertos/FreeRTOS.h"

#include "hal/spi_types.h"
#include "driver/spi_common.h"
#include "sdkconfig.h"

#ifdef __cplusplus
extern "C"
{
#endif

#if !SOC_SPI_SUPPORT_SLAVE_HD_VER2  && !CI_HEADER_CHECK
#error The SPI peripheral does not support this feature
#endif

#define SPI_SLAVE_HD_TRANS_DMA_BUFFER_ALIGN_AUTO   (1<<0)    ///< Automatically re-malloc dma buffer if user buffer doesn't meet hardware alignment or dma_capable, this process may lose some memory and performance

/// Descriptor of data to send/receive
typedef struct {
    uint8_t* data;                              ///< Buffer to send, must be DMA capable
    size_t   len;                               ///< Len of data to send/receive. For receiving the buffer length should be multiples of 4 bytes, otherwise the extra part will be truncated.
    size_t   trans_len;                         ///< For RX direction, it indicates the data actually received. For TX direction, it is meaningless.
    uint32_t flags;                             ///< Bitwise OR of SPI_SLAVE_HD_TRANS_* flags
    void*    arg;                               ///< Extra argument indicating this data
} spi_slave_hd_data_t;

/// Information of SPI Slave HD event
typedef struct {
    spi_event_t          event;                 ///< Event type
    spi_slave_hd_data_t* trans;                 ///< Corresponding transaction for SPI_EV_SEND and SPI_EV_RECV events
} spi_slave_hd_event_t;

/// Callback for SPI Slave HD
typedef bool (*slave_cb_t)(void* arg, spi_slave_hd_event_t* event, BaseType_t* awoken);

/// Channel of SPI Slave HD to do data transaction
typedef enum {
    SPI_SLAVE_CHAN_TX = 0,                      ///< The output channel (RDDMA)
    SPI_SLAVE_CHAN_RX = 1,                      ///< The input channel (WRDMA)
} spi_slave_chan_t;

/// Callback configuration structure for SPI Slave HD
typedef struct {
    slave_cb_t cb_buffer_tx;                    ///< Callback when master reads from shared buffer
    slave_cb_t cb_buffer_rx;                    ///< Callback when master writes to shared buffer
    slave_cb_t cb_send_dma_ready;               ///< Callback when TX data buffer is loaded to the hardware (DMA)
    slave_cb_t cb_sent;                         ///< Callback when data are sent
    slave_cb_t cb_recv_dma_ready;               ///< Callback when RX data buffer is loaded to the hardware (DMA)
    slave_cb_t cb_recv;                         ///< Callback when data are received
    slave_cb_t cb_cmd9;                         ///< Callback when CMD9 received
    slave_cb_t cb_cmdA;                         ///< Callback when CMDA received
    void* arg;                                  ///< Argument indicating this SPI Slave HD peripheral instance
} spi_slave_hd_callback_config_t;

//flags for ``spi_slave_hd_slot_config_t`` to use
#define SPI_SLAVE_HD_TXBIT_LSBFIRST     (1<<0)  ///< Transmit command/address/data LSB first instead of the default MSB first
#define SPI_SLAVE_HD_RXBIT_LSBFIRST     (1<<1)  ///< Receive data LSB first instead of the default MSB first
#define SPI_SLAVE_HD_BIT_LSBFIRST       (SPI_SLAVE_HD_TXBIT_LSBFIRST|SPI_SLAVE_HD_RXBIT_LSBFIRST) ///< Transmit and receive LSB first
#define SPI_SLAVE_HD_APPEND_MODE        (1<<2)  ///< Adopt DMA append mode for transactions. In this mode, users can load(append) DMA descriptors without stopping the DMA

/// Configuration structure for the SPI Slave HD driver
typedef struct {
    uint8_t mode;                               /**< SPI mode, representing a pair of (CPOL, CPHA) configuration:
                                                     - 0: (0, 0)
                                                     - 1: (0, 1)
                                                     - 2: (1, 0)
                                                     - 3: (1, 1)
                                                 */
    uint32_t spics_io_num;                      ///< CS GPIO pin for this device
    uint32_t flags;                             ///< Bitwise OR of SPI_SLAVE_HD_* flags
    uint32_t command_bits;                      ///< command field bits, multiples of 8 and at least 8.
    uint32_t address_bits;                      ///< address field bits, multiples of 8 and at least 8.
    uint32_t dummy_bits;                        ///< dummy field bits, multiples of 8 and at least 8.
    uint32_t queue_size;                        ///< Transaction queue size. This sets how many transactions can be 'in the air' (queued using spi_slave_hd_queue_trans but not yet finished using spi_slave_hd_get_trans_result) at the same time
    spi_dma_chan_t dma_chan;                    ///< DMA channel to used.
    spi_slave_hd_callback_config_t cb_config;   ///< Callback configuration
} spi_slave_hd_slot_config_t;

/**
 * @brief Initialize the SPI Slave HD driver.
 *
 * @param host_id       The host to use
 * @param bus_config    Bus configuration for the bus used
 * @param config        Configuration for the SPI Slave HD driver
 * @return
 *  - ESP_OK:                on success
 *  - ESP_ERR_INVALID_ARG:   invalid argument given
 *  - ESP_ERR_INVALID_STATE: function called in invalid state, may be some resources are already in use
 *  - ESP_ERR_NOT_FOUND      if there is no available DMA channel
 *  - ESP_ERR_NO_MEM:        memory allocation failed
 *  - or other return value from `esp_intr_alloc`
 */
esp_err_t spi_slave_hd_init(spi_host_device_t host_id, const spi_bus_config_t *bus_config,
                            const spi_slave_hd_slot_config_t *config);

/**
 * @brief Deinitialize the SPI Slave HD driver
 *
 * @param host_id The host to deinitialize the driver
 * @return
 *  - ESP_OK: on success
 *  - ESP_ERR_INVALID_ARG: if the host_id is not correct
 */
esp_err_t spi_slave_hd_deinit(spi_host_device_t host_id);

/**
 * @brief Queue transactions (segment mode)
 *
 * @param host_id   Host to queue the transaction
 * @param chan      SPI_SLAVE_CHAN_TX or SPI_SLAVE_CHAN_RX
 * @param trans     Transaction descriptors
 * @param timeout   Timeout before the data is queued
 * @return
 *  - ESP_OK: on success
 *  - ESP_ERR_INVALID_ARG: The input argument is invalid. Can be the following reason:
 *      - The buffer given is not DMA capable
 *      - The length of data is invalid (not larger than 0, or exceed the max transfer length)
 *      - The transaction direction is invalid
 *  - ESP_ERR_TIMEOUT: Cannot queue the data before timeout. Master is still processing previous transaction.
 *  - ESP_ERR_INVALID_STATE: Function called in invalid state. This API should be called under segment mode.
 */
esp_err_t spi_slave_hd_queue_trans(spi_host_device_t host_id, spi_slave_chan_t chan, spi_slave_hd_data_t* trans, TickType_t timeout);

/**
 * @brief Get the result of a data transaction (segment mode)
 *
 * @note This API should be called successfully the same times as the ``spi_slave_hd_queue_trans``.
 *
 * @param host_id   Host to queue the transaction
 * @param chan      Channel to get the result, SPI_SLAVE_CHAN_TX or SPI_SLAVE_CHAN_RX
 * @param[out] out_trans Pointer to the transaction descriptor (``spi_slave_hd_data_t``) passed to the driver before. Hardware has finished this transaction. Member ``trans_len`` indicates the actual number of bytes of received data, it's meaningless for TX.
 * @param timeout   Timeout before the result is got
 * @return
 *  - ESP_OK: on success
 *  - ESP_ERR_INVALID_ARG: Function is not valid
 *  - ESP_ERR_TIMEOUT: There's no transaction done before timeout
 *  - ESP_ERR_INVALID_STATE: Function called in invalid state. This API should be called under segment mode.
 */
esp_err_t spi_slave_hd_get_trans_res(spi_host_device_t host_id, spi_slave_chan_t chan, spi_slave_hd_data_t **out_trans, TickType_t timeout);

/**
 * @brief Read the shared registers
 *
 * @param host_id   Host to read the shared registers
 * @param addr      Address of register to read, 0 to ``SOC_SPI_MAXIMUM_BUFFER_SIZE-1``
 * @param[out] out_data Output buffer to store the read data
 * @param len       Length to read, not larger than ``SOC_SPI_MAXIMUM_BUFFER_SIZE-addr``
 */
void spi_slave_hd_read_buffer(spi_host_device_t host_id, int addr, uint8_t *out_data, size_t len);

/**
 * @brief Write the shared registers
 *
 * @param host_id   Host to write the shared registers
 * @param addr      Address of register to write, 0 to ``SOC_SPI_MAXIMUM_BUFFER_SIZE-1``
 * @param data      Buffer holding the data to write
 * @param len       Length to write, ``SOC_SPI_MAXIMUM_BUFFER_SIZE-addr``
 */
void spi_slave_hd_write_buffer(spi_host_device_t host_id, int addr, uint8_t *data, size_t len);

/**
 * @brief Load transactions (append mode)
 *
 * @note In this mode, user transaction descriptors will be appended to the DMA and the DMA will keep processing the data without stopping
 *
 * @param host_id   Host to load transactions
 * @param chan      SPI_SLAVE_CHAN_TX or SPI_SLAVE_CHAN_RX
 * @param trans     Transaction descriptor
 * @param timeout   Timeout before the transaction is loaded
 * @return
 *  - ESP_OK: on success
 *  - ESP_ERR_INVALID_ARG: The input argument is invalid. Can be the following reason:
 *      - The buffer given is not DMA capable
 *      - The length of data is invalid (not larger than 0, or exceed the max transfer length)
 *      - The transaction direction is invalid
 *  - ESP_ERR_TIMEOUT: Master is still processing previous transaction. There is no available transaction for slave to load
 *  - ESP_ERR_INVALID_STATE: Function called in invalid state. This API should be called under append mode.
 */
esp_err_t spi_slave_hd_append_trans(spi_host_device_t host_id, spi_slave_chan_t chan, spi_slave_hd_data_t *trans, TickType_t timeout);

/**
 * @brief Get the result of a data transaction (append mode)
 *
 * @note This API should be called the same times as the ``spi_slave_hd_append_trans``
 *
 * @param host_id   Host to load the transaction
 * @param chan      SPI_SLAVE_CHAN_TX or SPI_SLAVE_CHAN_RX
 * @param[out] out_trans Pointer to the transaction descriptor (``spi_slave_hd_data_t``) passed to the driver before. Hardware has finished this transaction. Member ``trans_len`` indicates the actual number of bytes of received data, it's meaningless for TX.
 * @param timeout   Timeout before the result is got
 * @return
 *  - ESP_OK: on success
 *  - ESP_ERR_INVALID_ARG: Function is not valid
 *  - ESP_ERR_TIMEOUT: There's no transaction done before timeout
 *  - ESP_ERR_INVALID_STATE: Function called in invalid state. This API should be called under append mode.
 */
esp_err_t spi_slave_hd_get_append_trans_res(spi_host_device_t host_id, spi_slave_chan_t chan, spi_slave_hd_data_t **out_trans, TickType_t timeout);

#ifdef __cplusplus
}
#endif