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