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