Kernel Core API#

OSInit()#

Description#

Initializes the internals of the Kernel and MUST be called before creating any Kernel object and before calling OSStart().

Files#

os.h/os_core.c

Prototype#

void  OSInit (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

  1. This function MUST be called AFTER Common's Mem_Init().

OSIntEnter()#

Description#

Used in an interrupt service routine (ISR) to notify the Kernel that you are about to service an interrupt. This allows the Kernel to keep track of interrupt nesting and only performs rescheduling at the last nested ISR.

Files#

os.h/os_core.c

Prototype#

void  OSIntEnter (void)

Arguments#

None.

Returned Value#

None.

Notes / Warnings#

  1. This function MUST be called with interrupts already disabled.

  2. Your ISR can directly increment 'OSIntNestingCtr' without calling this function because OSIntNestingCtr has been declared 'global'. The port is actually considered part of the OS and is allowed to access the Kernel's variables.

  3. You MUST still call OSIntExit() even though you can increment 'OSIntNestingCtr' directly.

  4. You MUST invoke OSIntEnter() and OSIntExit() in pairs. In other words, for every call to OSIntEnter() (or direct increment to OSIntNestingCtr) at the beginning of the ISR you MUST have a call to OSIntExit() at the end of the ISR.

  5. You are allowed to nest interrupts up to 250 levels deep.

OSIntExit()#

Description#

Notifies the Kernel that you have completed servicing an ISR. When the last nested ISR has completed, the Kernel will call the scheduler to determine whether a new, high-priority task is ready to run.

Files#

os.h/os_core.c

Prototype#

void  OSIntExit (void)

Arguments#

None.

Returned Value#

None.

Notes / Warnings#

  1. You MUST invoke OSIntEnter() and OSIntExit() in pairs. In other words, for every call to OSIntEnter() (or direct increment to OSIntNestingCtr) at the beginning of the ISR, you MUST have a call to OSIntExit() at the end of the ISR.

  2. Rescheduling is prevented when the scheduler is locked (see OSSchedLock()).

OSSchedRoundRobinCfg()#

Description#

Changes the round-robin scheduling parameters.

Files#

os.h/os_core.c

Prototype#

void  OSSchedRoundRobinCfg (CPU_BOOLEAN   en,
                            OS_TICK       dflt_time_quanta,
                            RTOS_ERR     *p_err)

Arguments#

en

Determines if the round-robin will be used:

  • DEF_ENABLED Round-robin scheduling is enabled.

  • DEF_DISABLED Round-robin scheduling is disabled.

dflt_time_quanta

Default number of ticks between time slices. A value of 0 assumes OSCfg_TickRate_Hz / 10.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

OSSchedRoundRobinYield()#

Description#

Gives up the CPU when a task is finished its execution before its time slice expires.

Files#

os.h/os_core.c

Prototype#

void  OSSchedRoundRobinYield (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_NONE_WAITING

  • RTOS_ERR_OS_SCHED_LOCKED

Returned Value#

None.

Notes / Warnings#

  1. This function MUST be called from a task.

OSSched()#

Description#

This function is called by other kernel services to determine whether a new, high priority task has been made ready to run. This function is invoked by TASK level code and is not used to reschedule tasks from ISRs (see OSIntExit() for ISR rescheduling).

Files#

os.h/os_core.c

Prototype#

void  OSSched (void)

Arguments#

None.

Returned Value#

None.

Notes / Warnings#

  1. Rescheduling is prevented when the scheduler is locked (see OSSchedLock()).

OSSchedLock()#

Description#

Prevents rescheduling from taking place, allowing your application to prevent context switches until you are ready to permit context switching.

Files#

os.h/os_core.c

Prototype#

void  OSSchedLock (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_WOULD_OVF

Returned Value#

None.

Notes / Warnings#

  1. You MUST invoke OSSchedLock() and OSSchedUnlock() in pairs. In other words, for every call to OSSchedLock(), you MUST have a call to OSSchedUnlock().

OSSchedUnlock()#

Description#

Re-allows rescheduling.

Files#

os.h/os_core.c

Prototype#

void  OSSchedUnlock (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_OS_SCHED_LOCKED

Returned Value#

None.

Notes / Warnings#

  1. You MUST invoke OSSchedLock() and OSSchedUnlock() in pairs. In other words, for every call to OSSchedLock(), you MUST have a call to OSSchedUnlock().

OSStart()#

Description#

Starts the multitasking process which lets the Kernel manage the tasks that you created. Before you can call OSStart(), you MUST have called OSInit() and you MUST have created at least one application task.

Files#

os.h/os_core.c

Prototype#

void  OSStart (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

  1. OSStartHighRdy() MUST:

    a) Call OSTaskSwHook().

    b) Load the context of the task pointed to by OSTCBHighRdyPtr.

    c) Execute the task.

  2. OSStart() is not supposed to return. If it does, that would be considered a fatal error.

OSVersion()#

Description#

Returns the version number of the Kernel. The returned value is the Kernel's version number multiplied by 10000. In other words, version 3.01.02 would be returned as 30102.

Files#

os.h/os_core.c

Prototype#

CPU_INT16U  OSVersion (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

The version number of the Kernel multiplied by 10000.

Notes / Warnings#

  1. This function is DEPRECATED and will be removed in a future version of this product. Instead, use the RTOS_VERSION define. which can be found in rtos/common/include/version.h.

OS_ConfigureISRStk()#

Description#

Configure the stack used for ISRs, if available.

Files#

os.h/os_core.c

Prototype#

void  OS_ConfigureISRStk (CPU_STK       *p_stk_base_ptr,
                          CPU_STK_SIZE   stk_size)

Arguments#

p_stk_base_ptr

Pointer to the base of the buffer used as the stack.

stk_size

Size of the stack, in CPU_STK elements.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before OSInit(). If it is not called, default values will be used.

OS_ConfigureMemSeg()#

Description#

Configure the memory segment used by the kernel.

Files#

os.h/os_core.c

Prototype#

void  OS_ConfigureMemSeg (MEM_SEG  *p_mem_seg)

Arguments#

p_mem_seg

Pointer to the memory segment in which the kernel data will be allocated.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before OSInit(). If it is not called, default values will be used.

OS_ConfigureMsgPoolSize()#

Description#

Configure the kernel message pool size.

Files#

os.h/os_core.c

Prototype#

void  OS_ConfigureMsgPoolSize (OS_MSG_SIZE   msg_pool_size)

Arguments#

msg_pool_size

Number of messages the kernel will manage. Shared between task message queues and regular message queues.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before OSInit(). If it is not called, default values will be used.

OS_ConfigureStkLimit()#

Description#

Configure the application stack limit.

Files#

os.h/os_core.c

Prototype#

void  OS_ConfigureStkLimit (CPU_STK_SIZE  task_stk_limit)

Arguments#

task_stk_limit

Stack limit in percentage to empty.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before OSInit(). If it is not called, default values will be used.

OS_ConfigureStatTask()#

Description#

If enabled, configure the Statistics Task.

Files#

os.h/os_core.c

Prototype#

void  OS_ConfigureStatTask  (OS_TASK_CFG  *p_stat_task_cfg)

Arguments#

p_stat_task_cfg

Pointer to the Statistics Task configuration.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before OSInit(). If it is not called, default values will be used.

OS_ConfigureTmrTask()#

Description#

If enabled, configure the Timer Management Task.

Files#

os.h/os_core.c

Prototype#

void  OS_ConfigureTmrTask (OS_TASK_CFG  *p_tmr_task_cfg)

Arguments#

p_tmr_task_cfg

Pointer to the Timer Management Task configuration.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before OSInit(). If it is not called, default values will be used.