Nil RTOS: Nil

Nil RTOS

Classes
struct	nil_system_t
	System data structure. More...

struct	nil_thread
	Structure representing a thread. More...

struct	nil_thread_cfg
	Structure representing a thread static configuration. More...

struct	semaphore_t
	Type of a structure representing a counting semaphore. More...

Macros
#define	NIL_DBG_ENABLED FALSE
	System timer resolution in Hz. More...

Typedefs
typedef struct port_intctx	intctx_t
	Type of internal context structure.

typedef void(*	tfunc_t )(void *)
	Thread function.

typedef struct nil_thread_cfg	thread_config_t
	Type of a structure representing a thread static configuration.

typedef thread_t *	thread_ref_t
	Type of a thread reference.

typedef struct nil_thread	thread_t
	Type of a structure representing a thread.

Functions
msg_t	nilSchGoSleepTimeoutS (tstate_t newstate, systime_t timeout)
	Puts the current thread to sleep into the specified state with timeout specification. More...

thread_ref_t	nilSchReadyI (thread_ref_t tr, msg_t msg)
	Makes the specified thread ready for execution. More...

void	nilSchRescheduleS ()
	Reschedules. More...

void	nilSemReset (semaphore_t *sp, cnt_t n)
	Performs a reset operation on the semaphore. More...

void	nilSemResetI (semaphore_t *sp, cnt_t n)
	Performs a reset operation on the semaphore. More...

void	nilSemSignal (semaphore_t *sp)
	Performs a signal operation on a semaphore. More...

void	nilSemSignalI (semaphore_t *sp)
	Performs a signal operation on a semaphore. More...

msg_t	nilSemWaitTimeout (semaphore_t *sp, systime_t timeout)
	Performs a wait operation on a semaphore with timeout specification. More...

msg_t	nilSemWaitTimeoutS (semaphore_t *sp, systime_t timeout)
	Performs a wait operation on a semaphore with timeout specification. More...

void	nilSysInit (void)
	Initializes the kernel. More...

void	nilSysTimerHandlerI (void)
	Time management handler. More...

void	nilThdResumeI (thread_ref_t *trp, msg_t msg)
	Wakes up a thread waiting on a thread reference object. More...

void	nilThdSleep (systime_t time)
	Suspends the invoking thread for the specified time. More...

void	nilThdSleepUntil (systime_t time)
	Suspends the invoking thread until the system time arrives to the specified value. More...

msg_t	nilThdSuspendTimeoutS (thread_ref_t *trp, systime_t timeout)
	Sends the current thread sleeping and sets a reference variable. More...

systime_t	nilTimeNow (void)
	Current system time. More...

bool	nilTimeNowIsWithin (systime_t start, systime_t end)
	Checks if the current system time is within the specified time window. More...

Variables
nil_system_t	nil
	System variables.

nil_system_t	nil
	System variables.

const thread_config_t	nil_thd_configs []

const uint8_t	nil_thd_count

Nil RTOS identification
#define	_NIL_
	Nil RTOS identification.

#define	NIL_KERNEL_VERSION "0.0.1"
	Kernel version string.

#define	NIL_KERNEL_MAJOR 0
	Version major number.

#define	NIL_KERNEL_MINOR 0
	Version minor number.

#define	NIL_KERNEL_PATCH 1
	Version patch number.

Common constants
#define	FALSE 0
	Generic 'false' boolean constant.

#define	TRUE !FALSE
	Generic 'true' boolean constant.

Wakeup status codes
#define	NIL_MSG_OK 0
	Normal wakeup message.

#define	NIL_MSG_TMO -1
	Wake-up caused by a timeout condition.

#define	NIL_MSG_RST -2
	Wake-up caused by a reset condition.

Special time constants
#define	TIME_IMMEDIATE ((systime_t)-1)
	Zero time specification for some functions with a timeout specification. More...

