/** * @file IxOsal.h * * @brief Top include file for OSAL * * * @par * IXP400 SW Release version 2.0 * * -- Copyright Notice -- * * @par * Copyright 2001-2005, Intel Corporation. * All rights reserved. * * @par * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. Neither the name of the Intel Corporation nor the names of its contributors * may be used to endorse or promote products derived from this software * without specific prior written permission. * * @par * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * * @par * -- End of Copyright Notice -- */ #ifndef IxOsal_H #define IxOsal_H /* Basic types */ #include "IxOsalTypes.h" /* Include assert */ #include "IxOsalAssert.h" /* * Config header gives users option to choose IO MEM * and buffer management modules */ #include "IxOsalConfig.h" /* * Symbol file needed by some OS. */ #include "IxOsalUtilitySymbols.h" /* OS-specific header */ #include "IxOsalOs.h" /** * @defgroup IxOsal Operating System Abstraction Layer (IxOsal) API * * @brief This service provides a thin layer of OS dependency services. * * This file contains the API to the functions which are some what OS dependant and would * require porting to a particular OS. * A primary focus of the component development is to make them as OS independent as possible. * All other components should abstract their OS dependency to this module. * Services overview * -# Data types, constants, defines * -# Interrupts * - bind interrupts to handlers * - unbind interrupts from handlers * - disables all interrupts * - enables all interrupts * - selectively disables interrupts * - enables an interrupt level * - disables an interrupt level * -# Memory * - allocates memory * - frees memory * - copies memory zones * - fills a memory zone * - allocates cache-safe memory * - frees cache-safe memory * - physical to virtual address translation * - virtual to physical address translation * - cache to memory flush * - cache line invalidate * -# Threads * - creates a new thread * - starts a newly created thread * - kills an existing thread * - exits a running thread * - sets the priority of an existing thread * - suspends thread execution * - resumes thread execution * -# IPC * - creates a message queue * - deletes a message queue * - sends a message to a message queue * - receives a message from a message queue * -# Thread Synchronisation * - initializes a mutex * - locks a mutex * - unlocks a mutex * - non-blocking attempt to lock a mutex * - destroys a mutex object * - initializes a fast mutex * - non-blocking attempt to lock a fast mutex * - unlocks a fast mutex * - destroys a fast mutex object * - initializes a semaphore * - posts to (increments) a semaphore * - waits on (decrements) a semaphore * - non-blocking wait on semaphore * - gets semaphore value * - destroys a semaphore object * - yields execution of current thread * -# Time functions * - yielding sleep for a number of milliseconds * - busy sleep for a number of microseconds * - value of the timestamp counter * - resolution of the timestamp counter * - system clock rate, in ticks * - current system time * - converts ixOsalTimeVal into ticks * - converts ticks into ixOsalTimeVal * - converts ixOsalTimeVal to milliseconds * - converts milliseconds to IxOsalTimeval * - "equal" comparison for IxOsalTimeval * - "less than" comparison for IxOsalTimeval * - "greater than" comparison for IxOsalTimeval * - "add" operator for IxOsalTimeval * - "subtract" operator for IxOsalTimeval * -# Logging * - sets the current logging verbosity level * - interrupt-safe logging function * -# Timer services * - schedules a repeating timer * - schedules a single-shot timer * - cancels a running timer * - displays all the running timers * -# Optional Modules * - Buffer management module * - I/O memory and endianess support module * * @{ */ /* * Prototypes */ /* ========================== Interrupts ================================ * */ /** * @ingroup IxOsal * * @brief Binds an interrupt handler to an interrupt level * * @param irqLevel (in) - interrupt level * @param irqHandler (in) - interrupt handler * @param parameter (in) - custom parameter to be passed to the * interrupt handler * * Binds an interrupt handler to an interrupt level. The operation will * fail if the wrong level is selected, if the handler is NULL, or if the * interrupt is already bound. This functions binds the specified C * routine to an interrupt level. When called, the "parameter" value will * be passed to the routine. * * Reentrant: no * IRQ safe: no * * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise */ PUBLIC IX_STATUS ixOsalIrqBind (UINT32 irqLevel, IxOsalVoidFnVoidPtr irqHandler, void *parameter); /** * @ingroup IxOsal * * @brief Unbinds an interrupt handler from an interrupt level * * @param irqLevel (in) - interrupt level * * Unbinds the selected interrupt level from any previously registered * handler * * @li Reentrant: no * @li IRQ safe: no * * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise */ PUBLIC IX_STATUS ixOsalIrqUnbind (UINT32 irqLevel); /** * @ingroup IxOsal * * @brief Disables all interrupts * * @param - none * * Disables all the interrupts and prevents tasks scheduling * * @li Reentrant: no * @li IRQ safe: yes * * @return interrupt enable status prior to locking */ PUBLIC UINT32 ixOsalIrqLock (void); /** * @ingroup IxOsal * * @brief Enables all interrupts * * @param irqEnable (in) - interrupt enable status, prior to interrupt * locking * * Enables the interrupts and task scheduling, cancelling the effect * of ixOsalIrqLock() * * @li Reentrant: no * @li IRQ safe: yes * * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise */ PUBLIC void ixOsalIrqUnlock (UINT32 irqEnable); /** * @ingroup IxOsal * * @brief Selectively disables interrupts * * @param irqLevel ­ new interrupt level * * Disables the interrupts below the specified interrupt level * * @li Reentrant: no * @li IRQ safe: yes * * @note Depending on the implementation this function can disable all * the interrupts * * @return previous interrupt level */ PUBLIC UINT32 ixOsalIrqLevelSet (UINT32 irqLevel); /** * @ingroup IxOsal * * @brief Enables an interrupt level * * @param irqLevel ­ interrupt level to enable * * Enables the specified interrupt level * * @li Reentrant: no * @li IRQ safe: yes * * @return - none */ PUBLIC void ixOsalIrqEnable (UINT32 irqLevel); /** * @ingroup IxOsal * * @brief Disables an interrupt level * * @param irqLevel ­ interrupt level to disable * * Disables the specified interrupt level * * @li Reentrant: no * @li IRQ safe: yes * * @return - none */ PUBLIC void ixOsalIrqDisable (UINT32 irqLevel); /* ============================= Memory ================================= * */ /** * @ingroup IxOsal * * @brief Allocates memory * * @param size - memory size to allocate, in bytes * * Allocates a memory zone of a given size * * @li Reentrant: no * @li IRQ safe: no * * @return Pointer to the allocated zone or NULL if the allocation failed */ PUBLIC void *ixOsalMemAlloc (UINT32 size); /** * @ingroup IxOsal * * @brief Frees memory * * @param ptr - pointer to the memory zone * * Frees a previously allocated memory zone * * @li Reentrant: no * @li IRQ safe: no * * @return - none */ PUBLIC void ixOsalMemFree (void *ptr); /** * @ingroup IxOsal * * @brief Copies memory zones * * @param dest - destination memory zone * @param src - source memory zone * @param count - number of bytes to copy * * Copies count bytes from the source memory zone pointed by src into the * memory zone pointed by dest. * * @li Reentrant: no * @li IRQ safe: yes * * @return Pointer to the destination memory zone */ PUBLIC void *ixOsalMemCopy (void *dest, void *src, UINT32 count); /** * @ingroup IxOsal * * @brief Fills a memory zone * * @param ptr - pointer to the memory zone * @param filler - byte to fill the memory zone with * @param count - number of bytes to fill * * Fills a memory zone with a given constant byte * * @li Reentrant: no * @li IRQ safe: yes * * @return Pointer to the memory zone */ PUBLIC void *ixOsalMemSet (void *ptr, UINT8 filler, UINT32 count); /** * @ingroup IxOsal * * @brief Allocates cache-safe memory * * @param size - size, in bytes, of the allocated zone * * Allocates a cache-safe memory zone of at least "size" bytes and returns * the pointer to the memory zone. This memory zone, depending on the * platform, is either uncached or aligned on a cache line boundary to make * the CACHE_FLUSH and CACHE_INVALIDATE macros safe to use. The memory * allocated with this function MUST be freed with ixOsalCacheDmaFree(), * otherwise memory corruption can occur. * * @li Reentrant: no * @li IRQ safe: no * * @return Pointer to the memory zone or NULL if allocation failed * * @note It is important to note that cache coherence is maintained in * software by using the IX_OSAL_CACHE_FLUSH and IX_OSAL_CACHE_INVALIDATE * macros to maintain consistency between cache and external memory. */ PUBLIC void *ixOsalCacheDmaMalloc (UINT32 size); /* Macros for ixOsalCacheDmaMalloc*/ #define IX_OSAL_CACHE_DMA_MALLOC(size) ixOsalCacheDmaMalloc(size) /** * @ingroup IxOsal * * @brief Frees cache-safe memory * * @param ptr - pointer to the memory zone * * Frees a memory zone previously allocated with ixOsalCacheDmaMalloc() * * @li Reentrant: no * @li IRQ safe: no * * @return - none */ PUBLIC void ixOsalCacheDmaFree (void *ptr); #define IX_OSAL_CACHE_DMA_FREE(ptr) ixOsalCacheDmaFree(ptr) /** * @ingroup IxOsal * * @brief physical to virtual address translation * * @param physAddr - physical address * * Converts a physical address into its equivalent MMU-mapped virtual address * * @li Reentrant: no * @li IRQ safe: yes * * @return Corresponding virtual address, as UINT32 */ #define IX_OSAL_MMU_PHYS_TO_VIRT(physAddr) \ IX_OSAL_OS_MMU_PHYS_TO_VIRT(physAddr) /** * @ingroup IxOsal * * @brief virtual to physical address translation * * @param virtAddr - virtual address * * Converts a virtual address into its equivalent MMU-mapped physical address * * @li Reentrant: no * @li IRQ safe: yes * * @return Corresponding physical address, as UINT32 */ #define IX_OSAL_MMU_VIRT_TO_PHYS(virtAddr) \ IX_OSAL_OS_MMU_VIRT_TO_PHYS(virtAddr) /** * @ingroup IxOsal * * @brief cache to memory flush * * @param addr - memory address to flush from cache * @param size - number of bytes to flush (rounded up to a cache line) * * Flushes the cached value of the memory zone pointed by "addr" into memory, * rounding up to a cache line. Use before the zone is to be read by a * processing unit which is not cache coherent with the main CPU. * * @li Reentrant: no * @li IRQ safe: yes * * @return - none */ #define IX_OSAL_CACHE_FLUSH(addr, size) IX_OSAL_OS_CACHE_FLUSH(addr, size) /** * @ingroup IxOsal * * @brief cache line invalidate * * @param addr - memory address to invalidate in cache * @param size - number of bytes to invalidate (rounded up to a cache line) * * Invalidates the cached value of the memory zone pointed by "addr", * rounding up to a cache line. Use before reading the zone from the main * CPU, if the zone has been updated by a processing unit which is not cache * coherent with the main CPU. * * @li Reentrant: no * @li IRQ safe: yes * * @return - none */ #define IX_OSAL_CACHE_INVALIDATE(addr, size) IX_OSAL_OS_CACHE_INVALIDATE(addr, size) /* ============================= Threads ================================= * */ /** * @ingroup IxOsal * * @brief Creates a new thread * * @param thread - handle of the thread to be created * @param threadAttr - pointer to a thread attribute object * @param startRoutine - thread entry point * @param arg - argument given to the thread * * Creates a thread given a thread handle and a thread attribute object. The * same thread attribute object can be used to create separate threads. "NULL" * can be specified as the attribute, in which case the default values will * be used. The thread needs to be explicitly started using ixOsalThreadStart(). * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalThreadCreate (IxOsalThread * thread, IxOsalThreadAttr * threadAttr, IxOsalVoidFnVoidPtr startRoutine, void *arg); /** * @ingroup IxOsal * * @brief Starts a newly created thread * * @param thread - handle of the thread to be started * * Starts a thread given its thread handle. This function is to be called * only once, following the thread initialization. * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalThreadStart (IxOsalThread * thread); /** * @ingroup IxOsal * * @brief Kills an existing thread * * @param thread - handle of the thread to be killed * * Kills a thread given its thread handle. * * @li Reentrant: no * @li IRQ safe: no * * @note It is not possible to kill threads in Linux kernel mode. This * function will only send a SIGTERM signal, and it is the responsibility * of the thread to check for the presence of this signal with * signal_pending(). * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalThreadKill (IxOsalThread * thread); /** * @ingroup IxOsal * * @brief Exits a running thread * * Terminates the calling thread * * @li Reentrant: no * @li IRQ safe: no * * @return - This function never returns */ PUBLIC void ixOsalThreadExit (void); /** * @ingroup IxOsal * * @brief Sets the priority of an existing thread * * @param thread - handle of the thread * @param priority - new priority, between 0 and 255 (0 being the highest) * * Sets the thread priority * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalThreadPrioritySet (IxOsalThread * thread, UINT32 priority); /** * @ingroup IxOsal * * @brief Suspends thread execution * * @param thread - handle of the thread * * Suspends the thread execution * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalThreadSuspend (IxOsalThread * thread); /** * @ingroup IxOsal * * @brief Resumes thread execution * * @param thread - handle of the thread * * Resumes the thread execution * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalThreadResume (IxOsalThread * thread); /* ======================= Message Queues (IPC) ========================== * */ /** * @ingroup IxOsal * * @brief Creates a message queue * * @param queue - queue handle * @param msgCount - maximum number of messages to hold in the queue * @param msgLen - maximum length of each message, in bytes * * Creates a message queue of msgCount messages, each containing msgLen bytes * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalMessageQueueCreate (IxOsalMessageQueue * queue, UINT32 msgCount, UINT32 msgLen); /** * @ingroup IxOsal * * @brief Deletes a message queue * * @param queue - queue handle * * Deletes a message queue * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalMessageQueueDelete (IxOsalMessageQueue * queue); /** * @ingroup IxOsal * * @brief Sends a message to a message queue * * @param queue - queue handle * @param message - message to send * * Sends a message to the message queue. The message will be copied (at the * configured size of the message) into the queue. * * @li Reentrant: yes * @li IRQ safe: yes * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalMessageQueueSend (IxOsalMessageQueue * queue, UINT8 * message); /** * @ingroup IxOsal * * @brief Receives a message from a message queue * * @param queue - queue handle * @param message - pointer to where the message should be copied to * * Retrieves the first message from the message queue * * @li Reentrant: yes * @li IRQ safe: yes * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalMessageQueueReceive (IxOsalMessageQueue * queue, UINT8 * message); /* ======================= Thread Synchronisation ======================== * */ /** * @ingroup IxOsal * * @brief initializes a mutex * * @param mutex - mutex handle * * Initializes a mutex object * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalMutexInit (IxOsalMutex * mutex); /** * @ingroup IxOsal * * @brief locks a mutex * * @param mutex - mutex handle * @param timeout - timeout in ms; IX_OSAL_WAIT_FOREVER (-1) to wait forever * or IX_OSAL_WAIT_NONE to return immediately * * Locks a mutex object * * @li Reentrant: yes * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalMutexLock (IxOsalMutex * mutex, INT32 timeout); /** * @ingroup IxOsal * * @brief Unlocks a mutex * * @param mutex - mutex handle * * Unlocks a mutex object * * @li Reentrant: yes * @li IRQ safe: yes * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalMutexUnlock (IxOsalMutex * mutex); /** * @ingroup IxOsal * * @brief Non-blocking attempt to lock a mutex * * @param mutex - mutex handle * * Attempts to lock a mutex object, returning immediately with IX_SUCCESS if * the lock was successful or IX_FAIL if the lock failed * * @li Reentrant: yes * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalMutexTryLock (IxOsalMutex * mutex); /** * @ingroup IxOsal * * @brief Destroys a mutex object * * @param mutex - mutex handle * @param * * Destroys a mutex object; the caller should ensure that no thread is * blocked on this mutex * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalMutexDestroy (IxOsalMutex * mutex); /** * @ingroup IxOsal * * @brief Initializes a fast mutex * * @param mutex - fast mutex handle * * Initializes a fast mutex object * * @li Reentrant: yes * @li IRQ safe: yes * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalFastMutexInit (IxOsalFastMutex * mutex); /** * @ingroup IxOsal * * @brief Non-blocking attempt to lock a fast mutex * * @param mutex - fast mutex handle * * Attempts to lock a fast mutex object, returning immediately with * IX_SUCCESS if the lock was successful or IX_FAIL if the lock failed * * @li Reentrant: yes * @li IRQ safe: yes * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalFastMutexTryLock (IxOsalFastMutex * mutex); /** * @ingroup IxOsal * * @brief Unlocks a fast mutex * * @param mutex - fast mutex handle * * Unlocks a fast mutex object * * @li Reentrant: yes * @li IRQ safe: yes * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalFastMutexUnlock (IxOsalFastMutex * mutex); /** * @ingroup IxOsal * * @brief Destroys a fast mutex object * * @param mutex - fast mutex handle * * Destroys a fast mutex object * * @li Reentrant: yes * @li IRQ safe: yes * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalFastMutexDestroy (IxOsalFastMutex * mutex); /** * @ingroup IxOsal * * @brief Initializes a semaphore * * @param semaphore - semaphore handle * @param value - initial semaphore value * * Initializes a semaphore object * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalSemaphoreInit (IxOsalSemaphore * semaphore, UINT32 value); /** * @ingroup IxOsal * * @brief Posts to (increments) a semaphore * * @param semaphore - semaphore handle * * Increments a semaphore object * * @li Reentrant: no * @li IRQ safe: yes * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalSemaphorePost (IxOsalSemaphore * semaphore); /** * @ingroup IxOsal * * @brief Waits on (decrements) a semaphore * * @param semaphore - semaphore handle * @param timeout - timeout, in ms; IX_OSAL_WAIT_FOREVER (-1) if the thread * is to block indefinitely or IX_OSAL_WAIT_NONE (0) if the thread is to * return immediately even if the call fails * * Decrements a semaphore, blocking if the semaphore is * unavailable (value is 0). * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalSemaphoreWait (IxOsalSemaphore * semaphore, INT32 timeout); /** * @ingroup IxOsal * * @brief Non-blocking wait on semaphore * * @param semaphore - semaphore handle * * Decrements a semaphore, not blocking the calling thread if the semaphore * is unavailable * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalSemaphoreTryWait (IxOsalSemaphore * semaphore); /** * @ingroup IxOsal * * @brief Gets semaphore value * * @param semaphore - semaphore handle * @param value - location to store the semaphore value * * Retrieves the current value of a semaphore object * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalSemaphoreGetValue (IxOsalSemaphore * semaphore, UINT32 * value); /** * @ingroup IxOsal * * @brief Destroys a semaphore object * * @param semaphore - semaphore handle * * Destroys a semaphore object; the caller should ensure that no thread is * blocked on this semaphore * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalSemaphoreDestroy (IxOsalSemaphore * semaphore); /** * @ingroup IxOsal * * @brief Yields execution of current thread * * Yields the execution of the current thread * * @li Reentrant: no * @li IRQ safe: no * * @return - none */ PUBLIC void ixOsalYield (void); /* ========================== Time functions =========================== * */ /** * @ingroup IxOsal * * @brief Yielding sleep for a number of milliseconds * * @param milliseconds - number of milliseconds to sleep * * The calling thread will sleep for the specified number of milliseconds. * This sleep is yielding, hence other tasks will be scheduled by the * operating system during the sleep period. Calling this function with an * argument of 0 will place the thread at the end of the current scheduling * loop. * * @li Reentrant: no * @li IRQ safe: no * * @return - none */ PUBLIC void ixOsalSleep (UINT32 milliseconds); /** * @ingroup IxOsal * * @brief Busy sleep for a number of microseconds * * @param microseconds - number of microseconds to sleep * * Sleeps for the specified number of microseconds, without explicitly * yielding thread execution to the OS scheduler * * @li Reentrant: yes * @li IRQ safe: yes * * @return - none */ PUBLIC void ixOsalBusySleep (UINT32 microseconds); /** * @ingroup IxOsal * * @brief XXX * * Retrieves the current timestamp * * @li Reentrant: yes * @li IRQ safe: yes * * @return - The current timestamp * * @note The implementation of this function is platform-specific. Not * all the platforms provide a high-resolution timestamp counter. */ PUBLIC UINT32 ixOsalTimestampGet (void); /** * @ingroup IxOsal * * @brief Resolution of the timestamp counter * * Retrieves the resolution (frequency) of the timestamp counter. * * @li Reentrant: yes * @li IRQ safe: yes * * @return - The resolution of the timestamp counter * * @note The implementation of this function is platform-specific. Not all * the platforms provide a high-resolution timestamp counter. */ PUBLIC UINT32 ixOsalTimestampResolutionGet (void); /** * @ingroup IxOsal * * @brief System clock rate, in ticks * * Retrieves the resolution (number of ticks per second) of the system clock * * @li Reentrant: no * @li IRQ safe: no * * @return - The system clock rate * * @note The implementation of this function is platform and OS-specific. * The system clock rate is not always available - e.g. Linux does not * provide this information in user mode */ PUBLIC UINT32 ixOsalSysClockRateGet (void); /** * @ingroup IxOsal * * @brief Current system time * * @param tv - pointer to an IxOsalTimeval structure to store the current * time in * * Retrieves the current system time (real-time) * * @li Reentrant: no * @li IRQ safe: no * * @return - none * * @note The implementation of this function is platform-specific. Not all * platforms have a real-time clock. */ PUBLIC void ixOsalTimeGet (IxOsalTimeval * tv); /* Internal function to convert timer val to ticks. * NOTE - This should not be called by the user. * Use the macro IX_OSAL_TIMEVAL_TO_TICKS * OS-independent, implemented in framework. */ PUBLIC UINT32 ixOsalTimevalToTicks (IxOsalTimeval tv); /** * @ingroup IxOsal * * @brief Converts ixOsalTimeVal into ticks * * @param tv - an IxOsalTimeval structure * * Converts an IxOsalTimeval structure into OS ticks * * @li Reentrant: yes * @li IRQ safe: yes * * @return - Corresponding number of ticks * * Note: This function is OS-independent. Implemented by core. */ #define IX_OSAL_TIMEVAL_TO_TICKS(tv) ixOsalTimevalToTicks(tv) /* Internal function to convert ticks to timer val * NOTE - This should not be called by the user. * Use the macro IX_OSAL_TICKS_TO_TIMEVAL */ PUBLIC void ixOsalTicksToTimeval (UINT32 ticks, IxOsalTimeval * pTv); /** * @ingroup IxOsal * * @brief Converts ticks into ixOsalTimeVal * * @param ticks - number of ticks * @param pTv - pointer to the destination structure * * Converts the specified number of ticks into an IxOsalTimeval structure * * @li Reentrant: yes * @li IRQ safe: yes * * @return - Corresponding IxOsalTimeval structure * Note: This function is OS-independent. Implemented by core. */ #define IX_OSAL_TICKS_TO_TIMEVAL(ticks, pTv) \ ixOsalTicksToTimeval(ticks, pTv) /** * @ingroup IxOsal * * @brief Converts ixOsalTimeVal to milliseconds * * @param tv - IxOsalTimeval structure to convert * * Converts an IxOsalTimeval structure into milliseconds * * @li Reentrant: yes * @li IRQ safe: yes * * @return - Corresponding number of milliseconds * Note: This function is OS-independent. Implemented by core. */ #define IX_OSAL_TIMEVAL_TO_MS(tv) ((tv.secs * 1000) + (tv.nsecs / 1000000)) /** * @ingroup IxOsal * * @brief Converts milliseconds to IxOsalTimeval * * @param milliseconds - number of milliseconds to convert * @param pTv - pointer to the destination structure * * Converts a millisecond value into an IxOsalTimeval structure * * @li Reentrant: yes * @li IRQ safe: yes * * @return - Corresponding IxOsalTimeval structure * Note: This function is OS-independent. Implemented by core. */ #define IX_OSAL_MS_TO_TIMEVAL(milliseconds, pTv) \ ((IxOsalTimeval *) pTv)->secs = milliseconds / 1000; \ ((IxOsalTimeval *) pTv)->nsecs = (milliseconds % 1000) * 1000000 /** * @ingroup IxOsal * * @brief "equal" comparison for IxOsalTimeval * * @param tvA, tvB - IxOsalTimeval structures to compare * * Compares two IxOsalTimeval structures for equality * * @li Reentrant: yes * @li IRQ safe: yes * * @return - TRUE if the structures are equal * - FALSE otherwise * Note: This function is OS-independant */ #define IX_OSAL_TIME_EQ(tvA, tvB) \ ((tvA).secs == (tvB).secs && (tvA).nsecs == (tvB).nsecs) /** * @ingroup IxOsal * * @brief "less than" comparison for IxOsalTimeval * * @param tvA, tvB - IxOsalTimeval structures to compare * * Compares two IxOsalTimeval structures to determine if the first one is * less than the second one * * @li Reentrant: yes * @li IRQ safe: yes * * @return - TRUE if tvA < tvB * - FALSE otherwise * Note: This function is OS-independent. Implemented by core. */ #define IX_OSAL_TIME_LT(tvA,tvB) \ ((tvA).secs < (tvB).secs || \ ((tvA).secs == (tvB).secs && (tvA).nsecs < (tvB).nsecs)) /** * @ingroup IxOsal * * @brief "greater than" comparison for IxOsalTimeval * * @param tvA, tvB - IxOsalTimeval structures to compare * * Compares two IxOsalTimeval structures to determine if the first one is * greater than the second one * * @li Reentrant: yes * @li IRQ safe: yes * * @return - TRUE if tvA > tvB * - FALSE otherwise * Note: This function is OS-independent. */ #define IX_OSAL_TIME_GT(tvA, tvB) \ ((tvA).secs > (tvB).secs || \ ((tvA).secs == (tvB).secs && (tvA).nsecs > (tvB).nsecs)) /** * @ingroup IxOsal * * @brief "add" operator for IxOsalTimeval * * @param tvA, tvB - IxOsalTimeval structures to add * * Adds the second IxOsalTimevalStruct to the first one (equivalent to * tvA += tvB) * * @li Reentrant: yes * @li IRQ safe: yes * * @return - none * Note: This function is OS-independent. */ #define IX_OSAL_TIME_ADD(tvA, tvB) \ (tvA).secs += (tvB).secs; \ (tvA).nsecs += (tvB).nsecs; \ if ((tvA).nsecs >= IX_OSAL_BILLION) \ { \ (tvA).secs++; \ (tvA).nsecs -= IX_OSAL_BILLION; } /** * @ingroup IxOsal * * @brief "subtract" operator for IxOsalTimeval * * @param tvA, tvB - IxOsalTimeval structures to subtract * * Subtracts the second IxOsalTimevalStruct from the first one (equivalent * to tvA -= tvB) * * @li Reentrant: yes * @li IRQ safe: yes * * @return - none * Note: This function is OS-independent. Implemented by core. */ #define IX_OSAL_TIME_SUB(tvA, tvB) \ if ((tvA).nsecs >= (tvB).nsecs) \ { \ (tvA).secs -= (tvB).secs; \ (tvA).nsecs -= (tvB).nsecs; \ } \ else \ { \ (tvA).secs -= ((tvB).secs + 1); \ (tvA).nsecs += IX_OSAL_BILLION - (tvB).nsecs; \ } /* ============================= Logging ============================== * */ /** * @ingroup IxOsal * * @brief Interrupt-safe logging function * * @param level - identifier prefix for the message * @param device - output device * @param format - message format, in a printf format * @param ... - up to 6 arguments to be printed * * IRQ-safe logging function, similar to printf. Accepts up to 6 arguments * to print (excluding the level, device and the format). This function will * actually display the message only if the level is lower than the current * verbosity level or if the IX_OSAL_LOG_USER level is used. An output device * must be specified (see IxOsalTypes.h). * * @li Reentrant: yes * @li IRQ safe: yes * * @return - Beside the exceptions documented in the note below, the returned * value is the number of printed characters, or -1 if the parameters are * incorrect (NULL format, unknown output device) * * @note The exceptions to the return value are: * VxWorks: The return value is 32 if the specified level is 1 and 64 * if the specified level is greater than 1 and less or equal than 9. * WinCE: If compiled for EBOOT then the return value is always 0. * * @note The given print format should take into account the specified * output device. IX_OSAL_STDOUT supports all the usual print formats, * however a custom hex display specified by IX_OSAL_HEX would support * only a fixed number of hexadecimal digits. */ PUBLIC INT32 ixOsalLog (IxOsalLogLevel level, IxOsalLogDevice device, char *format, int arg1, int arg2, int arg3, int arg4, int arg5, int arg6); /** * @ingroup IxOsal * * @brief sets the current logging verbosity level * * @param level - new log verbosity level * * Sets the log verbosity level. The default value is IX_OSAL_LOG_ERROR. * * @li Reentrant: yes * @li IRQ safe: yes * * @return - Old log verbosity level */ PUBLIC UINT32 ixOsalLogLevelSet (UINT32 level); /* ============================= Logging ============================== * */ /** * @ingroup IxOsal * * @brief Schedules a repeating timer * * @param timer - handle of the timer object * @param period - timer trigger period, in milliseconds * @param priority - timer priority (0 being the highest) * @param callback - user callback to invoke when the timer triggers * @param param - custom parameter passed to the callback * * Schedules a timer to be called every period milliseconds. The timer * will invoke the specified callback function possibly in interrupt * context, passing the given parameter. If several timers trigger at the * same time contention issues are dealt according to the specified timer * priorities. * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalRepeatingTimerSchedule (IxOsalTimer * timer, UINT32 period, UINT32 priority, IxOsalVoidFnVoidPtr callback, void *param); /** * @ingroup IxOsal * * @brief Schedules a single-shot timer * * @param timer - handle of the timer object * @param period - timer trigger period, in milliseconds * @param priority - timer priority (0 being the highest) * @param callback - user callback to invoke when the timer triggers * @param param - custom parameter passed to the callback * * Schedules a timer to be called after period milliseconds. The timer * will cease to function past its first trigger. The timer will invoke * the specified callback function, possibly in interrupt context, passing * the given parameter. If several timers trigger at the same time contention * issues are dealt according to the specified timer priorities. * * @li Reentrant: no * @li IRQ safe: no * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalSingleShotTimerSchedule (IxOsalTimer * timer, UINT32 period, UINT32 priority, IxOsalVoidFnVoidPtr callback, void *param); /** * @ingroup IxOsal * * @brief Cancels a running timer * * @param timer - handle of the timer object * * Cancels a single-shot or repeating timer. * * @li Reentrant: no * @li IRQ safe: yes * * @return - IX_SUCCESS/IX_FAIL */ PUBLIC IX_STATUS ixOsalTimerCancel (IxOsalTimer * timer); /** * @ingroup IxOsal * * @brief displays all the running timers * * Displays a list with all the running timers and their parameters (handle, * period, type, priority, callback and user parameter) * * @li Reentrant: no * @li IRQ safe: no * * @return - none */ PUBLIC void ixOsalTimersShow (void); /* ============================= Version ============================== * */ /** * @ingroup IxOsal * * @brief provides the name of the Operating System running * * @param osName - Pointer to a NULL-terminated string of characters * that holds the name of the OS running. * This is both an input and an ouput parameter * @param maxSize - Input parameter that defines the maximum number of * bytes that can be stored in osName * * Returns a string of characters that describe the Operating System name * * @li Reentrant: yes * @li IRQ safe: yes * * return - IX_SUCCESS for successful retrieval * - IX_FAIL if (osType == NULL | maxSize =< 0) */ PUBLIC IX_STATUS ixOsalOsNameGet (INT8* osName, INT32 maxSize); /** * @ingroup IxOsal * * @brief provides the version of the Operating System running * * @param osVersion - Pointer to a NULL terminated string of characters * that holds the version of the OS running. * This is both an input and an ouput parameter * @param maxSize - Input parameter that defines the maximum number of * bytes that can be stored in osVersion * * Returns a string of characters that describe the Operating System's version * * @li Reentrant: yes * @li IRQ safe: yes * * return - IX_SUCCESS for successful retrieval * - IX_FAIL if (osVersion == NULL | maxSize =< 0) */ PUBLIC IX_STATUS ixOsalOsVersionGet(INT8* osVersion, INT32 maxSize); /** * @} IxOsal */ #endif /* IxOsal_H */