ChibiOS  21.6.0
Base API
Collaboration diagram for Base API:

Detailed Description

Macros

#define __CHIBIOS_NIL__
 ChibiOS/NIL identification macro. More...
 
#define CH_KERNEL_STABLE   0
 Stable release flag. More...
 
#define THD_IDLE_BASE   (&__main_thread_stack_base__)
 
#define __CH_STRINGIFY(a)   #a
 Utility to make the parameter a quoted string. More...
 
#define THD_WORKING_AREA_END(wa)   ((wa) + ((sizeof wa) / sizeof (stkalign_t)))
 Returns the top address of a working area. More...
 

ChibiOS/NIL version identification

#define CH_KERNEL_VERSION   "4.1.0"
 Kernel version string. More...
 
#define CH_KERNEL_MAJOR   4
 Kernel version major number. More...
 
#define CH_KERNEL_MINOR   1
 Kernel version minor number. More...
 
#define CH_KERNEL_PATCH   0
 Kernel version patch number. More...
 

Constants for configuration options

#define FALSE   0
 Generic 'false' preprocessor boolean constant. More...
 
#define TRUE   1
 Generic 'true' preprocessor boolean constant. More...
 

Wakeup messages

#define MSG_OK   (msg_t)0
 OK wakeup message.
More...
 
#define MSG_TIMEOUT   (msg_t)-1
 Wake-up caused by a timeout condition.
More...
 
#define MSG_RESET   (msg_t)-2
 Wake-up caused by a reset condition.
More...
 

Special time constants

#define TIME_IMMEDIATE   ((sysinterval_t)-1)
 Zero time specification for some functions with a timeout specification. More...
 
#define TIME_INFINITE   ((sysinterval_t)0)
 Infinite time specification for all functions with a timeout specification. More...
 
#define TIME_MAX_INTERVAL   ((sysinterval_t)-2)
 Maximum interval constant usable as timeout. More...
 
#define TIME_MAX_SYSTIME   ((systime_t)-1)
 Maximum system of system time before it wraps. More...
 

Thread state related macros

#define NIL_STATE_WTSTART   (tstate_t)0
 Thread not yet started or terminated.
More...
 
#define NIL_STATE_READY   (tstate_t)1
 Thread ready or executing.
More...
 
#define NIL_STATE_SLEEPING   (tstate_t)2
 Thread sleeping.
More...
 
#define NIL_STATE_SUSPENDED   (tstate_t)3
 Thread suspended.
More...
 
#define NIL_STATE_WTEXIT   (tstate_t)4
 Waiting a thread.
More...
 
#define NIL_STATE_WTQUEUE   (tstate_t)5
 On queue or semaph. More...
 
#define NIL_STATE_WTOREVT   (tstate_t)6
 Waiting for events. More...
 
#define NIL_STATE_WTANDEVT   (tstate_t)7
 Waiting for events. More...
 
#define NIL_STATE_SNDMSGQ   (tstate_t)8
 Sending a message, in queue.
More...
 
#define NIL_STATE_WTMSG   (tstate_t)10
 Waiting for a message.
More...
 
#define NIL_STATE_FINAL   (tstate_t)11
 Thread terminated.
More...
 
#define NIL_THD_IS_WTSTART(tp)   ((tp)->state == NIL_STATE_WTSTART)
 
#define NIL_THD_IS_READY(tp)   ((tp)->state == NIL_STATE_READY)
 
#define NIL_THD_IS_SLEEPING(tp)   ((tp)->state == NIL_STATE_SLEEPING)
 
#define NIL_THD_IS_SUSPENDED(tp)   ((tp)->state == NIL_STATE_SUSPENDED)
 
#define NIL_THD_IS_WTEXIT(tp)   ((tp)->state == NIL_STATE_WTEXIT)
 
#define NIL_THD_IS_WTQUEUE(tp)   ((tp)->state == NIL_STATE_WTQUEUE)
 
#define NIL_THD_IS_WTOREVT(tp)   ((tp)->state == NIL_STATE_WTOREVT)
 
#define NIL_THD_IS_WTANDEVT(tp)   ((tp)->state == NIL_STATE_WTANDEVT)
 
#define NIL_THD_IS_SNDMSGQ(tp)   ((tp)->state == NIL_STATE_SNDMSGQ)
 
#define NIL_THD_IS_WTMSG(tp)   ((tp)->state == NIL_STATE_WTMSG)
 
#define NIL_THD_IS_FINAL(tp)   ((tp)->state == NIL_STATE_FINAL)
 
#define CH_STATE_NAMES
 

RT options not existing in NIL

#define CH_CFG_USE_REGISTRY   FALSE
 

Kernel types

typedef port_rtcnt_t rtcnt_t
 
typedef port_syssts_t syssts_t
 
typedef port_stkalign_t stkalign_t
 
typedef uint8_t tstate_t
 
typedef uint32_t tprio_t
 
typedef int32_t msg_t
 
typedef int32_t eventid_t
 
typedef uint32_t eventmask_t
 
typedef uint32_t eventflags_t
 
typedef int32_t cnt_t
 
typedef uint32_t ucnt_t
 

Threads tables definition macros

#define THD_TABLE_BEGIN   const thread_descriptor_t nil_thd_configs[] = {
 Start of user threads table. More...
 
#define THD_TABLE_THREAD(_prio, _name, _wap, _funcp, _arg)
 Entry of user threads table. More...
 
#define THD_TABLE_END
 End of user threads table. More...
 

Memory alignment support macros

#define MEM_ALIGN_MASK(a)   ((size_t)(a) - 1U)
 Alignment mask constant. More...
 
#define MEM_ALIGN_PREV(p, a)   ((size_t)(p) & ~MEM_ALIGN_MASK(a))
 Aligns to the previous aligned memory address. More...
 
#define MEM_ALIGN_NEXT(p, a)
 Aligns to the new aligned memory address. More...
 
#define MEM_IS_ALIGNED(p, a)   (((size_t)(p) & MEM_ALIGN_MASK(a)) == 0U)
 Returns whatever a pointer or memory size is aligned. More...
 
#define MEM_IS_VALID_ALIGNMENT(a)   (((size_t)(a) != 0U) && (((size_t)(a) & ((size_t)(a) - 1U)) == 0U))
 Returns whatever a constant is a valid alignment. More...
 

Working Areas

#define THD_WORKING_AREA_SIZE(n)
 Calculates the total Working Area size. More...
 
#define THD_WORKING_AREA(s, n)   PORT_WORKING_AREA(s, n)
 Static working area allocation. More...
 

Threads abstraction macros

#define THD_FUNCTION(tname, arg)   PORT_THD_FUNCTION(tname, arg)
 Thread declaration macro. More...
 

ISRs abstraction macros

#define CH_IRQ_IS_VALID_PRIORITY(prio)   PORT_IRQ_IS_VALID_PRIORITY(prio)
 Priority level validation macro. More...
 
#define CH_IRQ_IS_VALID_KERNEL_PRIORITY(prio)   PORT_IRQ_IS_VALID_KERNEL_PRIORITY(prio)
 Priority level validation macro. More...
 
#define CH_IRQ_PROLOGUE()
 IRQ handler enter code. More...
 
#define CH_IRQ_EPILOGUE()
 IRQ handler exit code. More...
 
#define CH_IRQ_HANDLER(id)   PORT_IRQ_HANDLER(id)
 Standard normal IRQ handler declaration. More...
 

Fast ISRs abstraction macros

#define CH_FAST_IRQ_HANDLER(id)   PORT_FAST_IRQ_HANDLER(id)
 Standard fast IRQ handler declaration. More...
 

Time conversion utilities

#define TIME_S2I(secs)   ((sysinterval_t)((time_conv_t)(secs) * (time_conv_t)CH_CFG_ST_FREQUENCY))
 Seconds to time interval. More...
 
#define TIME_MS2I(msecs)
 Milliseconds to time interval. More...
 
#define TIME_US2I(usecs)
 Microseconds to time interval. More...
 
#define TIME_I2S(interval)
 Time interval to seconds. More...
 
#define TIME_I2MS(interval)
 Time interval to milliseconds. More...
 
#define TIME_I2US(interval)
 Time interval to microseconds. More...
 

Threads queues

#define __THREADS_QUEUE_DATA(name)   {(cnt_t)0}
 Data part of a static threads queue object initializer. More...
 
#define THREADS_QUEUE_DECL(name)   threads_queue_t name = __THREADS_QUEUE_DATA(name)
 Static threads queue object initializer. More...
 

Macro Functions

#define chSysGetRealtimeCounterX()   (rtcnt_t)port_rt_get_counter_value()
 Returns the current value of the system real time counter. More...
 
