The C Kernel Application Programming Interface

Definitions and macro's

• KERNEL_FREQUENCY
• MS_TO_KERNELCOUNT(x)

Exported Variables

• CK_Version
• CK_VersionStr

Initialization

• CK_Init
• CK_Run

Task Management

• CK_CreateTask
• CK_DeleteTask
• CK_SetPriority
• CK_GetPriority
• CK_SetTimeSlice
• CK_GetTimeSlice
• CK_GetActiveTask
• CK_Sleep
• CK_Suspend
• CK_Resume
• CK_Yield

Semaphore Management

• CK_CreateSema
• CK_DeleteSema
• CK_Wait
• CK_TestWait
• CK_Signal
• CK_ISRsignal

Mailbox/Message Management

• CK_CreateMbox
• CK_DeleteMbox
• CK_Receive
• CK_TestReceive
• CK_Send
• CK_ISRsend

Region Management

• CK_CreateRegion
• CK_DeleteRegion
• CK_Lock
• CK_TestLock
• CK_Unlock

Timer Management

• CK_CreateTimer
• CK_DeleteTimer
• CK_StartTimer
• CK_RestartTimer
• CK_StopTimer
• CK_GetTimeRemaining

Clock Management

• CK_SetTime
• CK_GetTime

#define KERNEL_FREQUENCY ((int16u) ((int32u) 1000000 / \
(int32u) KERNEL_TICKRATE))
#define MS_TO_KERNELCOUNT(x) ((int16u) ((int32u) (x) * (int32u) 1000 / \
(int32u) KERNEL_TICKRATE))

/**** EXPORTED VARIABLES ****/

/**** The C Kernel global version number (V x.yy multiply by 100) ****/
extern const int16u CK_Version;
/**** The C Kernel global version number in string format ****/
extern const int8s CK_VersionStr[];

Top

/**** KERNEL INITIALIZATION SECTION ****/

/****************************************************************************/
int16s CK_Init (void);
/****************************************************************************/
/*
* Initializes the C Kernel. This call must be called before any other call
* is used to the C Kernel. All resources are initialized, kernel timing is
* initialized and the Idle task is created with priority 0 (lowest).
* CK_Init turns off all interrupts. The application should not enable
* interrupts before CK_Run is called.
*
* Parameters: None
*
* Returns: CK_OK Success
* CK_NO_QUEUE Failed to allocate Queue resources
* CK_NO_TCB Failed to allocate Idle Task resource
*/

/****************************************************************************/
void CK_Run (void);
/****************************************************************************/
/*
* This function starts the scheduler, this means that the task with the
* highest priority in the ready list becomes the running task. A call to this
* function never returns. This function should be the last function call in
* the main function body in order to start your multitasking application.
*
* Parameters: None
*
* Returns: Never!
*/

Top

/**** KERNEL TASK MANAGEMENT FUNCTIONS ****/

/****************************************************************************/
int8u CK_CreateTask (taskptr taskFunction, int8u priority,

stacktype *stackBasePtr, int16u stackSize);
/****************************************************************************/
/*
* This function creates a task. The user must pass the function address, the
* task's initial priority and the stack definition for this task.
* When the kernel is already running due to a call to CK_Run, the
* new task will be placed on the ready list. The kernel does not perform
* a reschedule, since this is the responsibility of the task that created
* the new task (for example by calling CK_Yield).
*
* Parameters: taskFunction The task's function address
* priority The task's initial priority
* stackBasePtr The task's stack base definition
* stackSize Stack size to use for this task
* Specify number of stacktypes, not bytes
*
* Returns: Task Id On success
* NR_OF_TASKS On Failure (defined in ck_cfg.h)
*/

