Merge branch 'feature/ulp_ticks_and_cycles' into 'master'

feat(ulp): Removes ambiguity between ticks and cycles in ULP APIs

Closes IDFGH-16733

See merge request espressif/esp-idf!43153

Author: Konstantin Kondrashov

components/ulp/lp_core/lp_core/include/ulp_lp_core_i2c.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -25,7 +25,7 @@ extern "C" {
  * @param device_addr       I2C device address (7-bit)
  * @param data_rd           Buffer to hold data to be read
  * @param size              Size of data to be read in bytes
- * @param ticks_to_wait     Operation timeout in CPU cycles. Set to -1 to wait forever.
+ * @param cycles_to_wait    Operation timeout in CPU cycles. Set to -1 to wait forever.
  *
  * @return esp_err_t    ESP_OK when successful
  *
@@ -34,7 +34,7 @@ extern "C" {
  */
 esp_err_t lp_core_i2c_master_read_from_device(i2c_port_t lp_i2c_num, uint16_t device_addr,
                                               uint8_t *data_rd, size_t size,
-                                              int32_t ticks_to_wait);
+                                              int32_t cycles_to_wait);
 
 /**
  * @brief Write to I2C device
@@ -46,7 +46,7 @@ esp_err_t lp_core_i2c_master_read_from_device(i2c_port_t lp_i2c_num, uint16_t de
  * @param device_addr       I2C device address (7-bit)
  * @param data_wr           Buffer which holds the data to be written
  * @param size              Size of data to be written in bytes
- * @param ticks_to_wait     Operation timeout in CPU cycles. Set to -1 to wait forever.
+ * @param cycles_to_wait    Operation timeout in CPU cycles. Set to -1 to wait forever.
  *
  * @return esp_err_t    ESP_OK when successful
  *
@@ -55,7 +55,7 @@ esp_err_t lp_core_i2c_master_read_from_device(i2c_port_t lp_i2c_num, uint16_t de
  */
 esp_err_t lp_core_i2c_master_write_to_device(i2c_port_t lp_i2c_num, uint16_t device_addr,
                                              const uint8_t *data_wr, size_t size,
-                                             int32_t ticks_to_wait);
+                                             int32_t cycles_to_wait);
 
 /**
  * @brief Write to and then read from an I2C device in a single transaction
@@ -69,7 +69,7 @@ esp_err_t lp_core_i2c_master_write_to_device(i2c_port_t lp_i2c_num, uint16_t dev
  * @param write_size        Size of data to be written in bytes
  * @param data_rd           Buffer to hold data to be read
  * @param read_size         Size of data to be read in bytes
- * @param ticks_to_wait     Operation timeout in CPU cycles. Set to -1 to wait forever.
+ * @param cycles_to_wait    Operation timeout in CPU cycles. Set to -1 to wait forever.
  *
  * @return esp_err_t    ESP_OK when successful
  *
@@ -79,7 +79,7 @@ esp_err_t lp_core_i2c_master_write_to_device(i2c_port_t lp_i2c_num, uint16_t dev
 esp_err_t lp_core_i2c_master_write_read_device(i2c_port_t lp_i2c_num, uint16_t device_addr,
                                                const uint8_t *data_wr, size_t write_size,
                                                uint8_t *data_rd, size_t read_size,
-                                               int32_t ticks_to_wait);
+                                               int32_t cycles_to_wait);
 
 /**
  * @brief Enable or disable ACK checking by the LP_I2C controller during write operations

components/ulp/lp_core/lp_core/include/ulp_lp_core_spi.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -39,26 +39,26 @@ typedef struct {
  * from the device.
  *
  * @param trans_desc        LP SPI transaction configuration descriptor
- * @param ticks_to_wait     Operation timeout in CPU cycles. Set to -1 to wait forever.
+ * @param cycles_to_wait    Operation timeout in CPU cycles. Set to -1 to wait forever.
  *
  * @return esp_err_t        ESP_OK when successful
  *                          ESP_ERR_INVALID_ARG if the configuration is invalid
  *                          ESP_ERR_TIMEOUT when the operation times out
  */