#define chSysDisable()
 Raises the system interrupt priority mask to the maximum level. More...
 
#define chSysSuspend()
 Raises the system interrupt priority mask to system level. More...
 
#define chSysEnable()
 Lowers the system interrupt priority mask to user level. More...
 
#define chSysLock()
 Enters the kernel lock state. More...
 
#define chSysUnlock()
 Leaves the kernel lock state. More...
 
#define chSysLockFromISR()
 Enters the kernel lock state from within an interrupt handler. More...
 
#define chSysUnlockFromISR()
 Leaves the kernel lock state from within an interrupt handler. More...
 
#define chSchGoSleepS(newstate)   chSchGoSleepTimeoutS(newstate, TIME_INFINITE)
 Puts the current thread to sleep into the specified state. More...
 
#define chSchWakeupS(ntp, msg)
 Wakes up a thread. More...
 
#define chSchIsRescRequiredI()   ((bool)(nil.current != nil.next))
 Evaluates if a reschedule is required. More...
 
#define chThdGetSelfX()   nil.current
 Returns a pointer to the current thread_t. More...
 
#define chThdGetPriorityX(void)   (tprio_t)(nil.current - &nil.threads[0])
 Returns the current thread priority. More...
 
#define chThdResumeS(trp, msg)
 Wakes up a thread waiting on a thread reference object. More...
 
#define chThdSleepSeconds(secs)   chThdSleep(TIME_S2I(secs))
 Delays the invoking thread for the specified number of seconds. More...
 
#define chThdSleepMilliseconds(msecs)   chThdSleep(TIME_MS2I(msecs))
 Delays the invoking thread for the specified number of milliseconds. More...
 
#define chThdSleepMicroseconds(usecs)   chThdSleep(TIME_US2I(usecs))
 Delays the invoking thread for the specified number of microseconds. More...
 
#define chThdSleepS(timeout)   (void) chSchGoSleepTimeoutS(NIL_STATE_SLEEPING, timeout)
 Suspends the invoking thread for the specified time. More...
 
#define chThdSleepUntilS(abstime)
 Suspends the invoking thread until the system time arrives to the specified value. More...
 
#define chThdQueueObjectInit(tqp)   ((tqp)->cnt = (cnt_t)0)
 Initializes a threads queue object. More...
 
#define chThdQueueIsEmptyI(tqp)   ((bool)(tqp->cnt >= (cnt_t)0))
 Evaluates to true if the specified queue is empty. More...
 
#define chVTGetSystemTimeX()   (nil.systime)
 Current system time. More...
 
#define chVTTimeElapsedSinceX(start)   chTimeDiffX((start), chVTGetSystemTimeX())
 Returns the elapsed time since the specified start time. More...
 
#define chVTIsSystemTimeWithinX(start, end)   chTimeIsInRangeX(chVTGetSystemTimeX(), start, end)
 Checks if the current system time is within the specified time window. More...
 
#define chTimeAddX(systime, interval)   ((systime_t)(systime) + (systime_t)(interval))
 Adds an interval to a system time returning a system time. More...
 
#define chTimeDiffX(start, end)   ((sysinterval_t)((systime_t)((systime_t)(end) - (systime_t)(start))))
 Subtracts two system times returning an interval. More...
 
#define chDbgCheck(c)
 Function parameters check. More...
 
#define chDbgAssert(c, r)
 Condition assertion. More...
 

Typedefs

typedef uint32_t systime_t
 Type of system time. More...
 
typedef uint32_t sysinterval_t
 Type of time interval. More...
 
typedef uint64_t time_conv_t
 Type of time conversion variable. More...
 
typedef struct nil_os_instance os_instance_t
 Type of a structure representing the system. More...
 
typedef void(* tfunc_t) (void *p)
 Thread function. More...
 
typedef struct nil_thread_descriptor thread_descriptor_t
 Type of a thread descriptor. More...
 
typedef struct nil_thread thread_t
 Type of a structure representing a thread. More...
 
typedef thread_tthread_reference_t
 Type of a thread reference. More...
 
typedef struct nil_threads_queue threads_queue_t
 Type of a queue of threads. More...
 
typedef threads_queue_t semaphore_t
 Type of a structure representing a semaphore. More...
 

Data Structures

struct  nil_threads_queue
 Structure representing a queue of threads. More...
 
struct  nil_thread_descriptor
 Structure representing a thread descriptor. More...
 
struct  nil_thread
 Structure representing a thread. More...
 
struct  nil_os_instance
 System data structure. More...
 

Functions

thread_tnil_find_thread (tstate_t state, void *p)
 Retrieves the highest priority thread in the specified state and associated to the specified object. More...
 
cnt_t nil_ready_all (void *p, cnt_t cnt, msg_t msg)
 Puts in ready state all thread matching the specified status and associated object. More...
 
void __dbg_check_disable (void)
 Guard code for chSysDisable(). More...
 
void __dbg_check_suspend (void)
 Guard code for chSysSuspend(). More...
 
void __dbg_check_enable (void)
 Guard code for chSysEnable(). More...
 
void __dbg_check_lock (void)
 Guard code for chSysLock(). More...
 
void __dbg_check_unlock (void)
 Guard code for chSysUnlock(). More...
 
void __dbg_check_lock_from_isr (void)
 Guard code for chSysLockFromIsr(). More...
 
void __dbg_check_unlock_from_isr (void)
 Guard code for chSysUnlockFromIsr(). More...
 
void __dbg_check_enter_isr (void)
 Guard code for CH_IRQ_PROLOGUE(). More...
 
void __dbg_check_leave_isr (void)
 Guard code for CH_IRQ_EPILOGUE(). More...
 
void chDbgCheckClassI (void)
 I-class functions context check. More...
 
void chDbgCheckClassS (void)
 S-class functions context check. More...
 
void chSysInit (void)
 Initializes the kernel. More...
 
void chSysHalt (const char *reason)
 Halts the system. More...
 
void chSysTimerHandlerI (void)
 Time management handler. More...
 
void chSysUnconditionalLock (void)
 Unconditionally enters the kernel lock state. More...
 
void chSysUnconditionalUnlock (void)
 Unconditionally leaves the kernel lock state. More...
 
syssts_t chSysGetStatusAndLockX (void)
 Returns the execution status and enters a critical zone. More...
 
void chSysRestoreStatusX (syssts_t sts)
 Restores the specified execution status and leaves a critical zone. More...
 
bool chSysIsCounterWithinX (rtcnt_t cnt, rtcnt_t start, rtcnt_t end)
 Realtime window test. More...
 
void chSysPolledDelayX (rtcnt_t cycles)
 Polled delay. More...
 
thread_tchSchReadyI (thread_t *tp, msg_t msg)
 Makes the specified thread ready for execution. More...
 
bool chSchIsPreemptionRequired (void)
 Evaluates if preemption is required. More...
 
void chSchDoPreemption (void)
 Switches to the first thread on the runnable queue. More...
 
void chSchRescheduleS (void)
 Reschedules if needed. More...
 
msg_t chSchGoSleepTimeoutS (tstate_t newstate, sysinterval_t timeout)
 Puts the current thread to sleep into the specified state with timeout specification. More...
 
bool chTimeIsInRangeX (systime_t time, systime_t start, systime_t end)
 Checks if the specified time is within the specified time range. More...
 
thread_tchThdCreateI (const thread_descriptor_t *tdp)
 Creates a new thread into a static memory area. More...
 
thread_tchThdCreate (const thread_descriptor_t *tdp)
 Creates a new thread into a static memory area. More...
 
void chThdExit (msg_t msg)
 Terminates the current thread. More...
 
msg_t chThdWait (thread_t *tp)
 Blocks the execution of the invoking thread until the specified thread terminates then the exit code is returned. More...
 
msg_t chThdSuspendTimeoutS (thread_reference_t *trp, sysinterval_t timeout)
 Sends the current thread sleeping and sets a reference variable. More...
 
void chThdResumeI (thread_reference_t *trp, msg_t msg)
 Wakes up a thread waiting on a thread reference object. More...
 
void chThdResume (thread_reference_t *trp, msg_t msg)
 Wakes up a thread waiting on a thread reference object. More...
 
void chThdSleep (sysinterval_t timeout)
 Suspends the invoking thread for the specified time. More...
 
void chThdSleepUntil (systime_t abstime)
 Suspends the invoking thread until the system time arrives to the specified value. More...
 
msg_t chThdEnqueueTimeoutS (threads_queue_t *tqp, sysinterval_t timeout)
 Enqueues the caller thread on a threads queue object. More...
 
