]>
Commit | Line | Data |
---|---|---|
ba94a1bb WD |
1 | /** |
2 | * @file IxOsal.h | |
3 | * | |
4 | * @brief Top include file for OSAL | |
5 | * | |
6 | * | |
7 | * @par | |
8 | * IXP400 SW Release version 2.0 | |
9 | * | |
10 | * -- Copyright Notice -- | |
11 | * | |
12 | * @par | |
13 | * Copyright 2001-2005, Intel Corporation. | |
14 | * All rights reserved. | |
15 | * | |
16 | * @par | |
17 | * Redistribution and use in source and binary forms, with or without | |
18 | * modification, are permitted provided that the following conditions | |
19 | * are met: | |
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. | |
28 | * | |
29 | * @par | |
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 | |
40 | * SUCH DAMAGE. | |
41 | * | |
42 | * @par | |
43 | * -- End of Copyright Notice -- | |
44 | */ | |
45 | ||
46 | #ifndef IxOsal_H | |
47 | #define IxOsal_H | |
48 | ||
49 | /* Basic types */ | |
50 | #include "IxOsalTypes.h" | |
51 | ||
52 | /* Include assert */ | |
53 | #include "IxOsalAssert.h" | |
54 | ||
55 | /* | |
56 | * Config header gives users option to choose IO MEM | |
57 | * and buffer management modules | |
58 | */ | |
59 | ||
60 | #include "IxOsalConfig.h" | |
61 | ||
62 | /* | |
63 | * Symbol file needed by some OS. | |
64 | */ | |
65 | #include "IxOsalUtilitySymbols.h" | |
66 | ||
67 | /* OS-specific header */ | |
68 | #include "IxOsalOs.h" | |
69 | ||
70 | ||
71 | /** | |
72 | * @defgroup IxOsal Operating System Abstraction Layer (IxOsal) API | |
73 | * | |
74 | * @brief This service provides a thin layer of OS dependency services. | |
75 | * | |
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. | |
80 | * Services overview | |
81 | * -# Data types, constants, defines | |
82 | * -# Interrupts | |
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 | |
90 | * -# Memory | |
91 | * - allocates memory | |
92 | * - frees memory | |
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 | |
101 | * -# Threads | |
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 | |
109 | * -# IPC | |
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 | |
116 | * - locks a mutex | |
117 | * - unlocks 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 | |
131 | * -# Time functions | |
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 | |
147 | * -# Logging | |
148 | * - sets the current logging verbosity level | |
149 | * - interrupt-safe logging function | |
150 | * -# Timer services | |
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 | |
158 | * | |
159 | * @{ | |
160 | */ | |
161 | ||
162 | ||
163 | /* | |
164 | * Prototypes | |
165 | */ | |
166 | ||
167 | /* ========================== Interrupts ================================ | |
168 | * | |
169 | */ | |
170 | ||
171 | /** | |
172 | * @ingroup IxOsal | |
173 | * | |
174 | * @brief Binds an interrupt handler to an interrupt level | |
175 | * | |
176 | * @param irqLevel (in) - interrupt level | |
177 | * @param irqHandler (in) - interrupt handler | |
178 | * @param parameter (in) - custom parameter to be passed to the | |
179 | * interrupt handler | |
180 | * | |
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. | |
186 | * | |
187 | * Reentrant: no | |
188 | * IRQ safe: no | |
189 | * | |
190 | * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise | |
191 | */ | |
192 | PUBLIC IX_STATUS ixOsalIrqBind (UINT32 irqLevel, | |
193 | IxOsalVoidFnVoidPtr irqHandler, | |
194 | void *parameter); | |
195 | ||
196 | /** | |
197 | * @ingroup IxOsal | |
198 | * | |
199 | * @brief Unbinds an interrupt handler from an interrupt level | |
200 | * | |
201 | * @param irqLevel (in) - interrupt level | |
202 | * | |
203 | * Unbinds the selected interrupt level from any previously registered | |
204 | * handler | |
205 | * | |
206 | * @li Reentrant: no | |
207 | * @li IRQ safe: no | |
208 | * | |
209 | * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise | |
210 | */ | |
211 | PUBLIC IX_STATUS ixOsalIrqUnbind (UINT32 irqLevel); | |
212 | ||
213 | ||
214 | /** | |
215 | * @ingroup IxOsal | |
216 | * | |
217 | * @brief Disables all interrupts | |
218 | * | |
219 | * @param - none | |
220 | * | |
221 | * Disables all the interrupts and prevents tasks scheduling | |
222 | * | |
223 | * @li Reentrant: no | |
224 | * @li IRQ safe: yes | |
225 | * | |
226 | * @return interrupt enable status prior to locking | |
227 | */ | |
228 | PUBLIC UINT32 ixOsalIrqLock (void); | |
229 | ||
230 | /** | |
231 | * @ingroup IxOsal | |
232 | * | |
233 | * @brief Enables all interrupts | |
234 | * | |
235 | * @param irqEnable (in) - interrupt enable status, prior to interrupt | |
236 | * locking | |
237 | * | |
238 | * Enables the interrupts and task scheduling, cancelling the effect | |
239 | * of ixOsalIrqLock() | |
240 | * | |
241 | * @li Reentrant: no | |
242 | * @li IRQ safe: yes | |
243 | * | |
244 | * @return IX_SUCCESS if the operation succeeded or IX_FAIL otherwise | |
245 | */ | |
246 | PUBLIC void ixOsalIrqUnlock (UINT32 irqEnable); | |
247 | ||
248 | /** | |
249 | * @ingroup IxOsal | |
250 | * | |
251 | * @brief Selectively disables interrupts | |
252 | * | |
fa82f871 | 253 | * @param irqLevel - new interrupt level |
ba94a1bb WD |
254 | * |
255 | * Disables the interrupts below the specified interrupt level | |
256 | * | |
257 | * @li Reentrant: no | |
258 | * @li IRQ safe: yes | |
259 | * | |
260 | * @note Depending on the implementation this function can disable all | |
261 | * the interrupts | |
262 | * | |
263 | * @return previous interrupt level | |
264 | */ | |
265 | PUBLIC UINT32 ixOsalIrqLevelSet (UINT32 irqLevel); | |
266 | ||
267 | /** | |
268 | * @ingroup IxOsal | |
269 | * | |
270 | * @brief Enables an interrupt level | |
271 | * | |
fa82f871 | 272 | * @param irqLevel - interrupt level to enable |
ba94a1bb WD |
273 | * |
274 | * Enables the specified interrupt level | |
275 | * | |
276 | * @li Reentrant: no | |
277 | * @li IRQ safe: yes | |
278 | * | |
279 | * @return - none | |
280 | */ | |
281 | PUBLIC void ixOsalIrqEnable (UINT32 irqLevel); | |
282 | ||
283 | /** | |
284 | * @ingroup IxOsal | |
285 | * | |
286 | * @brief Disables an interrupt level | |
287 | * | |
fa82f871 | 288 | * @param irqLevel - interrupt level to disable |
ba94a1bb WD |
289 | * |
290 | * Disables the specified interrupt level | |
291 | * | |
292 | * @li Reentrant: no | |
293 | * @li IRQ safe: yes | |
294 | * | |
295 | * @return - none | |
296 | */ | |
297 | PUBLIC void ixOsalIrqDisable (UINT32 irqLevel); | |
298 | ||
299 | ||
300 | /* ============================= Memory ================================= | |
301 | * | |
302 | */ | |
303 | ||
304 | /** | |
305 | * @ingroup IxOsal | |
306 | * | |
307 | * @brief Allocates memory | |
308 | * | |
309 | * @param size - memory size to allocate, in bytes | |
310 | * | |
311 | * Allocates a memory zone of a given size | |
312 | * | |
313 | * @li Reentrant: no | |
314 | * @li IRQ safe: no | |
315 | * | |
316 | * @return Pointer to the allocated zone or NULL if the allocation failed | |
317 | */ | |
318 | PUBLIC void *ixOsalMemAlloc (UINT32 size); | |
319 | ||
320 | /** | |
321 | * @ingroup IxOsal | |
322 | * | |
323 | * @brief Frees memory | |
324 | * | |
325 | * @param ptr - pointer to the memory zone | |
326 | * | |
327 | * Frees a previously allocated memory zone | |
328 | * | |
329 | * @li Reentrant: no | |
330 | * @li IRQ safe: no | |
331 | * | |
332 | * @return - none | |
333 | */ | |
334 | PUBLIC void ixOsalMemFree (void *ptr); | |
335 | ||
336 | /** | |
337 | * @ingroup IxOsal | |
338 | * | |
339 | * @brief Copies memory zones | |
340 | * | |
341 | * @param dest - destination memory zone | |
342 | * @param src - source memory zone | |
343 | * @param count - number of bytes to copy | |
344 | * | |
345 | * Copies count bytes from the source memory zone pointed by src into the | |
346 | * memory zone pointed by dest. | |
347 | * | |
348 | * @li Reentrant: no | |
349 | * @li IRQ safe: yes | |
350 | * | |
351 | * @return Pointer to the destination memory zone | |
352 | */ | |
353 | PUBLIC void *ixOsalMemCopy (void *dest, void *src, UINT32 count); | |
354 | ||
355 | /** | |
356 | * @ingroup IxOsal | |
357 | * | |
358 | * @brief Fills a memory zone | |
359 | * | |
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 | |
363 | * | |
364 | * Fills a memory zone with a given constant byte | |
365 | * | |
366 | * @li Reentrant: no | |
367 | * @li IRQ safe: yes | |
368 | * | |
369 | * @return Pointer to the memory zone | |
370 | */ | |
371 | PUBLIC void *ixOsalMemSet (void *ptr, UINT8 filler, UINT32 count); | |
372 | ||
373 | /** | |
374 | * @ingroup IxOsal | |
375 | * | |
376 | * @brief Allocates cache-safe memory | |
377 | * | |
378 | * @param size - size, in bytes, of the allocated zone | |
379 | * | |
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. | |
386 | * | |
387 | * @li Reentrant: no | |
388 | * @li IRQ safe: no | |
389 | * | |
390 | * @return Pointer to the memory zone or NULL if allocation failed | |
391 | * | |
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. | |
395 | */ | |
396 | PUBLIC void *ixOsalCacheDmaMalloc (UINT32 size); | |
397 | ||
398 | /* Macros for ixOsalCacheDmaMalloc*/ | |
399 | #define IX_OSAL_CACHE_DMA_MALLOC(size) ixOsalCacheDmaMalloc(size) | |
400 | ||
401 | /** | |
402 | * @ingroup IxOsal | |
403 | * | |
404 | * @brief Frees cache-safe memory | |
405 | * | |
406 | * @param ptr - pointer to the memory zone | |
407 | * | |
408 | * Frees a memory zone previously allocated with ixOsalCacheDmaMalloc() | |
409 | * | |
410 | * @li Reentrant: no | |
411 | * @li IRQ safe: no | |
412 | * | |
413 | * @return - none | |
414 | */ | |
415 | PUBLIC void ixOsalCacheDmaFree (void *ptr); | |
416 | ||
417 | #define IX_OSAL_CACHE_DMA_FREE(ptr) ixOsalCacheDmaFree(ptr) | |
418 | ||
419 | /** | |
420 | * @ingroup IxOsal | |
421 | * | |
422 | * @brief physical to virtual address translation | |
423 | * | |
424 | * @param physAddr - physical address | |
425 | * | |
426 | * Converts a physical address into its equivalent MMU-mapped virtual address | |
427 | * | |
428 | * @li Reentrant: no | |
429 | * @li IRQ safe: yes | |
430 | * | |
431 | * @return Corresponding virtual address, as UINT32 | |
432 | */ | |
433 | #define IX_OSAL_MMU_PHYS_TO_VIRT(physAddr) \ | |
434 | IX_OSAL_OS_MMU_PHYS_TO_VIRT(physAddr) | |
435 | ||
436 | ||
437 | /** | |
438 | * @ingroup IxOsal | |
439 | * | |
440 | * @brief virtual to physical address translation | |
441 | * | |
442 | * @param virtAddr - virtual address | |
443 | * | |
444 | * Converts a virtual address into its equivalent MMU-mapped physical address | |
445 | * | |
446 | * @li Reentrant: no | |
447 | * @li IRQ safe: yes | |
448 | * | |
449 | * @return Corresponding physical address, as UINT32 | |
450 | */ | |
451 | #define IX_OSAL_MMU_VIRT_TO_PHYS(virtAddr) \ | |
452 | IX_OSAL_OS_MMU_VIRT_TO_PHYS(virtAddr) | |
453 | ||
454 | ||
455 | ||
456 | /** | |
457 | * @ingroup IxOsal | |
458 | * | |
459 | * @brief cache to memory flush | |
460 | * | |
461 | * @param addr - memory address to flush from cache | |
462 | * @param size - number of bytes to flush (rounded up to a cache line) | |
463 | * | |
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. | |
467 | * | |
468 | * @li Reentrant: no | |
469 | * @li IRQ safe: yes | |
470 | * | |
471 | * @return - none | |
472 | */ | |
473 | #define IX_OSAL_CACHE_FLUSH(addr, size) IX_OSAL_OS_CACHE_FLUSH(addr, size) | |
474 | ||
475 | ||
476 | ||
477 | /** | |
478 | * @ingroup IxOsal | |
479 | * | |
480 | * @brief cache line invalidate | |
481 | * | |
482 | * @param addr - memory address to invalidate in cache | |
483 | * @param size - number of bytes to invalidate (rounded up to a cache line) | |
484 | * | |
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. | |
489 | * | |
490 | * @li Reentrant: no | |
491 | * @li IRQ safe: yes | |
492 | * | |
493 | * @return - none | |
494 | */ | |
495 | #define IX_OSAL_CACHE_INVALIDATE(addr, size) IX_OSAL_OS_CACHE_INVALIDATE(addr, size) | |
496 | ||
497 | ||
498 | /* ============================= Threads ================================= | |
499 | * | |
500 | */ | |
501 | ||
502 | /** | |
503 | * @ingroup IxOsal | |
504 | * | |
505 | * @brief Creates a new thread | |
506 | * | |
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 | |
511 | * | |
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(). | |
516 | * | |
517 | * @li Reentrant: no | |
518 | * @li IRQ safe: no | |
519 | * | |
520 | * @return - IX_SUCCESS/IX_FAIL | |
521 | */ | |
522 | PUBLIC IX_STATUS ixOsalThreadCreate (IxOsalThread * thread, | |
523 | IxOsalThreadAttr * threadAttr, | |
524 | IxOsalVoidFnVoidPtr startRoutine, | |
525 | void *arg); | |
526 | ||
527 | /** | |
528 | * @ingroup IxOsal | |
529 | * | |
530 | * @brief Starts a newly created thread | |
531 | * | |
532 | * @param thread - handle of the thread to be started | |
533 | * | |
534 | * Starts a thread given its thread handle. This function is to be called | |
535 | * only once, following the thread initialization. | |
536 | * | |
537 | * @li Reentrant: no | |
538 | * @li IRQ safe: no | |
539 | * | |
540 | * @return - IX_SUCCESS/IX_FAIL | |
541 | */ | |
542 | PUBLIC IX_STATUS ixOsalThreadStart (IxOsalThread * thread); | |
543 | ||
544 | /** | |
545 | * @ingroup IxOsal | |
546 | * | |
547 | * @brief Kills an existing thread | |
548 | * | |
549 | * @param thread - handle of the thread to be killed | |
550 | * | |
551 | * Kills a thread given its thread handle. | |
552 | * | |
553 | * @li Reentrant: no | |
554 | * @li IRQ safe: no | |
555 | * | |
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 | |
559 | * signal_pending(). | |
560 | * | |
561 | * @return - IX_SUCCESS/IX_FAIL | |
562 | */ | |
563 | PUBLIC IX_STATUS ixOsalThreadKill (IxOsalThread * thread); | |
564 | ||
565 | /** | |
566 | * @ingroup IxOsal | |
567 | * | |
568 | * @brief Exits a running thread | |
569 | * | |
570 | * Terminates the calling thread | |
571 | * | |
572 | * @li Reentrant: no | |
573 | * @li IRQ safe: no | |
574 | * | |
575 | * @return - This function never returns | |
576 | */ | |
577 | PUBLIC void ixOsalThreadExit (void); | |
578 | ||
579 | /** | |
580 | * @ingroup IxOsal | |
581 | * | |
582 | * @brief Sets the priority of an existing thread | |
583 | * | |
584 | * @param thread - handle of the thread | |
585 | * @param priority - new priority, between 0 and 255 (0 being the highest) | |
586 | * | |
587 | * Sets the thread priority | |
588 | * | |
589 | * @li Reentrant: no | |
590 | * @li IRQ safe: no | |
591 | * | |
592 | * @return - IX_SUCCESS/IX_FAIL | |
593 | */ | |
594 | PUBLIC IX_STATUS ixOsalThreadPrioritySet (IxOsalThread * thread, | |
595 | UINT32 priority); | |
596 | ||
597 | /** | |
598 | * @ingroup IxOsal | |
599 | * | |
600 | * @brief Suspends thread execution | |
601 | * | |
602 | * @param thread - handle of the thread | |
603 | * | |
604 | * Suspends the thread execution | |
605 | * | |
606 | * @li Reentrant: no | |
607 | * @li IRQ safe: no | |
608 | * | |
609 | * @return - IX_SUCCESS/IX_FAIL | |
610 | */ | |
611 | PUBLIC IX_STATUS ixOsalThreadSuspend (IxOsalThread * thread); | |
612 | ||
613 | /** | |
614 | * @ingroup IxOsal | |
615 | * | |
616 | * @brief Resumes thread execution | |
617 | * | |
618 | * @param thread - handle of the thread | |
619 | * | |
620 | * Resumes the thread execution | |
621 | * | |
622 | * @li Reentrant: no | |
623 | * @li IRQ safe: no | |
624 | * | |
625 | * @return - IX_SUCCESS/IX_FAIL | |
626 | */ | |
627 | PUBLIC IX_STATUS ixOsalThreadResume (IxOsalThread * thread); | |
628 | ||
629 | ||
630 | /* ======================= Message Queues (IPC) ========================== | |
631 | * | |
632 | */ | |
633 | ||
634 | /** | |
635 | * @ingroup IxOsal | |
636 | * | |
637 | * @brief Creates a message queue | |
638 | * | |
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 | |
642 | * | |
643 | * Creates a message queue of msgCount messages, each containing msgLen bytes | |
644 | * | |
645 | * @li Reentrant: no | |
646 | * @li IRQ safe: no | |
647 | * | |
648 | * @return - IX_SUCCESS/IX_FAIL | |
649 | */ | |
650 | PUBLIC IX_STATUS ixOsalMessageQueueCreate (IxOsalMessageQueue * queue, | |
651 | UINT32 msgCount, UINT32 msgLen); | |
652 | ||
653 | /** | |
654 | * @ingroup IxOsal | |
655 | * | |
656 | * @brief Deletes a message queue | |
657 | * | |
658 | * @param queue - queue handle | |
659 | * | |
660 | * Deletes a message queue | |
661 | * | |
662 | * @li Reentrant: no | |
663 | * @li IRQ safe: no | |
664 | * | |
665 | * @return - IX_SUCCESS/IX_FAIL | |
666 | */ | |
667 | PUBLIC IX_STATUS ixOsalMessageQueueDelete (IxOsalMessageQueue * queue); | |
668 | ||
669 | /** | |
670 | * @ingroup IxOsal | |
671 | * | |
672 | * @brief Sends a message to a message queue | |
673 | * | |
674 | * @param queue - queue handle | |
675 | * @param message - message to send | |
676 | * | |
677 | * Sends a message to the message queue. The message will be copied (at the | |
678 | * configured size of the message) into the queue. | |
679 | * | |
680 | * @li Reentrant: yes | |
681 | * @li IRQ safe: yes | |
682 | * | |
683 | * @return - IX_SUCCESS/IX_FAIL | |
684 | */ | |
685 | PUBLIC IX_STATUS ixOsalMessageQueueSend (IxOsalMessageQueue * queue, | |
686 | UINT8 * message); | |
687 | ||
688 | /** | |
689 | * @ingroup IxOsal | |
690 | * | |
691 | * @brief Receives a message from a message queue | |
692 | * | |
693 | * @param queue - queue handle | |
694 | * @param message - pointer to where the message should be copied to | |
695 | * | |
696 | * Retrieves the first message from the message queue | |
697 | * | |
698 | * @li Reentrant: yes | |
699 | * @li IRQ safe: yes | |
700 | * | |
701 | * @return - IX_SUCCESS/IX_FAIL | |
702 | */ | |
703 | PUBLIC IX_STATUS ixOsalMessageQueueReceive (IxOsalMessageQueue * queue, | |
704 | UINT8 * message); | |
705 | ||
706 | ||
707 | /* ======================= Thread Synchronisation ======================== | |
708 | * | |
709 | */ | |
710 | ||
711 | /** | |
712 | * @ingroup IxOsal | |
713 | * | |
714 | * @brief initializes a mutex | |
715 | * | |
716 | * @param mutex - mutex handle | |
717 | * | |
718 | * Initializes a mutex object | |
719 | * | |
720 | * @li Reentrant: no | |
721 | * @li IRQ safe: no | |
722 | * | |
723 | * @return - IX_SUCCESS/IX_FAIL | |
724 | */ | |
725 | PUBLIC IX_STATUS ixOsalMutexInit (IxOsalMutex * mutex); | |
726 | ||
727 | /** | |
728 | * @ingroup IxOsal | |
729 | * | |
730 | * @brief locks a mutex | |
731 | * | |
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 | |
735 | * | |
736 | * Locks a mutex object | |
737 | * | |
738 | * @li Reentrant: yes | |
739 | * @li IRQ safe: no | |
740 | * | |
741 | * @return - IX_SUCCESS/IX_FAIL | |
742 | */ | |
743 | PUBLIC IX_STATUS ixOsalMutexLock (IxOsalMutex * mutex, INT32 timeout); | |
744 | ||
745 | /** | |
746 | * @ingroup IxOsal | |
747 | * | |
748 | * @brief Unlocks a mutex | |
749 | * | |
750 | * @param mutex - mutex handle | |
751 | * | |
752 | * Unlocks a mutex object | |
753 | * | |
754 | * @li Reentrant: yes | |
755 | * @li IRQ safe: yes | |
756 | * | |
757 | * @return - IX_SUCCESS/IX_FAIL | |
758 | */ | |
759 | PUBLIC IX_STATUS ixOsalMutexUnlock (IxOsalMutex * mutex); | |
760 | ||
761 | /** | |
762 | * @ingroup IxOsal | |
763 | * | |
764 | * @brief Non-blocking attempt to lock a mutex | |
765 | * | |
766 | * @param mutex - mutex handle | |
767 | * | |
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 | |
770 | * | |
771 | * @li Reentrant: yes | |
772 | * @li IRQ safe: no | |
773 | * | |
774 | * @return - IX_SUCCESS/IX_FAIL | |
775 | */ | |
776 | PUBLIC IX_STATUS ixOsalMutexTryLock (IxOsalMutex * mutex); | |
777 | ||
778 | /** | |
779 | * @ingroup IxOsal | |
780 | * | |
781 | * @brief Destroys a mutex object | |
782 | * | |
783 | * @param mutex - mutex handle | |
784 | * @param | |
785 | * | |
786 | * Destroys a mutex object; the caller should ensure that no thread is | |
787 | * blocked on this mutex | |
788 | * | |
789 | * @li Reentrant: no | |
790 | * @li IRQ safe: no | |
791 | * | |
792 | * @return - IX_SUCCESS/IX_FAIL | |
793 | */ | |
794 | PUBLIC IX_STATUS ixOsalMutexDestroy (IxOsalMutex * mutex); | |
795 | ||
796 | /** | |
797 | * @ingroup IxOsal | |
798 | * | |
799 | * @brief Initializes a fast mutex | |
800 | * | |
801 | * @param mutex - fast mutex handle | |
802 | * | |
803 | * Initializes a fast mutex object | |
804 | * | |
805 | * @li Reentrant: yes | |
806 | * @li IRQ safe: yes | |
807 | * | |
808 | * @return - IX_SUCCESS/IX_FAIL | |
809 | */ | |
810 | PUBLIC IX_STATUS ixOsalFastMutexInit (IxOsalFastMutex * mutex); | |
811 | ||
812 | /** | |
813 | * @ingroup IxOsal | |
814 | * | |
815 | * @brief Non-blocking attempt to lock a fast mutex | |
816 | * | |
817 | * @param mutex - fast mutex handle | |
818 | * | |
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 | |
821 | * | |
822 | * @li Reentrant: yes | |
823 | * @li IRQ safe: yes | |
824 | * | |
825 | * @return - IX_SUCCESS/IX_FAIL | |
826 | */ | |
827 | PUBLIC IX_STATUS ixOsalFastMutexTryLock (IxOsalFastMutex * mutex); | |
828 | ||
829 | /** | |
830 | * @ingroup IxOsal | |
831 | * | |
832 | * @brief Unlocks a fast mutex | |
833 | * | |
834 | * @param mutex - fast mutex handle | |
835 | * | |
836 | * Unlocks a fast mutex object | |
837 | * | |
838 | * @li Reentrant: yes | |
839 | * @li IRQ safe: yes | |
840 | * | |
841 | * @return - IX_SUCCESS/IX_FAIL | |
842 | */ | |
843 | PUBLIC IX_STATUS ixOsalFastMutexUnlock (IxOsalFastMutex * mutex); | |
844 | ||
845 | /** | |
846 | * @ingroup IxOsal | |
847 | * | |
848 | * @brief Destroys a fast mutex object | |
849 | * | |
850 | * @param mutex - fast mutex handle | |
851 | * | |
852 | * Destroys a fast mutex object | |
853 | * | |
854 | * @li Reentrant: yes | |
855 | * @li IRQ safe: yes | |
856 | * | |
857 | * @return - IX_SUCCESS/IX_FAIL | |
858 | */ | |
859 | PUBLIC IX_STATUS ixOsalFastMutexDestroy (IxOsalFastMutex * mutex); | |
860 | ||
861 | /** | |
862 | * @ingroup IxOsal | |
863 | * | |
864 | * @brief Initializes a semaphore | |
865 | * | |
866 | * @param semaphore - semaphore handle | |
867 | * @param value - initial semaphore value | |
868 | * | |
869 | * Initializes a semaphore object | |
870 | * | |
871 | * @li Reentrant: no | |
872 | * @li IRQ safe: no | |
873 | * | |
874 | * @return - IX_SUCCESS/IX_FAIL | |
875 | */ | |
876 | PUBLIC IX_STATUS ixOsalSemaphoreInit (IxOsalSemaphore * semaphore, | |
877 | UINT32 value); | |
878 | ||
879 | /** | |
880 | * @ingroup IxOsal | |
881 | * | |
882 | * @brief Posts to (increments) a semaphore | |
883 | * | |
884 | * @param semaphore - semaphore handle | |
885 | * | |
886 | * Increments a semaphore object | |
887 | * | |
888 | * @li Reentrant: no | |
889 | * @li IRQ safe: yes | |
890 | * | |
891 | * @return - IX_SUCCESS/IX_FAIL | |
892 | */ | |
893 | PUBLIC IX_STATUS ixOsalSemaphorePost (IxOsalSemaphore * semaphore); | |
894 | ||
895 | /** | |
896 | * @ingroup IxOsal | |
897 | * | |
898 | * @brief Waits on (decrements) a semaphore | |
899 | * | |
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 | |
904 | * | |
905 | * Decrements a semaphore, blocking if the semaphore is | |
906 | * unavailable (value is 0). | |
907 | * | |
908 | * @li Reentrant: no | |
909 | * @li IRQ safe: no | |
910 | * | |
911 | * @return - IX_SUCCESS/IX_FAIL | |
912 | */ | |
913 | PUBLIC IX_STATUS ixOsalSemaphoreWait (IxOsalSemaphore * semaphore, | |
914 | INT32 timeout); | |
915 | ||
916 | /** | |
917 | * @ingroup IxOsal | |
918 | * | |
919 | * @brief Non-blocking wait on semaphore | |
920 | * | |
921 | * @param semaphore - semaphore handle | |
922 | * | |
923 | * Decrements a semaphore, not blocking the calling thread if the semaphore | |
924 | * is unavailable | |
925 | * | |
926 | * @li Reentrant: no | |
927 | * @li IRQ safe: no | |
928 | * | |
929 | * @return - IX_SUCCESS/IX_FAIL | |
930 | */ | |
931 | PUBLIC IX_STATUS ixOsalSemaphoreTryWait (IxOsalSemaphore * semaphore); | |
932 | ||
933 | /** | |
934 | * @ingroup IxOsal | |
935 | * | |
936 | * @brief Gets semaphore value | |
937 | * | |
938 | * @param semaphore - semaphore handle | |
939 | * @param value - location to store the semaphore value | |
940 | * | |
941 | * Retrieves the current value of a semaphore object | |
942 | * | |
943 | * @li Reentrant: no | |
944 | * @li IRQ safe: no | |
945 | * | |
946 | * @return - IX_SUCCESS/IX_FAIL | |
947 | */ | |
948 | PUBLIC IX_STATUS ixOsalSemaphoreGetValue (IxOsalSemaphore * semaphore, | |
949 | UINT32 * value); | |
950 | ||
951 | /** | |
952 | * @ingroup IxOsal | |
953 | * | |
954 | * @brief Destroys a semaphore object | |
955 | * | |
956 | * @param semaphore - semaphore handle | |
957 | * | |
958 | * Destroys a semaphore object; the caller should ensure that no thread is | |
959 | * blocked on this semaphore | |
960 | * | |
961 | * @li Reentrant: no | |
962 | * @li IRQ safe: no | |
963 | * | |
964 | * @return - IX_SUCCESS/IX_FAIL | |
965 | */ | |
966 | PUBLIC IX_STATUS ixOsalSemaphoreDestroy (IxOsalSemaphore * semaphore); | |
967 | ||
968 | /** | |
969 | * @ingroup IxOsal | |
970 | * | |
971 | * @brief Yields execution of current thread | |
972 | * | |
973 | * Yields the execution of the current thread | |
974 | * | |
975 | * @li Reentrant: no | |
976 | * @li IRQ safe: no | |
977 | * | |
978 | * @return - none | |
979 | */ | |
980 | PUBLIC void ixOsalYield (void); | |
981 | ||
982 | ||
983 | /* ========================== Time functions =========================== | |
984 | * | |
985 | */ | |
986 | ||
987 | /** | |
988 | * @ingroup IxOsal | |
989 | * | |
990 | * @brief Yielding sleep for a number of milliseconds | |
991 | * | |
992 | * @param milliseconds - number of milliseconds to sleep | |
993 | * | |
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 | |
998 | * loop. | |
999 | * | |
1000 | * @li Reentrant: no | |
1001 | * @li IRQ safe: no | |
1002 | * | |
1003 | * @return - none | |
1004 | */ | |
1005 | PUBLIC void ixOsalSleep (UINT32 milliseconds); | |
1006 | ||
1007 | /** | |
1008 | * @ingroup IxOsal | |
1009 | * | |
1010 | * @brief Busy sleep for a number of microseconds | |
1011 | * | |
1012 | * @param microseconds - number of microseconds to sleep | |
1013 | * | |
1014 | * Sleeps for the specified number of microseconds, without explicitly | |
1015 | * yielding thread execution to the OS scheduler | |
1016 | * | |
1017 | * @li Reentrant: yes | |
1018 | * @li IRQ safe: yes | |
1019 | * | |
1020 | * @return - none | |
1021 | */ | |
1022 | PUBLIC void ixOsalBusySleep (UINT32 microseconds); | |
1023 | ||
1024 | /** | |
1025 | * @ingroup IxOsal | |
1026 | * | |
1027 | * @brief XXX | |
1028 | * | |
1029 | * Retrieves the current timestamp | |
1030 | * | |
1031 | * @li Reentrant: yes | |
1032 | * @li IRQ safe: yes | |
1033 | * | |
1034 | * @return - The current timestamp | |
1035 | * | |
1036 | * @note The implementation of this function is platform-specific. Not | |
1037 | * all the platforms provide a high-resolution timestamp counter. | |
1038 | */ | |
1039 | PUBLIC UINT32 ixOsalTimestampGet (void); | |
1040 | ||
1041 | /** | |
1042 | * @ingroup IxOsal | |
1043 | * | |
1044 | * @brief Resolution of the timestamp counter | |
1045 | * | |
1046 | * Retrieves the resolution (frequency) of the timestamp counter. | |
1047 | * | |
1048 | * @li Reentrant: yes | |
1049 | * @li IRQ safe: yes | |
1050 | * | |
1051 | * @return - The resolution of the timestamp counter | |
1052 | * | |
1053 | * @note The implementation of this function is platform-specific. Not all | |
1054 | * the platforms provide a high-resolution timestamp counter. | |
1055 | */ | |
1056 | PUBLIC UINT32 ixOsalTimestampResolutionGet (void); | |
1057 | ||
1058 | /** | |
1059 | * @ingroup IxOsal | |
1060 | * | |
1061 | * @brief System clock rate, in ticks | |
1062 | * | |
1063 | * Retrieves the resolution (number of ticks per second) of the system clock | |
1064 | * | |
1065 | * @li Reentrant: no | |
1066 | * @li IRQ safe: no | |
1067 | * | |
1068 | * @return - The system clock rate | |
1069 | * | |
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 | |
1073 | */ | |
1074 | PUBLIC UINT32 ixOsalSysClockRateGet (void); | |
1075 | ||
1076 | /** | |
1077 | * @ingroup IxOsal | |
1078 | * | |
1079 | * @brief Current system time | |
1080 | * | |
1081 | * @param tv - pointer to an IxOsalTimeval structure to store the current | |
1082 | * time in | |
1083 | * | |
1084 | * Retrieves the current system time (real-time) | |
1085 | * | |
1086 | * @li Reentrant: no | |
1087 | * @li IRQ safe: no | |
1088 | * | |
1089 | * @return - none | |
1090 | * | |
1091 | * @note The implementation of this function is platform-specific. Not all | |
1092 | * platforms have a real-time clock. | |
1093 | */ | |
1094 | PUBLIC void ixOsalTimeGet (IxOsalTimeval * tv); | |
1095 | ||
1096 | ||
1097 | ||
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. | |
1102 | */ | |
1103 | PUBLIC UINT32 ixOsalTimevalToTicks (IxOsalTimeval tv); | |
1104 | ||
1105 | ||
1106 | /** | |
1107 | * @ingroup IxOsal | |
1108 | * | |
1109 | * @brief Converts ixOsalTimeVal into ticks | |
1110 | * | |
1111 | * @param tv - an IxOsalTimeval structure | |
1112 | * | |
1113 | * Converts an IxOsalTimeval structure into OS ticks | |
1114 | * | |
1115 | * @li Reentrant: yes | |
1116 | * @li IRQ safe: yes | |
1117 | * | |
1118 | * @return - Corresponding number of ticks | |
1119 | * | |
1120 | * Note: This function is OS-independent. Implemented by core. | |
1121 | */ | |
1122 | #define IX_OSAL_TIMEVAL_TO_TICKS(tv) ixOsalTimevalToTicks(tv) | |
1123 | ||
1124 | ||
1125 | ||
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 | |
1129 | */ | |
1130 | ||
1131 | PUBLIC void ixOsalTicksToTimeval (UINT32 ticks, IxOsalTimeval * pTv); | |
1132 | ||
1133 | ||
1134 | /** | |
1135 | * @ingroup IxOsal | |
1136 | * | |
1137 | * @brief Converts ticks into ixOsalTimeVal | |
1138 | * | |
1139 | * @param ticks - number of ticks | |
1140 | * @param pTv - pointer to the destination structure | |
1141 | * | |
1142 | * Converts the specified number of ticks into an IxOsalTimeval structure | |
1143 | * | |
1144 | * @li Reentrant: yes | |
1145 | * @li IRQ safe: yes | |
1146 | * | |
1147 | * @return - Corresponding IxOsalTimeval structure | |
1148 | * Note: This function is OS-independent. Implemented by core. | |
1149 | */ | |
1150 | #define IX_OSAL_TICKS_TO_TIMEVAL(ticks, pTv) \ | |
1151 | ixOsalTicksToTimeval(ticks, pTv) | |
1152 | ||
1153 | ||
1154 | ||
1155 | ||
1156 | /** | |
1157 | * @ingroup IxOsal | |
1158 | * | |
1159 | * @brief Converts ixOsalTimeVal to milliseconds | |
1160 | * | |
1161 | * @param tv - IxOsalTimeval structure to convert | |
1162 | * | |
1163 | * Converts an IxOsalTimeval structure into milliseconds | |
1164 | * | |
1165 | * @li Reentrant: yes | |
1166 | * @li IRQ safe: yes | |
1167 | * | |
1168 | * @return - Corresponding number of milliseconds | |
1169 | * Note: This function is OS-independent. Implemented by core. | |
1170 | */ | |
1171 | #define IX_OSAL_TIMEVAL_TO_MS(tv) ((tv.secs * 1000) + (tv.nsecs / 1000000)) | |
1172 | ||
1173 | ||
1174 | /** | |
1175 | * @ingroup IxOsal | |
1176 | * | |
1177 | * @brief Converts milliseconds to IxOsalTimeval | |
1178 | * | |
1179 | * @param milliseconds - number of milliseconds to convert | |
1180 | * @param pTv - pointer to the destination structure | |
1181 | * | |
1182 | * Converts a millisecond value into an IxOsalTimeval structure | |
1183 | * | |
1184 | * @li Reentrant: yes | |
1185 | * @li IRQ safe: yes | |
1186 | * | |
1187 | * @return - Corresponding IxOsalTimeval structure | |
1188 | * Note: This function is OS-independent. Implemented by core. | |
1189 | */ | |
1190 | #define IX_OSAL_MS_TO_TIMEVAL(milliseconds, pTv) \ | |
1191 | ((IxOsalTimeval *) pTv)->secs = milliseconds / 1000; \ | |
1192 | ((IxOsalTimeval *) pTv)->nsecs = (milliseconds % 1000) * 1000000 | |
1193 | ||
1194 | ||
1195 | /** | |
1196 | * @ingroup IxOsal | |
1197 | * | |
1198 | * @brief "equal" comparison for IxOsalTimeval | |
1199 | * | |
1200 | * @param tvA, tvB - IxOsalTimeval structures to compare | |
1201 | * | |
1202 | * Compares two IxOsalTimeval structures for equality | |
1203 | * | |
1204 | * @li Reentrant: yes | |
1205 | * @li IRQ safe: yes | |
1206 | * | |
472d5460 YS |
1207 | * @return - true if the structures are equal |
1208 | * - false otherwise | |
ba94a1bb WD |
1209 | * Note: This function is OS-independant |
1210 | */ | |
1211 | #define IX_OSAL_TIME_EQ(tvA, tvB) \ | |
1212 | ((tvA).secs == (tvB).secs && (tvA).nsecs == (tvB).nsecs) | |
1213 | ||
1214 | ||
1215 | /** | |
1216 | * @ingroup IxOsal | |
1217 | * | |
1218 | * @brief "less than" comparison for IxOsalTimeval | |
1219 | * | |
1220 | * @param tvA, tvB - IxOsalTimeval structures to compare | |
1221 | * | |
1222 | * Compares two IxOsalTimeval structures to determine if the first one is | |
1223 | * less than the second one | |
1224 | * | |
1225 | * @li Reentrant: yes | |
1226 | * @li IRQ safe: yes | |
1227 | * | |
472d5460 YS |
1228 | * @return - true if tvA < tvB |
1229 | * - false otherwise | |
ba94a1bb WD |
1230 | * Note: This function is OS-independent. Implemented by core. |
1231 | */ | |
1232 | #define IX_OSAL_TIME_LT(tvA,tvB) \ | |
1233 | ((tvA).secs < (tvB).secs || \ | |
1234 | ((tvA).secs == (tvB).secs && (tvA).nsecs < (tvB).nsecs)) | |
1235 | ||
1236 | ||
1237 | /** | |
1238 | * @ingroup IxOsal | |
1239 | * | |
1240 | * @brief "greater than" comparison for IxOsalTimeval | |
1241 | * | |
1242 | * @param tvA, tvB - IxOsalTimeval structures to compare | |
1243 | * | |
1244 | * Compares two IxOsalTimeval structures to determine if the first one is | |
1245 | * greater than the second one | |
1246 | * | |
1247 | * @li Reentrant: yes | |
1248 | * @li IRQ safe: yes | |
1249 | * | |
472d5460 YS |
1250 | * @return - true if tvA > tvB |
1251 | * - false otherwise | |
ba94a1bb WD |
1252 | * Note: This function is OS-independent. |
1253 | */ | |
1254 | #define IX_OSAL_TIME_GT(tvA, tvB) \ | |
1255 | ((tvA).secs > (tvB).secs || \ | |
1256 | ((tvA).secs == (tvB).secs && (tvA).nsecs > (tvB).nsecs)) | |
1257 | ||
1258 | ||
1259 | /** | |
1260 | * @ingroup IxOsal | |
1261 | * | |
1262 | * @brief "add" operator for IxOsalTimeval | |
1263 | * | |
1264 | * @param tvA, tvB - IxOsalTimeval structures to add | |
1265 | * | |
1266 | * Adds the second IxOsalTimevalStruct to the first one (equivalent to | |
1267 | * tvA += tvB) | |
1268 | * | |
1269 | * @li Reentrant: yes | |
1270 | * @li IRQ safe: yes | |
1271 | * | |
1272 | * @return - none | |
1273 | * Note: This function is OS-independent. | |
1274 | */ | |
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) \ | |
1279 | { \ | |
1280 | (tvA).secs++; \ | |
1281 | (tvA).nsecs -= IX_OSAL_BILLION; } | |
1282 | ||
1283 | ||
1284 | /** | |
1285 | * @ingroup IxOsal | |
1286 | * | |
1287 | * @brief "subtract" operator for IxOsalTimeval | |
1288 | * | |
1289 | * @param tvA, tvB - IxOsalTimeval structures to subtract | |
1290 | * | |
1291 | * Subtracts the second IxOsalTimevalStruct from the first one (equivalent | |
1292 | * to tvA -= tvB) | |
1293 | * | |
1294 | * @li Reentrant: yes | |
1295 | * @li IRQ safe: yes | |
1296 | * | |
1297 | * @return - none | |
1298 | * Note: This function is OS-independent. Implemented by core. | |
1299 | */ | |
1300 | #define IX_OSAL_TIME_SUB(tvA, tvB) \ | |
1301 | if ((tvA).nsecs >= (tvB).nsecs) \ | |
1302 | { \ | |
1303 | (tvA).secs -= (tvB).secs; \ | |
1304 | (tvA).nsecs -= (tvB).nsecs; \ | |
1305 | } \ | |
1306 | else \ | |
1307 | { \ | |
1308 | (tvA).secs -= ((tvB).secs + 1); \ | |
1309 | (tvA).nsecs += IX_OSAL_BILLION - (tvB).nsecs; \ | |
1310 | } | |
1311 | ||
1312 | ||
1313 | /* ============================= Logging ============================== | |
1314 | * | |
1315 | */ | |
1316 | ||
1317 | /** | |
1318 | * @ingroup IxOsal | |
1319 | * | |
1320 | * @brief Interrupt-safe logging function | |
1321 | * | |
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 | |
1326 | * | |
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). | |
1332 | * | |
1333 | * @li Reentrant: yes | |
1334 | * @li IRQ safe: yes | |
1335 | * | |
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) | |
1339 | * | |
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. | |
1344 | * | |
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. | |
1349 | */ | |
1350 | PUBLIC INT32 ixOsalLog (IxOsalLogLevel level, | |
1351 | IxOsalLogDevice device, | |
1352 | char *format, | |
1353 | int arg1, | |
1354 | int arg2, int arg3, int arg4, int arg5, int arg6); | |
1355 | ||
1356 | /** | |
1357 | * @ingroup IxOsal | |
1358 | * | |
1359 | * @brief sets the current logging verbosity level | |
1360 | * | |
1361 | * @param level - new log verbosity level | |
1362 | * | |
1363 | * Sets the log verbosity level. The default value is IX_OSAL_LOG_ERROR. | |
1364 | * | |
1365 | * @li Reentrant: yes | |
1366 | * @li IRQ safe: yes | |
1367 | * | |
1368 | * @return - Old log verbosity level | |
1369 | */ | |
1370 | PUBLIC UINT32 ixOsalLogLevelSet (UINT32 level); | |
1371 | ||
1372 | ||
1373 | /* ============================= Logging ============================== | |
1374 | * | |
1375 | */ | |
1376 | ||
1377 | /** | |
1378 | * @ingroup IxOsal | |
1379 | * | |
1380 | * @brief Schedules a repeating timer | |
1381 | * | |
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 | |
1387 | * | |
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 | |
1392 | * priorities. | |
1393 | * | |
1394 | * @li Reentrant: no | |
1395 | * @li IRQ safe: no | |
1396 | * | |
1397 | * @return - IX_SUCCESS/IX_FAIL | |
1398 | */ | |
1399 | PUBLIC IX_STATUS ixOsalRepeatingTimerSchedule (IxOsalTimer * timer, | |
1400 | UINT32 period, | |
1401 | UINT32 priority, | |
1402 | IxOsalVoidFnVoidPtr callback, | |
1403 | void *param); | |
1404 | ||
1405 | /** | |
1406 | * @ingroup IxOsal | |
1407 | * | |
1408 | * @brief Schedules a single-shot timer | |
1409 | * | |
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 | |
1415 | * | |
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. | |
1421 | * | |
1422 | * @li Reentrant: no | |
1423 | * @li IRQ safe: no | |
1424 | * | |
1425 | * @return - IX_SUCCESS/IX_FAIL | |
1426 | */ | |
1427 | PUBLIC IX_STATUS | |
1428 | ixOsalSingleShotTimerSchedule (IxOsalTimer * timer, | |
1429 | UINT32 period, | |
1430 | UINT32 priority, | |
1431 | IxOsalVoidFnVoidPtr callback, void *param); | |
1432 | ||
1433 | /** | |
1434 | * @ingroup IxOsal | |
1435 | * | |
1436 | * @brief Cancels a running timer | |
1437 | * | |
1438 | * @param timer - handle of the timer object | |
1439 | * | |
1440 | * Cancels a single-shot or repeating timer. | |
1441 | * | |
1442 | * @li Reentrant: no | |
1443 | * @li IRQ safe: yes | |
1444 | * | |
1445 | * @return - IX_SUCCESS/IX_FAIL | |
1446 | */ | |
1447 | PUBLIC IX_STATUS ixOsalTimerCancel (IxOsalTimer * timer); | |
1448 | ||
1449 | /** | |
1450 | * @ingroup IxOsal | |
1451 | * | |
1452 | * @brief displays all the running timers | |
1453 | * | |
1454 | * Displays a list with all the running timers and their parameters (handle, | |
1455 | * period, type, priority, callback and user parameter) | |
1456 | * | |
1457 | * @li Reentrant: no | |
1458 | * @li IRQ safe: no | |
1459 | * | |
1460 | * @return - none | |
1461 | */ | |
1462 | PUBLIC void ixOsalTimersShow (void); | |
1463 | ||
1464 | ||
1465 | /* ============================= Version ============================== | |
1466 | * | |
1467 | */ | |
1468 | ||
1469 | /** | |
1470 | * @ingroup IxOsal | |
1471 | * | |
1472 | * @brief provides the name of the Operating System running | |
1473 | * | |
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 | |
1479 | * | |
1480 | * Returns a string of characters that describe the Operating System name | |
1481 | * | |
1482 | * @li Reentrant: yes | |
1483 | * @li IRQ safe: yes | |
1484 | * | |
1485 | * return - IX_SUCCESS for successful retrieval | |
1486 | * - IX_FAIL if (osType == NULL | maxSize =< 0) | |
1487 | */ | |
1488 | PUBLIC IX_STATUS ixOsalOsNameGet (INT8* osName, INT32 maxSize); | |
1489 | ||
1490 | /** | |
1491 | * @ingroup IxOsal | |
1492 | * | |
1493 | * @brief provides the version of the Operating System running | |
1494 | * | |
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 | |
1500 | * | |
1501 | * Returns a string of characters that describe the Operating System's version | |
1502 | * | |
1503 | * @li Reentrant: yes | |
1504 | * @li IRQ safe: yes | |
1505 | * | |
1506 | * return - IX_SUCCESS for successful retrieval | |
1507 | * - IX_FAIL if (osVersion == NULL | maxSize =< 0) | |
1508 | */ | |
1509 | PUBLIC IX_STATUS ixOsalOsVersionGet(INT8* osVersion, INT32 maxSize); | |
1510 | ||
1511 | ||
1512 | ||
1513 | /** | |
1514 | * @} IxOsal | |
1515 | */ | |
1516 | ||
1517 | #endif /* IxOsal_H */ |