Home

The AVIX Application Programming Interface (API) is consistent, type safe and does not depend on direct data manipulation.

The AVIX API goes a step further than many competing product. It is entirely function call based. AVIX does not require manipulation of complex data structures as many competing products do. The API implements a strict naming schema so the name of each function is self-explaining. The API is also type safe to a level not seen in any C implementation. Type safety does not depend on any compiler setting and can not be switched off. A programming error based on incorrect type usage is caught by the compiler, period. This largely helps finding programming errors in the earliest possible stage and makes the AVIX processing faster since the runtime does not need to check what the compiler is guaranteed to have checked.

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.

 

Function

Description

avixExch_ConnectCallbackEventGroup

Connect a callback to an Exchange receiving an Event Group Id as one of the parameters

avixExch_ConnectCallbackPipe

Connect a callback to an Exchange receiving a Pipe Id as one of the parameters

avixExch_ConnectCallbackThread

Connect a callback to an Exchange receiving a Thread Id as one of the parameters

avixExch_ConnectEventGroup

Connect an Event Group to an Exchange in order to set flags when Exchange is written

avixExch_ConnectMsgQThread

Connect a Thread to an Exchange in order to send a message to its queue when Exchange is written

avixExch_ConnectPipe

Connect a pipe to an Exchange in order to write data to the pipe when Exchange is written

avixExch_Create

Create a new Exchange object

avixExch_DisableActiveConnection

Disable the connection of the current active callback so it is no longer activated when Exchange is written

avixExch_DisableAllConnections

Disable all connections, disabled connections are not activated when the Exchange is written

avixExch_DisableConnection

Disable a connection, a disabled connection is not activated when the Exchange is written

avixExch_EnableAllConnections

Enable all connections, enabled connections are activated when the Exchange is written

avixExch_EnableConnection

Enable a connection, an enabled connection is activated when the Exchange is written

avixExch_Get

Get an Exchange Id of an existing Exchange and wait if not yet existent

avixExch_GetConnectionExch

Get the Exchange id belonging to a specific connection id

avixExch_GetConnectionMode

Get the mode of a connection. A connection either has an enabled or disabled mode

avixExch_GetLastWriteThread

Get id of thread that executed the last write operation to the Exchange

avixExch_GetSize

Get the size in bytes of the Exchange data section

avixExch_Lock

Lock an Exchange to allow direct access to its data section, preventing to be preempted by other threads

avixExch_Read

Read the content of an Exchange data section by making a copy to a caller provided buffer

avixExch_Write

Write the content of an Exchange data section by copying a caller provide buffer

avixExch_Unlock

Finish a direct access sequence initiated by avixExch_Lock

avixExch_UnlockAndNotify

Finish a direct access sequence initiated by avixExch_Lock and activate all Exchange connections

 

 

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.

 

Function

Description

avixPower_GetMode

Get the current set mode used by AVIX to decrease energy consumption when the Idle thread becomes active.

avixPower_GetModeFromISR

Get the current set mode used by AVIX to decrease energy consumption when the idle thread becomes active.

avixPower_SetCallback

Register a callback function to be called by AVIX when it is about to activate the currently selected power mode.

avixPower_SetMode

Set the mode that will be used by AVIX to decrease energy consumption when the idle thread becomes active.

avixPower_SetModeFromISR

Set the mode that will be used by AVIX to decrease energy consumption when the idle thread becomes active.

 

 

Diagnostic Functions

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

 

Function

Description

avixError_SetHandler

Set a user supplied central error handler, overriding the AVIX supplied handler.

avixError_Throw

Call the central error handler with a user supplied error code.

AVIX-RT © 2006-2015, All Rights Reserved

Legal Disclaimer

Privacy Policy