void chThdDoDequeueNextI (threads_queue_t *tqp, msg_t msg)
 Dequeues and wakes up one thread from the threads queue object. More...
 
void chThdDequeueNextI (threads_queue_t *tqp, msg_t msg)
 Dequeues and wakes up one thread from the threads queue object, if any. More...
 
void chThdDequeueAllI (threads_queue_t *tqp, msg_t msg)
 Dequeues and wakes up all threads from the threads queue object. More...
 

Variables

os_instance_t nil
 System data structures. More...
 

Macro Definition Documentation

◆ __CHIBIOS_NIL__

#define __CHIBIOS_NIL__

ChibiOS/NIL identification macro.

Definition at line 42 of file nil/include/ch.h.

◆ CH_KERNEL_STABLE

#define CH_KERNEL_STABLE   0

Stable release flag.

Definition at line 47 of file nil/include/ch.h.

◆ CH_KERNEL_VERSION

#define CH_KERNEL_VERSION   "4.1.0"

Kernel version string.

Definition at line 56 of file nil/include/ch.h.

◆ CH_KERNEL_MAJOR

#define CH_KERNEL_MAJOR   4

Kernel version major number.

Definition at line 61 of file nil/include/ch.h.

◆ CH_KERNEL_MINOR

#define CH_KERNEL_MINOR   1

Kernel version minor number.

Definition at line 66 of file nil/include/ch.h.

◆ CH_KERNEL_PATCH

#define CH_KERNEL_PATCH   0

Kernel version patch number.

Definition at line 71 of file nil/include/ch.h.

◆ FALSE

#define FALSE   0

Generic 'false' preprocessor boolean constant.

Note
It is meant to be used in configuration files as switch.

Definition at line 83 of file nil/include/ch.h.

◆ TRUE

#define TRUE   1

Generic 'true' preprocessor boolean constant.

Note
It is meant to be used in configuration files as switch.

Definition at line 91 of file nil/include/ch.h.

◆ MSG_OK

#define MSG_OK   (msg_t)0

OK wakeup message.

Definition at line 99 of file nil/include/ch.h.

◆ MSG_TIMEOUT

#define MSG_TIMEOUT   (msg_t)-1

Wake-up caused by a timeout condition.

Definition at line 100 of file nil/include/ch.h.

◆ MSG_RESET

#define MSG_RESET   (msg_t)-2

Wake-up caused by a reset condition.

Definition at line 102 of file nil/include/ch.h.

◆ TIME_IMMEDIATE

#define TIME_IMMEDIATE   ((sysinterval_t)-1)

Zero time specification for some functions with a timeout specification.

Note
Not all functions accept TIME_IMMEDIATE as timeout parameter, see the specific function documentation.

Definition at line 116 of file nil/include/ch.h.

◆ TIME_INFINITE

#define TIME_INFINITE   ((sysinterval_t)0)

Infinite time specification for all functions with a timeout specification.

Definition at line 122 of file nil/include/ch.h.

◆ TIME_MAX_INTERVAL

#define TIME_MAX_INTERVAL   ((sysinterval_t)-2)

Maximum interval constant usable as timeout.

Definition at line 127 of file nil/include/ch.h.

◆ TIME_MAX_SYSTIME

#define TIME_MAX_SYSTIME   ((systime_t)-1)

Maximum system of system time before it wraps.

Definition at line 132 of file nil/include/ch.h.

◆ NIL_STATE_WTSTART

#define NIL_STATE_WTSTART   (tstate_t)0

Thread not yet started or terminated.

Definition at line 139 of file nil/include/ch.h.

◆ NIL_STATE_READY

#define NIL_STATE_READY   (tstate_t)1

Thread ready or executing.

Definition at line 141 of file nil/include/ch.h.

◆ NIL_STATE_SLEEPING

#define NIL_STATE_SLEEPING   (tstate_t)2

Thread sleeping.

Definition at line 143 of file nil/include/ch.h.

◆ NIL_STATE_SUSPENDED

#define NIL_STATE_SUSPENDED   (tstate_t)3

Thread suspended.

Definition at line 144 of file nil/include/ch.h.

◆ NIL_STATE_WTEXIT

#define NIL_STATE_WTEXIT   (tstate_t)4

Waiting a thread.

Definition at line 145 of file nil/include/ch.h.

◆ NIL_STATE_WTQUEUE

#define NIL_STATE_WTQUEUE   (tstate_t)5

On queue or semaph.

Definition at line 146 of file nil/include/ch.h.

◆ NIL_STATE_WTOREVT

#define NIL_STATE_WTOREVT   (tstate_t)6

Waiting for events.

Definition at line 147 of file nil/include/ch.h.

◆ NIL_STATE_WTANDEVT

#define NIL_STATE_WTANDEVT   (tstate_t)7

Waiting for events.

Definition at line 148 of file nil/include/ch.h.

◆ NIL_STATE_SNDMSGQ

#define NIL_STATE_SNDMSGQ   (tstate_t)8

Sending a message, in queue.

Definition at line 149 of file nil/include/ch.h.

◆ NIL_STATE_WTMSG

#define NIL_STATE_WTMSG   (tstate_t)10

Waiting for a message.

Definition at line 151 of file nil/include/ch.h.

◆ NIL_STATE_FINAL

#define NIL_STATE_FINAL   (tstate_t)11

Thread terminated.

Definition at line 153 of file nil/include/ch.h.

◆ THD_IDLE_BASE

#define THD_IDLE_BASE   (&__main_thread_stack_base__)

Boundaries of the idle thread boundaries, only required if stack checking is enabled.

Definition at line 370 of file nil/include/ch.h.

◆ __CH_STRINGIFY

#define __CH_STRINGIFY (   a)    #a

Utility to make the parameter a quoted string.

Definition at line 618 of file nil/include/ch.h.

◆ THD_TABLE_BEGIN

#define THD_TABLE_BEGIN   const thread_descriptor_t nil_thd_configs[] = {

Start of user threads table.

Definition at line 627 of file nil/include/ch.h.

◆ THD_TABLE_THREAD

#define THD_TABLE_THREAD (   _prio,
  _name,
  _wap,
  _funcp,
  _arg 
)
Value:
{ \
.name = (_name), \
.wbase = (_wap), \
.wend = THD_WORKING_AREA_END(_wap), \
.prio = (_prio), \
.funcp = (_funcp), \
.arg = (_arg) \
},

Entry of user threads table.

Definition at line 633 of file nil/include/ch.h.

◆ THD_TABLE_END

#define THD_TABLE_END
Value:
{ \
.name = "idle", \
.wbase = THD_IDLE_BASE, \
.wend = THD_IDLE_END, \
.prio = CH_CFG_MAX_THREADS, \
.funcp = NULL, \
.arg = NULL \
} \
};

End of user threads table.

Definition at line 646 of file nil/include/ch.h.

◆ MEM_ALIGN_MASK

#define MEM_ALIGN_MASK (   a)    ((size_t)(a) - 1U)

Alignment mask constant.

Parameters
[in]aalignment, must be a power of two

Definition at line 667 of file nil/include/ch.h.

◆ MEM_ALIGN_PREV

#define MEM_ALIGN_PREV (   p,
 
)    ((size_t)(p) & ~MEM_ALIGN_MASK(a))

Aligns to the previous aligned memory address.

Parameters
[in]pvariable to be aligned
[in]aalignment, must be a power of two

Definition at line 675 of file nil/include/ch.h.

◆ MEM_ALIGN_NEXT

#define MEM_ALIGN_NEXT (   p,
 
)
Value:
MEM_ALIGN_PREV((size_t)(p) + \
MEM_ALIGN_MASK(a), (a))

Aligns to the new aligned memory address.

Parameters
[in]pvariable to be aligned
[in]aalignment, must be a power of two

Definition at line 683 of file nil/include/ch.h.

◆ MEM_IS_ALIGNED

#define MEM_IS_ALIGNED (   p,
 
)    (((size_t)(p) & MEM_ALIGN_MASK(a)) == 0U)

Returns whatever a pointer or memory size is aligned.

Parameters
[in]pvariable to be aligned
[in]aalignment, must be a power of two

Definition at line 692 of file nil/include/ch.h.

◆ MEM_IS_VALID_ALIGNMENT

#define MEM_IS_VALID_ALIGNMENT (   a)    (((size_t)(a) != 0U) && (((size_t)(a) & ((size_t)(a) - 1U)) == 0U))

Returns whatever a constant is a valid alignment.

Valid alignments are powers of two.

Parameters
[in]aalignment to be checked, must be a constant

Definition at line 700 of file nil/include/ch.h.

◆ THD_WORKING_AREA_SIZE

#define THD_WORKING_AREA_SIZE (   n)
Value:

