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