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