mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-01 19:54:32 +02:00
Merge branch 'bugfix/ulp_doc_fixes' into 'master'
ULP: Update instruction set documentation for Esp32 and Esp32s2. See merge request espressif/esp-idf!8560
This commit is contained in:
@@ -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
|
* 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
|
* 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.
|
* programmed into SENS_ULP_CP_SLEEP_CYCx_REG registers, x = 0..4 for ESP32, and
|
||||||
* By default, wakeup timer will use the period set into SENS_ULP_CP_SLEEP_CYC0_REG,
|
* 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
|
* 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.
|
* 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
|
* 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.
|
* 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_index wakeup period setting number (0 - 4)
|
||||||
* @param period_us wakeup period, us
|
* @param period_us wakeup period, us
|
||||||
|
@@ -145,21 +145,46 @@ Declaration of the entry point symbol comes from the generated header file menti
|
|||||||
entry:
|
entry:
|
||||||
/* code starts here */
|
/* 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
|
.. _binutils-esp32ulp toolchain: https://github.com/espressif/binutils-esp32ulp
|
||||||
|
@@ -358,7 +358,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low
|
|||||||
**Operands**
|
**Operands**
|
||||||
- *Rsrc* – Register R[0..3], holds the 16-bit value to store
|
- *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
|
- *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**
|
**Cycles**
|
||||||
4 cycles to execute, 4 cycles to fetch next instruction
|
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
|
*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**
|
**Cycles**
|
||||||
4 cycles to execute, 4 cycles to fetch next instruction
|
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**
|
**Operands**
|
||||||
- *Rdst* – Destination Register R[0..3], result will be stored to this register
|
- *Rdst* – Destination Register R[0..3], result will be stored to this register
|
||||||
- *Sar_sel* – Select ADC: 0 = SARADC1, 1 = SARADC2
|
- *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**
|
**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
|
``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
|
||||||
|
@@ -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
|
*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**
|
**Cycles**
|
||||||
4 cycles to execute, 4 cycles to fetch next instruction
|
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
|
*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**
|
**Cycles**
|
||||||
4 cycles to execute, 4 cycles to fetch next instruction
|
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
|
**WAIT** – wait some number of cycles
|
||||||
-------------------------------------
|
-------------------------------------
|
||||||
|
|
||||||
@@ -1012,7 +989,7 @@ The detailed description of these commands please see below.
|
|||||||
**Operands**
|
**Operands**
|
||||||
- *Rdst* – Destination Register R[0..3], result will be stored to this register
|
- *Rdst* – Destination Register R[0..3], result will be stored to this register
|
||||||
- *Sar_sel* – Select ADC: 0 = SARADC1, 1 = SARADC2
|
- *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**
|
**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
|
``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
|
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
|
**REG_RD** – read from peripheral register
|
||||||
------------------------------------------
|
------------------------------------------
|
||||||
|
Reference in New Issue
Block a user