docs: add information about execution time of ULP instructions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index b327068c2a3d4a4609992b2bdef4f90c1fba23f5..6e4c2eccafc6af83b21463d5bdcf3d4b860a57cf 100644 (file)
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -751,6 +751,13 @@ UT_003_08:
     - UT_T1_1
     - UT_single_core
 
+UT_003_09:
+  <<: *unit_test_template
+  tags:
+    - ESP32_IDF
+    - UT_T1_1
+    - UT_single_core
+
 UT_004_01:
   <<: *unit_test_template
   tags:

diff --git a/components/soc/esp32/test/test_rtc_clk.c b/components/soc/esp32/test/test_rtc_clk.c
index 00fb0040ff7b4118699328c2b637660831d555c1..3773f9401e1986e8f1ecfd2f9c2b5ec6ddcc1f52 100644 (file)
--- a/components/soc/esp32/test/test_rtc_clk.c
+++ b/components/soc/esp32/test/test_rtc_clk.c
@@ -112,6 +112,15 @@ static void test_clock_switching(void (*switch_func)(rtc_cpu_freq_t))
     ref_clock_deinit();
 }
 
+TEST_CASE("Calculate 8M clock frequency", "[rtc_clk]")
+{
+    // calibrate 8M/256 clock against XTAL, get 8M/256 clock period
+    uint32_t rtc_8md256_period = rtc_clk_cal(RTC_CAL_8MD256, 100);
+    uint32_t rtc_fast_freq_hz = 1000000ULL * (1 << RTC_CLK_CAL_FRACT) * 256 / rtc_8md256_period;
+    printf("RTC_FAST_CLK=%d Hz\n", rtc_fast_freq_hz);
+    TEST_ASSERT_INT32_WITHIN(500000, RTC_FAST_CLK_FREQ_APPROX, rtc_fast_freq_hz);
+}
+
 TEST_CASE("Test switching between PLL and XTAL", "[rtc_clk]")
 {
     test_clock_switching(rtc_clk_cpu_freq_set);

diff --git a/docs/api-guides/ulp_instruction_set.rst b/docs/api-guides/ulp_instruction_set.rst
index 62cbe3bd5ab6c03d2b47dc5f5372a825933776d7..893fcc56e13e4f54f3d4d0e03478e5bbce8542e0 100755 (executable)
--- a/docs/api-guides/ulp_instruction_set.rst
+++ b/docs/api-guides/ulp_instruction_set.rst
@@ -62,14 +62,32 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
           ST R2, R1, 0      // write value of R2 into the third array element,\r
                             // i.e. array[2]\r
 \r
+Note about instruction execution time\r
+-------------------------------------\r
+\r
+ULP coprocessor is clocked from RTC_FAST_CLK, which is normally derived from the internal 8MHz oscillator. Applications which need to know exact ULP clock frequency can calibrate it against the main XTAL clock::\r
+\r
+    #include "soc/rtc.h"\r
+\r
+    // calibrate 8M/256 clock against XTAL, get 8M/256 clock period\r
+    uint32_t rtc_8md256_period = rtc_clk_cal(RTC_CAL_8MD256, 100);\r
+    uint32_t rtc_fast_freq_hz = 1000000ULL * (1 << RTC_CLK_CAL_FRACT) * 256 / rtc_8md256_period;\r
+\r
+ULP coprocessor needs 2 clock cycle to fetch each instuction (fetching is not pipelined), plus certain number of cycles to execute, depending on the instruction. See description of each instruction for details on the execution time.\r
+\r
+Note that when accessing RTC memories and RTC registers, ULP coprocessor has lower priority than the main CPUs. This means that ULP coprocessor execution may be suspended while the main CPUs access same memory region as the ULP.\r
+\r
+\r
 **NOP** - no operation\r
 ----------------------\r
 \r
-**Syntax:**\r
+**Syntax**\r
   **NOP**\r
-**Operands:**\r
+**Operands**\r
   None\r
-**Description:**\r
+**Cycles**\r
+  2 (fetch) + 1 (execute)\r
+**Description**\r
   No operation is performed. Only the PC is incremented.\r
 \r
 **Example**::\r
@@ -80,20 +98,22 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 **ADD** - Add to register\r
 -------------------------\r
 \r
-**Syntax:**\r
+**Syntax**\r
     **ADD**      *Rdst, Rsrc1, Rsrc2*\r
 \r
     **ADD**      *Rdst, Rsrc1, imm*\r
 \r
 \r
-**Operands:**\r
+**Operands**\r
   - *Rdst* - Register R[0..3]\r
   - *Rsrc1* - Register R[0..3]\r
   - *Rsrc2* - Register R[0..3]\r
   - *Imm* - 16-bit signed value\r
 \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
 \r
-**Description:**\r
+**Description**\r
   The instruction adds source register to another source register or to a 16-bit signed value and stores result to the destination register.\r
 \r
 **Examples**::\r
@@ -115,21 +135,24 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 **SUB** - Subtract from register\r
 --------------------------------\r
 \r
-**Syntax:**\r
+**Syntax**\r
   **SUB** *Rdst, Rsrc1, Rsrc2*\r
 \r
   **SUB** *Rdst, Rsrc1, imm*\r
 \r
-**Operands:**\r
+**Operands**\r
   - *Rdst*  - Register R[0..3]\r
   - *Rsrc1* - Register R[0..3]\r
   - *Rsrc2* - Register R[0..3]\r
   - *Imm*   - 16-bit signed value\r
 \r
-**Description:**\r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
+**Description**\r
   The instruction subtracts the source register from another source register or subtracts 16-bit signed value from a source register, and stores result to the destination register.\r
 \r
-**Examples:**::\r
+**Examples**::\r
 \r
   1:         SUB R1, R2, R3             //R1 = R2 - R3\r
   \r
@@ -146,21 +169,24 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 **AND** - Logical AND of two operands\r
 -------------------------------------\r
 \r
-**Syntax:**\r
+**Syntax**\r
     **AND** *Rdst, Rsrc1, Rsrc2*\r
 \r
     **AND** *Rdst, Rsrc1, imm*\r
 \r
-**Operands:**\r
+**Operands**\r
   - *Rdst* - Register R[0..3]\r
   - *Rsrc1* - Register R[0..3]\r
   - *Rsrc2* - Register R[0..3]\r
   - *Imm* - 16-bit signed value\r
 \r
-**Description:**\r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
+**Description**\r
   The instruction does logical AND of a source register and another source register or 16-bit signed value and stores result to the destination register.\r
 \r
-**Example**::\r
+**Examples**::\r
 \r
   1:        AND R1, R2, R3          //R1 = R2 & R3\r
 \r
@@ -183,12 +209,14 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
  \r
   **OR** *Rdst, Rsrc1, imm*\r
 \r
-\r
 **Operands**\r
   - *Rdst* - Register R[0..3]\r
   - *Rsrc1* - Register R[0..3]\r
   - *Rsrc2* - Register R[0..3]\r
   - *Imm* - 16-bit signed value\r
+\r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
  \r
 **Description**\r
   The instruction does logical OR of a source register and another source register or 16-bit signed value and stores result to the destination register.\r
@@ -223,6 +251,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
   - *Rsrc2* - Register R[0..3]\r
   - *Imm* - 16-bit signed value\r
  \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
 **Description**\r
    The instruction does logical shift to left of source register to number of bits from another source register or 16-bit signed value and store result to the destination register.\r
 \r
@@ -255,6 +286,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
   *Rsrc2* - Register R[0..3]\r
   *Imm* - 16-bit signed value\r
 \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
 **Description**\r
   The instruction does logical shift to right of source register to number of bits from another source register or 16-bit signed value and store result to the destination register.\r
 \r
@@ -286,6 +320,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
   - *Rsrc* – Register R[0..3]\r
   - *Imm*  – 16-bit signed value\r
 \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
 **Description**\r
    The instruction move to destination register value from source register or 16-bit signed value.\r
 \r
@@ -318,6 +355,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
   - *Rdst* – Register R[0..3], address of the destination, in 32-bit words\r
   - *Offset* – 10-bit signed value, offset in bytes\r
 \r
+**Cycles**\r
+  2 (fetch) + 4 (execute)\r
+\r
 **Description**\r
   The instruction stores the 16-bit value of Rsrc to the lower half-word of memory with address Rdst+offset. The upper half-word is written with the current program counter (PC), expressed in words, shifted left by 5 bits::\r
 \r
@@ -352,6 +392,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
    \r
    *Offset* – 10-bit signed value, offset in bytes\r
 \r
+**Cycles**\r
+  2 (fetch) + 4 (execute)\r
+\r
 **Description**\r
    The instruction loads lower 16-bit half-word from memory with address Rsrc+offset into the destination register Rdst::\r
 \r
@@ -395,6 +438,8 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
      - EQ – jump if last ALU operation result was zero\r
      - OV – jump if last ALU has set overflow flag\r
 \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
 \r
 **Description**\r
   The instruction makes jump to the specified address. Jump can be either unconditional or based on an ALU flag.\r
@@ -432,6 +477,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 \r
       - *LT* (less than) – jump if value in R0 < threshold\r
 \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
 **Description**\r
    The instruction makes a jump to a relative address if condition is true. Condition is the result of comparison of R0 register value and the threshold value.\r
 \r
@@ -461,6 +509,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
        - *LT* (less than) –  jump if value in stage_cnt < threshold\r
        - *GT* (greater than) –  jump if value in stage_cnt > threshold\r
 \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
 **Description**\r
     The instruction makes a jump to a relative address if condition is true. Condition is the result of comparison of count register value and threshold value.\r
 \r
@@ -487,6 +538,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 **Description**\r
    The instruction sets the stage count register to 0\r
 \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
 **Examples**::\r
 \r
    1:       STAGE_RST      // Reset stage count register\r
@@ -502,6 +556,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 **Operands**\r
    - *Value* – 8 bits value\r
 \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
 **Description**\r
    The instruction increments stage count register by given value.\r
 \r
@@ -525,6 +582,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 **Operands**\r
    - *Value* – 8 bits value\r
 \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
 **Description**\r
    The instruction decrements stage count register by given value.\r
 \r
@@ -548,17 +608,21 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 \r
 **Operands**\r
   No operands\r
+\r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
 **Description**\r
-   The instruction halt the processor to the power down mode\r
+   The instruction halts the ULP coprocessor and restarts ULP wakeup timer, if it is enabled.\r
 \r
 **Examples**::\r
 \r
-  1:       HALT      // Move chip to powerdown\r
+  1:       HALT      // Halt the coprocessor\r
 \r
 \r
 \r
-**WAKE** – wakeup the chip\r
---------------------------\r
+**WAKE** – Wake up the chip\r
+---------------------------\r
 \r
 **Syntax**\r
    **WAKE**\r
@@ -566,6 +630,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 **Operands**\r
   No operands\r
 \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
 **Description**\r
   The instruction sends an interrupt from ULP to RTC controller.\r
 \r
@@ -598,6 +665,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 **Operands**\r
    - *sleep_reg* – 0..4, selects one of ``SENS_ULP_CP_SLEEP_CYCx_REG`` registers.\r
 \r
+**Cycles**\r
+  2 (fetch) + 2 (execute)\r
+\r
 **Description**\r
    The instruction selects which of the ``SENS_ULP_CP_SLEEP_CYCx_REG`` (x = 0..4) register values is to be used by the ULP wakeup timer as wakeup period. By default, the value from ``SENS_ULP_CP_SLEEP_CYC0_REG`` is used.\r
 \r
@@ -618,6 +688,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 **Operands**\r
    - *Cycles* – number of cycles for wait\r
 \r
+**Cycles**\r
+  2 (fetch) + *Cycles* (execute)\r
+\r
 **Description**\r
    The instruction delays for given number of cycles.\r
 \r
@@ -641,6 +714,8 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
   - *Rdst* – Destination Register R[0..3], result will be stored to this register\r
   - *Wait_Delay* – number of cycles used to perform the measurement\r
 \r
+**Cycles**\r
+  2 (fetch) + *Wait_Delay* + 3 * TSENS_CLK\r
 \r
 **Description**\r
    The instruction performs measurement using TSENS and stores the result into a general purpose register.\r
@@ -666,6 +741,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
   - *Sar_sel* – Select ADC: 0 = SARADC1, 1 = SARADC2\r
   - *Mux*  -  selected PAD, SARADC Pad[Mux+1] is enabled\r
 \r
+**Cycles**\r
+  2 (fetch) + 21 + max(1, SAR_AMP_WAIT1) + max(1, SAR_AMP_WAIT2) + max(1, SAR_AMP_WAIT3) + SARx_SAMPLE_CYCLE + SARx_SAMPLE_BIT\r
+\r
 **Description**\r
   The instruction makes measurements from ADC.\r
 \r
@@ -684,6 +762,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
   - *High*, *Low* — Define range of bits to read. Bits outside of [High, Low] range are masked.\r
   - *Slave_sel*  -  Index of I2C slave address to use.\r
 \r
+**Cycles**\r
+  2 (fetch) + I2C communication time\r
+\r
 **Description**\r
   ``I2C_RD`` instruction reads one byte from I2C slave with index ``Slave_sel``. Slave address (in 7-bit format) has to be set in advance into `SENS_I2C_SLAVE_ADDRx` register field, where ``x == Slave_sel``.\r
   8 bits of read result is stored into `R0` register.\r
@@ -705,6 +786,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
   - *High*, *Low* — Define range of bits to write. Bits outside of [High, Low] range are masked.\r
   - *Slave_sel*  -  Index of I2C slave address to use.\r
 \r
+**Cycles**\r
+  2 (fetch) + I2C communication time\r
+\r
 **Description**\r
   ``I2C_WR`` instruction writes one byte to I2C slave with index ``Slave_sel``. Slave address (in 7-bit format) has to be set in advance into `SENS_I2C_SLAVE_ADDRx` register field, where ``x == Slave_sel``.\r
 \r
@@ -724,6 +808,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
   - *High* – High part of R0\r
   - *Low* – Low part of R0\r
 \r
+**Cycles**\r
+  2 (fetch) + 6 (execute)\r
+\r
 **Description**\r
    The instruction reads up to 16 bits from a peripheral register into a general purpose register: ``R0 = REG[Addr][High:Low]``.\r
 \r
@@ -749,6 +836,9 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
   - *Low* – Low part of R0\r
   - *Data* – value to write, 8 bits\r
 \r
+**Cycles**\r
+  2 (fetch) + 10 (execute)\r
+\r
 **Description**\r
    The instruction writes up to 8 bits from a general purpose register into a peripheral register. ``REG[Addr][High:Low] = data``\r
 \r