/****************************************************************************/
int16s CK_DeleteTask (int8u id);
/****************************************************************************/
/*
* The task specified will be deleted from the system. If the task was the
* running task, this will force a reschedule. If the task was in any
* of the system resource queues, the task is deleted from that queue, the
* resource is handled properly and finally the task will be deleted.
*
* Parameters: id The Task Id to delete
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Task Id specified
* CK_ILLEGAL_STATE Task resource already free
* CK_REGIONS_LOCKED Task has Regions locked
*/

/****************************************************************************/
int16s CK_SetPriority (int8u id, int8u priority);
/****************************************************************************/
/*
* The priority of the specified task id will be set. This kernel function
* will check if it is necessary to reschedule.
*
* Parameters: id The Task Id to set the new priority for
* priority New priority for task
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Task Id specified
* CK_ILLEGAL_STATE Task resource was freed
*/

/****************************************************************************/
int8u CK_GetPriority (int8u id);
/****************************************************************************/
/*
* The priority of the specified task id will be returned. If an illegal
* task id is passed, the priority returned is 0.
*
* Parameters: id The Task Id to get the priority from
*
* Returns: 0 Illegal Task Id or unallocated TCB
* priority Current priority of task
*/

/****************************************************************************/
void CK_SetTimeSlice (int16u ticks);
/****************************************************************************/
/*
* The time-slice value for round-robin scheduling will be set. Initially
* it is set to a predefined value (CK_CFG.H). The value must be specified
* as a number of system ticks. The time-slice value is used for round-robin
* scheduling between tasks with equal priority.
*
* Parameters: ticks Number of system ticks for scheduling
*
* Returns: None
*/

/****************************************************************************/
int16u CK_GetTimeSlice (void);
/****************************************************************************/
/*
* The time-slice value used by the kernel for round-robin scheduling will
* be returned.
*
* Parameters: None
*
* Returns: ticks Number of system ticks for scheduling
*/

/****************************************************************************/
int8u CK_GetActiveTask (void);
/****************************************************************************/
/*
* Returns the task id of the ActiveTask, which is currently running. The
* task that calls this function, which is of course the running (active)
* task, gets the own task identification returned.
*
* Parameters: None
*
* Returns: Task Id The calling task's own Id
*/

/****************************************************************************/
void CK_Sleep (int16u ticks);
/****************************************************************************/
/*
* Puts the calling task to sleep for the specified number of system ticks.
* This call will force a reschedule.
*
* Parameters: ticks Number of system ticks for sleep period
*
* Returns: None
*/

/****************************************************************************/
int16s CK_Suspend (int8u id);
/****************************************************************************/
/*
* Suspends the specified task. If the task is the running task, this will
* force a reschedule. The suspension depth of the specified task will be
* incremented by one, which means that a task may be suspended more than
* once. The task has to be in one of the states TASK_READY, TASK_RUNNING,
* TASK_SLEEP, TASK_SUSPENDED or TASK_SLEEP_SUSPENDED.
*
* Parameters: id The Task Id to suspend
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Task Id specified
* CK_REGIONS_LOCKED Task has Regions locked
* CK_MAX_SUSPENDED Task has reached max. suspension depth
* CK_ILLEGAL_STATE Task is in illegal state for suspend
*/

/****************************************************************************/
int16s CK_Resume (int8u id);
/****************************************************************************/
/*
* Resumes the specified task, this means that the suspension depth is
* decremented. When the task state is TASK_SUSPEND, the task is put back
* on the ready list when the suspension depth has reached zero, this can
* result in a reschedule. When the task state is TASK_SLEEP_SUSPEND, the
* task state will become TASK_SLEEP when the suspension depth has reached
* zero. Other states than TASK_SUSPENDED or TASK_SLEEP_SUSPENDED are not
* allowed.
*
* Parameters: id The Task Id to resume
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Task Id specified
* CK_ILLEGAL_STATE Task is in illegal state for resume
*/

