osapi.h

Philips ARM KPC2xxx series Real Time Operating System. Premptive System.

 *    important if the ISR is using services from the operating system, since 
 *    some services need to know if they are executed from an ISR or not. The 
 *    function osISRExit should be used before the ISR returns to 
 *    notify the operating system about the ISR exit. 
 *
 ****************************************************************************/
void osISREnter(void);


/*****************************************************************************
 *
 * Description:
 *    This function is used to notify the operating system that the currently 
 *    serviced interrupt is about to exit. The function is always used in 
 *    conjunction with the function osISREnter, which should always 
 *    be called before osISRExit. It is important to notify the OS 
 *    about ISRs (Interrupt Service Routines) if they are using services from 
 *    the operating system (since some services need to know if they are 
 *    executed from an ISR or not). 
 *
 ****************************************************************************/
void osISRExit(void);


/*****************************************************************************
 *
 * Description:
 *    This function initializes a counting semaphore and must be called before 
 *    any other function is used on the semaphore. 
 *
 * Params:
 *    [in] pSem    - A pointer to an allocated counting semaphore structure. 
 *    [in] initial - The initial counter value. 
 *
 ****************************************************************************/
void osSemInit(tCntSem* pSem,
               tU16     initial);


/*****************************************************************************
 *
 * Description:
 *    This function takes a counting semaphore, i.e. decreasing the semaphore 
 *    counting. If the semaphore counter is zero the function will block until 
 *    another process or an ISR gives the semaphore or a timeout occurs. 
 *
 * Params:
 *    [in]  pSem    - A pointer to an initialized semaphore structure. 
 *    [in]  timeout - After timeout ticks the operation will timeout. A 
 *                    timeout of zero means no timeout at all. 
 *    [out] pError  - The return status of the function. 
 *
 * Returns:
 *    TRUE if semaphore was taken and FALSE if timeout or error. 
 *
 * Error codes:
 *    OS_OK         - The function completed successfully. 
 *    OS_ERROR_ISR  - The function was called from an interrupt service 
 *                    routine. 
 *    OS_ERROR_NULL - A NULL pointer was supplied to the function where it was 
 *                    not allowed. 
 *
 ****************************************************************************/
tBool osSemTake(tCntSem* pSem,
                tU32     timeout,
                tU8*     pError);


/*****************************************************************************
 *
 * Description:
 *    This function gives a counting semaphore, i.e. increases the semaphore 
 *    counter. If there are one or more processes waiting for the semaphore 
 *    the process with highest priority is made ready to run. 
 *
 * Params:
 *    [in]  pSem   - A pointer to an initialized semaphore structure. 
 *    [out] pError - The return status of the function. 
 *
 * Error codes:
 *    OS_OK         - The function completed successfully. 
 *    OS_ERROR_NULL - A NULL pointer was supplied to the function where it was 
 *                    not allowed. 
 *
 ****************************************************************************/
void osSemGive(tCntSem* pSem,
               tU8*     pError);


/*****************************************************************************
 *
 * Description:
 *    This function tries to take a counting semaphore. If the semaphore 
 *    cannot be taken the function immediately returns instead of blocking. 
 *    This function can be used from an ISR (interrupt service routine). 
 *
 * Params:
 *    [in]  pSem   - A pointer to an initialized semaphore structure. 
 *    [out] pError - The return status of the function. 
 *
 * Returns:
 *    0 if the semaphore was taken, else 1. 
 *
 * Error codes:
 *    OS_OK         - The function completed successfully. 
 *    OS_ERROR_NULL - A NULL pointer was supplied to the function where it was 
 *                    not allowed. 
 *
 ****************************************************************************/
tU8 osSemTryTake(tCntSem* pSem,
                 tU8*     pError);


/*****************************************************************************
 *
 * Description:
 *    This function initializes a queue structure. 
 *
 * Params:
 *    [in] pQueue     - A pointer to an allocated queue structure. 
 *    [in] pQueueArea - A pointer to the queue area. The user must allocate 
 *                      the memory area used by the queue. The queue area is 
 *                      an array of void pointers. 
 *    [in] size       - The size of the queue area. The size is given in 
 *                      number of void pointers in the area. 
 *
 ****************************************************************************/
void osCreateQueue(tQueue* pQueue,
                   void**  pQueueArea,
                   tU16    size);


/*****************************************************************************
 *
 * Description:
 *    This function retrieves the first message from the queue. The message is 
 *    removed from the queue. If the queue is empty the function will block 
 *    until there is a message to retrieve or a timeout occurs. 
 *
 * Params:
 *    [in]  pQueue  - A pointer to an initialized queue structure. 
 *    [in]  timeout - The number of ticks to wait on a queue before returning. 
 *                    If a timeout of zero is specified the function will 
 *                    never timeout. 
 *    [out] pError  - The return status of the function. 
 *
 * Returns:
 *    The first message in the queue or NULL if timeout or error. 
 *
 * Error codes:
 *    OS_OK         - The function completed successfully. 
 *    OS_ERROR_ISR  - The function was called from an interrupt service 
 *                    routine. 
 *    OS_ERROR_NULL - A NULL pointer was supplied to the function where it was 
 *                    not allowed. 
 *
 ****************************************************************************/
void* osPendQueue(tQueue* pQueue,
                  tU16    timeout,
                  tU8*    pError);


/*****************************************************************************
 *
 * Description:
 *    This function tries to receive the first message from the queue. If the 
 *    queue is empty the function returns immediately. This function can be 
 *    called from within an interrupt service routine (ISR). 
 *
 * Params:
 *    [in]  pQueue - A pointer to an initialized queue structure. 
 *    [out] pError - The return status of the function. 
 *
 * Returns:
 *    The retrieved message or NULL if the queue is empty. 
 *
 * Error codes:
 *    OS_OK         - The function completed successfully. 
 *    OS_ERROR_NULL - A NULL pointer was supplied to the function where it was 
 *                    not allowed. 
 *
 ****************************************************************************/
void* osAcceptQueue(tQueue* pQueue,
                    tU8*    pError);


/*****************************************************************************
 *
 * Description:
 *    This function clears a queue from all messages. 
 *
 * Params:
 *    [in]  pQueue - A pointer to an initialized queue. 
 *    [out] pError - The return status of the function. 
 *
 * Error codes:
 *    OS_OK         - The function completed successfully. 
 *    OS_ERROR_NULL - A NULL pointer was supplied to the function where it was 
 *                    not allowed. 
 *
 ****************************************************************************/
void osFlushQueue(tQueue* pQueue,
                  tU8*    pError);


/*****************************************************************************
 *
 * Description:
 *    This function posts a new message to the end of the queue. 
 *
 * Params:
 *    [in]  pQueue - A pointer to an initialized queue structure. 
 *    [in]  msg    - The message to post. 
 *    [out] pError - The return status of the function. 
 *
 * Error codes:
 *    OS_ERROR_QUEUE_FULL - The queue is full. 
 *    OS_OK               - The function completed successfully. 
 *    OS_ERROR_NULL       - A NULL pointer was supplied to the function where 
 *                          it was not allowed. 
 *
 ****************************************************************************/
void osPostQueue(tQueue* pQueue,
                 void*   msg,
                 tU8*    pError);


/*****************************************************************************
 *
 * Description:
 *    This function posts a new message to the front of the queue. 
 *
 * Params:
 *    [in]  pQueue - 
 *    [in]  msg    - The message to post. 
 *    [out] pError - The return status of the function. 
 *
 * Error codes:
 *    OS_ERROR_QUEUE_FULL - The queue is full. 
 *    OS_OK               - The function completed successfully. 
 *    OS_ERROR_NULL       - A NULL pointer was supplied to the function where 
 *                          it was not allowed. 
 *
 ****************************************************************************/
