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