Calculates the total Working Area size.

Parameters
[in]nthe stack size to be assigned to the thread
Returns
The total used memory in bytes.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 716 of file nil/include/ch.h.

◆ THD_WORKING_AREA

#define THD_WORKING_AREA (   s,
 
)    PORT_WORKING_AREA(s, n)

Static working area allocation.

This macro is used to allocate a static thread working area aligned as both position and size.

Parameters
[in]sthe name to be assigned to the stack array
[in]nthe stack size to be assigned to the thread
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 729 of file nil/include/ch.h.

◆ THD_WORKING_AREA_END

#define THD_WORKING_AREA_END (   wa)    ((wa) + ((sizeof wa) / sizeof (stkalign_t)))

Returns the top address of a working area.

Note
The parameter is assumed to be an array of stkalign_t. The macros is invalid for anything else.
Parameters
[in]waworking area array
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 741 of file nil/include/ch.h.

◆ THD_FUNCTION

#define THD_FUNCTION (   tname,
  arg 
)    PORT_THD_FUNCTION(tname, arg)

Thread declaration macro.

Note
Thread declarations should be performed using this macro because the port layer could define optimizations for thread functions.

Definition at line 753 of file nil/include/ch.h.

◆ CH_IRQ_IS_VALID_PRIORITY

#define CH_IRQ_IS_VALID_PRIORITY (   prio)    PORT_IRQ_IS_VALID_PRIORITY(prio)

Priority level validation macro.

This macro determines if the passed value is a valid priority level for the underlying architecture.

Parameters
[in]priothe priority level
Returns
Priority range result.
Return values
falseif the priority is invalid or if the architecture does not support priorities.
trueif the priority is valid.

Definition at line 772 of file nil/include/ch.h.

◆ CH_IRQ_IS_VALID_KERNEL_PRIORITY

#define CH_IRQ_IS_VALID_KERNEL_PRIORITY (   prio)    PORT_IRQ_IS_VALID_KERNEL_PRIORITY(prio)

Priority level validation macro.

This macro determines if the passed value is a valid priority level that cannot preempt the kernel critical zone.

Parameters
[in]priothe priority level
Returns
Priority range result.
Return values
falseif the priority is invalid or if the architecture does not support priorities.
trueif the priority is valid.

Definition at line 790 of file nil/include/ch.h.

◆ CH_IRQ_PROLOGUE

#define CH_IRQ_PROLOGUE ( )
Value:
__dbg_check_enter_isr()

IRQ handler enter code.

Note
Usually IRQ handlers functions are also declared naked.
On some architectures this macro can be empty.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 803 of file nil/include/ch.h.

◆ CH_IRQ_EPILOGUE

#define CH_IRQ_EPILOGUE ( )
Value:
__dbg_check_leave_isr(); \
PORT_IRQ_EPILOGUE()

IRQ handler exit code.

Note
Usually IRQ handlers function are also declared naked.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 813 of file nil/include/ch.h.

◆ CH_IRQ_HANDLER

#define CH_IRQ_HANDLER (   id)    PORT_IRQ_HANDLER(id)

Standard normal IRQ handler declaration.

Note
id can be a function name or a vector number depending on the port implementation.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 824 of file nil/include/ch.h.

◆ CH_FAST_IRQ_HANDLER

#define CH_FAST_IRQ_HANDLER (   id)    PORT_FAST_IRQ_HANDLER(id)

Standard fast IRQ handler declaration.

Note
id can be a function name or a vector number depending on the port implementation.
Not all architectures support fast interrupts.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 839 of file nil/include/ch.h.

◆ TIME_S2I

#define TIME_S2I (   secs)    ((sysinterval_t)((time_conv_t)(secs) * (time_conv_t)CH_CFG_ST_FREQUENCY))

Seconds to time interval.

Converts from seconds to system ticks number.

Note
The result is rounded upward to the next tick boundary.
Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.
Parameters
[in]secsnumber of seconds
Returns
The number of ticks.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 859 of file nil/include/ch.h.

◆ TIME_MS2I

#define TIME_MS2I (   msecs)
Value:

Milliseconds to time interval.

Converts from milliseconds to system ticks number.

Note
The result is rounded upward to the next tick boundary.
Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.
Parameters
[in]msecsnumber of milliseconds
Returns
The number of ticks.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 875 of file nil/include/ch.h.

◆ TIME_US2I

#define TIME_US2I (   usecs)
Value:
((sysinterval_t)((((time_conv_t)(usecs) * \
(time_conv_t)999999) / (time_conv_t)1000000))

Microseconds to time interval.

Converts from microseconds to system ticks number.

Note
The result is rounded upward to the next tick boundary.
Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.
Parameters
[in]usecsnumber of microseconds
Returns
The number of ticks.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 893 of file nil/include/ch.h.

◆ TIME_I2S

#define TIME_I2S (   interval)
Value:

Time interval to seconds.

Converts from system ticks number to seconds.

Note
The result is rounded up to the next second boundary.
Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.
Parameters
[in]intervalinterval in ticks
Returns
The number of seconds.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 911 of file nil/include/ch.h.

◆ TIME_I2MS

#define TIME_I2MS (   interval)
Value:

Time interval to milliseconds.

Converts from system ticks number to milliseconds.

Note
The result is rounded up to the next millisecond boundary.
Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.
Parameters
[in]intervalinterval in ticks
Returns
The number of milliseconds.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 929 of file nil/include/ch.h.

◆ TIME_I2US

#define TIME_I2US (   interval)
Value:

Time interval to microseconds.

Converts from system ticks number to microseconds.

Note
The result is rounded up to the next microsecond boundary.
Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.
Parameters
[in]intervalinterval in ticks
Returns
The number of microseconds.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 947 of file nil/include/ch.h.

◆ __THREADS_QUEUE_DATA

#define __THREADS_QUEUE_DATA (   name)    {(cnt_t)0}

Data part of a static threads queue object initializer.

This macro should be used when statically initializing a threads queue that is part of a bigger structure.

Parameters
[in]namethe name of the threads queue variable

Definition at line 964 of file nil/include/ch.h.

◆ THREADS_QUEUE_DECL

#define THREADS_QUEUE_DECL (   name)    threads_queue_t name = __THREADS_QUEUE_DATA(name)

Static threads queue object initializer.

Statically initialized threads queues require no explicit initialization using queue_init().

Parameters
[in]namethe name of the threads queue variable

Definition at line 973 of file nil/include/ch.h.

◆ chSysGetRealtimeCounterX

#define chSysGetRealtimeCounterX ( )    (rtcnt_t)port_rt_get_counter_value()

Returns the current value of the system real time counter.

Note
This function is only available if the port layer supports the option PORT_SUPPORTS_RT.
Returns
The value of the system realtime counter of type rtcnt_t.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 992 of file nil/include/ch.h.

◆ chSysDisable

#define chSysDisable ( )
Value:
{ \
port_disable(); \
__dbg_check_disable(); \
}

Raises the system interrupt priority mask to the maximum level.

All the maskable interrupt sources are disabled regardless their hardware priority.

Note
Do not invoke this API from within a kernel lock.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 1003 of file nil/include/ch.h.

◆ chSysSuspend

#define chSysSuspend ( )
Value:
{ \
port_suspend(); \
__dbg_check_suspend(); \
}

Raises the system interrupt priority mask to system level.

The interrupt sources that should not be able to preempt the kernel are disabled, interrupt sources with higher priority are still enabled.

Note
Do not invoke this API from within a kernel lock.
This API is no replacement for chSysLock(), the chSysLock() could do more than just disable the interrupts.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 1019 of file nil/include/ch.h.

◆ chSysEnable

#define chSysEnable ( )
Value:
{ \
__dbg_check_enable(); \
port_enable(); \
}

Lowers the system interrupt priority mask to user level.

All the interrupt sources are enabled.

Note
Do not invoke this API from within a kernel lock.
This API is no replacement for chSysUnlock(), the chSysUnlock() could do more than just enable the interrupts.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 1033 of file nil/include/ch.h.

◆ chSysLock

#define chSysLock ( )
Value:
{ \
port_lock(); \
__dbg_check_lock(); \
}

Enters the kernel lock state.

Function Class:
Special function, this function has special requirements see the notes.

Definition at line 1043 of file nil/include/ch.h.

◆ chSysUnlock

#define chSysUnlock ( )
Value:
{ \
__dbg_check_unlock(); \
port_unlock(); \
}

Leaves the kernel lock state.

Function Class:
Special function, this function has special requirements see the notes.

Definition at line 1053 of file nil/include/ch.h.

◆ chSysLockFromISR

#define chSysLockFromISR ( )
Value:
{ \
port_lock_from_isr(); \
__dbg_check_lock_from_isr(); \
}

Enters the kernel lock state from within an interrupt handler.

Note
This API may do nothing on some architectures, it is required because on ports that support preemptable interrupt handlers it is required to raise the interrupt mask to the same level of the system mutual exclusion zone.
It is good practice to invoke this API before invoking any I-class syscall from an interrupt handler.
This API must be invoked exclusively from interrupt handlers.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 1070 of file nil/include/ch.h.

◆ chSysUnlockFromISR

#define chSysUnlockFromISR ( )
Value:
{ \
__dbg_check_unlock_from_isr(); \
port_unlock_from_isr(); \
}

Leaves the kernel lock state from within an interrupt handler.

Note
This API may do nothing on some architectures, it is required because on ports that support preemptable interrupt handlers it is required to raise the interrupt mask to the same level of the system mutual exclusion zone.
It is good practice to invoke this API after invoking any I-class syscall from an interrupt handler.
This API must be invoked exclusively from interrupt handlers.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 1088 of file nil/include/ch.h.

◆ chSchGoSleepS

#define chSchGoSleepS (   newstate)    chSchGoSleepTimeoutS(newstate, TIME_INFINITE)

Puts the current thread to sleep into the specified state.

Parameters
[in]newstatethe new thread state or a semaphore pointer
Returns
The wakeup message.
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 1101 of file nil/include/ch.h.

◆ chSchWakeupS

#define chSchWakeupS (   ntp,
  msg 
)
Value:
do { \
chSchReadyI(ntp, msg); \
chSchRescheduleS(); \
} while (false)

