cmake: add ulp components build support

This commit is contained in:
Renz Christian Bagaporo 2018-09-13 14:54:59 +08:00 committed by Angus Gratton
parent 62c3218981
commit 946f55db85
15 changed files with 384 additions and 7 deletions

View file

@ -0,0 +1,78 @@
cmake_minimum_required(VERSION 3.5)
include(${IDF_PATH}/tools/cmake/utilities.cmake)
project(${ULP_APP_NAME} ASM C)
set(ULP_MAP_GEN ${IDF_PATH}/components/ulp/esp32ulp_mapgen.py)
set(ULP_LD_TEMPLATE ${IDF_PATH}/components/ulp/ld/esp32.ulp.ld)
get_filename_component(sdkconfig_dir ${SDKCONFIG} DIRECTORY)
foreach(include ${COMPONENT_INCLUDES})
list(APPEND component_includes -I${include})
endforeach()
list(APPEND ULP_PREPROCESSOR_ARGS ${component_includes})
list(APPEND ULP_PREPROCESSOR_ARGS -I${COMPONENT_PATH})
list(APPEND ULP_PREPROCESSOR_ARGS -I${sdkconfig_dir})
include_directories(${component_includes})
list(APPEND ULP_PREPROCESSOR_ARGS -D__ASSEMBLER__)
# Preprocess linker script, pre-linking
get_filename_component(ULP_LD_SCRIPT ${ULP_LD_TEMPLATE} NAME)
add_custom_command( OUTPUT ${ULP_LD_SCRIPT}
COMMAND ${CMAKE_C_COMPILER} -E -P -xc -o ${ULP_LD_SCRIPT} ${ULP_PREPROCESSOR_ARGS} ${ULP_LD_TEMPLATE}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS ${ULP_LD_TEMPLATE}
VERBATIM)
add_custom_target(${ULP_APP_NAME}_ld_script
DEPENDS ${ULP_LD_SCRIPT}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
foreach(ulp_s_source ${ULP_S_SOURCES})
get_filename_component(ulp_ps_source ${ulp_s_source} NAME_WE)
set(ulp_ps_output ${CMAKE_CURRENT_BINARY_DIR}/${ulp_ps_source}.ulp.S)
# Generate preprocessed assembly files.
add_custom_command( OUTPUT ${ulp_ps_output}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMAND ${CMAKE_C_COMPILER} -E -P -xc ${ULP_PREPROCESSOR_ARGS} -o ${ulp_ps_output} ${ulp_s_source}
DEPENDS ${ulp_s_source} ${ULP_LD_SCRIPT}
VERBATIM)
# During assembly file compilation, output listing files as well.
set_source_files_properties(${ulp_ps_output}
PROPERTIES COMPILE_FLAGS
"-al=${CMAKE_CURRENT_BINARY_DIR}/${ulp_ps_source}.lst")
list(APPEND ULP_PS_SOURCES ${ulp_ps_output})
endforeach()
# Create an executable
add_executable(${ULP_APP_NAME} ${ULP_PS_SOURCES})
# Dump the list of global symbols in a convenient format
add_custom_command( OUTPUT ${ULP_APP_NAME}.sym
COMMAND ${CMAKE_NM} -g -f posix $<TARGET_FILE:${ULP_APP_NAME}> > ${ULP_APP_NAME}.sym
DEPENDS ${ULP_APP_NAME}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
# Dump the binary for inclusion into the project
add_custom_command( OUTPUT ${ULP_APP_NAME}.bin
COMMAND ${CMAKE_OBJCOPY} -O binary $<TARGET_FILE:${ULP_APP_NAME}> ${ULP_APP_NAME}.bin
DEPENDS ${ULP_APP_NAME}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
add_custom_command( OUTPUT ${ULP_APP_NAME}.ld ${ULP_APP_NAME}.h
COMMAND ${ULP_MAP_GEN} -s ${ULP_APP_NAME}.sym -o ${ULP_APP_NAME}
DEPENDS ${ULP_APP_NAME}.sym
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
# Building the component separately from the project should result in
# ULP files being built.
add_custom_target(build
DEPENDS ${ULP_APP_NAME} ${ULP_APP_NAME}.bin ${ULP_APP_NAME}.sym
${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME}.ld
${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME}.h
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
target_link_libraries(${ULP_APP_NAME} -T${CMAKE_CURRENT_BINARY_DIR}/${ULP_LD_SCRIPT} -Map=${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME}.map)

View file

@ -0,0 +1,15 @@
# CMake toolchain file for ULP
set(CMAKE_SYSTEM_NAME Generic)
# Compiler is only used for preprocessing
set(CMAKE_C_COMPILER "xtensa-esp32-elf-gcc")
set(CMAKE_ASM_COMPILER "esp32ulp-elf-as")
set(CMAKE_LINKER "esp32ulp-elf-ld")
set(CMAKE_ASM${ASM_DIALECT}_COMPILE_OBJECT "${CMAKE_ASM${ASM_DIALECT}_COMPILER} \
<DEFINES> <INCLUDES> -o <OBJECT> -c <SOURCE>")
set(CMAKE_EXE_LINKER_FLAGS "-A elf32-esp32ulp -nostdlib" CACHE STRING "ULP Linker Base Flags")
set(CMAKE_ASM_LINK_EXECUTABLE "${CMAKE_LINKER} <FLAGS> <CMAKE_ASM_LINK_FLAGS> \
<LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>")

View file

@ -0,0 +1,52 @@
if(NOT CMAKE_BUILD_EARLY_EXPANSION)
spaces2list(ULP_S_SOURCES)
foreach(ulp_s_source ${ULP_S_SOURCES})
get_filename_component(ulp_s_source ${ulp_s_source} ABSOLUTE)
list(APPEND ulp_s_sources ${ulp_s_source})
endforeach()
foreach(ulp_s_source ${ulp_s_sources})
get_filename_component(ulp_ps_source ${ulp_s_source} NAME_WE)
set(ulp_ps_output ${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME}/${ulp_ps_source}.ulp.S)
list(APPEND ulp_ps_sources ${ulp_ps_output})
endforeach()
set(ulp_artifacts_prefix ${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME}/${ULP_APP_NAME})
set(ulp_artifacts ${ulp_artifacts_prefix}.bin
${ulp_artifacts_prefix}.ld
${ulp_artifacts_prefix}.h)
set(ulp_artifacts_extras ${ulp_artifacts_prefix}.map
${ulp_artifacts_prefix}.sym
${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME}/esp32.ulp.ld)
externalproject_add(${ULP_APP_NAME}
SOURCE_DIR ${IDF_PATH}/components/ulp/cmake
BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME}
INSTALL_COMMAND ""
CMAKE_ARGS -DCMAKE_GENERATOR=${CMAKE_GENERATOR}
-DCMAKE_TOOLCHAIN_FILE=${IDF_PATH}/components/ulp/cmake/toolchain-ulp.cmake
-DULP_S_SOURCES=${ulp_s_sources} -DULP_APP_NAME=${ULP_APP_NAME}
-DCOMPONENT_PATH=${COMPONENT_PATH}
-DCOMPONENT_INCLUDES=$<TARGET_PROPERTY:${COMPONENT_NAME},INTERFACE_INCLUDE_DIRECTORIES>
-DIDF_PATH=${IDF_PATH}
-DSDKCONFIG=${SDKCONFIG_HEADER}
BUILD_COMMAND ${CMAKE_COMMAND} --build ${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME} --target build
BUILD_BYPRODUCTS ${ulp_artifacts} ${ulp_artifacts_extras} ${ulp_ps_sources}
${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME}/${ULP_APP_NAME}
BUILD_ALWAYS 1
)
spaces2list(ULP_EXP_DEP_SRCS)
set_source_files_properties(${ULP_EXP_DEP_SRCS} PROPERTIES OBJECT_DEPENDS ${ulp_artifacts})
include_directories(${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME})
add_custom_target(${ULP_APP_NAME}_artifacts DEPENDS ${ULP_APP_NAME})
add_dependencies(${COMPONENT_NAME} ${ULP_APP_NAME}_artifacts)
target_linker_script(${COMPONENT_NAME} ${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME}/${ULP_APP_NAME}.ld)
target_add_binary_data(${COMPONENT_NAME} ${CMAKE_CURRENT_BINARY_DIR}/${ULP_APP_NAME}/${ULP_APP_NAME}.bin BINARY)
endif()

View file

@ -20,6 +20,7 @@ API Guides
Partition Tables <partition-tables>
Secure Boot <../security/secure-boot>
ULP Coprocessor <ulp>
ULP Coprocessor (CMake) <ulp-cmake>
Unit Testing <unit-tests>
Application Level Tracing <app_trace>
Console Component <console>

View file

@ -0,0 +1,166 @@
ULP coprocessor programming (CMake)
===================================
.. toctree::
:maxdepth: 1
Instruction set reference <ulp_instruction_set>
Programming using macros (legacy) <ulp_macros>
ULP (Ultra Low Power) coprocessor is a simple FSM which is designed to perform measurements using ADC, temperature sensor, and external I2C sensors, while main processors are in deep sleep mode. ULP coprocessor can access RTC_SLOW_MEM memory region, and registers in RTC_CNTL, RTC_IO, and SARADC peripherals. ULP coprocessor uses fixed-width 32-bit instructions, 32-bit memory addressing, and has 4 general purpose 16-bit registers.
Installing the toolchain
------------------------
ULP coprocessor code is written in assembly and compiled using the `binutils-esp32ulp toolchain`_.
1. Download pre-built binaries of the latest toolchain release from:
https://github.com/espressif/binutils-esp32ulp/releases.
2. Extract the toolchain into a directory, and add the path to the ``bin/`` directory of the toolchain to the ``PATH`` environment variable.
Compiling ULP code
------------------
To compile ULP code as part of a component, the following steps must be taken:
1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`.
.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``COMPONENT_SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files.
2. Modify component CMakeLists.txt, appending the necessary ULP CMake definitions. As an example::
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")
include(${IDF_PATH}/components/ulp/component_ulp_common.cmake)
Here is each line explained:
set(ULP_APP_NAME ulp_${COMPONENT_NAME})
Sets the name of the generated ULP application, without an extension. This name is used for build products of the ULP application: ELF file, map file, binary file, generated header file, and generated linker export file.
set(ULP_S_SOURCES "ulp/ulp_assembly_source_file_1.S ulp/ulp_assembly_source_file_2.S")
Sets list of assembly files to be passed to the ULP assembler. The list should be space-delimited and the paths can either be absolute or relative to component CMakeLists.txt.
set(ULP_EXP_DEP_SRCS "ulp_c_source_file_1.c ulp_c_source_file_2.c")
Sets list of source files names within the component which include the generated header file. This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. See section below explaining the concept of generated header files for ULP applications.
The list should be space-delimited and the paths can either be absolute or relative to component CMakeLists.txt.
include(${IDF_PATH}/components/ulp/component_ulp_common.cmake)
Includes common definitions of ULP build steps. Configures build for ULP object files, ELF file, binary file, etc using the ULP toolchain.
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 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 assembler.** This produces objects (foo.ulp.o) and listing (foo.ulp.lst) files. Listing files are generated for debugging purposes and are not used at later stages of build process.
3. **Run linker script template through C preprocessor.** The template is located in components/ulp/ld directory.
4. **Link object files into an output ELF file** (ulp_app_name.elf). Map file (ulp_app_name.map) generated at this stage may be useful for debugging purposes.
5. **Dump contents of the ELF file into binary** (ulp_app_name.bin) for embedding into the application.
6. **Generate list of global symbols** (ulp_app_name.sym) in the ELF file using esp32ulp-elf-nm.
7. **Create 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 esp32ulp_mapgen.py utility.
8. **Add the generated binary to the list of binary files** to be emedded into the application.
Accessing ULP program variables
-------------------------------
Global symbols defined in the ULP program may be used inside the main program.
For example, 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
Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``${ULP_APP_NAME}.h`` and ``${ULP_APP_NAME}.ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``.
The header file contains 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 address of the symbol and cast to the appropriate type.
The generated linker script file defines locations of symbols in RTC_SLOW_MEM::
PROVIDE ( ulp_measurement_count = 0x50000060 );
To access ULP program variables from the main program, include the generated header file and use variables as one normally would::
#include "ulp_app_name.h"
// later
void init_ulp_vars() {
ulp_measurement_count = 64;
}
Note that 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 high part of the word.
Likewise, ULP store instruction writes register value into the lower 16 bit part of the 32-bit word. Upper 16 bits are written with a value which depends on the address of the store instruction, so when reading variables written by the ULP, main application needs to mask 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, main application needs to load the ULP program into RTC memory using ``ulp_load_binary`` function, and then start it using ``ulp_run`` function.
Note that "Enable Ultra Low Power (ULP) Coprocessor" option must be enabled in menuconfig in order 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. 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, application can start it, passing the address of the entry point to ``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 above mentioned generated header file, ``${ULP_APP_NAME}.h``. In assembly source of the ULP application, this symbol must be marked as ``.global``::
.global entry
entry:
/* code starts here */
ULP program flow
----------------
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 150kHz RC oscillator). The number of ticks is set using ``SENS_ULP_CP_SLEEP_CYCx_REG`` registers (x = 0..4). When starting the ULP for the first time, ``SENS_ULP_CP_SLEEP_CYC0_REG`` will be used to set the number of timer ticks. Later the ULP program can select another ``SENS_ULP_CP_SLEEP_CYCx_REG`` register using ``sleep`` instruction.
The application can set ULP timer period values (SENS_ULP_CP_SLEEP_CYCx_REG, x = 0..4) using ``ulp_wakeup_period_set`` 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.
.. _binutils-esp32ulp toolchain: https://github.com/espressif/binutils-esp32ulp

View file

@ -4,7 +4,6 @@
- Eclipse IDE Documentation
- Secure Boot
- Flash Encryption
- ULP toolchain.
Support for these features will be available before CMake becomes the default build system.

View file

@ -20,6 +20,7 @@ API Guides
Partition Tables <partition-tables>
Secure Boot <../security/secure-boot>
ULP Coprocessor <ulp>
ULP Coprocessor (CMake) <ulp-cmake>
单元测试 <unit-tests>
Application Level Tracing <app_trace>
Console Component <console>

View file

@ -0,0 +1 @@
.. include:: ../../en/api-guides/ulp-cmake.rst

View file

@ -0,0 +1,6 @@
# The following lines of boilerplate have to be in your project's CMakeLists
# in this exact order for cmake to work correctly
cmake_minimum_required(VERSION 3.5)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(ulp-example)

View file

@ -0,0 +1,27 @@
# Set usual component variables
set(COMPONENT_SRCS "ulp_example_main.c")
set(COMPONENT_ADD_INCLUDEDIRS "")
set(COMPONENT_REQUIRES soc nvs_flash ulp)
register_component()
#
# ULP support additions to component makefile.
#
# 1. ULP_APP_NAME must be unique (if multiple components use ULP)
# Default value, override if necessary:
set(ULP_APP_NAME ulp_${COMPONENT_NAME})
#
# 2. Specify all assembly source files here.
# Files should be placed into a separate directory (in this case, ulp/),
# which should not be added to COMPONENT_SRCS.
set(ULP_S_SOURCES "ulp/pulse_cnt.S")
#
# 3. List all the component source files which include automatically
# generated ULP export file, $(ULP_APP_NAME).h:
set(ULP_EXP_DEP_SRCS "ulp_example_main.c")
#
# 4. Include build rules for ULP program
# End of ULP support additions to component makefile.
#
include(${IDF_PATH}/components/ulp/component_ulp_common.cmake)

View file

@ -0,0 +1,6 @@
# The following lines of boilerplate have to be in your project's CMakeLists
# in this exact order for cmake to work correctly
cmake_minimum_required(VERSION 3.5)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(ulp-adc-example)

View file

@ -0,0 +1,27 @@
# Set usual component variables
set(COMPONENT_SRCS "ulp_adc_example_main.c")
set(COMPONENT_ADD_INCLUDEDIRS "")
set(COMPONENT_REQUIRES soc nvs_flash ulp driver)
register_component()
#
# ULP support additions to component makefile.
#
# 1. ULP_APP_NAME must be unique (if multiple components use ULP)
# Default value, override if necessary:
set(ULP_APP_NAME ulp_${COMPONENT_NAME})
#
# 2. Specify all assembly source files here.
# Files should be placed into a separate directory (in this case, ulp/),
# which should not be added to COMPONENT_SRCS.
set(ULP_S_SOURCES "ulp/adc.S")
#
# 3. List all the component source files which include automatically
# generated ULP export file, $(ULP_APP_NAME).h:
set(ULP_EXP_DEP_SRCS "ulp_adc_example_main.c")
#
# 4. Include build rules for ULP program
# End of ULP support additions to component makefile.
#
include(${IDF_PATH}/components/ulp/component_ulp_common.cmake)

View file

@ -5,10 +5,6 @@
CMAKE_EXAMPLE_PATHS=$( find ${IDF_PATH}/examples/ -type f -name CMakeLists.txt | grep -v "/components/" | grep -v "/main/")
MAKE_EXAMPLE_PATHS=$( find ${IDF_PATH}/examples/ -type f -name Makefile )
# temporary: ignore ULP examples as no ULP toolchain support
CMAKE_EXAMPLE_PATHS=$( echo "$CMAKE_EXAMPLE_PATHS" | grep -v "/system/ulp")
MAKE_EXAMPLE_PATHS=$( echo "$MAKE_EXAMPLE_PATHS" | grep -v "/system/ulp")
CMAKE_EXAMPLE_PATHS="$(/usr/bin/dirname $CMAKE_EXAMPLE_PATHS | sort -n)"
MAKE_EXAMPLE_PATHS="$(/usr/bin/dirname $MAKE_EXAMPLE_PATHS | sort -n)"

View file

@ -181,7 +181,6 @@ function(expand_component_requirements component)
set_property(GLOBAL APPEND PROPERTY BUILD_COMPONENTS ${component})
endfunction()
# Main functionality goes here
# Find every available component in COMPONENT_DIRS, save as ALL_COMPONENT_PATHS and ALL_COMPONENTS
@ -200,10 +199,14 @@ set_property(GLOBAL PROPERTY BUILD_COMPONENTS "")
set_property(GLOBAL PROPERTY BUILD_COMPONENT_PATHS "")
set_property(GLOBAL PROPERTY COMPONENTS_NOT_FOUND "")
# Indicate that the component CMakeLists.txt is being included in the early expansion phase of the build,
# and might not want to execute particular operations.
set(CMAKE_BUILD_EARLY_EXPANSION 1)
foreach(component ${COMPONENTS})
debug("Expanding initial component ${component}")
expand_component_requirements(${component})
endforeach()
unset(CMAKE_BUILD_EARLY_EXPANSION)
get_property(build_components GLOBAL PROPERTY BUILD_COMPONENTS)
get_property(build_component_paths GLOBAL PROPERTY BUILD_COMPONENT_PATHS)

View file

@ -31,7 +31,6 @@ function(spaces2list variable_name)
set("${variable_name}" "${tmp}" PARENT_SCOPE)
endfunction()
# lines2list
#
# Take a variable with multiple lines of output in it, convert it