-esp_err_t lp_core_lp_spi_master_transfer(lp_spi_transaction_t *trans_desc, int32_t ticks_to_wait);
+esp_err_t lp_core_lp_spi_master_transfer(lp_spi_transaction_t *trans_desc, int32_t cycles_to_wait);
 
 /**
  * @brief Initiate an LP SPI transaction in slave mode to receive data from an SPI master and optionally transmit data
  * back to the master.
  *
  * @param trans_desc        LP SPI transaction configuration descriptor
- * @param ticks_to_wait     Operation timeout in CPU cycles. Set to -1 to wait forever.
+ * @param cycles_to_wait    Operation timeout in CPU cycles. Set to -1 to wait forever.
  *
  * @return esp_err_t        ESP_OK when successful
  *                          ESP_ERR_INVALID_ARG if the configuration is invalid
  *                          ESP_ERR_TIMEOUT when the operation times out
  */
-esp_err_t lp_core_lp_spi_slave_transfer(lp_spi_transaction_t *trans_desc, int32_t ticks_to_wait);
+esp_err_t lp_core_lp_spi_slave_transfer(lp_spi_transaction_t *trans_desc, int32_t cycles_to_wait);
 
 #ifdef __cplusplus
 }

components/ulp/lp_core/lp_core/lp_core_i2c.c

@@ -65,7 +65,7 @@ static void lp_core_i2c_format_cmd(uint32_t cmd_idx, uint8_t op_code, uint8_t ac
     i2c_ll_master_write_cmd_reg(dev, hw_cmd, cmd_idx);
 }
 