Wakes up a thread.

Parameters
[in]ntpthe thread to be made ready
[in]msgthe wakeup message
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 1111 of file nil/include/ch.h.

◆ chSchIsRescRequiredI

#define chSchIsRescRequiredI ( )    ((bool)(nil.current != nil.next))

Evaluates if a reschedule is required.

Return values
trueif there is a thread that must go in running state immediately.
falseif preemption is not required.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 1125 of file nil/include/ch.h.

◆ chThdGetSelfX

#define chThdGetSelfX ( )    nil.current

Returns a pointer to the current thread_t.

Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 1132 of file nil/include/ch.h.

◆ chThdGetPriorityX

#define chThdGetPriorityX (   void)    (tprio_t)(nil.current - &nil.threads[0])

Returns the current thread priority.

Note
Can be invoked in any context.
Returns
The current thread priority.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 1142 of file nil/include/ch.h.

◆ chThdResumeS

#define chThdResumeS (   trp,
  msg 
)
Value:
do { \
chThdResumeI(trp, msg); \
chSchRescheduleS(); \
} while (false)

Wakes up a thread waiting on a thread reference object.

Note
This function must reschedule, it can only be called from thread context.
Parameters
[in]trpa pointer to a thread reference object
[in]msgthe message code
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 1154 of file nil/include/ch.h.

◆ chThdSleepSeconds

#define chThdSleepSeconds (   secs)    chThdSleep(TIME_S2I(secs))

Delays the invoking thread for the specified number of seconds.

Note
The specified time is rounded up to a value allowed by the real system clock.
The maximum specified value is implementation dependent.
Parameters
[in]secstime in seconds, must be different from zero
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 1169 of file nil/include/ch.h.

◆ chThdSleepMilliseconds

#define chThdSleepMilliseconds (   msecs)    chThdSleep(TIME_MS2I(msecs))

Delays the invoking thread for the specified number of milliseconds.

Note
The specified time is rounded up to a value allowed by the real system clock.
The maximum specified value is implementation dependent.
Parameters
[in]msecstime in milliseconds, must be different from zero
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 1182 of file nil/include/ch.h.

◆ chThdSleepMicroseconds

#define chThdSleepMicroseconds (   usecs)    chThdSleep(TIME_US2I(usecs))

Delays the invoking thread for the specified number of microseconds.

Note
The specified time is rounded up to a value allowed by the real system clock.
The maximum specified value is implementation dependent.
Parameters
[in]usecstime in microseconds, must be different from zero
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 1195 of file nil/include/ch.h.

◆ chThdSleepS

#define chThdSleepS (   timeout)    (void) chSchGoSleepTimeoutS(NIL_STATE_SLEEPING, timeout)

Suspends the invoking thread for the specified time.

Parameters
[in]timeoutthe delay in system ticks
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 1204 of file nil/include/ch.h.

◆ chThdSleepUntilS

#define chThdSleepUntilS (   abstime)
Value:

Suspends the invoking thread until the system time arrives to the specified value.

Parameters
[in]abstimeabsolute system time
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 1215 of file nil/include/ch.h.

◆ chThdQueueObjectInit

#define chThdQueueObjectInit (   tqp)    ((tqp)->cnt = (cnt_t)0)

Initializes a threads queue object.

Parameters
[out]tqppointer to the threads queue object
Function Class:
Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 1226 of file nil/include/ch.h.

◆ chThdQueueIsEmptyI

#define chThdQueueIsEmptyI (   tqp)    ((bool)(tqp->cnt >= (cnt_t)0))

Evaluates to true if the specified queue is empty.

Parameters
[out]tqppointer to the threads queue object
Returns
The queue status.
Return values
falseif the queue is not empty.
trueif the queue is empty.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 1238 of file nil/include/ch.h.

◆ chVTGetSystemTimeX

#define chVTGetSystemTimeX ( )    (nil.systime)

Current system time.

Returns the number of system ticks since the chSysInit() invocation.

Note
The counter can reach its maximum and then restart from zero.
This function can be called from any context but its atomicity is not guaranteed on architectures whose word size is less than systime_t size.
Returns
The system time in ticks.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 1254 of file nil/include/ch.h.

◆ chVTTimeElapsedSinceX

#define chVTTimeElapsedSinceX (   start)    chTimeDiffX((start), chVTGetSystemTimeX())

Returns the elapsed time since the specified start time.

Parameters
[in]startstart time
Returns
The elapsed time.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 1267 of file nil/include/ch.h.

◆ chVTIsSystemTimeWithinX

#define chVTIsSystemTimeWithinX (   start,
  end 
)    chTimeIsInRangeX(chVTGetSystemTimeX(), start, end)

Checks if the current system time is within the specified time window.

Note
When start==end then the function returns always false because the time window has zero size.
Parameters
[in]startthe start of the time window (inclusive)
[in]endthe end of the time window (non inclusive)
Return values
truecurrent time within the specified time window.
falsecurrent time not within the specified time window.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 1283 of file nil/include/ch.h.

◆ chTimeAddX

#define chTimeAddX (   systime,
  interval 
)    ((systime_t)(systime) + (systime_t)(interval))

Adds an interval to a system time returning a system time.

Parameters
[in]systimebase system time
[in]intervalinterval to be added
Returns
The new system time.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 1295 of file nil/include/ch.h.

◆ chTimeDiffX

#define chTimeDiffX (   start,
  end 
)    ((sysinterval_t)((systime_t)((systime_t)(end) - (systime_t)(start))))

Subtracts two system times returning an interval.

Parameters
[in]startfirst system time
[in]endsecond system time
Returns
The interval representing the time difference.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 1307 of file nil/include/ch.h.

◆ chDbgCheck

#define chDbgCheck (   c)
Value:
do { \
/*lint -save -e506 -e774 [2.1, 14.3] Can be a constant by design.*/ \
if (!(c)) { \
/*lint -restore*/ \
chSysHalt(__func__); \
} \
} \
} while (false)

Function parameters check.

If the condition check fails then the kernel panics and halts.

Note
The condition is tested only if the CH_DBG_ENABLE_CHECKS switch is specified in chconf.h else the macro does nothing.
Parameters
[in]cthe condition to be verified to be true
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 1321 of file nil/include/ch.h.

◆ chDbgAssert

#define chDbgAssert (   c,
 
)
Value:
do { \
/*lint -save -e506 -e774 [2.1, 14.3] Can be a constant by design.*/ \
if (!(c)) { \
/*lint -restore*/ \
chSysHalt(__func__); \
} \
} \
} while (false)

Condition assertion.

If the condition check fails then the kernel panics with a message and halts.

Note
The condition is tested only if the CH_DBG_ENABLE_ASSERTS switch is specified in chconf.h else the macro does nothing.
The remark string is not currently used except for putting a comment in the code about the assertion.
Parameters
[in]cthe condition to be verified to be true
[in]ra remark string
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 1347 of file nil/include/ch.h.

Typedef Documentation

◆ rtcnt_t

Realtime counter.

Definition at line 386 of file nil/include/ch.h.

◆ syssts_t

System status word.

Definition at line 387 of file nil/include/ch.h.

