Application Programming Interface

This page presents an overview of the API (Application Programming Interface) of AVIX. In detail the API can be found in the AVIX User Manual that can be downloaded from the Download page. The contents of this page is meant to present an overview and discuss the special attributes of the AVIX API.

API Properties

The AVIX API offers a number of properties not found in many other real time kernels that make working with AVIX easier and more error prone. These properties are:

• Entirelly Function Call Based: The entire API of AVIX is based on function calls. Never should the user of AVIX have to access AVIX internal data structures as is the case with many competing products. Although for its internal working AVIX uses a number of data structures, these are all internal and fully abstracted by the function interface offered. This leads to a much easier to use programming interface and thus introduces less programming errors.
   
• Clear Application Programming Interface: The AVIX API offers a number of functions to manipulate kernel objects as event groups, timers etc. The approach followed by many competing products is to give the API functions a large number of parameter to tune the functions behavior. In many situations these functions require don’t care for certain parameters. This makes it complicated to clearly understand what these functions actually do. The design approach followed by AVIX is that for a every function call, all parameters should be valid and have a clear meaning in the context of the function. No use is made of don’t care values, instead if this is applicable another function is specified with a limited number of parameters. An example are the functions avixEventGroup_Wait and avixEventGroupThread_Wait. The first waits for the desired flags in a global event group, the second waits for the desired flags in the private event group of the calling thread. This could also be done with one function where for the second case, instead of specifying an id of an event group, some don’t care value is supplied. By offering this as two separate functions, it is more clear what is happening and the chance on errors is minimized. Furthermore, AVIX uses a very clear naming schema for its functions. Every function begins with avix<object>, where object is the kernel object the function is working on. Next, separated with an underscore character (_) the function is expressed such that it is clear what the function is doing. Although this can lead to quite long function names, it minimizes the chance on mistakes. Finally, when arguments can have two possible values, no use is made of booleans but instead a type safe enumeration is used, clearly stating what the meaning of the parameter is..
   
• Type Safe: The AVIX API is largely type safe. When parameters of the wrong type are passed  this is detected compile time instead of runtime. The advantage is that errors are detected earlier and that runtime checks can be left behind thereby not cluttering the application code. As a whole this contributes to a higher quality of the application’s code. An example of this is the type of object id’s. Every kernel object (thread, mutex, timer, ...) is identified by an id. When the kernel object is created, the create function returns an id for the kernel object to the caller. When an operation is required on a kernel object, its id is used to identify which kernel object the operation is to be performed on. This is illustrated with an example. In the code section below you see a call to create a mutex object, followed by the call to lock the mutex. As you can see, the id returned from the create call is passed as a parameter to the lock call.

tavixMutex mutexId = avixMutex_Create(NULL, AVIX_MUTEX_UNLOCKED);
...;
avixMutex_Lock(mutexId);

When passing the mutex id to a thread function, which expects an id of type tavixThreadId instead of tavixMutexId, this is detected by the compiler so the programmer can fix the error before the program is actually running which would be much harder and take more time. This is shown in the code snippet below:

tavixMutexId mutexId = avixMutex_Create(NULL, AVIX_MUTEX_UNLOCKED);
...;
avixThread_Resume(mutexId);         // Thread call with id of incorrect type
 
