diff --git a/components/ulp/README.rst b/components/ulp/README.rst deleted file mode 100644 index c9f5b14db7..0000000000 --- a/components/ulp/README.rst +++ /dev/null @@ -1,177 +0,0 @@ -Programming ULP FSM coprocessor using C macros (legacy) -======================================================= - -In addition to the existing binutils port for the {IDF_TARGET_NAME} ULP coprocessor, it is possible to generate programs for the ULP by embedding assembly-like macros into an {IDF_TARGET_NAME} application. Here is an example how this can be done:: - - const ulp_insn_t program[] = { - I_MOVI(R3, 16), // R3 <- 16 - I_LD(R0, R3, 0), // R0 <- RTC_SLOW_MEM[R3 + 0] - I_LD(R1, R3, 1), // R1 <- RTC_SLOW_MEM[R3 + 1] - I_ADDR(R2, R0, R1), // R2 <- R0 + R1 - I_ST(R2, R3, 2), // R2 -> RTC_SLOW_MEM[R2 + 2] - I_HALT() - }; - size_t load_addr = 0; - size_t size = sizeof(program)/sizeof(ulp_insn_t); - ulp_process_macros_and_load(load_addr, program, &size); - ulp_run(load_addr); - -The ``program`` array is an array of ``ulp_insn_t``, i.e. ULP coprocessor instructions. Each ``I_XXX`` preprocessor define translates into a single 32-bit instruction. Arguments of these preprocessor defines can be register numbers (``R0 — R3``) and literal constants. See `ULP coprocessor instruction defines`_ section for descriptions of instructions and arguments they take. - -.. note:: - - Because some of the instruction macros expand to inline function calls, defining such array in global scope will cause the compiler to produce an "initializer element is not constant" error. To fix this error, move the definition of instructions array into local scope. - -Load and store instructions use addresses expressed in 32-bit words. Address 0 corresponds to the first word of ``RTC_SLOW_MEM`` (which is address 0x50000000 as seen by the main CPUs). - -To generate branch instructions, special ``M_`` preprocessor defines are used. ``M_LABEL`` define can be used to define a branch target. Label identifier is a 16-bit integer. ``M_Bxxx`` defines can be used to generate branch instructions with target set to a particular label. - -Implementation note: these ``M_`` preprocessor defines will be translated into two ``ulp_insn_t`` values: one is a token value which contains label number, and the other is the actual instruction. ``ulp_process_macros_and_load`` function resolves the label number to the address, modifies the branch instruction to use the correct address, and removes the the extra ``ulp_insn_t`` token which contains the label numer. - -Here is an example of using labels and branches:: - - const ulp_insn_t program[] = { - I_MOVI(R0, 34), // R0 <- 34 - M_LABEL(1), // label_1 - I_MOVI(R1, 32), // R1 <- 32 - I_LD(R1, R1, 0), // R1 <- RTC_SLOW_MEM[R1] - I_MOVI(R2, 33), // R2 <- 33 - I_LD(R2, R2, 0), // R2 <- RTC_SLOW_MEM[R2] - I_SUBR(R3, R1, R2), // R3 <- R1 - R2 - I_ST(R3, R0, 0), // R3 -> RTC_SLOW_MEM[R0 + 0] - I_ADDI(R0, R0, 1), // R0++ - M_BL(1, 64), // if (R0 < 64) goto label_1 - I_HALT(), - }; - RTC_SLOW_MEM[32] = 42; - RTC_SLOW_MEM[33] = 18; - size_t load_addr = 0; - size_t size = sizeof(program)/sizeof(ulp_insn_t); - ulp_process_macros_and_load(load_addr, program, &size); - ulp_run(load_addr); - - -Application Example -------------------- - -Demonstration of entering into deep sleep mode and waking up using several wake up sources: :example:`system/deep_sleep`. - - -API Reference -------------- - -Header File -^^^^^^^^^^^ - -.. list:: - - :esp32: - :component_file:`ulp/ulp_fsm/include/esp32/ulp.h` - :esp32s2: - :component_file:`ulp/ulp_fsm/include/esp32s2/ulp.h` - :esp32s3: - :component_file:`ulp/ulp_fsm/include/esp32s3/ulp.h` - -Functions -^^^^^^^^^ - -.. doxygenfunction:: ulp_process_macros_and_load -.. doxygenfunction:: ulp_run - -Error codes -^^^^^^^^^^^ - -.. doxygendefine:: ESP_ERR_ULP_BASE -.. doxygendefine:: ESP_ERR_ULP_SIZE_TOO_BIG -.. doxygendefine:: ESP_ERR_ULP_INVALID_LOAD_ADDR -.. doxygendefine:: ESP_ERR_ULP_DUPLICATE_LABEL -.. doxygendefine:: ESP_ERR_ULP_UNDEFINED_LABEL -.. doxygendefine:: ESP_ERR_ULP_BRANCH_OUT_OF_RANGE - -ULP coprocessor registers -^^^^^^^^^^^^^^^^^^^^^^^^^ - -ULP co-processor has 4 16-bit general purpose registers. All registers have same functionality, with one exception. R0 register is used by some of the compare-and-branch instructions as a source register. - -These definitions can be used for all instructions which require a register. - -.. doxygengroup:: ulp_registers - :content-only: - -ULP coprocessor instruction defines -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. doxygendefine:: I_DELAY -.. doxygendefine:: I_HALT -.. doxygendefine:: I_END -.. doxygendefine:: I_ST -.. only:: esp32s2 or esp32s3 - - .. doxygendefine:: I_ST_MANUAL - .. doxygendefine:: I_STL - .. doxygendefine:: I_STH - .. doxygendefine:: I_ST32 - .. doxygendefine:: I_STL_LABEL - .. doxygendefine:: I_STH_LABEL - .. doxygendefine:: I_ST_AUTO - .. doxygendefine:: I_STO - .. doxygendefine:: I_STI - .. doxygendefine:: I_STI_LABEL - .. doxygendefine:: I_STI32 - -.. doxygendefine:: I_LD -.. only:: esp32s2 or esp32s3 - - .. doxygendefine:: I_LD_MANUAL - .. doxygendefine:: I_LDL - .. doxygendefine:: I_LDH - -.. doxygendefine:: I_WR_REG -.. doxygendefine:: I_RD_REG -.. doxygendefine:: I_BL -.. only:: esp32 - - .. doxygendefine:: I_BGE - -.. only:: esp32s2 or esp32s3 - - .. doxygendefine:: I_BG - .. doxygendefine:: I_BE - -.. doxygendefine:: I_BXR -.. doxygendefine:: I_BXI -.. doxygendefine:: I_BXZR -.. doxygendefine:: I_BXZI -.. doxygendefine:: I_BXFR -.. doxygendefine:: I_BXFI -.. doxygendefine:: I_ADDR -.. doxygendefine:: I_SUBR -.. doxygendefine:: I_ANDR -.. doxygendefine:: I_ORR -.. doxygendefine:: I_MOVR -.. doxygendefine:: I_LSHR -.. doxygendefine:: I_RSHR -.. doxygendefine:: I_ADDI -.. doxygendefine:: I_SUBI -.. doxygendefine:: I_ANDI -.. doxygendefine:: I_ORI -.. doxygendefine:: I_MOVI -.. doxygendefine:: I_LSHI -.. doxygendefine:: I_RSHI -.. doxygendefine:: M_LABEL -.. doxygendefine:: M_BL -.. only:: esp32 - - .. doxygendefine:: M_BGE - -.. only:: esp32s2 or esp32s3 - - .. doxygendefine:: M_BG - .. doxygendefine:: M_BE - -.. doxygendefine:: M_BX -.. doxygendefine:: M_BXZ -.. doxygendefine:: M_BXF - -Defines -^^^^^^^ - -.. doxygendefine:: RTC_SLOW_MEM - diff --git a/components/ulp/ulp_fsm/include/esp32/ulp.h b/components/ulp/ulp_fsm/include/esp32/ulp.h index 71ed0a7562..25de6a0801 100644 --- a/components/ulp/ulp_fsm/include/esp32/ulp.h +++ b/components/ulp/ulp_fsm/include/esp32/ulp.h @@ -279,10 +279,6 @@ union ulp_insn { }; -typedef union ulp_insn ulp_insn_t; - -_Static_assert(sizeof(ulp_insn_t) == 4, "ULP coprocessor instruction size should be 4 bytes"); - /** * Delay (nop) for a given number of cycles */ diff --git a/components/ulp/ulp_fsm/include/esp32s2/ulp.h b/components/ulp/ulp_fsm/include/esp32s2/ulp.h index b21bd937c7..33a5738326 100644 --- a/components/ulp/ulp_fsm/include/esp32s2/ulp.h +++ b/components/ulp/ulp_fsm/include/esp32s2/ulp.h @@ -266,10 +266,6 @@ union ulp_insn { }; -typedef union ulp_insn ulp_insn_t; - -_Static_assert(sizeof(ulp_insn_t) == 4, "ULP coprocessor instruction size should be 4 bytes"); - /** * Delay (nop) for a given number of cycles */ diff --git a/components/ulp/ulp_fsm/include/esp32s3/ulp.h b/components/ulp/ulp_fsm/include/esp32s3/ulp.h index b21bd937c7..33a5738326 100644 --- a/components/ulp/ulp_fsm/include/esp32s3/ulp.h +++ b/components/ulp/ulp_fsm/include/esp32s3/ulp.h @@ -266,10 +266,6 @@ union ulp_insn { }; -typedef union ulp_insn ulp_insn_t; - -_Static_assert(sizeof(ulp_insn_t) == 4, "ULP coprocessor instruction size should be 4 bytes"); - /** * Delay (nop) for a given number of cycles */ diff --git a/docs/conf_common.py b/docs/conf_common.py index bdacefd60f..93c224a53e 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -81,9 +81,11 @@ FTDI_JTAG_DOCS = ['api-guides/jtag-debugging/configure-ft2232h-jtag.rst'] USB_SERIAL_JTAG_DOCS = ['api-guides/jtag-debugging/configure-builtin-jtag.rst', 'api-guides/usb-serial-jtag-console.rst'] -ULP_DOCS = ['api-guides/ulp.rst', 'api-guides/ulp_macros.rst'] +ULP_DOCS = ['api-reference/system/ulp.rst', + 'api-reference/system/ulp_macros.rst', + 'api-reference/system/ulp_instruction_set.rst'] -RISCV_COPROC_DOCS = ['api-guides/ulp-risc-v.rst',] +RISCV_COPROC_DOCS = ['api-reference/system/ulp-risc-v.rst',] XTENSA_DOCS = ['api-guides/hlinterrupts.rst', 'api-reference/system/perfmon.rst'] @@ -96,8 +98,7 @@ SIGMADELTA_DOCS = ['api-reference/peripherals/sigmadelta.rst'] I2S_DOCS = ['api-reference/peripherals/i2s.rst'] -ESP32_DOCS = ['api-guides/ulp_instruction_set.rst', - 'api-reference/system/himem.rst', +ESP32_DOCS = ['api-reference/system/himem.rst', 'api-guides/romconsole.rst', 'api-reference/system/ipc.rst', 'security/secure-boot-v1.rst', @@ -107,7 +108,6 @@ ESP32_DOCS = ['api-guides/ulp_instruction_set.rst', 'api-guides/RF_calibration.rst'] + FTDI_JTAG_DOCS ESP32S2_DOCS = ['hw-reference/esp32s2/**', - 'api-guides/ulp_extended_instruction_set.rst', 'api-guides/usb-console.rst', 'api-reference/peripherals/ds.rst', 'api-reference/peripherals/spi_slave_hd.rst', @@ -117,7 +117,6 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**', 'api-guides/RF_calibration.rst'] + FTDI_JTAG_DOCS ESP32S3_DOCS = ['hw-reference/esp32s3/**', - 'api-guides/ulp_extended_instruction_set.rst', 'api-reference/system/ipc.rst', 'api-guides/flash_psram_config.rst', 'api-guides/RF_calibration.rst'] diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index cc8ebc5242..07be051373 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -198,7 +198,6 @@ INPUT = \ $(PROJECT_PATH)/components/ulp/ulp_common/include/ulp_common.h \ $(PROJECT_PATH)/components/ulp/ulp_fsm/include/ulp_fsm_common.h \ $(PROJECT_PATH)/components/ulp/ulp_riscv/include/ulp_riscv.h \ - $(PROJECT_PATH)/components/ulp/ulp_riscv/include/ulp_riscv_utils.h \ $(PROJECT_PATH)/components/app_trace/include/esp_app_trace.h \ $(PROJECT_PATH)/components/app_trace/include/esp_sysview_trace.h \ $(PROJECT_PATH)/components/esp_pm/include/esp_pm.h \ diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index 066ad63410..bda9b935cc 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -36,11 +36,9 @@ API Guides :SOC_SPIRAM_SUPPORTED: external-ram thread-local-storage tools/index - :SOC_ULP_SUPPORTED: ulp - :SOC_RISCV_COPROC_SUPPORTED: ulp-risc-v unit-tests linux-host-testing :SOC_USB_OTG_SUPPORTED: usb-otg-console :SOC_USB_SERIAL_JTAG_SUPPORTED: usb-serial-jtag-console :SOC_WIFI_SUPPORTED: wifi - :SOC_WIFI_SUPPORTED: wifi-security \ No newline at end of file + :SOC_WIFI_SUPPORTED: wifi-security diff --git a/docs/en/api-guides/memory-types.rst b/docs/en/api-guides/memory-types.rst index 8499fcd08c..d50027cabb 100644 --- a/docs/en/api-guides/memory-types.rst +++ b/docs/en/api-guides/memory-types.rst @@ -156,7 +156,7 @@ The ``DRAM_ATTR`` attribute can be used to force constants from DROM into the :r RTC Slow memory ^^^^^^^^^^^^^^^ - Global and static variables used by code which runs from RTC memory must be placed into RTC Slow memory. For example :doc:`deep sleep ` variables can be placed here instead of RTC FAST memory, or code and variables accessed by the :doc:`/api-guides/ulp`. + Global and static variables used by code which runs from RTC memory must be placed into RTC Slow memory. For example :doc:`deep sleep ` variables can be placed here instead of RTC FAST memory, or code and variables accessed by the :doc:`/api-reference/system/ulp`. The attribute macro named ``RTC_NOINIT_ATTR`` can be used to place data into this type of memory. The values placed into this section keep their value after waking from deep sleep. diff --git a/docs/en/api-guides/ulp-risc-v.rst b/docs/en/api-guides/ulp-risc-v.rst deleted file mode 100644 index 8cf57b443a..0000000000 --- a/docs/en/api-guides/ulp-risc-v.rst +++ /dev/null @@ -1,157 +0,0 @@ -ULP-RISC-V Coprocessor programming -================================== -:link_to_translation:`zh_CN:[中文]` - -.. only:: esp32s3 - - .. warning:: - - This feature is not supported in v4.4 - - -.. toctree:: - :maxdepth: 1 - - -The ULP-RISC-V coprocessor is a variant of the ULP, present in ESP32-S2. Similar to ULP, ULP RISC-V coprocessor can perform tasks such as sensor readings while the main CPU stays in low power modes. The main difference from the FSM ULP is this variant can be programmed in C using standard GNU tools. The ULP-RISC-V coprocessor can access the RTC_SLOW_MEM memory region, and registers in RTC_CNTL, RTC_IO, and SARADC peripherals. The RISC-V processor is a 32-bit, fixed point machine. Its instruction set is based on RV32IMC which includes hardware multiplication and division, and compressed code. - -Installing the ULP-RISC-V Toolchain ------------------------------------ - -The ULP-RISC-V coprocessor code is written in C (assembly is also possible) and compiled using RISC-V toolchain based on GCC. - -If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../get-started/index>`, then the toolchain should already be installed. - -.. note: In earlier versions of ESP-IDF, RISC-V toolchain had a different prefix: `riscv-none-embed-gcc`. - -Compiling the ULP-RISC-V Code ------------------------------ - -To compile the ULP-RISC-V code as part of the component, the following steps must be taken: - -1. The ULP-RISC-V code, written in C or assembly (must use the `.S` extension), must be placed into a separate directory inside the component directory, for instance `ulp/`. - -.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument as it is currently done for the FSM ULP. See the step below for how to properly add ULP source files - -2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example:: - - ... - idf_component_register() - - set(ulp_app_name ulp_${COMPONENT_NAME}) - set(ulp_sources "ulp/ulp_c_source_file.c" "ulp/ulp_assembly_source_file.S") - set(ulp_exp_dep_srcs "ulp_c_source_file.c") - - ulp_embed_binary(${ulp_app_name} "${ulp_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 by other generated artifacts - such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP 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 will be created before any of these files are compiled. - See section below for 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 source file through the C compiler and assembler.** This step generates the object files (.obj.c or .obj.S depending of source file processed) in the component build directory. - - 2. **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 ``riscv32-esp-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-RISC-V Program Variables ------------------------------------------- - -Global symbols defined in the ULP-RISC-V program may be used inside the main program. - -For example, the ULP-RISC-V 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 - -.. code-block:: c - - volatile int measurement_count; - - int some_function() - { - //read the measurement count for use it later. - int temp = measurement_count; - - ...do something. - } - -The main program can access the global ULP-RISC-V program variables, 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 - -.. code-block:: c - - 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-RISC-V 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 - -.. code-block:: c - - #include "ulp_app_name.h" - - void init_ulp_vars() { - ulp_measurement_count = 64; - } - -Starting the ULP-RISC-V Program -------------------------------- - -To run a ULP-RISC-V program, the main application needs to load the ULP program into RTC memory using the :cpp:func:`ulp_riscv_load_binary` function, and then start it using the :cpp:func:`ulp_riscv_run` function. - -Note that `CONFIG_ULP_COPROC_ENABLED` and `CONFIG_ULP_COPROC_TYPE_RISCV` options 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-RISC-V 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``) - -.. code-block:: c - - 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_riscv_load_binary( bin_start, - (bin_end - bin_start)) ); - } - -.. doxygenfunction:: ulp_riscv_load_binary() - -Once the program is loaded into RTC memory, the application can start it, calling the :cpp:func:`ulp_riscv_run` function - -.. code-block:: c - - ESP_ERROR_CHECK( ulp_riscv_run() ); - -.. doxygenfunction:: ulp_riscv_run() - -ULP-RISC-V Program Flow ------------------------ - -{IDF_TARGET_RTC_CLK_FRE:default="150kHz", esp32s2="90kHz"} - -The ULP-RISC-V coprocessor is started by a timer. The timer is started once :cpp:func:`ulp_riscv_run` is called. The timer counts the number of RTC_SLOW_CLK ticks (by default, produced by an internal {IDF_TARGET_RTC_CLK_FRE} RC oscillator). The number of ticks is set using ``RTC_CNTL_ULP_CP_TIMER_1_REG`` register. When starting the ULP, ``RTC_CNTL_ULP_CP_TIMER_1_REG`` will be used to set the number of timer ticks. - -The application can set ULP timer period values (RTC_CNTL_ULP_CP_TIMER_1_REG) using the :cpp:func:`ulp_set_wakeup_period` function. - -Once the timer counts the number of ticks set in the ``RTC_CNTL_ULP_CP_TIMER_1_REG`` register, the ULP coprocessor will power up and start running the program from the entry point set in the call to :cpp:func:`ulp_riscv_run`. - -The program runs until the field ``RTC_CNTL_COCPU_DONE`` in register ``RTC_CNTL_COCPU_CTRL_REG`` gets written or when a trap occurs due to illegal processor state. 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. - diff --git a/docs/en/api-guides/ulp.rst b/docs/en/api-guides/ulp.rst deleted file mode 100644 index 49dad2a71e..0000000000 --- a/docs/en/api-guides/ulp.rst +++ /dev/null @@ -1,183 +0,0 @@ -ULP Coprocessor programming -============================= - -:link_to_translation:`zh_CN:[中文]` - -.. only:: esp32s3 - - .. warning:: - - This feature is not supported in v4.4 - -.. toctree:: - :maxdepth: 1 - - :esp32: Instruction set reference for ESP32 ULP - :esp32s2: Instruction set reference for ESP32-S2 ULP - :esp32s3: Instruction set reference for ESP32-S3 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 ------------------------- - -The ULP coprocessor code is written in assembly and compiled using the `binutils-esp32ulp toolchain`_. - -If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../get-started/index>`, then the ULP toolchain will already be installed. - -Compiling the ULP Code ------------------------ - -To compile the ULP code as part of the component, the following steps must be taken: - -1. The 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 the component directory, for instance `ulp/`. - -.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument. The logic behind this is that the ESP-IDF build system will compile files found in ``SRC_DIRS`` based on their extensions. For ``.S`` files, ``{IDF_TARGET_TOOLCHAIN_PREFIX}-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 ``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:: - - ... - idf_component_register() - - 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 by 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 will be created before any of these files are compiled. See section below for 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 */ - -.. only:: esp32 - - ESP32 ULP program flow - ----------------------- - - 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 ``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, 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. - - -.. 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_extended_instruction_set.rst b/docs/en/api-guides/ulp_extended_instruction_set.rst deleted file mode 100644 index 6f94933c49..0000000000 --- a/docs/en/api-guides/ulp_extended_instruction_set.rst +++ /dev/null @@ -1,1101 +0,0 @@ -{IDF_TARGET_NAME} ULP coprocessor instruction set -======================================== - -This document provides details about the instructions used by {IDF_TARGET_NAME} 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 register 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 ---------------------- -{IDF_TARGET_NAME} ULP coprocessor's ``JUMP``, ``ST``, ``LD`` family of instructions expect the address argument to be expressed in the following way depending on the type of address argument used: - -- When the address argument is presented as a label then the instruction expects the address to be expressed as 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 ``R1`` to be expressed in 32-bit words. To account for this common use case, the assembler will convert the address of label `loop` from bytes to words, when generating the ``MOVE`` instruction. Hence, 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 {IDF_TARGET_NAME} ULP Instruction sets --------------------------------------------------------------- - -Compared to the ESP32 ULP coprocessor, the {IDF_TARGET_NAME} ULP coprocessor has an extended instruction set. The {IDF_TARGET_NAME} ULP is not binary compatible with ESP32 ULP, -but the assembled program that was written for the ESP32 ULP will also work on the {IDF_TARGET_NAME} ULP after rebuild. -The list of the new instructions that was added to the {IDF_TARGET_NAME} 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* – 13-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* – 13-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. - - - -**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. 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 - -**Description** - The instruction makes measurements from ADC. - -**Examples**:: - - 1: ADC R1, 0, 1 // Measure value using ADC1 pad 2 and store result into R1 - - -**REG_RD** – read from peripheral register ------------------------------------------- - -**Syntax** - **REG_RD** *Addr, High, Low* - -**Operands** - - *Addr* – Register address, in 32-bit words - - *High* – Register end bit number - - *Low* – Register start bit number - -**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 PeriBUS1 as follows:: - - addr_ulp = (addr_peribus1 - DR_REG_RTCCNTL_BASE) / 4 - -**Examples**:: - - 1: REG_RD 0x120, 7, 4 // 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* – Register end bit number - - *Low* – Register start bit number - - *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 an immediate data value 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 PeriBUS1 as follows:: - - addr_ulp = (addr_peribus1 - 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/en/api-guides/ulp_instruction_set.rst b/docs/en/api-guides/ulp_instruction_set.rst deleted file mode 100644 index acdd36b85f..0000000000 --- a/docs/en/api-guides/ulp_instruction_set.rst +++ /dev/null @@ -1,948 +0,0 @@ -ESP32 ULP coprocessor instruction set -===================================== - -This document provides details about the instructions used by {IDF_TARGET_NAME} 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 register 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 ---------------------- -{IDF_TARGET_NAME} 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. - - -**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 - - -**ST** – Store data to the memory ---------------------------------- - -**Syntax** - **ST** *Rsrc, Rdst, offset* - -**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* – 13-bit signed value, offset in bytes - -**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. The upper half-word is written with the current program counter (PC) (expressed in words, shifted left by 5 bits) OR'd with Rdst (0..3):: - - Mem[Rdst + offset / 4]{31:0} = {PC[10:0], 3'b0, Rdst, Rsrc[15:0]} - - The application can use higher 16 bits to determine which instruction in the ULP program has written any particular word into memory. - -**Examples**:: - - 1: ST 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 - ST R1, R2, offs // MEM[R2 + 0] = R1 - // MEM[Addr1 + 0] will be 32'h600001 - - -**LD** – Load data from the memory ----------------------------------- - -**Syntax** - **LD** *Rdst, Rsrc, offset* - -**Operands** - *Rdst* – Register R[0..3], destination - - *Rsrc* – Register R[0..3], holds address of destination, in 32-bit words - - *Offset* – 13-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] - -**Examples**:: - - 1: LD 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) - LD R1, R2, offs // R1 = MEM[R2 + 0] - // R1 will be 123 - - - - -**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 *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. - -**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** - Conditions *LE*, *LT*, *GE*: 2 cycles to execute, 2 cycles to fetch next instruction - - Conditions *EQ*, *GT* are implemented in the assembler using two **JUMPS** instructions:: - - // 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 example - 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* - Enable ADC channel. Channel number is [Mux-1]. If the user passes Mux value 1, then ADC channel 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 - -**Description** - The instruction makes measurements from ADC. - -**Examples**:: - - 1: ADC R1, 0, 1 // Measure value using ADC1 channel 0 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* – Register end bit number - - *Low* – Register start bit number - -**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, 7, 4 // 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* – Register end bit number - - *Low* – Register start bit number - - *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 an immediate data value 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/en/api-guides/ulp_macros.rst b/docs/en/api-guides/ulp_macros.rst deleted file mode 100644 index 9859dcc92f..0000000000 --- a/docs/en/api-guides/ulp_macros.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../components/ulp/README.rst \ No newline at end of file diff --git a/docs/en/api-reference/peripherals/adc.rst b/docs/en/api-reference/peripherals/adc.rst index 2364057e3a..e7c77a5690 100644 --- a/docs/en/api-reference/peripherals/adc.rst +++ b/docs/en/api-reference/peripherals/adc.rst @@ -185,7 +185,7 @@ Single Read mode ADC example can be found in :example:`peripherals/adc/single_re .. only:: SOC_ULP_SUPPORTED - This API provides convenient way to configure ADC1 for reading from :doc:`ULP <../../api-guides/ulp>`. To do so, call function :cpp:func:`adc1_ulp_enable` and then set precision and attenuation as discussed above. + This API provides convenient way to configure ADC1 for reading from :doc:`ULP <../../api-reference/system/ulp>`. To do so, call function :cpp:func:`adc1_ulp_enable` and then set precision and attenuation as discussed above. .. only:: esp32 or esp32s2 diff --git a/docs/en/api-reference/peripherals/gpio.rst b/docs/en/api-reference/peripherals/gpio.rst index 11ce098cce..56393b76b4 100644 --- a/docs/en/api-reference/peripherals/gpio.rst +++ b/docs/en/api-reference/peripherals/gpio.rst @@ -914,7 +914,7 @@ Overview .. list:: - In deep sleep - :SOC_ULP_SUPPORTED: - The :doc:`Ultra Low Power co-processor <../../api-guides/ulp>` is running + :SOC_ULP_SUPPORTED: - The :doc:`Ultra Low Power co-processor <../../api-reference/system/ulp>` is running - Analog functions such as ADC/DAC/etc are in use. Application Example diff --git a/docs/en/api-reference/system/index.rst b/docs/en/api-reference/system/index.rst index 831d2c6db7..959b71452f 100644 --- a/docs/en/api-reference/system/index.rst +++ b/docs/en/api-reference/system/index.rst @@ -33,6 +33,8 @@ System API system_time :SOC_ASYNC_MEMCPY_SUPPORTED: async_memcpy :esp32: himem + :SOC_ULP_SUPPORTED: ulp + :SOC_RISCV_COPROC_SUPPORTED: ulp-risc-v wdts diff --git a/docs/en/api-reference/system/ulp-risc-v.rst b/docs/en/api-reference/system/ulp-risc-v.rst new file mode 100644 index 0000000000..e1e1be27c6 --- /dev/null +++ b/docs/en/api-reference/system/ulp-risc-v.rst @@ -0,0 +1,148 @@ +ULP RISC-V Coprocessor programming +================================== +:link_to_translation:`zh_CN:[中文]` + +The ULP RISC-V coprocessor is a variant of the ULP present in {IDF_TARGET_NAME}. Similar to ULP FSM, the ULP RISC-V coprocessor can perform tasks such as sensor readings while the main CPU stays in low power modes. The main difference between ULP FSM and ULP RISC-V is that the latter can be programmed in C using standard GNU tools. The ULP RISC-V coprocessor can access the RTC_SLOW_MEM memory region, and registers in RTC_CNTL, RTC_IO, and SARADC peripherals. The RISC-V processor is a 32-bit fixed point machine. Its instruction set is based on RV32IMC which includes hardware multiplication and division, and compressed code. + +Installing the ULP RISC-V Toolchain +----------------------------------- + +The ULP RISC-V coprocessor code is written in C (assembly is also possible) and compiled using the RISC-V toolchain based on GCC. + +If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../../get-started/index>`, then the toolchain should already be installed. + +.. note: In earlier versions of ESP-IDF, RISC-V toolchain had a different prefix: `riscv-none-embed-gcc`. + +Compiling the ULP RISC-V Code +----------------------------- + +To compile the ULP RISC-V code as part of the component, the following steps must be taken: + +1. The ULP RISC-V code, written in C or assembly (must use the `.S` extension), must be placed in a separate directory inside the component directory, for instance, `ulp/`. + +.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument as it is currently done for the ULP FSM. See the step below for how to properly add ULP source files. + +2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example:: + + ... + idf_component_register() + + set(ulp_app_name ulp_${COMPONENT_NAME}) + set(ulp_sources "ulp/ulp_c_source_file.c" "ulp/ulp_assembly_source_file.S") + set(ulp_exp_dep_srcs "ulp_c_source_file.c") + + ulp_embed_binary(${ulp_app_name} "${ulp_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 by other generated artifacts such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP 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 will be created before any of these files are compiled. See the section below for 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 source file through the C compiler and assembler.** This step generates the object files (.obj.c or .obj.S depending of source file processed) in the component build directory. + + 2. **Run the linker script template through the C preprocessor.** The template is located in ``components/ulp/ld`` directory. + + 3. **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. + + 4. **Dump the contents of the ELF file into a binary** (``ulp_app_name.bin``) which can then be embedded into the application. + + 5. **Generate a list of global symbols** (``ulp_app_name.sym``) in the ELF file using ``riscv32-esp-elf-nm``. + + 6. **Create an LD export script and a 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. + + 7. **Add the generated binary to the list of binary files** to be embedded into the application. + +Accessing the ULP RISC-V Program Variables +------------------------------------------ + +Global symbols defined in the ULP RISC-V program may be used inside the main program. + +For example, the ULP RISC-V 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. + +.. code-block:: c + + volatile int measurement_count; + + int some_function() + { + //read the measurement count for use it later. + int temp = measurement_count; + + ...do something. + } + +The main program can access the global ULP RISC-V program variables as 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 RISC-V program. Each global symbol defined in the ULP RISC-V program is included in these files and are prefixed with ``ulp_``. + +The header file contains the declaration of the symbol: + +.. code-block:: c + + 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 RISC-V program variables from the main program, the generated header file should be included using an ``include`` statement. This will allow the ULP RISC-V program variables to be accessed as regular variables. + +.. code-block:: c + + #include "ulp_app_name.h" + + void init_ulp_vars() { + ulp_measurement_count = 64; + } + +Starting the ULP RISC-V Program +------------------------------- + +To run a ULP RISC-V program, the main application needs to load the ULP program into RTC memory using the :cpp:func:`ulp_riscv_load_binary` function, and then start it using the :cpp:func:`ulp_riscv_run` function. + +Note that `CONFIG_ULP_COPROC_ENABLED` and `CONFIG_ULP_COPROC_TYPE_RISCV` options must be enabled in menuconfig to work with ULP RISC-V. To reserve memory for the ULP, the ``RTC slow memory reserved for coprocessor`` option must be set to a value big enough to store ULP RISC-V 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 RISC-V 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``): + +.. code-block:: c + + 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_riscv_load_binary( bin_start, + (bin_end - bin_start)) ); + } + +Once the program is loaded into RTC memory, the application can start it by calling the :cpp:func:`ulp_riscv_run` function: + +.. code-block:: c + + ESP_ERROR_CHECK( ulp_riscv_run() ); + +ULP RISC-V Program Flow +----------------------- + +{IDF_TARGET_RTC_CLK_FRE:default="150kHz", esp32s2="90kHz", esp32s3="136kHz"} + +The ULP RISC-V coprocessor is started by a timer. The timer is started once :cpp:func:`ulp_riscv_run` is called. The timer counts the number of RTC_SLOW_CLK ticks (by default, produced by an internal {IDF_TARGET_RTC_CLK_FRE} RC oscillator). The number of ticks is set using ``RTC_CNTL_ULP_CP_TIMER_1_REG`` register. When starting the ULP, ``RTC_CNTL_ULP_CP_TIMER_1_REG`` will be used to set the number of timer ticks. + +The application can set ULP timer period values (RTC_CNTL_ULP_CP_TIMER_1_REG) using the :cpp:func:`ulp_set_wakeup_period` function. + +Once the timer counts the number of ticks set in the ``RTC_CNTL_ULP_CP_TIMER_1_REG`` register, the ULP RISC-V coprocessor will power up and start running the program from the entry point set in the call to :cpp:func:`ulp_riscv_run`. + +The program runs until the field ``RTC_CNTL_COCPU_DONE`` in register ``RTC_CNTL_COCPU_CTRL_REG`` gets written or when a trap occurs due to illegal processor state. Once the program halts, the ULP RISC-V 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_ULP_CP_TIMER_REG`` register. This can be done both from the ULP code and from the main program. + +Application Examples +-------------------- + +* ULP RISC-V Coprocessor polls GPIO while main CPU is in deep sleep: :example:`system/ulp_riscv/gpio`. +* ULP RISC-V Coprocessor reads external temperature sensor while main CPU is in deep sleep: :example:`system/ulp_riscv/ds18b20_onewire`. + +API Reference +------------- + +.. include-build-file:: inc/ulp_riscv.inc diff --git a/docs/en/api-reference/system/ulp.rst b/docs/en/api-reference/system/ulp.rst new file mode 100644 index 0000000000..6349bf2e42 --- /dev/null +++ b/docs/en/api-reference/system/ulp.rst @@ -0,0 +1,187 @@ +ULP Coprocessor programming +============================= + +:link_to_translation:`zh_CN:[中文]` + +The Ultra Low Power (ULP) coprocessor is a simple finite state machine (FSM) 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 the 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. This coprocessor is referred to as `ULP FSM` in ESP-IDF. + +.. only:: esp32s2 or esp32s3 + + {IDF_TARGET_NAME} provides a second type of ULP coprocessor which is based on a RISC-V instruction set architecture. For details regarding `ULP RISC-V` refer :doc:`ULP-RISC-V Coprocessor <../../../api-reference/system/ulp-risc-v>`. + +Installing the Toolchain +------------------------ + +The ULP FSM coprocessor code is written in assembly and compiled using the `binutils-esp32ulp toolchain`_. + +If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../../get-started/index>`, then the ULP FSM toolchain will already be installed. + +Programming ULP FSM +------------------- + +The ULP FSM can be programmed using the supported instruction set. Alternatively, the ULP FSM coprocessor can also be programmed using C Macros on the main CPU. Theses two methods are described in the following section: + +.. toctree:: + :maxdepth: 1 + + Instruction set reference for {IDF_TARGET_NAME} ULP + Programming using macros (legacy) + +Compiling the ULP Code +----------------------- + +To compile the ULP FSM code as part of the component, the following steps must be taken: + +1. The ULP FSM 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 the component directory, for instance, `ulp/`. + +.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument. The logic behind this is that the ESP-IDF build system will compile files found in ``SRC_DIRS`` based on their extensions. For ``.S`` files, ``{IDF_TARGET_TOOLCHAIN_PREFIX}-as`` assembler is used. This is not desirable for ULP FSM assembly files, so the easiest way to achieve the distinction is by placing ULP FSM assembly files into a separate directory. The ULP FSM assembly source files should also **not** be added to ``SRCS`` for the same reason. See the step below for how to properly add ULP FSM assembly source files. + +2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example:: + + ... + idf_component_register() + + 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 FSM binary name. The name specified here will also be used by other generated artifacts such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP FSM 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 will be created before any of these files are compiled. See the section below for 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 FSM 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 a 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 FSM Program Variables +--------------------------------------- + +Global symbols defined in the ULP FSM program may be used inside the main program. + +For example, the ULP FSM 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; + } + +.. only:: esp32 + + Note that the ULP FSM program can only use the 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 values into the lower 16 bits of the 32-bit word in RTC memory. 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 coprocessor, 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 FSM Program +---------------------------- + +To run a ULP FSM program, the main application needs to load the ULP program into RTC memory using the :cpp:func:`ulp_load_binary` function, and then start it using the :cpp:func:`ulp_run` function. + +Note that the ``Enable Ultra Low Power (ULP) Coprocessor`` option must be enabled in menuconfig to work with ULP. To select the type of ULP to be used, the ``ULP Co-processor type`` option must be set. To reserve memory for the ULP, the ``RTC slow memory reserved for coprocessor`` option must be set to a value big enough 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)) ); + } + +Once the program is loaded into RTC memory, the application can start it by passing the address of the entry point to the ``ulp_run`` function:: + + ESP_ERROR_CHECK( ulp_run(&ulp_entry - RTC_SLOW_MEM) ); + +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 FSM application, this symbol must be marked as ``.global``:: + + + .global entry + entry: + // code starts here + +.. only:: esp32 + + ESP32 ULP program flow + ----------------------- + + ESP32 ULP coprocessor is started by a timer. The timer is started once :cpp:func:`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 ``ulp_set_wakeup_period`` function. + + 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 :cpp:func:`ulp_run`. + + The program runs until it encounters a ``halt`` instruction or an illegal instruction. Once the program halts the 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. + + +.. only:: esp32s2 or esp32s3 + + {IDF_TARGET_NAME} ULP program flow + ---------------------------------- + + {IDF_TARGET_NAME} ULP coprocessor is started by a timer. The timer is started once :cpp:func:`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 :cpp:func:`ulp_set_wakeup_period` function. + + 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 :cpp:func:`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_ULP_CP_TIMER_REG`` register. This can be done both from ULP code and from the main program. + +Application Examples +-------------------- + +* ULP FSM Coprocessor counts pulses on an IO while main CPU is in deep sleep: :example:`system/ulp_fsm/ulp`. +* ULP FSM Coprocessor polls ADC in while main CPU is in deep sleep: :example:`system/ulp_fsm/ulp_adc`. + +API Reference +------------- + +.. include-build-file:: inc/ulp_fsm_common.inc +.. include-build-file:: inc/ulp_common.inc +.. include-build-file:: inc/ulp_common_defs.inc + +.. _binutils-esp32ulp toolchain: https://github.com/espressif/binutils-esp32ulp diff --git a/docs/en/api-reference/system/ulp_instruction_set.rst b/docs/en/api-reference/system/ulp_instruction_set.rst new file mode 100644 index 0000000000..6e193f876c --- /dev/null +++ b/docs/en/api-reference/system/ulp_instruction_set.rst @@ -0,0 +1,1262 @@ +{IDF_TARGET_NAME} ULP coprocessor instruction set +================================================= + +This document provides details about the instructions used by {IDF_TARGET_NAME} ULP FSM coprocessor assembler. + +ULP FSM 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 register 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. + +.. _ulp-fsm-addressing: + +Note about addressing +--------------------- +{IDF_TARGET_NAME} ULP FSM coprocessor's ``JUMP``, ``ST``, ``LD`` family of instructions expect the address argument to be expressed in the following way depending on the type of address argument used: + +- When the address argument is presented as a label then the instruction expects the address to be expressed as 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 ``R1`` to be expressed in 32-bit words. To account for this common use case, the assembler will convert the address of label `loop` from bytes to words, when generating the ``MOVE`` instruction. Hence, 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``. + + However, when an immediate value is used as an offset in ``LD`` and ``ST`` instructions, the assembler considers the address argument in bytes and converts it to 32-bit words before executing the instruction:: + + ST R1, R2, 4 // offset = 4 bytes; Mem[R2 + 4 / 4] = R1 + + In this case, the value in R1 is stored at the memory location pointed by [R2 + offset / 4] + + 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. + +.. only:: esp32s2 or esp32s3 + + Difference between ESP32 ULP and {IDF_TARGET_NAME} ULP Instruction sets + ----------------------------------------------------------------------- + + Compared to the ESP32 ULP FSM coprocessor, the {IDF_TARGET_NAME} ULP FSM coprocessor has an extended instruction set. The {IDF_TARGET_NAME} ULP FSM is not binary compatible with ESP32 ULP FSM, + but a ESP32 ULP FSM assembled program is expected to work on the {IDF_TARGET_NAME} ULP FSM after rebuilding. + The list of the new instructions that was added to the {IDF_TARGET_NAME} ULP FSM is: ``LDL``, ``LDH``, ``STL``, ``STH``, ``ST32``, ``STO``, ``STI``, ``STI32``. + + +The detailed description of all instructions is presented 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 the result in 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 a 16-bit signed value from a source register, and stores the 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 a logical AND of a source register and another source register or a 16-bit signed value and stores the 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 a logical OR of a source register and another source register or a 16-bit signed value and stores the 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 a logical shift to left of the source register by the number of bits from another source register or a 16-bit signed value and stores the 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 a logical shift to right of a source register by the number of bits from another source register or a 16-bit signed value and stores the 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 moves the value from the source register or a 16-bit signed value to the destination register. + +.. note:: + 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. See the section :ref:`ulp-fsm-addressing` for more details. + + +**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 + + +**ST** – Store data to the memory +--------------------------------- + +**Syntax** + **ST** *Rsrc, Rdst, offset* + +**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* – 13-bit signed value, offset in bytes + +**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. The upper half-word is written with the current program counter (PC) (expressed in words, shifted left by 5 bits) OR'd with Rdst (0..3):: + + Mem[Rdst + offset / 4]{31:0} = {PC[10:0], 3'b0, Rdst, Rsrc[15:0]} + + The application can use the higher 16 bits to determine which instruction in the ULP program has written any particular word into memory. + +.. note:: + Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section :ref:`ulp-fsm-addressing` for more details. + +**Examples**:: + + 1: ST R1, R2, 0x12 // MEM[R2 + 0x12 / 4] = 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 + ST R1, R2, offs // MEM[R2 + 0 / 4] = R1 + // MEM[Addr1 + 0] will be 32'h600001 + +.. only:: esp32s2 or esp32s3 + + **STL** – Store data to the lower 16 bits of 32-bit memory + ---------------------------------------------------------------- + + **Syntax** + **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 the memory with address [Rdst + offset / 4]:: + + Mem[Rdst + offset / 4]{15:0} = {Rsrc[15:0]} + Mem[Rdst + offset / 4]{15:0} = {Label[1:0],Rsrc[13:0]} + + The ``ST`` and the ``STL`` commands can be used interchangeably and have been provided to maintain backward compatibility with previous versions of the ULP core. + + .. note:: + Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section :ref:`ulp-fsm-addressing` for more details. + + **Examples**:: + + 1: STL R1, R2, 0x12 // MEM[R2 + 0x12 / 4] = 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 / 4] = R1 + // MEM[Addr1 + 0] will be 32'hxxxx0001 + 3: + MOVE R1, 1 // R1 = 1 + STL R1, R2, 0x12, 1 // MEM[R2 + 0x12 / 4] = 0xxxxx4001 + + + **STH** – Store data to the higher 16 bits of 32-bit 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 upper half-word of memory with address [Rdst + offset / 4]:: + + Mem[Rdst + offset / 4]{31:16} = {Rsrc[15:0]} + Mem[Rdst + offset / 4]{31:16} = {Label[1:0],Rsrc[13:0]} + + .. note:: + Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section :ref:`ulp-fsm-addressing` for more details. + + **Examples**:: + + 1: STH R1, R2, 0x12 // MEM[R2 + 0x12 / 4][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 / 4] = R1 + // MEM[Addr1 + 0] will be 32'h0001xxxx + 3: + MOVE R1, 1 // R1 = 1 + STH R1, R2, 0x12, 1 // MEM[R2 + 0x12 / 4] 0x4001xxxx + + + **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-bit memory with address [Rdst + offset / 4]:: + + Mem[Rdst + offset / 4]{31:0} = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + + .. note:: + Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section :ref:`ulp-fsm-addressing` for more details. + + **Examples**:: + + 1: ST32 R1, R2, 0x12, 0 // MEM[R2 + 0x12 / 4][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 + + + **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 sets the 16-bit value to the offset register:: + + offset = value / 4 + + .. note:: + Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section :ref:`ulp-fsm-addressing` for more details. + + **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 lower and upper half-word of memory with address [Rdst + offset / 4]. + The offset value is auto incremented when the STI instruction is called twice. Make sure to execute the ``STO`` instruction + to set the offset value before executing the STI instruction:: + + 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 4 // Set offset to 4 + STI R1, R2 // MEM[R2 + 4 / 4][15:0] = R1 + STI R1, R2 // MEM[R2 + 4 / 4][31:16] = R1 + // offset += (1 * 4) //offset is incremented by 1 word + STI R1, R2 // MEM[R2 + 8 / 4][15:0] = R1 + STI R1, R2 // MEM[R2 + 8 / 4][31:16] = R1 + + + **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-bit memory with address [Rdst + offset / 4]. + The offset value is auto incremented each time the STI32 instruction is called. Make sure to execute the ``STO`` instruction + to set the offset value before executing the STI32 instruction:: + + Mem[Rdst + offset / 4]{31:0} = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + + **Examples**:: + + 1: STO 0x12 + STI32 R1, R2, 0 // MEM[R2 + 0x12 / 4][31:0] = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + // offset += (1 * 4) //offset is incremented by 1 word + STI32 R1, R2, 0 // MEM[R2 + 0x16 / 4][31:0] = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]} + + +**LD** – Load data from the memory +---------------------------------- + +**Syntax** + **LD** *Rdst, Rsrc, offset* + +**Operands** + - *Rdst* – Register R[0..3], destination + - *Rsrc* – Register R[0..3], holds address of destination, in 32-bit words + - *Offset* – 13-bit signed value, offset in bytes + +**Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + +**Description** + The instruction loads the lower 16-bit half-word from memory with address [Rsrc + offset / 4] into the destination register Rdst:: + + Rdst[15:0] = Mem[Rsrc + offset / 4][15:0] + +.. note:: + Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section :ref:`ulp-fsm-addressing` for more details. + +**Examples**:: + + 1: LD R1, R2, 0x12 // R1 = MEM[R2 + 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 + MOVE R1, 1 // R1 = 1 + MOVE R2, Addr1 // R2 = Addr1 / 4 (address of label is converted into words) + LD R1, R2, offs // R1 = MEM[R2 + 0] + // R1 will be 123 + +.. only:: esp32s2 or esp32s3 + + **LDL** – Load data from the lower half-word of the 32-bit memory + ------------------------------------------------------------------ + + **Syntax** + **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* – 13-bit signed value, offset in bytes + + **Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + + **Description** + The instruction loads the lower 16-bit half-word from memory with address [Rsrc + offset / 4] into the destination register Rdst:: + + Rdst[15:0] = Mem[Rsrc + offset / 4][15:0] + + The ``LD`` and the ``LDL`` commands can be used interchangeably and have been provided to maintain backward compatibility with previous versions of the ULP core. + + .. note:: + Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section :ref:`ulp-fsm-addressing` for more details. + + **Examples**:: + + 1: LDL R1, R2, 0x12 // R1 = MEM[R2 + 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 + 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 upper half-word of the 32-bit 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* – 13-bit signed value, offset in bytes + + **Cycles** + 4 cycles to execute, 4 cycles to fetch next instruction + + **Description** + The instruction loads the upper 16-bit half-word from memory with address [Rsrc + offset / 4] into the destination register Rdst:: + + Rdst[15:0] = Mem[Rsrc + offset / 4][15:0] + + .. note:: + Note that the offset specified in bytes is converted to a 32-bit word offset before execution. See the section :ref:`ulp-fsm-addressing` for more details. + + **Examples**:: + + 1: LDH R1, R2, 0x12 // R1 = MEM[R2 + 0x12 / 4] + + 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 the stage count register by the 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 the stage count register by the given value. + +**Examples**:: + + 1: STAGE_DEC 10 // stage_cnt -= 10; + + 2: // Down counting loop example + 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 the 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 the ULP coprocessor to the 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. + + +.. only:: esp32 + + **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 + +.. only:: esp32 + + - *Mux* - Enable ADC channel. Channel number is [Mux-1]. If the user passes Mux value 1, then ADC channel 0 gets used. + +.. only:: esp32s2 or esp32s3 + + - *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 + +**Description** + The instruction makes measurements from ADC. + +**Examples**:: + +.. only:: esp32 + + 1: ADC R1, 0, 1 // Measure value using ADC1 channel 0 and store result into R1 + +.. only:: esp32s2 or esp32s3 + + 1: ADC R1, 0, 1 // Measure value using ADC1 pad 2 and store result into R1 + +.. only:: esp32 + + **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* – Register end bit number + - *Low* – Register start bit number + +**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]``. + +.. only:: esp32 + + This instruction can access registers in RTC_CNTL, RTC_IO, SENS, and RTC_I2C peripherals. Address of 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 + +.. only:: esp32s2 or esp32s3 + + This instruction can access registers in RTC_CNTL, RTC_IO, SENS, and RTC_I2C peripherals. Address of the register, as seen from the ULP, can be calculated from the address of the same register on the PeriBUS1 as follows:: + + addr_ulp = (addr_peribus1 - DR_REG_RTCCNTL_BASE) / 4 + +**Examples**:: + + 1: REG_RD 0x120, 7, 4 // 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* – Register end bit number + - *Low* – Register start bit number + - *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 an immediate data value into a peripheral register: ``REG[Addr][High:Low] = data``. + +.. only:: esp32 + + This instruction can access registers in RTC_CNTL, RTC_IO, SENS, and RTC_I2C peripherals. Address of 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 + +.. only:: esp32s2 or esp32s3 + + 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 PeriBUS1 as follows:: + + addr_ulp = (addr_peribus1 - 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/en/api-reference/system/ulp_macros.rst b/docs/en/api-reference/system/ulp_macros.rst new file mode 100644 index 0000000000..22a5b5eb2b --- /dev/null +++ b/docs/en/api-reference/system/ulp_macros.rst @@ -0,0 +1,58 @@ +Programming ULP FSM coprocessor using C macros (legacy) +======================================================= + +In addition to the existing binutils port for the {IDF_TARGET_NAME} ULP coprocessor, it is possible to generate programs for the ULP FSM coprocessor by embedding assembly-like macros into an {IDF_TARGET_NAME} application. Here is an example how this can be done:: + + const ulp_insn_t program[] = { + I_MOVI(R3, 16), // R3 <- 16 + I_LD(R0, R3, 0), // R0 <- RTC_SLOW_MEM[R3 + 0] + I_LD(R1, R3, 1), // R1 <- RTC_SLOW_MEM[R3 + 1] + I_ADDR(R2, R0, R1), // R2 <- R0 + R1 + I_ST(R2, R3, 2), // R2 -> RTC_SLOW_MEM[R2 + 2] + I_HALT() + }; + size_t load_addr = 0; + size_t size = sizeof(program)/sizeof(ulp_insn_t); + ulp_process_macros_and_load(load_addr, program, &size); + ulp_run(load_addr); + +The ``program`` array is an array of ``ulp_insn_t``, i.e. ULP coprocessor instructions. Each ``I_XXX`` preprocessor define translates into a single 32-bit instruction. Arguments of these preprocessor defines can be register numbers (``R0 — R3``) and literal constants. See the API reference section at the end of this guide for descriptions of instructions and arguments they take. + +.. note:: + + Because some of the instruction macros expand to inline function calls, defining such array in global scope will cause the compiler to produce an "initializer element is not constant" error. To fix this error, move the definition of instructions array into local scope. + +.. note:: + Load, store and move instructions use **addresses expressed in 32-bit words**. Address 0 corresponds to the first word of ``RTC_SLOW_MEM``. + This is different to how address arguments are handled in assembly code of the same instructions. See the section :ref:`ulp-fsm-addressing` for more details for reference. + +To generate branch instructions, special ``M_`` preprocessor defines are used. ``M_LABEL`` define can be used to define a branch target. Label identifier is a 16-bit integer. ``M_Bxxx`` defines can be used to generate branch instructions with target set to a particular label. + +Implementation note: these ``M_`` preprocessor defines will be translated into two ulp_insn_t values: one is a token value which contains label number, and the other is the actual instruction. ``ulp_process_macros_and_load`` function resolves the label number to the address, modifies the branch instruction to use the correct address, and removes the the extra ``ulp_insn_t`` token which contains the label numer. + +Here is an example of using labels and branches:: + + const ulp_insn_t program[] = { + I_MOVI(R0, 34), // R0 <- 34 + M_LABEL(1), // label_1 + I_MOVI(R1, 32), // R1 <- 32 + I_LD(R1, R1, 0), // R1 <- RTC_SLOW_MEM[R1] + I_MOVI(R2, 33), // R2 <- 33 + I_LD(R2, R2, 0), // R2 <- RTC_SLOW_MEM[R2] + I_SUBR(R3, R1, R2), // R3 <- R1 - R2 + I_ST(R3, R0, 0), // R3 -> RTC_SLOW_MEM[R0 + 0] + I_ADDI(R0, R0, 1), // R0++ + M_BL(1, 64), // if (R0 < 64) goto label_1 + I_HALT(), + }; + RTC_SLOW_MEM[32] = 42; + RTC_SLOW_MEM[33] = 18; + size_t load_addr = 0; + size_t size = sizeof(program)/sizeof(ulp_insn_t); + ulp_process_macros_and_load(load_addr, program, &size); + ulp_run(load_addr); + +API Reference +------------- + +.. include-build-file:: inc/ulp.inc diff --git a/docs/en/api-reference/template.rst b/docs/en/api-reference/template.rst index 4681d60387..a57cf8bb20 100644 --- a/docs/en/api-reference/template.rst +++ b/docs/en/api-reference/template.rst @@ -81,7 +81,7 @@ API Reference For example see :idf_file:`docs/en/api-reference/network/esp_wifi.rst` - 1. Optionally, rather that using ``*.inc`` files, you may want to describe API in you own way. See :idf_file:`docs/en/api-guides/ulp.rst` for example. + 1. Optionally, rather that using ``*.inc`` files, you may want to describe API in you own way. See :idf_file:`docs/en/api-reference/storage/fatfs.rst` for example. Below is the list of common ``.. doxygen...::`` directives: diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt index 741cbb48db..151e601a8c 100644 --- a/docs/page_redirects.txt +++ b/docs/page_redirects.txt @@ -57,7 +57,10 @@ get-started-cmake/get-started-pico-kit-v3 hw-reference/esp32/get-started-p api-guides/build-system-cmake api-guides/build-system api-guides/ulp-cmake api-guides/ulp api-guides/unit-tests-cmake api-guides/unit-tests -api-guides/ulps2_instruction_set.rst api-guides/ulp_extended_instruction_set.rst +api-guides/ulp_instruction_set.rst api-reference/system/ulp_instruction_set.rst +api-guides/ulps2_instruction_set.rst api-reference/system/ulp_instruction_set.rst +api-guides/ulp_macros.rst api-reference/system/ulp_macros.rst +api-guides/ulp-risc-v.rst api-reference/system/ulp-risc-v.rst api-reference/network/tcpip_adapter api-reference/network/esp_netif diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index abf3f84862..8aa4634995 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -36,11 +36,9 @@ API 指南 :SOC_SPIRAM_SUPPORTED: external-ram thread-local-storage tools/index - :SOC_ULP_SUPPORTED: ulp - :SOC_RISCV_COPROC_SUPPORTED: ulp-risc-v unit-tests linux-host-testing :SOC_USB_OTG_SUPPORTED: usb-otg-console :SOC_USB_SERIAL_JTAG_SUPPORTED: usb-serial-jtag-console :SOC_WIFI_SUPPORTED: wifi - :SOC_WIFI_SUPPORTED: wifi-security \ No newline at end of file + :SOC_WIFI_SUPPORTED: wifi-security diff --git a/docs/zh_CN/api-guides/memory-types.rst b/docs/zh_CN/api-guides/memory-types.rst index 5ff1f2c06d..782f4b2320 100644 --- a/docs/zh_CN/api-guides/memory-types.rst +++ b/docs/zh_CN/api-guides/memory-types.rst @@ -156,7 +156,7 @@ DROM（数据存储在 flash 中） RTC Slow memory（RTC 慢速存储器） ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - 从 RTC 存储器运行的代码中使用的全局和静态变量必须放入 RTC Slow memory 中。例如 :doc:`深度睡眠 ` 变量可以放在 RTC Slow memory 中，而不是 RTC FAST memory，或者也可以放入由 :doc:`/api-guides/ulp` 访问的代码和变量。 + 从 RTC 存储器运行的代码中使用的全局和静态变量必须放入 RTC Slow memory 中。例如 :doc:`深度睡眠 ` 变量可以放在 RTC Slow memory 中，而不是 RTC FAST memory，或者也可以放入由 :doc:`/api-reference/system/ulp` 访问的代码和变量。 ``RTC_NOINIT_ATTR`` 属性宏可以用来将数据放入 RTC Slow memory。放入此类型存储器的值从深度睡眠模式中醒来后会保持值不变。 diff --git a/docs/zh_CN/api-guides/ulp.rst b/docs/zh_CN/api-guides/ulp.rst deleted file mode 100644 index 9e861596b4..0000000000 --- a/docs/zh_CN/api-guides/ulp.rst +++ /dev/null @@ -1,177 +0,0 @@ -ULP 协处理器编程 -================ - -:link_to_translation:`en:[English]` - -.. toctree:: - :maxdepth: 1 - - :esp32: ESP32 ULP 指令集参考 - :esp32s2: ESP32-S2 ULP 指令集参考 - :esp32s3: ESP32-S3 ULP 指令集参考 - 使用宏进行编程（遗留） - - -ULP（Ultra Low Power 超低功耗）协处理器是一种简单的有限状态机 (FSM)，可以在主处理器处于深度睡眠模式时，使用 ADC、温度传感器和外部 I2C 传感器执行测量操作。ULP 协处理器可以访问 RTC_SLOW_MEM 内存区域及 RTC_CNTL、RTC_IO、SARADC 外设中的寄存器。ULP 协处理器使用 32 位固定宽度的指令，32 位内存寻址，配备 4 个 16 位通用寄存器。 - -安装工具链 ----------- - -ULP 协处理器代码是用汇编语言编写的，并使用 `binutils-esp32ulp 工具链`_ 进行编译。 - -如果你已经按照 :doc:`快速入门指南 <../../get-started/index>` 中的介绍安装好了 ESP-IDF 及其 CMake 构建系统，那么 ULP 工具链已经被默认安装到了你的开发环境中。 - -编译 ULP 代码 -------------- - -若需要将 ULP 代码编译为某组件的一部分，则必须执行以下步骤： - -1. 用汇编语言编写的 ULP 代码必须导入到一个或多个 `.S` 扩展文件中，且这些文件必须放在组件目录中一个独立的目录中，例如 `ulp/`。 - -.. note: 在注册组件（通过 ``idf_component_register``）时，不应将该目录添加到 ``SRC_DIRS`` 参数中。因为 ESP-IDF 构建系统将基于文件扩展名编译在 ``SRC_DIRS`` 中搜索到的文件。对于 ``.S`` 文件，使用的是 ``{IDF_TARGET_TOOLCHAIN_PREFIX}-as`` 汇编器。但这并不适用于 ULP 程序集文件，因此体现这种区别最简单的方式就是将 ULP 程序集文件放到单独的目录中。同样，ULP 程序集源文件也 **不应该** 添加到 ``SRCS`` 中。请参考如下步骤，查看如何正确添加 ULP 程序集源文件。 - -2. 注册后从组件 CMakeLists.txt 中调用 ``ulp_embed_binary`` 示例如下:: - - ... - idf_component_register() - - 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}") - -``ulp_embed_binary`` 的第一个参数为 ULP 二进制文件命名。指定的此名称也用于生成的其他文件，如：ELF 文件、.map 文件、头文件和链接器导出文件。第二个参数指定 ULP 程序集源文件。最后，第三个参数指定组件源文件列表，其中包括被生成的头文件。此列表用以建立正确的依赖项，并确保在编译这些文件之前先创建生成的头文件。有关 ULP 应用程序生成的头文件等相关概念，请参考下文。 - -3. 使用常规方法（例如 `idf.py app`）编译应用程序 - - 在内部，构建系统将按照以下步骤编译 ULP 程序： - - 1. **通过 C 预处理器运行每个程序集文件 (foo.S)。** 此步骤在组件编译目录中生成预处理的程序集文件 (foo.ulp.S)，同时生成依赖文件 (foo.ulp.d)。 - - 2. **通过汇编器运行预处理过的汇编源码。** 此步骤会生成目标文件 (foo.ulp.o) 和清单 (foo.ulp.lst)。清单文件仅用于调试，不用于编译进程的后续步骤。 - - 3. **通过 C 预处理器运行链接器脚本模板。** 模板位于 ``components/ulp/ld`` 目录中。 - - 4. **将目标文件链接到 ELF 输出文件** (``ulp_app_name.elf``)。此步骤生成的.map 文件 (``ulp_app_name.map``) 默认用于调试。 - - 5. **将 ELF 文件中的内容转储为二进制文件** (``ulp_app_name.bin``)，以便嵌入到应用程序中。 - - 6. 使用 ``esp32ulp-elf-nm`` 在 ELF 文件中 **生成全局符号列表** (``ulp_app_name.sym``)。 - - 7. **创建 LD 导出脚本和头文件** (``ulp_app_name.ld`` 和 ``ulp_app_name.h``)，包含来自 ``ulp_app_name.sym`` 的符号。此步骤可借助 ``esp32ulp_mapgen.py`` 工具来完成。 - - 8. **将生成的二进制文件添加到要嵌入应用程序的二进制文件列表中。** - -访问 ULP 程序变量 ------------------ - -在 ULP 程序中定义的全局符号也可以在主程序中使用。 - -例如，ULP 程序可以定义 ``measurement_count`` 变量，此变量可以定义程序从深度睡眠中唤醒芯片之前需要进行的 ADC 测量的次数:: - - .global measurement_count - measurement_count: .long 0 - - /* later, use measurement_count */ - move r3, measurement_count - ld r3, r3, 0 - -主程序需要在启动 ULP 程序之前初始化 ``measurement_count`` 变量，构建系统通过生成定义 ULP 编程中全局符号的 ``${ULP_APP_NAME}.h`` 和 ``${ULP_APP_NAME}.ld`` 文件实现上述操作。这些文件包含了在 ULP 程序中定义的所有全局符号，文件以 ``ulp_`` 开头。 - -头文件包含对此类符号的声明:: - - extern uint32_t ulp_measurement_count; - -注意，所有符号（包括变量、数组、函数）均被声明为 ``uint32_t``。对于函数和数组，先获取符号地址，然后转换为适当的类型。 - -生成的链接器脚本文件定义了 RTC_SLOW_MEM 中的符号位置:: - - PROVIDE ( ulp_measurement_count = 0x50000060 ); - -如果要从主程序访问 ULP 程序变量，应先使用 ``include`` 语句包含生成的头文件，这样，就可以像访问常规变量一样访问 ulp 程序变量。操作如下:: - - #include "ulp_app_name.h" - - // later - void init_ulp_vars() { - ulp_measurement_count = 64; - } - -注意，ULP 程序在 RTC 内存中只能使用 32 位字的低 16 位，因为寄存器是 16 位的，并且不具备从字的高位加载的指令。 - -同样，ULP 储存指令将寄存器值写入 32 位字的低 16 位中。高 16 位写入的值取决于储存指令的地址，因此在读取 ULP 写的变量时，主应用程序需要屏蔽高 16 位，例如:: - - printf("Last measurement value: %d\n", ulp_last_measurement & UINT16_MAX); - -启动 ULP 程序 -------------- - -要运行 ULP 程序，主应用程序需要调用 ``ulp_load_binary`` 函数将 ULP 程序加载到 RTC 内存中，然后调用 ``ulp_run`` 函数，启动 ULP 程序。 - -注意，在 menuconfig 中必须启用 "Enable Ultra Low Power (ULP) Coprocessor" 选项，以便为 ULP 预留内存。"RTC slow memory reserved for coprocessor" 选项设置的值必须足够储存 ULP 代码和数据。如果应用程序组件包含多个 ULP 程序，则 RTC 内存必须足以容纳最大的程序。 - -每个 ULP 程序均以二进制 BLOB 的形式嵌入到 ESP-IDF 应用程序中。应用程序可以引用此 BLOB，并以下面的方式加载此 BLOB（假设 ULP_APP_NAME 已被定义为 ``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 - -一旦上述程序加载到 RTC 内存后，应用程序即可启动此程序，并将入口点的地址传递给 ``ulp_run`` 函数:: - - ESP_ERROR_CHECK( ulp_run(&ulp_entry - RTC_SLOW_MEM) ); - -.. doxygenfunction:: ulp_run - -上述生成的头文件 ``${ULP_APP_NAME}.h`` 声明了入口点符号。在 ULP 应用程序的汇编源代码中，此符号必须标记为 ``.global``:: - - - .global entry - entry: - /* code starts here */ - -.. only:: esp32 - - ESP32 ULP 程序流 - ------------------ - - ESP32 ULP 协处理器由定时器启动，而调用 ``ulp_run`` 则可启动此定时器。定时器为 RTC_SLOW_CLK 的 Tick 事件计数（默认情况下，Tick 由内部 150 KHz RC 振荡器生成）。使用 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器 (x = 0..4) 设置 Tick 数值。第一次启动 ULP 时，使用 ``SENS_ULP_CP_SLEEP_CYC0_REG`` 设置定时器 Tick 数值，之后，ULP 程序可以使用 ``sleep`` 指令来选择另一个 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器。 - - 此应用程序可以调用 ``ulp_set_wakeup_period`` 函数来设置 ULP 定时器周期值 (SENS_ULP_CP_SLEEP_CYCx_REG, x = 0..4)。 - - .. doxygenfunction:: ulp_set_wakeup_period - - 一旦定时器计数到 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器设定的 Tick 数值，ULP 协处理器就会启动，并调用 ``ulp_run`` 的入口点开始运行程序。 - - 程序保持运行，直到遇到 ``halt`` 指令或非法指令。一旦程序停止，ULP 协处理器电源关闭，定时器再次启动。 - - 如果想禁用定时器（有效防止 ULP 程序再次运行），可在 ULP 代码或主程序中清除 ``RTC_CNTL_STATE0_REG`` 寄存器中的 ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` 位。 - - -.. only:: esp32s2 - - ESP32-S2 ULP 程序流 - -------------------- - - ESP32-S2 ULP 协处理器由定时器启动，调用 ``ulp_run`` 则可启动此定时器。定时器为 RTC_SLOW_CLK 的 Tick 事件计数（默认情况下，Tick 由内部 90 KHz RC 振荡器生成）。使用 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 寄存器设置 Tick 数值。 - - 此应用程序可以调用 ``ulp_set_wakeup_period`` 函数来设置 ULP 定时器周期值。 - - .. doxygenfunction:: ulp_set_wakeup_period - - 一旦定时器计数到 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 寄存器设定的 Tick 数值，ULP 协处理器就会启动，并调用 ``ulp_run`` 的入口点开始运行程序。 - - 程序保持运行，直到遇到 ``halt`` 指令或非法指令。一旦程序停止，ULP 协处理器电源关闭，定时器再次启动。 - - 如果想禁用定时器（有效防止 ULP 程序再次运行），可在 ULP 代码或主程序中清除 ``RTC_CNTL_STATE0_REG`` 寄存器中的 ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` 位。 - - -.. _binutils-esp32ulp 工具链: https://github.com/espressif/binutils-esp32ulp diff --git a/docs/zh_CN/api-guides/ulp_extended_instruction_set.rst b/docs/zh_CN/api-guides/ulp_extended_instruction_set.rst deleted file mode 100644 index fbc0190f39..0000000000 --- a/docs/zh_CN/api-guides/ulp_extended_instruction_set.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/api-guides/ulp_extended_instruction_set.rst diff --git a/docs/zh_CN/api-guides/ulp_instruction_set.rst b/docs/zh_CN/api-guides/ulp_instruction_set.rst deleted file mode 100644 index e36036d269..0000000000 --- a/docs/zh_CN/api-guides/ulp_instruction_set.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/api-guides/ulp_instruction_set.rst \ No newline at end of file diff --git a/docs/zh_CN/api-guides/ulp_macros.rst b/docs/zh_CN/api-guides/ulp_macros.rst deleted file mode 100644 index 408f1d6952..0000000000 --- a/docs/zh_CN/api-guides/ulp_macros.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../en/api-guides/ulp_macros.rst \ No newline at end of file diff --git a/docs/zh_CN/api-reference/system/index.rst b/docs/zh_CN/api-reference/system/index.rst index a8d71545ad..e4dbd0e78b 100644 --- a/docs/zh_CN/api-reference/system/index.rst +++ b/docs/zh_CN/api-reference/system/index.rst @@ -33,6 +33,8 @@ System API system_time :SOC_ASYNC_MEMCPY_SUPPORTED: async_memcpy :esp32: himem + :SOC_ULP_SUPPORTED: ulp + :SOC_RISCV_COPROC_SUPPORTED: ulp-risc-v wdts diff --git a/docs/zh_CN/api-guides/ulp-risc-v.rst b/docs/zh_CN/api-reference/system/ulp-risc-v.rst similarity index 53% rename from docs/zh_CN/api-guides/ulp-risc-v.rst rename to docs/zh_CN/api-reference/system/ulp-risc-v.rst index eebb2502b6..f3c2d2c09b 100644 --- a/docs/zh_CN/api-guides/ulp-risc-v.rst +++ b/docs/zh_CN/api-reference/system/ulp-risc-v.rst @@ -1,30 +1,26 @@ -ULP-RISC-V 协处理器编程 +ULP RISC-V 协处理器编程 ================================== :link_to_translation:`en:[English]` -.. toctree:: - :maxdepth: 1 +ULP RISC-V 协处理器是 ULP 的一种变体，用于 {IDF_TARGET_NAME}。与 ULP FSM 类似，ULP RISC-V 协处理器可以在主处理器处于低功耗模式时执行传感器读数等任务。其与 ULP FSM 的主要区别在于，ULP RISC-V 可以通过标准 GNU 工具使用 C 语言进行编程。ULP RISC-V 可以访问 RTC_SLOW_MEM 内存区域及 RTC_CNTL、RTC_IO、SARADC 等外设的寄存器。RISC-V 处理器是一种 32 位定点处理器，指令集基于 RV32IMC，包括硬件乘除法和压缩指令。 - -ULP-RISC-V 协处理器是 ULP 的一种变体，用于 ESP32-S2。与 ULP 类似，ULP-RISC-V 协处理器可以在主处理器处于低功耗模式时执行传感器读数等任务。与 ULP-FSM 的主要区别在于，ULP-RISC-V 可以使用标准 GNU 工具、以 C 语言进行编程。ULP-RISC-V 可以访问 RTC_SLOW_MEM 内存区域及 RTC_CNTL、RTC_IO、SARADC 等外设的寄存器。RISC-V 处理器是一种 32 位定点处理器，指令集基于 RV32IMC，包括硬件乘除法和压缩指令。 - -安装 ULP-RISC-V 工具链 +安装 ULP RISC-V 工具链 ----------------------------------- -ULP-RISC-V 协处理器代码以 C 语言编写（也可能是汇编语言），使用基于 GCC 的 RISC-V 工具链进行编译。 +ULP RISC-V 协处理器代码以 C 语言（或汇编语言）编写，使用基于 GCC 的 RISC-V 工具链进行编译。 -如果你已依照 :doc:`快速入门指南 <../../get-started/index>` 中的介绍安装好了 ESP-IDF 及其 CMake 构建系统，那么 ULP-RISC-V 工具链已经被默认安装到了你的开发环境中。 +如果您已依照 :doc:`快速入门指南 <../../../get-started/index>` 中的介绍安装好了 ESP-IDF 及其 CMake 构建系统，那么 ULP RISC-V 工具链已经被默认安装到了您的开发环境中。 .. note: 在早期版本的ESP-IDF中，RISC-V工具链具有不同的名称：`riscv-none-embed-gcc`。 -编译 ULP-RISC-V 代码 +编译 ULP RISC-V 代码 ----------------------------- -要将 ULP-RISC-V 代码编译为某组件的一部分，必须执行以下步骤： +要将 ULP RISC-V 代码编译为某组件的一部分，必须执行以下步骤： -1. ULP-RISC-V 代码以 C 语言或汇编语言编写（必须使用 `.S` 扩展名)，必须放在组件目录中一个独立的目录中，例如 `ulp/`。 +1. ULP RISC-V 代码以 C 语言或汇编语言编写（必须使用 `.S` 扩展名)，必须放在组件目录中一个独立的目录中，例如 `ulp/`。 -.. note: 当注册组件时（通过 ``idf_component_register``），该目录不应被添加至 ``SRC_DIRS`` 参数，因为目前 ULP-FSM 需要进行此步骤。如何正确添加 ULP 源文件，请见以下步骤。 +.. note: 当注册组件时（通过 ``idf_component_register``），该目录不应被添加至 ``SRC_DIRS`` 参数，因为目前该步骤需用于 ULP FSM。如何正确添加 ULP 源文件，请见以下步骤。 2. 注册后从组件 CMakeLists.txt 中调用 ``ulp_embed_binary`` 示例如下:: @@ -37,13 +33,9 @@ ULP-RISC-V 协处理器代码以 C 语言编写（也可能是汇编语言）， ulp_embed_binary(${ulp_app_name} "${ulp_sources}" "${ulp_exp_dep_srcs}") - ``ulp_embed_binary`` 的第一个参数指定生成的 ULP 二进制文件名。生成的其他文件， - 如 ELF 文件、.map 文件、头文件和链接器导出文件等也可使用此名称。第二个参数指定 ULP 源文件。 - 最后，第三个参数指定组件源文件列表，其中包括生成的头文件。 - 此列表用以正确构建依赖，并确保在构建过程中先生成后编译包含头文件的源文件。 - 请参考下文，查看为 ULP 应用程序生成的头文件等相关概念。 + ``ulp_embed_binary`` 的第一个参数指定生成的 ULP 二进制文件名。生成的其他文件，如 ELF 文件、.map 文件、头文件和链接器导出文件等也可使用此名称。第二个参数指定 ULP 源文件。最后，第三个参数指定组件源文件列表，其中包括生成的头文件。此列表用以正确构建依赖，并确保在构建过程中先生成后编译包含头文件的源文件。请参考下文，查看为 ULP 应用程序生成的头文件等相关概念。 -3. 使用常规方法（例如 `idf.py app`）编译应用程序 +3. 使用常规方法（例如 `idf.py app`）编译应用程序。 在内部，构建系统将按照以下步骤编译 ULP 程序： @@ -51,22 +43,22 @@ ULP-RISC-V 协处理器代码以 C 语言编写（也可能是汇编语言）， 2. **通过 C 预处理器运行链接器脚本模版。** 模版位于 ``components/ulp/ld`` 目录中。 - 4. **将目标文件链接到 ELF 输出文件** (``ulp_app_name.elf``)。此步骤生成的 .Map 文件默认用于调试 (``ulp_app_name.map``)。 + 3. **将目标文件链接到 ELF 输出文件** (``ulp_app_name.elf``)。此步骤生成的 .map 文件默认用于调试 (``ulp_app_name.map``)。 - 5. **将 ELF 文件中的内容转储为二进制文件** (``ulp_app_name.bin``)，以便嵌入到应用程序中。 + 4. **将 ELF 文件中的内容转储为二进制文件** (``ulp_app_name.bin``)，以便嵌入到应用程序中。 - 6. 使用 ``riscv32-esp-elf-nm`` 在 ELF 文件中 **生成全局符号列表** (``ulp_app_name.sym``)。 + 5. 使用 ``riscv32-esp-elf-nm`` 在 ELF 文件中 **生成全局符号列表** (``ulp_app_name.sym``)。 - 7. **创建 LD 导出脚本和头文件** （``ulp_app_name.ld`` 和 ``ulp_app_name.h``），包含来自 ``ulp_app_name.sym`` 的符号。此步骤可借助 ``esp32ulp_mapgen.py`` 工具来完成。 + 6. **创建 LD 导出脚本和头文件** （``ulp_app_name.ld`` 和 ``ulp_app_name.h``），包含来自 ``ulp_app_name.sym`` 的符号。此步骤可借助 ``esp32ulp_mapgen.py`` 工具来完成。 - 8. **将生成的二进制文件添加到要嵌入应用程序的二进制文件列表中。** + 7. **将生成的二进制文件添加到要嵌入应用程序的二进制文件列表中。** -访问 ULP-RISC-V 程序变量 +访问 ULP RISC-V 程序变量 ---------------------------- -在 ULP-RISC-V 程序中定义的全局符号也可以在主程序中使用。 +在 ULP RISC-V 程序中定义的全局符号也可以在主程序中使用。 -例如，ULP-RISC-V 程序可以定义 ``measurement_count`` 变量，此变量可以定义程序从深度睡眠中唤醒芯片之前需要进行的 ADC 测量的次数。 +例如，ULP RISC-V 程序可以定义 ``measurement_count`` 变量，此变量可以定义程序从深度睡眠中唤醒芯片之前需要进行的 ADC 测量的次数。 .. code-block:: c @@ -80,21 +72,21 @@ ULP-RISC-V 协处理器代码以 C 语言编写（也可能是汇编语言）， ...do something. } -构建系统生成定义 ULP 编程中全局符号的 ``${ULP_APP_NAME}.h`` 和 ``${ULP_APP_NAME}.ld`` 文件，使主程序能够访问全局 ULP-RISC-V 程序变量。上述两个文件包含 ULP 程序中定义的所有全局符号，且这些符号均以 ``ulp_`` 开头，。 +构建系统生成定义 ULP 编程中全局符号的 ``${ULP_APP_NAME}.h`` 和 ``${ULP_APP_NAME}.ld`` 文件，使主程序能够访问全局 ULP RISC-V 程序变量。上述两个文件包含 ULP RISC-V 程序中定义的所有全局符号，且这些符号均以 ``ulp_`` 开头。 -头文件包含对此类符号的声明 +头文件包含对此类符号的声明： .. code-block:: c extern uint32_t ulp_measurement_count; -注意，所有符号（包括变量、数组、函数）均被声明为 ``uint32_t``。 函数和数组需要先获取符号地址、再转换为适当的类型。 +注意，所有符号（包括变量、数组、函数）均被声明为 ``uint32_t``。函数和数组需要先获取符号地址，再转换为适当的类型。 生成的链接器文本定义了符号在 RTC_SLOW_MEM 中的位置:: PROVIDE ( ulp_measurement_count = 0x50000060 ); -要从主程序访问 ULP-RISC-V 程序变量，需使用 ``include`` 语句包含生成的头文件。这样，就可以像访问常规变量一样访问 ULP 程序变量。 +要从主程序访问 ULP RISC-V 程序变量，需使用 ``include`` 语句包含生成的头文件。这样，就可以像访问常规变量一样访问 ULP RISC-V 程序变量。 .. code-block:: c @@ -104,14 +96,14 @@ ULP-RISC-V 协处理器代码以 C 语言编写（也可能是汇编语言）， ulp_measurement_count = 64; } -启动 ULP-RISC-V 程序 +启动 ULP RISC-V 程序 ------------------------------- -要运行 ULP-RISC-V 程序，主程序需要调用 :cpp:func:`ulp_riscv_load_binary` 函数，将 ULP 程序加载到 RTC 内存中，然后调用 :cpp:func:`ulp_riscv_run` 函数，启动 ULP-RISC-V 程序。 +要运行 ULP RISC-V 程序，主程序需要调用 :cpp:func:`ulp_riscv_load_binary` 函数，将 ULP 程序加载到 RTC 内存中，然后调用 :cpp:func:`ulp_riscv_run` 函数，启动 ULP RISC-V 程序。 -注意，必须在 menuconfig 中启用 `CONFIG_ULP_COPROC_ENABLED` 和 `CONFIG_ULP_COPROC_TYPE_RISCV` 选项，以便为 ULP 预留内存。"RTC slow memory reserved for coprocessor" 选项设置的值必须足够存储 ULP 代码和数据。如果应用程序组件包含多个 ULP 程序，RTC 内存必须足以容纳最大的程序。 +注意，必须在 menuconfig 中启用 `CONFIG_ULP_COPROC_ENABLED` 和 `CONFIG_ULP_COPROC_TYPE_RISCV` 选项，以便正常运行 ULP RISC-V 程序。``RTC slow memory reserved for coprocessor`` 选项设置的值必须足够存储 ULP RISC-V 代码和数据。如果应用程序组件包含多个 ULP 程序，RTC 内存必须足以容纳最大的程序。 -每个 ULP-RISC-V 程序均以二进制 BLOB 的形式嵌入到 ESP-IDF 应用程序中。应用程序可以引用此 BLOB，并以下面的方式加载此 BLOB（假设 ULP_APP_NAME 已被定义为 ``ulp_app_name``）： +每个 ULP RISC-V 程序均以二进制 BLOB 的形式嵌入到 ESP-IDF 应用程序中。应用程序可以引用此 BLOB，并以下面的方式加载此 BLOB（假设 ULP_APP_NAME 已被定义为 ``ulp_app_name``）： .. code-block:: c @@ -123,26 +115,34 @@ ULP-RISC-V 协处理器代码以 C 语言编写（也可能是汇编语言）， (bin_end - bin_start)) ); } -.. doxygenfunction:: ulp_riscv_load_binary() - 一旦上述程序加载到 RTC 内存后，应用程序即可调用 :cpp:func:`ulp_riscv_run` 函数启动此程序： .. code-block:: c ESP_ERROR_CHECK( ulp_riscv_run() ); -.. doxygenfunction:: ulp_riscv_run() - -ULP-RISC-V 程序流 +ULP RISC-V 程序流 ----------------------- -ULP-RISC-V 协处理器由定时器启动，调用 :cpp:func:`ulp_riscv_run` 即可启动定时器。定时器为 RTC_SLOW_CLK 的 Tick 事件计数（默认情况下，Tick 由内部 90 kHz RC 振荡器产生）。Tick 数值使用 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 寄存器设置。启用 ULP 时，使用 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 设置定时器 Tick 数值。 +{IDF_TARGET_RTC_CLK_FRE:default="150kHz", esp32s2="90kHz", esp32s3="136kHz"} + +ULP RISC-V 协处理器由定时器启动，调用 :cpp:func:`ulp_riscv_run` 即可启动定时器。定时器为 RTC_SLOW_CLK 的 Tick 事件计数（默认情况下，Tick 由内部 90 kHz RC 振荡器产生）。Tick 数值使用 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 寄存器设置。启用 ULP 时，使用 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 设置定时器 Tick 数值。 此应用程序可以调用 :cpp:func:`ulp_set_wakeup_period` 函数来设置 ULP 定时器周期值 (RTC_CNTL_ULP_CP_TIMER_1_REG)。 -一旦定时器数到 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 寄存器中设置的 Tick 数，ULP 协处理器就会启动，并调用 :cpp:func:`ulp_riscv_run` 的入口点开始运行程序。 +一旦定时器数到 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 寄存器中设置的 Tick 数，ULP RISC-V 协处理器就会启动，并调用 :cpp:func:`ulp_riscv_run` 的入口点开始运行程序。 -程序保持运行，直至 ``RTC_CNTL_COCPU_CTRL_REG`` 寄存器中的 ``RTC_CNTL_COCPU_DONE`` 字段被置位或因非法处理器状态出现陷阱。一旦程序停止，ULP 协处理器会关闭电源，定时器再次启动。 +程序保持运行，直至 ``RTC_CNTL_COCPU_CTRL_REG`` 寄存器中的 ``RTC_CNTL_COCPU_DONE`` 字段被置位或因非法处理器状态出现陷阱。一旦程序停止，ULP RISC-V 协处理器会关闭电源，定时器再次启动。 如需禁用定时器（有效防止 ULP 程序再次运行），请清除 ``RTC_CNTL_STATE0_REG`` 寄存器中的 ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` 位，此项操作可在 ULP 代码或主程序中进行。 +应用示例 +-------------------- + +* 主处理器处于 Deep-sleep 状态时，ULP RISC-V 协处理器轮询 GPIO：:example:`system/ulp_riscv/gpio`。 +* 主处理器处于 Deep-sleep 状态时，ULP RISC-V 协处理器读取外部温度传感器：:example:`system/ulp_riscv/ds18b20_onewire`。 + +API 参考 +------------- + +.. include-build-file:: inc/ulp_riscv.inc diff --git a/docs/zh_CN/api-reference/system/ulp.rst b/docs/zh_CN/api-reference/system/ulp.rst new file mode 100644 index 0000000000..36ef43741f --- /dev/null +++ b/docs/zh_CN/api-reference/system/ulp.rst @@ -0,0 +1,187 @@ +ULP 协处理器编程 +================ + +:link_to_translation:`en:[English]` + +ULP（Ultra Low Power，超低功耗）协处理器是一种简单的有限状态机 (FSM)，可以在主处理器处于深度睡眠模式时，使用 ADC、温度传感器和外部 I2C 传感器执行测量操作。ULP 协处理器可以访问 RTC_SLOW_MEM 内存区域及 RTC_CNTL、RTC_IO、SARADC 外设中的寄存器。ULP 协处理器使用 32 位固定宽度的指令，32 位内存寻址，配备 4 个 16 位通用寄存器。在 ESP-IDF 项目中，此协处理器被称作 `ULP FSM`。 + +.. only:: esp32s2 or esp32s3 + + {IDF_TARGET_NAME} 基于 RISC-V 指令集架构提供另一种 ULP 协处理器。关于 `ULP RISC-V` 的详细信息，请参考 :doc:`ULP-RISC-V Coprocessor <../../../api-reference/system/ulp-risc-v>`。 + +安装工具链 +---------- + +ULP FSM 协处理器代码由汇编语言编写，使用 `binutils-esp32ulp 工具链`_ 进行编译。 + +如果您已经按照 :doc:`快速入门指南 <../../../get-started/index>` 中的介绍安装好了 ESP-IDF 及其 CMake 构建系统，那么 ULP 工具链已经被默认安装到了您的开发环境中。 + +编写 ULP FSM +------------------- + +使用受支持的指令集即可编写 ULP FSM 协处理器，此外也可使用主处理器上的 C 语言宏进行编程。以下小节分别介绍了这两种方法： + +.. toctree:: + :maxdepth: 1 + + {IDF_TARGET_NAME} ULP 指令集参考 + 使用宏进行编程（遗留） + +编译 ULP 代码 +-------------- + +若需要将 ULP FSM 代码编译为某组件的一部分，则必须执行以下步骤： + +1. 用汇编语言编写的 ULP FSM 代码必须导入到一个或多个 `.S` 扩展文件中，且这些文件必须放在组件目录中一个独立的目录中，例如 `ulp/`。 + +.. note: 在注册组件（通过 ``idf_component_register``）时，不应将该目录添加到 ``SRC_DIRS`` 参数中。因为 ESP-IDF 构建系统将基于文件扩展名编译在 ``SRC_DIRS`` 中搜索到的文件。对于 ``.S`` 文件，使用的是 ``{IDF_TARGET_TOOLCHAIN_PREFIX}-as`` 汇编器。但这并不适用于 ULP FSM 程序集文件，因此体现这种区别最简单的方式就是将 ULP FSM 程序集文件放到单独的目录中。同样，ULP FSM 程序集源文件也 **不应该** 添加到 ``SRCS`` 中。请参考如下步骤，查看如何正确添加 ULP FSM 程序集源文件。 + +2. 注册后从组件 CMakeLists.txt 中调用 ``ulp_embed_binary`` 示例如下:: + + ... + idf_component_register() + + 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}") + +``ulp_embed_binary`` 的第一个参数为 ULP 二进制文件命名。指定的此名称也用于生成的其他文件，如：ELF 文件、.map 文件、头文件和链接器导出文件。第二个参数指定 ULP FSM 程序集源文件。最后，第三个参数指定组件源文件列表，其中包括被生成的头文件。此列表用以建立正确的依赖项，并确保在编译这些文件之前先创建生成的头文件。有关 ULP FSM 应用程序生成的头文件等相关概念，请参考下文。 + +3. 使用常规方法（例如 `idf.py app`）编译应用程序。 + + 在内部，构建系统将按照以下步骤编译 ULP FSM 程序： + + 1. **通过 C 预处理器运行每个程序集文件 (foo.S)。** 此步骤在组件编译目录中生成预处理的程序集文件 (foo.ulp.S)，同时生成依赖文件 (foo.ulp.d)。 + + 2. **通过汇编器运行预处理过的汇编源码。** 此步骤会生成目标文件 (foo.ulp.o) 和清单 (foo.ulp.lst)。清单文件仅用于调试，不用于编译进程的后续步骤。 + + 3. **通过 C 预处理器运行链接器脚本模板。** 模板位于 ``components/ulp/ld`` 目录中。 + + 4. **将目标文件链接到 ELF 输出文件** (``ulp_app_name.elf``)。此步骤生成的 .map 文件 (``ulp_app_name.map``) 默认用于调试。 + + 5. **将 ELF 文件中的内容转储为二进制文件** (``ulp_app_name.bin``)，以便嵌入到应用程序中。 + + 6. 使用 ``esp32ulp-elf-nm`` 在 ELF 文件中 **生成全局符号列表** (``ulp_app_name.sym``)。 + + 7. **创建 LD 导出脚本和头文件** (``ulp_app_name.ld`` 和 ``ulp_app_name.h``)，包含来自 ``ulp_app_name.sym`` 的符号。此步骤可借助 ``esp32ulp_mapgen.py`` 工具来完成。 + + 8. **将生成的二进制文件添加到要嵌入应用程序的二进制文件列表中。** + +访问 ULP FSM 程序变量 +------------------------ + +在 ULP FSM 程序中定义的全局符号也可以在主程序中使用。 + +例如，ULP FSM 程序可以定义 ``measurement_count`` 变量，此变量可以定义程序从深度睡眠中唤醒芯片之前需要进行的 ADC 测量的次数:: + + .global measurement_count + measurement_count: .long 0 + + // later, use measurement_count + move r3, measurement_count + ld r3, r3, 0 + +主程序需要在启动 ULP 程序之前初始化 ``measurement_count`` 变量，构建系统通过生成定义 ULP 编程中全局符号的 ``${ULP_APP_NAME}.h`` 和 ``${ULP_APP_NAME}.ld`` 文件实现上述操作。这些文件包含了在 ULP 程序中定义的所有全局符号，文件以 ``ulp_`` 开头。 + +头文件包含对此类符号的声明:: + + extern uint32_t ulp_measurement_count; + +注意，所有符号（包括变量、数组、函数）均被声明为 ``uint32_t``。对于函数和数组，先获取符号地址，然后转换为适当的类型。 + +生成的链接器脚本文件定义了 RTC_SLOW_MEM 中的符号位置:: + + PROVIDE ( ulp_measurement_count = 0x50000060 ); + +如果要从主程序访问 ULP 程序变量，应先使用 ``include`` 语句包含生成的头文件，这样，就可以像访问常规变量一样访问 ulp 程序变量。操作如下:: + + #include "ulp_app_name.h" + + // later + void init_ulp_vars() { + ulp_measurement_count = 64; + } + +.. only:: esp32 + + 注意，ULP FSM 程序在 RTC 内存中只能使用 32 位字的低 16 位，因为寄存器是 16 位的，并且不具备从字的高位加载的指令。同样，ULP 储存指令将寄存器值写入 32 位字的低 16 位中。高 16 位写入的值取决于储存指令的地址，因此在读取 ULP 协处理器写的变量时，主应用程序需要屏蔽高 16 位，例如:: + + printf("Last measurement value: %d\n", ulp_last_measurement & UINT16_MAX); + +启动 ULP FSM 程序 +-------------------- + +要运行 ULP FSM 程序，主应用程序需要调用 :cpp:func:`ulp_load_binary` 函数将 ULP 程序加载到 RTC 内存中，然后调用 :cpp:func:`ulp_run` 函数，启动 ULP 程序。 + +注意，在 menuconfig 中必须启用 ``Enable Ultra Low Power (ULP) Coprocessor`` 选项，以便正常运行 ULP，并且必须设置 ``ULP Co-processor type`` 选项，以便选择要使用的 ULP 类型。 ``RTC slow memory reserved for coprocessor`` 选项设置的值必须足够储存 ULP 代码和数据。如果应用程序组件包含多个 ULP 程序，则 RTC 内存必须足以容纳最大的程序。 + +每个 ULP 程序均以二进制 BLOB 的形式嵌入到 ESP-IDF 应用程序中。应用程序可以引用此 BLOB，并以下面的方式加载此 BLOB（假设 ULP_APP_NAME 已被定义为 ``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)) ); + } + +一旦上述程序加载到 RTC 内存后，应用程序即可启动此程序，并将入口点的地址传递给 ``ulp_run`` 函数:: + + ESP_ERROR_CHECK( ulp_run(&ulp_entry - RTC_SLOW_MEM) ); + +上述生成的头文件 ``${ULP_APP_NAME}.h`` 声明了入口点符号。在 ULP 应用程序的汇编源代码中，此符号必须标记为 ``.global``:: + + + .global entry + entry: + // code starts here + +.. only:: esp32 + + ESP32 ULP 程序流 + ------------------- + + ESP32 ULP 协处理器由定时器启动，而调用 :cpp:func:`ulp_run` 则可启动此定时器。定时器为 RTC_SLOW_CLK 的 Tick 事件计数（默认情况下，Tick 由内部 150 KHz RC 振荡器生成）。使用 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器 (x = 0..4) 设置 Tick 数值。第一次启动 ULP 时，使用 ``SENS_ULP_CP_SLEEP_CYC0_REG`` 设置定时器 Tick 数值，之后，ULP 程序可以使用 ``sleep`` 指令来选择另一个 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器。 + + 此应用程序可以调用 ``ulp_set_wakeup_period`` 函数来设置 ULP 定时器周期值 (SENS_ULP_CP_SLEEP_CYCx_REG, x = 0..4)。 + + 一旦定时器计数到 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器设定的 Tick 数值，ULP 协处理器就会启动，并调用 :cpp:func:`ulp_run` 的入口点开始运行程序。 + + 程序保持运行，直到遇到 ``halt`` 指令或非法指令。一旦程序停止，ULP 协处理器电源关闭，定时器再次启动。 + + 如果想禁用定时器（有效防止 ULP 程序再次运行），可在 ULP 代码或主程序中清除 ``RTC_CNTL_STATE0_REG`` 寄存器中的 ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` 位。 + + +.. only:: esp32s2 or esp32s3 + + {IDF_TARGET_NAME} ULP 程序流 + ---------------------------- + + {IDF_TARGET_NAME} ULP 协处理器由定时器启动，调用 :cpp:func:`ulp_run` 则可启动此定时器。定时器为 RTC_SLOW_CLK 的 Tick 事件计数（默认情况下，Tick 由内部 90 KHz RC 振荡器生成）。使用 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 寄存器设置 Tick 数值。 + + 此应用程序可以调用 :cpp:func:`ulp_set_wakeup_period` 函数来设置 ULP 定时器周期值。 + + 一旦定时器计数到 ``RTC_CNTL_ULP_CP_TIMER_1_REG`` 寄存器设定的 Tick 数值，ULP 协处理器就会启动，并调用 :cpp:func:`ulp_run` 的入口点开始运行程序。 + + 程序保持运行，直到遇到 ``halt`` 指令或非法指令。一旦程序停止，ULP 协处理器电源关闭，定时器再次启动。 + + 如果想禁用定时器（有效防止 ULP 程序再次运行），可在 ULP 代码或主程序中清除 ``RTC_CNTL_ULP_CP_TIMER_REG`` 寄存器中的 ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` 位。 + +应用示例 +-------------------- + +* 主处理器处于 Deep-sleep 状态时，ULP FSM 协处理器对 IO 脉冲进行计数：:example:`system/ulp_fsm/ulp`。 +* 主处理器处于 Deep-sleep 状态时，ULP FSM 协处理器轮询 ADC：:example:`system/ulp_fsm/ulp_adc`。 + +API 参考 +------------- + +.. include-build-file:: inc/ulp_fsm_common.inc +.. include-build-file:: inc/ulp_common.inc +.. include-build-file:: inc/ulp_common_defs.inc + +.. _binutils-esp32ulp 工具链: https://github.com/espressif/binutils-esp32ulp diff --git a/docs/zh_CN/api-reference/system/ulp_instruction_set.rst b/docs/zh_CN/api-reference/system/ulp_instruction_set.rst new file mode 100644 index 0000000000..22fce38505 --- /dev/null +++ b/docs/zh_CN/api-reference/system/ulp_instruction_set.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/system/ulp_instruction_set.rst diff --git a/docs/zh_CN/api-reference/system/ulp_macros.rst b/docs/zh_CN/api-reference/system/ulp_macros.rst new file mode 100644 index 0000000000..e1ae5e2828 --- /dev/null +++ b/docs/zh_CN/api-reference/system/ulp_macros.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/system/ulp_macros.rst