1 /* 2 * SPDX-FileCopyrightText: 2010-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 #include "soc/soc.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** \defgroup ets_sys_apis, ets system related apis 20 * @brief ets system apis 21 */ 22 23 /** @addtogroup ets_sys_apis 24 * @{ 25 */ 26 27 /************************************************************************ 28 * NOTE 29 * Many functions in this header files can't be run in FreeRTOS. 30 * Please see the comment of the Functions. 31 * There are also some functions that doesn't work on FreeRTOS 32 * without listed in the header, such as: 33 * xtos functions start with "_xtos_" in ld file. 34 * 35 *********************************************************************** 36 */ 37 38 /** \defgroup ets_apis, Espressif Task Scheduler related apis 39 * @brief ets apis 40 */ 41 42 /** @addtogroup ets_apis 43 * @{ 44 */ 45 46 typedef enum { 47 ETS_OK = 0, /**< return successful in ets*/ 48 ETS_FAILED = 1, /**< return failed in ets*/ 49 ETS_PENDING = 2, 50 ETS_BUSY = 3, 51 ETS_CANCEL = 4, 52 } ETS_STATUS; 53 54 typedef ETS_STATUS ets_status_t; 55 56 typedef uint32_t ETSSignal; 57 typedef uint32_t ETSParam; 58 59 typedef struct ETSEventTag ETSEvent; /**< Event transmit/receive in ets*/ 60 61 struct ETSEventTag { 62 ETSSignal sig; /**< Event signal, in same task, different Event with different signal*/ 63 ETSParam par; /**< Event parameter, sometimes without usage, then will be set as 0*/ 64 }; 65 66 typedef void (*ETSTask)(ETSEvent *e); /**< Type of the Task processer*/ 67 typedef void (* ets_idle_cb_t)(void *arg); /**< Type of the system idle callback*/ 68 69 70 71 72 73 /** 74 * @} 75 */ 76 77 /** \defgroup ets_boot_apis, Boot routing related apis 78 * @brief ets boot apis 79 */ 80 81 /** @addtogroup ets_apis 82 * @{ 83 */ 84 85 extern const char *const exc_cause_table[40]; ///**< excption cause that defined by the core.*/ 86 87 /** 88 * @brief Set Pro cpu Entry code, code can be called in PRO CPU when booting is not completed. 89 * When Pro CPU booting is completed, Pro CPU will call the Entry code if not NULL. 90 * 91 * @param uint32_t start : the PRO Entry code address value in uint32_t 92 * 93 * @return None 94 */ 95 void ets_set_user_start(uint32_t start); 96 97 /** 98 * @} 99 */ 100 101 /** \defgroup ets_printf_apis, ets_printf related apis used in ets 102 * @brief ets printf apis 103 */ 104 105 /** @addtogroup ets_printf_apis 106 * @{ 107 */ 108 109 /** 110 * @brief Printf the strings to uart or other devices, similar with printf, simple than printf. 111 * Can not print float point data format, or longlong data format. 112 * So we maybe only use this in ROM. 113 * 114 * @param const char *fmt : See printf. 115 * 116 * @param ... : See printf. 117 * 118 * @return int : the length printed to the output device. 119 */ 120 int ets_printf(const char *fmt, ...); 121 122 /** 123 * @brief Set the uart channel of ets_printf(uart_tx_one_char). 124 * ROM will set it base on the efuse and gpio setting, however, this can be changed after booting. 125 * 126 * @param uart_no : 0 for UART0, 1 for UART1, 2 for UART2. 127 * 128 * @return None 129 */ 130 void ets_set_printf_channel(uint8_t uart_no); 131 132 /** 133 * @brief Get the uart channel of ets_printf(uart_tx_one_char). 134 * 135 * @return uint8_t uart channel used by ets_printf(uart_tx_one_char). 136 */ 137 uint8_t ets_get_printf_channel(void); 138 139 /** 140 * @brief Output a char to uart, which uart to output(which is in uart module in ROM) is not in scope of the function. 141 * Can not print float point data format, or longlong data format 142 * 143 * @param char c : char to output. 144 * 145 * @return None 146 */ 147 void ets_write_char_uart(char c); 148 149 /** 150 * @brief Ets_printf have two output functions： putc1 and putc2, both of which will be called if need ouput. 151 * To install putc1, which is defaulted installed as ets_write_char_uart in none silent boot mode, as NULL in silent mode. 152 * 153 * @param void (*)(char) p: Output function to install. 154 * 155 * @return None 156 */ 157 void ets_install_putc1(void (*p)(char c)); 158 159 /** 160 * @brief Ets_printf have two output functions： putc1 and putc2, both of which will be called if need ouput. 161 * To install putc2, which is defaulted installed as NULL. 162 * 163 * @param void (*)(char) p: Output function to install. 164 * 165 * @return None 166 */ 167 void ets_install_putc2(void (*p)(char c)); 168 169 /** 170 * @brief Install putc1 as ets_write_char_uart. 171 * In silent boot mode(to void interfere the UART attached MCU), we can call this function, after booting ok. 172 * 173 * @param None 174 * 175 * @return None 176 */ 177 void ets_install_uart_printf(void); 178 179 #define ETS_PRINTF(...) ets_printf(...) 180 181 #define ETS_ASSERT(v) do { \ 182 if (!(v)) { \ 183 ets_printf("%s %u \n", __FILE__, __LINE__); \ 184 while (1) {}; \ 185 } \ 186 } while (0); 187 188 /** 189 * @} 190 */ 191 192 /** \defgroup ets_timer_apis, ets_timer related apis used in ets 193 * @brief ets timer apis 194 */ 195 196 /** @addtogroup ets_timer_apis 197 * @{ 198 */ 199 typedef void ETSTimerFunc(void *timer_arg);/**< timer handler*/ 200 201 typedef struct _ETSTIMER_ { 202 struct _ETSTIMER_ *timer_next; /**< timer linker*/ 203 uint32_t timer_expire; /**< abstruct time when timer expire*/ 204 uint32_t timer_period; /**< timer period, 0 means timer is not periodic repeated*/ 205 ETSTimerFunc *timer_func; /**< timer handler*/ 206 void *timer_arg; /**< timer handler argument*/ 207 } ETSTimer; 208 209 /** 210 * @brief Init ets timer, this timer range is 640 us to 429496 ms 211 * In FreeRTOS, please call FreeRTOS apis, never call this api. 212 * 213 * @param None 214 * 215 * @return None 216 */ 217 void ets_timer_init(void); 218 219 /** 220 * @brief In FreeRTOS, please call FreeRTOS apis, never call this api. 221 * 222 * @param None 223 * 224 * @return None 225 */ 226 void ets_timer_deinit(void); 227 228 /** 229 * @brief Arm an ets timer, this timer range is 640 us to 429496 ms. 230 * In FreeRTOS, please call FreeRTOS apis, never call this api. 231 * 232 * @param ETSTimer *timer : Timer struct pointer. 233 * 234 * @param uint32_t tmout : Timer value in ms, range is 1 to 429496. 235 * 236 * @param bool repeat : Timer is periodic repeated. 237 * 238 * @return None 239 */ 240 void ets_timer_arm(ETSTimer *timer, uint32_t tmout, bool repeat); 241 242 /** 243 * @brief Arm an ets timer, this timer range is 640 us to 429496 ms. 244 * In FreeRTOS, please call FreeRTOS apis, never call this api. 245 * 246 * @param ETSTimer *timer : Timer struct pointer. 247 * 248 * @param uint32_t tmout : Timer value in us, range is 1 to 429496729. 249 * 250 * @param bool repeat : Timer is periodic repeated. 251 * 252 * @return None 253 */ 254 void ets_timer_arm_us(ETSTimer *ptimer, uint32_t us, bool repeat); 255 256 /** 257 * @brief Disarm an ets timer. 258 * In FreeRTOS, please call FreeRTOS apis, never call this api. 259 * 260 * @param ETSTimer *timer : Timer struct pointer. 261 * 262 * @return None 263 */ 264 void ets_timer_disarm(ETSTimer *timer); 265 266 /** 267 * @brief Set timer callback and argument. 268 * In FreeRTOS, please call FreeRTOS apis, never call this api. 269 * 270 * @param ETSTimer *timer : Timer struct pointer. 271 * 272 * @param ETSTimerFunc *pfunction : Timer callback. 273 * 274 * @param void *parg : Timer callback argument. 275 * 276 * @return None 277 */ 278 void ets_timer_setfn(ETSTimer *ptimer, ETSTimerFunc *pfunction, void *parg); 279 280 /** 281 * @brief Unset timer callback and argument to NULL. 282 * In FreeRTOS, please call FreeRTOS apis, never call this api. 283 * 284 * @param ETSTimer *timer : Timer struct pointer. 285 * 286 * @return None 287 */ 288 void ets_timer_done(ETSTimer *ptimer); 289 290 /** 291 * @brief CPU do while loop for some time. 292 * In FreeRTOS task, please call FreeRTOS apis. 293 * 294 * @param uint32_t us : Delay time in us. 295 * 296 * @return None 297 */ 298 void ets_delay_us(uint32_t us); 299 300 /** 301 * @brief Set the real CPU ticks per us to the ets, so that ets_delay_us will be accurate. 302 * Call this function when CPU frequency is changed. 303 * 304 * @param uint32_t ticks_per_us : CPU ticks per us. 305 * 306 * @return None 307 */ 308 void ets_update_cpu_frequency(uint32_t ticks_per_us); 309 310 311 312 /** 313 * @brief Get the real CPU ticks per us to the ets. 314 * 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. 315 * 316 * @param None 317 * 318 * @return uint32_t : CPU ticks per us record in ets. 319 */ 320 uint32_t ets_get_cpu_frequency(void); 321 322 /** 323 * @brief Get xtal_freq value, If value not stored in RTC_STORE5, than store. 324 * 325 * @param None 326 * 327 * @return uint32_t : if stored in efuse(not 0) 328 * clock = ets_efuse_get_xtal_freq() * 1000000; 329 * else if analog_8M in efuse 330 * clock = ets_get_xtal_scale() * 625 / 16 * ets_efuse_get_8M_clock(); 331 * else clock = 40M. 332 */ 333 uint32_t ets_get_xtal_freq(void); 334 335 /** 336 * @brief Get the apb divisor. The xtal frequency gets divided 337 * by this value to generate the APB clock. 338 * When any types of reset happens, the default value is 2. 339 * 340 * @param None 341 * 342 * @return uint32_t : 1 or 2. 343 */ 344 uint32_t ets_get_xtal_div(void); 345 346 347 /** 348 * @brief Modifies the apb divisor. The xtal frequency gets divided by this to 349 * generate the APB clock. 350 * 351 * @note The xtal frequency divisor is 2 by default as the glitch detector 352 * doesn't properly stop glitches when it is 1. Please do not set the 353 * divisor to 1 before the PLL is active without being aware that you 354 * may be introducing a security risk. 355 * 356 * @param div Divisor. 1 = xtal freq, 2 = 1/2th xtal freq. 357 */ 358 void ets_set_xtal_div(int div); 359 360 361 /** 362 * @brief Get apb_freq value, If value not stored in RTC_STORE5, than store. 363 * 364 * @param None 365 * 366 * @return uint32_t : if rtc store the value (RTC_STORE5 high 16 bits and low 16 bits with same value), read from rtc register. 367 * clock = (REG_READ(RTC_STORE5) & 0xffff) << 12; 368 * else store ets_get_detected_xtal_freq() in. 369 */ 370 uint32_t ets_get_apb_freq(void); 371 372 /** 373 * @} 374 */ 375 376 /** \defgroup ets_intr_apis, ets interrupt configure related apis 377 * @brief ets intr apis 378 */ 379 380 /** @addtogroup ets_intr_apis 381 * @{ 382 */ 383 384 typedef void (* ets_isr_t)(void *);/**< interrupt handler type*/ 385 386 /** 387 * @brief Attach a interrupt handler to a CPU interrupt number. 388 * This function equals to _xtos_set_interrupt_handler_arg(i, func, arg). 389 * In FreeRTOS, please call FreeRTOS apis, never call this api. 390 * 391 * @param int i : CPU interrupt number. 392 * 393 * @param ets_isr_t func : Interrupt handler. 394 * 395 * @param void *arg : argument of the handler. 396 * 397 * @return None 398 */ 399 void ets_isr_attach(int i, ets_isr_t func, void *arg); 400 401 /** 402 * @brief Mask the interrupts which show in mask bits. 403 * This function equals to _xtos_ints_off(mask). 404 * In FreeRTOS, please call FreeRTOS apis, never call this api. 405 * 406 * @param uint32_t mask : BIT(i) means mask CPU interrupt number i. 407 * 408 * @return None 409 */ 410 void ets_isr_mask(uint32_t mask); 411 412 /** 413 * @brief Unmask the interrupts which show in mask bits. 414 * This function equals to _xtos_ints_on(mask). 415 * In FreeRTOS, please call FreeRTOS apis, never call this api. 416 * 417 * @param uint32_t mask : BIT(i) means mask CPU interrupt number i. 418 * 419 * @return None 420 */ 421 void ets_isr_unmask(uint32_t unmask); 422 423 /** 424 * @brief Lock the interrupt to level 2. 425 * This function direct set the CPU registers. 426 * In FreeRTOS, please call FreeRTOS apis, never call this api. 427 * 428 * @param None 429 * 430 * @return None 431 */ 432 void ets_intr_lock(void); 433 434 /** 435 * @brief Unlock the interrupt to level 0. 436 * This function direct set the CPU registers. 437 * In FreeRTOS, please call FreeRTOS apis, never call this api. 438 * 439 * @param None 440 * 441 * @return None 442 */ 443 void ets_intr_unlock(void); 444 445 /** 446 * @brief Unlock the interrupt to level 0, and CPU will go into power save mode(wait interrupt). 447 * This function direct set the CPU registers. 448 * In FreeRTOS, please call FreeRTOS apis, never call this api. 449 * 450 * @param None 451 * 452 * @return None 453 */ 454 void ets_waiti0(void); 455 456 /** 457 * @brief Attach an CPU interrupt to a hardware source. 458 * We have 4 steps to use an interrupt: 459 * 1.Attach hardware interrupt source to CPU. intr_matrix_set(0, ETS_WIFI_MAC_INTR_SOURCE, ETS_WMAC_INUM); 460 * 2.Set interrupt handler. xt_set_interrupt_handler(ETS_WMAC_INUM, func, NULL); 461 * 3.Enable interrupt for CPU. xt_ints_on(1 << ETS_WMAC_INUM); 462 * 4.Enable interrupt in the module. 463 * 464 * @param int cpu_no : The CPU which the interrupt number belongs. 465 * 466 * @param uint32_t model_num : The interrupt hardware source number, please see the interrupt hardware source table. 467 * 468 * @param uint32_t intr_num : The interrupt number CPU, please see the interrupt cpu using table. 469 * 470 * @return None 471 */ 472 void intr_matrix_set(int cpu_no, uint32_t model_num, uint32_t intr_num); 473 474 #define _ETSTR(v) # v 475 #define _ETS_SET_INTLEVEL(intlevel) ({ unsigned __tmp; \ 476 __asm__ __volatile__( "rsil %0, " _ETSTR(intlevel) "\n" \ 477 : "=a" (__tmp) : : "memory" ); \ 478 }) 479 480 #ifdef CONFIG_NONE_OS 481 #define ETS_INTR_LOCK() \ 482 ets_intr_lock() 483 484 #define ETS_INTR_UNLOCK() \ 485 ets_intr_unlock() 486 487 #define ETS_ISR_ATTACH \ 488 ets_isr_attach 489 490 #define ETS_INTR_ENABLE(inum) \ 491 ets_isr_unmask((1<<inum)) 492 493 #define ETS_INTR_DISABLE(inum) \ 494 ets_isr_mask((1<<inum)) 495 496 #define ETS_WMAC_INTR_ATTACH(func, arg) \ 497 ETS_ISR_ATTACH(ETS_WMAC_INUM, (func), (void *)(arg)) 498 499 #define ETS_TG0_T0_INTR_ATTACH(func, arg) \ 500 ETS_ISR_ATTACH(ETS_TG0_T0_INUM, (func), (void *)(arg)) 501 502 #define ETS_GPIO_INTR_ATTACH(func, arg) \ 503 ETS_ISR_ATTACH(ETS_GPIO_INUM, (func), (void *)(arg)) 504 505 #define ETS_UART0_INTR_ATTACH(func, arg) \ 506 ETS_ISR_ATTACH(ETS_UART0_INUM, (func), (void *)(arg)) 507 508 #define ETS_WDT_INTR_ATTACH(func, arg) \ 509 ETS_ISR_ATTACH(ETS_WDT_INUM, (func), (void *)(arg)) 510 511 #define ETS_SLC_INTR_ATTACH(func, arg) \ 512 ETS_ISR_ATTACH(ETS_SLC_INUM, (func), (void *)(arg)) 513 514 #define ETS_BB_INTR_ENABLE() \ 515 ETS_INTR_ENABLE(ETS_BB_INUM) 516 517 #define ETS_BB_INTR_DISABLE() \ 518 ETS_INTR_DISABLE(ETS_BB_INUM) 519 520 #define ETS_UART0_INTR_ENABLE() \ 521 ETS_INTR_ENABLE(ETS_UART0_INUM) 522 523 #define ETS_UART0_INTR_DISABLE() \ 524 ETS_INTR_DISABLE(ETS_UART0_INUM) 525 526 #define ETS_GPIO_INTR_ENABLE() \ 527 ETS_INTR_ENABLE(ETS_GPIO_INUM) 528 529 #define ETS_GPIO_INTR_DISABLE() \ 530 ETS_INTR_DISABLE(ETS_GPIO_INUM) 531 532 #define ETS_WDT_INTR_ENABLE() \ 533 ETS_INTR_ENABLE(ETS_WDT_INUM) 534 535 #define ETS_WDT_INTR_DISABLE() \ 536 ETS_INTR_DISABLE(ETS_WDT_INUM) 537 538 #define ETS_TG0_T0_INTR_ENABLE() \ 539 ETS_INTR_ENABLE(ETS_TG0_T0_INUM) 540 541 #define ETS_TG0_T0_INTR_DISABLE() \ 542 ETS_INTR_DISABLE(ETS_TG0_T0_INUM) 543 544 #define ETS_SLC_INTR_ENABLE() \ 545 ETS_INTR_ENABLE(ETS_SLC_INUM) 546 547 #define ETS_SLC_INTR_DISABLE() \ 548 ETS_INTR_DISABLE(ETS_SLC_INUM) 549 #endif 550 551 /** 552 * @} 553 */ 554 555 #ifndef MAC2STR 556 #define MAC2STR(a) (a)[0], (a)[1], (a)[2], (a)[3], (a)[4], (a)[5] 557 #define MACSTR "%02x:%02x:%02x:%02x:%02x:%02x" 558 #endif 559 560 #define ETS_MEM_BAR() asm volatile ( "" : : : "memory" ) 561 562 #ifdef ESP_PLATFORM 563 // Remove in IDF v6.0 (IDF-7044) 564 typedef enum { 565 OK = 0, 566 FAIL, 567 PENDING, 568 BUSY, 569 CANCEL, 570 } STATUS __attribute__((deprecated("Use ETS_STATUS instead"))); 571 #endif 572 573 /** 574 * @} 575 */ 576 577 #ifdef __cplusplus 578 } 579 #endif 580 581 #endif /* _ROM_ETS_SYS_H_ */ 582