#define	TIME_INFINITE ((systime_t)0)
	Infinite time specification for all functions with a timeout specification.

Thread state related macros
#define	NIL_THD_READY 0
	Thread ready or executing.

#define	NIL_THD_SLEEPING 1
	Thread sleeping.

#define	NIL_THD_SUSP 2
	Thread suspended.

#define	NIL_THD_WTSEM 3
	Thread waiting on semaphore.

#define	NIL_THD_IS_READY(tr) ((tr)->state == NIL_THD_READY)

#define	NIL_THD_IS_SLEEPING(tr) ((tr)->state == NIL_THD_SLEEPING)

#define	NIL_THD_IS_SUSP(tr) ((tr)->state == NIL_THD_SUSP)

#define	NIL_THD_IS_WTSEM(tr) ((tr)->state == NIL_THD_WTSEM)

Threads tables definition macros
#define	NIL_THREADS_TABLE_BEGIN() const thread_config_t nil_thd_configs[] = {
	Start of user threads table.

#define	NIL_THREADS_TABLE_ENTRY(name, funcp, arg, wap, size) {name, funcp, arg, wap, size},
	Entry of user threads table.

#define	NIL_THREADS_TABLE_END()
	End of user threads table.

Macro Functions
#define	nilSysHalt() port_halt()
	System halt state.

#define	nilSysDisable() port_disable()
	Enters the kernel lock mode. More...

#define	nilSysEnable() port_enable()
	Enters the kernel lock mode. More...

#define	nilSysLock() port_lock()
	Enters the kernel lock mode. More...

#define	nilSysUnlock() port_unlock()
	Leaves the kernel lock mode. More...

#define	nilSysLockFromISR() port_lock_from_isr()
	Enters the kernel lock mode from within an interrupt handler. More...

#define	nilSysUnlockFromISR() port_unlock_from_isr()
	Leaves the kernel lock mode from within an interrupt handler. More...

#define	nilThdSleepSeconds(sec) nilThdSleep(S2ST(sec))
	Delays the invoking thread for the specified number of seconds. More...

#define	nilThdSleepMilliseconds(msec) nilThdSleep(MS2ST(msec))
	Delays the invoking thread for the specified number of milliseconds. More...

#define	nilThdSleepMicroseconds(usec) nilThdSleep(US2ST(usec))
	Delays the invoking thread for the specified number of microseconds. More...

#define	nilThdSleepS(timeout) nilSchGoSleepTimeoutS(NIL_THD_SLEEPING, timeout)
	Suspends the invoking thread for the specified time. More...

#define	nilThdSleepUntilS(time) nilSchGoSleepTimeoutS(NIL_THD_SLEEPING, (time) - nilTimeNowI())
	Suspends the invoking thread until the system time arrives to the specified value. More...

#define	nilSemInit(sp, n) ((sp)->cnt = n)
	Initializes a semaphore with the specified counter value. More...

#define	nilSemWait(sp) nilSemWaitTimeout(sp, TIME_INFINITE)
	Performs a wait operation on a semaphore. More...

#define	nilSemWaitS(sp) nilSemWaitTimeoutS(sp, TIME_INFINITE)
	Performs a wait operation on a semaphore. More...

#define	nilTimeNowI() (nil.systime)
	Current system time. More...

#define	nilTimeIsWithin(time, start, end)
	Checks if the specified time is within the specified time window. More...

Threads abstraction macros
#define	NIL_THREAD(tname, arg) PORT_THREAD(tname, arg)
	Thread declaration macro. More...

#define	nilDbgAssert(c, m, r) {(void)(c);}

ISRs abstraction macros
#define	NIL_IRQ_PROLOGUE() PORT_IRQ_PROLOGUE()
	IRQ handler enter code. More...

#define	NIL_IRQ_EPILOGUE() PORT_IRQ_EPILOGUE()
	IRQ handler exit code. More...

