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_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 that 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...

enum TN_RCode	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...

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

static _TN_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...

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

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

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

#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

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 283 of file tn_sys.h.

typedef void( TN_CBIdle)(void)

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

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

Attention

It is illegal to sleep here, because idle task (from which this function is called) should always be runnable, by design. If TN_DEBUG option is set, then sleeping in idle task is checked, so if you try to sleep here, _TN_FATAL_ERROR() macro will be called.

See also: tn_sys_start()

Definition at line 298 of file tn_sys.h.

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 307 of file tn_sys.h.

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 327 of file tn_sys.h.

Enumeration Type Documentation

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 221 of file tn_sys.h.

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 237 of file tn_sys.h.

Function Documentation

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.

enum TN_RCode 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)

Returns

TN_RC_OK on success;
TN_RC_WCONTEXT if called from wrong context.

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_TickCnt tn_sys_time_get ( void )

Get current system ticks count.

(refer to Legend for details)

Returns: Current system ticks count.

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

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.

enum TN_StateFlag tn_sys_state_flags_get ( void )

Returns current system state flags.

(refer to Legend for details)

enum TN_Context tn_sys_context_get ( void )

Returns system context: task or ISR.

(refer to Legend for details)

See also: enum TN_Context

static _TN_INLINE TN_BOOL tn_is_task_context ( void )

static

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 514 of file tn_sys.h.

static _TN_INLINE TN_BOOL tn_is_isr_context ( void )

static

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 533 of file tn_sys.h.

struct TN_Task* tn_cur_task_get ( void )

Returns pointer to the currently running task.

(refer to Legend for details)

TN_TaskBody* tn_cur_task_body_get ( void )

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

(refer to Legend for details)

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

Typedef Documentation

Enumeration Type Documentation

Function Documentation