ChibiOS/NIL  3.2.2
ch.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio.
3 
4  This file is part of ChibiOS.
5 
6  ChibiOS is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 3 of the License, or
9  (at your option) any later version.
10 
11  ChibiOS is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  GNU General Public License for more details.
15 
16  You should have received a copy of the GNU General Public License
17  along with this program. If not, see <http://www.gnu.org/licenses/>.
18 */
19 
20 /**
21  * @file nil/include/ch.h
22  * @brief Nil RTOS main header file.
23  * @details This header includes all the required kernel headers so it is the
24  * only header you usually need to include in your application.
25  *
26  * @addtogroup NIL_KERNEL
27  * @{
28  */
29 
30 #ifndef CH_H
31 #define CH_H
32 
33 #include "chtypes.h"
34 #include "chconf.h"
35 #include "chlicense.h"
36 
37 /*===========================================================================*/
38 /* Module constants. */
39 /*===========================================================================*/
40 
41 /**
42  * @brief ChibiOS/NIL identification macro.
43  */
44 #define _CHIBIOS_NIL_
45 
46 /**
47  * @brief Stable release flag.
48  */
49 #define CH_KERNEL_STABLE 1
50 
51 /**
52  * @name ChibiOS/NIL version identification
53  * @{
54  */
55 /**
56  * @brief Kernel version string.
57  */
58 #define CH_KERNEL_VERSION "3.2.2"
59 
60 /**
61  * @brief Kernel version major number.
62  */
63 #define CH_KERNEL_MAJOR 3
64 
65 /**
66  * @brief Kernel version minor number.
67  */
68 #define CH_KERNEL_MINOR 2
69 
70 /**
71  * @brief Kernel version patch number.
72  */
73 #define CH_KERNEL_PATCH 2
74 /** @} */
75 
76 /**
77  * @name Constants for configuration options
78  */
79 /**
80  * @brief Generic 'false' preprocessor boolean constant.
81  * @note It is meant to be used in configuration files as switch.
82  */
83 #if !defined(FALSE) || defined(__DOXYGEN__)
84 #define FALSE 0
85 #endif
86 
87 /**
88  * @brief Generic 'true' preprocessor boolean constant.
89  * @note It is meant to be used in configuration files as switch.
90  */
91 #if !defined(TRUE) || defined(__DOXYGEN__)
92 #define TRUE 1
93 #endif
94 /** @} */
95 
96 /**
97  * @name Wakeup messages
98  * @{
99  */
100 #define MSG_OK (msg_t)0 /**< @brief OK wakeup message. */
101 #define MSG_TIMEOUT (msg_t)-1 /**< @brief Wake-up caused by
102  a timeout condition. */
103 #define MSG_RESET (msg_t)-2 /**< @brief Wake-up caused by
104  a reset condition. */
105 /** @} */
106 
107 /**
108  * @name Special time constants
109  * @{
110  */
111 /**
112  * @brief Zero time specification for some functions with a timeout
113  * specification.
114  * @note Not all functions accept @p TIME_IMMEDIATE as timeout parameter,
115  * see the specific function documentation.
116  */
117 #define TIME_IMMEDIATE ((sysinterval_t)-1)
118 
119 /**
120  * @brief Infinite time specification for all functions with a timeout
121  * specification.
122  */
123 #define TIME_INFINITE ((sysinterval_t)0)
124 
125 /**
126  * @brief Maximum interval constant usable as timeout.
127  */
128 #define TIME_MAX_INTERVAL ((sysinterval_t)-2)
129 
130 /**
131  * @brief Maximum system of system time before it wraps.
132  */
133 #define TIME_MAX_SYSTIME ((systime_t)-1)
134 /** @} */
136 /**
137  * @name Thread state related macros
138  * @{
139  */
140 #define NIL_STATE_READY (tstate_t)0 /**< @brief Thread ready or
141  executing. */
142 #define NIL_STATE_SLEEPING (tstate_t)1 /**< @brief Thread sleeping. */
143 #define NIL_STATE_SUSP (tstate_t)2 /**< @brief Thread suspended. */
144 #define NIL_STATE_WTQUEUE (tstate_t)3 /**< @brief On queue or semaph. */
145 #define NIL_STATE_WTOREVT (tstate_t)4 /**< @brief Waiting for events. */
146 #define NIL_THD_IS_READY(tp) ((tp)->state == NIL_STATE_READY)
147 #define NIL_THD_IS_SLEEPING(tp) ((tp)->state == NIL_STATE_SLEEPING)
148 #define NIL_THD_IS_SUSP(tp) ((tp)->state == NIL_STATE_SUSP)
149 #define NIL_THD_IS_WTQUEUE(tp) ((tp)->state == NIL_STATE_WTQUEUE)
150 #define NIL_THD_IS_WTOREVT(tp) ((tp)->state == NIL_STATE_WTOREVT)
151 /** @} */
152 
153 /**
154  * @name Events related macros
155  * @{
156  */
157 /**
158  * @brief All events allowed mask.
159  */
160 #define ALL_EVENTS ((eventmask_t)-1)
161 
162 /**
163  * @brief Returns an event mask from an event identifier.
164  */
165 #define EVENT_MASK(eid) ((eventmask_t)(1 << (eid)))
166 /** @} */
167 
168 /*===========================================================================*/
169 /* Module pre-compile time settings. */
170 /*===========================================================================*/
171 
172 /*-*
173  * @brief Number of user threads in the application.
174  * @note This number is not inclusive of the idle thread which is
175  * implicitly handled.
176  */
177 #if !defined(CH_CFG_NUM_THREADS) || defined(__DOXYGEN__)
178 #define CH_CFG_NUM_THREADS 2
179 #endif
180 
181 /*-*
182  * @brief System time counter resolution.
183  * @note Allowed values are 16 or 32 bits.
184  */
185 #if !defined(CH_CFG_ST_RESOLUTION) || defined(__DOXYGEN__)
186 #define CH_CFG_ST_RESOLUTION 32
187 #endif
188 
189 /*-*
190  * @brief System tick frequency.
191  * @note This value together with the @p CH_CFG_ST_RESOLUTION
192  * option defines the maximum amount of time allowed for
193  * timeouts.
194  */
195 #if !defined(CH_CFG_ST_FREQUENCY) || defined(__DOXYGEN__)
196 #define CH_CFG_ST_FREQUENCY 100
197 #endif
198 
199 /*-*
200  * @brief Time delta constant for the tick-less mode.
201  * @note If this value is zero then the system uses the classic
202  * periodic tick. This value represents the minimum number
203  * of ticks that is safe to specify in a timeout directive.
204  * The value one is not valid, timeouts are rounded up to
205  * this value.
206  */
207 #if !defined(CH_CFG_ST_TIMEDELTA) || defined(__DOXYGEN__)
208 #define CH_CFG_ST_TIMEDELTA 0
209 #endif
210 
211 /*-*
212  * @brief Semaphores APIs.
213  * @details If enabled then the Semaphores APIs are included in the kernel.
214  *
215  * @note The default is @p TRUE.
216  */
217 #if !defined(CH_CFG_USE_SEMAPHORES) || defined(__DOXYGEN__)
218 #define CH_CFG_USE_SEMAPHORES TRUE
219 #endif
220 
221 /*-*
222  * @brief Mutexes APIs.
223  * @details If enabled then the mutexes APIs are included in the kernel.
224  *
225  * @note Feature not currently implemented.
226  * @note The default is @p FALSE.
227  */
228 #if !defined(CH_CFG_USE_MUTEXES) || defined(__DOXYGEN__)
229 #define CH_CFG_USE_MUTEXES FALSE
230 #endif
231 
232 /*-*
233  * @brief Events Flags APIs.
234  * @details If enabled then the event flags APIs are included in the kernel.
235  *
236  * @note The default is @p TRUE.
237  */
238 #if !defined(CH_CFG_USE_EVENTS) || defined(__DOXYGEN__)
239 #define CH_CFG_USE_EVENTS TRUE
240 #endif
241 
242 /*-*
243  * @brief Mailboxes APIs.
244  * @details If enabled then the asynchronous messages (mailboxes) APIs are
245  * included in the kernel.
246  *
247  * @note The default is @p TRUE.
248  * @note Requires @p CH_CFG_USE_SEMAPHORES.
249  */
250 #if !defined(CH_CFG_USE_MAILBOXES) || defined(__DOXYGEN__)
251 #define CH_CFG_USE_MAILBOXES TRUE
252 #endif
253 
254 /*-*
255  * @brief Core Memory Manager APIs.
256  * @details If enabled then the core memory manager APIs are included
257  * in the kernel.
258  *
259  * @note The default is @p TRUE.
260  */
261 #if !defined(CH_CFG_USE_MEMCORE) || defined(__DOXYGEN__)
262 #define CH_CFG_USE_MEMCORE TRUE
263 #endif
264 
265 /*-*
266  * @brief Heap Allocator APIs.
267  * @details If enabled then the memory heap allocator APIs are included
268  * in the kernel.
269  *
270  * @note The default is @p TRUE.
271  */
272 #if !defined(CH_CFG_USE_HEAP) || defined(__DOXYGEN__)
273 #define CH_CFG_USE_HEAP TRUE
274 #endif
275 
276 /*-*
277  * @brief Memory Pools Allocator APIs.
278  * @details If enabled then the memory pools allocator APIs are included
279  * in the kernel.
280  *
281  * @note The default is @p TRUE.
282  */
283 #if !defined(CH_CFG_USE_MEMPOOLS) || defined(__DOXYGEN__)
284 #define CH_CFG_USE_MEMPOOLS TRUE
285 #endif
286 /**
287  * @brief Objects Factory APIs.
288  * @details If enabled then the objects factory APIs are included in the
289  * kernel.
290  *
291  * @note The default is @p FALSE.
292  */
293 #if !defined(CH_CFG_USE_FACTORY) || defined(__DOXYGEN__)
294 #define CH_CFG_USE_FACTORY TRUE
295 #endif
296 
297 /**
298  * @brief Maximum length for object names.
299  * @details If the specified length is zero then the name is stored by
300  * pointer but this could have unintended side effects.
301  */
302 #if !defined(CH_CFG_FACTORY_MAX_NAMES_LENGTH) || defined(__DOXYGEN__)
303 #define CH_CFG_FACTORY_MAX_NAMES_LENGTH 8
304 #endif
305 
306 /**
307  * @brief Enables the registry of generic objects.
308  */
309 #if !defined(CH_CFG_FACTORY_OBJECTS_REGISTRY) || defined(__DOXYGEN__)
310 #define CH_CFG_FACTORY_OBJECTS_REGISTRY TRUE
311 #endif
312 
313 /**
314  * @brief Enables factory for generic buffers.
315  */
316 #if !defined(CH_CFG_FACTORY_GENERIC_BUFFERS) || defined(__DOXYGEN__)
317 #define CH_CFG_FACTORY_GENERIC_BUFFERS TRUE
318 #endif
319 
320 /**
321  * @brief Enables factory for semaphores.
322  */
323 #if !defined(CH_CFG_FACTORY_SEMAPHORES) || defined(__DOXYGEN__)
324 #define CH_CFG_FACTORY_SEMAPHORES TRUE
325 #endif
326 
327 /**
328  * @brief Enables factory for mailboxes.
329  */
330 #if !defined(CH_CFG_FACTORY_MAILBOXES) || defined(__DOXYGEN__)
331 #define CH_CFG_FACTORY_MAILBOXES TRUE
332 #endif
333 
334 /**
335  * @brief Enables factory for objects FIFOs.
336  */
337 #if !defined(CH_CFG_FACTORY_OBJ_FIFOS) || defined(__DOXYGEN__)
338 #define CH_CFG_FACTORY_OBJ_FIFOS TRUE
339 #endif
340 
341 /*-*
342  * @brief Debug option, kernel statistics.
343  *
344  * @note Feature not currently implemented.
345  * @note The default is @p FALSE.
346  */
347 #if !defined(CH_DBG_STATISTICS) || defined(__DOXYGEN__)
348 #define CH_DBG_STATISTICS FALSE
349 #endif
350 
351 /*-*
352  * @brief Debug option, system state check.
353  * @note This is a planned feature, not yet implemented.
354  *
355  * @note The default is @p FALSE.
356  */
357 #if !defined(CH_DBG_SYSTEM_STATE_CHECK) || defined(__DOXYGEN__)
358 #define CH_DBG_SYSTEM_STATE_CHECK FALSE
359 #endif
360 
361 /*-*
362  * @brief Debug option, parameters checks.
363  *
364  * @note The default is @p FALSE.
365  */
366 #if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
367 #define CH_DBG_ENABLE_CHECKS FALSE
368 #endif
369 
370 /*-*
371  * @brief System assertions.
372  *
373  * @note The default is @p FALSE.
374  */
375 #if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
376 #define CH_DBG_ENABLE_ASSERTS FALSE
377 #endif
378 
379 /*-*
380  * @brief Stack check.
381  *
382  * @note The default is @p FALSE.
383  */
384 #if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
385 #define CH_DBG_ENABLE_STACK_CHECK FALSE
386 #endif
387 
388 /*-*
389  * @brief System initialization hook.
390  */
391 #if !defined(CH_CFG_SYSTEM_INIT_HOOK) || defined(__DOXYGEN__)
392 #define CH_CFG_SYSTEM_INIT_HOOK() {}
393 #endif
394 
395 /*-*
396  * @brief Threads descriptor structure extension.
397  * @details User fields added to the end of the @p thread_t structure.
398  */
399 #if !defined(CH_CFG_THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
400 #define CH_CFG_THREAD_EXT_FIELDS
401 #endif
402 
403 /*-*
404  * @brief Threads initialization hook.
405  */
406 #if !defined(CH_CFG_THREAD_EXT_INIT_HOOK) || defined(__DOXYGEN__)
407 #define CH_CFG_THREAD_EXT_INIT_HOOK(tp) {}
408 #endif
409 
410 /*-*
411  * @brief Idle thread enter hook.
412  * @note This hook is invoked within a critical zone, no OS functions
413  * should be invoked from here.
414  * @note This macro can be used to activate a power saving mode.
415  */
416 #if !defined(CH_CFG_IDLE_ENTER_HOOK) || defined(__DOXYGEN__)
417 #define CH_CFG_IDLE_ENTER_HOOK() {}
418 #endif
419 
420 /*-*
421  * @brief Idle thread leave hook.
422  * @note This hook is invoked within a critical zone, no OS functions
423  * should be invoked from here.
424  * @note This macro can be used to deactivate a power saving mode.
425  */
426 #if !defined(CH_CFG_IDLE_LEAVE_HOOK) || defined(__DOXYGEN__)
427 #define CH_CFG_IDLE_LEAVE_HOOK() {}
428 #endif
429 
430 /*-*
431  * @brief System halt hook.
432  */
433 #if !defined(CH_CFG_SYSTEM_HALT_HOOK) || defined(__DOXYGEN__)
434 #define CH_CFG_SYSTEM_HALT_HOOK(reason) {}
435 #endif
436 
437 /*===========================================================================*/
438 /* Derived constants and error checks. */
439 /*===========================================================================*/
440 
441 /* License checks.*/
442 #if !defined(CH_CUSTOMER_LIC_NIL) || !defined(CH_LICENSE_FEATURES)
443 #error "malformed chlicense.h"
444 #endif
445 
446 #if CH_CUSTOMER_LIC_NIL == FALSE
447 #error "ChibiOS/NIL not licensed"
448 #endif
449 
450 #if (CH_LICENSE_FEATURES != CH_FEATURES_FULL) && \
451  (CH_LICENSE_FEATURES != CH_FEATURES_INTERMEDIATE) && \
452  (CH_LICENSE_FEATURES != CH_FEATURES_BASIC)
453 #error "invalid CH_LICENSE_FEATURES setting"
454 #endif
455 
456 /* Restrictions in basic and intermediate modes.*/
457 #if (CH_LICENSE_FEATURES == CH_FEATURES_INTERMEDIATE) || \
458  (CH_LICENSE_FEATURES == CH_FEATURES_BASIC)
459 
460 /* System tick limited to 1000hz.*/
461 #if CH_CFG_ST_FREQUENCY > 1000
462 #undef CH_CFG_ST_FREQUENCY
463 #define CH_CFG_ST_FREQUENCY 1000
464 #endif
465 
466 #endif /* (CH_LICENSE_FEATURES == CH_FEATURES_INTERMEDIATE) ||
467  (CH_LICENSE_FEATURES == CH_FEATURES_BASIC) */
468 
469 /* Restrictions in basic mode.*/
470 #if CH_LICENSE_FEATURES == CH_FEATURES_BASIC
471 
472 /* Tick-Less mode restricted.*/
473 #undef CH_CFG_ST_TIMEDELTA
474 #define CH_CFG_ST_TIMEDELTA 0
475 
476 #endif /* CH_LICENSE_FEATURES == CH_FEATURES_BASIC */
477 
478 #if !defined(_CHIBIOS_NIL_CONF_)
479 #error "missing or wrong configuration file"
480 #endif
481 
482 #if !defined(_CHIBIOS_NIL_CONF_VER_3_2_)
483 #error "obsolete or unknown configuration file"
484 #endif
485 
486 #if CH_CFG_NUM_THREADS < 1
487 #error "at least one thread must be defined"
488 #endif
489 
490 #if CH_CFG_NUM_THREADS > 16
491 #error "ChibiOS/NIL is not recommended for thread-intensive applications," \
492  "consider ChibiOS/RT instead"
493 #endif
494 
495 #if (CH_CFG_ST_RESOLUTION != 16) && (CH_CFG_ST_RESOLUTION != 32)
496 #error "invalid CH_CFG_ST_RESOLUTION specified, must be 16 or 32"
497 #endif
498 
499 #if CH_CFG_ST_FREQUENCY <= 0
500 #error "invalid CH_CFG_ST_FREQUENCY specified, must be greater than zero"
501 #endif
502 
503 #if (CH_CFG_ST_TIMEDELTA < 0) || (CH_CFG_ST_TIMEDELTA == 1)
504 #error "invalid CH_CFG_ST_TIMEDELTA specified, must " \
505  "be zero or greater than one"
506 #endif
507 
508 #if CH_CFG_USE_MUTEXES == TRUE
509 #error "mutexes not yet supported"
510 #endif
511 
512 #if CH_DBG_STATISTICS == TRUE
513 #error "statistics not yet supported"
514 #endif
515 
516 #if (CH_DBG_SYSTEM_STATE_CHECK == TRUE) || \
517  (CH_DBG_ENABLE_CHECKS == TRUE) || \
518  (CH_DBG_ENABLE_ASSERTS == TRUE) || \
519  (CH_DBG_ENABLE_STACK_CHECK == TRUE)
520 #define NIL_DBG_ENABLED TRUE
521 #else
522 #define NIL_DBG_ENABLED FALSE
523 #endif
524 
525 /** Boundaries of the idle thread boundaries, only required if stack checking
526  is enabled.*/
527 #if (CH_DBG_ENABLE_STACK_CHECK == TRUE) || defined(__DOXYGEN__)
528 #define THD_IDLE_BASE (&__main_thread_stack_base__)
529 #define THD_IDLE_END (&__main_thread_stack_end__)
530 #else
531 #define THD_IDLE_BASE NULL
532 #define THD_IDLE_END NULL
533 #endif
534 
535 /*===========================================================================*/
536 /* Module data structures and types. */
537 /*===========================================================================*/
538 
539 #if (CH_CFG_ST_RESOLUTION == 32) || defined(__DOXYGEN__)
540 /**
541  * @brief Type of system time.
542  * @note It is selectable in configuration between 16 or 32 bits.
543  */
544 typedef uint32_t systime_t;
545 
546 /**
547  * @brief Type of time interval.
548  * @note It is selectable in configuration between 16 or 32 bits.
549  */
550 typedef uint32_t sysinterval_t;
551 
552 /**
553  * @brief Type of time conversion variable.
554  * @note This type must have double width than other time types, it is
555  * only used internally for conversions.
556  */
557 typedef uint64_t time_conv_t;
558 
559 #else
560 typedef uint16_t systime_t;
561 typedef uint16_t sysinterval_t;
562 typedef uint32_t time_conv_t;
563 #endif
564 
565 /**
566  * @brief Type of a structure representing a thread.
567  * @note It is required as an early definition.
568  */
569 typedef struct nil_thread thread_t;
570 
571 #include "chcore.h"
573 /**
574  * @brief Structure representing a queue of threads.
575  */
576 struct nil_threads_queue {
577  volatile cnt_t cnt; /**< @brief Threads Queue counter. */
578 };
580 /**
581  * @brief Type of a queue of threads.
582  */
583 typedef struct nil_threads_queue threads_queue_t;
584 
585 #if (CH_CFG_USE_SEMAPHORES == TRUE) || defined(__DOXYGEN__)
586 /**
587  * @brief Type of a structure representing a semaphore.
588  * @note Semaphores are implemented on thread queues, the object is the
589  * same, the behavior is slightly different.
590  */
592 #endif /* CH_CFG_USE_SEMAPHORES == TRUE */
593 
594 /**
595  * @brief Thread function.
596  */
597 typedef void (*tfunc_t)(void *p);
598 
599 /**
600  * @brief Type of a structure representing a thread static configuration.
601  */
602 typedef struct nil_thread_cfg thread_config_t;
603 
604 /**
605  * @brief Structure representing a thread static configuration.
606  */
607 struct nil_thread_cfg {
608  stkalign_t *wbase; /**< @brief Thread working area base. */
609  stkalign_t *wend; /**< @brief Thread working area end. */
610  const char *namep; /**< @brief Thread name, for debugging. */
611  tfunc_t funcp; /**< @brief Thread function. */
612  void *arg; /**< @brief Thread function argument. */
613 };
615 /**
616  * @brief Type of a thread reference.
617  */
618 typedef thread_t * thread_reference_t;
619 
620 /**
621  * @brief Structure representing a thread.
622  */
623 struct nil_thread {
624  struct port_context ctx; /**< @brief Processor context. */
625  tstate_t state; /**< @brief Thread state. */
626  /* Note, the following union contains a pointer while the thread is in a
627  sleeping state (!NIL_THD_IS_READY()) else contains the wake-up message.*/
628  union {
629  msg_t msg; /**< @brief Wake-up message. */
630  void *p; /**< @brief Generic pointer. */
631  thread_reference_t *trp; /**< @brief Pointer to thread reference.*/
632  threads_queue_t *tqp; /**< @brief Pointer to thread queue. */
633 #if (CH_CFG_USE_SEMAPHORES == TRUE) || defined(__DOXYGEN__)
634  semaphore_t *semp; /**< @brief Pointer to semaphore. */
635 #endif
636 #if (CH_CFG_USE_EVENTS == TRUE) || defined(__DOXYGEN__)
637  eventmask_t ewmask; /**< @brief Enabled events mask. */
638 #endif
639  } u1;
640  volatile sysinterval_t timeout; /**< @brief Timeout counter, zero
641  if disabled. */
642 #if (CH_CFG_USE_EVENTS == TRUE) || defined(__DOXYGEN__)
643  eventmask_t epmask; /**< @brief Pending events mask. */
644 #endif
645 #if (CH_DBG_ENABLE_STACK_CHECK == TRUE) || defined(__DOXYGEN__)
646  stkalign_t *wabase; /**< @brief Thread stack boundary. */
647 #endif
648  /* Optional extra fields.*/
650 };
651 
652 /**
653  * @brief Type of a structure representing the system.
654  */
655 typedef struct nil_system nil_system_t;
656 
657 /**
658  * @brief System data structure.
659  * @note This structure contain all the data areas used by the OS except
660  * stacks.
661  */
662 struct nil_system {
663  /**
664  * @brief Pointer to the running thread.
665  */
666  thread_t *current;
667  /**
668  * @brief Pointer to the next thread to be executed.
669  * @note This pointer must point at the same thread pointed by @p current
670  * or to an higher priority thread if a switch is required.
671  */
672  thread_t *next;
673 #if (CH_CFG_ST_TIMEDELTA == 0) || defined(__DOXYGEN__)
674  /**
675  * @brief System time.
676  */
677  volatile systime_t systime;
678 #endif
679 #if (CH_CFG_ST_TIMEDELTA > 0) || defined(__DOXYGEN__)
680  /**
681  * @brief System time of the last tick event.
682  */
683  systime_t lasttime;
684  /**
685  * @brief Time of the next scheduled tick event.
686  */
687  systime_t nexttime;
688 #endif
689 #if (CH_DBG_SYSTEM_STATE_CHECK == TRUE) || defined(__DOXYGEN__)
690  /**
691  * @brief ISR nesting level.
692  */
693  cnt_t isr_cnt;
694  /**
695  * @brief Lock nesting level.
696  */
697  cnt_t lock_cnt;
698 #endif
699 #if (NIL_DBG_ENABLED == TRUE) || defined(__DOXYGEN__)
700  /**
701  * @brief Panic message.
702  * @note This field is only present if some debug options have been
703  * activated.
704  * @note Accesses to this pointer must never be optimized out so the
705  * field itself is declared volatile.
706  */
707  const char * volatile dbg_panic_msg;
708 #endif
709  /**
710  * @brief Thread structures for all the defined threads.
711  */
712  thread_t threads[CH_CFG_NUM_THREADS + 1];
713 };
714 
715 /*===========================================================================*/
716 /* Module macros. */
717 /*===========================================================================*/
718 
719 #if CH_DBG_SYSTEM_STATE_CHECK == TRUE
720 #define _dbg_enter_lock() (nil.lock_cnt = (cnt_t)1)
721 #define _dbg_leave_lock() (nil.lock_cnt = (cnt_t)0)
722 #endif
723 
724 /**
725  * @brief Utility to make the parameter a quoted string.
726  */
727 #define __CH_STRINGIFY(a) #a
728 
729 /**
730  * @name Threads tables definition macros
731  * @{
732  */
733 /**
734  * @brief Start of user threads table.
735  */
736 #define THD_TABLE_BEGIN \
737  const thread_config_t nil_thd_configs[CH_CFG_NUM_THREADS + 1] = {
738 
739 /**
740  * @brief Entry of user threads table
741  */
742 #define THD_TABLE_ENTRY(wap, name, funcp, arg) \
743  {wap, ((stkalign_t *)(wap)) + (sizeof (wap) / sizeof(stkalign_t)), \
744  name, funcp, arg},
746 /**
747  * @brief End of user threads table.
748  */
749 #define THD_TABLE_END \
750  {THD_IDLE_BASE, THD_IDLE_END, "idle", NULL, NULL} \
751 };
752 /** @} */
753 
754 /**
755  * @name Memory alignment support macros
756  */
757 /**
758  * @brief Alignment mask constant.
759  *
760  * @param[in] a alignment, must be a power of two
761  */
762 #define MEM_ALIGN_MASK(a) ((size_t)(a) - 1U)
763 
764 /**
765  * @brief Aligns to the previous aligned memory address.
766  *
767  * @param[in] p variable to be aligned
768  * @param[in] a alignment, must be a power of two
769  */
770 #define MEM_ALIGN_PREV(p, a) ((size_t)(p) & ~MEM_ALIGN_MASK(a))
771 
772 /**
773  * @brief Aligns to the new aligned memory address.
774  *
775  * @param[in] p variable to be aligned
776  * @param[in] a alignment, must be a power of two
777  */
778 #define MEM_ALIGN_NEXT(p, a) MEM_ALIGN_PREV((size_t)(p) + \
779  MEM_ALIGN_MASK(a), (a))
780 
781 /**
782  * @brief Returns whatever a pointer or memory size is aligned.
783  *
784  * @param[in] p variable to be aligned
785  * @param[in] a alignment, must be a power of two
786  */
787 #define MEM_IS_ALIGNED(p, a) (((size_t)(p) & MEM_ALIGN_MASK(a)) == 0U)
788 
789 /**
790  * @brief Returns whatever a constant is a valid alignment.
791  * @details Valid alignments are powers of two.
792  *
793  * @param[in] a alignment to be checked, must be a constant
794  */
795 #define MEM_IS_VALID_ALIGNMENT(a) \
796  (((size_t)(a) != 0U) && (((size_t)(a) & ((size_t)(a) - 1U)) == 0U))
797 /** @} */
799 /**
800  * @name Working Areas
801  */
802 /**
803  * @brief Calculates the total Working Area size.
804  *
805  * @param[in] n the stack size to be assigned to the thread
806  * @return The total used memory in bytes.
807  *
808  * @api
809  */
810 #define THD_WORKING_AREA_SIZE(n) MEM_ALIGN_NEXT(PORT_WA_SIZE(n), \
811  PORT_STACK_ALIGN)
812 
813 /**
814  * @brief Static working area allocation.
815  * @details This macro is used to allocate a static thread working area
816  * aligned as both position and size.
817  *
818  * @param[in] s the name to be assigned to the stack array
819  * @param[in] n the stack size to be assigned to the thread
820  *
821  * @api
822  */
823 #define THD_WORKING_AREA(s, n) PORT_WORKING_AREA(s, n)
824 /** @} */
825 
826 /**
827  * @name Threads abstraction macros
828  */
829 /**
830  * @brief Thread declaration macro.
831  * @note Thread declarations should be performed using this macro because
832  * the port layer could define optimizations for thread functions.
833  */
834 #define THD_FUNCTION(tname, arg) PORT_THD_FUNCTION(tname, arg)
835 /** @} */
836 
837 /**
838  * @name ISRs abstraction macros
839  */
840 /**
841  * @brief Priority level validation macro.
842  * @details This macro determines if the passed value is a valid priority
843  * level for the underlying architecture.
844  *
845  * @param[in] prio the priority level
846  * @return Priority range result.
847  * @retval false if the priority is invalid or if the architecture
848  * does not support priorities.
849  * @retval true if the priority is valid.
850  */
851 #if defined(PORT_IRQ_IS_VALID_PRIORITY) || defined(__DOXYGEN__)
852 #define CH_IRQ_IS_VALID_PRIORITY(prio) \
853  PORT_IRQ_IS_VALID_PRIORITY(prio)
854 #else
855 #define CH_IRQ_IS_VALID_PRIORITY(prio) false
856 #endif
857 
858 /**
859  * @brief Priority level validation macro.
860  * @details This macro determines if the passed value is a valid priority
861  * level that cannot preempt the kernel critical zone.
862  *
863  * @param[in] prio the priority level
864  * @return Priority range result.
865  * @retval false if the priority is invalid or if the architecture
866  * does not support priorities.
867  * @retval true if the priority is valid.
868  */
869 #if defined(PORT_IRQ_IS_VALID_KERNEL_PRIORITY) || defined(__DOXYGEN__)
870 #define CH_IRQ_IS_VALID_KERNEL_PRIORITY(prio) \
871  PORT_IRQ_IS_VALID_KERNEL_PRIORITY(prio)
872 #else
873 #define CH_IRQ_IS_VALID_KERNEL_PRIORITY(prio) false
874 #endif
875 
876 /**
877  * @brief IRQ handler enter code.
878  * @note Usually IRQ handlers functions are also declared naked.
879  * @note On some architectures this macro can be empty.
880  *
881  * @special
882  */
883 #define CH_IRQ_PROLOGUE() \
884  PORT_IRQ_PROLOGUE(); \
885  _dbg_check_enter_isr()
887 /**
888  * @brief IRQ handler exit code.
889  * @note Usually IRQ handlers function are also declared naked.
890  *
891  * @special
892  */
893 #define CH_IRQ_EPILOGUE() \
894  _dbg_check_leave_isr(); \
895  PORT_IRQ_EPILOGUE()
897 /**
898  * @brief Standard normal IRQ handler declaration.
899  * @note @p id can be a function name or a vector number depending on the
900  * port implementation.
901  *
902  * @special
903  */
904 #define CH_IRQ_HANDLER(id) PORT_IRQ_HANDLER(id)
905 /** @} */
906 
907 /**
908  * @name Fast ISRs abstraction macros
909  */
910 /**
911  * @brief Standard fast IRQ handler declaration.
912  * @note @p id can be a function name or a vector number depending on the
913  * port implementation.
914  * @note Not all architectures support fast interrupts.
915  *
916  * @special
917  */
918 #define CH_FAST_IRQ_HANDLER(id) PORT_FAST_IRQ_HANDLER(id)
919 /** @} */
920 
921 /**
922  * @name Time conversion utilities
923  * @{
924  */
925 /**
926  * @brief Seconds to time interval.
927  * @details Converts from seconds to system ticks number.
928  * @note The result is rounded upward to the next tick boundary.
929  * @note Use of this macro for large values is not secure because
930  * integer overflows, make sure your value can be correctly
931  * converted.
932  *
933  * @param[in] secs number of seconds
934  * @return The number of ticks.
935  *
936  * @api
937  */
938 #define TIME_S2I(secs) \
939  ((sysinterval_t)((time_conv_t)(secs) * (time_conv_t)CH_CFG_ST_FREQUENCY))
940 
941 /**
942  * @brief Milliseconds to time interval.
943  * @details Converts from milliseconds to system ticks number.
944  * @note The result is rounded upward to the next tick boundary.
945  * @note Use of this macro for large values is not secure because
946  * integer overflows, make sure your value can be correctly
947  * converted.
948  *
949  * @param[in] msecs number of milliseconds
950  * @return The number of ticks.
951  *
952  * @api
953  */
954 #define TIME_MS2I(msecs) \
955  ((sysinterval_t)((((time_conv_t)(msecs) * \
956  (time_conv_t)CH_CFG_ST_FREQUENCY) + \
957  (time_conv_t)999) / (time_conv_t)1000))
958 
959 /**
960  * @brief Microseconds to time interval.
961  * @details Converts from microseconds to system ticks number.
962  * @note The result is rounded upward to the next tick boundary.
963  * @note Use of this macro for large values is not secure because
964  * integer overflows, make sure your value can be correctly
965  * converted.
966  *
967  * @param[in] usecs number of microseconds
968  * @return The number of ticks.
969  *
970  * @api
971  */
972 #define TIME_US2I(usecs) \
973  ((sysinterval_t)((((time_conv_t)(usecs) * \
974  (time_conv_t)CH_CFG_ST_FREQUENCY) + \
975  (time_conv_t)999999) / (time_conv_t)1000000))
976 
977 /**
978  * @brief Time interval to seconds.
979  * @details Converts from system ticks number to seconds.
980  * @note The result is rounded up to the next second boundary.
981  * @note Use of this macro for large values is not secure because
982  * integer overflows, make sure your value can be correctly
983  * converted.
984  *
985  * @param[in] interval interval in ticks
986  * @return The number of seconds.
987  *
988  * @api
989  */
990 #define TIME_I2S(interval) \
991  (time_secs_t)(((time_conv_t)(interval) + \
992  (time_conv_t)CH_CFG_ST_FREQUENCY - \
993  (time_conv_t)1) / (time_conv_t)CH_CFG_ST_FREQUENCY)
994 
995 /**
996  * @brief Time interval to milliseconds.
997  * @details Converts from system ticks number to milliseconds.
998  * @note The result is rounded up to the next millisecond boundary.
999  * @note Use of this macro for large values is not secure because
1000  * integer overflows, make sure your value can be correctly
1001  * converted.
1002  *
1003  * @param[in] interval interval in ticks
1004  * @return The number of milliseconds.
1005  *
1006  * @api
1007  */
1008 #define TIME_I2MS(interval) \
1009  (time_msecs_t)((((time_conv_t)(interval) * (time_conv_t)1000) + \
1010  (time_conv_t)CH_CFG_ST_FREQUENCY - (time_conv_t)1) / \
1011  (time_conv_t)CH_CFG_ST_FREQUENCY)
1012 
1013 /**
1014  * @brief Time interval to microseconds.
1015  * @details Converts from system ticks number to microseconds.
1016  * @note The result is rounded up to the next microsecond boundary.
1017  * @note Use of this macro for large values is not secure because
1018  * integer overflows, make sure your value can be correctly
1019  * converted.
1020  *
1021  * @param[in] interval interval in ticks
1022  * @return The number of microseconds.
1023  *
1024  * @api
1025  */
1026 #define TIME_I2US(interval) \
1027  (time_msecs_t)((((time_conv_t)(interval) * (time_conv_t)1000000) + \
1028  (time_conv_t)CH_CFG_ST_FREQUENCY - (time_conv_t)1) / \
1029  (time_conv_t)CH_CFG_ST_FREQUENCY)
1030 /** @} */
1031 
1032 /**
1033  * @name Threads queues
1034  */
1035 /**
1036  * @brief Data part of a static threads queue object initializer.
1037  * @details This macro should be used when statically initializing a threads
1038  * queue that is part of a bigger structure.
1039  *
1040  * @param[in] name the name of the threads queue variable
1041  */
1042 #define _THREADS_QUEUE_DATA(name) {(cnt_t)0}
1043 
1044 /**
1045  * @brief Static threads queue object initializer.
1046  * @details Statically initialized threads queues require no explicit
1047  * initialization using @p queue_init().
1048  *
1049  * @param[in] name the name of the threads queue variable
1050  */
1051 #define _THREADS_QUEUE_DECL(name) \
1052  threads_queue_t name = _THREADS_QUEUE_DATA(name)
1053 /** @} */
1055 /**
1056  * @name Semaphores macros
1057  * @{
1058  */
1059 /**
1060  * @brief Data part of a static semaphore initializer.
1061  * @details This macro should be used when statically initializing a semaphore
1062  * that is part of a bigger structure.
1063  *
1064  * @param[in] name the name of the semaphore variable
1065  * @param[in] n the counter initial value, this value must be
1066  * non-negative
1067  */
1068 #define _SEMAPHORE_DATA(name, n) {n}
1069 
1070 /**
1071  * @brief Static semaphore initializer.
1072  * @details Statically initialized semaphores require no explicit
1073  * initialization using @p chSemInit().
1074  *
1075  * @param[in] name the name of the semaphore variable
1076  * @param[in] n the counter initial value, this value must be
1077  * non-negative
1078  */
1079 #define SEMAPHORE_DECL(name, n) semaphore_t name = _SEMAPHORE_DATA(name, n)
1080 /** @} */
1081 
1082 /**
1083  * @name Macro Functions
1084  * @{
1085  */
1086 /**
1087  * @brief Returns the current value of the system real time counter.
1088  * @note This function is only available if the port layer supports the
1089  * option @p PORT_SUPPORTS_RT.
1090  *
1091  * @return The value of the system realtime counter of
1092  * type rtcnt_t.
1093  *
1094  * @xclass
1095  */
1096 #if (PORT_SUPPORTS_RT == TRUE) || defined(__DOXYGEN__)
1097 #define chSysGetRealtimeCounterX() (rtcnt_t)port_rt_get_counter_value()
1098 #endif
1099 
1100 /**
1101  * @brief Raises the system interrupt priority mask to the maximum level.
1102  * @details All the maskable interrupt sources are disabled regardless their
1103  * hardware priority.
1104  * @note Do not invoke this API from within a kernel lock.
1105  *
1106  * @special
1107  */
1108 #define chSysDisable() { \
1109  port_disable(); \
1110  _dbg_check_disable(); \
1112 
1113 /**
1114  * @brief Raises the system interrupt priority mask to system level.
1115  * @details The interrupt sources that should not be able to preempt the kernel
1116  * are disabled, interrupt sources with higher priority are still
1117  * enabled.
1118  * @note Do not invoke this API from within a kernel lock.
1119  * @note This API is no replacement for @p chSysLock(), the @p chSysLock()
1120  * could do more than just disable the interrupts.
1121  *
1122  * @special
1123  */
1124 #define chSysSuspend() { \
1125  port_suspend(); \
1126  _dbg_check_suspend(); \
1128 
1129 /**
1130  * @brief Lowers the system interrupt priority mask to user level.
1131  * @details All the interrupt sources are enabled.
1132  * @note Do not invoke this API from within a kernel lock.
1133  * @note This API is no replacement for @p chSysUnlock(), the
1134  * @p chSysUnlock() could do more than just enable the interrupts.
1135  *
1136  * @special
1137  */
1138 #define chSysEnable() { \
1139  _dbg_check_enable(); \
1140  port_enable(); \
1142 
1143 /**
1144  * @brief Enters the kernel lock state.
1145  *
1146  * @special
1147  */
1148 #define chSysLock() { \
1149  port_lock(); \
1150  _dbg_check_lock(); \
1152 
1153 /**
1154  * @brief Leaves the kernel lock state.
1155  *
1156  * @special
1157  */
1158 #define chSysUnlock() { \
1159  _dbg_check_unlock(); \
1160  port_unlock(); \
1162 
1163 /**
1164  * @brief Enters the kernel lock state from within an interrupt handler.
1165  * @note This API may do nothing on some architectures, it is required
1166  * because on ports that support preemptable interrupt handlers
1167  * it is required to raise the interrupt mask to the same level of
1168  * the system mutual exclusion zone.<br>
1169  * It is good practice to invoke this API before invoking any I-class
1170  * syscall from an interrupt handler.
1171  * @note This API must be invoked exclusively from interrupt handlers.
1172  *
1173  * @special
1174  */
1175 #define chSysLockFromISR() { \
1176  port_lock_from_isr(); \
1177  _dbg_check_lock_from_isr(); \
1179 
1180 /**
1181  * @brief Leaves the kernel lock state from within an interrupt handler.
1182  *
1183  * @note This API may do nothing on some architectures, it is required
1184  * because on ports that support preemptable interrupt handlers
1185  * it is required to raise the interrupt mask to the same level of
1186  * the system mutual exclusion zone.<br>
1187  * It is good practice to invoke this API after invoking any I-class
1188  * syscall from an interrupt handler.
1189  * @note This API must be invoked exclusively from interrupt handlers.
1190  *
1191  * @special
1192  */
1193 #define chSysUnlockFromISR() { \
1194  _dbg_check_unlock_from_isr(); \
1195  port_unlock_from_isr(); \
1197 
1198 /**
1199  * @brief Evaluates if a reschedule is required.
1200  *
1201  * @retval true if there is a thread that must go in running state
1202  * immediately.
1203  * @retval false if preemption is not required.
1204  *
1205  * @iclass
1206  */
1207 #define chSchIsRescRequiredI() ((bool)(nil.current != nil.next))
1208 
1209 /**
1210  * @brief Returns a pointer to the current @p thread_t.
1211  *
1212  * @xclass
1213  */
1214 #define chThdGetSelfX() nil.current
1215 
1216 /**
1217  * @brief Delays the invoking thread for the specified number of seconds.
1218  * @note The specified time is rounded up to a value allowed by the real
1219  * system clock.
1220  * @note The maximum specified value is implementation dependent.
1221  *
1222  * @param[in] secs time in seconds, must be different from zero
1223  *
1224  * @api
1225  */
1226 #define chThdSleepSeconds(secs) chThdSleep(TIME_S2I(secs))
1227 
1228 /**
1229  * @brief Delays the invoking thread for the specified number of
1230  * milliseconds.
1231  * @note The specified time is rounded up to a value allowed by the real
1232  * system clock.
1233  * @note The maximum specified value is implementation dependent.
1234  *
1235  * @param[in] msecs time in milliseconds, must be different from zero
1236  *
1237  * @api
1238  */
1239 #define chThdSleepMilliseconds(msecs) chThdSleep(TIME_MS2I(msecs))
1240 
1241 /**
1242  * @brief Delays the invoking thread for the specified number of
1243  * microseconds.
1244  * @note The specified time is rounded up to a value allowed by the real
1245  * system clock.
1246  * @note The maximum specified value is implementation dependent.
1247  *
1248  * @param[in] usecs time in microseconds, must be different from zero
1249  *
1250  * @api
1251  */
1252 #define chThdSleepMicroseconds(usecs) chThdSleep(TIME_US2I(usecs))
1253 
1254 /**
1255  * @brief Suspends the invoking thread for the specified time.
1256  *
1257  * @param[in] timeout the delay in system ticks
1258  *
1259  * @sclass
1260  */
1261 #define chThdSleepS(timeout) \
1262  (void) chSchGoSleepTimeoutS(NIL_STATE_SLEEPING, timeout)
1263 
1264 /**
1265  * @brief Suspends the invoking thread until the system time arrives to the
1266  * specified value.
1267  *
1268  * @param[in] abstime absolute system time
1269  *
1270  * @sclass
1271  */
1272 #define chThdSleepUntilS(abstime) \
1273  (void) chSchGoSleepTimeoutS(NIL_STATE_SLEEPING, \
1274  chTimeDiffX(chVTGetSystemTimeX(), (abstime)))
1276 /**
1277  * @brief Initializes a threads queue object.
1278  *
1279  * @param[out] tqp pointer to the threads queue object
1280  *
1281  * @init
1282  */
1283 #define chThdQueueObjectInit(tqp) ((tqp)->cnt = (cnt_t)0)
1284 
1285 /**
1286  * @brief Evaluates to @p true if the specified queue is empty.
1287  *
1288  * @param[out] tqp pointer to the threads queue object
1289  * @return The queue status.
1290  * @retval false if the queue is not empty.
1291  * @retval true if the queue is empty.
1292  *
1293  * @iclass
1294  */
1295 #define chThdQueueIsEmptyI(tqp) ((bool)(tqp->cnt >= (cnt_t)0))
1296 
1297 #if (CH_CFG_USE_SEMAPHORES == TRUE) || defined(__DOXYGEN__)
1298 /**
1299  * @brief Initializes a semaphore with the specified counter value.
1300  *
1301  * @param[out] sp pointer to a @p semaphore_t structure
1302  * @param[in] n initial value of the semaphore counter. Must be
1303  * non-negative.
1304  *
1305  * @init
1306  */
1307 #define chSemObjectInit(sp, n) ((sp)->cnt = (n))
1308 
1309 /**
1310  * @brief Performs a wait operation on a semaphore.
1311  *
1312  * @param[in] sp pointer to a @p semaphore_t structure
1313  * @return A message specifying how the invoking thread has been
1314  * released from the semaphore.
1315  * @retval CH_MSG_OK if the thread has not stopped on the semaphore or the
1316  * semaphore has been signaled.
1317  * @retval CH_MSG_RST if the semaphore has been reset using @p chSemReset().
1318  *
1319  * @api
1320  */
1321 #define chSemWait(sp) chSemWaitTimeout(sp, TIME_INFINITE)
1322 
1323 /**
1324  * @brief Performs a wait operation on a semaphore.
1325  *
1326  * @param[in] sp pointer to a @p semaphore_t structure
1327  * @return A message specifying how the invoking thread has been
1328  * released from the semaphore.
1329  * @retval CH_MSG_OK if the thread has not stopped on the semaphore or the
1330  * semaphore has been signaled.
1331  * @retval CH_MSG_RST if the semaphore has been reset using @p chSemReset().
1332  *
1333  * @sclass
1334  */
1335 #define chSemWaitS(sp) chSemWaitTimeoutS(sp, TIME_INFINITE)
1336 
1337 /**
1338  * @brief Decreases the semaphore counter.
1339  * @details This macro can be used when the counter is known to be positive.
1340  *
1341  * @param[in] sp pointer to a @p semaphore_t structure
1342  *
1343  * @iclass
1344  */
1345 #define chSemFastWaitI(sp) ((sp)->cnt--)
1346 
1347 /**
1348  * @brief Increases the semaphore counter.
1349  * @details This macro can be used when the counter is known to be not
1350  * negative.
1351  *
1352  * @param[in] sp pointer to a @p semaphore_t structure
1353  *
1354  * @iclass
1355  */
1356 #define chSemFastSignalI(sp) ((sp)->cnt++)
1357 
1358 /**
1359  * @brief Returns the semaphore counter current value.
1360  *
1361  * @iclass
1362  */
1363 #define chSemGetCounterI(sp) ((sp)->cnt)
1364 #endif /* CH_CFG_USE_SEMAPHORES == TRUE */
1365 
1366 /**
1367  * @brief Current system time.
1368  * @details Returns the number of system ticks since the @p chSysInit()
1369  * invocation.
1370  * @note The counter can reach its maximum and then restart from zero.
1371  * @note This function can be called from any context but its atomicity
1372  * is not guaranteed on architectures whose word size is less than
1373  * @p systime_t size.
1374  *
1375  * @return The system time in ticks.
1376  *
1377  * @xclass
1378  */
1379 #if (CH_CFG_ST_TIMEDELTA == 0) || defined(__DOXYGEN__)
1380 #define chVTGetSystemTimeX() (nil.systime)
1381 #else
1382 #define chVTGetSystemTimeX() port_timer_get_time()
1383 #endif
1384 
1385 /**
1386  * @brief Returns the elapsed time since the specified start time.
1387  *
1388  * @param[in] start start time
1389  * @return The elapsed time.
1390  *
1391  * @xclass
1392  */
1393 #define chVTTimeElapsedSinceX(start) \
1394  chTimeDiffX((start), chVTGetSystemTimeX())
1395 
1396 /**
1397  * @brief Adds an interval to a system time returning a system time.
1398  *
1399  * @param[in] systime base system time
1400  * @param[in] interval interval to be added
1401  * @return The new system time.
1402  *
1403  * @xclass
1404  */
1405 #define chTimeAddX(systime, interval) \
1406  ((systime_t)(systime) + (systime_t)(interval))
1407 
1408 /**
1409  * @brief Subtracts two system times returning an interval.
1410  *
1411  * @param[in] start first system time
1412  * @param[in] end second system time
1413  * @return The interval representing the time difference.
1414  *
1415  * @xclass
1416  */
1417 #define chTimeDiffX(start, end) \
1418  ((sysinterval_t)((systime_t)((systime_t)(end) - (systime_t)(start))))
1419 
1420 /**
1421  * @brief Checks if the specified time is within the specified time range.
1422  * @note When start==end then the function returns always true because the
1423  * whole time range is specified.
1424  *
1425  * @param[in] time the time to be verified
1426  * @param[in] start the start of the time window (inclusive)
1427  * @param[in] end the end of the time window (non inclusive)
1428  * @retval true current time within the specified time window.
1429  * @retval false current time not within the specified time window.
1430  *
1431  * @xclass
1432  */
1433 #define chTimeIsInRangeX(time, start, end) \
1434  ((bool)((systime_t)((systime_t)(time) - (systime_t)(start)) < \
1435  (systime_t)((systime_t)(end) - (systime_t)(start))))
1437 /**
1438  * @brief Function parameters check.
1439  * @details If the condition check fails then the kernel panics and halts.
1440  * @note The condition is tested only if the @p CH_DBG_ENABLE_CHECKS switch
1441  * is specified in @p chconf.h else the macro does nothing.
1442  *
1443  * @param[in] c the condition to be verified to be true
1444  *
1445  * @api
1446  */
1447 #if !defined(chDbgCheck)
1448 #define chDbgCheck(c) do { \
1449  /*lint -save -e506 -e774 [2.1, 14.3] Can be a constant by design.*/ \
1450  if (CH_DBG_ENABLE_CHECKS != FALSE) { \
1451  if (!(c)) { \
1452  /*lint -restore*/ \
1453  chSysHalt(__func__); \
1454  } \
1455  } \
1456 } while (false)
1457 #endif /* !defined(chDbgCheck) */
1458 
1459 /**
1460  * @brief Condition assertion.
1461  * @details If the condition check fails then the kernel panics with a
1462  * message and halts.
1463  * @note The condition is tested only if the @p CH_DBG_ENABLE_ASSERTS
1464  * switch is specified in @p chconf.h else the macro does nothing.
1465  * @note The remark string is not currently used except for putting a
1466  * comment in the code about the assertion.
1467  *
1468  * @param[in] c the condition to be verified to be true
1469  * @param[in] r a remark string
1470  *
1471  * @api
1472  */
1473 #if !defined(chDbgAssert)
1474 #define chDbgAssert(c, r) do { \
1475  /*lint -save -e506 -e774 [2.1, 14.3] Can be a constant by design.*/ \
1476  if (CH_DBG_ENABLE_ASSERTS != FALSE) { \
1477  if (!(c)) { \
1478  /*lint -restore*/ \
1479  chSysHalt(__func__); \
1480  } \
1481  } \
1482 } while (false)
1483 #endif /* !defined(chDbgAssert) */
1484 /** @} */
1485 
1486 /* Empty macros if the state checker is not enabled.*/
1487 #if CH_DBG_SYSTEM_STATE_CHECK == FALSE
1488 #define _dbg_enter_lock()
1489 #define _dbg_leave_lock()
1490 #define _dbg_check_disable()
1491 #define _dbg_check_suspend()
1492 #define _dbg_check_enable()
1493 #define _dbg_check_lock()
1494 #define _dbg_check_unlock()
1495 #define _dbg_check_lock_from_isr()
1496 #define _dbg_check_unlock_from_isr()
1497 #define _dbg_check_enter_isr()
1498 #define _dbg_check_leave_isr()
1499 #define chDbgCheckClassI()
1500 #define chDbgCheckClassS()
1501 #endif
1502 
1503 /*===========================================================================*/
1504 /* External declarations. */
1505 /*===========================================================================*/
1506 
1507 #if !defined(__DOXYGEN__)
1508 #if (CH_DBG_ENABLE_STACK_CHECK == TRUE) || defined(__DOXYGEN__)
1509 extern stkalign_t __main_thread_stack_base__, __main_thread_stack_end__;
1510 #endif
1511 extern nil_system_t nil;
1512 extern const thread_config_t nil_thd_configs[CH_CFG_NUM_THREADS + 1];
1513 #endif
1514 
1515 #ifdef __cplusplus
1516 extern "C" {
1517 #endif
1518  void chSysInit(void);
1519  void chSysHalt(const char *reason);
1520  void chSysTimerHandlerI(void);
1521  void chSysUnconditionalLock(void);
1522  void chSysUnconditionalUnlock(void);
1523  syssts_t chSysGetStatusAndLockX(void);
1524  bool chSysIsCounterWithinX(rtcnt_t cnt, rtcnt_t start, rtcnt_t end);
1525  void chSysPolledDelayX(rtcnt_t cycles);
1526  void chSysRestoreStatusX(syssts_t sts);
1527  thread_t *chSchReadyI(thread_t *tp, msg_t msg);
1528  bool chSchIsPreemptionRequired(void);
1529  void chSchDoReschedule(void);
1530  void chSchRescheduleS(void);
1531  msg_t chSchGoSleepTimeoutS(tstate_t newstate, sysinterval_t timeout);
1533  void chThdResumeI(thread_reference_t *trp, msg_t msg);
1534  void chThdResume(thread_reference_t *trp, msg_t msg);
1535  void chThdSleep(sysinterval_t timeout);
1536  void chThdSleepUntil(systime_t abstime);
1537  msg_t chThdEnqueueTimeoutS(threads_queue_t *tqp, sysinterval_t timeout);
1538  void chThdDoDequeueNextI(threads_queue_t *tqp, msg_t msg);
1539  void chThdDequeueNextI(threads_queue_t *tqp, msg_t msg);
1540  void chThdDequeueAllI(threads_queue_t *tqp, msg_t msg);
1541 #if CH_CFG_USE_SEMAPHORES == TRUE
1542  msg_t chSemWaitTimeout(semaphore_t *sp, sysinterval_t timeout);
1543  msg_t chSemWaitTimeoutS(semaphore_t *sp, sysinterval_t timeout);
1544  void chSemSignal(semaphore_t *sp);
1545  void chSemSignalI(semaphore_t *sp);
1546  void chSemReset(semaphore_t *sp, cnt_t n);
1547  void chSemResetI(semaphore_t *sp, cnt_t n);
1548 #endif /* CH_CFG_USE_SEMAPHORES == TRUE */
1549 #if CH_CFG_USE_EVENTS == TRUE
1550  void chEvtSignal(thread_t *tp, eventmask_t mask);
1551  void chEvtSignalI(thread_t *tp, eventmask_t mask);
1552  eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, sysinterval_t timeout);
1553 #endif
1554 #if CH_DBG_SYSTEM_STATE_CHECK == TRUE
1555  void _dbg_check_disable(void);
1556  void _dbg_check_suspend(void);
1557  void _dbg_check_enable(void);
1558  void _dbg_check_lock(void);
1559  void _dbg_check_unlock(void);
1560  void _dbg_check_lock_from_isr(void);
1561  void _dbg_check_unlock_from_isr(void);
1562  void _dbg_check_enter_isr(void);
1563  void _dbg_check_leave_isr(void);
1564  void chDbgCheckClassI(void);
1565  void chDbgCheckClassS(void);
1566 #endif
1567 #ifdef __cplusplus
1568 }
1569 #endif
1570 
1571 /* OSLIB.*/
1572 #include "chlib.h"
1573 
1574 #endif /* CH_H */
1575 
1576 /** @} */
threads_queue_t semaphore_t
Type of a structure representing a semaphore.
Definition: ch.h:594
Structure representing a thread.
Definition: ch.h:626
void chSchRescheduleS(void)
Reschedules if needed.
Definition: ch.c:658
void chEvtSignal(thread_t *tp, eventmask_t mask)
Adds a set of event flags directly to the specified thread_t.
Definition: ch.c:1108
msg_t chSchGoSleepTimeoutS(tstate_t newstate, sysinterval_t timeout)
Puts the current thread to sleep into the specified state with timeout specification.
Definition: ch.c:684
void chSysHalt(const char *reason)
Halts the system.
Definition: ch.c:354
volatile cnt_t cnt
Threads Queue counter.
Definition: ch.h:580
ChibiOS/LIB main include file.
void chThdDequeueAllI(threads_queue_t *tqp, msg_t msg)
Dequeues and wakes up all threads from the threads queue object.
Definition: ch.c:932
void chSemSignal(semaphore_t *sp)
Performs a signal operation on a semaphore.
Definition: ch.c:1019
msg_t chThdSuspendTimeoutS(thread_reference_t *trp, sysinterval_t timeout)
Sends the current thread sleeping and sets a reference variable.
Definition: ch.c:766
void chThdResume(thread_reference_t *trp, msg_t msg)
Wakes up a thread waiting on a thread reference object.
Definition: ch.c:811
void chEvtSignalI(thread_t *tp, eventmask_t mask)
Adds a set of event flags directly to the specified thread_t.
Definition: ch.c:1128
thread_t * thread_reference_t
Type of a thread reference.
Definition: ch.h:621
void(* tfunc_t)(void *p)
Thread function.
Definition: ch.h:600
void chThdResumeI(thread_reference_t *trp, msg_t msg)
Wakes up a thread waiting on a thread reference object.
Definition: ch.c:789
void chSemSignalI(semaphore_t *sp)
Performs a signal operation on a semaphore.
Definition: ch.c:1038
void chThdDoDequeueNextI(threads_queue_t *tqp, msg_t msg)
Dequeues and wakes up one thread from the threads queue object.
Definition: ch.c:895
Structure representing a thread static configuration.
Definition: ch.h:610
void chSysRestoreStatusX(syssts_t sts)
Restores the specified execution status and leaves a critical zone.
Definition: ch.c:536
eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, sysinterval_t timeout)
Waits for any of the specified events.
Definition: ch.c:1158
void chDbgCheckClassS(void)
S-class functions context check.
Definition: ch.c:254
#define CH_CFG_THREAD_EXT_FIELDS
Threads descriptor structure extension.
Definition: chconf.h:304
void chSemReset(semaphore_t *sp, cnt_t n)
Performs a reset operation on the semaphore.
Definition: ch.c:1061
void chSemResetI(semaphore_t *sp, cnt_t n)
Performs a reset operation on the semaphore.
Definition: ch.c:1085
void _dbg_check_suspend(void)
Guard code for chSysSuspend().
Definition: ch.c:130
void chThdSleepUntil(systime_t abstime)
Suspends the invoking thread until the system time arrives to the specified value.
Definition: ch.c:841
void chDbgCheckClassI(void)
I-class functions context check.
Definition: ch.c:239
uint32_t sysinterval_t
Type of time interval.
Definition: ch.h:553
void chThdSleep(sysinterval_t timeout)
Suspends the invoking thread for the specified time.
Definition: ch.c:826
void chSysUnconditionalLock(void)
Unconditionally enters the kernel lock state.
Definition: ch.c:479
msg_t chThdEnqueueTimeoutS(threads_queue_t *tqp, sysinterval_t timeout)
Enqueues the caller thread on a threads queue object.
Definition: ch.c:868
Configuration file template.
void chSysPolledDelayX(rtcnt_t cycles)
Polled delay.
Definition: ch.c:585
void _dbg_check_lock(void)
Guard code for chSysLock().
Definition: ch.c:154
#define CH_CFG_NUM_THREADS
Number of user threads in the application.
Definition: chconf.h:46
void chSysInit(void)
Initializes the kernel.
Definition: ch.c:273
uint32_t systime_t
Type of system time.
Definition: ch.h:547
void chThdDequeueNextI(threads_queue_t *tqp, msg_t msg)
Dequeues and wakes up one thread from the threads queue object, if any.
Definition: ch.c:914
uint64_t time_conv_t
Type of time conversion variable.
Definition: ch.h:560
bool chSchIsPreemptionRequired(void)
Evaluates if preemption is required.
Definition: ch.c:631
void chSysTimerHandlerI(void)
Time management handler.
Definition: ch.c:379
void _dbg_check_lock_from_isr(void)
Guard code for chSysLockFromIsr().
Definition: ch.c:180
void _dbg_check_unlock_from_isr(void)
Guard code for chSysUnlockFromIsr().
Definition: ch.c:193
void _dbg_check_enable(void)
Guard code for chSysEnable().
Definition: ch.c:142
bool chSysIsCounterWithinX(rtcnt_t cnt, rtcnt_t start, rtcnt_t end)
Realtime window test.
Definition: ch.c:568
void chSysUnconditionalUnlock(void)
Unconditionally leaves the kernel lock state.
Definition: ch.c:493
Structure representing a queue of threads.
Definition: ch.h:579
thread_t * chSchReadyI(thread_t *tp, msg_t msg)
Makes the specified thread ready for execution.
Definition: ch.c:602
void _dbg_check_leave_isr(void)
Guard code for CH_IRQ_EPILOGUE().
Definition: ch.c:221
syssts_t chSysGetStatusAndLockX(void)
Returns the execution status and enters a critical zone.
Definition: ch.c:513
void _dbg_check_enter_isr(void)
Guard code for CH_IRQ_PROLOGUE().
Definition: ch.c:206
void chSchDoReschedule(void)
Switches to the first thread on the runnable queue.
Definition: ch.c:643
msg_t chSemWaitTimeout(semaphore_t *sp, sysinterval_t timeout)
Performs a wait operation on a semaphore with timeout specification.
Definition: ch.c:960
nil_system_t nil
System data structures.
Definition: ch.c:41
System data structure.
Definition: ch.h:665
msg_t chSemWaitTimeoutS(semaphore_t *sp, sysinterval_t timeout)
Performs a wait operation on a semaphore with timeout specification.
Definition: ch.c:989
void _dbg_check_unlock(void)
Guard code for chSysUnlock().
Definition: ch.c:167
void _dbg_check_disable(void)
Guard code for chSysDisable().
Definition: ch.c:118