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