sys/contrib/ncsw/inc/xx_ext.h

   1 /* Copyright (c) 2008-2011 Freescale Semiconductor, Inc.
   2  * All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *     * Redistributions of source code must retain the above copyright
   7  *       notice, this list of conditions and the following disclaimer.
   8  *     * Redistributions in binary form must reproduce the above copyright
   9  *       notice, this list of conditions and the following disclaimer in the
  10  *       documentation and/or other materials provided with the distribution.
  11  *     * Neither the name of Freescale Semiconductor nor the
  12  *       names of its contributors may be used to endorse or promote products
  13  *       derived from this software without specific prior written permission.
  14  *
  15  *
  16  * ALTERNATIVELY, this software may be distributed under the terms of the
  17  * GNU General Public License ("GPL") as published by the Free Software
  18  * Foundation, either version 2 of that License or (at your option) any
  19  * later version.
  20  *
  21  * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY
  22  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  23  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  24  * DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY
  25  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  26  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  27  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  28  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  30  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 /**************************************************************************//**
  34  @File          xx_ext.h
  35
  36  @Description   Prototypes, externals and typedefs for system-supplied
  37                 (external) routines
  38 *//***************************************************************************/
  39
  40 #ifndef __XX_EXT_H
  41 #define __XX_EXT_H
  42
  43 #include "std_ext.h"
  44 #include "part_ext.h"
  45
  46 #if defined(__MWERKS__) && defined(OPTIMIZED_FOR_SPEED)
  47 #include "xx_integration_ext.h"
  48 #endif /* defined(__MWERKS__) && defined(OPTIMIZED_FOR_SPEED) */
  49
  50
  51 /**************************************************************************//**
  52  @Group         xx_id  XX Interface (System call hooks)
  53
  54  @Description   Prototypes, externals and typedefs for system-supplied
  55                 (external) routines
  56
  57  @{
  58 *//***************************************************************************/
  59
  60 #if (defined(REPORT_EVENTS) && (REPORT_EVENTS > 0))
  61 /**************************************************************************//**
  62  @Function      XX_EventById
  63
  64  @Description   Event reporting routine - executed only when REPORT_EVENTS=1.
  65
  66  @Param[in]     event - Event code (e_Event).
  67  @Param[in]     appId - Application identifier.
  68  @Param[in]     flags - Event flags.
  69  @Param[in]     msg   - Event message.
  70
  71  @Return        None
  72 *//***************************************************************************/
  73 void XX_EventById(uint32_t event, t_Handle appId, uint16_t flags, char *msg);
  74
  75 #else  /* not REPORT_EVENTS */
  76 #define XX_EventById(event, appId, flags, msg)
  77 #endif /* REPORT_EVENTS */
  78
  79
  80 #ifdef DEBUG_XX_MALLOC
  81 void * XX_MallocDebug(uint32_t size, char *fname, int line);
  82
  83 void * XX_MallocSmartDebug(uint32_t size,
  84                            int      memPartitionId,
  85                            uint32_t alignment,
  86                            char     *fname,
  87                            int      line);
  88
  89 #define XX_Malloc(sz) \
  90     XX_MallocDebug((sz), __FILE__, __LINE__)
  91
  92 #define XX_MallocSmart(sz, memt, al) \
  93     XX_MallocSmartDebug((sz), (memt), (al), __FILE__, __LINE__)
  94
  95 #else /* not DEBUG_XX_MALLOC */
  96 /**************************************************************************//**
  97  @Function      XX_Malloc
  98
  99  @Description   allocates contiguous block of memory.
 100
 101  @Param[in]     size - Number of bytes to allocate.
 102
 103  @Return        The address of the newly allocated block on success, NULL on failure.
 104 *//***************************************************************************/
 105 void * XX_Malloc(uint32_t size);
 106
 107 /**************************************************************************//**
 108  @Function      XX_MallocSmartInit
 109
 110  @Description   Initializes SmartMalloc allocator.
 111
 112  @Return        E_OK on success, error code otherwise.
 113 *//***************************************************************************/
 114 int XX_MallocSmartInit(void);
 115
 116 /**************************************************************************//**
 117  @Function      XX_MallocSmart
 118
 119  @Description   Allocates contiguous block of memory in a specified
 120                 alignment and from the specified segment.
 121
 122  @Param[in]     size            - Number of bytes to allocate.
 123  @Param[in]     memPartitionId  - Memory partition ID; The value zero must
 124                                   be mapped to the default heap partition.
 125  @Param[in]     alignment       - Required memory alignment (in bytes).
 126
 127  @Return        The address of the newly allocated block on success, NULL on failure.
 128 *//***************************************************************************/
 129 void * XX_MallocSmart(uint32_t size, int memPartitionId, uint32_t alignment);
 130 #endif /* not DEBUG_XX_MALLOC */
 131
 132 /**************************************************************************//**
 133  @Function      XX_FreeSmart
 134
 135  @Description   Frees the memory block pointed to by "p".
 136                 Only for memory allocated by XX_MallocSmart
 137
 138  @Param[in]     p_Memory - pointer to the memory block.
 139
 140  @Return        None.
 141 *//***************************************************************************/
 142 void XX_FreeSmart(void *p_Memory);
 143
 144 /**************************************************************************//**
 145  @Function      XX_Free
 146
 147  @Description   frees the memory block pointed to by "p".
 148
 149  @Param[in]     p_Memory - pointer to the memory block.
 150
 151  @Return        None.
 152 *//***************************************************************************/
 153 void XX_Free(void *p_Memory);
 154
 155 #ifndef NCSW_LINUX
 156 /**************************************************************************//**
 157  @Function      XX_GetMemPartitionBase
 158
 159  @Description   This routine gets the address of a memory segment according to
 160                 the memory type.
 161
 162  @Param[in]     memPartitionId  - Memory partition ID; The value zero must
 163                                   be mapped to the default heap partition.
 164
 165  @Return        The address of the required memory type.
 166 *//***************************************************************************/
 167 void * XX_GetMemPartitionBase(int memPartitionId);
 168 #endif
 169
 170 /**************************************************************************//**
 171  @Function      XX_Print
 172
 173  @Description   print a string.
 174
 175  @Param[in]     str - string to print.
 176
 177  @Return        None.
 178 *//***************************************************************************/
 179 void    XX_Print(char *str, ...);
 180
 181 /**************************************************************************//**
 182  @Function      XX_GetChar
 183
 184  @Description   Get character from console.
 185
 186  @Return        Character is returned on success. Zero is returned otherwise.
 187 *//***************************************************************************/
 188 char    XX_GetChar(void);
 189
 190 /**************************************************************************//**
 191  @Function      XX_PreallocAndBindIntr
 192
 193  @Description   Preallocate and optionally bind it to given CPU.
 194
 195  @Param[in]     irq     - Interrupt ID (system-specific number).
 196  @Param[in]     cpu     - CPU to bind to or -1 if iRQ should be unbound.
 197
 198  @Return        E_OK on success; error code otherwise..
 199 *//***************************************************************************/
 200 t_Error XX_PreallocAndBindIntr(int irq, unsigned int cpu);
 201
 202 /**************************************************************************//**
 203  @Function      XX_DeallocIntr
 204
 205  @Description   Deallocate preallocated interupt.
 206
 207  @Param[in]     irq     - Interrupt ID (system-specific number).
 208
 209  @Return        E_OK on success; error code otherwise..
 210 *//***************************************************************************/
 211 t_Error XX_DeallocIntr(int irq);
 212
 213 /**************************************************************************//**
 214  @Function      XX_SetIntr
 215
 216  @Description   Set an interrupt service routine for a specific interrupt source.
 217
 218  @Param[in]     irq     - Interrupt ID (system-specific number).
 219  @Param[in]     f_Isr   - Callback routine that will be called when the interrupt occurs.
 220  @Param[in]     handle  - The argument for the user callback routine.
 221
 222  @Return        E_OK on success; error code otherwise..
 223 *//***************************************************************************/
 224 t_Error XX_SetIntr(int irq, t_Isr *f_Isr, t_Handle handle);
 225
 226 /**************************************************************************//**
 227  @Function      XX_FreeIntr
 228
 229  @Description   Free a specific interrupt and a specific callback routine.
 230
 231  @Param[in]     irq - Interrupt ID (system-specific number).
 232
 233  @Return        E_OK on success; error code otherwise..
 234 *//***************************************************************************/
 235 t_Error XX_FreeIntr(int irq);
 236
 237 /**************************************************************************//**
 238  @Function      XX_EnableIntr
 239
 240  @Description   Enable a specific interrupt.
 241
 242  @Param[in]     irq - Interrupt ID (system-specific number).
 243
 244  @Return        E_OK on success; error code otherwise..
 245 *//***************************************************************************/
 246 t_Error XX_EnableIntr(int irq);
 247
 248 /**************************************************************************//**
 249  @Function      XX_DisableIntr
 250
 251  @Description   Disable a specific interrupt.
 252
 253  @Param[in]     irq - Interrupt ID (system-specific number).
 254
 255  @Return        E_OK on success; error code otherwise..
 256 *//***************************************************************************/
 257 t_Error XX_DisableIntr(int irq);
 258
 259 #if !(defined(__MWERKS__) && defined(OPTIMIZED_FOR_SPEED))
 260 /**************************************************************************//**
 261  @Function      XX_DisableAllIntr
 262
 263  @Description   Disable all interrupts by masking them at the CPU.
 264
 265  @Return        A value that represents the interrupts state before the
 266                 operation, and should be passed to the matching
 267                 XX_RestoreAllIntr() call.
 268 *//***************************************************************************/
 269 uint32_t XX_DisableAllIntr(void);
 270
 271 /**************************************************************************//**
 272  @Function      XX_RestoreAllIntr
 273
 274  @Description   Restore previous state of interrupts level at the CPU.
 275
 276  @Param[in]     flags - A value that represents the interrupts state to restore,
 277                         as returned by the matching call for XX_DisableAllIntr().
 278
 279  @Return        None.
 280 *//***************************************************************************/
 281 void XX_RestoreAllIntr(uint32_t flags);
 282 #endif /* !(defined(__MWERKS__) && defined(OPTIMIZED_FOR_SPEED)) */
 283
 284 /**************************************************************************//**
 285  @Function      XX_Call
 286
 287  @Description   Call a service in another task.
 288
 289                 Activate the routine "f" via the queue identified by "IntrManagerId". The
 290                 parameter to "f" is Id - the handle of the destination object
 291
 292  @Param[in]     intrManagerId   - Queue ID.
 293  @Param[in]     f               - routine pointer.
 294  @Param[in]     Id              - the parameter to be passed to f().
 295  @Param[in]     h_App           - Application handle.
 296  @Param[in]     flags           - Unused,
 297
 298  @Return        E_OK is returned on success. E_FAIL is returned otherwise (usually an operating system level failure).
 299 *//***************************************************************************/
 300 t_Error XX_Call( uint32_t intrManagerId,
 301                  t_Error (* f)(t_Handle),
 302                  t_Handle Id,
 303                  t_Handle h_App,
 304                  uint16_t flags );
 305
 306 /**************************************************************************//**
 307  @Function      XX_Exit
 308
 309  @Description   Stop execution and report status (where it is applicable)
 310
 311  @Param[in]     status - exit status
 312 *//***************************************************************************/
 313 void    XX_Exit(int status);
 314
 315 /*****************************************************************************/
 316 /*                        Tasklet Service Routines                           */
 317 /*****************************************************************************/
 318 typedef t_Handle t_TaskletHandle;
 319
 320 /**************************************************************************//**
 321  @Function      XX_InitTasklet
 322
 323  @Description   Create and initialize a tasklet object.
 324
 325  @Param[in]     routine - A routine to be ran as a tasklet.
 326  @Param[in]     data    - An argument to pass to the tasklet.
 327
 328  @Return        Tasklet handle is returned on success. NULL is returned otherwise.
 329 *//***************************************************************************/
 330 t_TaskletHandle XX_InitTasklet (void (*routine)(void *), void *data);
 331
 332 /**************************************************************************//**
 333  @Function      XX_FreeTasklet
 334
 335  @Description   Free a tasklet object.
 336
 337  @Param[in]     h_Tasklet - A handle to a tasklet to be free.
 338
 339  @Return        None.
 340 *//***************************************************************************/
 341 void XX_FreeTasklet (t_TaskletHandle h_Tasklet);
 342
 343 /**************************************************************************//**
 344  @Function      XX_ScheduleTask
 345
 346  @Description   Schedule a tasklet object.
 347
 348  @Param[in]     h_Tasklet - A handle to a tasklet to be scheduled.
 349  @Param[in]     immediate - Indicate whether to schedule this tasklet on
 350                             the immediate queue or on the delayed one.
 351
 352  @Return        0 - on success. Error code - otherwise.
 353 *//***************************************************************************/
 354 int XX_ScheduleTask(t_TaskletHandle h_Tasklet, int immediate);
 355
 356 /**************************************************************************//**
 357  @Function      XX_FlushScheduledTasks
 358
 359  @Description   Flush all tasks there are in the scheduled tasks queue.
 360
 361  @Return        None.
 362 *//***************************************************************************/
 363 void XX_FlushScheduledTasks(void);
 364
 365 /**************************************************************************//**
 366  @Function      XX_TaskletIsQueued
 367
 368  @Description   Check if task is queued.
 369
 370  @Param[in]     h_Tasklet - A handle to a tasklet to be scheduled.
 371
 372  @Return        1 - task is queued. 0 - otherwise.
 373 *//***************************************************************************/
 374 int XX_TaskletIsQueued(t_TaskletHandle h_Tasklet);
 375
 376 /**************************************************************************//**
 377  @Function      XX_SetTaskletData
 378
 379  @Description   Set data to a scheduled task. Used to change data of already
 380                 scheduled task.
 381
 382  @Param[in]     h_Tasklet - A handle to a tasklet to be scheduled.
 383  @Param[in]     data      - Data to be set.
 384 *//***************************************************************************/
 385 void XX_SetTaskletData(t_TaskletHandle h_Tasklet, t_Handle data);
 386
 387 /**************************************************************************//**
 388  @Function      XX_GetTaskletData
 389
 390  @Description   Get the data of scheduled task.
 391
 392  @Param[in]     h_Tasklet - A handle to a tasklet to be scheduled.
 393
 394  @Return        handle to the data of the task.
 395 *//***************************************************************************/
 396 t_Handle XX_GetTaskletData(t_TaskletHandle h_Tasklet);
 397
 398 /**************************************************************************//**
 399  @Function      XX_BottomHalf
 400
 401  @Description   Bottom half implementation, invoked by the interrupt handler.
 402
 403                 This routine handles all bottom-half tasklets with interrupts
 404                 enabled.
 405
 406  @Return        None.
 407 *//***************************************************************************/
 408 void XX_BottomHalf(void);
 409
 410
 411 /*****************************************************************************/
 412 /*                        Spinlock Service Routines                          */
 413 /*****************************************************************************/
 414
 415 /**************************************************************************//**
 416  @Function      XX_InitSpinlock
 417
 418  @Description   Creates a spinlock.
 419
 420  @Return        Spinlock handle is returned on success; NULL otherwise.
 421 *//***************************************************************************/
 422 t_Handle XX_InitSpinlock(void);
 423
 424 /**************************************************************************//**
 425  @Function      XX_FreeSpinlock
 426
 427  @Description   Frees the memory allocated for the spinlock creation.
 428
 429  @Param[in]     h_Spinlock - A handle to a spinlock.
 430
 431  @Return        None.
 432 *//***************************************************************************/
 433 void XX_FreeSpinlock(t_Handle h_Spinlock);
 434
 435 /**************************************************************************//**
 436  @Function      XX_LockSpinlock
 437
 438  @Description   Locks a spinlock.
 439
 440  @Param[in]     h_Spinlock - A handle to a spinlock.
 441
 442  @Return        None.
 443 *//***************************************************************************/
 444 void XX_LockSpinlock(t_Handle h_Spinlock);
 445
 446 /**************************************************************************//**
 447  @Function      XX_UnlockSpinlock
 448
 449  @Description   Unlocks a spinlock.
 450
 451  @Param[in]     h_Spinlock - A handle to a spinlock.
 452
 453  @Return        None.
 454 *//***************************************************************************/
 455 void XX_UnlockSpinlock(t_Handle h_Spinlock);
 456
 457 /**************************************************************************//**
 458  @Function      XX_LockIntrSpinlock
 459
 460  @Description   Locks a spinlock (interrupt safe).
 461
 462  @Param[in]     h_Spinlock - A handle to a spinlock.
 463
 464  @Return        A value that represents the interrupts state before the
 465                 operation, and should be passed to the matching
 466                 XX_UnlockIntrSpinlock() call.
 467 *//***************************************************************************/
 468 uint32_t XX_LockIntrSpinlock(t_Handle h_Spinlock);
 469
 470 /**************************************************************************//**
 471  @Function      XX_UnlockIntrSpinlock
 472
 473  @Description   Unlocks a spinlock (interrupt safe).
 474
 475  @Param[in]     h_Spinlock  - A handle to a spinlock.
 476  @Param[in]     intrFlags   - A value that represents the interrupts state to
 477                               restore, as returned by the matching call for
 478                               XX_LockIntrSpinlock().
 479
 480  @Return        None.
 481 *//***************************************************************************/
 482 void XX_UnlockIntrSpinlock(t_Handle h_Spinlock, uint32_t intrFlags);
 483
 484
 485 /*****************************************************************************/
 486 /*                        Timers Service Routines                            */
 487 /*****************************************************************************/
 488
 489 /**************************************************************************//**
 490  @Function      XX_CurrentTime
 491
 492  @Description   Returns current system time.
 493
 494  @Return        Current system time (in milliseconds).
 495 *//***************************************************************************/
 496 uint32_t XX_CurrentTime(void);
 497
 498 /**************************************************************************//**
 499  @Function      XX_CreateTimer
 500
 501  @Description   Creates a timer.
 502
 503  @Return        Timer handle is returned on success; NULL otherwise.
 504 *//***************************************************************************/
 505 t_Handle XX_CreateTimer(void);
 506
 507 /**************************************************************************//**
 508  @Function      XX_FreeTimer
 509
 510  @Description   Frees the memory allocated for the timer creation.
 511
 512  @Param[in]     h_Timer - A handle to a timer.
 513
 514  @Return        None.
 515 *//***************************************************************************/
 516 void XX_FreeTimer(t_Handle h_Timer);
 517
 518 /**************************************************************************//**
 519  @Function      XX_StartTimer
 520
 521  @Description   Starts a timer.
 522
 523                 The user can select to start the timer as periodic timer or as
 524                 one-shot timer. The user should provide a callback routine that
 525                 will be called when the timer expires.
 526
 527  @Param[in]     h_Timer         - A handle to a timer.
 528  @Param[in]     msecs           - Timer expiration period (in milliseconds).
 529  @Param[in]     periodic        - TRUE for a periodic timer;
 530                                   FALSE for a one-shot timer..
 531  @Param[in]     f_TimerExpired  - A callback routine to be called when the
 532                                   timer expires.
 533  @Param[in]     h_Arg           - The argument to pass in the timer-expired
 534                                   callback routine.
 535
 536  @Return        None.
 537 *//***************************************************************************/
 538 void XX_StartTimer(t_Handle h_Timer,
 539                    uint32_t msecs,
 540                    bool     periodic,
 541                    void     (*f_TimerExpired)(t_Handle h_Arg),
 542                    t_Handle h_Arg);
 543
 544 /**************************************************************************//**
 545  @Function      XX_StopTimer
 546
 547  @Description   Frees the memory allocated for the timer creation.
 548
 549  @Param[in]     h_Timer - A handle to a timer.
 550
 551  @Return        None.
 552 *//***************************************************************************/
 553 void XX_StopTimer(t_Handle h_Timer);
 554
 555 /**************************************************************************//**
 556  @Function      XX_GetExpirationTime
 557
 558  @Description   Returns the time (in milliseconds) remaining until the
 559                 expiration of a timer.
 560
 561  @Param[in]     h_Timer - A handle to a timer.
 562
 563  @Return        The time left until the timer expires.
 564 *//***************************************************************************/
 565 uint32_t XX_GetExpirationTime(t_Handle h_Timer);
 566
 567 /**************************************************************************//**
 568  @Function      XX_ModTimer
 569
 570  @Description   Updates the expiration time of a timer.
 571
 572                 This routine adds the given time to the current system time,
 573                 and sets this value as the new expiration time of the timer.
 574
 575  @Param[in]     h_Timer - A handle to a timer.
 576  @Param[in]     msecs   - The new interval until timer expiration
 577                           (in milliseconds).
 578
 579  @Return        None.
 580 *//***************************************************************************/
 581 void XX_ModTimer(t_Handle h_Timer, uint32_t msecs);
 582
 583 /**************************************************************************//**
 584  @Function      XX_TimerIsActive
 585
 586  @Description   Checks whether a timer is active (pending) or not.
 587
 588  @Param[in]     h_Timer - A handle to a timer.
 589
 590  @Return        0 - the timer is inactive; Non-zero value - the timer is active;
 591 *//***************************************************************************/
 592 int XX_TimerIsActive(t_Handle h_Timer);
 593
 594 /**************************************************************************//**
 595  @Function      XX_Sleep
 596
 597  @Description   Non-busy wait until the desired time (in milliseconds) has passed.
 598
 599  @Param[in]     msecs - The requested sleep time (in milliseconds).
 600
 601  @Return        None.
 602
 603  @Cautions      This routine enables interrupts during its wait time.
 604 *//***************************************************************************/
 605 uint32_t XX_Sleep(uint32_t msecs);
 606
 607 /**************************************************************************//**
 608  @Function      XX_UDelay
 609
 610  @Description   Busy-wait until the desired time (in microseconds) has passed.
 611
 612  @Param[in]     usecs - The requested delay time (in microseconds).
 613
 614  @Return        None.
 615
 616  @Cautions      It is highly unrecommended to call this routine during interrupt
 617                 time, because the system time may not be updated properly during
 618                 the delay loop. The behavior of this routine during interrupt
 619                 time is unexpected.
 620 *//***************************************************************************/
 621 void XX_UDelay(uint32_t usecs);
 622
 623
 624 /*****************************************************************************/
 625 /*                         Other Service Routines                            */
 626 /*****************************************************************************/
 627
 628 /**************************************************************************//**
 629  @Function      XX_PhysToVirt
 630
 631  @Description   Translates a physical address to the matching virtual address.
 632
 633  @Param[in]     addr - The physical address to translate.
 634
 635  @Return        Virtual address.
 636 *//***************************************************************************/
 637 void * XX_PhysToVirt(physAddress_t addr);
 638
 639 /**************************************************************************//**
 640  @Function      XX_VirtToPhys
 641
 642  @Description   Translates a virtual address to the matching physical address.
 643
 644  @Param[in]     addr - The virtual address to translate.
 645
 646  @Return        Physical address.
 647 *//***************************************************************************/
 648 physAddress_t XX_VirtToPhys(void *addr);
 649
 650 /**************************************************************************//**
 651  @Function      XX_PortalSetInfo
 652
 653  @Description   Save physical and virtual adresses of the portals.
 654
 655  @Param[in]     dev - Portals device - either bman or qman.
 656
 657  @Return        Physical, virtual addresses and size.
 658 *//***************************************************************************/
 659 void XX_PortalSetInfo(device_t dev);
 660
 661 /**************************************************************************//**
 662  @Function      XX_FmanSetIntrInfo
 663
 664  @Description   Workaround for FMan interrupt, which must be binded to one CPU
 665                 only.
 666
 667  @Param[in]     irq - Interrupt number.
 668
 669  @Return        None.
 670 *//***************************************************************************/
 671 void XX_FmanFixIntr(int irq);
 672
 673 /**************************************************************************//**
 674  @Group         xx_ipc  XX Inter-Partition-Communication API
 675
 676  @Description   The following API is to be used when working with multiple
 677                 partitions configuration.
 678
 679  @{
 680 *//***************************************************************************/
 681
 682 #define XX_IPC_MAX_ADDR_NAME_LENGTH 16         /**< Maximum length of an endpoint name string;
 683                                                     The IPC service can use this constant to limit
 684                                                     the storage space for IPC endpoint names. */
 685
 686
 687 /**************************************************************************//**
 688  @Function      t_IpcMsgCompletion
 689
 690  @Description   Callback function used upon IPC non-blocking transaction completion
 691                 to return message buffer to the caller and to forward reply if available.
 692
 693                 This callback function may be attached by the source endpoint to any outgoing
 694                 IPC message to indicate a non-blocking send (see also XX_IpcSendMessage() routine).
 695                 Upon completion of an IPC transaction (consisting of a message and an optional reply),
 696                 the IPC service invokes this callback routine to return the message buffer to the sender
 697                 and to provide the received reply, if requested.
 698
 699                 User provides this function. Driver invokes it.
 700
 701  @Param[in]     h_Module        - Abstract handle to the sending module -  the same handle as was passed
 702                                   in the XX_IpcSendMessage() function; This handle is typically used to point
 703                                   to the internal data structure of the source endpoint.
 704  @Param[in]     p_Msg           - Pointer to original (sent) message buffer;
 705                                   The source endpoint can free (or reuse) this buffer when message
 706                                   completion callback is called.
 707  @Param[in]     p_Reply         - Pointer to (received) reply buffer;
 708                                   This pointer is the same as was provided by the source endpoint in
 709                                   XX_IpcSendMessage().
 710  @Param[in]     replyLength     - Length (in bytes) of actual data in the reply buffer.
 711  @Param[in]     status          - Completion status - E_OK or failure indication, e.g. IPC transaction completion
 712                                   timeout.
 713
 714  @Return        None
 715  *//***************************************************************************/
 716 typedef void    (t_IpcMsgCompletion)(t_Handle   h_Module,
 717                                      uint8_t    *p_Msg,
 718                                      uint8_t    *p_Reply,
 719                                      uint32_t   replyLength,
 720                                      t_Error    status);
 721
 722 /**************************************************************************//**
 723  @Function      t_IpcMsgHandler
 724
 725  @Description   Callback function used as IPC message handler.
 726
 727                 The IPC service invokes message handlers for each IPC message received.
 728                 The actual function pointer should be registered by each destination endpoint
 729                 via the XX_IpcRegisterMsgHandler() routine.
 730
 731                 User provides this function. Driver invokes it.
 732
 733  @Param[in]     h_Module        - Abstract handle to the message handling module -  the same handle as
 734                                   was passed in the XX_IpcRegisterMsgHandler() function; this handle is
 735                                   typically used to point to the internal data structure of the destination
 736                                   endpoint.
 737  @Param[in]     p_Msg           - Pointer to message buffer with data received from peer.
 738  @Param[in]     msgLength       - Length (in bytes) of message data.
 739  @Param[in]     p_Reply         - Pointer to reply buffer, to be filled by the message handler and then sent
 740                                   by the IPC service;
 741                                   The reply buffer is allocated by the IPC service with size equals to the
 742                                   replyLength parameter provided in message handler registration (see
 743                                   XX_IpcRegisterMsgHandler() function);
 744                                   If replyLength was initially specified as zero during message handler registration,
 745                                   the IPC service may set this pointer to NULL and assume that a reply is not needed;
 746                                   The IPC service is also responsible for freeing the reply buffer after the
 747                                   reply has been sent or dismissed.
 748  @Param[in,out] p_ReplyLength   - Pointer to reply length, which has a dual role in this function:
 749                                   [In] equals the replyLength parameter provided in message handler
 750                                   registration (see XX_IpcRegisterMsgHandler() function), and
 751                                   [Out] should be updated by message handler to the actual reply length; if
 752                                   this value is set to zero, the IPC service must assume that a reply should
 753                                   not be sent;
 754                                   Note: If p_Reply is not NULL, p_ReplyLength must not be NULL as well.
 755
 756  @Return        E_OK on success; Error code otherwise.
 757  *//***************************************************************************/
 758 typedef t_Error (t_IpcMsgHandler)(t_Handle  h_Module,
 759                                   uint8_t   *p_Msg,
 760                                   uint32_t  msgLength,
 761                                   uint8_t   *p_Reply,
 762                                   uint32_t  *p_ReplyLength);
 763
 764 /**************************************************************************//**
 765  @Function      XX_IpcRegisterMsgHandler
 766
 767  @Description   IPC mailbox registration.
 768
 769                 This function is used for registering an IPC message handler in the IPC service.
 770                 This function is called by each destination endpoint to indicate that it is ready
 771                 to handle incoming messages. The IPC service invokes the message handler upon receiving
 772                 a message addressed to the specified destination endpoint.
 773
 774  @Param[in]     addr                - The address name string associated with the destination endpoint;
 775                                       This address must be unique across the IPC service domain to ensure
 776                                       correct message routing.
 777  @Param[in]     f_MsgHandler        - Pointer to the message handler callback for processing incoming
 778                                       message; invoked by the IPC service upon receiving a message
 779                                       addressed to the destination endpoint specified by the addr
 780                                       parameter.
 781  @Param[in]     h_Module            - Abstract handle to the message handling module, passed unchanged
 782                                       to f_MsgHandler callback function.
 783  @Param[in]     replyLength         - The maximal data length (in bytes) of any reply that the specified message handler
 784                                       may generate; the IPC service provides the message handler with buffer
 785                                       for reply according to the length specified here (refer also to the description
 786                                       of #t_IpcMsgHandler callback function type);
 787                                       This size shall be zero if the message handler never generates replies.
 788
 789  @Return        E_OK on success; Error code otherwise.
 790 *//***************************************************************************/
 791 t_Error XX_IpcRegisterMsgHandler(char                   addr[XX_IPC_MAX_ADDR_NAME_LENGTH],
 792                                  t_IpcMsgHandler        *f_MsgHandler,
 793                                  t_Handle               h_Module,
 794                                  uint32_t               replyLength);
 795
 796 /**************************************************************************//**
 797  @Function      XX_IpcUnregisterMsgHandler
 798
 799  @Description   Release IPC mailbox routine.
 800
 801                  This function is used for unregistering an IPC message handler from the IPC service.
 802                  This function is called by each destination endpoint to indicate that it is no longer
 803                  capable of handling incoming messages.
 804
 805  @Param[in]     addr          - The address name string associated with the destination endpoint;
 806                                 This address is the same as was used when the message handler was
 807                                 registered via XX_IpcRegisterMsgHandler().
 808
 809  @Return        E_OK on success; Error code otherwise.
 810 *//***************************************************************************/
 811 t_Error XX_IpcUnregisterMsgHandler(char addr[XX_IPC_MAX_ADDR_NAME_LENGTH]);
 812
 813 /**************************************************************************//**
 814  @Function      XX_IpcInitSession
 815
 816  @Description   This function is used for creating an IPC session between the source endpoint
 817                 and the destination endpoint.
 818
 819                 The actual implementation and representation of a session is left for the IPC service.
 820                 The function returns an abstract handle to the created session. This handle shall be used
 821                 by the source endpoint in subsequent calls to XX_IpcSendMessage().
 822                 The IPC service assumes that before this function is called, no messages are sent from
 823                 the specified source endpoint to the specified destination endpoint.
 824
 825                 The IPC service may use a connection-oriented approach or a connectionless approach (or both)
 826                 as described below.
 827
 828                 @par Connection-Oriented Approach
 829
 830                 The IPC service may implement a session in a connection-oriented approach -  when this function is called,
 831                 the IPC service should take the necessary steps to bring up a source-to-destination channel for messages
 832                 and a destination-to-source channel for replies. The returned handle should represent the internal
 833                 representation of these channels.
 834
 835                 @par Connectionless Approach
 836
 837                 The IPC service may implement a session in a connectionless approach -  when this function is called, the
 838                 IPC service should not perform any particular steps, but it must store the pair of source and destination
 839                 addresses in some session representation and return it as a handle. When XX_IpcSendMessage() shall be
 840                 called, the IPC service may use this handle to provide the necessary identifiers for routing the messages
 841                 through the connectionless medium.
 842
 843  @Param[in]     destAddr      - The address name string associated with the destination endpoint.
 844  @Param[in]     srcAddr       - The address name string associated with the source endpoint.
 845
 846  @Return        Abstract handle to the initialized session, or NULL on error.
 847 *//***************************************************************************/
 848 t_Handle XX_IpcInitSession(char destAddr[XX_IPC_MAX_ADDR_NAME_LENGTH],
 849                            char srcAddr[XX_IPC_MAX_ADDR_NAME_LENGTH]);
 850
 851 /**************************************************************************//**
 852  @Function      XX_IpcFreeSession
 853
 854  @Description   This function is used for terminating an existing IPC session between a source endpoint
 855                 and a destination endpoint.
 856
 857                 The IPC service assumes that after this function is called, no messages shall be sent from
 858                 the associated source endpoint to the associated destination endpoint.
 859
 860  @Param[in]     h_Session      - Abstract handle to the IPC session -  the same handle as was originally
 861                                  returned by the XX_IpcInitSession() function.
 862
 863  @Return        E_OK on success; Error code otherwise.
 864 *//***************************************************************************/
 865 t_Error XX_IpcFreeSession(t_Handle h_Session);
 866
 867 /**************************************************************************//**
 868  @Function      XX_IpcSendMessage
 869
 870  @Description   IPC message send routine.
 871
 872                 This function may be used by a source endpoint to send an IPC message to a destination
 873                 endpoint. The source endpoint cannot send a message to the destination endpoint without
 874                 first initiating a session with that destination endpoint via XX_IpcInitSession() routine.
 875
 876                 The source endpoint must provide the buffer pointer and length of the outgoing message.
 877                 Optionally, it may also provide a buffer for an expected reply. In the latter case, the
 878                 transaction is not considered complete by the IPC service until the reply has been received.
 879                 If the source endpoint does not provide a reply buffer, the transaction is considered
 880                 complete after the message has been sent. The source endpoint must keep the message (and
 881                 optional reply) buffers valid until the transaction is complete.
 882
 883                 @par Non-blocking mode
 884
 885                 The source endpoint may request a non-blocking send by providing a non-NULL pointer to a message
 886                 completion callback function (f_Completion). Upon completion of the IPC transaction (consisting of a
 887                 message and an optional reply), the IPC service invokes this callback routine to return the message
 888                 buffer to the sender and to provide the received reply, if requested.
 889
 890                 @par Blocking mode
 891
 892                 The source endpoint may request a blocking send by setting f_Completion to NULL. The function is
 893                 expected to block until the IPC transaction is complete -  either the reply has been received or (if no reply
 894                 was requested) the message has been sent.
 895
 896  @Param[in]     h_Session       - Abstract handle to the IPC session -  the same handle as was originally
 897                                   returned by the XX_IpcInitSession() function.
 898  @Param[in]     p_Msg           - Pointer to message buffer to send.
 899  @Param[in]     msgLength       - Length (in bytes) of actual data in the message buffer.
 900  @Param[in]     p_Reply         - Pointer to reply buffer -  if this buffer is not NULL, the IPC service
 901                                   fills this buffer with the received reply data;
 902                                   In blocking mode, the reply data must be valid when the function returns;
 903                                   In non-blocking mode, the reply data is valid when f_Completion is called;
 904                                   If this pointer is NULL, no reply is expected.
 905  @Param[in,out] p_ReplyLength   - Pointer to reply length, which has a dual role in this function:
 906                                   [In] specifies the maximal length (in bytes) of the reply buffer pointed by
 907                                   p_Reply, and
 908                                   [Out] in non-blocking mode this value is updated by the IPC service to the
 909                                   actual reply length (in bytes).
 910  @Param[in]     f_Completion    - Pointer to a completion callback to be used in non-blocking send mode;
 911                                   The completion callback is invoked by the IPC service upon
 912                                   completion of the IPC transaction (consisting of a message and an optional
 913                                   reply);
 914                                   If this pointer is NULL, the function is expected to block until the IPC
 915                                   transaction is complete.
 916  @Param[in]     h_Arg           - Abstract handle to the sending module; passed unchanged to the f_Completion
 917                                   callback function as the first argument.
 918
 919  @Return        E_OK on success; Error code otherwise.
 920 *//***************************************************************************/
 921 t_Error XX_IpcSendMessage(t_Handle           h_Session,
 922                           uint8_t            *p_Msg,
 923                           uint32_t           msgLength,
 924                           uint8_t            *p_Reply,
 925                           uint32_t           *p_ReplyLength,
 926                           t_IpcMsgCompletion *f_Completion,
 927                           t_Handle           h_Arg);
 928
 929
 930 /** @} */ /* end of xx_ipc group */
 931 /** @} */ /* end of xx_id group */
 932
 933 /** FreeBSD Specific additions. */
 934 void XX_TrackInit(void);
 935 physAddress_t  XX_TrackAddress(void *addr);
 936 void XX_UntrackAddress(void *addr);
 937
 938 #endif /* __XX_EXT_H */