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(device_t dev, 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 #endif /* __XX_EXT_H */ 798