-static inline esp_err_t lp_core_i2c_wait_for_interrupt(uint32_t intr_mask, int32_t ticks_to_wait)
+static inline esp_err_t lp_core_i2c_wait_for_interrupt(uint32_t intr_mask, int32_t cycles_to_wait)
 {
     uint32_t intr_status = 0;
     uint32_t to = 0;
@@ -96,13 +96,13 @@ static inline esp_err_t lp_core_i2c_wait_for_interrupt(uint32_t intr_mask, int32
             break;
         }
 
-        if (ticks_to_wait > -1) {
-            /* If the ticks_to_wait value is not -1, keep track of ticks and
+        if (cycles_to_wait > -1) {
+            /* If the cycles_to_wait value is not -1, keep track of cycles and
              * break from the loop once the timeout is reached.
              */
             ulp_lp_core_delay_cycles(1);
             to++;
-            if (to >= ticks_to_wait) {
+            if (to >= cycles_to_wait) {
                 /* Timeout. Clear interrupt bits and return an error */
                 i2c_ll_clear_intr_mask(dev, intr_mask);
                 return ESP_ERR_TIMEOUT;
@@ -142,7 +142,7 @@ void lp_core_i2c_master_set_ack_check_en(i2c_port_t lp_i2c_num, bool ack_check_e
 
 esp_err_t lp_core_i2c_master_read_from_device(i2c_port_t lp_i2c_num, uint16_t device_addr,
                                               uint8_t *data_rd, size_t size,
-                                              int32_t ticks_to_wait)
+                                              int32_t cycles_to_wait)
 {
     (void)lp_i2c_num;
 
@@ -215,7 +215,7 @@ esp_err_t lp_core_i2c_master_read_from_device(i2c_port_t lp_i2c_num, uint16_t de
         i2c_ll_start_trans(dev);
 
         /* Wait for the transfer to complete */
-        ret = lp_core_i2c_wait_for_interrupt(intr_mask, ticks_to_wait);
+        ret = lp_core_i2c_wait_for_interrupt(intr_mask, cycles_to_wait);
         if (ret != ESP_OK) {
             /* Transaction error. Abort. */
             return ret;
@@ -233,7 +233,7 @@ esp_err_t lp_core_i2c_master_read_from_device(i2c_port_t lp_i2c_num, uint16_t de
 
 esp_err_t lp_core_i2c_master_write_to_device(i2c_port_t lp_i2c_num, uint16_t device_addr,
                                              const uint8_t *data_wr, size_t size,
-                                             int32_t ticks_to_wait)
+                                             int32_t cycles_to_wait)
 {
     (void)lp_i2c_num;
 
@@ -306,7 +306,7 @@ esp_err_t lp_core_i2c_master_write_to_device(i2c_port_t lp_i2c_num, uint16_t dev
         i2c_ll_start_trans(dev);
 
         /* Wait for the transfer to complete */
-        ret = lp_core_i2c_wait_for_interrupt(intr_mask, ticks_to_wait);
+        ret = lp_core_i2c_wait_for_interrupt(intr_mask, cycles_to_wait);
         if (ret != ESP_OK) {
             /* Transaction error. Abort. */
             return ret;
@@ -325,7 +325,7 @@ esp_err_t lp_core_i2c_master_write_to_device(i2c_port_t lp_i2c_num, uint16_t dev
 esp_err_t lp_core_i2c_master_write_read_device(i2c_port_t lp_i2c_num, uint16_t device_addr,
                                                const uint8_t *data_wr, size_t write_size,
                                                uint8_t *data_rd, size_t read_size,
-                                               int32_t ticks_to_wait)
+                                               int32_t cycles_to_wait)
 {
     (void)lp_i2c_num;
 
@@ -393,7 +393,7 @@ esp_err_t lp_core_i2c_master_write_read_device(i2c_port_t lp_i2c_num, uint16_t d
         i2c_ll_start_trans(dev);
 
         /* Wait for the transfer to complete */
-        ret = lp_core_i2c_wait_for_interrupt(intr_mask, ticks_to_wait);
+        ret = lp_core_i2c_wait_for_interrupt(intr_mask, cycles_to_wait);
         if (ret != ESP_OK) {
             /* Transaction error. Abort. */
             return ret;
@@ -462,7 +462,7 @@ esp_err_t lp_core_i2c_master_write_read_device(i2c_port_t lp_i2c_num, uint16_t d
         i2c_ll_start_trans(dev);
 
         /* Wait for the transfer to complete */
-        ret = lp_core_i2c_wait_for_interrupt(intr_mask, ticks_to_wait);
+        ret = lp_core_i2c_wait_for_interrupt(intr_mask, cycles_to_wait);
         if (ret != ESP_OK) {
             /* Transaction error. Abort. */
             return ret;

components/ulp/lp_core/lp_core/lp_core_spi.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -17,16 +17,16 @@
 /* Use the register structure to access LP_SPI module registers */
 lp_spi_dev_t *lp_spi_dev = &LP_SPI;
 
-static inline esp_err_t lp_core_spi_wait_for_interrupt(int32_t ticks_to_wait)
+static inline esp_err_t lp_core_spi_wait_for_interrupt(int32_t cycles_to_wait)
 {
     uint32_t to = 0;
     while (!lp_spi_dev->spi_dma_int_raw.reg_trans_done_int_raw) {
-        if (ticks_to_wait > -1) {
-            /* If the ticks_to_wait value is not -1, keep track of ticks and
+        if (cycles_to_wait > -1) {
+            /* If the cycles_to_wait value is not -1, keep track of cycles and
              * break from the loop once the timeout is reached.
              */
             to++;
-            if (to >= ticks_to_wait) {
+            if (to >= cycles_to_wait) {
                 /* Clear interrupt bits */
                 lp_spi_dev->spi_dma_int_clr.reg_trans_done_int_clr = 1;
                 return ESP_ERR_TIMEOUT;
@@ -41,7 +41,7 @@ static inline esp_err_t lp_core_spi_wait_for_interrupt(int32_t ticks_to_wait)
 ////////////////////////////////// Public APIs ///////////////////////////////////
 //////////////////////////////////////////////////////////////////////////////////
 
-esp_err_t lp_core_lp_spi_master_transfer(lp_spi_transaction_t *trans_desc, int32_t ticks_to_wait)
+esp_err_t lp_core_lp_spi_master_transfer(lp_spi_transaction_t *trans_desc, int32_t cycles_to_wait)
 {
     esp_err_t ret = ESP_OK;
 
@@ -130,7 +130,7 @@ esp_err_t lp_core_lp_spi_master_transfer(lp_spi_transaction_t *trans_desc, int32
             lp_spi_dev->spi_cmd.reg_usr = 1;
 
             /* Wait for the transaction to complete */
-            ret = lp_core_spi_wait_for_interrupt(ticks_to_wait);
+            ret = lp_core_spi_wait_for_interrupt(cycles_to_wait);
             if (ret != ESP_OK) {
                 return ret;
             }
@@ -152,7 +152,7 @@ esp_err_t lp_core_lp_spi_master_transfer(lp_spi_transaction_t *trans_desc, int32
     return ret;
 }
 
-esp_err_t lp_core_lp_spi_slave_transfer(lp_spi_transaction_t *trans_desc, int32_t ticks_to_wait)
+esp_err_t lp_core_lp_spi_slave_transfer(lp_spi_transaction_t *trans_desc, int32_t cycles_to_wait)
 {
     esp_err_t ret = ESP_OK;
 
@@ -203,7 +203,7 @@ esp_err_t lp_core_lp_spi_slave_transfer(lp_spi_transaction_t *trans_desc, int32_
 
     while (rx_idx < length_in_bytes) {
         /* Wait for the transmission to complete */
-        ret = lp_core_spi_wait_for_interrupt(ticks_to_wait);
+        ret = lp_core_spi_wait_for_interrupt(cycles_to_wait);
         if (ret != ESP_OK) {
             return ret;
         }
@@ -247,7 +247,7 @@ esp_err_t lp_core_lp_spi_slave_transfer(lp_spi_transaction_t *trans_desc, int32_
         lp_spi_dev->spi_cmd.reg_usr = 1;
 
         /* Wait for the transaction to complete */
-        ret = lp_core_spi_wait_for_interrupt(ticks_to_wait);
+        ret = lp_core_spi_wait_for_interrupt(cycles_to_wait);
         if (ret != ESP_OK) {
             return ret;
         }

components/ulp/lp_core/lp_core/lp_core_uart.c

@@ -22,13 +22,13 @@ uart_hal_context_t hal = {
     .dev = (uart_dev_t *)UART_LL_GET_HW(LP_UART_NUM_0),
 };
 
-static esp_err_t lp_core_uart_check_timeout(uint32_t intr_mask, int32_t timeout, uint32_t *ticker)
+static esp_err_t lp_core_uart_check_timeout(uint32_t intr_mask, int32_t timeout, uint32_t *cycle_count)
 {
     if (timeout > -1) {
-        /* If the timeout value is not -1, delay for 1 CPU cycle and keep track of ticks */
+        /* If the timeout value is not -1, delay for 1 CPU cycle and keep track of cycles */
         ulp_lp_core_delay_cycles(1);
-        *ticker = *ticker + 1;
-        if (*ticker >= timeout) {
+        (*cycle_count)++;
+        if (*cycle_count >= (uint32_t)timeout) {
             /* Disable and clear interrupt bits */
             uart_hal_disable_intr_mask(&hal, intr_mask);
             uart_hal_clr_intsts_mask(&hal, intr_mask);

components/ulp/ulp_riscv/ulp_core/ulp_riscv_i2c.c

@@ -67,7 +67,7 @@ static void ulp_riscv_i2c_format_cmd(uint32_t cmd_idx, uint8_t op_code, uint8_t
                    ((byte_num & 0xFF) << 0));      // Byte Num
 }
 
-static inline int32_t ulp_riscv_i2c_wait_for_interrupt(int32_t ticks_to_wait)
+static inline int32_t ulp_riscv_i2c_wait_for_interrupt(int32_t cycles_to_wait)
 {
     uint32_t status = 0;
     uint32_t to = 0;
@@ -90,13 +90,13 @@ static inline int32_t ulp_riscv_i2c_wait_for_interrupt(int32_t ticks_to_wait)
             return -1;
         }
 
-        if (ticks_to_wait > -1) {
-            /* If the ticks_to_wait value is not -1, keep track of ticks and
+        if (cycles_to_wait > -1) {
+            /* If the cycles_to_wait value is not -1, keep track of cycles and
              * break from the loop once the timeout is reached.
              */
             ulp_riscv_delay_cycles(1);
             to++;
-            if (to >= ticks_to_wait) {
+            if (to >= cycles_to_wait) {
                 return -1;
             }
         }