4 * @brief Top include file for OSAL
8 * IXP400 SW Release version 2.0
10 * -- Copyright Notice --
13 * Copyright 2001-2005, Intel Corporation.
14 * All rights reserved.
17 * Redistribution and use in source and binary forms, with or without
18 * modification, are permitted provided that the following conditions
20 * 1. Redistributions of source code must retain the above copyright
21 * notice, this list of conditions and the following disclaimer.
22 * 2. Redistributions in binary form must reproduce the above copyright
23 * notice, this list of conditions and the following disclaimer in the
24 * documentation and/or other materials provided with the distribution.
25 * 3. Neither the name of the Intel Corporation nor the names of its contributors
26 * may be used to endorse or promote products derived from this software
27 * without specific prior written permission.
30 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
31 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
32 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
33 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
34 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
35 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
36 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
37 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
38 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
39 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
43 * -- End of Copyright Notice --
50 #include "IxOsalTypes.h"
53 #include "IxOsalAssert.h"
56 * Config header gives users option to choose IO MEM
57 * and buffer management modules
60 #include "IxOsalConfig.h"
63 * Symbol file needed by some OS.
65 #include "IxOsalUtilitySymbols.h"
67 /* OS-specific header */
72 * @defgroup IxOsal Operating System Abstraction Layer (IxOsal) API
74 * @brief This service provides a thin layer of OS dependency services.
76 * This file contains the API to the functions which are some what OS dependant and would
77 * require porting to a particular OS.
78 * A primary focus of the component development is to make them as OS independent as possible.
79 * All other components should abstract their OS dependency to this module.
81 * -# Data types, constants, defines
83 * - bind interrupts to handlers
84 * - unbind interrupts from handlers
85 * - disables all interrupts
86 * - enables all interrupts
87 * - selectively disables interrupts
88 * - enables an interrupt level
89 * - disables an interrupt level
93 * - copies memory zones
94 * - fills a memory zone
95 * - allocates cache-safe memory
96 * - frees cache-safe memory
97 * - physical to virtual address translation
98 * - virtual to physical address translation
99 * - cache to memory flush
100 * - cache line invalidate
102 * - creates a new thread
103 * - starts a newly created thread
104 * - kills an existing thread
105 * - exits a running thread
106 * - sets the priority of an existing thread
107 * - suspends thread execution
108 * - resumes thread execution
110 * - creates a message queue
111 * - deletes a message queue
112 * - sends a message to a message queue
113 * - receives a message from a message queue
114 * -# Thread Synchronisation
115 * - initializes a mutex
118 * - non-blocking attempt to lock a mutex
119 * - destroys a mutex object
120 * - initializes a fast mutex
121 * - non-blocking attempt to lock a fast mutex
122 * - unlocks a fast mutex
123 * - destroys a fast mutex object
124 * - initializes a semaphore
125 * - posts to (increments) a semaphore
126 * - waits on (decrements) a semaphore
127 * - non-blocking wait on semaphore
128 * - gets semaphore value
129 * - destroys a semaphore object
130 * - yields execution of current thread
132 * - yielding sleep for a number of milliseconds
133 * - busy sleep for a number of microseconds
134 * - value of the timestamp counter
135 * - resolution of the timestamp counter
136 * - system clock rate, in ticks
137 * - current system time
138 * - converts ixOsalTimeVal into ticks
139 * - converts ticks into ixOsalTimeVal
140 * - converts ixOsalTimeVal to milliseconds
141 * - converts milliseconds to IxOsalTimeval
142 * - "equal" comparison for IxOsalTimeval
143 * - "less than" comparison for IxOsalTimeval
144 * - "greater than" comparison for IxOsalTimeval
145 * - "add" operator for IxOsalTimeval
146 * - "subtract" operator for IxOsalTimeval
148 * - sets the current logging verbosity level
149 * - interrupt-safe logging function
151 * - schedules a repeating timer
152 * - schedules a single-shot timer
153 * - cancels a running timer
154 * - displays all the running timers
155 * -# Optional Modules
156 * - Buffer management module
157 * - I/O memory and endianess support module
167 /* ========================== Interrupts ================================
174 * @brief Binds an interrupt handler to an interrupt level
176 * @param irqLevel (in) - interrupt level
177 * @param irqHandler (in) - interrupt handler
178 * @param parameter (in) - custom parameter to be passed to the
181 * Binds an interrupt handler to an interrupt level. The operation will
182 * fail if the wrong level is selected, if the handler is NULL, or if the
183 * interrupt is already bound. This functions binds the specified C
184 * routine to an interrupt level. When called, the "parameter" value will
185 * be passed to the routine.
190 * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
192 PUBLIC IX_STATUS ixOsalIrqBind (UINT32 irqLevel,
193 IxOsalVoidFnVoidPtr irqHandler,
199 * @brief Unbinds an interrupt handler from an interrupt level
201 * @param irqLevel (in) - interrupt level
203 * Unbinds the selected interrupt level from any previously registered
209 * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
211 PUBLIC IX_STATUS ixOsalIrqUnbind (UINT32 irqLevel);
217 * @brief Disables all interrupts
221 * Disables all the interrupts and prevents tasks scheduling
226 * @return interrupt enable status prior to locking
228 PUBLIC UINT32 ixOsalIrqLock (void);
233 * @brief Enables all interrupts
235 * @param irqEnable (in) - interrupt enable status, prior to interrupt
238 * Enables the interrupts and task scheduling, cancelling the effect
244 * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
246 PUBLIC void ixOsalIrqUnlock (UINT32 irqEnable);
251 * @brief Selectively disables interrupts
253 * @param irqLevel - new interrupt level
255 * Disables the interrupts below the specified interrupt level
260 * @note Depending on the implementation this function can disable all
263 * @return previous interrupt level
265 PUBLIC UINT32 ixOsalIrqLevelSet (UINT32 irqLevel);
270 * @brief Enables an interrupt level
272 * @param irqLevel - interrupt level to enable
274 * Enables the specified interrupt level
281 PUBLIC void ixOsalIrqEnable (UINT32 irqLevel);
286 * @brief Disables an interrupt level
288 * @param irqLevel - interrupt level to disable
290 * Disables the specified interrupt level
297 PUBLIC void ixOsalIrqDisable (UINT32 irqLevel);
300 /* ============================= Memory =================================
307 * @brief Allocates memory
309 * @param size - memory size to allocate, in bytes
311 * Allocates a memory zone of a given size
316 * @return Pointer to the allocated zone or NULL if the allocation failed
318 PUBLIC void *ixOsalMemAlloc (UINT32 size);
323 * @brief Frees memory
325 * @param ptr - pointer to the memory zone
327 * Frees a previously allocated memory zone
334 PUBLIC void ixOsalMemFree (void *ptr);
339 * @brief Copies memory zones
341 * @param dest - destination memory zone
342 * @param src - source memory zone
343 * @param count - number of bytes to copy
345 * Copies count bytes from the source memory zone pointed by src into the
346 * memory zone pointed by dest.
351 * @return Pointer to the destination memory zone
353 PUBLIC void *ixOsalMemCopy (void *dest, void *src, UINT32 count);
358 * @brief Fills a memory zone
360 * @param ptr - pointer to the memory zone
361 * @param filler - byte to fill the memory zone with
362 * @param count - number of bytes to fill
364 * Fills a memory zone with a given constant byte
369 * @return Pointer to the memory zone
371 PUBLIC void *ixOsalMemSet (void *ptr, UINT8 filler, UINT32 count);
376 * @brief Allocates cache-safe memory
378 * @param size - size, in bytes, of the allocated zone
380 * Allocates a cache-safe memory zone of at least "size" bytes and returns
381 * the pointer to the memory zone. This memory zone, depending on the
382 * platform, is either uncached or aligned on a cache line boundary to make
383 * the CACHE_FLUSH and CACHE_INVALIDATE macros safe to use. The memory
384 * allocated with this function MUST be freed with ixOsalCacheDmaFree(),
385 * otherwise memory corruption can occur.
390 * @return Pointer to the memory zone or NULL if allocation failed
392 * @note It is important to note that cache coherence is maintained in
393 * software by using the IX_OSAL_CACHE_FLUSH and IX_OSAL_CACHE_INVALIDATE
394 * macros to maintain consistency between cache and external memory.
396 PUBLIC void *ixOsalCacheDmaMalloc (UINT32 size);
398 /* Macros for ixOsalCacheDmaMalloc*/
399 #define IX_OSAL_CACHE_DMA_MALLOC(size) ixOsalCacheDmaMalloc(size)
404 * @brief Frees cache-safe memory
406 * @param ptr - pointer to the memory zone
408 * Frees a memory zone previously allocated with ixOsalCacheDmaMalloc()
415 PUBLIC void ixOsalCacheDmaFree (void *ptr);
417 #define IX_OSAL_CACHE_DMA_FREE(ptr) ixOsalCacheDmaFree(ptr)
422 * @brief physical to virtual address translation
424 * @param physAddr - physical address
426 * Converts a physical address into its equivalent MMU-mapped virtual address
431 * @return Corresponding virtual address, as UINT32
433 #define IX_OSAL_MMU_PHYS_TO_VIRT(physAddr) \
434 IX_OSAL_OS_MMU_PHYS_TO_VIRT(physAddr)
440 * @brief virtual to physical address translation
442 * @param virtAddr - virtual address
444 * Converts a virtual address into its equivalent MMU-mapped physical address
449 * @return Corresponding physical address, as UINT32
451 #define IX_OSAL_MMU_VIRT_TO_PHYS(virtAddr) \
452 IX_OSAL_OS_MMU_VIRT_TO_PHYS(virtAddr)
459 * @brief cache to memory flush
461 * @param addr - memory address to flush from cache
462 * @param size - number of bytes to flush (rounded up to a cache line)
464 * Flushes the cached value of the memory zone pointed by "addr" into memory,
465 * rounding up to a cache line. Use before the zone is to be read by a
466 * processing unit which is not cache coherent with the main CPU.
473 #define IX_OSAL_CACHE_FLUSH(addr, size) IX_OSAL_OS_CACHE_FLUSH(addr, size)
480 * @brief cache line invalidate
482 * @param addr - memory address to invalidate in cache
483 * @param size - number of bytes to invalidate (rounded up to a cache line)
485 * Invalidates the cached value of the memory zone pointed by "addr",
486 * rounding up to a cache line. Use before reading the zone from the main
487 * CPU, if the zone has been updated by a processing unit which is not cache
488 * coherent with the main CPU.
495 #define IX_OSAL_CACHE_INVALIDATE(addr, size) IX_OSAL_OS_CACHE_INVALIDATE(addr, size)
498 /* ============================= Threads =================================
505 * @brief Creates a new thread
507 * @param thread - handle of the thread to be created
508 * @param threadAttr - pointer to a thread attribute object
509 * @param startRoutine - thread entry point
510 * @param arg - argument given to the thread
512 * Creates a thread given a thread handle and a thread attribute object. The
513 * same thread attribute object can be used to create separate threads. "NULL"
514 * can be specified as the attribute, in which case the default values will
515 * be used. The thread needs to be explicitly started using ixOsalThreadStart().
520 * @return - IX_SUCCESS/IX_FAIL
522 PUBLIC IX_STATUS ixOsalThreadCreate (IxOsalThread * thread,
523 IxOsalThreadAttr * threadAttr,
524 IxOsalVoidFnVoidPtr startRoutine,
530 * @brief Starts a newly created thread
532 * @param thread - handle of the thread to be started
534 * Starts a thread given its thread handle. This function is to be called
535 * only once, following the thread initialization.
540 * @return - IX_SUCCESS/IX_FAIL
542 PUBLIC IX_STATUS ixOsalThreadStart (IxOsalThread * thread);
547 * @brief Kills an existing thread
549 * @param thread - handle of the thread to be killed
551 * Kills a thread given its thread handle.
556 * @note It is not possible to kill threads in Linux kernel mode. This
557 * function will only send a SIGTERM signal, and it is the responsibility
558 * of the thread to check for the presence of this signal with
561 * @return - IX_SUCCESS/IX_FAIL
563 PUBLIC IX_STATUS ixOsalThreadKill (IxOsalThread * thread);
568 * @brief Exits a running thread
570 * Terminates the calling thread
575 * @return - This function never returns
577 PUBLIC void ixOsalThreadExit (void);
582 * @brief Sets the priority of an existing thread
584 * @param thread - handle of the thread
585 * @param priority - new priority, between 0 and 255 (0 being the highest)
587 * Sets the thread priority
592 * @return - IX_SUCCESS/IX_FAIL
594 PUBLIC IX_STATUS ixOsalThreadPrioritySet (IxOsalThread * thread,
600 * @brief Suspends thread execution
602 * @param thread - handle of the thread
604 * Suspends the thread execution
609 * @return - IX_SUCCESS/IX_FAIL
611 PUBLIC IX_STATUS ixOsalThreadSuspend (IxOsalThread * thread);
616 * @brief Resumes thread execution
618 * @param thread - handle of the thread
620 * Resumes the thread execution
625 * @return - IX_SUCCESS/IX_FAIL
627 PUBLIC IX_STATUS ixOsalThreadResume (IxOsalThread * thread);
630 /* ======================= Message Queues (IPC) ==========================
637 * @brief Creates a message queue
639 * @param queue - queue handle
640 * @param msgCount - maximum number of messages to hold in the queue
641 * @param msgLen - maximum length of each message, in bytes
643 * Creates a message queue of msgCount messages, each containing msgLen bytes
648 * @return - IX_SUCCESS/IX_FAIL
650 PUBLIC IX_STATUS ixOsalMessageQueueCreate (IxOsalMessageQueue * queue,
651 UINT32 msgCount, UINT32 msgLen);
656 * @brief Deletes a message queue
658 * @param queue - queue handle
660 * Deletes a message queue
665 * @return - IX_SUCCESS/IX_FAIL
667 PUBLIC IX_STATUS ixOsalMessageQueueDelete (IxOsalMessageQueue * queue);
672 * @brief Sends a message to a message queue
674 * @param queue - queue handle
675 * @param message - message to send
677 * Sends a message to the message queue. The message will be copied (at the
678 * configured size of the message) into the queue.
683 * @return - IX_SUCCESS/IX_FAIL
685 PUBLIC IX_STATUS ixOsalMessageQueueSend (IxOsalMessageQueue * queue,
691 * @brief Receives a message from a message queue
693 * @param queue - queue handle
694 * @param message - pointer to where the message should be copied to
696 * Retrieves the first message from the message queue
701 * @return - IX_SUCCESS/IX_FAIL
703 PUBLIC IX_STATUS ixOsalMessageQueueReceive (IxOsalMessageQueue * queue,
707 /* ======================= Thread Synchronisation ========================
714 * @brief initializes a mutex
716 * @param mutex - mutex handle
718 * Initializes a mutex object
723 * @return - IX_SUCCESS/IX_FAIL
725 PUBLIC IX_STATUS ixOsalMutexInit (IxOsalMutex * mutex);
730 * @brief locks a mutex
732 * @param mutex - mutex handle
733 * @param timeout - timeout in ms; IX_OSAL_WAIT_FOREVER (-1) to wait forever
734 * or IX_OSAL_WAIT_NONE to return immediately
736 * Locks a mutex object
741 * @return - IX_SUCCESS/IX_FAIL
743 PUBLIC IX_STATUS ixOsalMutexLock (IxOsalMutex * mutex, INT32 timeout);
748 * @brief Unlocks a mutex
750 * @param mutex - mutex handle
752 * Unlocks a mutex object
757 * @return - IX_SUCCESS/IX_FAIL
759 PUBLIC IX_STATUS ixOsalMutexUnlock (IxOsalMutex * mutex);
764 * @brief Non-blocking attempt to lock a mutex
766 * @param mutex - mutex handle
768 * Attempts to lock a mutex object, returning immediately with IX_SUCCESS if
769 * the lock was successful or IX_FAIL if the lock failed
774 * @return - IX_SUCCESS/IX_FAIL
776 PUBLIC IX_STATUS ixOsalMutexTryLock (IxOsalMutex * mutex);
781 * @brief Destroys a mutex object
783 * @param mutex - mutex handle
786 * Destroys a mutex object; the caller should ensure that no thread is
787 * blocked on this mutex
792 * @return - IX_SUCCESS/IX_FAIL
794 PUBLIC IX_STATUS ixOsalMutexDestroy (IxOsalMutex * mutex);
799 * @brief Initializes a fast mutex
801 * @param mutex - fast mutex handle
803 * Initializes a fast mutex object
808 * @return - IX_SUCCESS/IX_FAIL
810 PUBLIC IX_STATUS ixOsalFastMutexInit (IxOsalFastMutex * mutex);
815 * @brief Non-blocking attempt to lock a fast mutex
817 * @param mutex - fast mutex handle
819 * Attempts to lock a fast mutex object, returning immediately with
820 * IX_SUCCESS if the lock was successful or IX_FAIL if the lock failed
825 * @return - IX_SUCCESS/IX_FAIL
827 PUBLIC IX_STATUS ixOsalFastMutexTryLock (IxOsalFastMutex * mutex);
832 * @brief Unlocks a fast mutex
834 * @param mutex - fast mutex handle
836 * Unlocks a fast mutex object
841 * @return - IX_SUCCESS/IX_FAIL
843 PUBLIC IX_STATUS ixOsalFastMutexUnlock (IxOsalFastMutex * mutex);
848 * @brief Destroys a fast mutex object
850 * @param mutex - fast mutex handle
852 * Destroys a fast mutex object
857 * @return - IX_SUCCESS/IX_FAIL
859 PUBLIC IX_STATUS ixOsalFastMutexDestroy (IxOsalFastMutex * mutex);
864 * @brief Initializes a semaphore
866 * @param semaphore - semaphore handle
867 * @param value - initial semaphore value
869 * Initializes a semaphore object
874 * @return - IX_SUCCESS/IX_FAIL
876 PUBLIC IX_STATUS ixOsalSemaphoreInit (IxOsalSemaphore * semaphore,
882 * @brief Posts to (increments) a semaphore
884 * @param semaphore - semaphore handle
886 * Increments a semaphore object
891 * @return - IX_SUCCESS/IX_FAIL
893 PUBLIC IX_STATUS ixOsalSemaphorePost (IxOsalSemaphore * semaphore);
898 * @brief Waits on (decrements) a semaphore
900 * @param semaphore - semaphore handle
901 * @param timeout - timeout, in ms; IX_OSAL_WAIT_FOREVER (-1) if the thread
902 * is to block indefinitely or IX_OSAL_WAIT_NONE (0) if the thread is to
903 * return immediately even if the call fails
905 * Decrements a semaphore, blocking if the semaphore is
906 * unavailable (value is 0).
911 * @return - IX_SUCCESS/IX_FAIL
913 PUBLIC IX_STATUS ixOsalSemaphoreWait (IxOsalSemaphore * semaphore,
919 * @brief Non-blocking wait on semaphore
921 * @param semaphore - semaphore handle
923 * Decrements a semaphore, not blocking the calling thread if the semaphore
929 * @return - IX_SUCCESS/IX_FAIL
931 PUBLIC IX_STATUS ixOsalSemaphoreTryWait (IxOsalSemaphore * semaphore);
936 * @brief Gets semaphore value
938 * @param semaphore - semaphore handle
939 * @param value - location to store the semaphore value
941 * Retrieves the current value of a semaphore object
946 * @return - IX_SUCCESS/IX_FAIL
948 PUBLIC IX_STATUS ixOsalSemaphoreGetValue (IxOsalSemaphore * semaphore,
954 * @brief Destroys a semaphore object
956 * @param semaphore - semaphore handle
958 * Destroys a semaphore object; the caller should ensure that no thread is
959 * blocked on this semaphore
964 * @return - IX_SUCCESS/IX_FAIL
966 PUBLIC IX_STATUS ixOsalSemaphoreDestroy (IxOsalSemaphore * semaphore);
971 * @brief Yields execution of current thread
973 * Yields the execution of the current thread
980 PUBLIC void ixOsalYield (void);
983 /* ========================== Time functions ===========================
990 * @brief Yielding sleep for a number of milliseconds
992 * @param milliseconds - number of milliseconds to sleep
994 * The calling thread will sleep for the specified number of milliseconds.
995 * This sleep is yielding, hence other tasks will be scheduled by the
996 * operating system during the sleep period. Calling this function with an
997 * argument of 0 will place the thread at the end of the current scheduling
1005 PUBLIC void ixOsalSleep (UINT32 milliseconds);
1010 * @brief Busy sleep for a number of microseconds
1012 * @param microseconds - number of microseconds to sleep
1014 * Sleeps for the specified number of microseconds, without explicitly
1015 * yielding thread execution to the OS scheduler
1017 * @li Reentrant: yes
1022 PUBLIC void ixOsalBusySleep (UINT32 microseconds);
1029 * Retrieves the current timestamp
1031 * @li Reentrant: yes
1034 * @return - The current timestamp
1036 * @note The implementation of this function is platform-specific. Not
1037 * all the platforms provide a high-resolution timestamp counter.
1039 PUBLIC UINT32 ixOsalTimestampGet (void);
1044 * @brief Resolution of the timestamp counter
1046 * Retrieves the resolution (frequency) of the timestamp counter.
1048 * @li Reentrant: yes
1051 * @return - The resolution of the timestamp counter
1053 * @note The implementation of this function is platform-specific. Not all
1054 * the platforms provide a high-resolution timestamp counter.
1056 PUBLIC UINT32 ixOsalTimestampResolutionGet (void);
1061 * @brief System clock rate, in ticks
1063 * Retrieves the resolution (number of ticks per second) of the system clock
1068 * @return - The system clock rate
1070 * @note The implementation of this function is platform and OS-specific.
1071 * The system clock rate is not always available - e.g. Linux does not
1072 * provide this information in user mode
1074 PUBLIC UINT32 ixOsalSysClockRateGet (void);
1079 * @brief Current system time
1081 * @param tv - pointer to an IxOsalTimeval structure to store the current
1084 * Retrieves the current system time (real-time)
1091 * @note The implementation of this function is platform-specific. Not all
1092 * platforms have a real-time clock.
1094 PUBLIC void ixOsalTimeGet (IxOsalTimeval * tv);
1098 /* Internal function to convert timer val to ticks.
1099 * NOTE - This should not be called by the user.
1100 * Use the macro IX_OSAL_TIMEVAL_TO_TICKS
1101 * OS-independent, implemented in framework.
1103 PUBLIC UINT32 ixOsalTimevalToTicks (IxOsalTimeval tv);
1109 * @brief Converts ixOsalTimeVal into ticks
1111 * @param tv - an IxOsalTimeval structure
1113 * Converts an IxOsalTimeval structure into OS ticks
1115 * @li Reentrant: yes
1118 * @return - Corresponding number of ticks
1120 * Note: This function is OS-independent. Implemented by core.
1122 #define IX_OSAL_TIMEVAL_TO_TICKS(tv) ixOsalTimevalToTicks(tv)
1126 /* Internal function to convert ticks to timer val
1127 * NOTE - This should not be called by the user.
1128 * Use the macro IX_OSAL_TICKS_TO_TIMEVAL
1131 PUBLIC void ixOsalTicksToTimeval (UINT32 ticks, IxOsalTimeval * pTv);
1137 * @brief Converts ticks into ixOsalTimeVal
1139 * @param ticks - number of ticks
1140 * @param pTv - pointer to the destination structure
1142 * Converts the specified number of ticks into an IxOsalTimeval structure
1144 * @li Reentrant: yes
1147 * @return - Corresponding IxOsalTimeval structure
1148 * Note: This function is OS-independent. Implemented by core.
1150 #define IX_OSAL_TICKS_TO_TIMEVAL(ticks, pTv) \
1151 ixOsalTicksToTimeval(ticks, pTv)
1159 * @brief Converts ixOsalTimeVal to milliseconds
1161 * @param tv - IxOsalTimeval structure to convert
1163 * Converts an IxOsalTimeval structure into milliseconds
1165 * @li Reentrant: yes
1168 * @return - Corresponding number of milliseconds
1169 * Note: This function is OS-independent. Implemented by core.
1171 #define IX_OSAL_TIMEVAL_TO_MS(tv) ((tv.secs * 1000) + (tv.nsecs / 1000000))
1177 * @brief Converts milliseconds to IxOsalTimeval
1179 * @param milliseconds - number of milliseconds to convert
1180 * @param pTv - pointer to the destination structure
1182 * Converts a millisecond value into an IxOsalTimeval structure
1184 * @li Reentrant: yes
1187 * @return - Corresponding IxOsalTimeval structure
1188 * Note: This function is OS-independent. Implemented by core.
1190 #define IX_OSAL_MS_TO_TIMEVAL(milliseconds, pTv) \
1191 ((IxOsalTimeval *) pTv)->secs = milliseconds / 1000; \
1192 ((IxOsalTimeval *) pTv)->nsecs = (milliseconds % 1000) * 1000000
1198 * @brief "equal" comparison for IxOsalTimeval
1200 * @param tvA, tvB - IxOsalTimeval structures to compare
1202 * Compares two IxOsalTimeval structures for equality
1204 * @li Reentrant: yes
1207 * @return - TRUE if the structures are equal
1209 * Note: This function is OS-independant
1211 #define IX_OSAL_TIME_EQ(tvA, tvB) \
1212 ((tvA).secs == (tvB).secs && (tvA).nsecs == (tvB).nsecs)
1218 * @brief "less than" comparison for IxOsalTimeval
1220 * @param tvA, tvB - IxOsalTimeval structures to compare
1222 * Compares two IxOsalTimeval structures to determine if the first one is
1223 * less than the second one
1225 * @li Reentrant: yes
1228 * @return - TRUE if tvA < tvB
1230 * Note: This function is OS-independent. Implemented by core.
1232 #define IX_OSAL_TIME_LT(tvA,tvB) \
1233 ((tvA).secs < (tvB).secs || \
1234 ((tvA).secs == (tvB).secs && (tvA).nsecs < (tvB).nsecs))
1240 * @brief "greater than" comparison for IxOsalTimeval
1242 * @param tvA, tvB - IxOsalTimeval structures to compare
1244 * Compares two IxOsalTimeval structures to determine if the first one is
1245 * greater than the second one
1247 * @li Reentrant: yes
1250 * @return - TRUE if tvA > tvB
1252 * Note: This function is OS-independent.
1254 #define IX_OSAL_TIME_GT(tvA, tvB) \
1255 ((tvA).secs > (tvB).secs || \
1256 ((tvA).secs == (tvB).secs && (tvA).nsecs > (tvB).nsecs))
1262 * @brief "add" operator for IxOsalTimeval
1264 * @param tvA, tvB - IxOsalTimeval structures to add
1266 * Adds the second IxOsalTimevalStruct to the first one (equivalent to
1269 * @li Reentrant: yes
1273 * Note: This function is OS-independent.
1275 #define IX_OSAL_TIME_ADD(tvA, tvB) \
1276 (tvA).secs += (tvB).secs; \
1277 (tvA).nsecs += (tvB).nsecs; \
1278 if ((tvA).nsecs >= IX_OSAL_BILLION) \
1281 (tvA).nsecs -= IX_OSAL_BILLION; }
1287 * @brief "subtract" operator for IxOsalTimeval
1289 * @param tvA, tvB - IxOsalTimeval structures to subtract
1291 * Subtracts the second IxOsalTimevalStruct from the first one (equivalent
1294 * @li Reentrant: yes
1298 * Note: This function is OS-independent. Implemented by core.
1300 #define IX_OSAL_TIME_SUB(tvA, tvB) \
1301 if ((tvA).nsecs >= (tvB).nsecs) \
1303 (tvA).secs -= (tvB).secs; \
1304 (tvA).nsecs -= (tvB).nsecs; \
1308 (tvA).secs -= ((tvB).secs + 1); \
1309 (tvA).nsecs += IX_OSAL_BILLION - (tvB).nsecs; \
1313 /* ============================= Logging ==============================
1320 * @brief Interrupt-safe logging function
1322 * @param level - identifier prefix for the message
1323 * @param device - output device
1324 * @param format - message format, in a printf format
1325 * @param ... - up to 6 arguments to be printed
1327 * IRQ-safe logging function, similar to printf. Accepts up to 6 arguments
1328 * to print (excluding the level, device and the format). This function will
1329 * actually display the message only if the level is lower than the current
1330 * verbosity level or if the IX_OSAL_LOG_USER level is used. An output device
1331 * must be specified (see IxOsalTypes.h).
1333 * @li Reentrant: yes
1336 * @return - Beside the exceptions documented in the note below, the returned
1337 * value is the number of printed characters, or -1 if the parameters are
1338 * incorrect (NULL format, unknown output device)
1340 * @note The exceptions to the return value are:
1341 * VxWorks: The return value is 32 if the specified level is 1 and 64
1342 * if the specified level is greater than 1 and less or equal than 9.
1343 * WinCE: If compiled for EBOOT then the return value is always 0.
1345 * @note The given print format should take into account the specified
1346 * output device. IX_OSAL_STDOUT supports all the usual print formats,
1347 * however a custom hex display specified by IX_OSAL_HEX would support
1348 * only a fixed number of hexadecimal digits.
1350 PUBLIC INT32 ixOsalLog (IxOsalLogLevel level,
1351 IxOsalLogDevice device,
1354 int arg2, int arg3, int arg4, int arg5, int arg6);
1359 * @brief sets the current logging verbosity level
1361 * @param level - new log verbosity level
1363 * Sets the log verbosity level. The default value is IX_OSAL_LOG_ERROR.
1365 * @li Reentrant: yes
1368 * @return - Old log verbosity level
1370 PUBLIC UINT32 ixOsalLogLevelSet (UINT32 level);
1373 /* ============================= Logging ==============================
1380 * @brief Schedules a repeating timer
1382 * @param timer - handle of the timer object
1383 * @param period - timer trigger period, in milliseconds
1384 * @param priority - timer priority (0 being the highest)
1385 * @param callback - user callback to invoke when the timer triggers
1386 * @param param - custom parameter passed to the callback
1388 * Schedules a timer to be called every period milliseconds. The timer
1389 * will invoke the specified callback function possibly in interrupt
1390 * context, passing the given parameter. If several timers trigger at the
1391 * same time contention issues are dealt according to the specified timer
1397 * @return - IX_SUCCESS/IX_FAIL
1399 PUBLIC IX_STATUS ixOsalRepeatingTimerSchedule (IxOsalTimer * timer,
1402 IxOsalVoidFnVoidPtr callback,
1408 * @brief Schedules a single-shot timer
1410 * @param timer - handle of the timer object
1411 * @param period - timer trigger period, in milliseconds
1412 * @param priority - timer priority (0 being the highest)
1413 * @param callback - user callback to invoke when the timer triggers
1414 * @param param - custom parameter passed to the callback
1416 * Schedules a timer to be called after period milliseconds. The timer
1417 * will cease to function past its first trigger. The timer will invoke
1418 * the specified callback function, possibly in interrupt context, passing
1419 * the given parameter. If several timers trigger at the same time contention
1420 * issues are dealt according to the specified timer priorities.
1425 * @return - IX_SUCCESS/IX_FAIL
1428 ixOsalSingleShotTimerSchedule (IxOsalTimer * timer,
1431 IxOsalVoidFnVoidPtr callback, void *param);
1436 * @brief Cancels a running timer
1438 * @param timer - handle of the timer object
1440 * Cancels a single-shot or repeating timer.
1445 * @return - IX_SUCCESS/IX_FAIL
1447 PUBLIC IX_STATUS ixOsalTimerCancel (IxOsalTimer * timer);
1452 * @brief displays all the running timers
1454 * Displays a list with all the running timers and their parameters (handle,
1455 * period, type, priority, callback and user parameter)
1462 PUBLIC void ixOsalTimersShow (void);
1465 /* ============================= Version ==============================
1472 * @brief provides the name of the Operating System running
1474 * @param osName - Pointer to a NULL-terminated string of characters
1475 * that holds the name of the OS running.
1476 * This is both an input and an ouput parameter
1477 * @param maxSize - Input parameter that defines the maximum number of
1478 * bytes that can be stored in osName
1480 * Returns a string of characters that describe the Operating System name
1482 * @li Reentrant: yes
1485 * return - IX_SUCCESS for successful retrieval
1486 * - IX_FAIL if (osType == NULL | maxSize =< 0)
1488 PUBLIC IX_STATUS ixOsalOsNameGet (INT8* osName, INT32 maxSize);
1493 * @brief provides the version of the Operating System running
1495 * @param osVersion - Pointer to a NULL terminated string of characters
1496 * that holds the version of the OS running.
1497 * This is both an input and an ouput parameter
1498 * @param maxSize - Input parameter that defines the maximum number of
1499 * bytes that can be stored in osVersion
1501 * Returns a string of characters that describe the Operating System's version
1503 * @li Reentrant: yes
1506 * return - IX_SUCCESS for successful retrieval
1507 * - IX_FAIL if (osVersion == NULL | maxSize =< 0)
1509 PUBLIC IX_STATUS ixOsalOsVersionGet(INT8* osVersion, INT32 maxSize);
1517 #endif /* IxOsal_H */