/****************************************************************************/
void CK_Yield (void);
/****************************************************************************/
/*
* The calling task gives up the processor. This kernel service can be used for
* round-robin scheduling between tasks with equal priority. When the caller
* has the highest priority, this call has no effect since the highest
* priority task always gets the processor, then the task gives the processor
* to itself. Another example of using this kernel service is when a task
* has created another task. This new task is put in the ready list, but
* no check is performed if a reschedule has to occur. The 'parent' task can
* do this by calling CK_Yield.
*
* Parameters: None
*
* Returns: None
*/

Top

/**** KERNEL SEMAPHORE FUNCTIONS ****/

/****************************************************************************/
int8u CK_CreateSema (int16s count, int8u mode);
/****************************************************************************/
/*
* This function creates a semaphore. When the semaphore can be created, the
* id will be returned. If it can not be created NR_OF_SEMAS (as defined in
* configuration file CK_CFG.H) will be returned. The value passed is the
* initial semaphore count (must be >= 0 initially). If the count passed
* is negative also NR_OF_SEMAS will be returned. Semaphores used for mutual
* exclusion of resources or data must be initialized to 1 (defined as
* MUTEX_SEMA). The mode byte can be used to specify priority-based task
* queues or fifo-based task queues, see definitions in header file.
*
* Parameters: count Initial Semaphore count
* mode Either PRIO_Q or FIFO_Q
*
* Returns: Semaphore Id On success
* NR_OF_SEMAS On Failure (defined in ck_cfg.h)
*/

/****************************************************************************/
int16s CK_DeleteSema (int8u id);
/****************************************************************************/
/*
* This function deletes the given semaphore. If tasks were waiting on the
* semaphore queue, they will be put back on the ready list after which the
* scheduler will be called to check for higher priority tasks than the
* running one.
*
* Parameters: id The Sema Id to delete
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Sema Id specified
*/

/****************************************************************************/
int16s CK_Wait (int8u id);
/****************************************************************************/
/*
* This function waits for the given semaphore. This means that the count
* of the semaphore is decremented. If the count remains nonnegative, the
* function returns immediately to the calling task. Otherwise it enqueues
* the calling task on the waiting list for the semaphore, sets the state
* to TASK_WAIT and performs a reschedule. Once enqueued, the task remains on
* the waiting list until it reaches the head of the queue and some other
* process signals the semaphore.
*
* Parameters: id The Sema Id to perform a Wait on
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Sema Id specified
* CK_SEMA_DELETED Semaphore was deleted while waiting
*/

/****************************************************************************/
bool CK_TestWait (int8u id);
/****************************************************************************/
/*
* This function tests if the given semaphore has a unit available. If the
* semaphore has no units or some error occurred (illegal id), FALSE will
* be returned. If there were units available, the calling task executes
* the wait operation immediately (thus gets the unit) and TRUE will be
* returned.
*
* Parameters: id The Sema Id to perform a TestWait on
*
* Returns: TRUE A semaphore unit was available
* FALSE No semaphore unit available or illegal Id
*/

/****************************************************************************/
int16s CK_Signal (int8u id);
/****************************************************************************/
/*
* This function signals the given semaphore. This means that the count
* of the semaphore is incremented. When the semaphore queue is not empty
* (the count is negative), this function inserts a waiting task in the
* ready list from the head of the semaphore queue, after which a reschedule
* can occur.
*
* Parameters: id The Sema Id to signal
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Sema Id specified
*/

/****************************************************************************/
int16s CK_ISRsignal (byte id);
/****************************************************************************/
/*
* This function must be called from an interrupt context and signals the
* given semaphore. The interrupt policy in the kernel is that interrupt
* processing must be performed as quickly as possible, so interrupt handlers
* from the application can only use this call to signal the system that
* an interrupt has occurred. Normally, a waiting (interrupt-) task will be
* placed in the ready list and the kernel checks if a reschedule has to
* be performed. If so, the new (interrupt-) task will be started, and the
* interrupt context is finished.
*
* NOTE: This function must be called from the first level of the
* interrupt handler context (no further calling depth is allowed) !!
* If not, stacks will become corrupted.
*
* Parameters: id The Sema Id to signal
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Sema Id specified
*/

