1 /* 2 * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef _ROM_ETS_SYS_H_ 8 #define _ROM_ETS_SYS_H_ 9 10 #include <stdint.h> 11 #include <stdbool.h> 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 /** \defgroup ets_sys_apis, ets system related apis 18 * @brief ets system apis 19 */ 20 21 /** @addtogroup ets_sys_apis 22 * @{ 23 */ 24 25 /************************************************************************ 26 * NOTE 27 * Many functions in this header files can't be run in FreeRTOS. 28 * Please see the comment of the Functions. 29 * There are also some functions that doesn't work on FreeRTOS 30 * without listed in the header, such as: 31 * xtos functions start with "_xtos_" in ld file. 32 * 33 *********************************************************************** 34 */ 35 36 /** \defgroup ets_apis, Espressif Task Scheduler related apis 37 * @brief ets apis 38 */ 39 40 /** @addtogroup ets_apis 41 * @{ 42 */ 43 44 typedef enum { 45 ETS_OK = 0, /**< return successful in ets*/ 46 ETS_FAILED = 1, /**< return failed in ets*/ 47 ETS_PENDING = 2, 48 ETS_BUSY = 3, 49 ETS_CANCEL = 4, 50 } ETS_STATUS; 51 52 typedef ETS_STATUS ets_status_t; 53 54 typedef uint32_t ETSSignal; 55 typedef uint32_t ETSParam; 56 57 typedef struct ETSEventTag ETSEvent; /**< Event transmit/receive in ets*/ 58 59 struct ETSEventTag { 60 ETSSignal sig; /**< Event signal, in same task, different Event with different signal*/ 61 ETSParam par; /**< Event parameter, sometimes without usage, then will be set as 0*/ 62 }; 63 64 typedef void (*ETSTask)(ETSEvent *e); /**< Type of the Task processer*/ 65 typedef void (* ets_idle_cb_t)(void *arg); /**< Type of the system idle callback*/ 66 67 68 69 70 71 /** 72 * @} 73 */ 74 75 /** \defgroup ets_boot_apis, Boot routing related apis 76 * @brief ets boot apis 77 */ 78 79 /** @addtogroup ets_apis 80 * @{ 81 */ 82 83 extern const char *const exc_cause_table[40]; ///**< excption cause that defined by the core.*/ 84 85 /** 86 * @brief Set Pro cpu Entry code, code can be called in PRO CPU when booting is not completed. 87 * When Pro CPU booting is completed, Pro CPU will call the Entry code if not NULL. 88 * 89 * @param uint32_t start : the PRO Entry code address value in uint32_t 90 * 91 * @return None 92 */ 93 void ets_set_user_start(uint32_t start); 94 95 /** 96 * @} 97 */ 98 99 /** \defgroup ets_printf_apis, ets_printf related apis used in ets 100 * @brief ets printf apis 101 */ 102 103 /** @addtogroup ets_printf_apis 104 * @{ 105 */ 106 107 /** 108 * @brief Printf the strings to uart or other devices, similar with printf, simple than printf. 109 * Can not print float point data format, or longlong data format. 110 * So we maybe only use this in ROM. 111 * 112 * @param const char *fmt : See printf. 113 * 114 * @param ... : See printf. 115 * 116 * @return int : the length printed to the output device. 117 */ 118 int ets_printf(const char *fmt, ...); 119 120 /** 121 * @brief Get the uart channel of ets_printf(uart_tx_one_char). 122 * 123 * @return uint8_t uart channel used by ets_printf(uart_tx_one_char). 124 */ 125 uint8_t ets_get_printf_channel(void); 126 127 /** 128 * @brief Ets_printf have two output functions： putc1 and putc2, both of which will be called if need ouput. 129 * To install putc1, which is defaulted installed as ets_write_char_uart in none silent boot mode, as NULL in silent mode. 130 * 131 * @param void (*)(char) p: Output function to install. 132 * 133 * @return None 134 */ 135 void ets_install_putc1(void (*p)(char c)); 136 137 /** 138 * @brief Ets_printf have two output functions： putc1 and putc2, both of which will be called if need ouput. 139 * To install putc2, which is defaulted installed as NULL. 140 * 141 * @param void (*)(char) p: Output function to install. 142 * 143 * @return None 144 */ 145 void ets_install_putc2(void (*p)(char c)); 146 147 /** 148 * @brief Install putc1 as ets_write_char_uart. 149 * In silent boot mode(to void interfere the UART attached MCU), we can call this function, after booting ok. 150 * 151 * @param None 152 * 153 * @return None 154 */ 155 void ets_install_uart_printf(void); 156 157 #define ETS_PRINTF(...) ets_printf(...) 158 159 #define ETS_ASSERT(v) do { \ 160 if (!(v)) { \ 161 ets_printf("%s %u \n", __FILE__, __LINE__); \ 162 while (1) {}; \ 163 } \ 164 } while (0); 165 166 /** 167 * @} 168 */ 169 170 /** \defgroup ets_timer_apis, ets_timer related apis used in ets 171 * @brief ets timer apis 172 */ 173 174 /** @addtogroup ets_timer_apis 175 * @{ 176 */ 177 typedef void ETSTimerFunc(void *timer_arg);/**< timer handler*/ 178 179 typedef struct _ETSTIMER_ { 180 struct _ETSTIMER_ *timer_next; /**< timer linker*/ 181 uint32_t timer_expire; /**< abstruct time when timer expire*/ 182 uint32_t timer_period; /**< timer period, 0 means timer is not periodic repeated*/ 183 ETSTimerFunc *timer_func; /**< timer handler*/ 184 void *timer_arg; /**< timer handler argument*/ 185 } ETSTimer; 186 187 /** 188 * @brief Init ets timer, this timer range is 640 us to 429496 ms 189 * In FreeRTOS, please call FreeRTOS apis, never call this api. 190 * 191 * @param None 192 * 193 * @return None 194 */ 195 void ets_timer_init(void); 196 197 /** 198 * @brief In FreeRTOS, please call FreeRTOS apis, never call this api. 199 * 200 * @param None 201 * 202 * @return None 203 */ 204 void ets_timer_deinit(void); 205 206 /** 207 * @brief Arm an ets timer, this timer range is 640 us to 429496 ms. 208 * In FreeRTOS, please call FreeRTOS apis, never call this api. 209 * 210 * @param ETSTimer *timer : Timer struct pointer. 211 * 212 * @param uint32_t tmout : Timer value in ms, range is 1 to 429496. 213 * 214 * @param bool repeat : Timer is periodic repeated. 215 * 216 * @return None 217 */ 218 void ets_timer_arm(ETSTimer *timer, uint32_t tmout, bool repeat); 219 220 /** 221 * @brief Arm an ets timer, this timer range is 640 us to 429496 ms. 222 * In FreeRTOS, please call FreeRTOS apis, never call this api. 223 * 224 * @param ETSTimer *timer : Timer struct pointer. 225 * 226 * @param uint32_t tmout : Timer value in us, range is 1 to 429496729. 227 * 228 * @param bool repeat : Timer is periodic repeated. 229 * 230 * @return None 231 */ 232 void ets_timer_arm_us(ETSTimer *ptimer, uint32_t us, bool repeat); 233 234 /** 235 * @brief Disarm an ets timer. 236 * In FreeRTOS, please call FreeRTOS apis, never call this api. 237 * 238 * @param ETSTimer *timer : Timer struct pointer. 239 * 240 * @return None 241 */ 242 void ets_timer_disarm(ETSTimer *timer); 243 244 /** 245 * @brief Set timer callback and argument. 246 * In FreeRTOS, please call FreeRTOS apis, never call this api. 247 * 248 * @param ETSTimer *timer : Timer struct pointer. 249 * 250 * @param ETSTimerFunc *pfunction : Timer callback. 251 * 252 * @param void *parg : Timer callback argument. 253 * 254 * @return None 255 */ 256 void ets_timer_setfn(ETSTimer *ptimer, ETSTimerFunc *pfunction, void *parg); 257 258 /** 259 * @brief Unset timer callback and argument to NULL. 260 * In FreeRTOS, please call FreeRTOS apis, never call this api. 261 * 262 * @param ETSTimer *timer : Timer struct pointer. 263 * 264 * @return None 265 */ 266 void ets_timer_done(ETSTimer *ptimer); 267 268 /** 269 * @brief CPU do while loop for some time. 270 * In FreeRTOS task, please call FreeRTOS apis. 271 * 272 * @param uint32_t us : Delay time in us. 273 * 274 * @return None 275 */ 276 void ets_delay_us(uint32_t us); 277 278 /** 279 * @brief Set the real CPU ticks per us to the ets, so that ets_delay_us will be accurate. 280 * Call this function when CPU frequency is changed. 281 * 282 * @param uint32_t ticks_per_us : CPU ticks per us. 283 * 284 * @return None 285 */ 286 void ets_update_cpu_frequency(uint32_t ticks_per_us); 287 288 289 290 /** 291 * @brief Get the real CPU ticks per us to the ets. 292 * This function do not return real CPU ticks per us, just the record in ets. It can be used to check with the real CPU frequency. 293 * 294 * @param None 295 * 296 * @return uint32_t : CPU ticks per us record in ets. 297 */ 298 uint32_t ets_get_cpu_frequency(void); 299 300 /** 301 * @brief Get xtal_freq value, If value not stored in RTC_STORE5, than store. 302 * 303 * @param None 304 * 305 * @return uint32_t : if stored in efuse(not 0) 306 * clock = ets_efuse_get_xtal_freq() * 1000000; 307 * else if analog_8M in efuse 308 * clock = ets_get_xtal_scale() * 625 / 16 * ets_efuse_get_8M_clock(); 309 * else clock = 40M. 310 */ 311 uint32_t ets_get_xtal_freq(void); 312 313 /** 314 * @brief Get the apb divior by xtal frequency. 315 * When any types of reset happen, the default value is 2. 316 * 317 * @param None 318 * 319 * @return uint32_t : 1 or 2. 320 */ 321 uint32_t ets_get_xtal_div(void); 322 323 /** 324 * @brief Get apb_freq value, If value not stored in RTC_STORE5, than store. 325 * 326 * @param None 327 * 328 * @return uint32_t : if rtc store the value (RTC_STORE5 high 16 bits and low 16 bits with same value), read from rtc register. 329 * clock = (REG_READ(RTC_STORE5) & 0xffff) << 12; 330 * else store ets_get_detected_xtal_freq() in. 331 */ 332 uint32_t ets_get_apb_freq(void); 333 334 /** 335 * @} 336 */ 337 338 /** \defgroup ets_intr_apis, ets interrupt configure related apis 339 * @brief ets intr apis 340 */ 341 342 /** @addtogroup ets_intr_apis 343 * @{ 344 */ 345 346 typedef void (* ets_isr_t)(void *);/**< interrupt handler type*/ 347 348 /** 349 * @brief Attach a interrupt handler to a CPU interrupt number. 350 * This function equals to _xtos_set_interrupt_handler_arg(i, func, arg). 351 * In FreeRTOS, please call FreeRTOS apis, never call this api. 352 * 353 * @param int i : CPU interrupt number. 354 * 355 * @param ets_isr_t func : Interrupt handler. 356 * 357 * @param void *arg : argument of the handler. 358 * 359 * @return None 360 */ 361 void ets_isr_attach(int i, ets_isr_t func, void *arg); 362 363 /** 364 * @brief Mask the interrupts which show in mask bits. 365 * This function equals to _xtos_ints_off(mask). 366 * In FreeRTOS, please call FreeRTOS apis, never call this api. 367 * 368 * @param uint32_t mask : BIT(i) means mask CPU interrupt number i. 369 * 370 * @return None 371 */ 372 void ets_isr_mask(uint32_t mask); 373 374 /** 375 * @brief Unmask the interrupts which show in mask bits. 376 * This function equals to _xtos_ints_on(mask). 377 * In FreeRTOS, please call FreeRTOS apis, never call this api. 378 * 379 * @param uint32_t mask : BIT(i) means mask CPU interrupt number i. 380 * 381 * @return None 382 */ 383 void ets_isr_unmask(uint32_t unmask); 384 385 /** 386 * @brief Lock the interrupt to level 2. 387 * This function direct set the CPU registers. 388 * In FreeRTOS, please call FreeRTOS apis, never call this api. 389 * 390 * @param None 391 * 392 * @return None 393 */ 394 void ets_intr_lock(void); 395 396 /** 397 * @brief Unlock the interrupt to level 0. 398 * This function direct set the CPU registers. 399 * In FreeRTOS, please call FreeRTOS apis, never call this api. 400 * 401 * @param None 402 * 403 * @return None 404 */ 405 void ets_intr_unlock(void); 406 407 /** 408 * @brief Attach an CPU interrupt to a hardware source. 409 * We have 4 steps to use an interrupt: 410 * 1.Attach hardware interrupt source to CPU. intr_matrix_set(0, ETS_WIFI_MAC_INTR_SOURCE, ETS_WMAC_INUM); 411 * 2.Set interrupt handler. xt_set_interrupt_handler(ETS_WMAC_INUM, func, NULL); 412 * 3.Enable interrupt for CPU. xt_ints_on(1 << ETS_WMAC_INUM); 413 * 4.Enable interrupt in the module. 414 * 415 * @param int cpu_no : The CPU which the interrupt number belongs. 416 * 417 * @param uint32_t model_num : The interrupt hardware source number, please see the interrupt hardware source table. 418 * 419 * @param uint32_t intr_num : The interrupt number CPU, please see the interrupt cpu using table. 420 * 421 * @return None 422 */ 423 void intr_matrix_set(int cpu_no, uint32_t model_num, uint32_t intr_num); 424 425 /** 426 * @} 427 */ 428 429 #ifndef MAC2STR 430 #define MAC2STR(a) (a)[0], (a)[1], (a)[2], (a)[3], (a)[4], (a)[5] 431 #define MACSTR "%02x:%02x:%02x:%02x:%02x:%02x" 432 #endif 433 434 #define ETS_MEM_BAR() asm volatile ( "" : : : "memory" ) 435 436 #ifdef ESP_PLATFORM 437 // Remove in IDF v6.0 (IDF-7044) 438 typedef enum { 439 OK = 0, 440 FAIL, 441 PENDING, 442 BUSY, 443 CANCEL, 444 } STATUS __attribute__((deprecated("Use ETS_STATUS instead"))); 445 #endif 446 447 /** 448 * @} 449 */ 450 451 #ifdef __cplusplus 452 } 453 #endif 454 455 #endif /* _ROM_ETS_SYS_H_ */ 456
