Application Programming Interface

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 avixTimer_StartFromISR See Timer API avixTimer_StopFromISR See Timer API avixPower_GetModeFromISR See Power Management API avixPower_SetModeFromISR See Power Management API

Exchange Services

The purpose of Exchange services is to offer a high level inter-thread communication mechanism supporting loose coupling, broadcasting and synchronization of threads operating at different speeds. Additionally, Exchange Services makes reuse of software components easier and facilitates extending an application by adding new functionality with the least possible or, most of the time, even no changes to existing code.

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_PulseTracePort Generate a pulse on the trace port assigned to this thread avixThread_Relinquish 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. Two types of event groups are offered. Global event groups and thread local event groups, bot offering the same functionality.

Function Description avixEventGroup_Change Clear, set or toggle one or more flags of an event group or a thread event group avixEventGroup_ChangeFromISR Clear, set or toggle one or more flags of an event group or a thread event group 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_GetEventFlags Poll an event group or a thread event group for the current flag status. avixEventGroup_Wait Wait a specified flags to be or become set in an event group or thread event group

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 or a thread event group to a timer to clear, set or toggle flags when the timer expires. avixTimer_Create Create a new timer object avixTimer_DisconnectEventGroup Disconnect an event group from the timer. avixTimer_Get Get an id of an existing timer object and wait if not yet existent avixTimer_GetRemainingTicks Get the number of ticks remaining before the timer will expire avixTimer_Resume Resume a (stopped) timer avixTimer_ResumeFromISR Resume a (stopped) timer from an Interrupt Service Routine avixTimer_Set Set the properties of a timer avixTimer_SetPeriod Change the period of a running cyclic timer with a seamless transition to the new period 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 or thread event group to be set when messages are present avixMsgQThread_DisconnectEventGroup Disconnect an event group from the message queue. avixMsgQThread_Flush Remove all messages from a thread message queue and return messages to message pool

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_ReadAsync Start an asynchronous read operation. avixPipe_Write Write data to a pipe and wait if not enough empty space in the pipe to write avixPipe_WriteAsync Start an asynchronous write operation. 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 avixPipe_FlushAndAbort Flush the pipe buffer and set all waiting requests finished avixPipe_GetStatusAsyncReq Poll for the status of an asynchronous read or write operation avixPipe_AbortAsyncReq Abort a pending asynchronous read or write operation avixPipe_SetHandlerTracePort Assign a trace port to the pipe handler used for ISR-thread interaction

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_CreateExt Create a new memory pool object in Extended Memory (When available!) 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.

Diagnostic Functions

The central error handling mechanism is supported by the following functions: