PortLib (POsix Real-Time LIBrary) is a library that helps porting applications written for the VxWorks real-time system to a Unix-compatible system providing the Posix.4 real-time extensions.
portLib defines the following types:
typedef int (*FUNCPTR) (); typedef int (*INTFUNCPTR)(); typedef void (*VOIDFUNCPTR)(); typedef float (*FLTFUNCPTR)(); typedef double (*DBLFUNCPTR)(); typedef void *(*VOIDPTRFUNCPTR)();
WAIT_FOREVER NO_WAIT MIN MAX
S_portLib_NO_MEMORY S_portLib_NO_SUCH_TASK S_portLib_NOT_IN_A_TASK S_portLib_INVALID_TASKID S_portLib_NOT_IMPLEMENTED
Any Unix process that wants to use portLib functions should call the
osInit function first. Not that this function is also
called by the comLib Initialisation function
(h2initGlob). Hence a task using
h2initGlob() to initialize comLib and portLib doesn't need to
#include <portLib.h> STATUS osInit(int clkRate)
osInit() initializes the real-time OS library. It should be called one
before any call to other functions of the library. The clkRate parameter
specifies the clock rate used in this process. A value of 0 disables the
clock. The maximum value on most systems is the HZ constant, which is
generally equal to 100.
ERROR in case of an error. Then it sets
the errno value of the task.
PortLib uses Posix threads to implement VxWorks tasks. All fonctionalities of VxWorks tasks are not present. Especially, portLib uses the default Linux scheduler in the Posix threads implementation, which doesn't share VxWorks real-time capabilities.
#include <taskLib.h> long taskSpawn(char *name, int priority, int options, int stackSize, FUNCPTR entryPt, ...)
taskSpawn() function creates a new task in pocoLib. name is the
external name given to the new task. priority is the priority of the new
task. The value is interpreted following the VxWorks convention, where 0
is the highest priority and 255 the lowest one. The mapping of the prior‐
ity specified here to priorities provided by the underlying system is
implementation-dependant. options is an OR-ed mask of possible task
options. Valid options include:
: Indicates that the given task is using floating point
values in expressions, and thus hints the underlying
system that the floating-point context of the task
should be saved and restored across task switches.
stackSize specifies the amount of memory to use for the stack of the new
task. Not all systems use the specified value. entryPt is the pointer to
a function returning an int and taking up to ten integer parameters. The
rest of the parameters (up to ten integers) passed to
transmitted to the new function.
#include <taskLib.h> long taskSpawn2(const char *name, int priority, int options, int stackSize, void *(*start_routine)(void *), void *arg);
taskSpawn2() is similar to
taskSpawn except that the calling
convention of the function run in the new task follows the
pthread_create prototype, which is more portable and permits to pass
arbitrary types to the new task. This should be used instead of
taskSpawn() in new code.
#include <taskLib.h> STATUS taskDelete(long taskId)
taskDelete() function deletes (terminates) the specified task.
#include <taskLib.h> STATUS taskSuspend(long taskId)
taskSuspend() function is supposed to suspend the execution of
the given task. In the implementation of pocoLibs on POSIX systems,
it is implemented by a call to
abort(2) in order to save a core image
of the process. This is done this way because in traditional pocoLibs
taskSuspend() is used to stop a failed task for
#include <taskLib.h> STATUS taskDelay(int ticks)
taskDelay() function suspends the execution of the current task for
the specified number of ticks.
#include <taskLib.h> long taskIdSelf(void)
taskIdSelf() function returns the identifier of the current task. In
most of the above mentionned functions, if tid is zero, it will design
the current task (ie
#include <taskLib.h> STATUS taskSetUserData(long taskId, unsigned long data)
#include <taskLib.h> unsigned long taskGetUserData(long taskId)
#include <taskLookLib.h> STATUS taskCreateHookAdd(FUNCPTR createHook);
#include <taskLookLib.h> STATUS taskCreateHookDelete(FUNCPTR createHook);
#include <taskLookLib.h> STATUS taskSwitchHookAdd(FUNCPTR switchHook);
#include <taskLookLib.h> STATUS taskSwitchHookDelete(FUNCPTR switchHook);
#include <taskLookLib.h> STATUS taskDeleteHookAdd(FUNCPTR deleteHook);
#include <taskLookLib.h> STATUS taskDeleteHookDelete(FUNCPTR deleteHook);
The sysLib library groups all functions that are system dependant and provided by board support packages (BSP) under VxWorks. In the case of pocoLibs, only clock handling functions are provided by sysLib.
#include <tickLib.h> void tickAnnounce(void)
tickAnnounce() is a function provided to be used as the default
handler for the system clock. This function handles the expiration of
the system watch dogs for pocoLibs and handles the tick counter. The
default pocoLibs initialization routine,
h2initGlob() registers this
function as handler of the system clock.
#include <tickLib.h> unsigned long tickGet(void)
ticGet() returns the current value of the tick counter.
#include <tickLib.h> void tickSet(unsigned long ticks)
tickSet() sets the value of the tick counter to the value of ticks.
#include <sysLib.h> STATUS sysClkRateSet(int ticksPerSecond)
The rate of the system clock can be set with the
tion, to the given ticksPerSecond value. The initial rate of the system
clock is defined by the call to
ERROR if an error occured.
#include <sysLib.h> int sysClkRateGet(void)
The current rate of the system clock is returned by the sysClkRateGet() function.
When a function fails it calls
errnoSet() with the error code returned
by the underlying operating system. There is no sysLib specific error
code defined in pocoLibs.
On POSIX based systems, the system clock can be implemented by using
either POSIX defined real-time timers, using
traditionnal Unix timers based on
setitimer(2). On certain Linux
kernel revisions the setitimer based timers offer better performance
than the POSIX real-time timers. Normally the configure script probes
the behaviour of both kind of timers and selects the best suiting
--disable-posix-timers configure option can be used to
force use of traditional Unix timers at build time.
Linking pocoLibs application with external libraries that use the
SIGALRM signal is known to cause problems to the system clock.
In the case of a POSIX-style operating system, all these three semaphore types are local to the Unix process that created them.
#include <semLib.h> SEM_ID semBCreate(int options, SEM_B_STATE initialState)
semBCreate() creates a binary semaphore.
options can be
SEM_Q_FIFO to specify that tasks waiting on the
semaphore are dequeued in a FIFO order, or
SEM_Q_PRIORITY to specify
that tasks waiting on the semaphore are dequeued by decreasing
initialState indicates the initial state of a binary semaphore, either
#include <semLib.h> SEM_ID semCCreate(int options, int initialCount)
semCCreate() creates a counting semaphore.
value indicates the initial value of a counting semaphore.
#include <semLib.h> SEM_ID semMCreate(int options)
semMCreate() Creates a ticket lock which can be used as a mutual
#include <semLib.h> STATUS semDelete(SEM_ID sem)
semDelete() deletes a semaphore from the process and releases any
resources used by the semaphore. sem is the identifier of the
semaphore to delete.
The behaviour of processes blocked on a semaphore when it is deleted is not defined.
#include <semLib.h> STATUS semGive(SEM_ID sem)
semGive() implements the V operation on the given semaphore.
#include <semLib.h> STATUS semTake(SEM_ID sem, int timeout)
semTake() implements the P operation on the semaphore.
timeout specifies a number of tick in which the operation must
succeed. If the semaphore was not taken with this delay,
returned and the errno value of the task is set to
#include <semLib.h> STATUS semFlusuh(SEM_ID sem)
semFlush() resets the value of a counting or binary semaphore to 0
SEM_EMPTY, causing the next call to
semTake() to effectively
block the calling task.
semCCreate() return the semaphore identifier for the
newly created semaphore or
NULL in case of an error. In that case an
error code is left in the task's errno value.
ERROR in case an error occured. In that case an error code is
left in the task's errno value.
The task's errno value can be set to an error code from the operating system or to:
: A timeout occured on a
#include <wdLib.h> WDOG_ID wdCreate(void)
wdCreate() creates a new inactive watch dog.
#include <wdLib.h> STATUS wdDelete(WDOG_ID wdId)
wdDelete() destroys an exising watch dog.
#include <wdLib.h> STATUS wdStart(WDOG_ID wdId, int delay, FUNCPTR pRoutine, long parameter)
wdStart() starts the timer associated with a watch dog. wdId is a
watch dog identifier as returned by
wdCreate(). delay is the
number of ticks until the watch dog expires. pRoutine is a pointer
to a function that will be called when the timer expires. parameter
is an integer value that will be passed to the routine when it will be
#include <wdLib.h> STATUS wdCancel(WDOG_ID wdId)
wdCancel() cancels the active watchDog designated by wdId.
wdCreate() returns the identifier of the newly created watchdor or NULL
if an error occured.
an error ocurred. All functions set the task error code in case of
The error code of the current task can be set to:
: The allocation of memory for a new watchog failed.
: The wdId passed to a function is not valid.
errnoSet() are designed to emulate the VxWorks
function of the same name.
#include <errnoLib.h> int errnoGet(void)
errnoGet() returns the pocoLibs error code associated with the current task.
#include <errnoLib.h> STATUS errnoSet(int errorValue)
errnoSet() sets the pocoLibs error code associated with the current
thread to the value passed in errorValue.