◆ stkalign_t

Stack alignment type.

Definition at line 388 of file nil/include/ch.h.

◆ tstate_t

typedef uint8_t tstate_t

Thread state.

Definition at line 391 of file nil/include/ch.h.

◆ tprio_t

typedef uint32_t tprio_t

Thread priority.

Definition at line 392 of file nil/include/ch.h.

◆ msg_t

typedef int32_t msg_t

Inter-thread message.

Definition at line 393 of file nil/include/ch.h.

◆ eventid_t

typedef int32_t eventid_t

Numeric event identifier.

Definition at line 394 of file nil/include/ch.h.

◆ eventmask_t

typedef uint32_t eventmask_t

Mask of event identifiers.

Definition at line 395 of file nil/include/ch.h.

◆ eventflags_t

typedef uint32_t eventflags_t

Mask of event flags.

Definition at line 396 of file nil/include/ch.h.

◆ cnt_t

typedef int32_t cnt_t

Generic signed counter.

Definition at line 397 of file nil/include/ch.h.

◆ ucnt_t

typedef uint32_t ucnt_t

Generic unsigned counter.

Definition at line 398 of file nil/include/ch.h.

◆ systime_t

typedef uint32_t systime_t

Type of system time.

Note
It is selectable in configuration between 16 or 32 bits.

Definition at line 428 of file nil/include/ch.h.

◆ sysinterval_t

typedef uint32_t sysinterval_t

Type of time interval.

Note
It is selectable in configuration between 16 or 32 bits.

Definition at line 434 of file nil/include/ch.h.

◆ time_conv_t

typedef uint64_t time_conv_t

Type of time conversion variable.

Note
This type must have double width than other time types, it is only used internally for conversions.

Definition at line 441 of file nil/include/ch.h.

◆ os_instance_t

Type of a structure representing the system.

Definition at line 452 of file nil/include/ch.h.

◆ tfunc_t

typedef void(* tfunc_t) (void *p)

Thread function.

Definition at line 457 of file nil/include/ch.h.

◆ thread_descriptor_t

Type of a thread descriptor.

Definition at line 462 of file nil/include/ch.h.

◆ thread_t

typedef struct nil_thread thread_t

Type of a structure representing a thread.

Note
It is required as an early definition.

Definition at line 468 of file nil/include/ch.h.

◆ thread_reference_t

Type of a thread reference.

Definition at line 473 of file nil/include/ch.h.

◆ threads_queue_t

Type of a queue of threads.

Definition at line 478 of file nil/include/ch.h.

◆ semaphore_t

Type of a structure representing a semaphore.

Note
Semaphores are implemented on thread queues, the object is the same, the behavior is slightly different.

Definition at line 486 of file nil/include/ch.h.

Function Documentation

◆ nil_find_thread()

thread_t * nil_find_thread ( tstate_t  state,
void *  p 
)

Retrieves the highest priority thread in the specified state and associated to the specified object.

Parameters
[in]statethread state
[in]pobject pointer
Returns
The pointer to the found thread.
Return values
NULLif the thread is not found.
Function Class:
Not an API, this function is for internal use only.

Definition at line 70 of file ch.c.

References CH_CFG_MAX_THREADS, nil, and ch_thread::state.

Referenced by chThdDoDequeueNextI().

◆ nil_ready_all()

cnt_t nil_ready_all ( void *  p,
cnt_t  cnt,
msg_t  msg 
)

Puts in ready state all thread matching the specified status and associated object.

Parameters
[in]pobject pointer
[in]cntnumber of threads to be readied as a negative number, non negative numbers are ignored
[in]msgthe wakeup message
Returns
The number of readied threads.
Function Class:
Not an API, this function is for internal use only.

Definition at line 95 of file ch.c.

References CH_CFG_MAX_THREADS, chDbgAssert, chSchReadyI(), nil, NIL_STATE_WTQUEUE, and ch_thread::state.

Referenced by chThdDequeueAllI().

Here is the call graph for this function:

◆ __dbg_check_disable()

void __dbg_check_disable ( void  )

Guard code for chSysDisable().

Function Class:
Not an API, this function is for internal use only.

Definition at line 120 of file ch.c.

References chSysHalt(), and nil.

Here is the call graph for this function:

◆ __dbg_check_suspend()

void __dbg_check_suspend ( void  )

Guard code for chSysSuspend().

Function Class:
Not an API, this function is for internal use only.

Definition at line 132 of file ch.c.

References chSysHalt(), and nil.

Here is the call graph for this function:

◆ __dbg_check_enable()

void __dbg_check_enable ( void  )

Guard code for chSysEnable().

Function Class:
Not an API, this function is for internal use only.

Definition at line 144 of file ch.c.

References chSysHalt(), and nil.

Here is the call graph for this function:

◆ __dbg_check_lock()

void __dbg_check_lock ( void  )

Guard code for chSysLock().

Function Class:
Not an API, this function is for internal use only.

Definition at line 156 of file ch.c.

References chSysHalt(), and nil.

Here is the call graph for this function:

◆ __dbg_check_unlock()

void __dbg_check_unlock ( void  )

Guard code for chSysUnlock().

Function Class:
Not an API, this function is for internal use only.

Definition at line 169 of file ch.c.

References chSysHalt(), and nil.

Here is the call graph for this function:

◆ __dbg_check_lock_from_isr()

void __dbg_check_lock_from_isr ( void  )

Guard code for chSysLockFromIsr().

Function Class:
Not an API, this function is for internal use only.

Definition at line 182 of file ch.c.

References chSysHalt(), and nil.

Here is the call graph for this function:

◆ __dbg_check_unlock_from_isr()

void __dbg_check_unlock_from_isr ( void  )

Guard code for chSysUnlockFromIsr().

Function Class:
Not an API, this function is for internal use only.

Definition at line 195 of file ch.c.

References chSysHalt(), and nil.

Here is the call graph for this function:

◆ __dbg_check_enter_isr()

void __dbg_check_enter_isr ( void  )

Guard code for CH_IRQ_PROLOGUE().

Function Class:
Not an API, this function is for internal use only.

Definition at line 208 of file ch.c.

References chSysHalt(), nil, port_lock_from_isr(), and port_unlock_from_isr().

Here is the call graph for this function:

◆ __dbg_check_leave_isr()

void __dbg_check_leave_isr ( void  )

Guard code for CH_IRQ_EPILOGUE().

Function Class:
Not an API, this function is for internal use only.

Definition at line 223 of file ch.c.

References chSysHalt(), nil, port_lock_from_isr(), and port_unlock_from_isr().

Here is the call graph for this function:

◆ chDbgCheckClassI()

void chDbgCheckClassI ( void  )

I-class functions context check.

Verifies that the system is in an appropriate state for invoking an I-class API function. A panic is generated if the state is not compatible.

Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 241 of file ch.c.

References chSysHalt(), and nil.

Referenced by chSchReadyI(), chSysTimerHandlerI(), chThdCreateI(), chThdDequeueAllI(), and chThdDequeueNextI().

Here is the call graph for this function:

◆ chDbgCheckClassS()

void chDbgCheckClassS ( void  )

S-class functions context check.

Verifies that the system is in an appropriate state for invoking an S-class API function. A panic is generated if the state is not compatible.

Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 256 of file ch.c.

References chSysHalt(), and nil.

Referenced by chSchGoSleepTimeoutS(), chSchRescheduleS(), and chThdEnqueueTimeoutS().

Here is the call graph for this function:

◆ chSysInit()

void chSysInit ( void  )

Initializes the kernel.

Initializes the kernel structures, the current instructions flow becomes the idle thread upon return. The idle thread must not invoke any kernel primitive able to change state to not runnable.

Note
This function assumes that the nil global variable has been zeroed by the runtime environment. If this is not the case then make sure to clear it before calling this function.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 275 of file ch.c.

References __oslib_init(), CH_CFG_MAX_THREADS, CH_CFG_SYSTEM_INIT_HOOK, chSchRescheduleS(), chSysSuspend, chSysUnlock, chThdCreateI(), thread_descriptor_t::funcp, nil, NIL_STATE_READY, and THD_IDLE_BASE.

Here is the call graph for this function:

◆ chSysHalt()

void chSysHalt ( const char *  reason)

Halts the system.

This function is invoked by the operating system when an unrecoverable error is detected, for example because a programming error in the application code that triggers an assertion while in debug mode.

Note
Can be invoked from any system state.
Parameters
[in]reasonpointer to an error string
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 330 of file ch.c.

References __trace_halt(), CH_CFG_SYSTEM_HALT_HOOK, currcore, nil, port_disable(), and ch_system::state.

