feat(spi_master): add transaction config for dynamic clock speed update

Closes #13753

Author: wanckl

components/esp_driver_spi/include/driver/spi_master.h

@@ -137,6 +137,7 @@ struct spi_transaction_t {
                                       */
     size_t length;                  ///< Total data length, in bits
     size_t rxlength;                ///< Total data length received, should be not greater than ``length`` in full-duplex mode (0 defaults this to the value of ``length``).
+    uint32_t override_freq_hz;      ///< New freq speed value will override for current device, remain `0` to skip update. Need about 30us each time
     void *user;                     ///< User-defined variable. Can be used to store eg transaction ID.
     union {
         const void *tx_buffer;      ///< Pointer to transmit buffer, or NULL for no MOSI phase
@@ -205,7 +206,7 @@ esp_err_t spi_bus_remove_device(spi_device_handle_t handle);
  * @note Normally a device cannot start (queue) polling and interrupt
  *      transactions simultaneously.
  *
- * @param handle Device handle obtained using spi_host_add_dev
+ * @param handle Device handle obtained using spi_bus_add_device()
  * @param trans_desc Description of transaction to execute
  * @param ticks_to_wait Ticks to wait until there's room in the queue; use portMAX_DELAY to
  *                      never time out.
@@ -228,7 +229,7 @@ esp_err_t spi_device_queue_trans(spi_device_handle_t handle, spi_transaction_t *
  * completed transaction so software can inspect the result and e.g. free the memory or
  * reuse the buffers.
  *
- * @param handle Device handle obtained using spi_host_add_dev
+ * @param handle Device handle obtained using spi_bus_add_device()
  * @param 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.
@@ -252,7 +253,7 @@ esp_err_t spi_device_get_trans_result(spi_device_handle_t handle, spi_transactio
  *      Normally a device cannot start (queue) polling and interrupt
  *      transactions simutanuously.
  *
- * @param handle Device handle obtained using spi_host_add_dev
+ * @param handle Device handle obtained using spi_bus_add_device()
  * @param trans_desc Description of transaction to execute
  * @return
  *         - ESP_ERR_INVALID_ARG   if parameter is invalid
@@ -267,7 +268,7 @@ esp_err_t spi_device_transmit(spi_device_handle_t handle, spi_transaction_t *tra
  *      transactions simutanuously. Moreover, a device cannot start a new polling
  *      transaction if another polling transaction is not finished.
  *
- * @param handle Device handle obtained using spi_host_add_dev
+ * @param handle Device handle obtained using spi_bus_add_device()
  * @param trans_desc Description of transaction to execute
  * @param ticks_to_wait Ticks to wait until there's room in the queue;
  *              currently only portMAX_DELAY is supported.
@@ -290,7 +291,7 @@ esp_err_t spi_device_polling_start(spi_device_handle_t handle, spi_transaction_t
  * successfully completed. The task is not blocked, but actively busy-spins for
  * the transaction to be completed.
  *
- * @param handle Device handle obtained using spi_host_add_dev
+ * @param handle Device handle obtained using spi_bus_add_device()
  * @param ticks_to_wait Ticks to wait until there's a returned item; use portMAX_DELAY to never time
                         out.
  * @return
@@ -310,7 +311,7 @@ esp_err_t spi_device_polling_end(spi_device_handle_t handle, TickType_t ticks_to
  *      Normally a device cannot start (queue) polling and interrupt
  *      transactions simutanuously.
  *
- * @param handle Device handle obtained using spi_host_add_dev
+ * @param handle Device handle obtained using spi_bus_add_device()
  * @param trans_desc Description of transaction to execute
  * @return
  *         - ESP_ERR_INVALID_ARG   if parameter is invalid
@@ -368,19 +369,19 @@ esp_err_t spi_device_get_actual_freq(spi_device_handle_t handle, int *freq_khz);
 int spi_get_actual_clock(int fapb, int hz, int duty_cycle) __attribute__((deprecated("Please use spi_device_get_actual_freq instead")));
 
 /**
-  * @brief Calculate the timing settings of specified frequency and settings.
-  *
-  * @param gpio_is_used True if using GPIO matrix, or False if iomux pins are used.
-  * @param input_delay_ns Input delay from SCLK launch edge to MISO data valid.
-  * @param eff_clk Effective clock frequency (in Hz) from `spi_get_actual_clock()`.
-  * @param dummy_o Address of dummy bits used output. Set to NULL if not needed.
-  * @param 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.
-  *
-  * @note If **dummy_o* is not zero, it means dummy bits should be applied in half duplex mode, and full duplex mode may not work.
-  */
+ * @brief Calculate the timing settings of specified frequency and settings.
+ *
+ * @param gpio_is_used True if using GPIO matrix, or False if iomux pins are used.
+ * @param input_delay_ns Input delay from SCLK launch edge to MISO data valid.
+ * @param eff_clk Effective clock frequency (in Hz) from `spi_get_actual_clock()`.
+ * @param dummy_o Address of dummy bits used output. Set to NULL if not needed.
+ * @param 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.
+ *
+ * @note If **dummy_o* is not zero, it means dummy bits should be applied in half duplex mode, and full duplex mode may not work.
+ */
 void spi_get_timing(bool gpio_is_used, int input_delay_ns, int eff_clk, int *dummy_o, int *cycles_remain_o);
 
 /**

components/esp_driver_spi/src/gpspi/spi_master.c

@@ -487,6 +487,7 @@ esp_err_t spi_bus_add_device(spi_host_device_t host_id, const spi_device_interfa
     SPI_CHECK(ret == ESP_OK, "assigned clock speed not supported", ret);
     temp_timing_conf.clock_source = clk_src;
     temp_timing_conf.source_pre_div = clock_source_div;
+    temp_timing_conf.source_real_freq = clock_source_hz;
     temp_timing_conf.rx_sample_point = dev_config->sample_point;
     if (temp_timing_conf.rx_sample_point == SPI_SAMPLING_POINT_PHASE_1) {
         SPI_CHECK(spi_ll_master_is_rx_std_sample_supported(), "SPI_SAMPLING_POINT_PHASE_1 is not supported on this chip", ESP_ERR_NOT_SUPPORTED);
@@ -626,14 +627,33 @@ int spi_get_actual_clock(int fapb, int hz, int duty_cycle)
 
 // Setup the device-specified configuration registers. Called every time a new
 // transaction is to be sent, but only apply new configurations when the device
-// changes.
-static SPI_MASTER_ISR_ATTR void spi_setup_device(spi_device_t *dev)
+// changes or timing change is required.
+static SPI_MASTER_ISR_ATTR void spi_setup_device(spi_device_t *dev, spi_trans_priv_t *trans_buf)
 {
     spi_bus_lock_dev_handle_t dev_lock = dev->dev_lock;
     spi_hal_context_t *hal = &dev->host->hal;
     spi_hal_dev_config_t *hal_dev = &(dev->hal_dev);
 
-    if (spi_bus_lock_touch(dev_lock)) {
+    bool clock_changed = false;
+    // check if timing config update is required
+    if (trans_buf && (trans_buf->trans->override_freq_hz > 0) && (hal_dev->timing_conf.expect_freq != trans_buf->trans->override_freq_hz)) {
+        spi_hal_timing_param_t timing_param = {
+            .expected_freq = trans_buf->trans->override_freq_hz,
+            .clk_src_hz = dev->hal_dev.timing_conf.source_real_freq,
+            .duty_cycle = dev->cfg.duty_cycle_pos,
+            .input_delay_ns = dev->cfg.input_delay_ns,
+            .half_duplex = dev->hal_dev.half_duplex,
+            .use_gpio = !(dev->host->bus_attr->flags | SPICOMMON_BUSFLAG_IOMUX_PINS),
+        };
+
+        if (ESP_OK == spi_hal_cal_clock_conf(&timing_param, &dev->hal_dev.timing_conf)) {
+            clock_changed = true;
+        } else {
+            ESP_EARLY_LOGW(SPI_TAG, "assigned clock speed %d not supported", trans_buf->trans->override_freq_hz);
+        }
+    }
+
+    if (spi_bus_lock_touch(dev_lock) || clock_changed) {
         /* Configuration has not been applied yet. */
         spi_hal_setup_device(hal, hal_dev);
         SPI_MASTER_PERI_CLOCK_ATOMIC() {
@@ -781,7 +801,7 @@ static void SPI_MASTER_ISR_ATTR spi_new_trans(spi_device_t *dev, spi_trans_priv_
     dev->host->cur_cs = dev->id;
 
     //Reconfigure according to device settings, the function only has effect when the dev_id is changed.
-    spi_setup_device(dev);
+    spi_setup_device(dev, trans_buf);
 
     //set the transaction specific configuration each time before a transaction setup
     spi_hal_trans_config_t hal_trans = {};
@@ -856,7 +876,7 @@ static void SPI_MASTER_ISR_ATTR spi_new_sct_trans(spi_device_t *dev, spi_sct_tra
     dev->host->cur_cs = dev->id;
 
     //Reconfigure according to device settings, the function only has effect when the dev_id is changed.
-    spi_setup_device(dev);
+    spi_setup_device(dev, NULL);
 
 #if !CONFIG_IDF_TARGET_ESP32S2
     // s2 update this seg_gap_clock_len by dma from conf_buffer
@@ -1310,7 +1330,7 @@ esp_err_t SPI_MASTER_ISR_ATTR spi_device_acquire_bus(spi_device_t *device, TickT
     esp_pm_lock_acquire(host->bus_attr->pm_lock);
 #endif
     //configure the device ahead so that we don't need to do it again in the following transactions
-    spi_setup_device(host->device[device->id]);
+    spi_setup_device(host->device[device->id], NULL);
     //the DMA is also occupied by the device, all the slave devices that using DMA should wait until bus released.
 
 #if CONFIG_IDF_TARGET_ESP32

components/esp_driver_spi/test_apps/components/spi_bench_mark/include/spi_performance.h

@@ -54,21 +54,21 @@
 #endif
 
 #elif CONFIG_IDF_TARGET_ESP32C6
-#define IDF_PERFORMANCE_MAX_SPI_CLK_FREQ                            26*1000*1000
+#define IDF_PERFORMANCE_MAX_SPI_CLK_FREQ                            26666*1000
 #define IDF_PERFORMANCE_MAX_SPI_PER_TRANS_NO_POLLING                35  //TODO: IDF-9551, check perform
 #define IDF_PERFORMANCE_MAX_SPI_PER_TRANS_POLLING                   17
 #define IDF_PERFORMANCE_MAX_SPI_PER_TRANS_NO_POLLING_NO_DMA         32
 #define IDF_PERFORMANCE_MAX_SPI_PER_TRANS_POLLING_NO_DMA            15
 
 #elif CONFIG_IDF_TARGET_ESP32H2
-#define IDF_PERFORMANCE_MAX_SPI_CLK_FREQ                            26*1000*1000
+#define IDF_PERFORMANCE_MAX_SPI_CLK_FREQ                            24*1000*1000
 #define IDF_PERFORMANCE_MAX_SPI_PER_TRANS_POLLING                   32
 #define IDF_PERFORMANCE_MAX_SPI_PER_TRANS_POLLING_NO_DMA            25
 #define IDF_PERFORMANCE_MAX_SPI_PER_TRANS_NO_POLLING                61
 #define IDF_PERFORMANCE_MAX_SPI_PER_TRANS_NO_POLLING_NO_DMA         54
 
 #elif CONFIG_IDF_TARGET_ESP32P4
-#define IDF_PERFORMANCE_MAX_SPI_CLK_FREQ                            26*1000*1000
+#define IDF_PERFORMANCE_MAX_SPI_CLK_FREQ                            20*1000*1000
 #define IDF_PERFORMANCE_MAX_SPI_PER_TRANS_NO_POLLING                44
 #define IDF_PERFORMANCE_MAX_SPI_PER_TRANS_POLLING                   28
 #define IDF_PERFORMANCE_MAX_SPI_PER_TRANS_NO_POLLING_NO_DMA         26

components/esp_driver_spi/test_apps/master/main/test_spi_master.c

@@ -181,6 +181,44 @@ TEST_CASE("SPI Master clk_source and divider accuracy", "[spi]")
     TEST_ESP_OK(spi_bus_free(TEST_SPI_HOST));
 }
 
+TEST_CASE("test_device_dynamic_freq_update", "[spi]")
+{
+    spi_device_handle_t dev0;
+    int master_send;
+
+    spi_bus_config_t buscfg = SPI_BUS_TEST_DEFAULT_CONFIG();
+    spi_device_interface_config_t devcfg = SPI_DEVICE_TEST_DEFAULT_CONFIG();
+    devcfg.flags |= SPI_DEVICE_HALFDUPLEX;
+    TEST_ESP_OK(spi_bus_initialize(TEST_SPI_HOST, &buscfg, SPI_DMA_CH_AUTO));
+    TEST_ESP_OK(spi_bus_add_device(TEST_SPI_HOST, &devcfg, &dev0));
+
+    spi_transaction_t trans_cfg = {
+        .tx_buffer = &master_send,
+        .length = sizeof(master_send) * 8,
+    };
+
+    trans_cfg.override_freq_hz = IDF_PERFORMANCE_MAX_SPI_CLK_FREQ;
+    for (int i = 1; i < 15; i++) {
+        TEST_ESP_OK(spi_device_transmit(dev0, &trans_cfg));
+        spi_device_get_actual_freq(dev0, &master_send);
+        printf("override %5ld k real freq %5d k\n", trans_cfg.override_freq_hz / 1000, master_send);
+        if (trans_cfg.override_freq_hz) {
+            TEST_ASSERT_EQUAL_UINT32(trans_cfg.override_freq_hz / 1000, master_send);
+        }
+        if (i > 10) {
+            //test without override freq
+            trans_cfg.override_freq_hz = 0;
+            continue;
+        }
+        if (!(i % 2)) {
+            //test override freq every 2 trans
+            trans_cfg.override_freq_hz /= 2;
+        }
+    }
+    TEST_ESP_OK(spi_bus_remove_device(dev0));
+    TEST_ESP_OK(spi_bus_free(TEST_SPI_HOST));
+}
+
 static spi_device_handle_t setup_spi_bus_loopback(int clkspeed, bool dma)
 {
     spi_bus_config_t buscfg = {

components/hal/esp32/include/hal/spi_ll.h

@@ -652,6 +652,7 @@ static inline void spi_ll_master_set_clock_by_reg(spi_dev_t *hw, const spi_ll_cl
  *
  * @return Frequency of given dividers.
  */
+__attribute__((always_inline))
 static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
 {
     return (fapb / (pre * n));
@@ -667,6 +668,7 @@ static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
  *
  * @return Actual (nearest) frequency.
  */
+__attribute__((always_inline))
 static inline int spi_ll_master_cal_clock(int fapb, int hz, int duty_cycle, spi_ll_clock_val_t *out_reg)
 {
     typeof(SPI1.clock) reg = {.val = 0};

components/hal/esp32c2/include/hal/spi_ll.h

@@ -735,6 +735,7 @@ static inline void spi_ll_master_set_clock_by_reg(spi_dev_t *hw, const spi_ll_cl
  *
  * @return     Frequency of given dividers.
  */
+__attribute__((always_inline))
 static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
 {
     return (fapb / (pre * n));
@@ -750,6 +751,7 @@ static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
  *
  * @return           Actual (nearest) frequency.
  */
+__attribute__((always_inline))
 static inline int spi_ll_master_cal_clock(int fapb, int hz, int duty_cycle, spi_ll_clock_val_t *out_reg)
 {
     typeof(GPSPI2.clock) reg = {.val = 0};

components/hal/esp32c3/include/hal/spi_ll.h

@@ -737,6 +737,7 @@ static inline void spi_ll_master_set_clock_by_reg(spi_dev_t *hw, const spi_ll_cl
  *
  * @return     Frequency of given dividers.
  */
+__attribute__((always_inline))
 static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
 {
     return (fapb / (pre * n));
@@ -752,6 +753,7 @@ static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
  *
  * @return           Actual (nearest) frequency.
  */
+__attribute__((always_inline))
 static inline int spi_ll_master_cal_clock(int fapb, int hz, int duty_cycle, spi_ll_clock_val_t *out_reg)
 {
     typeof(GPSPI2.clock) reg = {.val = 0};

components/hal/esp32c5/include/hal/spi_ll.h

@@ -735,6 +735,7 @@ static inline void spi_ll_master_set_clock_by_reg(spi_dev_t *hw, const spi_ll_cl
  *
  * @return     Frequency of given dividers.
  */
+__attribute__((always_inline))
 static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
 {
     return (fapb / (pre * n));
@@ -750,6 +751,7 @@ static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
  *
  * @return           Actual (nearest) frequency.
  */
+__attribute__((always_inline))
 static inline int spi_ll_master_cal_clock(int fapb, int hz, int duty_cycle, spi_ll_clock_val_t *out_reg)
 {
     typeof(GPSPI2.clock) reg = {.val = 0};

components/hal/esp32c6/include/hal/spi_ll.h

@@ -728,6 +728,7 @@ static inline void spi_ll_master_set_clock_by_reg(spi_dev_t *hw, const spi_ll_cl
  *
  * @return     Frequency of given dividers.
  */
+__attribute__((always_inline))
 static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
 {
     return (fapb / (pre * n));
@@ -743,6 +744,7 @@ static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
  *
  * @return           Actual (nearest) frequency.
  */
+__attribute__((always_inline))
 static inline int spi_ll_master_cal_clock(int fapb, int hz, int duty_cycle, spi_ll_clock_val_t *out_reg)
 {
     typeof(GPSPI2.clock) reg = {.val = 0};

components/hal/esp32c61/include/hal/spi_ll.h

@@ -748,6 +748,7 @@ static inline void spi_ll_master_set_clock_by_reg(spi_dev_t *hw, const spi_ll_cl
  *
  * @return     Frequency of given dividers.
  */
+__attribute__((always_inline))
 static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
 {
     return (fapb / (pre * n));
@@ -763,6 +764,7 @@ static inline int spi_ll_freq_for_pre_n(int fapb, int pre, int n)
  *
  * @return           Actual (nearest) frequency.
  */
+__attribute__((always_inline))
 static inline int spi_ll_master_cal_clock(int fapb, int hz, int duty_cycle, spi_ll_clock_val_t *out_reg)
 {
     typeof(GPSPI2.clock) reg = {.val = 0};