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 * SPDX-License-Identifier: BSD-3-Clause
19 * -- End of Copyright Notice --
26 #include "IxOsalTypes.h"
29 #include "IxOsalAssert.h"
32 * Config header gives users option to choose IO MEM
33 * and buffer management modules
36 #include "IxOsalConfig.h"
39 * Symbol file needed by some OS.
41 #include "IxOsalUtilitySymbols.h"
43 /* OS-specific header */
48 * @defgroup IxOsal Operating System Abstraction Layer (IxOsal) API
50 * @brief This service provides a thin layer of OS dependency services.
52 * This file contains the API to the functions which are some what OS dependant and would
53 * require porting to a particular OS.
54 * A primary focus of the component development is to make them as OS independent as possible.
55 * All other components should abstract their OS dependency to this module.
57 * -# Data types, constants, defines
59 * - bind interrupts to handlers
60 * - unbind interrupts from handlers
61 * - disables all interrupts
62 * - enables all interrupts
63 * - selectively disables interrupts
64 * - enables an interrupt level
65 * - disables an interrupt level
69 * - copies memory zones
70 * - fills a memory zone
71 * - allocates cache-safe memory
72 * - frees cache-safe memory
73 * - physical to virtual address translation
74 * - virtual to physical address translation
75 * - cache to memory flush
76 * - cache line invalidate
78 * - creates a new thread
79 * - starts a newly created thread
80 * - kills an existing thread
81 * - exits a running thread
82 * - sets the priority of an existing thread
83 * - suspends thread execution
84 * - resumes thread execution
86 * - creates a message queue
87 * - deletes a message queue
88 * - sends a message to a message queue
89 * - receives a message from a message queue
90 * -# Thread Synchronisation
91 * - initializes a mutex
94 * - non-blocking attempt to lock a mutex
95 * - destroys a mutex object
96 * - initializes a fast mutex
97 * - non-blocking attempt to lock a fast mutex
98 * - unlocks a fast mutex
99 * - destroys a fast mutex object
100 * - initializes a semaphore
101 * - posts to (increments) a semaphore
102 * - waits on (decrements) a semaphore
103 * - non-blocking wait on semaphore
104 * - gets semaphore value
105 * - destroys a semaphore object
106 * - yields execution of current thread
108 * - yielding sleep for a number of milliseconds
109 * - busy sleep for a number of microseconds
110 * - value of the timestamp counter
111 * - resolution of the timestamp counter
112 * - system clock rate, in ticks
113 * - current system time
114 * - converts ixOsalTimeVal into ticks
115 * - converts ticks into ixOsalTimeVal
116 * - converts ixOsalTimeVal to milliseconds
117 * - converts milliseconds to IxOsalTimeval
118 * - "equal" comparison for IxOsalTimeval
119 * - "less than" comparison for IxOsalTimeval
120 * - "greater than" comparison for IxOsalTimeval
121 * - "add" operator for IxOsalTimeval
122 * - "subtract" operator for IxOsalTimeval
124 * - sets the current logging verbosity level
125 * - interrupt-safe logging function
127 * - schedules a repeating timer
128 * - schedules a single-shot timer
129 * - cancels a running timer
130 * - displays all the running timers
131 * -# Optional Modules
132 * - Buffer management module
133 * - I/O memory and endianess support module
143 /* ========================== Interrupts ================================
150 * @brief Binds an interrupt handler to an interrupt level
152 * @param irqLevel (in) - interrupt level
153 * @param irqHandler (in) - interrupt handler
154 * @param parameter (in) - custom parameter to be passed to the
157 * Binds an interrupt handler to an interrupt level. The operation will
158 * fail if the wrong level is selected, if the handler is NULL, or if the
159 * interrupt is already bound. This functions binds the specified C
160 * routine to an interrupt level. When called, the "parameter" value will
161 * be passed to the routine.
166 * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
168 PUBLIC IX_STATUS ixOsalIrqBind (UINT32 irqLevel,
169 IxOsalVoidFnVoidPtr irqHandler,
175 * @brief Unbinds an interrupt handler from an interrupt level
177 * @param irqLevel (in) - interrupt level
179 * Unbinds the selected interrupt level from any previously registered
185 * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
187 PUBLIC IX_STATUS ixOsalIrqUnbind (UINT32 irqLevel);
193 * @brief Disables all interrupts
197 * Disables all the interrupts and prevents tasks scheduling
202 * @return interrupt enable status prior to locking
204 PUBLIC UINT32 ixOsalIrqLock (void);
209 * @brief Enables all interrupts
211 * @param irqEnable (in) - interrupt enable status, prior to interrupt
214 * Enables the interrupts and task scheduling, cancelling the effect
220 * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
222 PUBLIC void ixOsalIrqUnlock (UINT32 irqEnable);
227 * @brief Selectively disables interrupts
229 * @param irqLevel - new interrupt level
231 * Disables the interrupts below the specified interrupt level
236 * @note Depending on the implementation this function can disable all
239 * @return previous interrupt level
241 PUBLIC UINT32 ixOsalIrqLevelSet (UINT32 irqLevel);
246 * @brief Enables an interrupt level
248 * @param irqLevel - interrupt level to enable
250 * Enables the specified interrupt level
257 PUBLIC void ixOsalIrqEnable (UINT32 irqLevel);
262 * @brief Disables an interrupt level
264 * @param irqLevel - interrupt level to disable
266 * Disables the specified interrupt level
273 PUBLIC void ixOsalIrqDisable (UINT32 irqLevel);
276 /* ============================= Memory =================================
283 * @brief Allocates memory
285 * @param size - memory size to allocate, in bytes
287 * Allocates a memory zone of a given size
292 * @return Pointer to the allocated zone or NULL if the allocation failed
294 PUBLIC void *ixOsalMemAlloc (UINT32 size);
299 * @brief Frees memory
301 * @param ptr - pointer to the memory zone
303 * Frees a previously allocated memory zone
310 PUBLIC void ixOsalMemFree (void *ptr);
315 * @brief Copies memory zones
317 * @param dest - destination memory zone
318 * @param src - source memory zone
319 * @param count - number of bytes to copy
321 * Copies count bytes from the source memory zone pointed by src into the
322 * memory zone pointed by dest.
327 * @return Pointer to the destination memory zone
329 PUBLIC void *ixOsalMemCopy (void *dest, void *src, UINT32 count);
334 * @brief Fills a memory zone
336 * @param ptr - pointer to the memory zone
337 * @param filler - byte to fill the memory zone with
338 * @param count - number of bytes to fill
340 * Fills a memory zone with a given constant byte
345 * @return Pointer to the memory zone
347 PUBLIC void *ixOsalMemSet (void *ptr, UINT8 filler, UINT32 count);
352 * @brief Allocates cache-safe memory
354 * @param size - size, in bytes, of the allocated zone
356 * Allocates a cache-safe memory zone of at least "size" bytes and returns
357 * the pointer to the memory zone. This memory zone, depending on the
358 * platform, is either uncached or aligned on a cache line boundary to make
359 * the CACHE_FLUSH and CACHE_INVALIDATE macros safe to use. The memory
360 * allocated with this function MUST be freed with ixOsalCacheDmaFree(),
361 * otherwise memory corruption can occur.
366 * @return Pointer to the memory zone or NULL if allocation failed
368 * @note It is important to note that cache coherence is maintained in
369 * software by using the IX_OSAL_CACHE_FLUSH and IX_OSAL_CACHE_INVALIDATE
370 * macros to maintain consistency between cache and external memory.
372 PUBLIC void *ixOsalCacheDmaMalloc (UINT32 size);
374 /* Macros for ixOsalCacheDmaMalloc*/
375 #define IX_OSAL_CACHE_DMA_MALLOC(size) ixOsalCacheDmaMalloc(size)
380 * @brief Frees cache-safe memory
382 * @param ptr - pointer to the memory zone
384 * Frees a memory zone previously allocated with ixOsalCacheDmaMalloc()
391 PUBLIC void ixOsalCacheDmaFree (void *ptr);
393 #define IX_OSAL_CACHE_DMA_FREE(ptr) ixOsalCacheDmaFree(ptr)
398 * @brief physical to virtual address translation
400 * @param physAddr - physical address
402 * Converts a physical address into its equivalent MMU-mapped virtual address
407 * @return Corresponding virtual address, as UINT32
409 #define IX_OSAL_MMU_PHYS_TO_VIRT(physAddr) \
410 IX_OSAL_OS_MMU_PHYS_TO_VIRT(physAddr)
416 * @brief virtual to physical address translation
418 * @param virtAddr - virtual address
420 * Converts a virtual address into its equivalent MMU-mapped physical address
425 * @return Corresponding physical address, as UINT32
427 #define IX_OSAL_MMU_VIRT_TO_PHYS(virtAddr) \
428 IX_OSAL_OS_MMU_VIRT_TO_PHYS(virtAddr)
435 * @brief cache to memory flush
437 * @param addr - memory address to flush from cache
438 * @param size - number of bytes to flush (rounded up to a cache line)
440 * Flushes the cached value of the memory zone pointed by "addr" into memory,
441 * rounding up to a cache line. Use before the zone is to be read by a
442 * processing unit which is not cache coherent with the main CPU.
449 #define IX_OSAL_CACHE_FLUSH(addr, size) IX_OSAL_OS_CACHE_FLUSH(addr, size)
456 * @brief cache line invalidate
458 * @param addr - memory address to invalidate in cache
459 * @param size - number of bytes to invalidate (rounded up to a cache line)
461 * Invalidates the cached value of the memory zone pointed by "addr",
462 * rounding up to a cache line. Use before reading the zone from the main
463 * CPU, if the zone has been updated by a processing unit which is not cache
464 * coherent with the main CPU.
471 #define IX_OSAL_CACHE_INVALIDATE(addr, size) IX_OSAL_OS_CACHE_INVALIDATE(addr, size)
474 /* ============================= Threads =================================
481 * @brief Creates a new thread
483 * @param thread - handle of the thread to be created
484 * @param threadAttr - pointer to a thread attribute object
485 * @param startRoutine - thread entry point
486 * @param arg - argument given to the thread
488 * Creates a thread given a thread handle and a thread attribute object. The
489 * same thread attribute object can be used to create separate threads. "NULL"
490 * can be specified as the attribute, in which case the default values will
491 * be used. The thread needs to be explicitly started using ixOsalThreadStart().
496 * @return - IX_SUCCESS/IX_FAIL
498 PUBLIC IX_STATUS ixOsalThreadCreate (IxOsalThread * thread,
499 IxOsalThreadAttr * threadAttr,
500 IxOsalVoidFnVoidPtr startRoutine,
506 * @brief Starts a newly created thread
508 * @param thread - handle of the thread to be started
510 * Starts a thread given its thread handle. This function is to be called
511 * only once, following the thread initialization.
516 * @return - IX_SUCCESS/IX_FAIL
518 PUBLIC IX_STATUS ixOsalThreadStart (IxOsalThread * thread);
523 * @brief Kills an existing thread
525 * @param thread - handle of the thread to be killed
527 * Kills a thread given its thread handle.
532 * @note It is not possible to kill threads in Linux kernel mode. This
533 * function will only send a SIGTERM signal, and it is the responsibility
534 * of the thread to check for the presence of this signal with
537 * @return - IX_SUCCESS/IX_FAIL
539 PUBLIC IX_STATUS ixOsalThreadKill (IxOsalThread * thread);
544 * @brief Exits a running thread
546 * Terminates the calling thread
551 * @return - This function never returns
553 PUBLIC void ixOsalThreadExit (void);
558 * @brief Sets the priority of an existing thread
560 * @param thread - handle of the thread
561 * @param priority - new priority, between 0 and 255 (0 being the highest)
563 * Sets the thread priority
568 * @return - IX_SUCCESS/IX_FAIL
570 PUBLIC IX_STATUS ixOsalThreadPrioritySet (IxOsalThread * thread,
576 * @brief Suspends thread execution
578 * @param thread - handle of the thread
580 * Suspends the thread execution
585 * @return - IX_SUCCESS/IX_FAIL
587 PUBLIC IX_STATUS ixOsalThreadSuspend (IxOsalThread * thread);
592 * @brief Resumes thread execution
594 * @param thread - handle of the thread
596 * Resumes the thread execution
601 * @return - IX_SUCCESS/IX_FAIL
603 PUBLIC IX_STATUS ixOsalThreadResume (IxOsalThread * thread);
606 /* ======================= Message Queues (IPC) ==========================
613 * @brief Creates a message queue
615 * @param queue - queue handle
616 * @param msgCount - maximum number of messages to hold in the queue
617 * @param msgLen - maximum length of each message, in bytes
619 * Creates a message queue of msgCount messages, each containing msgLen bytes
624 * @return - IX_SUCCESS/IX_FAIL
626 PUBLIC IX_STATUS ixOsalMessageQueueCreate (IxOsalMessageQueue * queue,
627 UINT32 msgCount, UINT32 msgLen);
632 * @brief Deletes a message queue
634 * @param queue - queue handle
636 * Deletes a message queue
641 * @return - IX_SUCCESS/IX_FAIL
643 PUBLIC IX_STATUS ixOsalMessageQueueDelete (IxOsalMessageQueue * queue);
648 * @brief Sends a message to a message queue
650 * @param queue - queue handle
651 * @param message - message to send
653 * Sends a message to the message queue. The message will be copied (at the
654 * configured size of the message) into the queue.
659 * @return - IX_SUCCESS/IX_FAIL
661 PUBLIC IX_STATUS ixOsalMessageQueueSend (IxOsalMessageQueue * queue,
667 * @brief Receives a message from a message queue
669 * @param queue - queue handle
670 * @param message - pointer to where the message should be copied to
672 * Retrieves the first message from the message queue
677 * @return - IX_SUCCESS/IX_FAIL
679 PUBLIC IX_STATUS ixOsalMessageQueueReceive (IxOsalMessageQueue * queue,
683 /* ======================= Thread Synchronisation ========================
690 * @brief initializes a mutex
692 * @param mutex - mutex handle
694 * Initializes a mutex object
699 * @return - IX_SUCCESS/IX_FAIL
701 PUBLIC IX_STATUS ixOsalMutexInit (IxOsalMutex * mutex);
706 * @brief locks a mutex
708 * @param mutex - mutex handle
709 * @param timeout - timeout in ms; IX_OSAL_WAIT_FOREVER (-1) to wait forever
710 * or IX_OSAL_WAIT_NONE to return immediately
712 * Locks a mutex object
717 * @return - IX_SUCCESS/IX_FAIL
719 PUBLIC IX_STATUS ixOsalMutexLock (IxOsalMutex * mutex, INT32 timeout);
724 * @brief Unlocks a mutex
726 * @param mutex - mutex handle
728 * Unlocks a mutex object
733 * @return - IX_SUCCESS/IX_FAIL
735 PUBLIC IX_STATUS ixOsalMutexUnlock (IxOsalMutex * mutex);
740 * @brief Non-blocking attempt to lock a mutex
742 * @param mutex - mutex handle
744 * Attempts to lock a mutex object, returning immediately with IX_SUCCESS if
745 * the lock was successful or IX_FAIL if the lock failed
750 * @return - IX_SUCCESS/IX_FAIL
752 PUBLIC IX_STATUS ixOsalMutexTryLock (IxOsalMutex * mutex);
757 * @brief Destroys a mutex object
759 * @param mutex - mutex handle
762 * Destroys a mutex object; the caller should ensure that no thread is
763 * blocked on this mutex
768 * @return - IX_SUCCESS/IX_FAIL
770 PUBLIC IX_STATUS ixOsalMutexDestroy (IxOsalMutex * mutex);
775 * @brief Initializes a fast mutex
777 * @param mutex - fast mutex handle
779 * Initializes a fast mutex object
784 * @return - IX_SUCCESS/IX_FAIL
786 PUBLIC IX_STATUS ixOsalFastMutexInit (IxOsalFastMutex * mutex);
791 * @brief Non-blocking attempt to lock a fast mutex
793 * @param mutex - fast mutex handle
795 * Attempts to lock a fast mutex object, returning immediately with
796 * IX_SUCCESS if the lock was successful or IX_FAIL if the lock failed
801 * @return - IX_SUCCESS/IX_FAIL
803 PUBLIC IX_STATUS ixOsalFastMutexTryLock (IxOsalFastMutex * mutex);
808 * @brief Unlocks a fast mutex
810 * @param mutex - fast mutex handle
812 * Unlocks a fast mutex object
817 * @return - IX_SUCCESS/IX_FAIL
819 PUBLIC IX_STATUS ixOsalFastMutexUnlock (IxOsalFastMutex * mutex);
824 * @brief Destroys a fast mutex object
826 * @param mutex - fast mutex handle
828 * Destroys a fast mutex object
833 * @return - IX_SUCCESS/IX_FAIL
835 PUBLIC IX_STATUS ixOsalFastMutexDestroy (IxOsalFastMutex * mutex);
840 * @brief Initializes a semaphore
842 * @param semaphore - semaphore handle
843 * @param value - initial semaphore value
845 * Initializes a semaphore object
850 * @return - IX_SUCCESS/IX_FAIL
852 PUBLIC IX_STATUS ixOsalSemaphoreInit (IxOsalSemaphore * semaphore,
858 * @brief Posts to (increments) a semaphore
860 * @param semaphore - semaphore handle
862 * Increments a semaphore object
867 * @return - IX_SUCCESS/IX_FAIL
869 PUBLIC IX_STATUS ixOsalSemaphorePost (IxOsalSemaphore * semaphore);
874 * @brief Waits on (decrements) a semaphore
876 * @param semaphore - semaphore handle
877 * @param timeout - timeout, in ms; IX_OSAL_WAIT_FOREVER (-1) if the thread
878 * is to block indefinitely or IX_OSAL_WAIT_NONE (0) if the thread is to
879 * return immediately even if the call fails
881 * Decrements a semaphore, blocking if the semaphore is
882 * unavailable (value is 0).
887 * @return - IX_SUCCESS/IX_FAIL
889 PUBLIC IX_STATUS ixOsalSemaphoreWait (IxOsalSemaphore * semaphore,
895 * @brief Non-blocking wait on semaphore
897 * @param semaphore - semaphore handle
899 * Decrements a semaphore, not blocking the calling thread if the semaphore
905 * @return - IX_SUCCESS/IX_FAIL
907 PUBLIC IX_STATUS ixOsalSemaphoreTryWait (IxOsalSemaphore * semaphore);
912 * @brief Gets semaphore value
914 * @param semaphore - semaphore handle
915 * @param value - location to store the semaphore value
917 * Retrieves the current value of a semaphore object
922 * @return - IX_SUCCESS/IX_FAIL
924 PUBLIC IX_STATUS ixOsalSemaphoreGetValue (IxOsalSemaphore * semaphore,
930 * @brief Destroys a semaphore object
932 * @param semaphore - semaphore handle
934 * Destroys a semaphore object; the caller should ensure that no thread is
935 * blocked on this semaphore
940 * @return - IX_SUCCESS/IX_FAIL
942 PUBLIC IX_STATUS ixOsalSemaphoreDestroy (IxOsalSemaphore * semaphore);
947 * @brief Yields execution of current thread
949 * Yields the execution of the current thread
956 PUBLIC void ixOsalYield (void);
959 /* ========================== Time functions ===========================
966 * @brief Yielding sleep for a number of milliseconds
968 * @param milliseconds - number of milliseconds to sleep
970 * The calling thread will sleep for the specified number of milliseconds.
971 * This sleep is yielding, hence other tasks will be scheduled by the
972 * operating system during the sleep period. Calling this function with an
973 * argument of 0 will place the thread at the end of the current scheduling
981 PUBLIC void ixOsalSleep (UINT32 milliseconds);
986 * @brief Busy sleep for a number of microseconds
988 * @param microseconds - number of microseconds to sleep
990 * Sleeps for the specified number of microseconds, without explicitly
991 * yielding thread execution to the OS scheduler
998 PUBLIC void ixOsalBusySleep (UINT32 microseconds);
1005 * Retrieves the current timestamp
1007 * @li Reentrant: yes
1010 * @return - The current timestamp
1012 * @note The implementation of this function is platform-specific. Not
1013 * all the platforms provide a high-resolution timestamp counter.
1015 PUBLIC UINT32 ixOsalTimestampGet (void);
1020 * @brief Resolution of the timestamp counter
1022 * Retrieves the resolution (frequency) of the timestamp counter.
1024 * @li Reentrant: yes
1027 * @return - The resolution of the timestamp counter
1029 * @note The implementation of this function is platform-specific. Not all
1030 * the platforms provide a high-resolution timestamp counter.
1032 PUBLIC UINT32 ixOsalTimestampResolutionGet (void);
1037 * @brief System clock rate, in ticks
1039 * Retrieves the resolution (number of ticks per second) of the system clock
1044 * @return - The system clock rate
1046 * @note The implementation of this function is platform and OS-specific.
1047 * The system clock rate is not always available - e.g. Linux does not
1048 * provide this information in user mode
1050 PUBLIC UINT32 ixOsalSysClockRateGet (void);
1055 * @brief Current system time
1057 * @param tv - pointer to an IxOsalTimeval structure to store the current
1060 * Retrieves the current system time (real-time)
1067 * @note The implementation of this function is platform-specific. Not all
1068 * platforms have a real-time clock.
1070 PUBLIC void ixOsalTimeGet (IxOsalTimeval * tv);
1074 /* Internal function to convert timer val to ticks.
1075 * NOTE - This should not be called by the user.
1076 * Use the macro IX_OSAL_TIMEVAL_TO_TICKS
1077 * OS-independent, implemented in framework.
1079 PUBLIC UINT32 ixOsalTimevalToTicks (IxOsalTimeval tv);
1085 * @brief Converts ixOsalTimeVal into ticks
1087 * @param tv - an IxOsalTimeval structure
1089 * Converts an IxOsalTimeval structure into OS ticks
1091 * @li Reentrant: yes
1094 * @return - Corresponding number of ticks
1096 * Note: This function is OS-independent. Implemented by core.
1098 #define IX_OSAL_TIMEVAL_TO_TICKS(tv) ixOsalTimevalToTicks(tv)
1102 /* Internal function to convert ticks to timer val
1103 * NOTE - This should not be called by the user.
1104 * Use the macro IX_OSAL_TICKS_TO_TIMEVAL
1107 PUBLIC void ixOsalTicksToTimeval (UINT32 ticks, IxOsalTimeval * pTv);
1113 * @brief Converts ticks into ixOsalTimeVal
1115 * @param ticks - number of ticks
1116 * @param pTv - pointer to the destination structure
1118 * Converts the specified number of ticks into an IxOsalTimeval structure
1120 * @li Reentrant: yes
1123 * @return - Corresponding IxOsalTimeval structure
1124 * Note: This function is OS-independent. Implemented by core.
1126 #define IX_OSAL_TICKS_TO_TIMEVAL(ticks, pTv) \
1127 ixOsalTicksToTimeval(ticks, pTv)
1135 * @brief Converts ixOsalTimeVal to milliseconds
1137 * @param tv - IxOsalTimeval structure to convert
1139 * Converts an IxOsalTimeval structure into milliseconds
1141 * @li Reentrant: yes
1144 * @return - Corresponding number of milliseconds
1145 * Note: This function is OS-independent. Implemented by core.
1147 #define IX_OSAL_TIMEVAL_TO_MS(tv) ((tv.secs * 1000) + (tv.nsecs / 1000000))
1153 * @brief Converts milliseconds to IxOsalTimeval
1155 * @param milliseconds - number of milliseconds to convert
1156 * @param pTv - pointer to the destination structure
1158 * Converts a millisecond value into an IxOsalTimeval structure
1160 * @li Reentrant: yes
1163 * @return - Corresponding IxOsalTimeval structure
1164 * Note: This function is OS-independent. Implemented by core.
1166 #define IX_OSAL_MS_TO_TIMEVAL(milliseconds, pTv) \
1167 ((IxOsalTimeval *) pTv)->secs = milliseconds / 1000; \
1168 ((IxOsalTimeval *) pTv)->nsecs = (milliseconds % 1000) * 1000000
1174 * @brief "equal" comparison for IxOsalTimeval
1176 * @param tvA, tvB - IxOsalTimeval structures to compare
1178 * Compares two IxOsalTimeval structures for equality
1180 * @li Reentrant: yes
1183 * @return - true if the structures are equal
1185 * Note: This function is OS-independant
1187 #define IX_OSAL_TIME_EQ(tvA, tvB) \
1188 ((tvA).secs == (tvB).secs && (tvA).nsecs == (tvB).nsecs)
1194 * @brief "less than" comparison for IxOsalTimeval
1196 * @param tvA, tvB - IxOsalTimeval structures to compare
1198 * Compares two IxOsalTimeval structures to determine if the first one is
1199 * less than the second one
1201 * @li Reentrant: yes
1204 * @return - true if tvA < tvB
1206 * Note: This function is OS-independent. Implemented by core.
1208 #define IX_OSAL_TIME_LT(tvA,tvB) \
1209 ((tvA).secs < (tvB).secs || \
1210 ((tvA).secs == (tvB).secs && (tvA).nsecs < (tvB).nsecs))
1216 * @brief "greater than" comparison for IxOsalTimeval
1218 * @param tvA, tvB - IxOsalTimeval structures to compare
1220 * Compares two IxOsalTimeval structures to determine if the first one is
1221 * greater than the second one
1223 * @li Reentrant: yes
1226 * @return - true if tvA > tvB
1228 * Note: This function is OS-independent.
1230 #define IX_OSAL_TIME_GT(tvA, tvB) \
1231 ((tvA).secs > (tvB).secs || \
1232 ((tvA).secs == (tvB).secs && (tvA).nsecs > (tvB).nsecs))
1238 * @brief "add" operator for IxOsalTimeval
1240 * @param tvA, tvB - IxOsalTimeval structures to add
1242 * Adds the second IxOsalTimevalStruct to the first one (equivalent to
1245 * @li Reentrant: yes
1249 * Note: This function is OS-independent.
1251 #define IX_OSAL_TIME_ADD(tvA, tvB) \
1252 (tvA).secs += (tvB).secs; \
1253 (tvA).nsecs += (tvB).nsecs; \
1254 if ((tvA).nsecs >= IX_OSAL_BILLION) \
1257 (tvA).nsecs -= IX_OSAL_BILLION; }
1263 * @brief "subtract" operator for IxOsalTimeval
1265 * @param tvA, tvB - IxOsalTimeval structures to subtract
1267 * Subtracts the second IxOsalTimevalStruct from the first one (equivalent
1270 * @li Reentrant: yes
1274 * Note: This function is OS-independent. Implemented by core.
1276 #define IX_OSAL_TIME_SUB(tvA, tvB) \
1277 if ((tvA).nsecs >= (tvB).nsecs) \
1279 (tvA).secs -= (tvB).secs; \
1280 (tvA).nsecs -= (tvB).nsecs; \
1284 (tvA).secs -= ((tvB).secs + 1); \
1285 (tvA).nsecs += IX_OSAL_BILLION - (tvB).nsecs; \
1289 /* ============================= Logging ==============================
1296 * @brief Interrupt-safe logging function
1298 * @param level - identifier prefix for the message
1299 * @param device - output device
1300 * @param format - message format, in a printf format
1301 * @param ... - up to 6 arguments to be printed
1303 * IRQ-safe logging function, similar to printf. Accepts up to 6 arguments
1304 * to print (excluding the level, device and the format). This function will
1305 * actually display the message only if the level is lower than the current
1306 * verbosity level or if the IX_OSAL_LOG_USER level is used. An output device
1307 * must be specified (see IxOsalTypes.h).
1309 * @li Reentrant: yes
1312 * @return - Beside the exceptions documented in the note below, the returned
1313 * value is the number of printed characters, or -1 if the parameters are
1314 * incorrect (NULL format, unknown output device)
1316 * @note The exceptions to the return value are:
1317 * VxWorks: The return value is 32 if the specified level is 1 and 64
1318 * if the specified level is greater than 1 and less or equal than 9.
1319 * WinCE: If compiled for EBOOT then the return value is always 0.
1321 * @note The given print format should take into account the specified
1322 * output device. IX_OSAL_STDOUT supports all the usual print formats,
1323 * however a custom hex display specified by IX_OSAL_HEX would support
1324 * only a fixed number of hexadecimal digits.
1326 PUBLIC INT32 ixOsalLog (IxOsalLogLevel level,
1327 IxOsalLogDevice device,
1330 int arg2, int arg3, int arg4, int arg5, int arg6);
1335 * @brief sets the current logging verbosity level
1337 * @param level - new log verbosity level
1339 * Sets the log verbosity level. The default value is IX_OSAL_LOG_ERROR.
1341 * @li Reentrant: yes
1344 * @return - Old log verbosity level
1346 PUBLIC UINT32 ixOsalLogLevelSet (UINT32 level);
1349 /* ============================= Logging ==============================
1356 * @brief Schedules a repeating timer
1358 * @param timer - handle of the timer object
1359 * @param period - timer trigger period, in milliseconds
1360 * @param priority - timer priority (0 being the highest)
1361 * @param callback - user callback to invoke when the timer triggers
1362 * @param param - custom parameter passed to the callback
1364 * Schedules a timer to be called every period milliseconds. The timer
1365 * will invoke the specified callback function possibly in interrupt
1366 * context, passing the given parameter. If several timers trigger at the
1367 * same time contention issues are dealt according to the specified timer
1373 * @return - IX_SUCCESS/IX_FAIL
1375 PUBLIC IX_STATUS ixOsalRepeatingTimerSchedule (IxOsalTimer * timer,
1378 IxOsalVoidFnVoidPtr callback,
1384 * @brief Schedules a single-shot timer
1386 * @param timer - handle of the timer object
1387 * @param period - timer trigger period, in milliseconds
1388 * @param priority - timer priority (0 being the highest)
1389 * @param callback - user callback to invoke when the timer triggers
1390 * @param param - custom parameter passed to the callback
1392 * Schedules a timer to be called after period milliseconds. The timer
1393 * will cease to function past its first trigger. The timer will invoke
1394 * the specified callback function, possibly in interrupt context, passing
1395 * the given parameter. If several timers trigger at the same time contention
1396 * issues are dealt according to the specified timer priorities.
1401 * @return - IX_SUCCESS/IX_FAIL
1404 ixOsalSingleShotTimerSchedule (IxOsalTimer * timer,
1407 IxOsalVoidFnVoidPtr callback, void *param);
1412 * @brief Cancels a running timer
1414 * @param timer - handle of the timer object
1416 * Cancels a single-shot or repeating timer.
1421 * @return - IX_SUCCESS/IX_FAIL
1423 PUBLIC IX_STATUS ixOsalTimerCancel (IxOsalTimer * timer);
1428 * @brief displays all the running timers
1430 * Displays a list with all the running timers and their parameters (handle,
1431 * period, type, priority, callback and user parameter)
1438 PUBLIC void ixOsalTimersShow (void);
1441 /* ============================= Version ==============================
1448 * @brief provides the name of the Operating System running
1450 * @param osName - Pointer to a NULL-terminated string of characters
1451 * that holds the name of the OS running.
1452 * This is both an input and an ouput parameter
1453 * @param maxSize - Input parameter that defines the maximum number of
1454 * bytes that can be stored in osName
1456 * Returns a string of characters that describe the Operating System name
1458 * @li Reentrant: yes
1461 * return - IX_SUCCESS for successful retrieval
1462 * - IX_FAIL if (osType == NULL | maxSize =< 0)
1464 PUBLIC IX_STATUS ixOsalOsNameGet (INT8* osName, INT32 maxSize);
1469 * @brief provides the version of the Operating System running
1471 * @param osVersion - Pointer to a NULL terminated string of characters
1472 * that holds the version of the OS running.
1473 * This is both an input and an ouput parameter
1474 * @param maxSize - Input parameter that defines the maximum number of
1475 * bytes that can be stored in osVersion
1477 * Returns a string of characters that describe the Operating System's version
1479 * @li Reentrant: yes
1482 * return - IX_SUCCESS for successful retrieval
1483 * - IX_FAIL if (osVersion == NULL | maxSize =< 0)
1485 PUBLIC IX_STATUS ixOsalOsVersionGet(INT8* osVersion, INT32 maxSize);
1493 #endif /* IxOsal_H */