Detailed Description

Kernel system routines: system start, tick processing, time slice managing.

Definition in file tn_sys.h.

Data Structures
struct	_TN_BuildCfg
	Structure with build-time configurations values; it is needed for run-time check which ensures that build-time options for the kernel match ones for the application. More...

Macros
#define	TN_STACK_ARR_DEF(name, size)
	Convenience macro for the definition of stack array. More...

#define	_TN_BUILD_CFG_ARCH_STRUCT_FILL(_p_struct)
	For internal kernel usage: helper macro that fills architecture-dependent values. More...

#define	_TN_BUILD_CFG_STRUCT_FILL(_p_struct)
	For internal kernel usage: fill the structure `_TN_BuildCfg` with current build-time configuration values. More...

#define	_TN_MAX_INLINED_FUNC /* nothing */
	For internal kernel usage: helper macro that allows functions to be inlined or not depending on configuration (see `TN_MAX_INLINE`)

#define	TN_NO_TIME_SLICE 0
	Value to pass to `tn_sys_tslice_set()` to turn round-robin off.

#define	TN_MAX_TIME_SLICE 0xFFFE
	Max value of time slice.

Typedefs
typedef void()	TN_CBUserTaskCreate(void)
	User-provided callback function that is called directly from `tn_sys_start()` as a part of system startup routine; it should merely create at least one (and typically just one) user's task, which should perform all the rest application initialization. More...

typedef void()	TN_CBIdle(void)
	User-provided callback function which is called repeatedly from the idle task loop. More...

typedef void()	TN_CBStackOverflow(struct TN_Task *task)
	User-provided callback function that is called when the kernel detects stack overflow (see `TN_STACK_OVERFLOW_CHECK`). More...

typedef void()	TN_CBDeadlock(TN_BOOL active, struct TN_Mutex mutex, struct TN_Task task)
	User-provided callback function that is called whenever deadlock becomes active or inactive. More...

Enumerations
enum	TN_StateFlag { TN_STATE_FLAG__SYS_RUNNING = (1 << 0), TN_STATE_FLAG__DEADLOCK = (1 << 1) }
	System state flags. More...

enum	TN_Context { TN_CONTEXT_NONE, TN_CONTEXT_TASK, TN_CONTEXT_ISR }
	System context. More...

Functions
void	tn_sys_start (TN_UWord idle_task_stack, unsigned int idle_task_stack_size, TN_UWord int_stack, unsigned int int_stack_size, TN_CBUserTaskCreate cb_user_task_create, TN_CBIdle cb_idle)
	Initial TNeo system start function, never returns. More...

void	tn_tick_int_processing (void)
	Process system tick; should be called periodically, typically from some kind of timer ISR. More...

enum TN_RCode	tn_sys_tslice_set (int priority, int ticks)
	Set time slice ticks value for specified priority (see Round-robin scheduling). More...

TN_TickCnt	tn_sys_time_get (void)
	Get current system ticks count. More...

void	tn_callback_deadlock_set (TN_CBDeadlock *cb)
	Set callback function that should be called whenever deadlock occurs or becomes inactive (say, if one of tasks involved in the deadlock was released from wait because of timeout) More...

void	tn_callback_stack_overflow_set (TN_CBStackOverflow *cb)
	Set callback function that is called when the kernel detects stack overflow (see `TN_STACK_OVERFLOW_CHECK`). More...

enum TN_StateFlag	tn_sys_state_flags_get (void)
	Returns current system state flags. More...

enum TN_Context	tn_sys_context_get (void)
	Returns system context: task or ISR. More...

_TN_STATIC_INLINE TN_BOOL	tn_is_task_context (void)
	Returns whether current system context is `TN_CONTEXT_TASK` More...

_TN_STATIC_INLINE TN_BOOL	tn_is_isr_context (void)
	Returns whether current system context is `TN_CONTEXT_ISR` More...

struct TN_Task *	tn_cur_task_get (void)
	Returns pointer to the currently running task. More...

TN_TaskBody *	tn_cur_task_body_get (void)
	Returns pointer to the body function of the currently running task. More...

_TN_STATIC_INLINE TN_UWord	tn_sched_dis_save (void)
	Disable kernel scheduler and return previous scheduler state. More...

_TN_STATIC_INLINE void	tn_sched_restore (TN_UWord sched_state)
	Restore state of the kernel scheduler. More...

void	tn_callback_dyn_tick_set (TN_CBTickSchedule cb_tick_schedule, TN_CBTickCntGet cb_tick_cnt_get)
	Available if only `TN_DYNAMIC_TICK` is set. More...

Macro Definition Documentation

◆ TN_STACK_ARR_DEF

#define TN_STACK_ARR_DEF	(	name,
		size
	)

Value:

TN_ARCH_STK_ATTR_BEFORE                   \
   TN_UWord name[ (size) ]                   \
   TN_ARCH_STK_ATTR_AFTER

Convenience macro for the definition of stack array.

See tn_task_create() for the usage example.

Parameters

name	C variable name of the array
size	size of the stack array in words (`TN_UWord`), not in bytes.

Definition at line 87 of file tn_sys.h.

◆ _TN_BUILD_CFG_ARCH_STRUCT_FILL

#define _TN_BUILD_CFG_ARCH_STRUCT_FILL ( _p_struct )

For internal kernel usage: helper macro that fills architecture-dependent values.

This macro is used by _TN_BUILD_CFG_STRUCT_FILL() only.

Definition at line 107 of file tn_sys.h.

◆ _TN_BUILD_CFG_STRUCT_FILL

#define _TN_BUILD_CFG_STRUCT_FILL ( _p_struct )

Value:

{                                                                       \
   memset((_p_struct), 0x00, sizeof(*(_p_struct)));                     \
                                                                        \
   (_p_struct)->priorities_cnt            = TN_PRIORITIES_CNT;          \
   (_p_struct)->check_param               = TN_CHECK_PARAM;             \
   (_p_struct)->debug                     = TN_DEBUG;                   \
   (_p_struct)->use_mutexes               = TN_USE_MUTEXES;             \
   (_p_struct)->mutex_rec                 = TN_MUTEX_REC;               \
   (_p_struct)->mutex_deadlock_detect     = TN_MUTEX_DEADLOCK_DETECT;   \
   (_p_struct)->tick_lists_cnt_minus_one  = (TN_TICK_LISTS_CNT - 1);    \
   (_p_struct)->api_make_alig_arg         = TN_API_MAKE_ALIG_ARG;       \
   (_p_struct)->profiler                  = TN_PROFILER;                \
   (_p_struct)->profiler_wait_time        = TN_PROFILER_WAIT_TIME;      \
   (_p_struct)->stack_overflow_check      = TN_STACK_OVERFLOW_CHECK;    \
   (_p_struct)->dynamic_tick              = TN_DYNAMIC_TICK;            \
   (_p_struct)->old_events_api            = TN_OLD_EVENT_API;           \
                                                                        \
   _TN_BUILD_CFG_ARCH_STRUCT_FILL(_p_struct);                           \
}

For internal kernel usage: fill the structure _TN_BuildCfg with current build-time configuration values.

Parameters

_p_struct Pointer to struct _TN_BuildCfg

Definition at line 119 of file tn_sys.h.

Typedef Documentation

◆ TN_CBUserTaskCreate

typedef void() TN_CBUserTaskCreate(void)

User-provided callback function that is called directly from tn_sys_start() as a part of system startup routine; it should merely create at least one (and typically just one) user's task, which should perform all the rest application initialization.

When TN_CBUserTaskCreate() returned, the kernel performs first context switch to the task with highest priority. If there are several tasks with highest priority, context is switched to the first created one.

Refer to the section Starting the kernel for details about system startup process on the whole.

Note: Although you're able to create more than one task here, it's usually not so good idea, because many things typically should be done at startup before tasks can go on with their job: we need to initialize various on-board peripherals (displays, flash memory chips, or whatever) as well as initialize software modules used by application. So, if many tasks are created here, you have to provide some synchronization object so that tasks will wait until all the initialization is done.

It's usually easier to maintain if we create just one task here, which firstly performs all the necessary initialization, then creates the rest of your tasks, and eventually gets to its primary job (the job for which task was created at all). For the usage example, refer to the page Starting the kernel.

Attention

The only system service is allowed to call in this function is tn_task_create().

See also: tn_sys_start()

Definition at line 294 of file tn_sys.h.

◆ TN_CBIdle

typedef void() TN_CBIdle(void)

User-provided callback function which is called repeatedly from the idle task loop.

Make sure that idle task has enough stack space to call this function.

Typically, this callback can be used for things like:

MCU sleep/idle mode. When system has nothing to do, it often makes sense to bring processor to some power-saving mode. Of course, the application is responsible for setting some condition to wake up: typically, it's an interrupt.
Calculation of system load. The easiest implementation is to just increment some variable in the idle task. The faster value grows, the less busy system is.

Attention

From withing this callback, it is illegal to invoke tn_task_sleep() or any other service which could put task to waiting state, because idle task (from which this function is called) should always be runnable, by design. If TN_DEBUG option is set, then this is checked, so if idle task becomes non-runnable, _TN_FATAL_ERROR() macro will be called.

See also: tn_sys_start()

Definition at line 321 of file tn_sys.h.

◆ TN_CBStackOverflow

typedef void() TN_CBStackOverflow(struct TN_Task *task)