error: incompatible type for argument 1 of `avixThreadResume’

Functions

The following functions are offered, categorized by functional area:

Interrupt Service Routine Functions

AVIX allows Interrupt Service Routines to directly use a substantial number of functions. These are listed in the table below. All but one of these functions come from a specific service category and is described in the applicable table. The one exception is avixDIH_Queue, a function forming the basis for Interrupt Service Routine/Thread integration. Through this function an additional number of other functions can be used from an Interrupt Service Routine.

Function Description avixDIH_Queue Register a Deferred Interrupt Handler to be activated when ISR’s are no longer active avixPipe_ReadFromISR See Pipe API avixPipe_WriteFromISR See Pipe API avixPipe_StopDeviceFromISR See Pipe API avixMemPool_AllocateFromISR See Memory Pool API avixMemPool_FreeFromISR See Memory Pool API avixMemPool_GetSizeBlockFromISR See Memory Pool API avixSemaphore_UnlockFromISR See Semaphore API avixThread_ResumeFromISR See Thread API avixMsg_AllocateFromISR See Message API avixMsg_SendFromISR See Message API avixMsg_Put<type>FromISR See Message API avixEventGroup_ChangeFromISR See Event Group API avixEventGroupThread_ChangeFromISR See Event Group API avixTimer_StartFromISR See Timer API avixTimer_StopFromISR See Timer API avixPower_GetModeFromISR See Power Management API avixPower_SetModeFromISR See Power Management API

Thread Functions

The basic entity of AVIX is formed by a thread. Essentially a thread is a function that runs under control of AVIX, as specified by the parameters the user defined when creating it. Threads are the major type of active entity which means that threads consume CPU cycles. During their execution, they make use of AVIX functions to manipulate other kernel objects, communicate and synchronize.

Function Description avixThread_ArmTimeOut Set a time-out value for the following potential blocking function avixThread_Create Create a new thread avixThread_Get Get a thread id of an existing thread and wait if not yet existent avixThread_GetIdCurrent Get id of current thread avixThread_Relinguish Abandon current round robin time slice avixThread_Resume Resume a suspended thread avixThread_ResumeFromISR Resume a suspended thread directly from an Interrupt Service Routine avixThread_SetTracePort Assign a trace port to a thread avixThread_SetTracePortAndResume Assign a trace port to a thread and resume the thread avixThread_Sleep Wait for specified time. During this time the thread is inactive avixThread_Suspend Suspend the calling thread avixThread_TimeOutOccured Test if the preceding potential blocking function timed out

Mutex Functions

Mutexes are used to guard critical sections where data is being manipulated for which it is essential that this manipulation is done uninterrupted. Mutexes are the only AVIX kernel objects with ownership. When a mutex is locked by a thread, there exists a relation between the mutex and the thread. A locked mutex can therefore only be unlocked by the owning thread. The reason for this is that Mutexes implement priority inheritance to solve the problem of priority inversion.

Function Description avixMutex_Create Create a new mutex avixMutex_Get Get a mutex id of an existing mutex and wait if not yet existent avixMutex_Lock Lock a mutex and wait if not available avixMutex_Unlock unlock a mutex

Semaphore Functions

Semaphores are kernel objects having a numeric value. They can be successfully locked as many times as this numeric value allows. After as many locks are taken as the initial count is set, locks will result in the calling thread to be blocked until the semaphore is unlocked again by another thread.

Function Description avixSemaphore_Create Create a new semaphore avixSemaphore_Get Get a semaphore id of an existing semaphore and wait if not yet existent avixSemaphore_Lock Lock a semaphore and wait if not available avixSemaphore_Unlock unlock a semaphore avixSemaphore_UnlockFromISR Unlock a semaphore directly from an Interrupt Service Routine.

Event Group Functions

Event groups are kernel objects maintaining binary flags that can be set, cleared toggled and waited for in any possible combination. As such they can be used as an inter-thread communication mechanism. Besides explicitly accessible, event group flags can also be manipulated by timers expiring and messages being send to threads allowing for a thread to wait for multiple events in a single call.

Function Description avixEventGroup_Change Clear, set or toggle one or more flags of an event group avixEventGroup_ChangeFromISR Clear, set or toggle one or more flags of an event group directly from an Interrupt Service Routine avixEventGroup_Create Create a new event group object avixEventGroup_Get Get an event group id of an existing event group and wait if not yet existent avixEventGroup_Wait Wait for a specified number of event group flags to be or become set avixEventGroupThread_Change Clear, set or toggle one or more flags of a thread implicit event group avixEventGroupThread_ChangeFromISR Clear, set or toggle one or more flags of a thread implicit event group directly from an Interrupt Service Routine avixEventGroupThreadWait Wait for a specified number of thread implicit event group flags to become set

Timer Functions

AVIX supports timers as separate global kernel objects. For basic timing functionality every thread contains an implicit timer with limited functionality. This thread implicit timer functionality is accessible through function avixThread_Sleep.

Function Description avixTimer_ConnectEventGroup Connect an event group to a timer for clearing, setting or toggling flags when the timer expires. avixTimer_ConnectEventGroupThread Connect a thread implicit event group to a timer for clearing, setting or toggling flags when the timer expires. avixTimer_Create Create a new timer object avixTimer_DisconnectEventGroup Disconnect an event group from the timer, whether the event group connected is a regular event group or a thread event group or none avixTimer_Get Get an id of an existing timer object and wait if not yet existent avixTimer_Set Set the properties of a timer avixTimer_Start Start a timer avixTimer_StartFromISR Start a timer from an ISR avixTimer_Stop Stop a timer avixTimer_StopFromISR Stop a timer from an ISR avixTimer_Wait Wait for a timer to expire

Message Functions

Messages are used to communicate small blocks of information between threads. AVIX implements a client-server model meaning that a message is sent to a specific thread.

Function Description avixMsg_Allocate Allocate a new message block the message pool avixMsg_AllocateFromISR Allocate a new message block from the message pool directly from an Interrupt Service Routine avixMsg_Reuse Prepare a message for reuse after having received id avixMsg_Free Return a message to the message pool avixMsg_GetType Get the type of a received message avixMsg_GetSender Get the thread id of the sending thread avixMsg_PutChar<FromISR> Put a single byte value in the message body avixMsg_PutShort<FromISR> Put a double byte value in the message body avixMsg_PutInt<FromISR> Put a value in the message body whose size depends on the type of controller used (16-bit or 32-bit) avixMsg_PutLong<FromISR> Put a long (4 byte) value in the message body avixMsg_PutPtr<FromISR> Put a pointer in the message body avixMsg_PutKernelObjectId<FromISR> Put a kernel object id of any desired type in the message body avixMsg_PutIndirect<FromISR> Put free format data in the mesage body. avixMsg_GetChar Get a single byte value from the message body avixMsg_GetShort Get a double byte value from the message body avixMsg_GetInt Get a value from the message body whose size depends on the type of controller (16-bit or 32-bit) avixMsg_GetLong Get a long (4 byte) value from the message body avixMsg_GetPtr Get a pointer from the message body avixMsg_GetKernelObjectId Get a kernel object id of any desired type from the message body avixMsg_GetIndirect Get free format data from the message body avixMsgQThread_Send Send a message to a designated thread avixMsgQThread_SendFromISR Send a message to a designated thread directly from an Interrupt Service Routine avixMsgQThread_Reply Send the message back to its originator avixMsgQThread_Receive Wait for a message to be received avixMsgQThread_ConnectEventGroup Specify flags in an event group to be set when messages are present avixMsgQThread_ConnectEventGroupThread Specify flags in a thread event group to be set when messages are present avixMsgQThread_DisconnectEventGroup Disconnect an event group from the message queue, whether the event group connected is a regular event group or a thread event group or none.

Pipe Functions

Basically intended to be used between threads and interrupt service routines (ISR’s), AVIX offers pipes. Pipes are First-In-First-Out data buffers. AVIX pipes offer a mechanism that aids in controlling the device related to the Interrupt Service Routine on one side of the pipe. Besides being used between a thread and an ISR, pipes can also be used between two threads where the exchange of data forms the basis for synchronizing the threads.

Function Description avixPipe_Create Create a new pipe object avixPipe_Get Get an id of an existing pipe object and wait if not yet existent avixPipe_Read Read data from a pipe and wait if not sufficient data available avixPipe_Write Write data to a pipe and wait if not enough empty space in the pipe to write avixPipe_ReadFromISR Read data from a pipe from an Interrupt Service Routine avixPipe_WriteFromISR Write data to a pipe from an interrupt service routine avixPipe_StopDeviceFromISR Stop a device from an interrupt service routine

Memory Pool Functions

Memory pool functions allow for creation of memory pools with fixed size memory blocks. Memory blocks can be allocated from and returned to the pool. While allocated, memory blocks can be used to hold user specified data for whatever purpose needed.

Function Description avixMemPool_Create Create a new memory pool object avixMemPool_Get Get an id of an existing memory pool object and wait if not yet existent avixMemPool_Allocate Allocate a memory block from a memory pool avixMemPool_Free Return a memory block to its pool avixMemPool_AllocateFromISR Allocate a memory block from a pool from within an Interrupt Service Routine avixMemPool_FreeFromISR Return a memory block to its pool from within an Interrupt Service Routine avixMemPool_GetSizeBlock Return the size in bytes of a memory block. avixMemPool_GetSizeBlockFromISR Return the size in bytes of a memory block.

Power Management Functions

Power Management functions are used to exploit the energy saving capabilities of the micro controller AVIX is working on.