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