#define	NIL_IRQ_HANDLER(id) PORT_IRQ_HANDLER(id)
	Standard normal IRQ handler declaration. More...

Fast ISRs abstraction macros
#define	NIL_FAST_IRQ_HANDLER(id) PORT_FAST_IRQ_HANDLER(id)
	Standard fast IRQ handler declaration. More...

Time conversion utilities
#define	S2ST(sec) ((systime_t)((sec) * NIL_CFG_FREQUENCY))
	Seconds to system ticks. More...

#define	MS2ST(msec)
	Milliseconds to system ticks. More...

#define	US2ST(usec)
	Microseconds to system ticks. More...

Detailed Description

Nil RTOS services.

Macro Definition Documentation

#define MS2ST ( msec )

Value:

((systime_t)(((((uint32_t)(msec)) * ((uint32_t)NIL_CFG_FREQUENCY) - 1UL) /\

1000UL) + 1UL))

systime_t

uint16_t systime_t

Type of system time.

Definition: niltypes.h:41

NIL_CFG_FREQUENCY

#define NIL_CFG_FREQUENCY

System tick frequency.

Definition: nilconf.h:53

Milliseconds to system ticks.

Converts from milliseconds to system ticks number.

Note: The result is rounded upward to the next tick boundary.

Parameters

[in] msec number of milliseconds

Returns: The number of ticks.

#define NIL_DBG_ENABLED FALSE

System timer resolution in Hz.

Time delta constant for the tick-less mode.

Note: If this value is zero then the system uses the classic periodic tick. This value represents the minimum number of ticks that is safe to specify in a timeout directive. The value one is not valid, timeouts are rounded up to this value. System assertions. Threads descriptor structure extension.

User fields added to the end of the thread_t structure.

#define NIL_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.

#define NIL_IRQ_EPILOGUE ( ) PORT_IRQ_EPILOGUE()

IRQ handler exit code.

Note: Usually IRQ handlers function are also declared naked.

#define NIL_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.

#define NIL_IRQ_PROLOGUE ( ) PORT_IRQ_PROLOGUE()

IRQ handler enter code.

Note: Usually IRQ handlers functions are also declared naked.; On some architectures this macro can be empty.

#define NIL_THREAD	(	tname,
		arg
	)	PORT_THREAD(tname, arg)

Thread declaration macro.

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

#define nilSemInit	(	sp,
		n
	)	((sp)->cnt = n)

Initializes a semaphore with the specified counter value.

Parameters

[out]	sp	pointer to a `semaphore_t` structure
[in]	n	initial value of the semaphore counter. Must be non-negative.

#define nilSemWait ( sp ) nilSemWaitTimeout(sp, TIME_INFINITE)

Performs a wait operation on a semaphore.

Parameters

[in] sp pointer to a semaphore_t structure

Returns: A message specifying how the invoking thread has been released from the semaphore.

Return values

NIL_MSG_OK	if the thread has not stopped on the semaphore or the semaphore has been signaled.
NIL_MSG_RST	if the semaphore has been reset using `nilSemReset()`.

#define nilSemWaitS ( sp ) nilSemWaitTimeoutS(sp, TIME_INFINITE)

Performs a wait operation on a semaphore.

Parameters

[in] sp pointer to a semaphore_t structure

Returns: A message specifying how the invoking thread has been released from the semaphore.

Return values

NIL_MSG_OK	if the thread has not stopped on the semaphore or the semaphore has been signaled.
NIL_MSG_RST	if the semaphore has been reset using `nilSemReset()`.

#define nilSysDisable ( ) port_disable()

Enters the kernel lock mode.

#define nilSysEnable ( ) port_enable()

Enters the kernel lock mode.

#define nilSysLock ( ) port_lock()

Enters the kernel lock mode.

#define nilSysLockFromISR ( ) port_lock_from_isr()

Enters the kernel lock mode 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.

#define nilSysUnlock ( ) port_unlock()

