1 /*
2  * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef _ROM_ETS_SYS_H_
8 #define _ROM_ETS_SYS_H_
9 
10 #include <stdint.h>
11 #include <stdbool.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   * @}
97   */
98 
99 /** \defgroup ets_printf_apis, ets_printf related apis used in ets
100   * @brief ets printf apis
101   */
102 
103 /** @addtogroup ets_printf_apis
104   * @{
105   */
106 
107 /**
108   * @brief  Printf the strings to uart or other devices, similar with printf, simple than printf.
109   *         Can not print float point data format, or longlong data format.
110   *         So we maybe only use this in ROM.
111   *
112   * @param  const char *fmt : See printf.
113   *
114   * @param  ... : See printf.
115   *
116   * @return int : the length printed to the output device.
117   */
118 int ets_printf(const char *fmt, ...);
119 
120 /**
121   * @brief Get the uart channel of ets_printf(uart_tx_one_char).
122   *
123   * @return uint8_t uart channel used by ets_printf(uart_tx_one_char).
124   */
125 uint8_t ets_get_printf_channel(void);
126 
127 /**
128   * @brief  Ets_printf have two output functions: putc1 and putc2, both of which will be called if need ouput.
129   *         To install putc1, which is defaulted installed as ets_write_char_uart in none silent boot mode, as NULL in silent mode.
130   *
131   * @param  void (*)(char) p: Output function to install.
132   *
133   * @return None
134   */
135 void ets_install_putc1(void (*p)(char c));
136 
137 /**
138   * @brief  Ets_printf have two output functions: putc1 and putc2, both of which will be called if need ouput.
139   *         To install putc2, which is defaulted installed as NULL.
140   *
141   * @param  void (*)(char) p: Output function to install.
142   *
143   * @return None
144   */
145 void ets_install_putc2(void (*p)(char c));
146 
147 /**
148   * @brief  Install putc1 as ets_write_char_uart.
149   *         In silent boot mode(to void interfere the UART attached MCU), we can call this function, after booting ok.
150   *
151   * @param  None
152   *
153   * @return None
154   */
155 void ets_install_uart_printf(void);
156 
157 #define ETS_PRINTF(...) ets_printf(...)
158 
159 #define ETS_ASSERT(v) do { \
160     if (!(v)) {             \
161         ets_printf("%s %u \n", __FILE__, __LINE__); \
162         while (1) {};   \
163     }                   \
164 } while (0);
165 
166 /**
167   * @}
168   */
169 
170 /** \defgroup ets_timer_apis, ets_timer related apis used in ets
171   * @brief ets timer apis
172   */
173 
174 /** @addtogroup ets_timer_apis
175   * @{
176   */
177 typedef void ETSTimerFunc(void *timer_arg);/**< timer handler*/
178 
179 typedef struct _ETSTIMER_ {
180     struct _ETSTIMER_    *timer_next;   /**< timer linker*/
181     uint32_t              timer_expire; /**< abstruct time when timer expire*/
182     uint32_t              timer_period; /**< timer period, 0 means timer is not periodic repeated*/
183     ETSTimerFunc         *timer_func;   /**< timer handler*/
184     void                 *timer_arg;    /**< timer handler argument*/
185 } ETSTimer;
186 
187 /**
188   * @brief  Init ets timer, this timer range is 640 us to 429496 ms
189   *         In FreeRTOS, please call FreeRTOS apis, never call this api.
190   *
191   * @param  None
192   *
193   * @return None
194   */
195 void ets_timer_init(void);
196 
197 /**
198   * @brief  In FreeRTOS, please call FreeRTOS apis, never call this api.
199   *
200   * @param  None
201   *
202   * @return None
203   */
204 void ets_timer_deinit(void);
205 
206 /**
207   * @brief  Arm an ets timer, this timer range is 640 us to 429496 ms.
208   *         In FreeRTOS, please call FreeRTOS apis, never call this api.
209   *
210   * @param  ETSTimer *timer : Timer struct pointer.
211   *
212   * @param  uint32_t tmout : Timer value in ms, range is 1 to 429496.
213   *
214   * @param  bool repeat : Timer is periodic repeated.
215   *
216   * @return None
217   */
218 void ets_timer_arm(ETSTimer *timer, uint32_t tmout, bool repeat);
219 
220 /**
221   * @brief  Arm an ets timer, this timer range is 640 us to 429496 ms.
222   *         In FreeRTOS, please call FreeRTOS apis, never call this api.
223   *
224   * @param  ETSTimer *timer : Timer struct pointer.
225   *
226   * @param  uint32_t tmout : Timer value in us, range is 1 to 429496729.
227   *
228   * @param  bool repeat : Timer is periodic repeated.
229   *
230   * @return None
231   */
232 void ets_timer_arm_us(ETSTimer *ptimer, uint32_t us, bool repeat);
233 
234 /**
235   * @brief  Disarm an ets timer.
236   *         In FreeRTOS, please call FreeRTOS apis, never call this api.
237   *
238   * @param  ETSTimer *timer : Timer struct pointer.
239   *
240   * @return None
241   */
242 void ets_timer_disarm(ETSTimer *timer);
243 
244 /**
245   * @brief  Set timer callback and argument.
246   *         In FreeRTOS, please call FreeRTOS apis, never call this api.
247   *
248   * @param  ETSTimer *timer : Timer struct pointer.
249   *
250   * @param  ETSTimerFunc *pfunction : Timer callback.
251   *
252   * @param  void *parg : Timer callback argument.
253   *
254   * @return None
255   */
256 void ets_timer_setfn(ETSTimer *ptimer, ETSTimerFunc *pfunction, void *parg);
257 
258 /**
259   * @brief  Unset timer callback and argument to NULL.
260   *         In FreeRTOS, please call FreeRTOS apis, never call this api.
261   *
262   * @param  ETSTimer *timer : Timer struct pointer.
263   *
264   * @return None
265   */
266 void ets_timer_done(ETSTimer *ptimer);
267 
268 /**
269   * @brief  CPU do while loop for some time.
270   *         In FreeRTOS task, please call FreeRTOS apis.
271   *
272   * @param  uint32_t us : Delay time in us.
273   *
274   * @return None
275   */
276 void ets_delay_us(uint32_t us);
277 
278 /**
279   * @brief  Set the real CPU ticks per us to the ets, so that ets_delay_us will be accurate.
280   *         Call this function when CPU frequency is changed.
281   *
282   * @param  uint32_t ticks_per_us : CPU ticks per us.
283   *
284   * @return None
285   */
286 void ets_update_cpu_frequency(uint32_t ticks_per_us);
287 
288 
289 
290 /**
291   * @brief  Get the real CPU ticks per us to the ets.
292   *         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.
293   *
294   * @param  None
295   *
296   * @return uint32_t : CPU ticks per us record in ets.
297   */
298 uint32_t ets_get_cpu_frequency(void);
299 
300 /**
301   * @brief  Get xtal_freq value, If value not stored in RTC_STORE5, than store.
302   *
303   * @param  None
304   *
305   * @return uint32_t : if stored in efuse(not 0)
306   *                         clock = ets_efuse_get_xtal_freq() * 1000000;
307   *                    else if analog_8M in efuse
308   *                         clock = ets_get_xtal_scale() * 625 / 16 * ets_efuse_get_8M_clock();
309   *                    else clock = 40M.
310   */
311 uint32_t ets_get_xtal_freq(void);
312 
313 /**
314   * @brief  Get the apb divior by xtal frequency.
315   *         When any types of reset happen, the default value is 2.
316   *
317   * @param  None
318   *
319   * @return uint32_t : 1 or 2.
320   */
321 uint32_t ets_get_xtal_div(void);
322 
323 /**
324   * @brief  Get apb_freq value, If value not stored in RTC_STORE5, than store.
325   *
326   * @param  None
327   *
328   * @return uint32_t : if rtc store the value (RTC_STORE5 high 16 bits and low 16 bits with same value), read from rtc register.
329   *                         clock = (REG_READ(RTC_STORE5) & 0xffff) << 12;
330   *                    else store ets_get_detected_xtal_freq() in.
331   */
332 uint32_t ets_get_apb_freq(void);
333 
334 /**
335   * @}
336   */
337 
338 /** \defgroup ets_intr_apis, ets interrupt configure related apis
339   * @brief ets intr apis
340   */
341 
342 /** @addtogroup ets_intr_apis
343   * @{
344   */
345 
346 typedef void (* ets_isr_t)(void *);/**< interrupt handler type*/
347 
348 /**
349   * @brief  Attach a interrupt handler to a CPU interrupt number.
350   *         This function equals to _xtos_set_interrupt_handler_arg(i, func, arg).
351   *         In FreeRTOS, please call FreeRTOS apis, never call this api.
352   *
353   * @param  int i : CPU interrupt number.
354   *
355   * @param  ets_isr_t func : Interrupt handler.
356   *
357   * @param  void *arg : argument of the handler.
358   *
359   * @return None
360   */
361 void ets_isr_attach(int i, ets_isr_t func, void *arg);
362 
363 /**
364   * @brief  Mask the interrupts which show in mask bits.
365   *         This function equals to _xtos_ints_off(mask).
366   *         In FreeRTOS, please call FreeRTOS apis, never call this api.
367   *
368   * @param  uint32_t mask : BIT(i) means mask CPU interrupt number i.
369   *
370   * @return None
371   */
372 void ets_isr_mask(uint32_t mask);
373 
374 /**
375   * @brief  Unmask the interrupts which show in mask bits.
376   *         This function equals to _xtos_ints_on(mask).
377   *         In FreeRTOS, please call FreeRTOS apis, never call this api.
378   *
379   * @param  uint32_t mask : BIT(i) means mask CPU interrupt number i.
380   *
381   * @return None
382   */
383 void ets_isr_unmask(uint32_t unmask);
384 
385 /**
386   * @brief  Lock the interrupt to level 2.
387   *         This function direct set the CPU registers.
388   *         In FreeRTOS, please call FreeRTOS apis, never call this api.
389   *
390   * @param  None
391   *
392   * @return None
393   */
394 void ets_intr_lock(void);
395 
396 /**
397   * @brief  Unlock the interrupt to level 0.
398   *         This function direct set the CPU registers.
399   *         In FreeRTOS, please call FreeRTOS apis, never call this api.
400   *
401   * @param  None
402   *
403   * @return None
404   */
405 void ets_intr_unlock(void);
406 
407 /**
408   * @brief  Attach an CPU interrupt to a hardware source.
409   *         We have 4 steps to use an interrupt:
410   *         1.Attach hardware interrupt source to CPU.  intr_matrix_set(0, ETS_WIFI_MAC_INTR_SOURCE, ETS_WMAC_INUM);
411   *         2.Set interrupt handler.                    xt_set_interrupt_handler(ETS_WMAC_INUM, func, NULL);
412   *         3.Enable interrupt for CPU.                 xt_ints_on(1 << ETS_WMAC_INUM);
413   *         4.Enable interrupt in the module.
414   *
415   * @param  int cpu_no : The CPU which the interrupt number belongs.
416   *
417   * @param  uint32_t model_num : The interrupt hardware source number, please see the interrupt hardware source table.
418   *
419   * @param  uint32_t intr_num : The interrupt number CPU, please see the interrupt cpu using table.
420   *
421   * @return None
422   */
423 void intr_matrix_set(int cpu_no, uint32_t model_num, uint32_t intr_num);
424 
425 /**
426   * @}
427   */
428 
429 #ifndef MAC2STR
430 #define MAC2STR(a) (a)[0], (a)[1], (a)[2], (a)[3], (a)[4], (a)[5]
431 #define MACSTR "%02x:%02x:%02x:%02x:%02x:%02x"
432 #endif
433 
434 #define ETS_MEM_BAR() asm volatile ( "" : : : "memory" )
435 
436 #ifdef ESP_PLATFORM
437 // Remove in IDF v6.0 (IDF-7044)
438 typedef enum {
439     OK = 0,
440     FAIL,
441     PENDING,
442     BUSY,
443     CANCEL,
444 } STATUS __attribute__((deprecated("Use ETS_STATUS instead")));
445 #endif
446 
447 /**
448   * @}
449   */
450 
451 #ifdef __cplusplus
452 }
453 #endif
454 
455 #endif /* _ROM_ETS_SYS_H_ */
456