Top

/**** KERNEL MESSAGE FUNCTIONS ****/

/****************************************************************************/
int8u CK_CreateMbox (int8u mode);
/****************************************************************************/
/*
* This function creates a mailbox. When the mailbox can be created, the
* id will be returned. If it can not be created NR_OF_MBOXS (as defined in
* configuration file CK_CFG.H) will be returned. A mailbox can be used
* to send messages to it or receive messages from it. Messages actually
* consist of a 4-byte field in which the data is placed. The format of
* this data is defined by the application. If the mailbox can not be created
* the value NR_OF_MBOXS will be returned to indicate an error. The mode byte
* can be used to specify priority-based task queues or fifo-based task
* queues.
*
* Parameters: mode Either PRIO_Q or FIFO_Q
*
* Returns: Mailbox Id On success
* NR_OF_MBOXS On Failure (defined in ck_cfg.h)
*/

/****************************************************************************/
int16s CK_DeleteMbox (int8u id);
/****************************************************************************/
/*
* This function deletes the given mailbox. If tasks were waiting on the
* mailbox queue, they will be put back on the ready list after which the
* scheduler will be called to check for higher priority tasks than the
* running one. If messages were queued in the mailbox, the messages are
* released (freed) to the system.
*
* Parameters: id The Mailbox Id to delete
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Mailbox Id specified
*/

/****************************************************************************/
int16s CK_Receive (int8u id, int32u *msgPtr);
/****************************************************************************/
/*
* With this function a message can be received from a mailbox. The message
* is defined as a 4-byte field pointed to by msgPtr. If the message is
* received, the information will be copied into the area pointed to by
* msgPtr. If messages are queued in the mailbox message queue, the message
* at the head of the message queue is received. If however the message queue
* is empty, the calling task will be enqueued in the mailbox task queue,
* either at the tail (fifo) or according to priority.
*
* Parameters: id The Mailbox Id to perform a Wait on
* msgPtr Pointer to 4-byte message
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Mailbox Id specified
* CK_MBOX_DELETED Mailbox was deleted while waiting
*/

/****************************************************************************/
bool CK_TestReceive (int8u id, int32u *msgPtr);
/****************************************************************************/
/*
* This function tests if a message is available on the given mailbox. If
* there is no message available or some other occurred (illegal id),
* FALSE will be returned. If a message was available, the calling task
* receives the message in msgPtr and TRUE will be returned.
*
* Parameters: id The Mailbox Id to do a TestReceive on
*
* Returns: TRUE A message was available
* FALSE No messages available or illegal Id
*/

/****************************************************************************/
int16s CK_Send (int8u id, int32u msg);
/****************************************************************************/
/*
* With this function a message can be sent to a mailbox. The message is
* defined as a 4-byte field passed by msg. Internally a message item
* will be allocated to store the information and, if necessary, to queue
* the message in the mailbox message queue. If however tasks were waiting
* for messages, the message is sent immediately to the task at the head of
* the task queue waiting on the mailbox, after which the task is put back on
* the ready list. If the message can not be sent due to an allocation
* error for the message or an invalid id, CK_FAILED will be returned.
*
* Parameters: id The Mailbox Id to send to
* msg The 4-byte message to send
*
* Returns: CK_OK Success
* CK_FAILED Failed to send message (no resource)
* CK_ILLEGAL_ID Illegal Mbox Id specified
*/