Leaves the kernel lock mode.

#define nilSysUnlockFromISR ( ) port_unlock_from_isr()

Leaves the kernel lock mode 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.

#define nilThdSleepMicroseconds ( usec ) nilThdSleep(US2ST(usec))

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] usec time in microseconds, must be different from zero

#define nilThdSleepMilliseconds ( msec ) nilThdSleep(MS2ST(msec))

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] msec time in milliseconds, must be different from zero

#define nilThdSleepS ( timeout ) nilSchGoSleepTimeoutS(NIL_THD_SLEEPING, timeout)

Suspends the invoking thread for the specified time.

Parameters

[in] timeout the delay in system ticks

#define nilThdSleepSeconds ( sec ) nilThdSleep(S2ST(sec))

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] sec time in seconds, must be different from zero

#define nilThdSleepUntilS ( time ) nilSchGoSleepTimeoutS(NIL_THD_SLEEPING, (time) - nilTimeNowI())

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

Parameters

[in] time absolute system time

#define nilTimeIsWithin	(	time,
		start,
		end
	)

Value:

((end) > (start) ? ((time) >= (start)) && ((time) < (end)) : \

((time) >= (start)) || ((time) < (end)))

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

Note: When start==end then the function returns always true because the whole time range is specified.

Parameters

[in]	time	the time to be verified
[in]	start	the start of the time window (inclusive)
[in]	end	the end of the time window (non inclusive)

Return values

true	current time within the specified time window.
false	current time not within the specified time window.

#define nilTimeNowI ( ) (nil.systime)

Current system time.

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

Note: The counter can reach its maximum and then restart from zero.; This function is designed to work with the nilThdSleepUntil().

Returns: The system time in ticks.

#define S2ST ( sec ) ((systime_t)((sec) * NIL_CFG_FREQUENCY))

Seconds to system ticks.

Converts from seconds to system ticks number.

Note: The result is rounded upward to the next tick boundary.

Parameters

[in] sec number of seconds

Returns: The number of ticks.

#define TIME_IMMEDIATE ((systime_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.

#define US2ST ( usec )

Value:

((systime_t)(((((uint32_t)(usec)) * ((uint32_t)NIL_CFG_FREQUENCY) - 1UL) /\

1000000UL) + 1UL))

systime_t

uint16_t systime_t

Type of system time.

Definition: niltypes.h:41

NIL_CFG_FREQUENCY

#define NIL_CFG_FREQUENCY

System tick frequency.

Definition: nilconf.h:53

Microseconds to system ticks.

Converts from microseconds to system ticks number.

Note: The result is rounded upward to the next tick boundary.

Parameters

[in] usec number of microseconds

Returns: The number of ticks.

Function Documentation

