1296177Sjhibbits/* Copyright (c) 2008-2011 Freescale Semiconductor, Inc. 2296177Sjhibbits * All rights reserved. 3296177Sjhibbits * 4296177Sjhibbits * Redistribution and use in source and binary forms, with or without 5296177Sjhibbits * modification, are permitted provided that the following conditions are met: 6296177Sjhibbits * * Redistributions of source code must retain the above copyright 7296177Sjhibbits * notice, this list of conditions and the following disclaimer. 8296177Sjhibbits * * Redistributions in binary form must reproduce the above copyright 9296177Sjhibbits * notice, this list of conditions and the following disclaimer in the 10296177Sjhibbits * documentation and/or other materials provided with the distribution. 11296177Sjhibbits * * Neither the name of Freescale Semiconductor nor the 12296177Sjhibbits * names of its contributors may be used to endorse or promote products 13296177Sjhibbits * derived from this software without specific prior written permission. 14296177Sjhibbits * 15296177Sjhibbits * 16296177Sjhibbits * ALTERNATIVELY, this software may be distributed under the terms of the 17296177Sjhibbits * GNU General Public License ("GPL") as published by the Free Software 18296177Sjhibbits * Foundation, either version 2 of that License or (at your option) any 19296177Sjhibbits * later version. 20296177Sjhibbits * 21296177Sjhibbits * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY 22296177Sjhibbits * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 23296177Sjhibbits * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24296177Sjhibbits * DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY 25296177Sjhibbits * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 26296177Sjhibbits * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27296177Sjhibbits * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 28296177Sjhibbits * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29296177Sjhibbits * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30296177Sjhibbits * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31296177Sjhibbits */ 32296177Sjhibbits 33296177Sjhibbits/**************************************************************************//** 34296177Sjhibbits @File xx_ext.h 35296177Sjhibbits 36296177Sjhibbits @Description Prototypes, externals and typedefs for system-supplied 37296177Sjhibbits (external) routines 38296177Sjhibbits*//***************************************************************************/ 39296177Sjhibbits 40296177Sjhibbits#ifndef __XX_EXT_H 41296177Sjhibbits#define __XX_EXT_H 42296177Sjhibbits 43296177Sjhibbits#include "std_ext.h" 44296177Sjhibbits#include "part_ext.h" 45296177Sjhibbits 46296177Sjhibbits#if defined(__MWERKS__) && defined(OPTIMIZED_FOR_SPEED) 47296177Sjhibbits#include "xx_integration_ext.h" 48296177Sjhibbits#endif /* defined(__MWERKS__) && defined(OPTIMIZED_FOR_SPEED) */ 49296177Sjhibbits 50296177Sjhibbits 51296177Sjhibbits/**************************************************************************//** 52296177Sjhibbits @Group xx_id XX Interface (System call hooks) 53296177Sjhibbits 54296177Sjhibbits @Description Prototypes, externals and typedefs for system-supplied 55296177Sjhibbits (external) routines 56296177Sjhibbits 57296177Sjhibbits @{ 58296177Sjhibbits*//***************************************************************************/ 59296177Sjhibbits 60296177Sjhibbits#if (defined(REPORT_EVENTS) && (REPORT_EVENTS > 0)) 61296177Sjhibbits/**************************************************************************//** 62296177Sjhibbits @Function XX_EventById 63296177Sjhibbits 64296177Sjhibbits @Description Event reporting routine - executed only when REPORT_EVENTS=1. 65296177Sjhibbits 66296177Sjhibbits @Param[in] event - Event code (e_Event). 67296177Sjhibbits @Param[in] appId - Application identifier. 68296177Sjhibbits @Param[in] flags - Event flags. 69296177Sjhibbits @Param[in] msg - Event message. 70296177Sjhibbits 71296177Sjhibbits @Return None 72296177Sjhibbits*//***************************************************************************/ 73296177Sjhibbitsvoid XX_EventById(uint32_t event, t_Handle appId, uint16_t flags, char *msg); 74296177Sjhibbits 75296177Sjhibbits#else /* not REPORT_EVENTS */ 76296177Sjhibbits#define XX_EventById(event, appId, flags, msg) 77296177Sjhibbits#endif /* REPORT_EVENTS */ 78296177Sjhibbits 79296177Sjhibbits 80296177Sjhibbits#ifdef DEBUG_XX_MALLOC 81296177Sjhibbitsvoid * XX_MallocDebug(uint32_t size, char *fname, int line); 82296177Sjhibbits 83296177Sjhibbitsvoid * XX_MallocSmartDebug(uint32_t size, 84296177Sjhibbits int memPartitionId, 85296177Sjhibbits uint32_t alignment, 86296177Sjhibbits char *fname, 87296177Sjhibbits int line); 88296177Sjhibbits 89296177Sjhibbits#define XX_Malloc(sz) \ 90296177Sjhibbits XX_MallocDebug((sz), __FILE__, __LINE__) 91296177Sjhibbits 92296177Sjhibbits#define XX_MallocSmart(sz, memt, al) \ 93296177Sjhibbits XX_MallocSmartDebug((sz), (memt), (al), __FILE__, __LINE__) 94296177Sjhibbits 95296177Sjhibbits#else /* not DEBUG_XX_MALLOC */ 96296177Sjhibbits/**************************************************************************//** 97296177Sjhibbits @Function XX_Malloc 98296177Sjhibbits 99296177Sjhibbits @Description allocates contiguous block of memory. 100296177Sjhibbits 101296177Sjhibbits @Param[in] size - Number of bytes to allocate. 102296177Sjhibbits 103296177Sjhibbits @Return The address of the newly allocated block on success, NULL on failure. 104296177Sjhibbits*//***************************************************************************/ 105296177Sjhibbitsvoid * XX_Malloc(uint32_t size); 106296177Sjhibbits 107296177Sjhibbits/**************************************************************************//** 108296177Sjhibbits @Function XX_MallocSmartInit 109296177Sjhibbits 110296177Sjhibbits @Description Initializes SmartMalloc allocator. 111296177Sjhibbits 112296177Sjhibbits @Return E_OK on success, error code otherwise. 113296177Sjhibbits*//***************************************************************************/ 114296177Sjhibbitsint XX_MallocSmartInit(void); 115296177Sjhibbits 116296177Sjhibbits/**************************************************************************//** 117296177Sjhibbits @Function XX_MallocSmart 118296177Sjhibbits 119296177Sjhibbits @Description Allocates contiguous block of memory in a specified 120296177Sjhibbits alignment and from the specified segment. 121296177Sjhibbits 122296177Sjhibbits @Param[in] size - Number of bytes to allocate. 123296177Sjhibbits @Param[in] memPartitionId - Memory partition ID; The value zero must 124296177Sjhibbits be mapped to the default heap partition. 125296177Sjhibbits @Param[in] alignment - Required memory alignment (in bytes). 126296177Sjhibbits 127296177Sjhibbits @Return The address of the newly allocated block on success, NULL on failure. 128296177Sjhibbits*//***************************************************************************/ 129296177Sjhibbitsvoid * XX_MallocSmart(uint32_t size, int memPartitionId, uint32_t alignment); 130296177Sjhibbits#endif /* not DEBUG_XX_MALLOC */ 131296177Sjhibbits 132296177Sjhibbits/**************************************************************************//** 133296177Sjhibbits @Function XX_FreeSmart 134296177Sjhibbits 135296177Sjhibbits @Description Frees the memory block pointed to by "p". 136296177Sjhibbits Only for memory allocated by XX_MallocSmart 137296177Sjhibbits 138296177Sjhibbits @Param[in] p_Memory - pointer to the memory block. 139296177Sjhibbits 140296177Sjhibbits @Return None. 141296177Sjhibbits*//***************************************************************************/ 142296177Sjhibbitsvoid XX_FreeSmart(void *p_Memory); 143296177Sjhibbits 144296177Sjhibbits/**************************************************************************//** 145296177Sjhibbits @Function XX_Free 146296177Sjhibbits 147296177Sjhibbits @Description frees the memory block pointed to by "p". 148296177Sjhibbits 149296177Sjhibbits @Param[in] p_Memory - pointer to the memory block. 150296177Sjhibbits 151296177Sjhibbits @Return None. 152296177Sjhibbits*//***************************************************************************/ 153296177Sjhibbitsvoid XX_Free(void *p_Memory); 154296177Sjhibbits 155296177Sjhibbits#ifndef NCSW_LINUX 156296177Sjhibbits/**************************************************************************//** 157296177Sjhibbits @Function XX_GetMemPartitionBase 158296177Sjhibbits 159296177Sjhibbits @Description This routine gets the address of a memory segment according to 160296177Sjhibbits the memory type. 161296177Sjhibbits 162296177Sjhibbits @Param[in] memPartitionId - Memory partition ID; The value zero must 163296177Sjhibbits be mapped to the default heap partition. 164296177Sjhibbits 165296177Sjhibbits @Return The address of the required memory type. 166296177Sjhibbits*//***************************************************************************/ 167296177Sjhibbitsvoid * XX_GetMemPartitionBase(int memPartitionId); 168296177Sjhibbits#endif 169296177Sjhibbits 170296177Sjhibbits/**************************************************************************//** 171296177Sjhibbits @Function XX_Print 172296177Sjhibbits 173296177Sjhibbits @Description print a string. 174296177Sjhibbits 175296177Sjhibbits @Param[in] str - string to print. 176296177Sjhibbits 177296177Sjhibbits @Return None. 178296177Sjhibbits*//***************************************************************************/ 179296177Sjhibbitsvoid XX_Print(char *str, ...); 180296177Sjhibbits 181296177Sjhibbits/**************************************************************************//** 182296177Sjhibbits @Function XX_GetChar 183296177Sjhibbits 184296177Sjhibbits @Description Get character from console. 185296177Sjhibbits 186296177Sjhibbits @Return Character is returned on success. Zero is returned otherwise. 187296177Sjhibbits*//***************************************************************************/ 188296177Sjhibbitschar XX_GetChar(void); 189296177Sjhibbits 190296177Sjhibbits/**************************************************************************//** 191296177Sjhibbits @Function XX_PreallocAndBindIntr 192296177Sjhibbits 193296177Sjhibbits @Description Preallocate and optionally bind it to given CPU. 194296177Sjhibbits 195296177Sjhibbits @Param[in] irq - Interrupt ID (system-specific number). 196296177Sjhibbits @Param[in] cpu - CPU to bind to or -1 if iRQ should be unbound. 197296177Sjhibbits 198296177Sjhibbits @Return E_OK on success; error code otherwise.. 199296177Sjhibbits*//***************************************************************************/ 200296177Sjhibbitst_Error XX_PreallocAndBindIntr(int irq, unsigned int cpu); 201296177Sjhibbits 202296177Sjhibbits/**************************************************************************//** 203296177Sjhibbits @Function XX_DeallocIntr 204296177Sjhibbits 205296177Sjhibbits @Description Deallocate preallocated interupt. 206296177Sjhibbits 207296177Sjhibbits @Param[in] irq - Interrupt ID (system-specific number). 208296177Sjhibbits 209296177Sjhibbits @Return E_OK on success; error code otherwise.. 210296177Sjhibbits*//***************************************************************************/ 211296177Sjhibbitst_Error XX_DeallocIntr(int irq); 212296177Sjhibbits 213296177Sjhibbits/**************************************************************************//** 214296177Sjhibbits @Function XX_SetIntr 215296177Sjhibbits 216296177Sjhibbits @Description Set an interrupt service routine for a specific interrupt source. 217296177Sjhibbits 218296177Sjhibbits @Param[in] irq - Interrupt ID (system-specific number). 219296177Sjhibbits @Param[in] f_Isr - Callback routine that will be called when the interrupt occurs. 220296177Sjhibbits @Param[in] handle - The argument for the user callback routine. 221296177Sjhibbits 222296177Sjhibbits @Return E_OK on success; error code otherwise.. 223296177Sjhibbits*//***************************************************************************/ 224296177Sjhibbitst_Error XX_SetIntr(int irq, t_Isr *f_Isr, t_Handle handle); 225296177Sjhibbits 226296177Sjhibbits/**************************************************************************//** 227296177Sjhibbits @Function XX_FreeIntr 228296177Sjhibbits 229296177Sjhibbits @Description Free a specific interrupt and a specific callback routine. 230296177Sjhibbits 231296177Sjhibbits @Param[in] irq - Interrupt ID (system-specific number). 232296177Sjhibbits 233296177Sjhibbits @Return E_OK on success; error code otherwise.. 234296177Sjhibbits*//***************************************************************************/ 235296177Sjhibbitst_Error XX_FreeIntr(int irq); 236296177Sjhibbits 237296177Sjhibbits/**************************************************************************//** 238296177Sjhibbits @Function XX_EnableIntr 239296177Sjhibbits 240296177Sjhibbits @Description Enable a specific interrupt. 241296177Sjhibbits 242296177Sjhibbits @Param[in] irq - Interrupt ID (system-specific number). 243296177Sjhibbits 244296177Sjhibbits @Return E_OK on success; error code otherwise.. 245296177Sjhibbits*//***************************************************************************/ 246296177Sjhibbitst_Error XX_EnableIntr(int irq); 247296177Sjhibbits 248296177Sjhibbits/**************************************************************************//** 249296177Sjhibbits @Function XX_DisableIntr 250296177Sjhibbits 251296177Sjhibbits @Description Disable a specific interrupt. 252296177Sjhibbits 253296177Sjhibbits @Param[in] irq - Interrupt ID (system-specific number). 254296177Sjhibbits 255296177Sjhibbits @Return E_OK on success; error code otherwise.. 256296177Sjhibbits*//***************************************************************************/ 257296177Sjhibbitst_Error XX_DisableIntr(int irq); 258296177Sjhibbits 259296177Sjhibbits#if !(defined(__MWERKS__) && defined(OPTIMIZED_FOR_SPEED)) 260296177Sjhibbits/**************************************************************************//** 261296177Sjhibbits @Function XX_DisableAllIntr 262296177Sjhibbits 263296177Sjhibbits @Description Disable all interrupts by masking them at the CPU. 264296177Sjhibbits 265296177Sjhibbits @Return A value that represents the interrupts state before the 266296177Sjhibbits operation, and should be passed to the matching 267296177Sjhibbits XX_RestoreAllIntr() call. 268296177Sjhibbits*//***************************************************************************/ 269296177Sjhibbitsuint32_t XX_DisableAllIntr(void); 270296177Sjhibbits 271296177Sjhibbits/**************************************************************************//** 272296177Sjhibbits @Function XX_RestoreAllIntr 273296177Sjhibbits 274296177Sjhibbits @Description Restore previous state of interrupts level at the CPU. 275296177Sjhibbits 276296177Sjhibbits @Param[in] flags - A value that represents the interrupts state to restore, 277296177Sjhibbits as returned by the matching call for XX_DisableAllIntr(). 278296177Sjhibbits 279296177Sjhibbits @Return None. 280296177Sjhibbits*//***************************************************************************/ 281296177Sjhibbitsvoid XX_RestoreAllIntr(uint32_t flags); 282296177Sjhibbits#endif /* !(defined(__MWERKS__) && defined(OPTIMIZED_FOR_SPEED)) */ 283296177Sjhibbits 284296177Sjhibbits/**************************************************************************//** 285296177Sjhibbits @Function XX_Call 286296177Sjhibbits 287296177Sjhibbits @Description Call a service in another task. 288296177Sjhibbits 289296177Sjhibbits Activate the routine "f" via the queue identified by "IntrManagerId". The 290296177Sjhibbits parameter to "f" is Id - the handle of the destination object 291296177Sjhibbits 292296177Sjhibbits @Param[in] intrManagerId - Queue ID. 293296177Sjhibbits @Param[in] f - routine pointer. 294296177Sjhibbits @Param[in] Id - the parameter to be passed to f(). 295296177Sjhibbits @Param[in] h_App - Application handle. 296296177Sjhibbits @Param[in] flags - Unused, 297296177Sjhibbits 298296177Sjhibbits @Return E_OK is returned on success. E_FAIL is returned otherwise (usually an operating system level failure). 299296177Sjhibbits*//***************************************************************************/ 300296177Sjhibbitst_Error XX_Call( uint32_t intrManagerId, 301296177Sjhibbits t_Error (* f)(t_Handle), 302296177Sjhibbits t_Handle Id, 303296177Sjhibbits t_Handle h_App, 304296177Sjhibbits uint16_t flags ); 305296177Sjhibbits 306296177Sjhibbits/**************************************************************************//** 307296177Sjhibbits @Function XX_Exit 308296177Sjhibbits 309296177Sjhibbits @Description Stop execution and report status (where it is applicable) 310296177Sjhibbits 311296177Sjhibbits @Param[in] status - exit status 312296177Sjhibbits*//***************************************************************************/ 313296177Sjhibbitsvoid XX_Exit(int status); 314296177Sjhibbits 315296177Sjhibbits/*****************************************************************************/ 316296177Sjhibbits/* Tasklet Service Routines */ 317296177Sjhibbits/*****************************************************************************/ 318296177Sjhibbitstypedef t_Handle t_TaskletHandle; 319296177Sjhibbits 320296177Sjhibbits/**************************************************************************//** 321296177Sjhibbits @Function XX_InitTasklet 322296177Sjhibbits 323296177Sjhibbits @Description Create and initialize a tasklet object. 324296177Sjhibbits 325296177Sjhibbits @Param[in] routine - A routine to be ran as a tasklet. 326296177Sjhibbits @Param[in] data - An argument to pass to the tasklet. 327296177Sjhibbits 328296177Sjhibbits @Return Tasklet handle is returned on success. NULL is returned otherwise. 329296177Sjhibbits*//***************************************************************************/ 330296177Sjhibbitst_TaskletHandle XX_InitTasklet (void (*routine)(void *), void *data); 331296177Sjhibbits 332296177Sjhibbits/**************************************************************************//** 333296177Sjhibbits @Function XX_FreeTasklet 334296177Sjhibbits 335296177Sjhibbits @Description Free a tasklet object. 336296177Sjhibbits 337296177Sjhibbits @Param[in] h_Tasklet - A handle to a tasklet to be free. 338296177Sjhibbits 339296177Sjhibbits @Return None. 340296177Sjhibbits*//***************************************************************************/ 341296177Sjhibbitsvoid XX_FreeTasklet (t_TaskletHandle h_Tasklet); 342296177Sjhibbits 343296177Sjhibbits/**************************************************************************//** 344296177Sjhibbits @Function XX_ScheduleTask 345296177Sjhibbits 346296177Sjhibbits @Description Schedule a tasklet object. 347296177Sjhibbits 348296177Sjhibbits @Param[in] h_Tasklet - A handle to a tasklet to be scheduled. 349296177Sjhibbits @Param[in] immediate - Indicate whether to schedule this tasklet on 350296177Sjhibbits the immediate queue or on the delayed one. 351296177Sjhibbits 352296177Sjhibbits @Return 0 - on success. Error code - otherwise. 353296177Sjhibbits*//***************************************************************************/ 354296177Sjhibbitsint XX_ScheduleTask(t_TaskletHandle h_Tasklet, int immediate); 355296177Sjhibbits 356296177Sjhibbits/**************************************************************************//** 357296177Sjhibbits @Function XX_FlushScheduledTasks 358296177Sjhibbits 359296177Sjhibbits @Description Flush all tasks there are in the scheduled tasks queue. 360296177Sjhibbits 361296177Sjhibbits @Return None. 362296177Sjhibbits*//***************************************************************************/ 363296177Sjhibbitsvoid XX_FlushScheduledTasks(void); 364296177Sjhibbits 365296177Sjhibbits/**************************************************************************//** 366296177Sjhibbits @Function XX_TaskletIsQueued 367296177Sjhibbits 368296177Sjhibbits @Description Check if task is queued. 369296177Sjhibbits 370296177Sjhibbits @Param[in] h_Tasklet - A handle to a tasklet to be scheduled. 371296177Sjhibbits 372296177Sjhibbits @Return 1 - task is queued. 0 - otherwise. 373296177Sjhibbits*//***************************************************************************/ 374296177Sjhibbitsint XX_TaskletIsQueued(t_TaskletHandle h_Tasklet); 375296177Sjhibbits 376296177Sjhibbits/**************************************************************************//** 377296177Sjhibbits @Function XX_SetTaskletData 378296177Sjhibbits 379296177Sjhibbits @Description Set data to a scheduled task. Used to change data of already 380296177Sjhibbits scheduled task. 381296177Sjhibbits 382296177Sjhibbits @Param[in] h_Tasklet - A handle to a tasklet to be scheduled. 383296177Sjhibbits @Param[in] data - Data to be set. 384296177Sjhibbits*//***************************************************************************/ 385296177Sjhibbitsvoid XX_SetTaskletData(t_TaskletHandle h_Tasklet, t_Handle data); 386296177Sjhibbits 387296177Sjhibbits/**************************************************************************//** 388296177Sjhibbits @Function XX_GetTaskletData 389296177Sjhibbits 390296177Sjhibbits @Description Get the data of scheduled task. 391296177Sjhibbits 392296177Sjhibbits @Param[in] h_Tasklet - A handle to a tasklet to be scheduled. 393296177Sjhibbits 394296177Sjhibbits @Return handle to the data of the task. 395296177Sjhibbits*//***************************************************************************/ 396296177Sjhibbitst_Handle XX_GetTaskletData(t_TaskletHandle h_Tasklet); 397296177Sjhibbits 398296177Sjhibbits/**************************************************************************//** 399296177Sjhibbits @Function XX_BottomHalf 400296177Sjhibbits 401296177Sjhibbits @Description Bottom half implementation, invoked by the interrupt handler. 402296177Sjhibbits 403296177Sjhibbits This routine handles all bottom-half tasklets with interrupts 404296177Sjhibbits enabled. 405296177Sjhibbits 406296177Sjhibbits @Return None. 407296177Sjhibbits*//***************************************************************************/ 408296177Sjhibbitsvoid XX_BottomHalf(void); 409296177Sjhibbits 410296177Sjhibbits 411296177Sjhibbits/*****************************************************************************/ 412296177Sjhibbits/* Spinlock Service Routines */ 413296177Sjhibbits/*****************************************************************************/ 414296177Sjhibbits 415296177Sjhibbits/**************************************************************************//** 416296177Sjhibbits @Function XX_InitSpinlock 417296177Sjhibbits 418296177Sjhibbits @Description Creates a spinlock. 419296177Sjhibbits 420296177Sjhibbits @Return Spinlock handle is returned on success; NULL otherwise. 421296177Sjhibbits*//***************************************************************************/ 422296177Sjhibbitst_Handle XX_InitSpinlock(void); 423296177Sjhibbits 424296177Sjhibbits/**************************************************************************//** 425296177Sjhibbits @Function XX_FreeSpinlock 426296177Sjhibbits 427296177Sjhibbits @Description Frees the memory allocated for the spinlock creation. 428296177Sjhibbits 429296177Sjhibbits @Param[in] h_Spinlock - A handle to a spinlock. 430296177Sjhibbits 431296177Sjhibbits @Return None. 432296177Sjhibbits*//***************************************************************************/ 433296177Sjhibbitsvoid XX_FreeSpinlock(t_Handle h_Spinlock); 434296177Sjhibbits 435296177Sjhibbits/**************************************************************************//** 436296177Sjhibbits @Function XX_LockSpinlock 437296177Sjhibbits 438296177Sjhibbits @Description Locks a spinlock. 439296177Sjhibbits 440296177Sjhibbits @Param[in] h_Spinlock - A handle to a spinlock. 441296177Sjhibbits 442296177Sjhibbits @Return None. 443296177Sjhibbits*//***************************************************************************/ 444296177Sjhibbitsvoid XX_LockSpinlock(t_Handle h_Spinlock); 445296177Sjhibbits 446296177Sjhibbits/**************************************************************************//** 447296177Sjhibbits @Function XX_UnlockSpinlock 448296177Sjhibbits 449296177Sjhibbits @Description Unlocks a spinlock. 450296177Sjhibbits 451296177Sjhibbits @Param[in] h_Spinlock - A handle to a spinlock. 452296177Sjhibbits 453296177Sjhibbits @Return None. 454296177Sjhibbits*//***************************************************************************/ 455296177Sjhibbitsvoid XX_UnlockSpinlock(t_Handle h_Spinlock); 456296177Sjhibbits 457296177Sjhibbits/**************************************************************************//** 458296177Sjhibbits @Function XX_LockIntrSpinlock 459296177Sjhibbits 460296177Sjhibbits @Description Locks a spinlock (interrupt safe). 461296177Sjhibbits 462296177Sjhibbits @Param[in] h_Spinlock - A handle to a spinlock. 463296177Sjhibbits 464296177Sjhibbits @Return A value that represents the interrupts state before the 465296177Sjhibbits operation, and should be passed to the matching 466296177Sjhibbits XX_UnlockIntrSpinlock() call. 467296177Sjhibbits*//***************************************************************************/ 468296177Sjhibbitsuint32_t XX_LockIntrSpinlock(t_Handle h_Spinlock); 469296177Sjhibbits 470296177Sjhibbits/**************************************************************************//** 471296177Sjhibbits @Function XX_UnlockIntrSpinlock 472296177Sjhibbits 473296177Sjhibbits @Description Unlocks a spinlock (interrupt safe). 474296177Sjhibbits 475296177Sjhibbits @Param[in] h_Spinlock - A handle to a spinlock. 476296177Sjhibbits @Param[in] intrFlags - A value that represents the interrupts state to 477296177Sjhibbits restore, as returned by the matching call for 478296177Sjhibbits XX_LockIntrSpinlock(). 479296177Sjhibbits 480296177Sjhibbits @Return None. 481296177Sjhibbits*//***************************************************************************/ 482296177Sjhibbitsvoid XX_UnlockIntrSpinlock(t_Handle h_Spinlock, uint32_t intrFlags); 483296177Sjhibbits 484296177Sjhibbits 485296177Sjhibbits/*****************************************************************************/ 486296177Sjhibbits/* Timers Service Routines */ 487296177Sjhibbits/*****************************************************************************/ 488296177Sjhibbits 489296177Sjhibbits/**************************************************************************//** 490296177Sjhibbits @Function XX_CurrentTime 491296177Sjhibbits 492296177Sjhibbits @Description Returns current system time. 493296177Sjhibbits 494296177Sjhibbits @Return Current system time (in milliseconds). 495296177Sjhibbits*//***************************************************************************/ 496296177Sjhibbitsuint32_t XX_CurrentTime(void); 497296177Sjhibbits 498296177Sjhibbits/**************************************************************************//** 499296177Sjhibbits @Function XX_CreateTimer 500296177Sjhibbits 501296177Sjhibbits @Description Creates a timer. 502296177Sjhibbits 503296177Sjhibbits @Return Timer handle is returned on success; NULL otherwise. 504296177Sjhibbits*//***************************************************************************/ 505296177Sjhibbitst_Handle XX_CreateTimer(void); 506296177Sjhibbits 507296177Sjhibbits/**************************************************************************//** 508296177Sjhibbits @Function XX_FreeTimer 509296177Sjhibbits 510296177Sjhibbits @Description Frees the memory allocated for the timer creation. 511296177Sjhibbits 512296177Sjhibbits @Param[in] h_Timer - A handle to a timer. 513296177Sjhibbits 514296177Sjhibbits @Return None. 515296177Sjhibbits*//***************************************************************************/ 516296177Sjhibbitsvoid XX_FreeTimer(t_Handle h_Timer); 517296177Sjhibbits 518296177Sjhibbits/**************************************************************************//** 519296177Sjhibbits @Function XX_StartTimer 520296177Sjhibbits 521296177Sjhibbits @Description Starts a timer. 522296177Sjhibbits 523296177Sjhibbits The user can select to start the timer as periodic timer or as 524296177Sjhibbits one-shot timer. The user should provide a callback routine that 525296177Sjhibbits will be called when the timer expires. 526296177Sjhibbits 527296177Sjhibbits @Param[in] h_Timer - A handle to a timer. 528296177Sjhibbits @Param[in] msecs - Timer expiration period (in milliseconds). 529296177Sjhibbits @Param[in] periodic - TRUE for a periodic timer; 530296177Sjhibbits FALSE for a one-shot timer.. 531296177Sjhibbits @Param[in] f_TimerExpired - A callback routine to be called when the 532296177Sjhibbits timer expires. 533296177Sjhibbits @Param[in] h_Arg - The argument to pass in the timer-expired 534296177Sjhibbits callback routine. 535296177Sjhibbits 536296177Sjhibbits @Return None. 537296177Sjhibbits*//***************************************************************************/ 538296177Sjhibbitsvoid XX_StartTimer(t_Handle h_Timer, 539296177Sjhibbits uint32_t msecs, 540296177Sjhibbits bool periodic, 541296177Sjhibbits void (*f_TimerExpired)(t_Handle h_Arg), 542296177Sjhibbits t_Handle h_Arg); 543296177Sjhibbits 544296177Sjhibbits/**************************************************************************//** 545296177Sjhibbits @Function XX_StopTimer 546296177Sjhibbits 547296177Sjhibbits @Description Frees the memory allocated for the timer creation. 548296177Sjhibbits 549296177Sjhibbits @Param[in] h_Timer - A handle to a timer. 550296177Sjhibbits 551296177Sjhibbits @Return None. 552296177Sjhibbits*//***************************************************************************/ 553296177Sjhibbitsvoid XX_StopTimer(t_Handle h_Timer); 554296177Sjhibbits 555296177Sjhibbits/**************************************************************************//** 556296177Sjhibbits @Function XX_GetExpirationTime 557296177Sjhibbits 558296177Sjhibbits @Description Returns the time (in milliseconds) remaining until the 559296177Sjhibbits expiration of a timer. 560296177Sjhibbits 561296177Sjhibbits @Param[in] h_Timer - A handle to a timer. 562296177Sjhibbits 563296177Sjhibbits @Return The time left until the timer expires. 564296177Sjhibbits*//***************************************************************************/ 565296177Sjhibbitsuint32_t XX_GetExpirationTime(t_Handle h_Timer); 566296177Sjhibbits 567296177Sjhibbits/**************************************************************************//** 568296177Sjhibbits @Function XX_ModTimer 569296177Sjhibbits 570296177Sjhibbits @Description Updates the expiration time of a timer. 571296177Sjhibbits 572296177Sjhibbits This routine adds the given time to the current system time, 573296177Sjhibbits and sets this value as the new expiration time of the timer. 574296177Sjhibbits 575296177Sjhibbits @Param[in] h_Timer - A handle to a timer. 576296177Sjhibbits @Param[in] msecs - The new interval until timer expiration 577296177Sjhibbits (in milliseconds). 578296177Sjhibbits 579296177Sjhibbits @Return None. 580296177Sjhibbits*//***************************************************************************/ 581296177Sjhibbitsvoid XX_ModTimer(t_Handle h_Timer, uint32_t msecs); 582296177Sjhibbits 583296177Sjhibbits/**************************************************************************//** 584296177Sjhibbits @Function XX_TimerIsActive 585296177Sjhibbits 586296177Sjhibbits @Description Checks whether a timer is active (pending) or not. 587296177Sjhibbits 588296177Sjhibbits @Param[in] h_Timer - A handle to a timer. 589296177Sjhibbits 590296177Sjhibbits @Return 0 - the timer is inactive; Non-zero value - the timer is active; 591296177Sjhibbits*//***************************************************************************/ 592296177Sjhibbitsint XX_TimerIsActive(t_Handle h_Timer); 593296177Sjhibbits 594296177Sjhibbits/**************************************************************************//** 595296177Sjhibbits @Function XX_Sleep 596296177Sjhibbits 597296177Sjhibbits @Description Non-busy wait until the desired time (in milliseconds) has passed. 598296177Sjhibbits 599296177Sjhibbits @Param[in] msecs - The requested sleep time (in milliseconds). 600296177Sjhibbits 601296177Sjhibbits @Return None. 602296177Sjhibbits 603296177Sjhibbits @Cautions This routine enables interrupts during its wait time. 604296177Sjhibbits*//***************************************************************************/ 605296177Sjhibbitsuint32_t XX_Sleep(uint32_t msecs); 606296177Sjhibbits 607296177Sjhibbits/**************************************************************************//** 608296177Sjhibbits @Function XX_UDelay 609296177Sjhibbits 610296177Sjhibbits @Description Busy-wait until the desired time (in microseconds) has passed. 611296177Sjhibbits 612296177Sjhibbits @Param[in] usecs - The requested delay time (in microseconds). 613296177Sjhibbits 614296177Sjhibbits @Return None. 615296177Sjhibbits 616296177Sjhibbits @Cautions It is highly unrecommended to call this routine during interrupt 617296177Sjhibbits time, because the system time may not be updated properly during 618296177Sjhibbits the delay loop. The behavior of this routine during interrupt 619296177Sjhibbits time is unexpected. 620296177Sjhibbits*//***************************************************************************/ 621296177Sjhibbitsvoid XX_UDelay(uint32_t usecs); 622296177Sjhibbits 623296177Sjhibbits 624296177Sjhibbits/*****************************************************************************/ 625296177Sjhibbits/* Other Service Routines */ 626296177Sjhibbits/*****************************************************************************/ 627296177Sjhibbits 628296177Sjhibbits/**************************************************************************//** 629296177Sjhibbits @Function XX_PhysToVirt 630296177Sjhibbits 631296177Sjhibbits @Description Translates a physical address to the matching virtual address. 632296177Sjhibbits 633296177Sjhibbits @Param[in] addr - The physical address to translate. 634296177Sjhibbits 635296177Sjhibbits @Return Virtual address. 636296177Sjhibbits*//***************************************************************************/ 637296177Sjhibbitsvoid * XX_PhysToVirt(physAddress_t addr); 638296177Sjhibbits 639296177Sjhibbits/**************************************************************************//** 640296177Sjhibbits @Function XX_VirtToPhys 641296177Sjhibbits 642296177Sjhibbits @Description Translates a virtual address to the matching physical address. 643296177Sjhibbits 644296177Sjhibbits @Param[in] addr - The virtual address to translate. 645296177Sjhibbits 646296177Sjhibbits @Return Physical address. 647296177Sjhibbits*//***************************************************************************/ 648296177SjhibbitsphysAddress_t XX_VirtToPhys(void *addr); 649296177Sjhibbits 650296177Sjhibbits/**************************************************************************//** 651296177Sjhibbits @Function XX_PortalSetInfo 652296177Sjhibbits 653296177Sjhibbits @Description Save physical and virtual adresses of the portals. 654296177Sjhibbits 655296177Sjhibbits @Param[in] dev - Portals device - either bman or qman. 656296177Sjhibbits 657296177Sjhibbits @Return Physical, virtual addresses and size. 658296177Sjhibbits*//***************************************************************************/ 659296177Sjhibbitsvoid XX_PortalSetInfo(device_t dev); 660296177Sjhibbits 661296177Sjhibbits/**************************************************************************//** 662296177Sjhibbits @Function XX_FmanSetIntrInfo 663296177Sjhibbits 664296177Sjhibbits @Description Workaround for FMan interrupt, which must be binded to one CPU 665296177Sjhibbits only. 666296177Sjhibbits 667296177Sjhibbits @Param[in] irq - Interrupt number. 668296177Sjhibbits 669296177Sjhibbits @Return None. 670296177Sjhibbits*//***************************************************************************/ 671296177Sjhibbitsvoid XX_FmanFixIntr(int irq); 672296177Sjhibbits 673296177Sjhibbits/**************************************************************************//** 674296177Sjhibbits @Group xx_ipc XX Inter-Partition-Communication API 675296177Sjhibbits 676296177Sjhibbits @Description The following API is to be used when working with multiple 677296177Sjhibbits partitions configuration. 678296177Sjhibbits 679296177Sjhibbits @{ 680296177Sjhibbits*//***************************************************************************/ 681296177Sjhibbits 682296177Sjhibbits#define XX_IPC_MAX_ADDR_NAME_LENGTH 16 /**< Maximum length of an endpoint name string; 683296177Sjhibbits The IPC service can use this constant to limit 684296177Sjhibbits the storage space for IPC endpoint names. */ 685296177Sjhibbits 686296177Sjhibbits 687296177Sjhibbits/**************************************************************************//** 688296177Sjhibbits @Function t_IpcMsgCompletion 689296177Sjhibbits 690296177Sjhibbits @Description Callback function used upon IPC non-blocking transaction completion 691296177Sjhibbits to return message buffer to the caller and to forward reply if available. 692296177Sjhibbits 693296177Sjhibbits This callback function may be attached by the source endpoint to any outgoing 694296177Sjhibbits IPC message to indicate a non-blocking send (see also XX_IpcSendMessage() routine). 695296177Sjhibbits Upon completion of an IPC transaction (consisting of a message and an optional reply), 696296177Sjhibbits the IPC service invokes this callback routine to return the message buffer to the sender 697296177Sjhibbits and to provide the received reply, if requested. 698296177Sjhibbits 699296177Sjhibbits User provides this function. Driver invokes it. 700296177Sjhibbits 701296177Sjhibbits @Param[in] h_Module - Abstract handle to the sending module - the same handle as was passed 702296177Sjhibbits in the XX_IpcSendMessage() function; This handle is typically used to point 703296177Sjhibbits to the internal data structure of the source endpoint. 704296177Sjhibbits @Param[in] p_Msg - Pointer to original (sent) message buffer; 705296177Sjhibbits The source endpoint can free (or reuse) this buffer when message 706296177Sjhibbits completion callback is called. 707296177Sjhibbits @Param[in] p_Reply - Pointer to (received) reply buffer; 708296177Sjhibbits This pointer is the same as was provided by the source endpoint in 709296177Sjhibbits XX_IpcSendMessage(). 710296177Sjhibbits @Param[in] replyLength - Length (in bytes) of actual data in the reply buffer. 711296177Sjhibbits @Param[in] status - Completion status - E_OK or failure indication, e.g. IPC transaction completion 712296177Sjhibbits timeout. 713296177Sjhibbits 714296177Sjhibbits @Return None 715296177Sjhibbits *//***************************************************************************/ 716296177Sjhibbitstypedef void (t_IpcMsgCompletion)(t_Handle h_Module, 717296177Sjhibbits uint8_t *p_Msg, 718296177Sjhibbits uint8_t *p_Reply, 719296177Sjhibbits uint32_t replyLength, 720296177Sjhibbits t_Error status); 721296177Sjhibbits 722296177Sjhibbits/**************************************************************************//** 723296177Sjhibbits @Function t_IpcMsgHandler 724296177Sjhibbits 725296177Sjhibbits @Description Callback function used as IPC message handler. 726296177Sjhibbits 727296177Sjhibbits The IPC service invokes message handlers for each IPC message received. 728296177Sjhibbits The actual function pointer should be registered by each destination endpoint 729296177Sjhibbits via the XX_IpcRegisterMsgHandler() routine. 730296177Sjhibbits 731296177Sjhibbits User provides this function. Driver invokes it. 732296177Sjhibbits 733296177Sjhibbits @Param[in] h_Module - Abstract handle to the message handling module - the same handle as 734296177Sjhibbits was passed in the XX_IpcRegisterMsgHandler() function; this handle is 735296177Sjhibbits typically used to point to the internal data structure of the destination 736296177Sjhibbits endpoint. 737296177Sjhibbits @Param[in] p_Msg - Pointer to message buffer with data received from peer. 738296177Sjhibbits @Param[in] msgLength - Length (in bytes) of message data. 739296177Sjhibbits @Param[in] p_Reply - Pointer to reply buffer, to be filled by the message handler and then sent 740296177Sjhibbits by the IPC service; 741296177Sjhibbits The reply buffer is allocated by the IPC service with size equals to the 742296177Sjhibbits replyLength parameter provided in message handler registration (see 743296177Sjhibbits XX_IpcRegisterMsgHandler() function); 744296177Sjhibbits If replyLength was initially specified as zero during message handler registration, 745296177Sjhibbits the IPC service may set this pointer to NULL and assume that a reply is not needed; 746296177Sjhibbits The IPC service is also responsible for freeing the reply buffer after the 747296177Sjhibbits reply has been sent or dismissed. 748296177Sjhibbits @Param[in,out] p_ReplyLength - Pointer to reply length, which has a dual role in this function: 749296177Sjhibbits [In] equals the replyLength parameter provided in message handler 750296177Sjhibbits registration (see XX_IpcRegisterMsgHandler() function), and 751296177Sjhibbits [Out] should be updated by message handler to the actual reply length; if 752296177Sjhibbits this value is set to zero, the IPC service must assume that a reply should 753296177Sjhibbits not be sent; 754296177Sjhibbits Note: If p_Reply is not NULL, p_ReplyLength must not be NULL as well. 755296177Sjhibbits 756296177Sjhibbits @Return E_OK on success; Error code otherwise. 757296177Sjhibbits *//***************************************************************************/ 758296177Sjhibbitstypedef t_Error (t_IpcMsgHandler)(t_Handle h_Module, 759296177Sjhibbits uint8_t *p_Msg, 760296177Sjhibbits uint32_t msgLength, 761296177Sjhibbits uint8_t *p_Reply, 762296177Sjhibbits uint32_t *p_ReplyLength); 763296177Sjhibbits 764296177Sjhibbits/**************************************************************************//** 765296177Sjhibbits @Function XX_IpcRegisterMsgHandler 766296177Sjhibbits 767296177Sjhibbits @Description IPC mailbox registration. 768296177Sjhibbits 769296177Sjhibbits This function is used for registering an IPC message handler in the IPC service. 770296177Sjhibbits This function is called by each destination endpoint to indicate that it is ready 771296177Sjhibbits to handle incoming messages. The IPC service invokes the message handler upon receiving 772296177Sjhibbits a message addressed to the specified destination endpoint. 773296177Sjhibbits 774296177Sjhibbits @Param[in] addr - The address name string associated with the destination endpoint; 775296177Sjhibbits This address must be unique across the IPC service domain to ensure 776296177Sjhibbits correct message routing. 777296177Sjhibbits @Param[in] f_MsgHandler - Pointer to the message handler callback for processing incoming 778296177Sjhibbits message; invoked by the IPC service upon receiving a message 779296177Sjhibbits addressed to the destination endpoint specified by the addr 780296177Sjhibbits parameter. 781296177Sjhibbits @Param[in] h_Module - Abstract handle to the message handling module, passed unchanged 782296177Sjhibbits to f_MsgHandler callback function. 783296177Sjhibbits @Param[in] replyLength - The maximal data length (in bytes) of any reply that the specified message handler 784296177Sjhibbits may generate; the IPC service provides the message handler with buffer 785296177Sjhibbits for reply according to the length specified here (refer also to the description 786296177Sjhibbits of #t_IpcMsgHandler callback function type); 787296177Sjhibbits This size shall be zero if the message handler never generates replies. 788296177Sjhibbits 789296177Sjhibbits @Return E_OK on success; Error code otherwise. 790296177Sjhibbits*//***************************************************************************/ 791296177Sjhibbitst_Error XX_IpcRegisterMsgHandler(char addr[XX_IPC_MAX_ADDR_NAME_LENGTH], 792296177Sjhibbits t_IpcMsgHandler *f_MsgHandler, 793296177Sjhibbits t_Handle h_Module, 794296177Sjhibbits uint32_t replyLength); 795296177Sjhibbits 796296177Sjhibbits/**************************************************************************//** 797296177Sjhibbits @Function XX_IpcUnregisterMsgHandler 798296177Sjhibbits 799296177Sjhibbits @Description Release IPC mailbox routine. 800296177Sjhibbits 801296177Sjhibbits This function is used for unregistering an IPC message handler from the IPC service. 802296177Sjhibbits This function is called by each destination endpoint to indicate that it is no longer 803296177Sjhibbits capable of handling incoming messages. 804296177Sjhibbits 805296177Sjhibbits @Param[in] addr - The address name string associated with the destination endpoint; 806296177Sjhibbits This address is the same as was used when the message handler was 807296177Sjhibbits registered via XX_IpcRegisterMsgHandler(). 808296177Sjhibbits 809296177Sjhibbits @Return E_OK on success; Error code otherwise. 810296177Sjhibbits*//***************************************************************************/ 811296177Sjhibbitst_Error XX_IpcUnregisterMsgHandler(char addr[XX_IPC_MAX_ADDR_NAME_LENGTH]); 812296177Sjhibbits 813296177Sjhibbits/**************************************************************************//** 814296177Sjhibbits @Function XX_IpcInitSession 815296177Sjhibbits 816296177Sjhibbits @Description This function is used for creating an IPC session between the source endpoint 817296177Sjhibbits and the destination endpoint. 818296177Sjhibbits 819296177Sjhibbits The actual implementation and representation of a session is left for the IPC service. 820296177Sjhibbits The function returns an abstract handle to the created session. This handle shall be used 821296177Sjhibbits by the source endpoint in subsequent calls to XX_IpcSendMessage(). 822296177Sjhibbits The IPC service assumes that before this function is called, no messages are sent from 823296177Sjhibbits the specified source endpoint to the specified destination endpoint. 824296177Sjhibbits 825296177Sjhibbits The IPC service may use a connection-oriented approach or a connectionless approach (or both) 826296177Sjhibbits as described below. 827296177Sjhibbits 828296177Sjhibbits @par Connection-Oriented Approach 829296177Sjhibbits 830296177Sjhibbits The IPC service may implement a session in a connection-oriented approach - when this function is called, 831296177Sjhibbits the IPC service should take the necessary steps to bring up a source-to-destination channel for messages 832296177Sjhibbits and a destination-to-source channel for replies. The returned handle should represent the internal 833296177Sjhibbits representation of these channels. 834296177Sjhibbits 835296177Sjhibbits @par Connectionless Approach 836296177Sjhibbits 837296177Sjhibbits The IPC service may implement a session in a connectionless approach - when this function is called, the 838296177Sjhibbits IPC service should not perform any particular steps, but it must store the pair of source and destination 839296177Sjhibbits addresses in some session representation and return it as a handle. When XX_IpcSendMessage() shall be 840296177Sjhibbits called, the IPC service may use this handle to provide the necessary identifiers for routing the messages 841296177Sjhibbits through the connectionless medium. 842296177Sjhibbits 843296177Sjhibbits @Param[in] destAddr - The address name string associated with the destination endpoint. 844296177Sjhibbits @Param[in] srcAddr - The address name string associated with the source endpoint. 845296177Sjhibbits 846296177Sjhibbits @Return Abstract handle to the initialized session, or NULL on error. 847296177Sjhibbits*//***************************************************************************/ 848296177Sjhibbitst_Handle XX_IpcInitSession(char destAddr[XX_IPC_MAX_ADDR_NAME_LENGTH], 849296177Sjhibbits char srcAddr[XX_IPC_MAX_ADDR_NAME_LENGTH]); 850296177Sjhibbits 851296177Sjhibbits/**************************************************************************//** 852296177Sjhibbits @Function XX_IpcFreeSession 853296177Sjhibbits 854296177Sjhibbits @Description This function is used for terminating an existing IPC session between a source endpoint 855296177Sjhibbits and a destination endpoint. 856296177Sjhibbits 857296177Sjhibbits The IPC service assumes that after this function is called, no messages shall be sent from 858296177Sjhibbits the associated source endpoint to the associated destination endpoint. 859296177Sjhibbits 860296177Sjhibbits @Param[in] h_Session - Abstract handle to the IPC session - the same handle as was originally 861296177Sjhibbits returned by the XX_IpcInitSession() function. 862296177Sjhibbits 863296177Sjhibbits @Return E_OK on success; Error code otherwise. 864296177Sjhibbits*//***************************************************************************/ 865296177Sjhibbitst_Error XX_IpcFreeSession(t_Handle h_Session); 866296177Sjhibbits 867296177Sjhibbits/**************************************************************************//** 868296177Sjhibbits @Function XX_IpcSendMessage 869296177Sjhibbits 870296177Sjhibbits @Description IPC message send routine. 871296177Sjhibbits 872296177Sjhibbits This function may be used by a source endpoint to send an IPC message to a destination 873296177Sjhibbits endpoint. The source endpoint cannot send a message to the destination endpoint without 874296177Sjhibbits first initiating a session with that destination endpoint via XX_IpcInitSession() routine. 875296177Sjhibbits 876296177Sjhibbits The source endpoint must provide the buffer pointer and length of the outgoing message. 877296177Sjhibbits Optionally, it may also provide a buffer for an expected reply. In the latter case, the 878296177Sjhibbits transaction is not considered complete by the IPC service until the reply has been received. 879296177Sjhibbits If the source endpoint does not provide a reply buffer, the transaction is considered 880296177Sjhibbits complete after the message has been sent. The source endpoint must keep the message (and 881296177Sjhibbits optional reply) buffers valid until the transaction is complete. 882296177Sjhibbits 883296177Sjhibbits @par Non-blocking mode 884296177Sjhibbits 885296177Sjhibbits The source endpoint may request a non-blocking send by providing a non-NULL pointer to a message 886296177Sjhibbits completion callback function (f_Completion). Upon completion of the IPC transaction (consisting of a 887296177Sjhibbits message and an optional reply), the IPC service invokes this callback routine to return the message 888296177Sjhibbits buffer to the sender and to provide the received reply, if requested. 889296177Sjhibbits 890296177Sjhibbits @par Blocking mode 891296177Sjhibbits 892296177Sjhibbits The source endpoint may request a blocking send by setting f_Completion to NULL. The function is 893296177Sjhibbits expected to block until the IPC transaction is complete - either the reply has been received or (if no reply 894296177Sjhibbits was requested) the message has been sent. 895296177Sjhibbits 896296177Sjhibbits @Param[in] h_Session - Abstract handle to the IPC session - the same handle as was originally 897296177Sjhibbits returned by the XX_IpcInitSession() function. 898296177Sjhibbits @Param[in] p_Msg - Pointer to message buffer to send. 899296177Sjhibbits @Param[in] msgLength - Length (in bytes) of actual data in the message buffer. 900296177Sjhibbits @Param[in] p_Reply - Pointer to reply buffer - if this buffer is not NULL, the IPC service 901296177Sjhibbits fills this buffer with the received reply data; 902296177Sjhibbits In blocking mode, the reply data must be valid when the function returns; 903296177Sjhibbits In non-blocking mode, the reply data is valid when f_Completion is called; 904296177Sjhibbits If this pointer is NULL, no reply is expected. 905296177Sjhibbits @Param[in,out] p_ReplyLength - Pointer to reply length, which has a dual role in this function: 906296177Sjhibbits [In] specifies the maximal length (in bytes) of the reply buffer pointed by 907296177Sjhibbits p_Reply, and 908296177Sjhibbits [Out] in non-blocking mode this value is updated by the IPC service to the 909296177Sjhibbits actual reply length (in bytes). 910296177Sjhibbits @Param[in] f_Completion - Pointer to a completion callback to be used in non-blocking send mode; 911296177Sjhibbits The completion callback is invoked by the IPC service upon 912296177Sjhibbits completion of the IPC transaction (consisting of a message and an optional 913296177Sjhibbits reply); 914296177Sjhibbits If this pointer is NULL, the function is expected to block until the IPC 915296177Sjhibbits transaction is complete. 916296177Sjhibbits @Param[in] h_Arg - Abstract handle to the sending module; passed unchanged to the f_Completion 917296177Sjhibbits callback function as the first argument. 918296177Sjhibbits 919296177Sjhibbits @Return E_OK on success; Error code otherwise. 920296177Sjhibbits*//***************************************************************************/ 921296177Sjhibbitst_Error XX_IpcSendMessage(t_Handle h_Session, 922296177Sjhibbits uint8_t *p_Msg, 923296177Sjhibbits uint32_t msgLength, 924296177Sjhibbits uint8_t *p_Reply, 925296177Sjhibbits uint32_t *p_ReplyLength, 926296177Sjhibbits t_IpcMsgCompletion *f_Completion, 927296177Sjhibbits t_Handle h_Arg); 928296177Sjhibbits 929296177Sjhibbits 930296177Sjhibbits/** @} */ /* end of xx_ipc group */ 931296177Sjhibbits/** @} */ /* end of xx_id group */ 932296177Sjhibbits 933296177Sjhibbits/** FreeBSD Specific additions. */ 934296177Sjhibbitsvoid XX_TrackInit(void); 935296177Sjhibbitsvoid XX_TrackAddress(void *addr); 936296177Sjhibbitsvoid XX_UntrackAddress(void *addr); 937296177Sjhibbits 938296177Sjhibbits#endif /* __XX_EXT_H */ 939