esp-who/components/bus/include/spi_bus.h

// Copyright 2015-2020 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at

//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef _IOT_SPI_BUS_H_
#define _IOT_SPI_BUS_H_

#include "driver/spi_master.h"
#include "driver/gpio.h"

#define NULL_SPI_CS_PIN -1 /*!< set cs_io_num to NULL_SPI_CS_PIN if spi device has no CP pin */
typedef void *spi_bus_handle_t; /*!< spi bus handle */
typedef void *spi_bus_device_handle_t; /*!< spi device handle */

/**
 * spi bus initialization parameters.
 * */
typedef struct {
    gpio_num_t miso_io_num; /*!< GPIO pin for Master In Slave Out (=spi_q) signal, or -1 if not used.*/
    gpio_num_t mosi_io_num; /*!< GPIO pin for Master Out Slave In (=spi_d) signal, or -1 if not used.*/
    gpio_num_t sclk_io_num; /*!< GPIO pin for Spi CLocK signal, or -1 if not used*/
    int max_transfer_sz; /*!< <Maximum length of bytes available to send, if < 4096, 4096 will be set*/
}spi_config_t;

/**
 * spi device initialization parameters.
 * */
typedef struct {
    gpio_num_t cs_io_num; /*!< GPIO pin to select this device (CS), or -1 if not used*/
    uint8_t mode; /*!< modes (0,1,2,3) that correspond to the four possible clocking configurations*/
    int clock_speed_hz; /*!< spi clock speed, divisors of 80MHz, in Hz. See ``SPI_MASTER_FREQ_*`*/
}spi_device_config_t;

#ifdef __cplusplus
extern "C"
{
#endif

/**
 * @brief Create and initialize a spi bus and return the spi bus handle
 * 
 * @param host_id SPI peripheral that controls this bus, SPI2_HOST or SPI3_HOST
 * @param bus_conf spi bus configurations details in spi_config_t
 * @return spi_bus_handle_t handle for spi bus operation, NULL if failed.
 */
spi_bus_handle_t spi_bus_create(spi_host_device_t host_id, const spi_config_t *bus_conf);

/**
 * @brief Deinitialize and delete the spi bus
 *
 * @param p_bus_handle pointer to spi bus handle, if delete succeed handle will set to NULL.
 * @return esp_err_t
 *     - ESP_ERR_INVALID_ARG   if parameter is invalid
 *     - ESP_FAIL Fail
 *     - ESP_OK Success
 */
esp_err_t spi_bus_delete(spi_bus_handle_t *p_bus_handle);

/**
 * @brief Create and add a device on the spi bus.
 *
 * @param bus_handle handle for spi bus operation.
 * @param device_conf spi device configurations details in spi_device_config_t
 * @return spi_bus_device_handle_t handle for device operation, NULL if failed.
 */
spi_bus_device_handle_t spi_bus_device_create(spi_bus_handle_t bus_handle, const spi_device_config_t *device_conf);

/**
 * @brief Deinitialize and remove the device from spi bus.
 *
 * @param p_dev_handle pointer to device handle, if delete succeed handle will set to NULL.
 * @return esp_err_t
 *     - ESP_ERR_INVALID_ARG   if parameter is invalid
 *     - ESP_FAIL Fail
 *     - ESP_OK Success
 */
esp_err_t spi_bus_device_delete(spi_bus_device_handle_t *p_dev_handle);

/**
 * @brief Transfer one byte with the device.
 *
 * @param dev_handle handle for device operation.
 * @param data_out data will send to device.
 * @param data_in pointer to receive buffer, set NULL to skip receive phase.
 * @return esp_err_t
 *     - ESP_ERR_INVALID_ARG   if parameter is invalid
 *     - ESP_ERR_TIMEOUT       if bus is busy
 *     - ESP_OK                on success
 */
esp_err_t spi_bus_transfer_byte(spi_bus_device_handle_t dev_handle, uint8_t data_out, uint8_t *data_in);

/**
 * @brief Transfer multi-bytes with the device.
 *
 * @param dev_handle handle for device operation.
 * @param data_out pointer to sent buffer, set NULL to skip sent phase.
 * @param data_in pointer to receive buffer, set NULL to skip receive phase.
 * @param data_len number of bytes will transfer.
 * @return esp_err_t
 *     - ESP_ERR_INVALID_ARG   if parameter is invalid
 *     - ESP_ERR_TIMEOUT       if bus is busy
 *     - ESP_OK                on success
 */
esp_err_t spi_bus_transfer_bytes(spi_bus_device_handle_t dev_handle, const uint8_t *data_out, uint8_t *data_in, uint32_t data_len);

/**************************************** Public Functions (Low level)*********************************************/

/**
 * @brief Send a polling transaction, wait for it to complete, and return the result
 *        @note
 *        Only call this function when ``spi_bus_transfer_xx`` do not meet the requirements
 * 
 * @param dev_handle handle for device operation.
 * @param p_trans Description of transaction to execute
 * @return esp_err_t 
 *     - ESP_ERR_INVALID_ARG   if parameter is invalid
 *     - ESP_ERR_TIMEOUT       if bus is busy
 *     - ESP_OK                on success
 */
esp_err_t spi_bus_transmit_begin(spi_bus_device_handle_t dev_handle, spi_transaction_t *p_trans);

/**
 * @brief Transfer one 16-bit value with the device. using msb by default.
 * For example 0x1234, 0x12 will send first then 0x34.
 *
 * @param dev_handle handle for device operation.
 * @param data_out data will send to device.
 * @param data_in pointer to receive buffer, set NULL to skip receive phase.
 * @return esp_err_t
 *     - ESP_ERR_INVALID_ARG   if parameter is invalid
 *     - ESP_ERR_TIMEOUT       if bus is busy
 *     - ESP_OK                on success
 */
esp_err_t spi_bus_transfer_reg16(spi_bus_device_handle_t dev_handle, uint16_t data_out, uint16_t *data_in);

/**
 * @brief Transfer one 32-bit value with the device. using msb by default.
 * For example 0x12345678, 0x12 will send first, 0x78 will send in the end.
 *
 * @param dev_handle handle for device operation.
 * @param data_out data will send to device.
 * @param data_in pointer to receive buffer, set NULL to skip receive phase.
 * @return esp_err_t
 *     - ESP_ERR_INVALID_ARG   if parameter is invalid
 *     - ESP_ERR_TIMEOUT       if bus is busy
 *     - ESP_OK                on success
 */
esp_err_t spi_bus_transfer_reg32(spi_bus_device_handle_t dev_handle, uint32_t data_out, uint32_t *data_in);

#ifdef __cplusplus
}
#endif

#endif