esp-idf/components/ulp
Michael (XIAO Xufeng) 562af8f65e global: move the soc component out of the common list
This MR removes the common dependency from every IDF components to the SOC component.

Currently, in the ``idf_functions.cmake`` script, we include the header path of SOC component by default for all components.
But for better code organization (or maybe also benifits to the compiling speed), we may remove the dependency to SOC components for most components except the driver and kernel related components.

In CMAKE, we have two kinds of header visibilities (set by include path visibility):

(Assume component A --(depends on)--> B, B is the current component)

1. public (``COMPONENT_ADD_INCLUDEDIRS``): means this path is visible to other depending components (A) (visible to A and B)
2. private (``COMPONENT_PRIV_INCLUDEDIRS``): means this path is only visible to source files inside the component (visible to B only)

and we have two kinds of depending ways:

(Assume component A --(depends on)--> B --(depends on)--> C, B is the current component)

1. public (```COMPONENT_REQUIRES```): means B can access to public include path of C. All other components rely on you (A) will also be available for the public headers. (visible to A, B)
2. private (``COMPONENT_PRIV_REQUIRES``): means B can access to public include path of C, but don't propagate this relation to other components (A). (visible to B)

1. remove the common requirement in ``idf_functions.cmake``, this makes the SOC components invisible to all other components by default.
2. if a component (for example, DRIVER) really needs the dependency to SOC, add a private dependency to SOC for it.
3. some other components that don't really depends on the SOC may still meet some errors saying "can't find header soc/...", this is because it's depended component (DRIVER) incorrectly include the header of SOC in its public headers. Moving all this kind of #include into source files, or private headers
4. Fix the include requirements for some file which miss sufficient #include directives. (Previously they include some headers by the long long long header include link)

This is a breaking change. Previous code may depends on the long include chain.
You may need to include the following headers for some files after this commit:

- soc/soc.h
- soc/soc_memory_layout.h
- driver/gpio.h
- esp_sleep.h

The major broken include chain includes:

1. esp_system.h no longer includes esp_sleep.h. The latter includes driver/gpio.h and driver/touch_pad.h.
2. ets_sys.h no longer includes soc/soc.h
3. freertos/portmacro.h no longer includes soc/soc_memory_layout.h

some peripheral headers no longer includes their hw related headers, e.g. rom/gpio.h no longer includes soc/gpio_pins.h and soc/gpio_reg.h

BREAKING CHANGE
2019-04-16 13:21:15 +08:00
..
cmake
include/esp32
ld
test
CMakeLists.txt
Makefile.projbuild
README.rst
component.mk
component_ulp_common.cmake
component_ulp_common.mk
esp32ulp_mapgen.py
toolchain_ulp_version.mk
ulp.c
ulp_macro.c

README.rst

Programming ULP coprocessor using C macros
==========================================

In addition to the existing binutils port for the ESP32 ULP coprocessor, it is possible to generate programs for the ULP by embedding assembly-like macros into an ESP32 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);


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
.. doxygendefine:: I_LD
.. doxygendefine:: I_WR_REG
.. doxygendefine:: I_RD_REG
.. doxygendefine:: I_BL
.. doxygendefine:: I_BGE
.. 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
.. doxygendefine:: M_BGE
.. doxygendefine:: M_BX
.. doxygendefine:: M_BXZ
.. doxygendefine:: M_BXF

Defines
^^^^^^^

.. doxygendefine:: RTC_SLOW_MEM