TNeoKernel  v1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Macros | Typedefs | Enumerations | Functions
tn_sys.h File Reference

Detailed Description

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

Definition in file tn_sys.h.

Go to the source code of this file.

Macros

#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_CBDeadlock )(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 TNeoKernel 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...
 
unsigned int tn_sys_time_get (void)
 Get current system ticks count. More...
 
void tn_sys_time_set (unsigned int value)
 Set 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...
 
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 BOOL tn_is_task_context (void)
 Returns whether current system context is TN_CONTEXT_TASK More...
 
static BOOL tn_is_isr_context (void)
 Returns whether current system context is TN_CONTEXT_ISR More...
 
struct TN_Tasktn_cur_task_get (void)
 Returns pointer to the currently running task. More...
 
TN_TaskBodytn_cur_task_body_get (void)
 Returns pointer to the body function of the currently running task. More...
 

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

typedef void( TN_CBDeadlock)(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
activeif TRUE, deadlock becomes active, otherwise it becomes inactive (say, if task stopped waiting for mutex because of timeout)
mutexmutex that is involved in deadlock. You may find out other mutexes involved by means of mutex->deadlock_list.
tasktask that is involved in deadlock. You may find out other tasks involved by means of task->deadlock_list.

Definition at line 171 of file tn_sys.h.

Enumeration Type Documentation

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 79 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 95 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 TNeoKernel 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_stackPointer to array for idle task stack. User must either use the macro TN_TASK_STACK_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_sizeSize of idle task stack, in words (TN_UWord)
int_stackPointer to array for interrupt stack. User must either use the macro TN_TASK_STACK_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_sizeSize of interrupt stack, in words (TN_UWord)
cb_user_task_createCallback function that should create initial user's task (see TN_CBUserTaskCreate)
cb_idleCallback function repeatedly called from idle task.
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)

For further information, refer to Quick guide.

attr_call_int.png
attr_call_ct_sw.png
(refer to Legend for details)

Returns
enum TN_RCode tn_sys_tslice_set ( int  priority,
int  ticks 
)

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

attr_call_task.png
(refer to Legend for details)

Parameters
priorityPriority of tasks for which time slice value should be set
ticksTime 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
unsigned int tn_sys_time_get ( void  )

Get current system ticks count.

attr_call_task.png
attr_call_int.png
(refer to Legend for details)

Returns
Current system ticks count. Note that this value does not affect any of the internal TNeoKernel routines, it is just incremented each system tick (i.e. in tn_tick_int_processing()) and is returned to user by tn_sys_time_get().

It is not used by TNeoKernel itself at all.

void tn_sys_time_set ( unsigned int  value)

Set system ticks count.

Note that this value does not affect any of the internal TNeoKernel routines, it is just incremented each system tick (i.e. in tn_tick_int_processing()) and is returned to user by tn_sys_time_get().

It is not used by TNeoKernel itself at all.

attr_call_task.png
attr_call_int.png
(refer to Legend for details)

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 before tn_sys_start()

Parameters
cbPointer to user-provided callback function.
See also
TN_MUTEX_DEADLOCK_DETECT
TN_CBDeadlock for callback function prototype
enum TN_StateFlag tn_sys_state_flags_get ( void  )

Returns current system state flags.

attr_call_task.png
attr_call_int.png
(refer to Legend for details)

enum TN_Context tn_sys_context_get ( void  )

Returns system context: task or ISR.

attr_call_task.png
attr_call_int.png
(refer to Legend for details)

See also
enum TN_Context
static BOOL tn_is_task_context ( void  )
inlinestatic

Returns whether current system context is TN_CONTEXT_TASK

attr_call_task.png
attr_call_int.png
(refer to Legend for details)

Returns
TRUE if current system context is TN_CONTEXT_TASK, FALSE otherwise.
See also
tn_sys_context_get()
enum TN_Context

Definition at line 364 of file tn_sys.h.

static BOOL tn_is_isr_context ( void  )
inlinestatic

Returns whether current system context is TN_CONTEXT_ISR

attr_call_task.png
attr_call_int.png
(refer to Legend for details)

Returns
TRUE if current system context is TN_CONTEXT_ISR, FALSE otherwise.
See also
tn_sys_context_get()
enum TN_Context

Definition at line 383 of file tn_sys.h.

struct TN_Task* tn_cur_task_get ( void  )

Returns pointer to the currently running task.

attr_call_task.png
attr_call_int.png
(refer to Legend for details)

TN_TaskBody* tn_cur_task_body_get ( void  )

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

attr_call_task.png
attr_call_int.png
(refer to Legend for details)