alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-11-19 18:44:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into feature/esp32s2beta_update

Browse Source
This commit is contained in:
Angus Gratton
2019-08-08 13:44:24 +10:00
committed by Angus Gratton
parent 1877a9fcd8 16b300bd7a
commit 24d26fccde
2414 changed files with 160787 additions and 45783 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
components/driver/include/driver/spi_common.h
View File

@@ -1,9 +1,9 @@
// Copyright 2010-2018 Espressif Systems (Shanghai) PTE LTD
// Copyright 2010-2019 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
@@ -12,9 +12,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef _DRIVER_SPI_COMMON_H_
#define _DRIVER_SPI_COMMON_H_
#pragma once
#include <stdint.h>
#include <stdbool.h>
@@ -62,35 +60,6 @@ extern "C"
*/
#define SPI_SWAP_DATA_RX(data, len) (__builtin_bswap32(data)>>(32-len))
/**
* Transform unsigned integer of length <= 32 bits to the format which can be
* sent by the SPI driver directly.
*
* E.g. to send 9 bits of data, you can:
*
* uint16_t data = SPI_SWAP_DATA_TX(0x145, 9);
*
* Then points tx_buffer to ``&data``.
*
* @param data Data to be sent, can be uint8_t, uint16_t or uint32_t. @param
* len Length of data to be sent, since the SPI peripheral sends from the MSB,
* this helps to shift the data to the MSB.
*/
#define SPI_SWAP_DATA_TX(data, len) __builtin_bswap32((uint32_t)data<<(32-len))
/**
* Transform received data of length <= 32 bits to the format of an unsigned integer.
*
* E.g. to transform the data of 15 bits placed in a 4-byte array to integer:
*
* uint16_t data = SPI_SWAP_DATA_RX(*(uint32_t*)t->rx_data, 15);
*
* @param data Data to be rearranged, can be uint8_t, uint16_t or uint32_t.
* @param len Length of data received, since the SPI peripheral writes from
* the MSB, this helps to shift the data to the LSB.
*/
#define SPI_SWAP_DATA_RX(data, len) (__builtin_bswap32(data)>>(32-len))
/**
* @brief This is a configuration structure for a SPI bus.
*
@@ -116,6 +85,50 @@ typedef struct {
} spi_bus_config_t;
/**
* @brief Initialize a SPI bus
*
* @warning For now, only supports HSPI and VSPI.
*
* @param host SPI peripheral that controls this bus
* @param bus_config Pointer to a spi_bus_config_t struct specifying how the host should be initialized
* @param dma_chan Either channel 1 or 2, or 0 in the case when no DMA is required. Selecting a DMA channel
* for a SPI bus allows transfers on the bus to have sizes only limited by the amount of
* internal memory. Selecting no DMA channel (by passing the value 0) limits the amount of
* bytes transfered to a maximum of 64. Set to 0 if only the SPI flash uses
* this bus.
*
* @warning If a DMA channel is selected, any transmit and receive buffer used should be allocated in
* DMA-capable memory.
*
* @warning The ISR of SPI is always executed on the core which calls this
* function. Never starve the ISR on this core or the SPI transactions will not
* be handled.
*
* @return
* - ESP_ERR_INVALID_ARG if configuration is invalid
* - ESP_ERR_INVALID_STATE if host already is in use
* - ESP_ERR_NO_MEM if out of memory
* - ESP_OK on success
*/
esp_err_t spi_bus_initialize(spi_host_device_t host, const spi_bus_config_t *bus_config, int dma_chan);
/**
* @brief Free a SPI bus
*
* @warning In order for this to succeed, all devices have to be removed first.
*
* @param host SPI peripheral to free
* @return
* - ESP_ERR_INVALID_ARG if parameter is invalid
* - ESP_ERR_INVALID_STATE if not all devices on the bus are freed
* - ESP_OK on success
*/
esp_err_t spi_bus_free(spi_host_device_t host);
/** @cond */ //Doxygen command to hide deprecated function (or non-public) from API Reference
/**
* @brief Try to claim a SPI peripheral
*
@@ -124,6 +137,8 @@ typedef struct {
* @param host Peripheral to claim
* @param source The caller indentification string.
*
* @note This public API is deprecated.
*
* @return True if peripheral is claimed successfully; false if peripheral already is claimed.
*/
bool spicommon_periph_claim(spi_host_device_t host, const char* source);
@@ -145,6 +160,8 @@ bool spicommon_periph_claim(spi_host_device_t host, const char* source);
*
* @param host Peripheral to check.
*
* @note This public API is deprecated.
*
* @return True if in use, otherwise false.
*/
bool spicommon_periph_in_use(spi_host_device_t host);
@@ -153,6 +170,9 @@ bool spicommon_periph_in_use(spi_host_device_t host);
* @brief Return the SPI peripheral so another driver can claim it.
*
* @param host Peripheral to return
*
* @note This public API is deprecated.
*
* @return True if peripheral is returned successfully; false if peripheral was free to claim already.
*/
bool spicommon_periph_free(spi_host_device_t host);
@@ -164,6 +184,8 @@ bool spicommon_periph_free(spi_host_device_t host);
*
* @param dma_chan channel to claim
*
* @note This public API is deprecated.
*
* @return True if success; false otherwise.
*/
bool spicommon_dma_chan_claim(int dma_chan);
@@ -173,6 +195,8 @@ bool spicommon_dma_chan_claim(int dma_chan);
*
* @param dma_chan DMA channel to check.
*
* @note This public API is deprecated.
*
* @return True if in use, otherwise false.
*/
bool spicommon_dma_chan_in_use(int dma_chan);
@@ -182,10 +206,13 @@ bool spicommon_dma_chan_in_use(int dma_chan);
*
* @param dma_chan channel to return
*
* @note This public API is deprecated.
*
* @return True if success; false otherwise.
*/
bool spicommon_dma_chan_free(int dma_chan);
/// @note macros deprecated from public API
#define SPICOMMON_BUSFLAG_SLAVE 0 ///< Initialize I/O in slave mode
#define SPICOMMON_BUSFLAG_MASTER (1<<0) ///< Initialize I/O in master mode
#define SPICOMMON_BUSFLAG_IOMUX_PINS (1<<1) ///< Check using iomux pins. Or indicates the pins are configured through the IO mux rather than GPIO matrix.
@@ -206,6 +233,9 @@ bool spicommon_dma_chan_free(int dma_chan);
* the arguments. Depending on the IO-pads requested, the routing is done either using the
* IO_mux or using the GPIO matrix.
*
* @note This public API is deprecated. Please call ``spi_bus_initialize`` for master
* bus initialization and ``spi_slave_initialize`` for slave initialization.
*
* @param host SPI peripheral to be routed
* @param bus_config Pointer to a spi_bus_config struct detailing the GPIO pins
* @param dma_chan DMA-channel (1 or 2) to use, or 0 for no DMA.
@@ -234,18 +264,9 @@ esp_err_t spicommon_bus_initialize_io(spi_host_device_t host, const spi_bus_conf
/**
* @brief Free the IO used by a SPI peripheral
* @deprecated Use spicommon_bus_free_io_cfg instead.
*
* @param host SPI peripheral to be freed
*
* @return
* - ESP_ERR_INVALID_ARG if parameter is invalid
* - ESP_OK on success
*/
esp_err_t spicommon_bus_free_io(spi_host_device_t host) __attribute__((deprecated));
/**
* @brief Free the IO used by a SPI peripheral
* @note This public API is deprecated. Please call ``spi_bus_free`` for master
* bus deinitialization and ``spi_slave_free`` for slave deinitialization.
*
* @param bus_cfg Bus config struct which defines which pins to be used.
*
@@ -258,6 +279,8 @@ esp_err_t spicommon_bus_free_io_cfg(const spi_bus_config_t *bus_cfg);
/**
* @brief Initialize a Chip Select pin for a specific SPI peripheral
*
* @note This public API is deprecated. Please call corresponding device initialization
* functions.
*
* @param host SPI peripheral
* @param cs_io_num GPIO pin to route
@@ -265,59 +288,61 @@ esp_err_t spicommon_bus_free_io_cfg(const spi_bus_config_t *bus_cfg);
* @param force_gpio_matrix If true, CS will always be routed through the GPIO matrix. If false,
* if the GPIO number allows it, the routing will happen through the IO_mux.
*/
void spicommon_cs_initialize(spi_host_device_t host, int cs_io_num, int cs_num, int force_gpio_matrix);
/**
* @brief Free a chip select line
* @deprecated Use spicommon_cs_io, which inputs the gpio num rather than the cs id instead.
*
* @param host SPI peripheral
* @param cs_num CS id to free
*/
void spicommon_cs_free(spi_host_device_t host, int cs_num) __attribute__((deprecated));
/**
* @brief Free a chip select line
*
* @param cs_gpio_num CS gpio num to free
*
* @note This public API is deprecated.
*/
void spicommon_cs_free_io(int cs_gpio_num);
/**
* @brief Setup a DMA link chain
* @brief Check whether all pins used by a host are through IOMUX.
*
* This routine will set up a chain of linked DMA descriptors in the array pointed to by
* ``dmadesc``. Enough DMA descriptors will be used to fit the buffer of ``len`` bytes in, and the
* descriptors will point to the corresponding positions in ``buffer`` and linked together. The
* end result is that feeding ``dmadesc[0]`` into DMA hardware results in the entirety ``len`` bytes
* of ``data`` being read or written.
* @param host SPI peripheral
*
* @param dmadesc Pointer to array of DMA descriptors big enough to be able to convey ``len`` bytes
* @param len Length of buffer
* @param data Data buffer to use for DMA transfer
* @param isrx True if data is to be written into ``data``, false if it's to be read from ``data``.
* @note This public API is deprecated.
*
* @return false if any pins are through the GPIO matrix, otherwise true.
*/
void spicommon_setup_dma_desc_links(lldesc_t *dmadesc, int len, const uint8_t *data, bool isrx);
bool spicommon_bus_using_iomux(spi_host_device_t host);
/**
* @brief Get the position of the hardware registers for a specific SPI host
* @brief Check whether all pins used by a host are through IOMUX.
*
* @param host The SPI host
* @param host SPI peripheral
*
* @return A register descriptor stuct pointer, pointed at the hardware registers
* @note This public API is deprecated.
*
* @return false if any pins are through the GPIO matrix, otherwise true.
*/
spi_dev_t *spicommon_hw_for_host(spi_host_device_t host);
bool spicommon_bus_using_iomux(spi_host_device_t host);
/**
* @brief Get the IRQ source for a specific SPI host
*
* @param host The SPI host
*
* @note This public API is deprecated.
*
* @return The hosts IRQ source
*/
int spicommon_irqsource_for_host(spi_host_device_t host);
/**
* @brief Get the IRQ source for a specific SPI DMA
*
* @param host The SPI host
*
* @note This public API is deprecated.
*
* @return The hosts IRQ source
*/
int spicommon_irqdma_source_for_host(spi_host_device_t host);
/**
* @brief Get the IRQ source for a specific SPI DMA
*
@@ -349,6 +374,8 @@ typedef void(*dmaworkaround_cb_t)(void *arg);
* @param cb Callback to call in case DMA channel cannot be reset immediately
* @param arg Argument to the callback
*
* @note This public API is deprecated.
*
* @return True when a DMA reset could be executed immediately. False when it could not; in this
* case the callback will be called with the specified argument when the logic can execute
* a reset, after that reset.
@@ -359,6 +386,8 @@ bool spicommon_dmaworkaround_req_reset(int dmachan, dmaworkaround_cb_t cb, void
/**
* @brief Check if a DMA reset is requested but has not completed yet
*
* @note This public API is deprecated.
*
* @return True when a DMA reset is requested but hasn't completed yet. False otherwise.
*/
bool spicommon_dmaworkaround_reset_in_progress();
@@ -369,6 +398,8 @@ bool spicommon_dmaworkaround_reset_in_progress();
*
* A call to this function tells the workaround logic that this channel will
* not be affected by a global SPI DMA reset.
*
* @note This public API is deprecated.
*/
void spicommon_dmaworkaround_idle(int dmachan);
@@ -377,13 +408,13 @@ void spicommon_dmaworkaround_idle(int dmachan);
*
* A call to this function tells the workaround logic that this channel will
* be affected by a global SPI DMA reset, and a reset like that should not be attempted.
*
* @note This public API is deprecated.
*/
void spicommon_dmaworkaround_transfer_active(int dmachan);
/** @endcond */
#ifdef __cplusplus
}
#endif
#endif