User-provided callback function that is called when the kernel detects stack overflow (see TN_STACK_OVERFLOW_CHECK).

Parameters

task	Task whose stack is overflowed

Definition at line 330 of file tn_sys.h.

◆ TN_CBDeadlock

typedef void() TN_CBDeadlock(TN_BOOL active, struct TN_Mutex *mutex, struct TN_Task *task)

User-provided callback function that is called whenever deadlock becomes active or inactive.

Note: this feature works if only TN_MUTEX_DEADLOCK_DETECT is non-zero.

Parameters

active	Boolean value indicating whether deadlock becomes active or inactive. Note: deadlock might become inactive if, for example, one of tasks involved in deadlock exits from waiting by timeout.
mutex	mutex that is involved in deadlock. You may find out other mutexes involved by means of `mutex->deadlock_list`.
task	task that is involved in deadlock. You may find out other tasks involved by means of `task->deadlock_list`.

Definition at line 350 of file tn_sys.h.

Enumeration Type Documentation

◆ TN_StateFlag

enum TN_StateFlag

System state flags.

Enumerator

TN_STATE_FLAG__SYS_RUNNING

system is running

TN_STATE_FLAG__DEADLOCK

deadlock is active Note: this feature works if only TN_MUTEX_DEADLOCK_DETECT is non-zero.

See also: TN_MUTEX_DEADLOCK_DETECT

Definition at line 232 of file tn_sys.h.

◆ TN_Context

enum TN_Context

System context.

See also: tn_sys_context_get()

Enumerator
TN_CONTEXT_NONE	None: this code is possible if only system is not running (flag (`TN_STATE_FLAG__SYS_RUNNING` is not set in the `_tn_sys_state`))
TN_CONTEXT_TASK	Task context.
TN_CONTEXT_ISR	ISR context.

Definition at line 248 of file tn_sys.h.

Function Documentation

◆ tn_sys_start()

void tn_sys_start	(	TN_UWord *	idle_task_stack,
		unsigned int	idle_task_stack_size,
		TN_UWord *	int_stack,
		unsigned int	int_stack_size,
		TN_CBUserTaskCreate *	cb_user_task_create,
		TN_CBIdle *	cb_idle
	)

Initial TNeo system start function, never returns.

Typically called from main().

Refer to the Starting the kernel section for the usage example and additional comments.

(refer to Legend for details)

Parameters

idle_task_stack	Pointer to array for idle task stack. User must either use the macro `TN_STACK_ARR_DEF()` for the definition of stack array, or allocate it manually as an array of `TN_UWord` with `TN_ARCH_STK_ATTR_BEFORE` and `TN_ARCH_STK_ATTR_AFTER` macros.
idle_task_stack_size	Size of idle task stack, in words (`TN_UWord`)
int_stack	Pointer to array for interrupt stack. User must either use the macro `TN_STACK_ARR_DEF()` for the definition of stack array, or allocate it manually as an array of `TN_UWord` with `TN_ARCH_STK_ATTR_BEFORE` and `TN_ARCH_STK_ATTR_AFTER` macros.
int_stack_size	Size of interrupt stack, in words (`TN_UWord`)
cb_user_task_create	Callback function that should create initial user's task, see `TN_CBUserTaskCreate` for details.
cb_idle	Callback function repeatedly called from idle task, see `TN_CBIdle` for details.

◆ tn_tick_int_processing()

void tn_tick_int_processing ( void )

Process system tick; should be called periodically, typically from some kind of timer ISR.

The period of this timer is determined by user (typically 1 ms, but user is free to set different value)

Among other things, expired timers are fired from this function.

For further information, refer to Quick guide.

(refer to Legend for details)

◆ tn_sys_tslice_set()

enum TN_RCode tn_sys_tslice_set	(	int	priority,
		int	ticks
	)

Set time slice ticks value for specified priority (see Round-robin scheduling).

(refer to Legend for details)

Parameters

