From 0a8afd13a2fca7603c03dfd8a4a96d2432879ff0 Mon Sep 17 00:00:00 2001 From: Dmitry Yakovlev Date: Sat, 17 Oct 2020 02:44:47 +0800 Subject: [PATCH] Udate instruction set documentation for Esp32 and Esp32s2. Sleep instruction removed from S2 instruction set. LDx/STx instructions descritioin fix offset range to 13 bits (11 bits signed 32 bit words offset). Remove I2C RD/WR operations from S2. --- components/ulp/include/ulp_common.h | 7 +- docs/en/api-guides/ulp.rst | 41 ++++++++--- docs/en/api-guides/ulp_instruction_set.rst | 6 +- docs/en/api-guides/ulps2_instruction_set.rst | 74 +------------------- 4 files changed, 44 insertions(+), 84 deletions(-) diff --git a/components/ulp/include/ulp_common.h b/components/ulp/include/ulp_common.h index cc39bd482b..d149df610d 100644 --- a/components/ulp/include/ulp_common.h +++ b/components/ulp/include/ulp_common.h @@ -86,13 +86,16 @@ esp_err_t ulp_run(uint32_t entry_point); * * ULP coprocessor starts running the program when the wakeup timer counts up * to a given value (called period). There are 5 period values which can be - * programmed into SENS_ULP_CP_SLEEP_CYCx_REG registers, x = 0..4. - * By default, wakeup timer will use the period set into SENS_ULP_CP_SLEEP_CYC0_REG, + * programmed into SENS_ULP_CP_SLEEP_CYCx_REG registers, x = 0..4 for ESP32, and + * one period value which can be programmed into RTC_CNTL_ULP_CP_TIMER_1_REG register for ESP32-S2. + * By default, for ESP32, wakeup timer will use the period set into SENS_ULP_CP_SLEEP_CYC0_REG, * i.e. period number 0. ULP program code can use SLEEP instruction to select * which of the SENS_ULP_CP_SLEEP_CYCx_REG should be used for subsequent wakeups. * * However, please note that SLEEP instruction issued (from ULP program) while the system * is in deep sleep mode does not have effect, and sleep cycle count 0 is used. + * + * For ESP32-s2 the SLEEP instruction not exist. Instead a WAKE instruction will be used. * * @param period_index wakeup period setting number (0 - 4) * @param period_us wakeup period, us diff --git a/docs/en/api-guides/ulp.rst b/docs/en/api-guides/ulp.rst index 3e1242fe75..b4adb90df7 100644 --- a/docs/en/api-guides/ulp.rst +++ b/docs/en/api-guides/ulp.rst @@ -145,21 +145,46 @@ Declaration of the entry point symbol comes from the generated header file menti entry: /* code starts here */ +.. only:: esp32 -ULP Program Flow ----------------- + ESP32 ULP program flow + ----------------------- -The ULP coprocessor is started by a timer. The timer is started once ``ulp_run`` is called. The timer counts the number of RTC_SLOW_CLK ticks (by default, produced by an internal 150kHz RC oscillator). The number of ticks is set using ``SENS_ULP_CP_SLEEP_CYCx_REG`` registers (x = 0..4). When starting the ULP for the first time, ``SENS_ULP_CP_SLEEP_CYC0_REG`` will be used to set the number of timer ticks. Later the ULP program can select another ``SENS_ULP_CP_SLEEP_CYCx_REG`` register using the ``sleep`` instruction. + ESP32 ULP coprocessor is started by a timer. The timer is started once ``ulp_run`` is called. The timer counts a number of RTC_SLOW_CLK ticks + (by default, produced by an internal 150 kHz RC oscillator). The number of ticks is set using ``SENS_ULP_CP_SLEEP_CYCx_REG`` registers (x = 0..4). + When starting the ULP for the first time, ``SENS_ULP_CP_SLEEP_CYC0_REG`` will be used to set the number of timer ticks. + Later the ULP program can select another ``SENS_ULP_CP_SLEEP_CYCx_REG`` register using ``sleep`` instruction. -The application can set ULP timer period values (SENS_ULP_CP_SLEEP_CYCx_REG, x = 0..4) using the ``ulp_set_wakeup_period`` function. + The application can set ULP timer period values (SENS_ULP_CP_SLEEP_CYCx_REG, x = 0..4) using ``ulp_set_wakeup_period`` function. -.. doxygenfunction:: ulp_set_wakeup_period + .. doxygenfunction:: ulp_set_wakeup_period -Once the timer counts the number of ticks set in the selected ``SENS_ULP_CP_SLEEP_CYCx_REG`` register, the ULP coprocessor will power up and start running the program from the entry point set in the call to ``ulp_run``. + Once the timer counts the number of ticks set in the selected ``SENS_ULP_CP_SLEEP_CYCx_REG`` register, ULP coprocessor powers up and starts running the program from the entry point set in the call to ``ulp_run``. -The program runs until it encounters a ``halt`` instruction or an illegal instruction. Once the program halts, the ULP coprocessor will power down, and the timer will be started again. + The program runs until it encounters a ``halt`` instruction or an illegal instruction. Once the program halts, ULP coprocessor powers down, and the timer is started again. -To disable the timer (effectively preventing the ULP program from running again), please clear the ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` bit in the ``RTC_CNTL_STATE0_REG`` register. This can be done both from the ULP code and from the main program. + To disable the timer (effectively preventing the ULP program from running again), clear the ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` bit in the ``RTC_CNTL_STATE0_REG`` register. This can be done both from ULP code and from the main program. + + +.. only:: esp32s2 + + ESP32-S2 ULP program flow + ------------------------- + + ESP32-S2 ULP coprocessor is started by a timer. The timer is started once ``ulp_run`` is called. The timer counts a number of RTC_SLOW_CLK ticks + (by default, produced by an internal 90 kHz RC oscillator). The number of ticks is set using ``RTC_CNTL_ULP_CP_TIMER_1_REG`` register. + + The application can set ULP timer period values by ``ulp_set_wakeup_period`` function. + + .. doxygenfunction:: ulp_set_wakeup_period + + Once the timer counts the number of ticks set in the selected ``RTC_CNTL_ULP_CP_TIMER_1_REG`` register, ULP coprocessor powers up and starts running the program + from the entry point set in the call to ``ulp_run``. + + The program runs until it encounters a ``halt`` instruction or an illegal instruction. Once the program halts, ULP coprocessor powers down, and the timer is started again. + + To disable the timer (effectively preventing the ULP program from running again), clear the ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` bit in the ``RTC_CNTL_STATE0_REG`` register. + This can be done both from ULP code and from the main program. .. _binutils-esp32ulp toolchain: https://github.com/espressif/binutils-esp32ulp diff --git a/docs/en/api-guides/ulp_instruction_set.rst b/docs/en/api-guides/ulp_instruction_set.rst index 1dc3149ca4..1dfc47b638 100644 --- a/docs/en/api-guides/ulp_instruction_set.rst +++ b/docs/en/api-guides/ulp_instruction_set.rst @@ -358,7 +358,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Operands** - *Rsrc* – Register R[0..3], holds the 16-bit value to store - *Rdst* – Register R[0..3], address of the destination, in 32-bit words - - *Offset* – 10-bit signed value, offset in bytes + - *Offset* – 13-bit signed value, offset in bytes **Cycles** 4 cycles to execute, 4 cycles to fetch next instruction @@ -395,7 +395,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low *Rsrc* – Register R[0..3], holds address of destination, in 32-bit words - *Offset* – 10-bit signed value, offset in bytes + *Offset* – 13-bit signed value, offset in bytes **Cycles** 4 cycles to execute, 4 cycles to fetch next instruction @@ -786,7 +786,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Operands** - *Rdst* – Destination Register R[0..3], result will be stored to this register - *Sar_sel* – Select ADC: 0 = SARADC1, 1 = SARADC2 - - *Mux* - selected PAD, SARADC Pad[Mux+1] is enabled + - *Mux* - selected PAD, SARADC Pad[Mux-1] is enabled. If the user passes Mux value 1, then ADC pad 0 gets used. **Cycles** ``23 + max(1, SAR_AMP_WAIT1) + max(1, SAR_AMP_WAIT2) + max(1, SAR_AMP_WAIT3) + SARx_SAMPLE_CYCLE + SARx_SAMPLE_BIT`` cycles to execute, 4 cycles to fetch next instruction diff --git a/docs/en/api-guides/ulps2_instruction_set.rst b/docs/en/api-guides/ulps2_instruction_set.rst index 654c2dbda4..c5ae635a37 100644 --- a/docs/en/api-guides/ulps2_instruction_set.rst +++ b/docs/en/api-guides/ulps2_instruction_set.rst @@ -597,7 +597,7 @@ The detailed description of these commands please see below. *Rsrc* – Register R[0..3], holds address of destination, in 32-bit words - *Offset* – 10-bit signed value, offset in bytes + *Offset* – 13-bit signed value, offset in bytes **Cycles** 4 cycles to execute, 4 cycles to fetch next instruction @@ -634,7 +634,7 @@ The detailed description of these commands please see below. *Rsrc* – Register R[0..3], holds address of destination, in 32-bit words - *Offset* – 10-bit signed value, offset in bytes + *Offset* – 13-bit signed value, offset in bytes **Cycles** 4 cycles to execute, 4 cycles to fetch next instruction @@ -933,29 +933,6 @@ The detailed description of these commands please see below. -**SLEEP** – set ULP wakeup timer period ---------------------------------------- - -**Syntax** - **SLEEP** *sleep_reg* - -**Operands** - - *sleep_reg* – 0..4, selects one of ``SENS_ULP_CP_SLEEP_CYCx_REG`` registers. - -**Cycles** - 2 cycles to execute, 4 cycles to fetch next instruction - -**Description** - 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. - -**Examples**:: - - 1: SLEEP 1 // Use period set in SENS_ULP_CP_SLEEP_CYC1_REG - - 2: .set sleep_reg, 4 // Set constant - SLEEP sleep_reg // Use period set in SENS_ULP_CP_SLEEP_CYC4_REG - - **WAIT** – wait some number of cycles ------------------------------------- @@ -1012,7 +989,7 @@ The detailed description of these commands please see below. **Operands** - *Rdst* – Destination Register R[0..3], result will be stored to this register - *Sar_sel* – Select ADC: 0 = SARADC1, 1 = SARADC2 - - *Mux* - selected PAD, SARADC Pad[Mux+1] is enabled + - *Mux* - selected PAD, SARADC Pad[Mux-1] is enabled. If the user passes Mux value 1, then ADC pad 0 gets used. **Cycles** ``23 + max(1, SAR_AMP_WAIT1) + max(1, SAR_AMP_WAIT2) + max(1, SAR_AMP_WAIT3) + SARx_SAMPLE_CYCLE + SARx_SAMPLE_BIT`` cycles to execute, 4 cycles to fetch next instruction @@ -1024,51 +1001,6 @@ The detailed description of these commands please see below. 1: ADC R1, 0, 1 // Measure value using ADC1 pad 2 and store result into R1 -**I2C_RD** - read single byte from I2C slave --------------------------------------------- - -**Syntax** - - **I2C_RD** *Sub_addr, High, Low, Slave_sel* - -**Operands** - - *Sub_addr* – Address within the I2C slave to read. - - *High*, *Low* — Define range of bits to read. Bits outside of [High, Low] range are masked. - - *Slave_sel* - Index of I2C slave address to use. - -**Cycles** - Execution time mostly depends on I2C communication time. 4 cycles to fetch next instruction. - -**Description** - ``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``. - 8 bits of read result is stored into `R0` register. - -**Examples**:: - - 1: I2C_RD 0x10, 7, 0, 0 // Read byte from sub-address 0x10 of slave with address set in SENS_I2C_SLAVE_ADDR0 - - -**I2C_WR** - write single byte to I2C slave -------------------------------------------- - -**Syntax** - - **I2C_WR** *Sub_addr, Value, High, Low, Slave_sel* - -**Operands** - - *Sub_addr* – Address within the I2C slave to write. - - *Value* – 8-bit value to be written. - - *High*, *Low* — Define range of bits to write. Bits outside of [High, Low] range are masked. - - *Slave_sel* - Index of I2C slave address to use. - -**Cycles** - Execution time mostly depends on I2C communication time. 4 cycles to fetch next instruction. - -**Description** - ``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``. - -**Examples**:: - - 1: I2C_WR 0x20, 0x33, 7, 0, 1 // Write byte 0x33 to sub-address 0x20 of slave with address set in SENS_I2C_SLAVE_ADDR1. - **REG_RD** – read from peripheral register ------------------------------------------