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  * 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  *
 253  * @param irqLevel - new interrupt level
 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  *
 272  * @param irqLevel - interrupt level to enable
 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  *
 288  * @param irqLevel - interrupt level to disable
 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  *
1207  * @return - true if the structures are equal
1208  *         - false otherwise
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  *
1228  * @return - true if tvA < tvB
1229  *         - false otherwise
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  *
1250  * @return - true if tvA > tvB
1251  *         - false  otherwise
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 */