msg_t nilSchGoSleepTimeoutS	(	tstate_t	newstate,
		systime_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 NIL_MSG_TMO low level message.

Parameters

[in]	newstate	the new thread state or a semaphore pointer
[in]	timeout	the number of ticks before the operation timeouts. the following special values are allowed: TIME_INFINITE no timeout.

Returns: The wakeup message.

Return values

NIL_MSG_TMO if a timeout occurred.

thread_ref_t nilSchReadyI	(	thread_ref_t	tr,
		msg_t	msg
	)

Makes the specified thread ready for execution.

Parameters

[in]	tr	reference to the `thread_t` object
[in]	msg	the wakeup message

Returns: The same reference passed as parameter.

void nilSchRescheduleS ( )

Reschedules.

void nilSemReset	(	semaphore_t *	sp,
		cnt_t	n
	)

Performs a reset operation on the semaphore.

Postcondition: After invoking this function all the threads waiting on the semaphore, if any, are released and the semaphore counter is set to the specified, non negative, value.

Parameters

[in]	sp	pointer to a `semaphore_t` structure
[in]	n	the new value of the semaphore counter. The value must be non-negative.

void nilSemResetI	(	semaphore_t *	sp,
		cnt_t	n
	)

Performs a reset operation on the semaphore.

Postcondition: After invoking this function all the threads waiting on the semaphore, if any, are released and the semaphore counter is set to the specified, non negative, value.; This function does not reschedule so a call to a rescheduling function must be performed before unlocking the kernel. Note that interrupt handlers always reschedule on exit so an explicit reschedule must not be performed in ISRs.

Parameters

[in]	sp	pointer to a `semaphore_t` structure
[in]	n	the new value of the semaphore counter. The value must be non-negative.

void nilSemSignal ( semaphore_t * sp )

Performs a signal operation on a semaphore.

Parameters

[in] sp pointer to a semaphore_t structure

void nilSemSignalI ( semaphore_t * sp )

Performs a signal operation on a semaphore.

Postcondition: This function does not reschedule so a call to a rescheduling function must be performed before unlocking the kernel. Note that interrupt handlers always reschedule on exit so an explicit reschedule must not be performed in ISRs.

Parameters

[in] sp pointer to a semaphore_t structure

msg_t nilSemWaitTimeout	(	semaphore_t *	sp,
		systime_t	timeout
	)

Performs a wait operation on a semaphore with timeout specification.

Parameters

[in]	sp	pointer to a `semaphore_t` structure
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: A message specifying how the invoking thread has been released from the semaphore.

Return values

NIL_MSG_OK	if the thread has not stopped on the semaphore or the semaphore has been signaled.
NIL_MSG_RST	if the semaphore has been reset using `nilSemReset()`.
NIL_MSG_TMO	if the semaphore has not been signaled or reset within the specified timeout.

msg_t nilSemWaitTimeoutS	(	semaphore_t *	sp,
		systime_t	timeout
	)

Performs a wait operation on a semaphore with timeout specification.

Parameters

[in]	sp	pointer to a `semaphore_t` structure
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: A message specifying how the invoking thread has been released from the semaphore.

Return values

NIL_MSG_OK	if the thread has not stopped on the semaphore or the semaphore has been signaled.
NIL_MSG_RST	if the semaphore has been reset using `nilSemReset()`.
NIL_MSG_TMO	if the semaphore has not been signaled or reset within the specified timeout.

void nilSysInit ( 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.

void nilSysTimerHandlerI ( void )

Time management handler.

Note: This handler has to be invoked by a periodic ISR in order to reschedule the waiting threads.

void nilThdResumeI	(	thread_ref_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]	trp	a pointer to a thread reference object
[in]	msg	the message code

void nilThdSleep ( systime_t time )

Suspends the invoking thread for the specified time.

Parameters

[in] time the delay in system ticks

void nilThdSleepUntil ( systime_t time )

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

Parameters

[in] time absolute system time

msg_t nilThdSuspendTimeoutS	(	thread_ref_t *	trp,
		systime_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]	trp	a pointer to a thread reference object
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_INFINITE no timeout.

Returns: The wake up message.

systime_t nilTimeNow ( void )

Current system time.

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

Note: The counter can reach its maximum and then restart from zero.; This function is designed to work with the nilThdSleepUntil().

Returns: The system time in ticks.

bool nilTimeNowIsWithin	(	systime_t	start,
		systime_t	end
	)

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

Note: When start==end then the function returns always true because the whole time range is specified.

Parameters

[in]	start	the start of the time window (inclusive)
[in]	end	the end of the time window (non inclusive)

Return values

true	current time within the specified time window.
false	current time not within the specified time window.

Classes

Macros

Typedefs

Functions

Variables

Nil RTOS identification

Common constants

Wakeup status codes

Special time constants

Thread state related macros

Threads tables definition macros

Macro Functions

Threads abstraction macros

ISRs abstraction macros

Fast ISRs abstraction macros

Time conversion utilities

Detailed Description

Macro Definition Documentation

Function Documentation