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

165 lines
6.2 KiB
C

// 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