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