drivers/net/npe/include/IxOsal.h

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