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.
|
|
|
|
|
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.
|
|
|