在 ESP32 的 ESP-IDF SDK 內包函有 SPI 的應用程式接口（API）函數 （Function），但這應用程式接口（API / Application Programming Interface）函數會使用在程式上，筆者為了方便，將 SPI 的函數都放在 Blog 上，隨時可以查閱。
 |
| ESP32 SPI Mater 主驅動 API函數 |
- 通過調用 spi_bus_initialize 初始化 SPI 總線。 確保在 bus_config 結構中設置正確的 IO 引腳。 注意將不需要的信號設置為 -1。
- 通過調用 spi_bus_add_device 告訴驅動程序有關連接到總線的 SPI 從設備。 確保在 dev_config 結構中配置設備具有的任何時序要求。 您現在應該擁有該設備的句柄，以便在發送事務時使用。
- 要與設備交互，請使用您需要的任何事務參數填充一個或多個 spi_transaction_t 結構。 然後以輪詢方式或中斷方式發送它們。
功能 – spi_bus_initialize ()
原型：esp_err_t spi_bus_initialize(spi_host_device_t host, const spi_bus_config_t *bus_config, int dma_chan)
參數：host: SPI peripheral that controls this bus bus_config: Pointer to a spi_bus_config_t struct specifying how the host should be initialized 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 32.
返回：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
說明：Initialize a SPI bus. For now, only supports HSPI and VSPI.
範例：
功能 – spi_bus_free()
原型：esp_err_t spi_bus_free(spi_host_device_t host)
參數：host: SPI peripheral to free
返回：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
說明：Free a SPI bus，In order for this to succeed，all devices have to be removed first
範例：
功能 – spi_bus_add_device()
原型：esp_err_t spi_bus_add_device(spi_host_device_t host, const spi_device_interface_config_t *dev_config, spi_device_handle_t *handle)
參數：host：SPI peripheral to allocate device on
dev_config：SPI interface protocol config for the device
handle：Pointer to variable to hold the device handle
返回：ESP_ERR_INVALID_ARG if parameter is invalid
ESP_ERR_NOT_FOUND if host doesn’t have any free CS slots
ESP_ERR_NO_MEM if out of memory
ESP_OK on success
說明：Allocate a device on a SPI bus。This initializes the internal structures for a device, plus allocates a CS pin on the indicated SPI master peripheral and routes it to the indicated GPIO. All SPI master devices have three CS pins and can thus control up to three devices. While in general, speeds up to 80MHz on the dedicated SPI pins and 40MHz on GPIO-matrix-routed pins are supported, full-duplex transfers routed over the GPIO matrix only support speeds up to 26MHz.
範例：
功能 – spi_bus_remove_device()
原型：esp_err_t spi_bus_remove_device(spi_device_handle_t handle)
參數：handle：Device handle to free
返回：ESP_ERR_INVALID_ARG if parameter is invalid
ESP_ERR_INVALID_STATE if device already is freed
ESP_OK on success
說明：Remove a device from the SPI bus.
範例：
功能 – spi_device_queue_trans()
原型：esp_err_t spi_device_queue_trans(spi_device_handle_t handle, spi_transaction_t *trans_desc, TickType_t ticks_to_wait)
參數：handle：Device handle obtained using spi_host_add_dev
trans_desc：Description of transaction to execute
ticks_to_wait：Ticks to wait until there’s room in the queue; use portMAX_DELAY to never time out.
返回：ESP_ERR_INVALID_ARG if parameter is invalid
ESP_ERR_TIMEOUT if there was no room in the queue before ticks_to_wait expired
ESP_ERR_NO_MEM if allocating DMA-capable temporary buffer failed
ESP_ERR_INVALID_STATE if previous transactions are not finished
ESP_OK on success
說明：Queue a SPI transaction for interrupt transaction execution. Get the result by spi_device_get_trans_result. Normally a device cannot start (queue) polling and interrupt transactions simultaneously.
範例：
功能 – spi_device_get_trans_result()
原型：esp_err_t spi_device_get_trans_result(spi_device_handle_t handle, spi_transaction_t **trans_desc, TickType_t ticks_to_wait)
參數：handle：Device handle obtained using spi_host_add_dev
trans_desc：Pointer to variable able to contain a pointer to the description of the transaction that is executed. The descriptor should not be modified until the descriptor is returned by spi_device_get_trans_result.
ticks_to_wait：Ticks to wait until there’s a returned item; use portMAX_DELAY to never time out.
返回：ESP_ERR_INVALID_ARG if parameter is invalid
ESP_ERR_TIMEOUT if there was no completed transaction before ticks_to_wait expired
ESP_OK on success
說明：Get the result of a SPI transaction queued earlier by spi_device_queue_trans. This routine will wait until a transaction to the given device succesfully completed. It will then return the description of the completed transaction so software can inspect the result and e.g. free the memory or re-use the buffers.
範例：
功能 – spi_device_transmit()
原型：esp_err_t spi_device_transmit(spi_device_handle_t handle, spi_transaction_t *trans_desc)
參數：handle：Device handle obtained using spi_host_add_dev
trans_desc：Description of transaction to execute
返回：ESP_ERR_INVALID_ARG if parameter is invalid
ESP_OK on success
說明：Send a SPI transaction, wait for it to complete, and return the result. This function is the equivalent of calling spi_device_queue_trans() followed by spi_device_get_trans_result(). Do not use this when there is still a transaction separately queued (started) from spi_device_queue_trans() or polling_start/transmit that hasn’t been finalized.. This function is not thread safe when multiple tasks access the same SPI device. Normally a device cannot start (queue) polling and interrupt transactions simutanuously.
範例：
功能 – spi_device_polling_start()
原型：esp_err_t spi_device_polling_start(spi_device_handle_t handle, spi_transaction_t *trans_desc, TickType_t ticks_to_wait)
參數：handle：Device handle obtained using spi_host_add_dev
trans_desc：Description of transaction to execute
ticks_to_wait：Ticks to wait until there’s room in the queue; currently only portMAX_DELAY is supported.
返回：ESP_ERR_INVALID_ARG if parameter is invalid
ESP_ERR_TIMEOUT if the device cannot get control of the bus before ticks_to_wait expired
ESP_ERR_NO_MEM if allocating DMA-capable temporary buffer failed
ESP_ERR_INVALID_STATE if previous transactions are not finished
ESP_OK on success
說明：Immediately start a polling transaction. Normally a device cannot start (queue) polling and interrupt transactions simutanuously. Moreover, a device cannot start a new polling transaction if another polling transaction is not finished.
範例：
功能 – spi_device_polling_end()
原型：esp_err_t spi_device_polling_end(spi_device_handle_t handle, TickType_t ticks_to_wait)
參數：handle：Device handle obtained using spi_host_add_dev
ticks_to_wait：Ticks to wait until there’s a returned item; use portMAX_DELAY to never time out.
返回：ESP_ERR_INVALID_ARG if parameter is invalid
ESP_ERR_TIMEOUT if the transaction cannot finish before ticks_to_wait expired
ESP_OK on success
說明：Poll until the polling transaction ends. This routine will not return until the transaction to the given device has succesfully completed. The task is not blocked, but actively busy-spins for the transaction to be completed.
範例：
功能 – spi_device_polling_transmit()
原型：esp_err_t spi_device_polling_transmit(spi_device_handle_t handle, spi_transaction_t *trans_desc)
參數：handle：Device handle obtained using spi_host_add_dev
trans_desc：Description of transaction to execute
返回：ESP_ERR_INVALID_ARG if parameter is invalid
ESP_OK on success
說明：Send a polling transaction, wait for it to complete, and return the result. This function is the equivalent of calling spi_device_polling_start() followed by spi_device_polling_end(). Do not use this when there is still a transaction that hasn’t been finalized. This function is not thread safe when multiple tasks access the same SPI device. Normally a device cannot start (queue) polling and interrupt transactions simutanuously.
範例：
功能 – spi_device_acquire_bus()
原型：esp_err_t spi_device_acquire_bus(spi_device_handle_t device, TickType_t wait)
參數：device：The device to occupy the bus.
wait：Time to wait before the the bus is occupied by the device. Currently MUST set to portMAX_DELAY.
返回：Occupy the SPI bus for a device to do continuous transactions. Transactions to all other devices will be put off until spi_device_release_bus is called. Note： The function will wait until all the existing transactions have been sent.
說明：ESP_ERR_INVALID_ARG : wait is not set to portMAX_DELAY.
ESP_OK : Success.
範例：
功能 – spi_device_release_bus()
原型：void spi_device_release_bus(spi_device_handle_t dev)
參數：dev: The device to release the bus.
返回：無
說明：Release the SPI bus occupied by the device. All other devices can start sending transactions.
範例：
功能 – spi_cal_clock()
原型：int spi_cal_clock(int fapb, int hz, int duty_cycle, uint32_t *reg_o)
參數：fapb：The frequency of apb clock, should be APB_CLK_FREQ.
hz：Desired working frequency duty_cycle：Duty cycle of the spi clock
reg_o：Output of value to be set in clock register, or NULL if not needed.
返回：Actual working frequency that most fit.
說明：Calculate the working frequency that is most close to desired frequency, and also the register value.
範例：
功能 – spi_get_timing()
原型：void spi_get_timing(bool gpio_is_used, int input_delay_ns, int eff_clk, int *dummy_o, int *cycles_remain_o)
參數：gpio_is_used：True if using GPIO matrix, or False if iomux pins are used.
input_delay_ns：Input delay from SCLK launch edge to MISO data valid.
eff_clk：Effective clock frequency (in Hz) from spi_cal_clock.
dummy_o：Address of dummy bits used output. Set to NULL if not needed.
cycles_remain_o：Address of cycles remaining (after dummy bits are used) output. -1 If too many cycles remaining, suggest to compensate half a clock. 0 If no remaining cycles or dummy bits are not used.
positive value：cycles suggest to compensate.
返回：無
說明：Calculate the timing settings of specified frequency and settings. If **dummy_o* is not zero, it means dummy bits should be applied in half duplex mode, and full duplex mode may not work.
範例：
功能 – spi_get_freq_limit()
原型：int spi_get_freq_limit(bool gpio_is_used, int input_delay_ns)
參數：gpio_is_used: True if using GPIO matrix, or False if native pins are used. input_delay_ns: Input delay from SCLK launch edge to MISO data valid.
返回：Frequency limit of current configurations.
說明：Get the frequency limit of current configurations. SPI master working at this limit is OK, while above the limit, full duplex mode and DMA will not work, and dummy bits will be applied in the half duplex mode.
範例：
Header File：driver/include/driver/spi_master.h
相關網址：
※ DIY - ESP32：ESP32 ILI9341 2.4吋 SPI TFT LCD 液晶屏電路（十三）
※ DIY - ESP32：ESP32 ILI9341 2.4吋 SPI TFT LCD 液晶屏程式（十四）
※ DIY - ESP32：ESP32 SPI 驅動 IO 介紹（十五）
※ DIY - ESP32：ESP32 SPI Master 主驅動 API 函數結構件（十七）
2018年 10月 25日 天氣報告
氣溫：25.6度 @ 19:20
相對濕度：百分之 68%
天氣：天色大致良好
沒有留言:
張貼留言