From 8fe3ecd0001ab190496092156a2f56ddb428d8b1 Mon Sep 17 00:00:00 2001 From: Dmitry Yakovlev Date: Fri, 13 Dec 2019 18:38:57 +0800 Subject: [PATCH] Added description for difference between ESP32 ULP and ESP32-S2 ULP Jumpr instruction updated. --- docs/en/api-guides/index.rst | 1 + docs/en/api-guides/ulp-cmake.rst | 164 +++ docs/en/api-guides/ulp.rst | 3 +- docs/en/api-guides/ulp_instruction_set.rst | 31 +- docs/en/api-guides/ulps2_instruction_set.rst | 1170 +++++++++++++++++ docs/sphinx-known-warnings.txt | 9 +- docs/zh_CN/api-guides/index.rst | 3 +- docs/zh_CN/api-guides/ulp-cmake.rst | 1 + .../api-guides/ulps2_instruction_set.rst | 1 + tools/test_idf_tools/test_idf_tools.py | 2 +- tools/tools.json | 62 +- 11 files changed, 1435 insertions(+), 12 deletions(-) create mode 100644 docs/en/api-guides/ulp-cmake.rst create mode 100644 docs/en/api-guides/ulps2_instruction_set.rst create mode 100644 docs/zh_CN/api-guides/ulp-cmake.rst create mode 100644 docs/zh_CN/api-guides/ulps2_instruction_set.rst diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index b8e6741d4..beb5e7526 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -32,6 +32,7 @@ API Guides Secure Boot <../security/secure-boot> Thread Local Storage Tools + ULP Coprocessor (CMake) ULP Coprocessor (Legacy GNU Make) ULP Coprocessor Unit Testing (Legacy GNU Make) diff --git a/docs/en/api-guides/ulp-cmake.rst b/docs/en/api-guides/ulp-cmake.rst new file mode 100644 index 000000000..d84a69031 --- /dev/null +++ b/docs/en/api-guides/ulp-cmake.rst @@ -0,0 +1,164 @@ +ULP coprocessor programming (CMake) +=================================== + +:link_to_translation:`zh_CN:[中文]` + +.. toctree:: + :maxdepth: 1 + + Instruction set reference for ESP32 ULP + Instruction set reference for ESP32-S2 ULP + Programming using macros (legacy) + + +The ULP (Ultra Low Power) coprocessor is a simple FSM (Finite State Machine) which is designed to perform measurements using the ADC, temperature sensor, and external I2C sensors, while the main processors are in deep sleep mode. The ULP coprocessor can access the RTC_SLOW_MEM memory region, and registers in RTC_CNTL, RTC_IO, and SARADC peripherals. The ULP coprocessor uses fixed-width 32-bit instructions, 32-bit memory addressing, and has 4 general-purpose 16-bit registers. + +Installing the toolchain +------------------------ + +ULP coprocessor code is written in assembly and compiled using the `binutils-esp32ulp toolchain`_. + +1. Download pre-built binaries of the latest toolchain release from: +https://github.com/espressif/binutils-esp32ulp/releases. + +2. Extract the toolchain into a directory, and add the path to the ``bin/`` directory of the toolchain to the ``PATH`` environment variable. + +Compiling ULP code +------------------ + +To compile ULP code as part of a component, the following steps must be taken: + +1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`. + +.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``COMPONENT_SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files. + +2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example:: + + ... + register_component() + + set(ulp_app_name ulp_${COMPONENT_NAME}) + set(ulp_s_sources ulp/ulp_assembly_source_file.S) + set(ulp_exp_dep_srcs "ulp_c_source_file.c") + + ulp_embed_binary(${ulp_app_name} ${ulp_s_sources} ${ulp_exp_dep_srcs}) + + The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used other generated artifacts + such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files. + Finally, the third argument specifies the list of component source files which include the header file to be generated. + This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. + See section below explaining the concept of generated header files for ULP applications. + +3. Build the application as usual (e.g. `idf.py app`) + + Inside, the build system will take the following steps to build ULP program: + + 1. **Run each assembly file (foo.S) through the C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.S) in the component build directory. This step also generates dependency files (foo.ulp.d). + + 2. **Run preprocessed assembly sources through the assembler.** This produces object (foo.ulp.o) and listing (foo.ulp.lst) files. Listing files are generated for debugging purposes and are not used at later stages of the build process. + + 3. **Run the linker script template through the C preprocessor.** The template is located in ``components/ulp/ld`` directory. + + 4. **Link the object files into an output ELF file** (``ulp_app_name.elf``). The Map file (``ulp_app_name.map``) generated at this stage may be useful for debugging purposes. + + 5. **Dump the contents of the ELF file into a binary** (``ulp_app_name.bin``) which can then be embedded into the application. + + 6. **Generate a list of global symbols** (``ulp_app_name.sym``) in the ELF file using ``esp32ulp-elf-nm``. + + 7. **Create an LD export script and header file** (``ulp_app_name.ld`` and ``ulp_app_name.h``) containing the symbols from ``ulp_app_name.sym``. This is done using the ``esp32ulp_mapgen.py`` utility. + + 8. **Add the generated binary to the list of binary files** to be embedded into the application. + +Accessing the ULP Program Variables +------------------------------------- + +Global symbols defined in the ULP program may be used inside the main program. + +For example, the ULP program may define a variable ``measurement_count`` which will define the number of ADC measurements the program needs to make before waking up the chip from deep sleep:: + + .global measurement_count + measurement_count: .long 0 + + /* later, use measurement_count */ + move r3, measurement_count + ld r3, r3, 0 + +The main program needs to initialize this variable before the ULP program is started. The build system makes this possible by generating the ``${ULP_APP_NAME}.h`` and ``${ULP_APP_NAME}.ld`` files which define the global symbols present in the ULP program. Each global symbol defined in the ULP program is included in these files and are prefixed with ``ulp_``. + +The header file contains the declaration of the symbol:: + + extern uint32_t ulp_measurement_count; + +Note that all symbols (variables, arrays, functions) are declared as ``uint32_t``. For functions and arrays, take the address of the symbol and cast it to the appropriate type. + +The generated linker script file defines the locations of symbols in RTC_SLOW_MEM:: + + PROVIDE ( ulp_measurement_count = 0x50000060 ); + +To access the ULP program variables from the main program, the generated header file should be included using an ``include`` statement. This will allow the ULP program variables to be accessed as regular variables:: + + #include "ulp_app_name.h" + + // later + void init_ulp_vars() { + ulp_measurement_count = 64; + } + +Note that the ULP program can only use lower 16 bits of each 32-bit word in RTC memory, because the registers are 16-bit, and there is no instruction to load from the high part of the word. + +Likewise, the ULP store instruction writes register value into the lower 16 bits part of the 32-bit word. The upper 16 bits are written with a value which depends on the address of the store instruction, thus when reading variables written by the ULP, the main application needs to mask the upper 16 bits, e.g.:: + + printf("Last measurement value: %d\n", ulp_last_measurement & UINT16_MAX); + +Starting the ULP Program +------------------------ + +To run a ULP program, the main application needs to load the ULP program into RTC memory using the ``ulp_load_binary`` function, and then start it using the ``ulp_run`` function. + +Note that "Enable Ultra Low Power (ULP) Coprocessor" option must be enabled in menuconfig to reserve memory for the ULP. "RTC slow memory reserved for coprocessor" option must be set to a value sufficient to store ULP code and data. If the application components contain multiple ULP programs, then the size of the RTC memory must be sufficient to hold the largest one. + +Each ULP program is embedded into the ESP-IDF application as a binary blob. The application can reference this blob and load it in the following way (suppose ULP_APP_NAME was defined to ``ulp_app_name``):: + + extern const uint8_t bin_start[] asm("_binary_ulp_app_name_bin_start"); + extern const uint8_t bin_end[] asm("_binary_ulp_app_name_bin_end"); + + void start_ulp_program() { + ESP_ERROR_CHECK( ulp_load_binary( + 0 /* load address, set to 0 when using default linker scripts */, + bin_start, + (bin_end - bin_start) / sizeof(uint32_t)) ); + } + +.. doxygenfunction:: ulp_load_binary + +Once the program is loaded into RTC memory, the application can start it, passing the address of the entry point to the ``ulp_run`` function:: + + ESP_ERROR_CHECK( ulp_run(&ulp_entry - RTC_SLOW_MEM) ); + +.. doxygenfunction:: ulp_run + +Declaration of the entry point symbol comes from the generated header file mentioned above, ``${ULP_APP_NAME}.h``. In the assembly source of the ULP application, this symbol must be marked as ``.global``:: + + + .global entry + entry: + /* code starts here */ + + +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. + +The application can set ULP timer period values (SENS_ULP_CP_SLEEP_CYCx_REG, x = 0..4) using the ``ulp_set_wakeup_period`` function. + +.. 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``. + +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. + +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. + + +.. _binutils-esp32ulp toolchain: https://github.com/espressif/binutils-esp32ulp diff --git a/docs/en/api-guides/ulp.rst b/docs/en/api-guides/ulp.rst index 499f8052d..ad2509e0c 100644 --- a/docs/en/api-guides/ulp.rst +++ b/docs/en/api-guides/ulp.rst @@ -6,7 +6,8 @@ ULP Coprocessor programming .. toctree:: :maxdepth: 1 - Instruction set reference + Instruction set reference for ESP32 ULP + Instruction set reference for ESP32-S2 ULP Programming using macros (legacy) diff --git a/docs/en/api-guides/ulp_instruction_set.rst b/docs/en/api-guides/ulp_instruction_set.rst index 2a6e6d707..6eec2f4b5 100644 --- a/docs/en/api-guides/ulp_instruction_set.rst +++ b/docs/en/api-guides/ulp_instruction_set.rst @@ -1,5 +1,5 @@ -ULP coprocessor instruction set -=============================== +ESP32 ULP coprocessor instruction set +===================================== This document provides details about the instructions used by ESP32 ULP coprocessor assembler. @@ -478,12 +478,35 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low - *Step* – relative shift from current position, in bytes - *Threshold* – threshold value for branch condition - *Condition*: + - *EQ* (equal) – jump if value in R0 == threshold + - *LT* (less than) – jump if value in R0 < threshold + - *LE* (less or equal) – jump if value in R0 <= threshold + - *GT* (greater than) – jump if value in R0 > threshold - *GE* (greater or equal) – jump if value in R0 >= threshold - - *LT* (less than) – jump if value in R0 < threshold **Cycles** - 2 cycles to execute, 2 cycles to fetch next instruction + Conditions *LT*, *GE*, *LE* and *GT*: 2 cycles to execute, 2 cycles to fetch next instruction + + Conditions *LE* and *GT* are implemented in the assembler using one **JUMPR** instructions:: + + // JUMPR target, threshold, GT is implemented as: + + JUMPR target, threshold+1, GE + + // JUMPR target, threshold, LE is implemented as: + + JUMPR target, threshold + 1, LT + + Conditions *EQ* is implemented in the assembler using two **JUMPR** instructions:: + + // JUMPR target, threshold, EQ is implemented as: + + JUMPR next, threshold + 1, GE + JUMPR target, threshold, GE + next: + + Therefore the execution time will depend on the branches taken: either 2 cycles to execute + 2 cycles to fetch, or 4 cycles to execute + 4 cycles to fetch. **Description** 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. diff --git a/docs/en/api-guides/ulps2_instruction_set.rst b/docs/en/api-guides/ulps2_instruction_set.rst new file mode 100644 index 000000000..061b41fca --- /dev/null +++ b/docs/en/api-guides/ulps2_instruction_set.rst @@ -0,0 +1,1170 @@ +ESP32-S2 ULP coprocessor instruction set +======================================== + +This document provides details about the instructions used by ESP32-S2 ULP coprocessor assembler. + +ULP coprocessor has 4 16-bit general purpose registers, labeled R0, R1, R2, R3. It also has an 8-bit counter register (stage_cnt) which can be used to implement loops. Stage count regiter is accessed using special instructions. + +ULP coprocessor can access 8k bytes of RTC_SLOW_MEM memory region. Memory is addressed in 32-bit word units. It can also access peripheral registers in RTC_CNTL, RTC_IO, and SENS peripherals. + +All instructions are 32-bit. Jump instructions, ALU instructions, peripheral register and memory access instructions are executed in 1 cycle. Instructions which work with peripherals (TSENS, ADC, I2C) take variable number of cycles, depending on peripheral operation. + +The instruction syntax is case insensitive. Upper and lower case letters can be used and intermixed arbitrarily. This is true both for register names and instruction names. + + +Note about addressing +--------------------- +ESP32-S2 ULP coprocessor's JUMP, ST, LD instructions which take register as an argument (jump address, store/load base address) expect the argument to be expressed in 32-bit words. + +Consider the following example program:: + + entry: + NOP + NOP + NOP + NOP + loop: + MOVE R1, loop + JUMP R1 + +When this program is assembled and linked, address of label ``loop`` will be equal to 16 (expressed in bytes). However `JUMP` instruction expects the address stored in register to be expressed in 32-bit words. To account for this common use case, assembler will convert the address of label `loop` from bytes to words, when generating ``MOVE`` instruction, so the code generated code will be equivalent to:: + + 0000 NOP + 0004 NOP + 0008 NOP + 000c NOP + 0010 MOVE R1, 4 + 0014 JUMP R1 + +The other case is when the argument of ``MOVE`` instruction is not a label but a constant. In this case assembler will use the value as is, without any conversion:: + + .set val, 0x10 + MOVE R1, val + +In this case, value loaded into R1 will be ``0x10``. + +Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the following code:: + + .global array + array: .long 0 + .long 0 + .long 0 + .long 0 + + MOVE R1, array + MOVE R2, 0x1234 + ST R2, R1, 0 // write value of R2 into the first array element, + // i.e. array[0] + + ST R2, R1, 4 // write value of R2 into the second array element + // (4 byte offset), i.e. array[1] + + ADD R1, R1, 2 // this increments address by 2 words (8 bytes) + ST R2, R1, 0 // write value of R2 into the third array element, + // i.e. array[2] + + +Note about instruction execution time +------------------------------------- + +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:: + + #include "soc/rtc.h" + + // 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; + +ULP coprocessor needs certain number of clock cycles to fetch each instruction, plus certain number of cycles to execute it, depending on the instruction. See description of each instruction below for details on the execution time. + +Instruction fetch time is: + +- 2 clock cycles — for instructions following ALU and branch instructions. +- 4 clock cycles — in other cases. + +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. + + +Difference between ESP32 ULP and ESP32-S2 ULP Instruction sets +-------------------------------------------------------------- + +Compare to the ESP32 ULP coprocessor, the ESP-S2 ULP coprocessor has extended instruction set. The ESP32-S2 ULP is not binary compatible with ESP32 ULP, +but the assembled program that was written for the ESP32 ULP will also work on the ESP32-S2 ULP after rebuild. +The list of the new instructions that was added to the ESP32-S2 ULP is: LDL, LDH, STO, ST32, STI32. +The detailed description of these commands please see below. + + +**NOP** - no operation +---------------------- + +**Syntax** + **NOP** +**Operands** + None +**Cycles** + 2 cycle to execute, 4 cycles to fetch next instruction +**Description** + No operation is performed. Only the PC is incremented. + +**Example**:: + + 1: NOP + + +**ADD** - Add to register +------------------------- + +**Syntax** + **ADD** *Rdst, Rsrc1, Rsrc2* + + **ADD** *Rdst, Rsrc1, imm* + + +**Operands** + - *Rdst* - Register R[0..3] + - *Rsrc1* - Register R[0..3] + - *Rsrc2* - Register R[0..3] + - *Imm* - 16-bit signed value + +**Cycles** + 2 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction adds source register to another source register or to a 16-bit signed value and stores result to the destination register. + +**Examples**:: + + 1: ADD R1, R2, R3 //R1 = R2 + R3 + + 2: Add R1, R2, 0x1234 //R1 = R2 + 0x1234 + + 3: .set value1, 0x03 //constant value1=0x03 + Add R1, R2, value1 //R1 = R2 + value1 + + + 4: .global label //declaration of variable label + Add R1, R2, label //R1 = R2 + label + ... + label: nop //definition of variable label + + +**SUB** - Subtract from register +-------------------------------- + +**Syntax** + **SUB** *Rdst, Rsrc1, Rsrc2* + + **SUB** *Rdst, Rsrc1, imm* + +**Operands** + - *Rdst* - Register R[0..3] + - *Rsrc1* - Register R[0..3] + - *Rsrc2* - Register R[0..3] + - *Imm* - 16-bit signed value + +**Cycles** + 2 cycles to execute, 4 cycles to fetch next instruction + +**Description** + 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. + +**Examples**:: + + 1: SUB R1, R2, R3 //R1 = R2 - R3 + + 2: sub R1, R2, 0x1234 //R1 = R2 - 0x1234 + + 3: .set value1, 0x03 //constant value1=0x03 + SUB R1, R2, value1 //R1 = R2 - value1 + 4: .global label //declaration of variable label + SUB R1, R2, label //R1 = R2 - label + .... + label: nop //definition of variable label + + +**AND** - Logical AND of two operands +------------------------------------- + +**Syntax** + **AND** *Rdst, Rsrc1, Rsrc2* + + **AND** *Rdst, Rsrc1, imm* + +**Operands** + - *Rdst* - Register R[0..3] + - *Rsrc1* - Register R[0..3] + - *Rsrc2* - Register R[0..3] + - *Imm* - 16-bit signed value + +**Cycles** + 2 cycles to execute, 4 cycles to fetch next instruction + +**Description** + 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. + +**Examples**:: + + 1: AND R1, R2, R3 //R1 = R2 & R3 + + 2: AND R1, R2, 0x1234 //R1 = R2 & 0x1234 + + 3: .set value1, 0x03 //constant value1=0x03 + AND R1, R2, value1 //R1 = R2 & value1 + + 4: .global label //declaration of variable label + AND R1, R2, label //R1 = R2 & label + ... + label: nop //definition of variable label + + +**OR** - Logical OR of two operands +----------------------------------- + +**Syntax** + **OR** *Rdst, Rsrc1, Rsrc2* + + **OR** *Rdst, Rsrc1, imm* + +**Operands** + - *Rdst* - Register R[0..3] + - *Rsrc1* - Register R[0..3] + - *Rsrc2* - Register R[0..3] + - *Imm* - 16-bit signed value + +**Cycles** + 2 cycles to execute, 4 cycles to fetch next instruction + +**Description** + 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. + +**Examples**:: + + 1: OR R1, R2, R3 //R1 = R2 \| R3 + + 2: OR R1, R2, 0x1234 //R1 = R2 \| 0x1234 + + 3: .set value1, 0x03 //constant value1=0x03 + OR R1, R2, value1 //R1 = R2 \| value1 + + 4: .global label //declaration of variable label + OR R1, R2, label //R1 = R2 \|label + ... + label: nop //definition of variable label + + +**LSH** - Logical Shift Left +---------------------------- + +**Syntax** + **LSH** *Rdst, Rsrc1, Rsrc2* + + **LSH** *Rdst, Rsrc1, imm* + +**Operands** + - *Rdst* - Register R[0..3] + - *Rsrc1* - Register R[0..3] + - *Rsrc2* - Register R[0..3] + - *Imm* - 16-bit signed value + +**Cycles** + 2 cycles to execute, 4 cycles to fetch next instruction + +**Description** + 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. + +**Examples**:: + + 1: LSH R1, R2, R3 //R1 = R2 << R3 + + 2: LSH R1, R2, 0x03 //R1 = R2 << 0x03 + + 3: .set value1, 0x03 //constant value1=0x03 + LSH R1, R2, value1 //R1 = R2 << value1 + + 4: .global label //declaration of variable label + LSH R1, R2, label //R1 = R2 << label + ... + label: nop //definition of variable label + + +**RSH** - Logical Shift Right +----------------------------- + +**Syntax** + **RSH** *Rdst, Rsrc1, Rsrc2* + + **RSH** *Rdst, Rsrc1, imm* + +**Operands** + *Rdst* - Register R[0..3] + *Rsrc1* - Register R[0..3] + *Rsrc2* - Register R[0..3] + *Imm* - 16-bit signed value + +**Cycles** + 2 cycles to execute, 4 cycles to fetch next instruction + +**Description** + 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. + +**Examples**:: + + 1: RSH R1, R2, R3 //R1 = R2 >> R3 + + 2: RSH R1, R2, 0x03 //R1 = R2 >> 0x03 + + 3: .set value1, 0x03 //constant value1=0x03 + RSH R1, R2, value1 //R1 = R2 >> value1 + + 4: .global label //declaration of variable label + RSH R1, R2, label //R1 = R2 >> label + label: nop //definition of variable label + + +**MOVE** – Move to register +--------------------------- + +**Syntax** + **MOVE** *Rdst, Rsrc* + + **MOVE** *Rdst, imm* + +**Operands** + - *Rdst* – Register R[0..3] + - *Rsrc* – Register R[0..3] + - *Imm* – 16-bit signed value + +**Cycles** + 2 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction move to destination register value from source register or 16-bit signed value. + + Note that when a label is used as an immediate, the address of the label will be converted from bytes to words. This is because LD, ST, and JUMP instructions expect the address register value to be expressed in words rather than bytes. To avoid using an extra instruction + + +**Examples**:: + + 1: MOVE R1, R2 //R1 = R2 + + 2: MOVE R1, 0x03 //R1 = 0x03 + + 3: .set value1, 0x03 //constant value1=0x03 + MOVE R1, value1 //R1 = value1 + + 4: .global label //declaration of label + MOVE R1, label //R1 = address_of(label) / 4 + ... + label: nop //definition of label + + +**STL**/**ST** – Store data to the low 16 bits of 32-bits memory +---------------------------------------------------------------- + +**Syntax** + **ST** *Rsrc, Rdst, offset, Label* + **STL** *Rsrc, Rdst, offset, Label* + +**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* – 11-bit signed value, offset in bytes + - *Label* – 2-bit user defined unsigned value + +**Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction stores the 16-bit value of Rsrc to the lower half-word of memory with address Rdst+offset:: + + Mem[Rdst + offset / 4]{15:0} = {Rsrc[15:0]} + Mem[Rdst + offset / 4]{15:0} = {Label[1:0],Rsrc[13:0]} + + The ST command introduced to make compatibility with previous versions of UPL core. + The application can use higher 16 bits to determine which instruction in the ULP program has written any particular word into memory. + +**Examples**:: + + 1: STL R1, R2, 0x12 //MEM[R2+0x12] = R1 + + 2: .data //Data section definition + Addr1: .word 123 // Define label Addr1 16 bit + .set offs, 0x00 // Define constant offs + .text //Text section definition + MOVE R1, 1 // R1 = 1 + MOVE R2, Addr1 // R2 = Addr1 + STL R1, R2, offs // MEM[R2 + 0] = R1 + // MEM[Addr1 + 0] will be 32'hxxxx0001 + 3: + MOVE R1, 1 // R1 = 1 + STL R1, R2, 0x12,1 // MEM[R2+0x12] 0xxxxx4001 + + +**STH** – Store data to the high 16 bits of 32-bits memory +---------------------------------------------------------- + +**Syntax** + **STH** *Rsrc, Rdst, offset, Label* + +**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* – 11-bit signed value, offset in bytes + - *Label* – 2-bit user defined unsigned value + +**Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction stores the 16-bit value of Rsrc to the high half-word of memory with address Rdst+offset:: + + Mem[Rdst + offset / 4]{31:16} = {Rsrc[15:0]} + Mem[Rdst + offset / 4]{31:16} = {Label[1:0],Rsrc[13:0]} + +**Examples**:: + + 1: STH R1, R2, 0x12 //MEM[R2+0x12][31:16] = R1 + + 2: .data //Data section definition + Addr1: .word 123 // Define label Addr1 16 bit + .set offs, 0x00 // Define constant offs + .text //Text section definition + MOVE R1, 1 // R1 = 1 + MOVE R2, Addr1 // R2 = Addr1 + STH R1, R2, offs // MEM[R2 + 0] = R1 + // MEM[Addr1 + 0] will be 32'h0001xxxx + 3: + MOVE R1, 1 // R1 = 1 + STH R1, R2, 0x12, 1 //MEM[R2+0x12] 0x4001xxxx + + +**STO** – Set offset value for auto increment operation +------------------------------------------------------- + +**Syntax** + **STO** *offset* + +**Operands** + - *Offset* – 11-bit signed value, offset in bytes + +**Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction set 16-bit value to the offset register:: + + offset = value/ 4 + +**Examples**:: + + 1: STO 0x12 // Offset = 0x12/4 + + 2: .data //Data section definition + Addr1: .word 123 // Define label Addr1 16 bit + .set offs, 0x00 // Define constant offs + .text //Text section definition + STO offs // Offset = 0x00 + + +**STI** – Store data to the 32-bits memory with auto increment of predefined offset address +------------------------------------------------------------------------------------------- + +**Syntax** + **STI** *Rsrc, Rdst, Label* + +**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 + - *Label* – 2-bit user defined unsigned value + +**Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction stores the 16-bit value of Rsrc to the low and high half-word of memory with address Rdst+offset with + auto increment of offset:: + + Mem[Rdst + offset / 4]{15:0/31:16} = {Rsrc[15:0]} + Mem[Rdst + offset / 4]{15:0/31:16} = {Label[1:0],Rsrc[13:0]} + +**Examples**:: + + 1: STO 0 // Set offset to 0 + STI R1, R2, 0x12 //MEM[R2+0x12][15:0] = R1 + STI R1, R2, 0x12 //MEM[R2+0x12][31:16] = R1 + + 2: .data //Data section definition + Addr1: .word 123 // Define label Addr1 16 bit + .set offs, 0x00 // Define constant offs + .text //Text section definition + STO 0 // Set offset to 0 + MOVE R1, 1 // R1 = 1 + MOVE R2, Addr1 // R2 = Addr1 + STI R1, R2 // MEM[R2 + 0] = R1 + // MEM[Addr1 + 0] will be 32'hxxxx0001 + STIx R1, R2 // MEM[R2 + 0] = R1 + // MEM[Addr1 + 0] will be 32'h00010001 + 3: + STO 0 // Set offset to 0 + MOVE R1, 1 // R1 = 1 + STI R1, R2, 1 //MEM[R2+0x12] 0xxxxx4001 + STI R1, R2, 1 //MEM[R2+0x12] 0x40014001 + + +**ST32** – Store 32-bits data to the 32-bits memory +--------------------------------------------------- + +**Syntax** + **ST32** *Rsrc, Rdst, offset, Label* + +**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* – 11-bit signed value, offset in bytes + - *Label* – 2-bit user defined unsigned value + +**Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction stores 11 bits of the PC value, label value and the 16-bit value of Rsrc to the 32-bits memory with address Rdst+offset:: + + Mem[Rdst + offset / 4]{31:0} = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + +**Examples**:: + + 1: ST32 R1, R2, 0x12, 0 //MEM[R2+0x12][31:0] = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + + 2: .data //Data section definition + Addr1: .word 123 // Define label Addr1 16 bit + .set offs, 0x00 // Define constant offs + .text //Text section definition + MOVE R1, 1 // R1 = 1 + MOVE R2, Addr1 // R2 = Addr1 + ST32 R1, R2, offs,1// MEM[R2 + 0] = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + // MEM[Addr1 + 0] will be 32'h00010001 + + +**STI32** – Store 32-bits data to the 32-bits memory with auto increment of adress offset +----------------------------------------------------------------------------------------- + +**Syntax** + **STI32** *Rsrc, Rdst, Label* + +**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 + - *Label* – 2-bit user defined unsigned value + +**Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction stores 11 bits of the PC value, label value and the 16-bit value of Rsrc to the 32-bits memory with address Rdst+offset:: + + Mem[Rdst + offset / 4]{31:0} = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + + Where offset value set by STO instruction + +**Examples**:: + + 1: STO 0x12 + STI32 R1, R2, 0 //MEM[R2+0x12][31:0] = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + STI32 R1, R2, 0 //MEM[R2+0x13][31:0] = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + + 2: .data //Data section definition + Addr1: .word 123 // Define label Addr1 16 bit + .set offs, 0x00 // Define constant offs + .text //Text section definition + MOVE R1, 1 // R1 = 1 + MOVE R2, Addr1 // R2 = Addr1 + STO offs + STI32 R1, R2, 1// MEM[R2 + 0] = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + // MEM[Addr1 + 0] will be 32'h00010001 + ST32 R1, R2, 1// MEM[R2 + 1] = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + // MEM[Addr1 + 1] will be 32'h00010001 + + +**LDL**/**LD** – Load data from low part of the 32-bits memory +-------------------------------------------------------------- + +**Syntax** + **LD** *Rdst, Rsrc, offset* + **LDL** *Rdst, Rsrc, offset* + +**Operands** + *Rdst* – Register R[0..3], destination + + *Rsrc* – Register R[0..3], holds address of destination, in 32-bit words + + *Offset* – 10-bit signed value, offset in bytes + +**Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction loads lower 16-bit half-word from memory with address Rsrc+offset into the destination register Rdst:: + + Rdst[15:0] = Mem[Rsrc + offset / 4][15:0] + + The LD command do the same as LDL, and included for compatibility with previous versions of ULP core. + +**Examples**:: + + 1: LDL R1, R2, 0x12 //R1 = MEM[R2+0x12] + + 2: .data //Data section definition + Addr1: .word 123 // Define label Addr1 16 bit + .set offs, 0x00 // Define constant offs + .text //Text section definition + MOVE R1, 1 // R1 = 1 + MOVE R2, Addr1 // R2 = Addr1 / 4 (address of label is converted into words) + LDL R1, R2, offs // R1 = MEM[R2 + 0] + // R1 will be 123 + + +**LDH** – Load data from high part of the 32-bits memory +-------------------------------------------------------- + +**Syntax** + **LDH** *Rdst, Rsrc, offset* + +**Operands** + *Rdst* – Register R[0..3], destination + + *Rsrc* – Register R[0..3], holds address of destination, in 32-bit words + + *Offset* – 10-bit signed value, offset in bytes + +**Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction loads higher 16-bit half-word from memory with address Rsrc+offset into the destination register Rdst:: + + Rdst[15:0] = Mem[Rsrc + offset / 4][15:0] + + The LD command do the same as LDL, and included for compatibility with previous versions of ULP core. + +**Examples**:: + + 1: LDH R1, R2, 0x12 //R1 = MEM[R2+0x12] + + 2: .data //Data section definition + Addr1: .word 0x12345678 // Define label Addr1 16 bit + .set offs, 0x00 // Define constant offs + .text //Text section definition + MOVE R1, 1 // R1 = 1 + MOVE R2, Addr1 // R2 = Addr1 / 4 (address of label is converted into words) + LDH R1, R2, offs // R1 = MEM[R2 + 0] + // R1 will be 0x1234 + + +**JUMP** – Jump to an absolute address +-------------------------------------- + +**Syntax** + **JUMP** *Rdst* + + **JUMP** *ImmAddr* + + **JUMP** *Rdst, Condition* + + **JUMP** *ImmAddr, Condition* + + +**Operands** + - *Rdst* – Register R[0..3] containing address to jump to (expressed in 32-bit words) + + - *ImmAddr* – 13 bits address (expressed in bytes), aligned to 4 bytes + + - *Condition*: + - EQ – jump if last ALU operation result was zero + - OV – jump if last ALU has set overflow flag + +**Cycles** + 2 cycles to execute, 2 cycles to fetch next instruction + +**Description** + The instruction makes jump to the specified address. Jump can be either unconditional or based on an ALU flag. + +**Examples**:: + + 1: JUMP R1 // Jump to address in R1 (address in R1 is in 32-bit words) + + 2: JUMP 0x120, EQ // Jump to address 0x120 (in bytes) if ALU result is zero + + 3: JUMP label // Jump to label + ... + label: nop // Definition of label + + 4: .global label // Declaration of global label + + MOVE R1, label // R1 = label (value loaded into R1 is in words) + JUMP R1 // Jump to label + ... + label: nop // Definition of label + + + +**JUMPR** – Jump to a relative offset (condition based on R0) +------------------------------------------------------------- + +**Syntax** + **JUMPR** *Step, Threshold, Condition* + +**Operands** + - *Step* – relative shift from current position, in bytes + - *Threshold* – threshold value for branch condition + - *Condition*: + - *EQ* (equal) – jump if value in R0 == threshold + - *LT* (less than) – jump if value in R0 < threshold + - *LE* (less or equal) – jump if value in R0 <= threshold + - *GT* (greater than) – jump if value in R0 > threshold + - *GE* (greater or equal) – jump if value in R0 >= threshold + +**Cycles** + Conditions *EQ*, *GT* and *LT*: 2 cycles to execute, 2 cycles to fetch next instruction + + Conditions *LE* and *GE* are implemented in the assembler using two **JUMPR** instructions:: + + // JUMPR target, threshold, LE is implemented as: + + JUMPR target, threshold, EQ + JUMPR target, threshold, LT + + // JUMPR target, threshold, GE is implemented as: + + JUMPR target, threshold, EQ + JUMPR target, threshold, GT + + Therefore the execution time will depend on the branches taken: either 2 cycles to execute + 2 cycles to fetch, or 4 cycles to execute + 4 cycles to fetch. + +**Description** + 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. + +**Examples**:: + + 1:pos: JUMPR 16, 20, GE // Jump to address (position + 16 bytes) if value in R0 >= 20 + + 2: // Down counting loop using R0 register + MOVE R0, 16 // load 16 into R0 + label: SUB R0, R0, 1 // R0-- + NOP // do something + JUMPR label, 1, GE // jump to label if R0 >= 1 + + + +**JUMPS** – Jump to a relative address (condition based on stage count) +----------------------------------------------------------------------- + +**Syntax** + **JUMPS** *Step, Threshold, Condition* + +**Operands** + - *Step* – relative shift from current position, in bytes + - *Threshold* – threshold value for branch condition + - *Condition*: + - *EQ* (equal) – jump if value in stage_cnt == threshold + - *LT* (less than) – jump if value in stage_cnt < threshold + - *LE* (less or equal) - jump if value in stage_cnt <= threshold + - *GT* (greater than) – jump if value in stage_cnt > threshold + - *GE* (greater or equal) — jump if value in stage_cnt >= threshold + +**Cycles** + 2 cycles to execute, 2 cycles to fetch next instruction:: + + // JUMPS target, threshold, EQ is implemented as: + + JUMPS next, threshold, LT + JUMPS target, threshold, LE + next: + + // JUMPS target, threshold, GT is implemented as: + + JUMPS next, threshold, LE + JUMPS target, threshold, GE + next: + + Therefore the execution time will depend on the branches taken: either 2 cycles to execute + 2 cycles to fetch, or 4 cycles to execute + 4 cycles to fetch. + + +**Description** + 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. + +**Examples**:: + + 1:pos: JUMPS 16, 20, EQ // Jump to (position + 16 bytes) if stage_cnt == 20 + + 2: // Up counting loop using stage count register + STAGE_RST // set stage_cnt to 0 + label: STAGE_INC 1 // stage_cnt++ + NOP // do something + JUMPS label, 16, LT // jump to label if stage_cnt < 16 + + + +**STAGE_RST** – Reset stage count register +------------------------------------------ +**Syntax** + **STAGE_RST** + +**Operands** + No operands + +**Description** + The instruction sets the stage count register to 0 + +**Cycles** + 2 cycles to execute, 4 cycles to fetch next instruction + +**Examples**:: + + 1: STAGE_RST // Reset stage count register + + + +**STAGE_INC** – Increment stage count register +---------------------------------------------- + +**Syntax** + **STAGE_INC** *Value* + +**Operands** + - *Value* – 8 bits value + +**Cycles** + 2 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction increments stage count register by given value. + +**Examples**:: + + 1: STAGE_INC 10 // stage_cnt += 10 + + 2: // Up counting loop example: + STAGE_RST // set stage_cnt to 0 + label: STAGE_INC 1 // stage_cnt++ + NOP // do something + JUMPS label, 16, LT // jump to label if stage_cnt < 16 + + +**STAGE_DEC** – Decrement stage count register +---------------------------------------------- + +**Syntax** + **STAGE_DEC** *Value* + +**Operands** + - *Value* – 8 bits value + +**Cycles** + 2 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction decrements stage count register by given value. + +**Examples**:: + + 1: STAGE_DEC 10 // stage_cnt -= 10; + + 2: // Down counting loop exaple + STAGE_RST // set stage_cnt to 0 + STAGE_INC 16 // increment stage_cnt to 16 + label: STAGE_DEC 1 // stage_cnt--; + NOP // do something + JUMPS label, 0, GT // jump to label if stage_cnt > 0 + + +**HALT** – End the program +-------------------------- + +**Syntax** + **HALT** + +**Operands** + No operands + +**Cycles** + 2 cycles to execute + +**Description** + The instruction halts the ULP coprocessor and restarts ULP wakeup timer, if it is enabled. + +**Examples**:: + + 1: HALT // Halt the coprocessor + + + +**WAKE** – Wake up the chip +--------------------------- + +**Syntax** + **WAKE** + +**Operands** + No operands + +**Cycles** + 2 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction sends an interrupt from ULP to RTC controller. + + - If the SoC is in deep sleep mode, and ULP wakeup is enabled, this causes the SoC to wake up. + + - If the SoC is not in deep sleep mode, and ULP interrupt bit (RTC_CNTL_ULP_CP_INT_ENA) is set in RTC_CNTL_INT_ENA_REG register, RTC interrupt will be triggered. + + Note that before using WAKE instruction, ULP program may needs to wait until RTC controller is ready to wake up the main CPU. This is indicated using RTC_CNTL_RDY_FOR_WAKEUP bit of RTC_CNTL_LOW_POWER_ST_REG register. If WAKE instruction is executed while RTC_CNTL_RDY_FOR_WAKEUP is zero, it has no effect (wake up does not occur). + +**Examples**:: + + 1: is_rdy_for_wakeup: // Read RTC_CNTL_RDY_FOR_WAKEUP bit + READ_RTC_FIELD(RTC_CNTL_LOW_POWER_ST_REG, RTC_CNTL_RDY_FOR_WAKEUP) + AND r0, r0, 1 + JUMP is_rdy_for_wakeup, eq // Retry until the bit is set + WAKE // Trigger wake up + REG_WR 0x006, 24, 24, 0 // Stop ULP timer (clear RTC_CNTL_ULP_CP_SLP_TIMER_EN) + HALT // Stop the ULP program + // After these instructions, SoC will wake up, + // and ULP will not run again until started by the main program. + + + +**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 +------------------------------------- + +**Syntax** + **WAIT** *Cycles* + +**Operands** + - *Cycles* – number of cycles for wait + +**Cycles** + 2 + *Cycles* cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction delays for given number of cycles. + +**Examples**:: + + 1: WAIT 10 // Do nothing for 10 cycles + + 2: .set wait_cnt, 10 // Set a constant + WAIT wait_cnt // wait for 10 cycles + + +**TSENS** – do measurement with temperature sensor +-------------------------------------------------- + +**Syntax** + - **TSENS** *Rdst, Wait_Delay* + +**Operands** + - *Rdst* – Destination Register R[0..3], result will be stored to this register + - *Wait_Delay* – number of cycles used to perform the measurement + +**Cycles** + 2 + *Wait_Delay* + 3 * TSENS_CLK to execute, 4 cycles to fetch next instruction + +**Description** + The instruction performs measurement using TSENS and stores the result into a general purpose register. + +**Examples**:: + + 1: TSENS R1, 1000 // Measure temperature sensor for 1000 cycles, + // and store result to R1 + + +**ADC** – do measurement with ADC +--------------------------------- + +**Syntax** + - **ADC** *Rdst, Sar_sel, Mux* + + - **ADC** *Rdst, Sar_sel, Mux, 0* — deprecated form + +**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 + +**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 + +**Description** + The instruction makes measurements from ADC. + +**Examples**:: + + 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 +------------------------------------------ + +**Syntax** + **REG_RD** *Addr, High, Low* + +**Operands** + - *Addr* – register address, in 32-bit words + - *High* – High part of R0 + - *Low* – Low part of R0 + +**Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction reads up to 16 bits from a peripheral register into a general purpose register: ``R0 = REG[Addr][High:Low]``. + + This instruction can access registers in RTC_CNTL, RTC_IO, SENS, and RTC_I2C peripherals. Address of the the register, as seen from the ULP, + can be calculated from the address of the same register on the DPORT bus as follows:: + + addr_ulp = (addr_dport - DR_REG_RTCCNTL_BASE) / 4 + +**Examples**:: + + 1: REG_RD 0x120, 2, 0 // load 4 bits: R0 = {12'b0, REG[0x120][7:4]} + + +**REG_WR** – write to peripheral register +----------------------------------------- + +**Syntax** + **REG_WR** *Addr, High, Low, Data* + +**Operands** + - *Addr* – register address, in 32-bit words. + - *High* – High part of R0 + - *Low* – Low part of R0 + - *Data* – value to write, 8 bits + +**Cycles** + 8 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction writes up to 8 bits from a general purpose register into a peripheral register. ``REG[Addr][High:Low] = data`` + + This instruction can access registers in RTC_CNTL, RTC_IO, SENS, and RTC_I2C peripherals. Address of the the register, as seen from the ULP, + can be calculated from the address of the same register on the DPORT bus as follows:: + + addr_ulp = (addr_dport - DR_REG_RTCCNTL_BASE) / 4 + +**Examples**:: + + 1: REG_WR 0x120, 7, 0, 0x10 // set 8 bits: REG[0x120][7:0] = 0x10 + + +Convenience macros for peripheral registers access +-------------------------------------------------- + +ULP source files are passed through C preprocessor before the assembler. This allows certain macros to be used to facilitate access to peripheral registers. + +Some existing macros are defined in ``soc/soc_ulp.h`` header file. These macros allow access to the fields of peripheral registers by their names. +Peripheral registers names which can be used with these macros are the ones defined in ``soc/rtc_cntl_reg.h``, ``soc/rtc_io_reg.h``, ``soc/sens_reg.h``, and ``soc/rtc_i2c_reg.h``. + +READ_RTC_REG(rtc_reg, low_bit, bit_width) + Read up to 16 bits from rtc_reg[low_bit + bit_width - 1 : low_bit] into R0. For example:: + + #include "soc/soc_ulp.h" + #include "soc/rtc_cntl_reg.h" + + /* Read 16 lower bits of RTC_CNTL_TIME0_REG into R0 */ + READ_RTC_REG(RTC_CNTL_TIME0_REG, 0, 16) + +READ_RTC_FIELD(rtc_reg, field) + Read from a field in rtc_reg into R0, up to 16 bits. For example:: + + #include "soc/soc_ulp.h" + #include "soc/sens_reg.h" + + /* Read 8-bit SENS_TSENS_OUT field of SENS_SAR_SLAVE_ADDR3_REG into R0 */ + READ_RTC_FIELD(SENS_SAR_SLAVE_ADDR3_REG, SENS_TSENS_OUT) + +WRITE_RTC_REG(rtc_reg, low_bit, bit_width, value) + Write immediate value into rtc_reg[low_bit + bit_width - 1 : low_bit], bit_width <= 8. For example:: + + #include "soc/soc_ulp.h" + #include "soc/rtc_io_reg.h" + + /* Set BIT(2) of RTC_GPIO_OUT_DATA_W1TS field in RTC_GPIO_OUT_W1TS_REG */ + WRITE_RTC_REG(RTC_GPIO_OUT_W1TS_REG, RTC_GPIO_OUT_DATA_W1TS_S + 2, 1, 1) + +WRITE_RTC_FIELD(rtc_reg, field, value) + Write immediate value into a field in rtc_reg, up to 8 bits. For example:: + + #include "soc/soc_ulp.h" + #include "soc/rtc_cntl_reg.h" + + /* Set RTC_CNTL_ULP_CP_SLP_TIMER_EN field of RTC_CNTL_STATE0_REG to 0 */ + WRITE_RTC_FIELD(RTC_CNTL_STATE0_REG, RTC_CNTL_ULP_CP_SLP_TIMER_EN, 0) diff --git a/docs/sphinx-known-warnings.txt b/docs/sphinx-known-warnings.txt index 51f66f18f..d2eb1541e 100644 --- a/docs/sphinx-known-warnings.txt +++ b/docs/sphinx-known-warnings.txt @@ -33,12 +33,15 @@ esp_bt_defs.inc:line: WARNING: Invalid definition: Expected identifier in nested # sphinx==1.8.4 # breathe==4.11.1 # -ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size) -ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) -ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) +ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size) +ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) +ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size) ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) +ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size) +ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) +ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) README.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) # # Issue present only when building on msys2 / mingw32 START >>> diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index e4f56cd77..39b8e6e78 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -22,7 +22,8 @@ API 指南 分区表 Secure Boot <../security/secure-boot> ULP 协处理器 - ULP ( CMake) + ULP ( CMake) + ULP ( Legacy GNU Make) 单元测试 单元测试 (传统 GNU Make) 应用层跟踪 diff --git a/docs/zh_CN/api-guides/ulp-cmake.rst b/docs/zh_CN/api-guides/ulp-cmake.rst new file mode 100644 index 000000000..543c64ecb --- /dev/null +++ b/docs/zh_CN/api-guides/ulp-cmake.rst @@ -0,0 +1 @@ +.. include:: ../../en/api-guides/ulp-cmake.rst \ No newline at end of file diff --git a/docs/zh_CN/api-guides/ulps2_instruction_set.rst b/docs/zh_CN/api-guides/ulps2_instruction_set.rst new file mode 100644 index 000000000..7ca475f3e --- /dev/null +++ b/docs/zh_CN/api-guides/ulps2_instruction_set.rst @@ -0,0 +1 @@ +.. include:: ../../en/api-guides/ulps2_instruction_set.rst \ No newline at end of file diff --git a/tools/test_idf_tools/test_idf_tools.py b/tools/test_idf_tools/test_idf_tools.py index a88702f84..0c6f6f52d 100755 --- a/tools/test_idf_tools/test_idf_tools.py +++ b/tools/test_idf_tools/test_idf_tools.py @@ -73,7 +73,7 @@ class TestUsage(unittest.TestCase): output = output_stream.getvalue() xtensa_esp32_elf_version = 'esp-2019r2-8.2.0' - esp32ulp_version = '2.28.51-esp-20190801' + esp32ulp_version = '2.28.51-esp-20191205' self.assertIn('* xtensa-esp32-elf:', output) self.assertIn('- %s (recommended)' % xtensa_esp32_elf_version, output) diff --git a/tools/tools.json b/tools/tools.json index 88cf3009a..477a271d9 100644 --- a/tools/tools.json +++ b/tools/tools.json @@ -157,7 +157,7 @@ "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20190801/binutils-esp32ulp-macos-2.28.51-esp-20190801.tar.gz" }, "name": "2.28.51-esp-20190801", - "status": "recommended", + "status": "supported", "win32": { "sha256": "44626cc2348686e9c57587142ca49cdab26fec742468942b8679f22b6661a7ec", "size": 12232098, @@ -168,6 +168,35 @@ "size": 12232098, "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20190801/binutils-esp32ulp-win32-2.28.51-esp-20190801.zip" } + }, + { + "linux-amd64": { + "sha256": "3016c4fc551181175bd9979869bc1d1f28fa8efa25a0e29ad7f833fca4bc03d7", + "size": 8248656, + "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32ulp-linux-amd64-2.28.51-esp-20191205.tar.gz" + }, + "linux-armel": { + "sha256": "88967c086a6e71834282d9ae05841ee74dae1815f27807b25cdd3f7775a47101", + "size": 8033639, + "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32ulp-linux-armel-2.28.51-esp-20191205.tar.gz" + }, + "macos": { + "sha256": "a35d9e7a0445247c7fc9dccd3fbc35682f0fafc28beeb10c94b59466317190c4", + "size": 8872874, + "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32ulp-macos-2.28.51-esp-20191205.tar.gz" + }, + "name": "2.28.51-esp-20191205", + "status": "recommended", + "win32": { + "sha256": "bade309353a9f0a4e5cc03bfe84845e33205f05502c4b199195e871ded271ab5", + "size": 12234162, + "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32ulp-win32-2.28.51-esp-20191205.zip" + }, + "win64": { + "sha256": "bade309353a9f0a4e5cc03bfe84845e33205f05502c4b199195e871ded271ab5", + "size": 12234162, + "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32ulp-win32-2.28.51-esp-20191205.zip" + } } ] }, @@ -207,7 +236,7 @@ "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20190801/binutils-esp32s2ulp-macos-2.28.51-esp-20190801.tar.gz" }, "name": "2.28.51-esp-20190801", - "status": "recommended", + "status": "supported", "win32": { "sha256": "dbd0f050273a95a82b3e506aba999c8e4d4b22c69e5f3f3efc712c8eb59355e2", "size": 12238724, @@ -218,6 +247,35 @@ "size": 12238724, "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20190801/binutils-esp32s2ulp-win32-2.28.51-esp-20190801.zip" } + }, + { + "linux-amd64": { + "sha256": "df7b2ff6c7c718a7cbe3b4b6dbcd68180d835d164d1913bc4698fd3781b9a466", + "size": 8254018, + "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32s2ulp-linux-amd64-2.28.51-esp-20191205.tar.gz" + }, + "linux-armel": { + "sha256": "893b213c8f716d455a6efb2b08b6cf1bc34d08b78ee19c31e82ac44b1b45417e", + "size": 8034624, + "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32s2ulp-linux-armel-2.28.51-esp-20191205.tar.gz" + }, + "macos": { + "sha256": "5a9bb678a5246638cbda303f523d9bb8121a9a24dc01ecb22c21c46c41184155", + "size": 8876194, + "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32s2ulp-macos-2.28.51-esp-20191205.tar.gz" + }, + "name": "2.28.51-esp-20191205", + "status": "recommended", + "win32": { + "sha256": "587de59fbb469a39f96168ae3eaa9f06b2601e6e0543c87eaf1bd97f23e5c4ca", + "size": 12239199, + "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32s2ulp-win32-2.28.51-esp-20191205.zip" + }, + "win64": { + "sha256": "587de59fbb469a39f96168ae3eaa9f06b2601e6e0543c87eaf1bd97f23e5c4ca", + "size": 12239199, + "url": "https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32s2ulp-win32-2.28.51-esp-20191205.zip" + } } ] },