diff --git a/components/esp_common/src/esp_err_to_name.c b/components/esp_common/src/esp_err_to_name.c index 12b5e21cb..e234a26b1 100644 --- a/components/esp_common/src/esp_err_to_name.c +++ b/components/esp_common/src/esp_err_to_name.c @@ -5,9 +5,6 @@ #if __has_include("soc/soc.h") #include "soc/soc.h" #endif -#if __has_include("esp32/ulp.h") -#include "esp32/ulp.h" -#endif #if __has_include("esp_efuse.h") #include "esp_efuse.h" #endif @@ -56,6 +53,9 @@ #if __has_include("tcpip_adapter.h") #include "tcpip_adapter.h" #endif +#if __has_include("ulp_common.h") +#include "ulp_common.h" +#endif #ifdef CONFIG_ESP_ERR_TO_NAME_LOOKUP #define ERR_TBL_IT(err) {err, #err} @@ -203,7 +203,7 @@ static const esp_err_msg_t esp_err_msg_table[] = { API functions. NVS key is different in comparison */ # endif - // components/ulp/include/esp32/ulp.h + // components/ulp/include/ulp_common.h # ifdef ESP_ERR_ULP_BASE ERR_TBL_IT(ESP_ERR_ULP_BASE), /* 4608 0x1200 Offset for ULP-related error codes */ # endif diff --git a/components/ulp/include/esp32/ulp.h b/components/ulp/include/esp32/ulp.h index d55a8c6c7..2f22937e2 100644 --- a/components/ulp/include/esp32/ulp.h +++ b/components/ulp/include/esp32/ulp.h @@ -18,6 +18,7 @@ #include #include "esp_err.h" #include "soc/soc.h" +#include "ulp_common.h" #ifdef __cplusplus extern "C" { @@ -111,15 +112,6 @@ extern "C" { #define SUB_OPCODE_MACRO_LABELPC 2 /*!< Label pointer macro */ /**@}*/ -/**@{*/ -#define ESP_ERR_ULP_BASE 0x1200 /*!< Offset for ULP-related error codes */ -#define ESP_ERR_ULP_SIZE_TOO_BIG (ESP_ERR_ULP_BASE + 1) /*!< Program doesn't fit into RTC memory reserved for the ULP */ -#define ESP_ERR_ULP_INVALID_LOAD_ADDR (ESP_ERR_ULP_BASE + 2) /*!< Load address is outside of RTC memory reserved for the ULP */ -#define ESP_ERR_ULP_DUPLICATE_LABEL (ESP_ERR_ULP_BASE + 3) /*!< More than one label with the same number was defined */ -#define ESP_ERR_ULP_UNDEFINED_LABEL (ESP_ERR_ULP_BASE + 4) /*!< Branch instructions references an undefined label */ -#define ESP_ERR_ULP_BRANCH_OUT_OF_RANGE (ESP_ERR_ULP_BASE + 5) /*!< Branch target is out of range of B instruction (try replacing with BX) */ -/**@}*/ - /** * @brief Instruction format structure @@ -135,7 +127,7 @@ extern "C" { * Preprocessor definitions provided below fill the fields of these structure with * the right arguments. */ -typedef union { +union ulp_insn { struct { uint32_t cycles : 16; /*!< Number of cycles to sleep */ @@ -295,7 +287,9 @@ typedef union { uint32_t instruction; /*!< Encoded instruction for ULP coprocessor */ -} ulp_insn_t; +}; + +typedef union ulp_insn ulp_insn_t; _Static_assert(sizeof(ulp_insn_t) == 4, "ULP coprocessor instruction size should be 4 bytes"); @@ -1046,80 +1040,7 @@ static inline uint32_t SOC_REG_TO_ULP_PERIPH_SEL(uint32_t reg) { #define RTC_SLOW_MEM ((uint32_t*) 0x50000000) /*!< RTC slow memory, 8k size */ -/** - * @brief Resolve all macro references in a program and load it into RTC memory - * @param load_addr address where the program should be loaded, expressed in 32-bit words - * @param program ulp_insn_t array with the program - * @param psize size of the program, expressed in 32-bit words - * @return - * - ESP_OK on success - * - ESP_ERR_NO_MEM if auxiliary temporary structure can not be allocated - * - one of ESP_ERR_ULP_xxx if program is not valid or can not be loaded - */ -esp_err_t ulp_process_macros_and_load(uint32_t load_addr, const ulp_insn_t* program, size_t* psize); - -/** - * @brief Load ULP program binary into RTC memory - * - * ULP program binary should have the following format (all values little-endian): - * - * 1. MAGIC, (value 0x00706c75, 4 bytes) - * 2. TEXT_OFFSET, offset of .text section from binary start (2 bytes) - * 3. TEXT_SIZE, size of .text section (2 bytes) - * 4. DATA_SIZE, size of .data section (2 bytes) - * 5. BSS_SIZE, size of .bss section (2 bytes) - * 6. (TEXT_OFFSET - 12) bytes of arbitrary data (will not be loaded into RTC memory) - * 7. .text section - * 8. .data section - * - * Linker script in components/ulp/ld/esp32.ulp.ld produces ELF files which - * correspond to this format. This linker script produces binaries with load_addr == 0. - * - * @param load_addr address where the program should be loaded, expressed in 32-bit words - * @param program_binary pointer to program binary - * @param program_size size of the program binary - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if load_addr is out of range - * - ESP_ERR_INVALID_SIZE if program_size doesn't match (TEXT_OFFSET + TEXT_SIZE + DATA_SIZE) - * - ESP_ERR_NOT_SUPPORTED if the magic number is incorrect - */ -esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t* program_binary, size_t program_size); - -/** - * @brief Run the program loaded into RTC memory - * @param entry_point entry point, expressed in 32-bit words - * @return ESP_OK on success - */ -esp_err_t ulp_run(uint32_t entry_point); - -/** - * @brief Set one of ULP wakeup period values - * - * ULP coprocessor starts running the program when the wakeup timer counts up - * to a given value (called period). There are 5 period values which can be - * programmed into SENS_ULP_CP_SLEEP_CYCx_REG registers, x = 0..4. - * By default, wakeup timer will use the period set into SENS_ULP_CP_SLEEP_CYC0_REG, - * i.e. period number 0. ULP program code can use SLEEP instruction to select - * which of the SENS_ULP_CP_SLEEP_CYCx_REG should be used for subsequent wakeups. - * - * However, please note that SLEEP instruction issued (from ULP program) while the system - * is in deep sleep mode does not have effect, and sleep cycle count 0 is used. - * - * @param period_index wakeup period setting number (0 - 4) - * @param period_us wakeup period, us - * @note The ULP FSM requires two clock cycles to wakeup before being able to run the program. - * Then additional 16 cycles are reserved after wakeup waiting until the 8M clock is stable. - * The FSM also requires two more clock cycles to go to sleep after the program execution is halted. - * The minimum wakeup period that may be set up for the ULP - * is equal to the total number of cycles spent on the above internal tasks. - * For a default configuration of the ULP running at 150kHz it makes about 133us. - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if period_index is out of range - */ -esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us); #ifdef __cplusplus } -#endif \ No newline at end of file +#endif diff --git a/components/ulp/include/esp32s2beta/ulp.h b/components/ulp/include/esp32s2beta/ulp.h index c9ca51101..58331cf52 100644 --- a/components/ulp/include/esp32s2beta/ulp.h +++ b/components/ulp/include/esp32s2beta/ulp.h @@ -18,6 +18,7 @@ #include #include "esp_err.h" #include "soc/soc.h" +#include "ulp_common.h" #ifdef __cplusplus extern "C" { @@ -100,16 +101,6 @@ extern "C" { #define SUB_OPCODE_MACRO_BRANCH 1 /*!< Branch macro */ /**@}*/ -/**@{*/ -#define ESP_ERR_ULP_BASE 0x1200 /*!< Offset for ULP-related error codes */ -#define ESP_ERR_ULP_SIZE_TOO_BIG (ESP_ERR_ULP_BASE + 1) /*!< Program doesn't fit into RTC memory reserved for the ULP */ -#define ESP_ERR_ULP_INVALID_LOAD_ADDR (ESP_ERR_ULP_BASE + 2) /*!< Load address is outside of RTC memory reserved for the ULP */ -#define ESP_ERR_ULP_DUPLICATE_LABEL (ESP_ERR_ULP_BASE + 3) /*!< More than one label with the same number was defined */ -#define ESP_ERR_ULP_UNDEFINED_LABEL (ESP_ERR_ULP_BASE + 4) /*!< Branch instructions references an undefined label */ -#define ESP_ERR_ULP_BRANCH_OUT_OF_RANGE (ESP_ERR_ULP_BASE + 5) /*!< Branch target is out of range of B instruction (try replacing with BX) */ -/**@}*/ - - /** * @brief Instruction format structure * @@ -124,7 +115,7 @@ extern "C" { * Preprocessor definitions provided below fill the fields of these structure with * the right arguments. */ -typedef union { +union ulp_insn { struct { uint32_t cycles : 16; /*!< Number of cycles to sleep */ @@ -262,7 +253,9 @@ typedef union { uint32_t opcode: 4; /*!< Opcode (OPCODE_MACRO) */ } macro; /*!< Format of tokens used by LABEL and BRANCH macros */ -} ulp_insn_t; +}; + +typedef union ulp_insn ulp_insn_t; _Static_assert(sizeof(ulp_insn_t) == 4, "ULP coprocessor instruction size should be 4 bytes"); @@ -841,80 +834,6 @@ static inline uint32_t SOC_REG_TO_ULP_PERIPH_SEL(uint32_t reg) { #define RTC_SLOW_MEM ((uint32_t*) 0x50000000) /*!< RTC slow memory, 8k size */ -/** - * @brief Resolve all macro references in a program and load it into RTC memory - * @param load_addr address where the program should be loaded, expressed in 32-bit words - * @param program ulp_insn_t array with the program - * @param psize size of the program, expressed in 32-bit words - * @return - * - ESP_OK on success - * - ESP_ERR_NO_MEM if auxiliary temporary structure can not be allocated - * - one of ESP_ERR_ULP_xxx if program is not valid or can not be loaded - */ -esp_err_t ulp_process_macros_and_load(uint32_t load_addr, const ulp_insn_t* program, size_t* psize); - -/** - * @brief Load ULP program binary into RTC memory - * - * ULP program binary should have the following format (all values little-endian): - * - * 1. MAGIC, (value 0x00706c75, 4 bytes) - * 2. TEXT_OFFSET, offset of .text section from binary start (2 bytes) - * 3. TEXT_SIZE, size of .text section (2 bytes) - * 4. DATA_SIZE, size of .data section (2 bytes) - * 5. BSS_SIZE, size of .bss section (2 bytes) - * 6. (TEXT_OFFSET - 12) bytes of arbitrary data (will not be loaded into RTC memory) - * 7. .text section - * 8. .data section - * - * Linker script in components/ulp/ld/esp32.ulp.ld produces ELF files which - * correspond to this format. This linker script produces binaries with load_addr == 0. - * - * @param load_addr address where the program should be loaded, expressed in 32-bit words - * @param program_binary pointer to program binary - * @param program_size size of the program binary - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if load_addr is out of range - * - ESP_ERR_INVALID_SIZE if program_size doesn't match (TEXT_OFFSET + TEXT_SIZE + DATA_SIZE) - * - ESP_ERR_NOT_SUPPORTED if the magic number is incorrect - */ -esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t* program_binary, size_t program_size); - -/** - * @brief Run the program loaded into RTC memory - * @param entry_point entry point, expressed in 32-bit words - * @return ESP_OK on success - */ -esp_err_t ulp_run(uint32_t entry_point); - -/** - * @brief Set one of ULP wakeup period values - * - * ULP coprocessor starts running the program when the wakeup timer counts up - * to a given value (called period). There are 5 period values which can be - * programmed into SENS_ULP_CP_SLEEP_CYCx_REG registers, x = 0..4. - * By default, wakeup timer will use the period set into SENS_ULP_CP_SLEEP_CYC0_REG, - * i.e. period number 0. ULP program code can use SLEEP instruction to select - * which of the SENS_ULP_CP_SLEEP_CYCx_REG should be used for subsequent wakeups. - * - * However, please note that SLEEP instruction issued (from ULP program) while the system - * is in deep sleep mode does not have effect, and sleep cycle count 0 is used. - * - * @param period_index wakeup period setting number (0 - 4) - * @param period_us wakeup period, us - * @note The ULP FSM requires two clock cycles to wakeup before being able to run the program. - * Then additional 16 cycles are reserved after wakeup waiting until the 8M clock is stable. - * The FSM also requires two more clock cycles to go to sleep after the program execution is halted. - * The minimum wakeup period that may be set up for the ULP - * is equal to the total number of cycles spent on the above internal tasks. - * For a default configuration of the ULP running at 150kHz it makes about 133us. - * @return - * - ESP_OK on success - * - ESP_ERR_INVALID_ARG if period_index is out of range - */ -esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us); - #ifdef __cplusplus } #endif diff --git a/components/ulp/include/ulp_common.h b/components/ulp/include/ulp_common.h new file mode 100644 index 000000000..b7c773d65 --- /dev/null +++ b/components/ulp/include/ulp_common.h @@ -0,0 +1,113 @@ +// Copyright 2016-2018 Espressif Systems (Shanghai) PTE LTD +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +#pragma once + +/* This file contains definitions that are common between esp32/ulp.h + and esp32s2beta/ulp.h +*/ + +#ifdef __cplusplus +extern "C" { +#endif + +/**@{*/ +#define ESP_ERR_ULP_BASE 0x1200 /*!< Offset for ULP-related error codes */ +#define ESP_ERR_ULP_SIZE_TOO_BIG (ESP_ERR_ULP_BASE + 1) /*!< Program doesn't fit into RTC memory reserved for the ULP */ +#define ESP_ERR_ULP_INVALID_LOAD_ADDR (ESP_ERR_ULP_BASE + 2) /*!< Load address is outside of RTC memory reserved for the ULP */ +#define ESP_ERR_ULP_DUPLICATE_LABEL (ESP_ERR_ULP_BASE + 3) /*!< More than one label with the same number was defined */ +#define ESP_ERR_ULP_UNDEFINED_LABEL (ESP_ERR_ULP_BASE + 4) /*!< Branch instructions references an undefined label */ +#define ESP_ERR_ULP_BRANCH_OUT_OF_RANGE (ESP_ERR_ULP_BASE + 5) /*!< Branch target is out of range of B instruction (try replacing with BX) */ +/**@}*/ + +union ulp_insn; // Declared in the chip-specific ulp.h header + +typedef union ulp_insn ulp_insn_t; + +/** + * @brief Resolve all macro references in a program and load it into RTC memory + * @param load_addr address where the program should be loaded, expressed in 32-bit words + * @param program ulp_insn_t array with the program + * @param psize size of the program, expressed in 32-bit words + * @return + * - ESP_OK on success + * - ESP_ERR_NO_MEM if auxiliary temporary structure can not be allocated + * - one of ESP_ERR_ULP_xxx if program is not valid or can not be loaded + */ +esp_err_t ulp_process_macros_and_load(uint32_t load_addr, const ulp_insn_t* program, size_t* psize); + +/** + * @brief Load ULP program binary into RTC memory + * + * ULP program binary should have the following format (all values little-endian): + * + * 1. MAGIC, (value 0x00706c75, 4 bytes) + * 2. TEXT_OFFSET, offset of .text section from binary start (2 bytes) + * 3. TEXT_SIZE, size of .text section (2 bytes) + * 4. DATA_SIZE, size of .data section (2 bytes) + * 5. BSS_SIZE, size of .bss section (2 bytes) + * 6. (TEXT_OFFSET - 12) bytes of arbitrary data (will not be loaded into RTC memory) + * 7. .text section + * 8. .data section + * + * Linker script in components/ulp/ld/esp32.ulp.ld produces ELF files which + * correspond to this format. This linker script produces binaries with load_addr == 0. + * + * @param load_addr address where the program should be loaded, expressed in 32-bit words + * @param program_binary pointer to program binary + * @param program_size size of the program binary + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if load_addr is out of range + * - ESP_ERR_INVALID_SIZE if program_size doesn't match (TEXT_OFFSET + TEXT_SIZE + DATA_SIZE) + * - ESP_ERR_NOT_SUPPORTED if the magic number is incorrect + */ +esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t* program_binary, size_t program_size); + +/** + * @brief Run the program loaded into RTC memory + * @param entry_point entry point, expressed in 32-bit words + * @return ESP_OK on success + */ +esp_err_t ulp_run(uint32_t entry_point); + +/** + * @brief Set one of ULP wakeup period values + * + * ULP coprocessor starts running the program when the wakeup timer counts up + * to a given value (called period). There are 5 period values which can be + * programmed into SENS_ULP_CP_SLEEP_CYCx_REG registers, x = 0..4. + * By default, wakeup timer will use the period set into SENS_ULP_CP_SLEEP_CYC0_REG, + * i.e. period number 0. ULP program code can use SLEEP instruction to select + * which of the SENS_ULP_CP_SLEEP_CYCx_REG should be used for subsequent wakeups. + * + * However, please note that SLEEP instruction issued (from ULP program) while the system + * is in deep sleep mode does not have effect, and sleep cycle count 0 is used. + * + * @param period_index wakeup period setting number (0 - 4) + * @param period_us wakeup period, us + * @note The ULP FSM requires two clock cycles to wakeup before being able to run the program. + * Then additional 16 cycles are reserved after wakeup waiting until the 8M clock is stable. + * The FSM also requires two more clock cycles to go to sleep after the program execution is halted. + * The minimum wakeup period that may be set up for the ULP + * is equal to the total number of cycles spent on the above internal tasks. + * For a default configuration of the ULP running at 150kHz it makes about 133us. + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if period_index is out of range + */ +esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us); + +#ifdef __cplusplus +} +#endif diff --git a/docs/Doxyfile b/docs/Doxyfile index 55a915b06..3736267a7 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -217,6 +217,7 @@ INPUT = \ ## ## NOTE: for line below header_file.inc is not used ../../components/ulp/include/esp32/ulp.h \ + ../../components/ulp/include/ulp_common.h \ ## ## Application Level Tracing - API Reference ##