priority	Priority of tasks for which time slice value should be set
ticks	Time slice value, in ticks. Set to `TN_NO_TIME_SLICE` for no round-robin scheduling for given priority (it's default value). Value can't be higher than `TN_MAX_TIME_SLICE`.

Returns

TN_RC_OK on success;
TN_RC_WCONTEXT if called from wrong context;
TN_RC_WPARAM if given priority or ticks are invalid.

◆ tn_sys_time_get()

TN_TickCnt tn_sys_time_get ( void )

Get current system ticks count.

(refer to Legend for details)

Returns: Current system ticks count.

◆ tn_callback_deadlock_set()

void tn_callback_deadlock_set ( TN_CBDeadlock * cb )

Set callback function that should be called whenever deadlock occurs or becomes inactive (say, if one of tasks involved in the deadlock was released from wait because of timeout)

(refer to Legend for details)

Note: this function should be called from main(), before tn_sys_start().

Parameters

cb	Pointer to user-provided callback function.

See also: TN_MUTEX_DEADLOCK_DETECT; TN_CBDeadlock for callback function prototype

◆ tn_callback_stack_overflow_set()

void tn_callback_stack_overflow_set ( TN_CBStackOverflow * cb )

Set callback function that is called when the kernel detects stack overflow (see TN_STACK_OVERFLOW_CHECK).

For function prototype, refer to TN_CBStackOverflow.

◆ tn_sys_state_flags_get()

enum TN_StateFlag tn_sys_state_flags_get ( void )

Returns current system state flags.

(refer to Legend for details)

◆ tn_sys_context_get()

enum TN_Context tn_sys_context_get ( void )

Returns system context: task or ISR.

(refer to Legend for details)

See also: enum TN_Context

◆ tn_is_task_context()

_TN_STATIC_INLINE TN_BOOL tn_is_task_context ( void )

Returns whether current system context is TN_CONTEXT_TASK

(refer to Legend for details)

Returns: TN_TRUE if current system context is TN_CONTEXT_TASK, TN_FALSE otherwise.

See also: tn_sys_context_get(); enum TN_Context

Definition at line 533 of file tn_sys.h.

◆ tn_is_isr_context()

_TN_STATIC_INLINE TN_BOOL tn_is_isr_context ( void )

Returns whether current system context is TN_CONTEXT_ISR

(refer to Legend for details)

Returns: TN_TRUE if current system context is TN_CONTEXT_ISR, TN_FALSE otherwise.

See also: tn_sys_context_get(); enum TN_Context

Definition at line 552 of file tn_sys.h.

◆ tn_cur_task_get()

struct TN_Task* tn_cur_task_get ( void )

Returns pointer to the currently running task.

(refer to Legend for details)

◆ tn_cur_task_body_get()

TN_TaskBody* tn_cur_task_body_get ( void )

Returns pointer to the body function of the currently running task.

(refer to Legend for details)

◆ tn_sched_dis_save()

_TN_STATIC_INLINE TN_UWord tn_sched_dis_save ( void )

Disable kernel scheduler and return previous scheduler state.

Actual behavior depends on the platform:

On Microchip platforms, only scheduler's interrupt gets disabled. All other interrupts are not affected, independently of their priorities.
On Cortex-M3/M4 platforms, we can only disable interrupts based on priority. So, this function disables all interrupts with lowest priority (since scheduler works at lowest interrupt priority).
On Cortex-M0/M0+, we have to disable all interrupts.

(refer to Legend for details)

Returns: State to be restored later by tn_sched_restore()

Definition at line 595 of file tn_sys.h.

◆ tn_sched_restore()

_TN_STATIC_INLINE void tn_sched_restore ( TN_UWord sched_state )

Restore state of the kernel scheduler.

See tn_sched_dis_save().

(refer to Legend for details)

Parameters

sched_state Value returned from tn_sched_dis_save()

Definition at line 611 of file tn_sys.h.

◆ tn_callback_dyn_tick_set()

void tn_callback_dyn_tick_set	(	TN_CBTickSchedule *	cb_tick_schedule,
		TN_CBTickCntGet *	cb_tick_cnt_get
	)

Available if only TN_DYNAMIC_TICK is set.

Set callbacks related to dynamic tick.

Attention: This function should be called before tn_sys_start(), otherwise, you'll run into run-time error _TN_FATAL_ERROR().

(refer to Legend for details)

Parameters

cb_tick_schedule	Pointer to callback function to schedule next time to call `tn_tick_int_processing()`, see `TN_CBTickSchedule` for the prototype.
cb_tick_cnt_get	Pointer to callback function to get current system tick counter value, see `TN_CBTickCntGet` for the prototype.

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ TN_STACK_ARR_DEF

◆ _TN_BUILD_CFG_ARCH_STRUCT_FILL

◆ _TN_BUILD_CFG_STRUCT_FILL

Typedef Documentation

◆ TN_CBUserTaskCreate

◆ TN_CBIdle

◆ TN_CBStackOverflow

◆ TN_CBDeadlock

Enumeration Type Documentation

◆ TN_StateFlag

◆ TN_Context

Function Documentation

◆ tn_sys_start()

◆ tn_tick_int_processing()

◆ tn_sys_tslice_set()

◆ tn_sys_time_get()

◆ tn_callback_deadlock_set()

◆ tn_callback_stack_overflow_set()

◆ tn_sys_state_flags_get()

◆ tn_sys_context_get()

◆ tn_is_task_context()

◆ tn_is_isr_context()

◆ tn_cur_task_get()

◆ tn_cur_task_body_get()

◆ tn_sched_dis_save()

◆ tn_sched_restore()

◆ tn_callback_dyn_tick_set()