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(uintptr_t 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(uintptr_t 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(uintptr_t 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(uintptr_t 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(uintptr_t 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(uintptr_t 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 #endif /* __XX_EXT_H */ 934