/****************************************************************************/
int16s CK_ISRsend (int8u id, int32u msg);
/****************************************************************************/
/*
* The same functionality as CK_Send is supplied by this function. However,
* this function should be called from an interrupt context and sends the
* message to the given mailbox. The interrupt policy in the kernel is that
* interrupt processing must be performed as quickly as possible, so
* interrupt handlers from the application can only use this call to signal
* the system that an interrupt has occurred. Normally, a waiting (interrupt-)
* task will be placed in the ready list and the kernel checks if a
* reschedule has to be performed. If so, the new (interrupt-) task will be
* started, and the interrupt context is finished.
*
* NOTE: This function must be called from the first level of the
* interrupt handler context (no further calling depth is allowed) !!
* If not, stacks will become corrupted.
*
* Parameters: id The Mailbox Id to send to
* msg The 4-byte message to send
*
* Returns: CK_OK Success
* CK_FAILED Failed to send message (no resource)
* CK_ILLEGAL_ID Illegal Mbox Id specified
*/

Top

/**** KERNEL REGION FUNCTIONS ****/

/****************************************************************************/
int8u CK_CreateRegion (void);
/****************************************************************************/
/*
* This function creates a priority region. When the region can be created,
* the id will be returned. If it can not be created NR_OF_REGIONS (as defined
* in configuration file CK_CFG.H) will be returned.
*
* A region is actually a mutual exclusion semaphore that solves the
* priority inversion problem that can occur when using semaphores. Priority
* inversion occurs in the following situation. Two tasks, one low and one
* high, both use a mutex semaphore. Task low gets the semaphore, task high
* preempts task low and also wants access to the semaphore resulting in
* task high being transferred to the waiting state, since low has gained
* control. When at this moment a task with medium priority comes in, task
* low is preempted by task medium while task high is still waiting for the
* semaphore. In most cases this situation is not desirable, since it can
* take a long time before task high finally gets the semaphore.
*
* To solve this problem regions can be used. When a low priority task
* has locked the region, while a high priority task is waiting to gain
* control over the region, the priority of task low is temporarily raised
* to the same priority as task high. When the region is unlocked, the
* task's priority is restored to the original level.
*
* NOTE: tasks that have one or more regions locked, can not be suspended
* or deleted.
*
* Parameters: None
*
* Returns: Region Id On success
* NR_OF_REGIONS On Failure (defined in ck_cfg.h)
*/

/****************************************************************************/
int16s CK_DeleteRegion (int8u id);
/****************************************************************************/
/*
* This function deletes the given region. If tasks were waiting on the
* region queue, they will be put back on the ready list after which the
* scheduler will be called to check for higher priority tasks than the
* running one.
*
* Parameters: id The Region Id to delete
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Region Id specified
*/

/****************************************************************************/
int16s CK_Lock (int8u id);
/****************************************************************************/
/*
* This function tries to lock the given region. If the region is already
* locked, the calling task will be put in the region's task queue (priority)
* and the task state will be set to TASK_WAIT. The task that had locked the
* region may temporarily receive a higher priority, if necessary. If the
* region was not locked, this function will lock the region and return
* immediately.
*
* Parameters: id The Region Id to lock
*
* Returns: CK_OK Success
* CK_ILLEGAL_ID Illegal Region Id specified
* CK_REGION_DELETED Region was deleted while waiting
*/

/****************************************************************************/
bool CK_TestLock (int8u id);
/****************************************************************************/
/*
* This function tests if the given region can be locked. If the region is
* already locked or some other error occurred (illegal id), FALSE will
* be returned. If the region was not locked, the calling task gets control
* over the region and TRUE will be returned.
*
* Parameters: id The Region Id to do a test lock on
*
* Returns: TRUE The Region was tested and locked
* FALSE Region not locked or illegal Id specified
*/

/****************************************************************************/
int16s CK_Unlock (int8u id);
/****************************************************************************/
/*
* This function unlocks the region. When there were tasks waiting in
* the region queue, the first task will be put back on the ready list, the
* region remains locked and the new task that has control can have its
* priority raised (when there are still more tasks in the queue). When
* there were no more tasks waiting for the region, the region is unlocked.
*
* Parameters: id The Region Id to unlock
*
* Returns: CK_OK Success
* CK_FAILED Failed to unlock; locked by another!
* CK_ILLEGAL_ID Illegal Region Id specified
*/

Top

Top