Referenced by __dbg_check_disable(), __dbg_check_enable(), __dbg_check_enter_isr(), __dbg_check_leave_isr(), __dbg_check_lock(), __dbg_check_lock_from_isr(), __dbg_check_suspend(), __dbg_check_unlock(), __dbg_check_unlock_from_isr(), chDbgCheckClassI(), and chDbgCheckClassS().

Here is the call graph for this function:

◆ chSysTimerHandlerI()

void chSysTimerHandlerI ( void  )

Time management handler.

Note
This handler has to be invoked by a periodic ISR in order to reschedule the waiting threads.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 355 of file ch.c.

References chDbgAssert, chDbgCheckClassI(), and nil.

Here is the call graph for this function:

◆ chSysUnconditionalLock()

void chSysUnconditionalLock ( void  )

Unconditionally enters the kernel lock state.

Note
Can be called without previous knowledge of the current lock state. The final state is "s-locked".
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 458 of file ch.c.

References chSysLock, port_get_irq_status(), and port_irq_enabled().

Here is the call graph for this function:

◆ chSysUnconditionalUnlock()

void chSysUnconditionalUnlock ( void  )

Unconditionally leaves the kernel lock state.

Note
Can be called without previous knowledge of the current lock state. The final state is "normal".
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 472 of file ch.c.

References chSysUnlock, port_get_irq_status(), and port_irq_enabled().

Here is the call graph for this function:

◆ chSysGetStatusAndLockX()

syssts_t chSysGetStatusAndLockX ( void  )

Returns the execution status and enters a critical zone.

This functions enters into a critical zone and can be called from any context. Because its flexibility it is less efficient than chSysLock() which is preferable when the calling context is known.

Postcondition
The system is in a critical zone.
Returns
The previous system status, the encoding of this status word is architecture-dependent and opaque.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 492 of file ch.c.

References chSysLock, chSysLockFromISR, port_get_irq_status(), port_irq_enabled(), and port_is_isr_context().

Here is the call graph for this function:

◆ chSysRestoreStatusX()

void chSysRestoreStatusX ( syssts_t  sts)

Restores the specified execution status and leaves a critical zone.

Note
A call to chSchRescheduleS() is automatically performed if exiting the critical zone and if not in ISR context.
Parameters
[in]ststhe system status to be restored.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 515 of file ch.c.

References chSchRescheduleS(), chSysUnlock, chSysUnlockFromISR, port_irq_enabled(), and port_is_isr_context().

Here is the call graph for this function:

◆ chSysIsCounterWithinX()

bool chSysIsCounterWithinX ( rtcnt_t  cnt,
rtcnt_t  start,
rtcnt_t  end 
)

Realtime window test.

This function verifies if the current realtime counter value lies within the specified range or not. The test takes care of the realtime counter wrapping to zero on overflow.

Note
When start==end then the function returns always false because a null time range is specified.
This function is only available if the port layer supports the option PORT_SUPPORTS_RT.
Parameters
[in]cntthe counter value to be tested
[in]startthe start of the time window (inclusive)
[in]endthe end of the time window (non inclusive)
Return values
truecurrent time within the specified time window.
falsecurrent time not within the specified time window.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 547 of file ch.c.

Referenced by chSysPolledDelayX().

◆ chSysPolledDelayX()

void chSysPolledDelayX ( rtcnt_t  cycles)

Polled delay.

Note
The real delay is always few cycles in excess of the specified value.
This function is only available if the port layer supports the option PORT_SUPPORTS_RT.
Parameters
[in]cyclesnumber of cycles
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 564 of file ch.c.

References chSysGetRealtimeCounterX, and chSysIsCounterWithinX().

Here is the call graph for this function:

◆ chSchReadyI()

thread_t * chSchReadyI ( thread_t tp,
msg_t  msg 
)

Makes the specified thread ready for execution.

Parameters
[in]tppointer to the thread_t object
[in]msgthe wakeup message
Returns
The same reference passed as parameter.

Definition at line 581 of file ch.c.

References CH_CFG_MAX_THREADS, chDbgAssert, chDbgCheck, chDbgCheckClassI(), and nil.

Referenced by chThdDoDequeueNextI(), chThdExit(), and nil_ready_all().

Here is the call graph for this function:

◆ chSchIsPreemptionRequired()

bool chSchIsPreemptionRequired ( void  )

Evaluates if preemption is required.

The decision is taken by comparing the relative priorities and depending on the state of the round robin timeout counter.

Note
Not a user function, it is meant to be invoked by the scheduler itself or from within the port layer.
Return values
trueif there is a thread that must go in running state immediately.
falseif preemption is not required.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 610 of file ch.c.

References chSchIsRescRequiredI.

◆ chSchDoPreemption()

void chSchDoPreemption ( void  )

Switches to the first thread on the runnable queue.

Note
Not a user function, it is meant to be invoked by the scheduler itself or from within the port layer.
Function Class:
Special function, this function has special requirements see the notes.

Definition at line 622 of file ch.c.

References CH_CFG_IDLE_LEAVE_HOOK, CH_CFG_MAX_THREADS, nil, and port_switch.

Referenced by chSchRescheduleS().

◆ chSchRescheduleS()

void chSchRescheduleS ( void  )

Reschedules if needed.

Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 637 of file ch.c.

References chDbgCheckClassS(), chSchDoPreemption(), and chSchIsRescRequiredI.

Referenced by chSysInit(), chSysRestoreStatusX(), and chThdCreate().

Here is the call graph for this function:

◆ chSchGoSleepTimeoutS()

msg_t chSchGoSleepTimeoutS ( tstate_t  newstate,
sysinterval_t  timeout 
)

Puts the current thread to sleep into the specified state with timeout specification.

The thread goes into a sleeping state, if it is not awakened explicitly within the specified system time then it is forcibly awakened with a MSG_TIMEOUT low level message.

Parameters
[in]newstatethe new thread state or a semaphore pointer
[in]timeoutthe number of ticks before the operation timeouts. the following special values are allowed:
  • TIME_INFINITE no timeout.
Returns
The wakeup message.
Return values
MSG_TIMEOUTif a timeout occurred.
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 663 of file ch.c.

References CH_CFG_MAX_THREADS, chDbgAssert, chDbgCheckClassS(), nil, ch_thread::state, and TIME_INFINITE.

Referenced by chThdEnqueueTimeoutS(), chThdExit(), and chThdSuspendTimeoutS().

Here is the call graph for this function:

◆ chTimeIsInRangeX()

bool chTimeIsInRangeX ( systime_t  time,
systime_t  start,
systime_t  end 
)

Checks if the specified time is within the specified time range.

Note
When start==end then the function returns always false because the time window has zero size.
Parameters
[in]timethe time to be verified
[in]startthe start of the time window (inclusive)
[in]endthe end of the time window (non inclusive)
Return values
truecurrent time within the specified time window.
falsecurrent time not within the specified time window.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 743 of file ch.c.

Referenced by chThdSleepUntilWindowed(), chVTIsSystemTimeWithin(), and chVTIsSystemTimeWithinX().

◆ chThdCreateI()

thread_t* chThdCreateI ( const thread_descriptor_t tdp)

Creates a new thread into a static memory area.

The new thread is initialized and make ready to execute.

Note
A thread can terminate by calling chThdExit() or by simply returning from its main function.
Parameters
[out]tdppointer to the thread descriptor structure
Returns
The pointer to the thread_t structure allocated for the thread.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 761 of file ch.c.

References CH_CFG_MAX_THREADS, chDbgAssert, chDbgCheck, chDbgCheckClassI(), thread_descriptor_t::funcp, MEM_IS_ALIGNED, nil, PORT_STACK_ALIGN, PORT_WORKING_AREA_ALIGN, thread_descriptor_t::prio, thread_descriptor_t::wbase, and thread_descriptor_t::wend.

Referenced by chSysInit(), and chThdCreate().

Here is the call graph for this function:

◆ chThdCreate()

thread_t* chThdCreate ( const thread_descriptor_t tdp)

Creates a new thread into a static memory area.

The new thread is initialized and make ready to execute.

Note
A thread can terminate by calling chThdExit() or by simply returning from its main function.
Parameters
[out]tdppointer to the thread descriptor structure
Returns
The pointer to the thread_t structure allocated for the thread.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 807 of file ch.c.

References chSchRescheduleS(), chSysLock, chSysUnlock, and chThdCreateI().

Here is the call graph for this function:

◆ chThdExit()

void chThdExit ( msg_t  msg)

Terminates the current thread.

The thread goes in the CH_STATE_FINAL state holding the specified exit status code, other threads can retrieve the exit status code by invoking the function chThdWait().

