sys/contrib/ncsw/inc/xx_ext.h

   1 /* Copyright (c) 2008-2012 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 /**************************************************************************//**
  35  @File          xx_ext.h
  36
  37  @Description   Prototypes, externals and typedefs for system-supplied
  38                 (external) routines
  39 *//***************************************************************************/
  40
  41 #ifndef __XX_EXT_H
  42 #define __XX_EXT_H
  43
  44 #include "std_ext.h"
  45 #include "xx_common.h"
  46 #include "part_ext.h"
  47
  48
  49
  50 /**************************************************************************//**
  51  @Group         xx_id  XX Interface (System call hooks)
  52
  53  @Description   Prototypes, externals and typedefs for system-supplied
  54                 (external) routines
  55
  56  @{
  57 *//***************************************************************************/
  58
  59 #ifdef DEBUG_XX_MALLOC
  60 void * XX_MallocDebug(uint32_t size, char *fname, int line);
  61
  62 void * XX_MallocSmartDebug(uint32_t size,
  63                            int      memPartitionId,
  64                            uint32_t alignment,
  65                            char     *fname,
  66                            int      line);
  67
  68 #define XX_Malloc(sz) \
  69     XX_MallocDebug((sz), __FILE__, __LINE__)
  70
  71 #define XX_MallocSmart(sz, memt, al) \
  72     XX_MallocSmartDebug((sz), (memt), (al), __FILE__, __LINE__)
  73
  74 #else /* not DEBUG_XX_MALLOC */
  75 /**************************************************************************//**
  76  @Function      XX_Malloc
  77
  78  @Description   allocates contiguous block of memory.
  79
  80  @Param[in]     size - Number of bytes to allocate.
  81
  82  @Return        The address of the newly allocated block on success, NULL on failure.
  83 *//***************************************************************************/
  84 void * XX_Malloc(uint32_t size);
  85
  86 /**************************************************************************//**
  87  @Function      XX_MallocSmart
  88
  89  @Description   Allocates contiguous block of memory in a specified
  90                 alignment and from the specified segment.
  91
  92  @Param[in]     size            - Number of bytes to allocate.
  93  @Param[in]     memPartitionId  - Memory partition ID; The value zero must
  94                                   be mapped to the default heap partition.
  95  @Param[in]     alignment       - Required memory alignment (in bytes).
  96
  97  @Return        The address of the newly allocated block on success, NULL on failure.
  98 *//***************************************************************************/
  99 void * XX_MallocSmart(uint32_t size, int memPartitionId, uint32_t alignment);
 100
 101 int XX_MallocSmartInit(void);
 102 #endif /* not DEBUG_XX_MALLOC */
 103
 104 /**************************************************************************//**
 105  @Function      XX_FreeSmart
 106
 107  @Description   Frees the memory block pointed to by "p".
 108                 Only for memory allocated by XX_MallocSmart
 109
 110  @Param[in]     p_Memory - pointer to the memory block.
 111
 112  @Return        None.
 113 *//***************************************************************************/
 114 void XX_FreeSmart(void *p_Memory);
 115
 116 /**************************************************************************//**
 117  @Function      XX_Free
 118
 119  @Description   frees the memory block pointed to by "p".
 120
 121  @Param[in]     p_Memory - pointer to the memory block.
 122
 123  @Return        None.
 124 *//***************************************************************************/
 125 void XX_Free(void *p_Memory);
 126
 127 /**************************************************************************//**
 128  @Function      XX_Print
 129
 130  @Description   print a string.
 131
 132  @Param[in]     str - string to print.
 133
 134  @Return        None.
 135 *//***************************************************************************/
 136 void XX_Print(char *str, ...);
 137
 138 /**************************************************************************//**
 139  @Function      XX_SetIntr
 140
 141  @Description   Set an interrupt service routine for a specific interrupt source.
 142
 143  @Param[in]     irq     - Interrupt ID (system-specific number).
 144  @Param[in]     f_Isr   - Callback routine that will be called when the interrupt occurs.
 145  @Param[in]     handle  - The argument for the user callback routine.
 146
 147  @Return        E_OK on success; error code otherwise..
 148 *//***************************************************************************/
 149 t_Error XX_SetIntr(uintptr_t irq, t_Isr *f_Isr, t_Handle handle);
 150
 151 /**************************************************************************//**
 152  @Function      XX_FreeIntr
 153
 154  @Description   Free a specific interrupt and a specific callback routine.
 155
 156  @Param[in]     irq - Interrupt ID (system-specific number).
 157
 158  @Return        E_OK on success; error code otherwise..
 159 *//***************************************************************************/
 160 t_Error XX_FreeIntr(uintptr_t irq);
 161
 162 /**************************************************************************//**
 163  @Function      XX_EnableIntr
 164
 165  @Description   Enable a specific interrupt.
 166
 167  @Param[in]     irq - Interrupt ID (system-specific number).
 168
 169  @Return        E_OK on success; error code otherwise..
 170 *//***************************************************************************/
 171 t_Error XX_EnableIntr(uintptr_t irq);
 172
 173 /**************************************************************************//**
 174  @Function      XX_DisableIntr
 175
 176  @Description   Disable a specific interrupt.
 177
 178  @Param[in]     irq - Interrupt ID (system-specific number).
 179
 180  @Return        E_OK on success; error code otherwise..
 181 *//***************************************************************************/
 182 t_Error XX_DisableIntr(uintptr_t irq);
 183
 184 /**************************************************************************//**
 185  @Function      XX_DisableAllIntr
 186
 187  @Description   Disable all interrupts by masking them at the CPU.
 188
 189  @Return        A value that represents the interrupts state before the
 190                 operation, and should be passed to the matching
 191                 XX_RestoreAllIntr() call.
 192 *//***************************************************************************/
 193 uint32_t XX_DisableAllIntr(void);
 194
 195 /**************************************************************************//**
 196  @Function      XX_RestoreAllIntr
 197
 198  @Description   Restore previous state of interrupts level at the CPU.
 199
 200  @Param[in]     flags - A value that represents the interrupts state to restore,
 201                         as returned by the matching call for XX_DisableAllIntr().
 202
 203  @Return        None.
 204 *//***************************************************************************/
 205 void XX_RestoreAllIntr(uint32_t flags);
 206
 207
 208 t_Error XX_PreallocAndBindIntr(uintptr_t irq, unsigned int cpu);
 209 t_Error XX_DeallocIntr(uintptr_t irq);
 210
 211 /**************************************************************************//**
 212  @Function      XX_Exit
 213
 214  @Description   Stop execution and report status (where it is applicable)
 215
 216  @Param[in]     status - exit status
 217 *//***************************************************************************/
 218 void    XX_Exit(int status);
 219
 220
 221 /*****************************************************************************/
 222 /*                        Tasklet Service Routines                           */
 223 /*****************************************************************************/
 224 typedef t_Handle t_TaskletHandle;
 225
 226 /**************************************************************************//**
 227  @Function      XX_InitTasklet
 228
 229  @Description   Create and initialize a tasklet object.
 230
 231  @Param[in]     routine - A routine to be ran as a tasklet.
 232  @Param[in]     data    - An argument to pass to the tasklet.
 233
 234  @Return        Tasklet handle is returned on success. NULL is returned otherwise.
 235 *//***************************************************************************/
 236 t_TaskletHandle XX_InitTasklet (void (*routine)(void *), void *data);
 237
 238 /**************************************************************************//**
 239  @Function      XX_FreeTasklet
 240
 241  @Description   Free a tasklet object.
 242
 243  @Param[in]     h_Tasklet - A handle to a tasklet to be free.
 244
 245  @Return        None.
 246 *//***************************************************************************/
 247 void XX_FreeTasklet (t_TaskletHandle h_Tasklet);
 248
 249 /**************************************************************************//**
 250  @Function      XX_ScheduleTask
 251
 252  @Description   Schedule a tasklet object.
 253
 254  @Param[in]     h_Tasklet - A handle to a tasklet to be scheduled.
 255  @Param[in]     immediate - Indicate whether to schedule this tasklet on
 256                             the immediate queue or on the delayed one.
 257
 258  @Return        0 - on success. Error code - otherwise.
 259 *//***************************************************************************/
 260 int XX_ScheduleTask(t_TaskletHandle h_Tasklet, int immediate);
 261
 262 /**************************************************************************//**
 263  @Function      XX_FlushScheduledTasks
 264
 265  @Description   Flush all tasks there are in the scheduled tasks queue.
 266
 267  @Return        None.
 268 *//***************************************************************************/
 269 void XX_FlushScheduledTasks(void);
 270
 271 /**************************************************************************//**
 272  @Function      XX_TaskletIsQueued
 273
 274  @Description   Check if task is queued.
 275
 276  @Param[in]     h_Tasklet - A handle to a tasklet to be scheduled.
 277
 278  @Return        1 - task is queued. 0 - otherwise.
 279 *//***************************************************************************/
 280 int XX_TaskletIsQueued(t_TaskletHandle h_Tasklet);
 281
 282 /**************************************************************************//**
 283  @Function      XX_SetTaskletData
 284
 285  @Description   Set data to a scheduled task. Used to change data of already
 286                 scheduled task.
 287
 288  @Param[in]     h_Tasklet - A handle to a tasklet to be scheduled.
 289  @Param[in]     data      - Data to be set.
 290 *//***************************************************************************/
 291 void XX_SetTaskletData(t_TaskletHandle h_Tasklet, t_Handle data);
 292
 293 /**************************************************************************//**
 294  @Function      XX_GetTaskletData
 295
 296  @Description   Get the data of scheduled task.
 297
 298  @Param[in]     h_Tasklet - A handle to a tasklet to be scheduled.
 299
 300  @Return        handle to the data of the task.
 301 *//***************************************************************************/
 302 t_Handle XX_GetTaskletData(t_TaskletHandle h_Tasklet);
 303
 304 /**************************************************************************//**
 305  @Function      XX_BottomHalf
 306
 307  @Description   Bottom half implementation, invoked by the interrupt handler.
 308
 309                 This routine handles all bottom-half tasklets with interrupts
 310                 enabled.
 311
 312  @Return        None.
 313 *//***************************************************************************/
 314 void XX_BottomHalf(void);
 315
 316
 317 /*****************************************************************************/
 318 /*                        Spinlock Service Routines                          */
 319 /*****************************************************************************/
 320
 321 /**************************************************************************//**
 322  @Function      XX_InitSpinlock
 323
 324  @Description   Creates a spinlock.
 325
 326  @Return        Spinlock handle is returned on success; NULL otherwise.
 327 *//***************************************************************************/
 328 t_Handle XX_InitSpinlock(void);
 329
 330 /**************************************************************************//**
 331  @Function      XX_FreeSpinlock
 332
 333  @Description   Frees the memory allocated for the spinlock creation.
 334
 335  @Param[in]     h_Spinlock - A handle to a spinlock.
 336
 337  @Return        None.
 338 *//***************************************************************************/
 339 void XX_FreeSpinlock(t_Handle h_Spinlock);
 340
 341 /**************************************************************************//**
 342  @Function      XX_LockSpinlock
 343
 344  @Description   Locks a spinlock.
 345
 346  @Param[in]     h_Spinlock - A handle to a spinlock.
 347
 348  @Return        None.
 349 *//***************************************************************************/
 350 void XX_LockSpinlock(t_Handle h_Spinlock);
 351
 352 /**************************************************************************//**
 353  @Function      XX_UnlockSpinlock
 354
 355  @Description   Unlocks a spinlock.
 356
 357  @Param[in]     h_Spinlock - A handle to a spinlock.
 358
 359  @Return        None.
 360 *//***************************************************************************/
 361 void XX_UnlockSpinlock(t_Handle h_Spinlock);
 362
 363 /**************************************************************************//**
 364  @Function      XX_LockIntrSpinlock
 365
 366  @Description   Locks a spinlock (interrupt safe).
 367
 368  @Param[in]     h_Spinlock - A handle to a spinlock.
 369
 370  @Return        A value that represents the interrupts state before the
 371                 operation, and should be passed to the matching
 372                 XX_UnlockIntrSpinlock() call.
 373 *//***************************************************************************/
 374 uint32_t XX_LockIntrSpinlock(t_Handle h_Spinlock);
 375
 376 /**************************************************************************//**
 377  @Function      XX_UnlockIntrSpinlock
 378
 379  @Description   Unlocks a spinlock (interrupt safe).
 380
 381  @Param[in]     h_Spinlock  - A handle to a spinlock.
 382  @Param[in]     intrFlags   - A value that represents the interrupts state to
 383                               restore, as returned by the matching call for
 384                               XX_LockIntrSpinlock().
 385
 386  @Return        None.
 387 *//***************************************************************************/
 388 void XX_UnlockIntrSpinlock(t_Handle h_Spinlock, uint32_t intrFlags);
 389
 390
 391 /*****************************************************************************/
 392 /*                        Timers Service Routines                            */
 393 /*****************************************************************************/
 394
 395 /**************************************************************************//**
 396  @Function      XX_CurrentTime
 397
 398  @Description   Returns current system time.
 399
 400  @Return        Current system time (in milliseconds).
 401 *//***************************************************************************/
 402 uint32_t XX_CurrentTime(void);
 403
 404 /**************************************************************************//**
 405  @Function      XX_CreateTimer
 406
 407  @Description   Creates a timer.
 408
 409  @Return        Timer handle is returned on success; NULL otherwise.
 410 *//***************************************************************************/
 411 t_Handle XX_CreateTimer(void);
 412
 413 /**************************************************************************//**
 414  @Function      XX_FreeTimer
 415
 416  @Description   Frees the memory allocated for the timer creation.
 417
 418  @Param[in]     h_Timer - A handle to a timer.
 419
 420  @Return        None.
 421 *//***************************************************************************/
 422 void XX_FreeTimer(t_Handle h_Timer);
 423
 424 /**************************************************************************//**
 425  @Function      XX_StartTimer
 426
 427  @Description   Starts a timer.
 428
 429                 The user can select to start the timer as periodic timer or as
 430                 one-shot timer. The user should provide a callback routine that
 431                 will be called when the timer expires.
 432
 433  @Param[in]     h_Timer         - A handle to a timer.
 434  @Param[in]     msecs           - Timer expiration period (in milliseconds).
 435  @Param[in]     periodic        - TRUE for a periodic timer;
 436                                   FALSE for a one-shot timer..
 437  @Param[in]     f_TimerExpired  - A callback routine to be called when the
 438                                   timer expires.
 439  @Param[in]     h_Arg           - The argument to pass in the timer-expired
 440                                   callback routine.
 441
 442  @Return        None.
 443 *//***************************************************************************/
 444 void XX_StartTimer(t_Handle h_Timer,
 445                    uint32_t msecs,
 446                    bool     periodic,
 447                    void     (*f_TimerExpired)(t_Handle h_Arg),
 448                    t_Handle h_Arg);
 449
 450 /**************************************************************************//**
 451  @Function      XX_StopTimer
 452
 453  @Description   Frees the memory allocated for the timer creation.
 454
 455  @Param[in]     h_Timer - A handle to a timer.
 456
 457  @Return        None.
 458 *//***************************************************************************/
 459 void XX_StopTimer(t_Handle h_Timer);
 460
 461 /**************************************************************************//**
 462  @Function      XX_ModTimer
 463
 464  @Description   Updates the expiration time of a timer.
 465
 466                 This routine adds the given time to the current system time,
 467                 and sets this value as the new expiration time of the timer.
 468
 469  @Param[in]     h_Timer - A handle to a timer.
 470  @Param[in]     msecs   - The new interval until timer expiration
 471                           (in milliseconds).
 472
 473  @Return        None.
 474 *//***************************************************************************/
 475 void XX_ModTimer(t_Handle h_Timer, uint32_t msecs);
 476
 477 /**************************************************************************//**
 478  @Function      XX_Sleep
 479
 480  @Description   Non-busy wait until the desired time (in milliseconds) has passed.
 481
 482  @Param[in]     msecs - The requested sleep time (in milliseconds).
 483
 484  @Return        Zero if the requested time has elapsed; Otherwise, the value
 485                 returned will be the unslept amount) in milliseconds.
 486
 487  @Cautions      This routine enables interrupts during its wait time.
 488 *//***************************************************************************/
 489 uint32_t XX_Sleep(uint32_t msecs);
 490
 491 /**************************************************************************//**
 492  @Function      XX_UDelay
 493
 494  @Description   Busy-wait until the desired time (in microseconds) has passed.
 495
 496  @Param[in]     usecs - The requested delay time (in microseconds).
 497
 498  @Return        None.
 499
 500  @Cautions      It is highly unrecommended to call this routine during interrupt
 501                 time, because the system time may not be updated properly during
 502                 the delay loop. The behavior of this routine during interrupt
 503                 time is unexpected.
 504 *//***************************************************************************/
 505 void XX_UDelay(uint32_t usecs);
 506
 507
 508 /*****************************************************************************/
 509 /*                         Other Service Routines                            */
 510 /*****************************************************************************/
 511
 512 /**************************************************************************//**
 513  @Function      XX_PhysToVirt
 514
 515  @Description   Translates a physical address to the matching virtual address.
 516
 517  @Param[in]     addr - The physical address to translate.
 518
 519  @Return        Virtual address.
 520 *//***************************************************************************/
 521 void * XX_PhysToVirt(physAddress_t addr);
 522
 523 /**************************************************************************//**
 524  @Function      XX_VirtToPhys
 525
 526  @Description   Translates a virtual address to the matching physical address.
 527
 528  @Param[in]     addr - The virtual address to translate.
 529
 530  @Return        Physical address.
 531 *//***************************************************************************/
 532 physAddress_t XX_VirtToPhys(void *addr);
 533
 534
 535 /**************************************************************************//**
 536  @Group         xx_ipc  XX Inter-Partition-Communication API
 537
 538  @Description   The following API is to be used when working with multiple
 539                 partitions configuration.
 540
 541  @{
 542 *//***************************************************************************/
 543
 544 #define XX_IPC_MAX_ADDR_NAME_LENGTH 16         /**< Maximum length of an endpoint name string;
 545                                                     The IPC service can use this constant to limit
 546                                                     the storage space for IPC endpoint names. */
 547
 548
 549 /**************************************************************************//**
 550  @Function      t_IpcMsgCompletion
 551
 552  @Description   Callback function used upon IPC non-blocking transaction completion
 553                 to return message buffer to the caller and to forward reply if available.
 554
 555                 This callback function may be attached by the source endpoint to any outgoing
 556                 IPC message to indicate a non-blocking send (see also XX_IpcSendMessage() routine).
 557                 Upon completion of an IPC transaction (consisting of a message and an optional reply),
 558                 the IPC service invokes this callback routine to return the message buffer to the sender
 559                 and to provide the received reply, if requested.
 560
 561                 User provides this function. Driver invokes it.
 562
 563  @Param[in]     h_Module        - Abstract handle to the sending module -  the same handle as was passed
 564                                   in the XX_IpcSendMessage() function; This handle is typically used to point
 565                                   to the internal data structure of the source endpoint.
 566  @Param[in]     p_Msg           - Pointer to original (sent) message buffer;
 567                                   The source endpoint can free (or reuse) this buffer when message
 568                                   completion callback is called.
 569  @Param[in]     p_Reply         - Pointer to (received) reply buffer;
 570                                   This pointer is the same as was provided by the source endpoint in
 571                                   XX_IpcSendMessage().
 572  @Param[in]     replyLength     - Length (in bytes) of actual data in the reply buffer.
 573  @Param[in]     status          - Completion status - E_OK or failure indication, e.g. IPC transaction completion
 574                                   timeout.
 575
 576  @Return        None
 577  *//***************************************************************************/
 578 typedef void    (t_IpcMsgCompletion)(t_Handle   h_Module,
 579                                      uint8_t    *p_Msg,
 580                                      uint8_t    *p_Reply,
 581                                      uint32_t   replyLength,
 582                                      t_Error    status);
 583
 584 /**************************************************************************//**
 585  @Function      t_IpcMsgHandler
 586
 587  @Description   Callback function used as IPC message handler.
 588
 589                 The IPC service invokes message handlers for each IPC message received.
 590                 The actual function pointer should be registered by each destination endpoint
 591                 via the XX_IpcRegisterMsgHandler() routine.
 592
 593                 User provides this function. Driver invokes it.
 594
 595  @Param[in]     h_Module        - Abstract handle to the message handling module -  the same handle as
 596                                   was passed in the XX_IpcRegisterMsgHandler() function; this handle is
 597                                   typically used to point to the internal data structure of the destination
 598                                   endpoint.
 599  @Param[in]     p_Msg           - Pointer to message buffer with data received from peer.
 600  @Param[in]     msgLength       - Length (in bytes) of message data.
 601  @Param[in]     p_Reply         - Pointer to reply buffer, to be filled by the message handler and then sent
 602                                   by the IPC service;
 603                                   The reply buffer is allocated by the IPC service with size equals to the
 604                                   replyLength parameter provided in message handler registration (see
 605                                   XX_IpcRegisterMsgHandler() function);
 606                                   If replyLength was initially specified as zero during message handler registration,
 607                                   the IPC service may set this pointer to NULL and assume that a reply is not needed;
 608                                   The IPC service is also responsible for freeing the reply buffer after the
 609                                   reply has been sent or dismissed.
 610  @Param[in,out] p_ReplyLength   - Pointer to reply length, which has a dual role in this function:
 611                                   [In] equals the replyLength parameter provided in message handler
 612                                   registration (see XX_IpcRegisterMsgHandler() function), and
 613                                   [Out] should be updated by message handler to the actual reply length; if
 614                                   this value is set to zero, the IPC service must assume that a reply should
 615                                   not be sent;
 616                                   Note: If p_Reply is not NULL, p_ReplyLength must not be NULL as well.
 617
 618  @Return        E_OK on success; Error code otherwise.
 619  *//***************************************************************************/
 620 typedef t_Error (t_IpcMsgHandler)(t_Handle  h_Module,
 621                                   uint8_t   *p_Msg,
 622                                   uint32_t  msgLength,
 623                                   uint8_t   *p_Reply,
 624                                   uint32_t  *p_ReplyLength);
 625
 626 /**************************************************************************//**
 627  @Function      XX_IpcRegisterMsgHandler
 628
 629  @Description   IPC mailbox registration.
 630
 631                 This function is used for registering an IPC message handler in the IPC service.
 632                 This function is called by each destination endpoint to indicate that it is ready
 633                 to handle incoming messages. The IPC service invokes the message handler upon receiving
 634                 a message addressed to the specified destination endpoint.
 635
 636  @Param[in]     addr                - The address name string associated with the destination endpoint;
 637                                       This address must be unique across the IPC service domain to ensure
 638                                       correct message routing.
 639  @Param[in]     f_MsgHandler        - Pointer to the message handler callback for processing incoming
 640                                       message; invoked by the IPC service upon receiving a message
 641                                       addressed to the destination endpoint specified by the addr
 642                                       parameter.
 643  @Param[in]     h_Module            - Abstract handle to the message handling module, passed unchanged
 644                                       to f_MsgHandler callback function.
 645  @Param[in]     replyLength         - The maximal data length (in bytes) of any reply that the specified message handler
 646                                       may generate; the IPC service provides the message handler with buffer
 647                                       for reply according to the length specified here (refer also to the description
 648                                       of #t_IpcMsgHandler callback function type);
 649                                       This size shall be zero if the message handler never generates replies.
 650
 651  @Return        E_OK on success; Error code otherwise.
 652 *//***************************************************************************/
 653 t_Error XX_IpcRegisterMsgHandler(char                   addr[XX_IPC_MAX_ADDR_NAME_LENGTH],
 654                                  t_IpcMsgHandler        *f_MsgHandler,
 655                                  t_Handle               h_Module,
 656                                  uint32_t               replyLength);
 657
 658 /**************************************************************************//**
 659  @Function      XX_IpcUnregisterMsgHandler
 660
 661  @Description   Release IPC mailbox routine.
 662
 663                  This function is used for unregistering an IPC message handler from the IPC service.
 664                  This function is called by each destination endpoint to indicate that it is no longer
 665                  capable of handling incoming messages.
 666
 667  @Param[in]     addr          - The address name string associated with the destination endpoint;
 668                                 This address is the same as was used when the message handler was
 669                                 registered via XX_IpcRegisterMsgHandler().
 670
 671  @Return        E_OK on success; Error code otherwise.
 672 *//***************************************************************************/
 673 t_Error XX_IpcUnregisterMsgHandler(char addr[XX_IPC_MAX_ADDR_NAME_LENGTH]);
 674
 675 /**************************************************************************//**
 676  @Function      XX_IpcInitSession
 677
 678  @Description   This function is used for creating an IPC session between the source endpoint
 679                 and the destination endpoint.
 680
 681                 The actual implementation and representation of a session is left for the IPC service.
 682                 The function returns an abstract handle to the created session. This handle shall be used
 683                 by the source endpoint in subsequent calls to XX_IpcSendMessage().
 684                 The IPC service assumes that before this function is called, no messages are sent from
 685                 the specified source endpoint to the specified destination endpoint.
 686
 687                 The IPC service may use a connection-oriented approach or a connectionless approach (or both)
 688                 as described below.
 689
 690                 @par Connection-Oriented Approach
 691
 692                 The IPC service may implement a session in a connection-oriented approach -  when this function is called,
 693                 the IPC service should take the necessary steps to bring up a source-to-destination channel for messages
 694                 and a destination-to-source channel for replies. The returned handle should represent the internal
 695                 representation of these channels.
 696
 697                 @par Connectionless Approach
 698
 699                 The IPC service may implement a session in a connectionless approach -  when this function is called, the
 700                 IPC service should not perform any particular steps, but it must store the pair of source and destination
 701                 addresses in some session representation and return it as a handle. When XX_IpcSendMessage() shall be
 702                 called, the IPC service may use this handle to provide the necessary identifiers for routing the messages
 703                 through the connectionless medium.
 704
 705  @Param[in]     destAddr      - The address name string associated with the destination endpoint.
 706  @Param[in]     srcAddr       - The address name string associated with the source endpoint.
 707
 708  @Return        Abstract handle to the initialized session, or NULL on error.
 709 *//***************************************************************************/
 710 t_Handle XX_IpcInitSession(char destAddr[XX_IPC_MAX_ADDR_NAME_LENGTH],
 711                            char srcAddr[XX_IPC_MAX_ADDR_NAME_LENGTH]);
 712
 713 /**************************************************************************//**
 714  @Function      XX_IpcFreeSession
 715
 716  @Description   This function is used for terminating an existing IPC session between a source endpoint
 717                 and a destination endpoint.
 718
 719                 The IPC service assumes that after this function is called, no messages shall be sent from
 720                 the associated source endpoint to the associated destination endpoint.
 721
 722  @Param[in]     h_Session      - Abstract handle to the IPC session -  the same handle as was originally
 723                                  returned by the XX_IpcInitSession() function.
 724
 725  @Return        E_OK on success; Error code otherwise.
 726 *//***************************************************************************/
 727 t_Error XX_IpcFreeSession(t_Handle h_Session);
 728
 729 /**************************************************************************//**
 730  @Function      XX_IpcSendMessage
 731
 732  @Description   IPC message send routine.
 733
 734                 This function may be used by a source endpoint to send an IPC message to a destination
 735                 endpoint. The source endpoint cannot send a message to the destination endpoint without
 736                 first initiating a session with that destination endpoint via XX_IpcInitSession() routine.
 737
 738                 The source endpoint must provide the buffer pointer and length of the outgoing message.
 739                 Optionally, it may also provide a buffer for an expected reply. In the latter case, the
 740                 transaction is not considered complete by the IPC service until the reply has been received.
 741                 If the source endpoint does not provide a reply buffer, the transaction is considered
 742                 complete after the message has been sent. The source endpoint must keep the message (and
 743                 optional reply) buffers valid until the transaction is complete.
 744
 745                 @par Non-blocking mode
 746
 747                 The source endpoint may request a non-blocking send by providing a non-NULL pointer to a message
 748                 completion callback function (f_Completion). Upon completion of the IPC transaction (consisting of a
 749                 message and an optional reply), the IPC service invokes this callback routine to return the message
 750                 buffer to the sender and to provide the received reply, if requested.
 751
 752                 @par Blocking mode
 753
 754                 The source endpoint may request a blocking send by setting f_Completion to NULL. The function is
 755                 expected to block until the IPC transaction is complete -  either the reply has been received or (if no reply
 756                 was requested) the message has been sent.
 757
 758  @Param[in]     h_Session       - Abstract handle to the IPC session -  the same handle as was originally
 759                                   returned by the XX_IpcInitSession() function.
 760  @Param[in]     p_Msg           - Pointer to message buffer to send.
 761  @Param[in]     msgLength       - Length (in bytes) of actual data in the message buffer.
 762  @Param[in]     p_Reply         - Pointer to reply buffer -  if this buffer is not NULL, the IPC service
 763                                   fills this buffer with the received reply data;
 764                                   In blocking mode, the reply data must be valid when the function returns;
 765                                   In non-blocking mode, the reply data is valid when f_Completion is called;
 766                                   If this pointer is NULL, no reply is expected.
 767  @Param[in,out] p_ReplyLength   - Pointer to reply length, which has a dual role in this function:
 768                                   [In] specifies the maximal length (in bytes) of the reply buffer pointed by
 769                                   p_Reply, and
 770                                   [Out] in non-blocking mode this value is updated by the IPC service to the
 771                                   actual reply length (in bytes).
 772  @Param[in]     f_Completion    - Pointer to a completion callback to be used in non-blocking send mode;
 773                                   The completion callback is invoked by the IPC service upon
 774                                   completion of the IPC transaction (consisting of a message and an optional
 775                                   reply);
 776                                   If this pointer is NULL, the function is expected to block until the IPC
 777                                   transaction is complete.
 778  @Param[in]     h_Arg           - Abstract handle to the sending module; passed unchanged to the f_Completion
 779                                   callback function as the first argument.
 780
 781  @Return        E_OK on success; Error code otherwise.
 782 *//***************************************************************************/
 783 t_Error XX_IpcSendMessage(t_Handle           h_Session,
 784                           uint8_t            *p_Msg,
 785                           uint32_t           msgLength,
 786                           uint8_t            *p_Reply,
 787                           uint32_t           *p_ReplyLength,
 788                           t_IpcMsgCompletion *f_Completion,
 789                           t_Handle           h_Arg);
 790
 791
 792 /** @} */ /* end of xx_ipc group */
 793 /** @} */ /* end of xx_id group */
 794
 795
 796 void XX_PortalSetInfo(device_t dev);
 797 void XX_FmanFixIntr(int irq);
 798 #endif /* __XX_EXT_H */