spi: add documents explicitly showing the executing core of the ISR

It is an ESP specific FreeRTOS feature that the ISR is always executed
on the core which calls the interrupt register function. In the SPI
driver, the function is always called in the bus initialization
function.

Hence, the ISR will be executed on the core which initialize the driver.

If the core is starved due to higher priority ISRs, or the interrupt is
disabled on the core (spinlock called, etc.), the ISR will not get
executed and SPI transactions will not be handled.

(MINOR CHANGE)

Resolves https://github.com/espressif/esp-idf/issues/2432.

diff --git a/components/driver/include/driver/spi_master.h b/components/driver/include/driver/spi_master.h
index ca82468890cc26b3abfa6736a7dbf215e6588702..04f2ba1f237a975dddce29d8eab2ebdc14e92e0c 100644 (file)
--- a/components/driver/include/driver/spi_master.h
+++ b/components/driver/include/driver/spi_master.h
@@ -150,6 +150,10 @@ typedef struct spi_device_t* spi_device_handle_t;  ///< Handle for a device on a
  * @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

diff --git a/components/driver/include/driver/spi_slave.h b/components/driver/include/driver/spi_slave.h
index 9ad4b9126d42647062d48abc2af27f9ad67d06df..ba0ce1de69dea74ff635c949f2949f5263c63286 100644 (file)
--- a/components/driver/include/driver/spi_slave.h
+++ b/components/driver/include/driver/spi_slave.h
@@ -71,10 +71,14 @@ struct spi_slave_transaction_t {
  *                 it. The SPI hardware has two DMA channels to share. This parameter indicates which
  *                 one to use.
  *
- * @warning If a DMA channel is selected, any transmit and receive buffer used should be allocated in 
+ * @warning If a DMA channel is selected, any transmit and receive buffer used should be allocated in
  *          DMA-capable memory.
  *
- * @return 
+ * @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
@@ -86,7 +90,7 @@ esp_err_t spi_slave_initialize(spi_host_device_t host, const spi_bus_config_t *b
  * @brief Free a SPI bus claimed as a SPI slave interface
  *
  * @param host SPI peripheral to free
- * @return 
+ * @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
@@ -110,7 +114,7 @@ esp_err_t spi_slave_free(spi_host_device_t host);
  *                   into the transaction description.
  * @param ticks_to_wait Ticks to wait until there's room in the queue; use portMAX_DELAY to
  *                      never time out.
- * @return 
+ * @return
  *         - ESP_ERR_INVALID_ARG   if parameter is invalid
  *         - ESP_OK                on success
  */
@@ -120,19 +124,19 @@ esp_err_t spi_slave_queue_trans(spi_host_device_t host, const spi_slave_transact
 /**
  * @brief Get the result of a SPI transaction queued earlier
  *
- * This routine will wait until a transaction to the given device (queued earlier with 
+ * This routine will wait until a transaction to the given device (queued earlier with
  * spi_slave_queue_trans) has 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 
+ * completed transaction so software can inspect the result and e.g. free the memory or
  * re-use the buffers.
  *
  * It is mandatory to eventually use this function for any transaction queued by ``spi_slave_queue_trans``.
  *
  * @param host SPI peripheral to that is acting as a slave
- * @param[out] trans_desc Pointer to variable able to contain a pointer to the description of the 
+ * @param[out] trans_desc Pointer to variable able to contain a pointer to the description of the
  *                   transaction that is executed
  * @param ticks_to_wait Ticks to wait until there's a returned item; use portMAX_DELAY to never time
  *                      out.
- * @return 
+ * @return
  *         - ESP_ERR_INVALID_ARG   if parameter is invalid
  *         - ESP_OK                on success
  */
@@ -143,16 +147,16 @@ esp_err_t spi_slave_get_trans_result(spi_host_device_t host, spi_slave_transacti
  * @brief Do a SPI transaction
  *
  * Essentially does the same as spi_slave_queue_trans followed by spi_slave_get_trans_result. Do
- * not use this when there is still a transaction queued that hasn't been finalized 
+ * not use this when there is still a transaction queued that hasn't been finalized
  * using spi_slave_get_trans_result.
  *
  * @param host SPI peripheral to that is acting as a slave
- * @param trans_desc Pointer to variable able to contain a pointer to the description of the 
+ * @param trans_desc Pointer to variable able to contain a pointer to the description of the
  *                   transaction that is executed. Not const because we may want to write status back
  *                   into the transaction description.
  * @param ticks_to_wait Ticks to wait until there's a returned item; use portMAX_DELAY to never time
  *                      out.
- * @return 
+ * @return
  *         - ESP_ERR_INVALID_ARG   if parameter is invalid
  *         - ESP_OK                on success
  */