Postcondition
Exiting a non-static thread that does not have references (detached) causes the thread to remain in the registry. It can only be removed by performing a registry scan operation.
Eventual code after this function will never be executed, this function never returns. The compiler has no way to know this so do not assume that the compiler would remove the dead code.
Parameters
[in]msgthread exit code
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 835 of file ch.c.

References CH_CFG_MAX_THREADS, CH_CFG_THREAD_EXIT_HOOK, chDbgAssert, chSchGoSleepTimeoutS(), chSchReadyI(), chSysLock, nil, NIL_STATE_FINAL, NIL_STATE_WTEXIT, ch_thread::state, and TIME_INFINITE.

Here is the call graph for this function:

◆ chThdWait()

msg_t chThdWait ( thread_t tp)

Blocks the execution of the invoking thread until the specified thread terminates then the exit code is returned.

Parameters
[in]tppointer to the thread
Returns
The exit code from the terminated thread.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 873 of file ch.c.

References chSysLock.

◆ chThdSuspendTimeoutS()

msg_t chThdSuspendTimeoutS ( thread_reference_t trp,
sysinterval_t  timeout 
)

Sends the current thread sleeping and sets a reference variable.

Note
This function must reschedule, it can only be called from thread context.
Parameters
[in]trpa pointer to a thread reference object
[in]timeoutthe number of ticks before the operation timeouts, the following special values are allowed:
  • TIME_IMMEDIATE immediate timeout.
  • TIME_INFINITE no timeout.
Returns
The wake up message.
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 904 of file ch.c.

References chDbgAssert, chSchGoSleepTimeoutS(), MSG_TIMEOUT, nil, NIL_STATE_SUSPENDED, and TIME_IMMEDIATE.

Here is the call graph for this function:

◆ chThdResumeI()

void chThdResumeI ( thread_reference_t trp,
msg_t  msg 
)

Wakes up a thread waiting on a thread reference object.

Note
This function must not reschedule because it can be called from ISR context.
Parameters
[in]trpa pointer to a thread reference object
[in]msgthe message code
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 927 of file ch.c.

References chDbgAssert.

◆ chThdResume()

void chThdResume ( thread_reference_t trp,
msg_t  msg 
)

Wakes up a thread waiting on a thread reference object.

Note
This function must reschedule, it can only be called from thread context.
Parameters
[in]trpa pointer to a thread reference object
[in]msgthe message code
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 949 of file ch.c.

References chSysLock, chSysUnlock, and chThdResumeS().

Here is the call graph for this function:

◆ chThdSleep()

void chThdSleep ( sysinterval_t  timeout)

Suspends the invoking thread for the specified time.

Parameters
[in]timeoutthe delay in system ticks
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 963 of file ch.c.

References chSysLock, chSysUnlock, and chThdSleepS.

◆ chThdSleepUntil()

void chThdSleepUntil ( systime_t  abstime)

Suspends the invoking thread until the system time arrives to the specified value.

Parameters
[in]abstimeabsolute system time
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 978 of file ch.c.

References chSysLock, chSysUnlock, and chThdSleepUntilS.

◆ chThdEnqueueTimeoutS()

msg_t chThdEnqueueTimeoutS ( threads_queue_t tqp,
sysinterval_t  timeout 
)

Enqueues the caller thread on a threads queue object.

The caller thread is enqueued and put to sleep until it is dequeued or the specified timeouts expires.

Parameters
[in]tqppointer to the threads queue object
[in]timeoutthe timeout in system ticks, the special values are handled as follow:
  • TIME_IMMEDIATE immediate timeout.
  • TIME_INFINITE no timeout.
Returns
The message from osalQueueWakeupOneI() or osalQueueWakeupAllI() functions.
Return values
MSG_TIMEOUTif the thread has not been dequeued within the specified timeout or if the function has been invoked with TIME_IMMEDIATE as timeout specification.
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 1005 of file ch.c.

References chDbgAssert, chDbgCheck, chDbgCheckClassS(), chSchGoSleepTimeoutS(), MSG_TIMEOUT, nil, NIL_STATE_WTQUEUE, and TIME_IMMEDIATE.

Here is the call graph for this function:

◆ chThdDoDequeueNextI()

void chThdDoDequeueNextI ( threads_queue_t tqp,
msg_t  msg 
)

Dequeues and wakes up one thread from the threads queue object.

Dequeues one thread from the queue without checking if the queue is empty.

Precondition
The queue must contain at least an object.
Parameters
[in]tqppointer to the threads queue object
[in]msgthe message code
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 1032 of file ch.c.

References chDbgAssert, chSchReadyI(), nil_find_thread(), and NIL_STATE_WTQUEUE.

Referenced by chThdDequeueAllI(), and chThdDequeueNextI().

Here is the call graph for this function:

◆ chThdDequeueNextI()

void chThdDequeueNextI ( threads_queue_t tqp,
msg_t  msg 
)

Dequeues and wakes up one thread from the threads queue object, if any.

Parameters
[in]tqppointer to the threads queue object
[in]msgthe message code
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 1054 of file ch.c.

References chDbgCheck, chDbgCheckClassI(), and chThdDoDequeueNextI().

Here is the call graph for this function:

◆ chThdDequeueAllI()

void chThdDequeueAllI ( threads_queue_t tqp,
msg_t  msg 
)

Dequeues and wakes up all threads from the threads queue object.

Parameters
[in]tqppointer to the threads queue object
[in]msgthe message code
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 1072 of file ch.c.

References chDbgCheck, chDbgCheckClassI(), and nil_ready_all().

Here is the call graph for this function:

Variable Documentation

◆ nil

chVTGetSystemTimeX
#define chVTGetSystemTimeX()
Current system time.
Definition: nil/include/ch.h:1254
time_secs_t
uint32_t time_secs_t
Type of seconds.
Definition: chtime.h:136
chTimeDiffX
#define chTimeDiffX(start, end)
Subtracts two system times returning an interval.
Definition: nil/include/ch.h:1307
PORT_IRQ_PROLOGUE
#define PORT_IRQ_PROLOGUE()
IRQ prologue code.
Definition: chcore.h:226
THD_WORKING_AREA_END
#define THD_WORKING_AREA_END(wa)
Returns the top address of a working area.
Definition: nil/include/ch.h:741
time_conv_t
uint64_t time_conv_t
Type of time conversion variable.
Definition: nil/include/ch.h:441
MEM_ALIGN_MASK
#define MEM_ALIGN_MASK(a)
Alignment mask constant.
Definition: nil/include/ch.h:667
CH_DBG_ENABLE_ASSERTS
#define CH_DBG_ENABLE_ASSERTS
Debug option, consistency checks.
Definition: rt/templates/chconf.h:590
CH_CFG_ST_FREQUENCY
#define CH_CFG_ST_FREQUENCY
System tick frequency.
Definition: rt/templates/chconf.h:75
chSchGoSleepTimeoutS
msg_t chSchGoSleepTimeoutS(tstate_t newstate, sysinterval_t timeout)
Puts the current thread to sleep into the specified state with timeout specification.
Definition: chschd.c:355
CH_DBG_ENABLE_CHECKS
#define CH_DBG_ENABLE_CHECKS
Debug option, parameters checks.
Definition: rt/templates/chconf.h:578
PORT_WA_SIZE
#define PORT_WA_SIZE(n)
Computes the thread working area global size.
Definition: chcore.h:196
THD_IDLE_BASE
#define THD_IDLE_BASE
Definition: nil/include/ch.h:370
CH_CFG_MAX_THREADS
#define CH_CFG_MAX_THREADS
Maximum number of user threads in the application.
Definition: nil/templates/chconf.h:51
MEM_ALIGN_NEXT
#define MEM_ALIGN_NEXT(p, a)
Aligns to the new aligned memory address.
Definition: nil/include/ch.h:683
time_msecs_t
uint32_t time_msecs_t
Type of milliseconds.
Definition: chtime.h:142
sysinterval_t
uint32_t sysinterval_t
Type of time interval.
Definition: nil/include/ch.h:434
time_conv_t
uint64_t time_conv_t
Type of time conversion variable.
Definition: chtime.h:155
MEM_ALIGN_PREV
#define MEM_ALIGN_PREV(p, a)
Aligns to the previous aligned memory address.
Definition: nil/include/ch.h:675
NIL_STATE_SLEEPING
#define NIL_STATE_SLEEPING
Thread sleeping.
Definition: nil/include/ch.h:143
FALSE
#define FALSE
Generic 'false' preprocessor boolean constant.
Definition: nil/include/ch.h:83
PORT_STACK_ALIGN
#define PORT_STACK_ALIGN
Stack alignment constant.
Definition: chcore.h:56