ulp: Add header for common ULP definitions

Fixes problems with duplicate error codes in the two chip-specific ulp headers

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

components/ulp/include/esp32/ulp.h

@@ -18,6 +18,7 @@
 #include <stdlib.h>
 #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
+#endif

components/ulp/include/esp32s2beta/ulp.h

@@ -18,6 +18,7 @@
 #include <stdlib.h>
 #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

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

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
     ##