void osPostFrontQueue(tQueue* pQueue,
                      void*   msg,
                      tU8*    pError);


/*****************************************************************************
 *
 * Description:
 *    This function initializes a timer. A timer is initialized with a timer 
 *    value, specified in timer ticks. When the specified time has elapsed the 
 *    timer is said to fire. When a timer fire the callback function of the 
 *    timer is executed. A timer can be set to be repeatable. A repeatable 
 *    timer is reactivated once the callback function has returned. The timer 
 *    structure must be allocated, statically or dynamically, by the user 
 *    before this function is used. osCreateTimer does not allocate the 
 *    structure, it initializes and queues the timer. 
 *
 * Params:
 *    [in] pTimer   - A pointer to an allocated timer structure. 
 *    [in] callback - The callback to be used when the timer fires. 
 *    [in] repeat   - If TRUE the timer will be reactivated as soon as the 
 *                    callback function has returned. 
 *    [in] time     - The initial timer value, specified in system ticks. 
 *
 ****************************************************************************/
void osCreateTimer(tTimer* pTimer,
                   void    (*callback) (void),
                   tBool   repeat,
                   tU32    time);


/*****************************************************************************
 *
 * Description:
 *    This function deletes a timer. The timer structure is not de-allocated, 
 *    only removed from the timer queue. If the timer has already fired and is 
 *    not repeatable there is no need to call this function. It is only 
 *    meaningful to call this function on a timer that is armed but not fired. 
 *
 * Params:
 *    [in]  pTimer - A pointer to the timer to delete. 
 *    [out] pError - The return status of the function. 
 *
 * Error codes:
 *    OS_OK         - The function completed successfully. 
 *    OS_ERROR_NULL - A NULL pointer was supplied to the function where it was 
 *                    not allowed. 
 *
 ****************************************************************************/
void osDeleteTimer(tTimer* pTimer,
                   tU8*    pError);


/*****************************************************************************
 *
 * Description:
 *    This function initializes the timer process. The timer process runs on 
 *    the highest priority, i.e. 0, and executes the timer callback function 
 *    when a timer expires. No other process should be run on this priority. 
 *
 * Params:
 *    [out] pError - The return status of the function. 
 *
 * Error codes:
 *    OS_OK             - The function completed successfully. 
 *    OS_ERROR_ALLOCATE - The timer process could not be created since there 
 *                        was no free process control blocks available. The 
 *                        number of process control blocks is specified during 
 *                        operating system configuration (maximum number of 
 *                        processes). 
 *
 ****************************************************************************/
void osInitTimers(tU8* pError);


/*****************************************************************************
 *
 * Description:
 *    This function returns the stack usage. The stack usage is based on the 
 *    maximum size used so far, i.e. from the application start to the point 
 *    where this function is called. 
 *
 * Params:
 *    [in] pid - The pid of the process to check. 
 *
 * Returns:
 *    The used fraction of the stack area specified in percent. 
 *
 ****************************************************************************/
tU8 osStackUsage(tU8 pid);

/*
 * The following functions should only be called from a hardware
 * abstraction layer.
 */


/*****************************************************************************
 *
 * Description:
 *    This function must be called periodically, usually from a timer 
 *    interrupt, to generate a system tick. It is essential to the operating 
 *    system to receive a periodic tick to work at all. All times in the 
 *    operating system is measured in system ticks, i.e. the time between two 
 *    system ticks. 
 *
 ****************************************************************************/
void osTick(void);


/*****************************************************************************
 *
 * Description:
 *    This function implements the scheduling policy and modifies the 
 *    pNxtToRun pointer to point to the process that should run according to 
 *    the policy. The policy is to always run the process with the highest 
 *    priority that is ready to run. If there is more than one process with 
 *    the highest priority, the processes are scheduled in a round-robin 
 *    fashion. 
 *
 ****************************************************************************/
void osGetHighPrioProc(void);

#endif