00001 /** 00002 * @file FrameQ.h 00003 * 00004 * @brief Defines for interfaces for FrameQ module. 00005 * 00006 * 00007 * 00008 * @ver 02.00.00.68_beta1 00009 * 00010 * ============================================================================ 00011 * 00012 * Copyright (c) 2008-2009, Texas Instruments Incorporated 00013 * 00014 * Redistribution and use in source and binary forms, with or without 00015 * modification, are permitted provided that the following conditions 00016 * are met: 00017 * 00018 * * Redistributions of source code must retain the above copyright 00019 * notice, this list of conditions and the following disclaimer. 00020 * 00021 * * Redistributions in binary form must reproduce the above copyright 00022 * notice, this list of conditions and the following disclaimer in the 00023 * documentation and/or other materials provided with the distribution. 00024 * 00025 * * Neither the name of Texas Instruments Incorporated nor the names of 00026 * its contributors may be used to endorse or promote products derived 00027 * from this software without specific prior written permission. 00028 * 00029 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 00030 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 00031 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 00032 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 00033 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00034 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 00035 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 00036 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 00037 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 00038 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 00039 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00040 * Contact information for paper mail: 00041 * Texas Instruments 00042 * Post Office Box 655303 00043 * Dallas, Texas 75265 00044 * Contact information: 00045 * http://www-k.ext.ti.com/sc/technical-support/product-information-centers.htm? 00046 * DCMP=TIHomeTracking&HQS=Other+OT+home_d_contact 00047 * ============================================================================ 00048 * 00049 */ 00050 00051 #ifndef FRAMEQ_H_0x6e6f 00052 #define FRAMEQ_H_0x6e6f 00053 00054 #include <ti/syslink/FrameQDefs.h> 00055 #include <ti/syslink/SysLink.h> 00056 #include <ti/ipc/Notify.h> 00057 00058 #if defined (__cplusplus) 00059 extern "C" { 00060 #endif 00061 00062 /* ============================================================================= 00063 * All success and failure codes for the module 00064 * ============================================================================= 00065 */ 00066 /*! 00067 * @brief Indicates module has been already destroyed. 00068 */ 00069 #define FrameQ_S_ALREADYDESTROYED 2 00070 00071 /*! 00072 * @brief Indicates module is already setup. 00073 */ 00074 #define FrameQ_S_ALREADYSETUP 1 00075 00076 /*! 00077 * @brief Operation successful. 00078 */ 00079 #define FrameQ_S_SUCCESS 0 00080 00081 /*! 00082 * @brief General Failure 00083 */ 00084 #define FrameQ_E_FAIL -1 00085 00086 /*! 00087 * @brief Argument passed to function is invalid. 00088 */ 00089 #define FrameQ_E_INVALIDARG -2 00090 00091 /*! 00092 * @brief FrameQ instance not found. 00093 */ 00094 #define FrameQ_E_NOTFOUND -3 00095 00096 /*! 00097 * @brief FrameQ instance already exists. 00098 */ 00099 #define FrameQ_E_INST_EXISTS -4 00100 00101 /*! 00102 * @brief Writer client already exists. 00103 */ 00104 #define FrameQ_E_WRITER_EXISTS -5 00105 00106 /*! 00107 * @brief Failed to allocate frame header. 00108 */ 00109 #define FrameQ_E_ALLOC_FRAME -6 00110 00111 /*! 00112 * @brief Failed to allocate frame buffers. 00113 */ 00114 #define FrameQ_E_ALLOC_FRAMEBUF -7 00115 00116 /*! 00117 * @brief Memory_alloc failed. 00118 */ 00119 #define FrameQ_E_MEMORY -8 00120 00121 /*! 00122 * @brief FrameQ is empty. Can not return frame. 00123 */ 00124 #define FrameQ_E_EMPTY -9 00125 00126 /*! 00127 * @brief Name server create failed for the module. 00128 */ 00129 #define FrameQ_E_CREATE_NAMESERVER -10 00130 00131 /*! 00132 * @brief GateMP instance create failed. 00133 */ 00134 #define FrameQ_E_CREATE_GATEMP -11 00135 00136 /*! 00137 * @brief GateMP instance open failed. 00138 */ 00139 #define FrameQ_E_OPEN_GATEMP -12 00140 00141 /*! 00142 * @brief Failed to create Client NotifyMgr instance. 00143 */ 00144 #define FrameQ_E_FAIL_CLIENTN0TIFYMGR_CREATE -13 00145 00146 /*! 00147 * @brief Failed to open Client NotifyMgr instance. 00148 */ 00149 #define FrameQ_E_FAIL_CLIENTN0TIFYMGR_OPEN -14 00150 00151 /*! 00152 * @brief Max limit of readers for a FrameQ is reached. 00153 */ 00154 #define FrameQ_E_MAX_READERS -15 00155 00156 /*! 00157 * @brief Operation can not be permitted or not implemented. 00158 */ 00159 #define FrameQ_E_ACCESSDENIED -16 00160 00161 /*! 00162 * @brief Module is not initialized. 00163 */ 00164 #define FrameQ_E_INVALIDSTATE -17 00165 00166 /*! 00167 * @brief Failure in OS call. 00168 */ 00169 #define FrameQ_E_OSFAILURE -18 00170 00171 /*! 00172 * @brief Adding FrameQ entry to name server instance failed. 00173 */ 00174 #define FrameQ_E_FAIL_NAMESERVERADD -19 00175 00176 /*! 00177 * @brief Unsupported interface type. 00178 */ 00179 #define FrameQ_E_INVALID_INTERFACE -20 00180 00181 /*! 00182 * @brief Called API is not implemented. 00183 */ 00184 #define FrameQ_E_NOTIMPLEMENTED -21 00185 00186 /*! 00187 * @brief NameServer open failed. 00188 */ 00189 #define FrameQ_E_OPEN_NAMESERVER -22 00190 00191 /*! 00192 * @brief Invalid FrameQbufMgr id. 00193 */ 00194 #define FrameQ_E_INVALID_FRAMEQBUFMGRID -23 00195 00196 /*! 00197 * @brief Reader client get this error in getv call if it is not able to get 00198 * all the requested frames. API is able to get only few frames. 00199 */ 00200 #define FrameQ_E_INSUFFICENT_FRAMES -24 00201 00202 /*! 00203 * @brief Failed to allocate memory. 00204 */ 00205 #define FrameQ_E_ALLOC_MEMORY -25 00206 00207 /*! 00208 * @brief Failed to open FrameQBufMgr. 00209 */ 00210 #define FrameQ_E_FRAMEQBUFMGROPEN -26 00211 00212 /*! 00213 * @brief Failed to open ListMP instance. 00214 */ 00215 #define FrameQ_E_LISTMPOPEN -27 00216 00217 /*! 00218 * @brief Failed to register with the clientNotifyMgr. 00219 */ 00220 #define FrameQ_E_CLIENTNOTIFYMGRREGCLIENT -28 00221 00222 /*! 00223 * @brief Failed to register with the FrameQBufMgr. 00224 */ 00225 #define FrameQ_E_FRAMEQBUFMGRREGCLIENT -29 00226 00227 /*! 00228 * @brief Failed to unregister with the clientNotifyMgr.. 00229 */ 00230 #define FrameQ_E_CLIENTNOTIFYMGRUNREGCLIENT -30 00231 00232 /*! 00233 * @brief Failed to unregister with the FrameQBufMgr. 00234 */ 00235 #define FrameQ_E_FRAMEQBUFMGRUNREGCLIENT -31 00236 00237 /*! 00238 * @brief Call back function is already registered. 00239 */ 00240 #define FrameQ_E_ALREADYREGISTERED -32 00241 00242 /*! 00243 * @brief NameServer_add failed. 00244 */ 00245 #define FrameQ_E_NAMESERVERADD -33 00246 00247 /* ============================================================================= 00248 * macros & defines 00249 * ============================================================================= 00250 */ 00251 #define FrameQ_FrameBufInfo Frame_FrameBufInfo 00252 00253 /*! 00254 * @brief Defines the frame header structure 00255 */ 00256 #define FrameQ_FrameHeader Frame_FrameHeader 00257 00258 /*! 00259 * @brief Defines the type for a frame pointer 00260 */ 00261 typedef Frame_FrameHeader * FrameQ_Frame; 00262 00263 /*! 00264 * @brief Maximum length of the name string in bytes. 00265 */ 00266 #define FrameQ_MAX_NAMELEN (32u) 00267 00268 /*! 00269 * @brief Max filled queues for a reader client of the FrameQ instance. 00270 */ 00271 #define FrameQ_MAXFILLEDQUEUS_FOR_READER (16) 00272 00273 /*! 00274 * @brief Maximum number of reader clients supported by the instance. 00275 */ 00276 #define FrameQ_MAX_INST_READERS (2u) 00277 00278 00279 /*! 00280 * @brief Maximum number of instances managed by FrameQ. 00281 */ 00282 #define FrameQ_MAX_INSTANCES (64u) 00283 00284 /*! 00285 * @brief Notify Event Number to be used by FrameQ module. 00286 */ 00287 #define FrameQ_NOTIFY_RESERVED_EVENTNO (1u) 00288 00289 /* ============================================================================= 00290 * Structures & Enums 00291 * ============================================================================= 00292 */ 00293 00294 /*! 00295 * @brief Handle for the FrameQ instance. 00296 */ 00297 typedef struct FrameQ_Object * FrameQ_Handle; 00298 00299 /*! 00300 * @brief Prototype of the FrameQ call back function. 00301 */ 00302 typedef void (* FrameQ_NotifyFunc) (FrameQ_Handle, Ptr arg, UInt32); 00303 00304 /*! 00305 * @brief Enumerates the notification types for FrameQ. 00306 */ 00307 typedef enum FrameQ_NotifyType_Tag { 00308 FrameQ_NOTIFICATION_NONE = SysLink_NOTIFICATION_NONE, 00309 /*!< No notification is required. */ 00310 FrameQ_NOTIFICATION_ALWAYS = SysLink_NOTIFICATION_ALWAYS, 00311 /*!< Notify whenever the other client sends data/frees up space.*/ 00312 FrameQ_NOTIFICATION_ONCE = SysLink_NOTIFICATION_ONCE, 00313 /*!< Notify when the other side sends data/frees up space. Once the 00314 * notification is done, the notification is disabled until it is 00315 * enabled again. 00316 */ 00317 FrameQ_NOTIFICATION_HDWRFIFO_ALWAYS = 00318 SysLink_NOTIFICATION_HDWRFIFO_ALWAYS, 00319 /*!< Notify whenever the other side sends data/frees up space. 00320 * This notification is never disabled. 00321 */ 00322 FrameQ_NOTIFICATION_HDWRFIFO_ONCE = 00323 SysLink_NOTIFICATION_HDWRFIFO_ONCE 00324 /*!< Notify when the other side sends data/frees up space. Once the 00325 * notification is done, the notification is disabled until it is 00326 * enabled again. The notification is enabled once the watermark 00327 * is crossed and does not require buffer to get full/empty. 00328 */ 00329 } FrameQ_NotifyType; 00330 00331 /*! 00332 * @brief Enumerations to indicate FrameQ open modes. 00333 */ 00334 typedef enum FrameQ_OpenMode_Tag { 00335 FrameQ_MODE_NONE, 00336 /*!< Mode is not reader/writer.Apps should not use this as open mode */ 00337 FrameQ_MODE_WRITER, 00338 /*!< FrameQ mode is writer. */ 00339 FrameQ_MODE_READER 00340 /*!< FrameQ mode is reader.*/ 00341 } FrameQ_OpenMode; 00342 00343 /*! 00344 * @brief Enumeration of CPU access flags for frame buffers. For frame headers 00345 * CPUACCESS is assumed to be TRUE.. 00346 */ 00347 typedef enum FrameQ_CpuAccessFlags_Tag { 00348 FrameQ_FRAMEBUF0_CPUACCESS = 0x10000, 00349 /*!< If specified first frame buffer is accessed through CPU 00350 * (direct memory access). 00351 */ 00352 FrameQ_FRAMEBUF1_CPUACCESS = 0x20000, 00353 /*!< If specified second frame buffer is accessed through CPU 00354 * (direct memory access). 00355 */ 00356 FrameQ_FRAMEBUF2_CPUACCESS = 0x40000, 00357 /*!< If specified third frame buffer is accessed through CPU 00358 * (direct memory access). 00359 */ 00360 FrameQ_FRAMEBUF3_CPUACCESS = 0x80000, 00361 /*!< If specified fourth frame buffer is accessed through CPU 00362 * (direct memory access). 00363 */ 00364 FrameQ_FRAMEBUF4_CPUACCESS = 0x100000, 00365 /*!< If specified fifth frame buffer is accessed through CPU 00366 * (direct memory access). 00367 */ 00368 FrameQ_FRAMEBUF5_CPUACCESS = 0x200000, 00369 /*!< If specified sixth frame buffer is accessed through CPU 00370 * (direct memory access). 00371 */ 00372 FrameQ_FRAMEBUF6_CPUACCESS = 0x400000, 00373 /*!< If specified seventh frame buffer is accessed through CPU 00374 * (direct memory access). 00375 */ 00376 FrameQ_FRAMEBUF7_CPUACCESS = 0x800000 00377 /*!< If specified eighth frame buffer is accessed through CPU 00378 * (direct memory access). 00379 */ 00380 } FrameQ_CpuAccessFlags; 00381 00382 /*! 00383 * @brief Enumeration of FrameQ interface types.Denotes different 00384 * implementation types. 00385 */ 00386 typedef enum FrameQ_Interface_Tag { 00387 FrameQ_INTERFACE_SHAREDMEM = 0x0, 00388 /*!< Denotes FrameQ implementation (FrameQ_ShMem 00389 * Implementation) on shared memory. 00390 */ 00391 FrameQ_INTERFACE_NONE = 0x1 00392 } FrameQ_Interface; 00393 00394 /*! 00395 * @brief Common parameters required to create FrameQ instance of 00396 * any implementation. It should be the first element of the actual 00397 * implementaton params structure . 00398 */ 00399 typedef struct FrameQ_CreateParams_Tag { 00400 UInt32 size; 00401 /*!< Size of the paramstructure */ 00402 FrameQ_Interface ctrlInterfaceType; 00403 /*!< Interface type */ 00404 String name; 00405 /*!< Name of the instance */ 00406 Bool openFlag; 00407 /* Open flag to indicate create/open. internal flag. Caller should not 00408 * touch this flag during create 00409 */ 00410 } FrameQ_CreateParams; 00411 00412 /*! 00413 * @brief Common parameters required to open a FrameQ instance of 00414 * any implementation. 00415 */ 00416 typedef struct FrameQ_CommonOpenParams_Tag { 00417 String name; 00418 /*!< Name of the instance to open */ 00419 Ptr sharedAddr; 00420 /*!< Virtual shared Region addr in case open by address is required.*/ 00421 UInt32 openMode; 00422 /*!< Mode of the client. */ 00423 UInt32 cpuAccessFlags; 00424 /*!< cpuAccessFlags flags to know if app is going to access frame buffers 00425 * through CPU. 00426 */ 00427 } FrameQ_CommonOpenParams; 00428 00429 /*! 00430 * @brief Common parameters required to create FrameQ instance of 00431 * any implementation. It should be the first element of the actual 00432 * implementaton params structure . 00433 */ 00434 typedef struct FrameQ_Params { 00435 FrameQ_CreateParams commonCreateParams; 00436 Ptr impParams; 00437 /*!< 00438 * Pointer to implementation specific parameters 00439 */ 00440 00441 UInt32 impParamsSize; 00442 /*!< 00443 * Size of the implementation specific structure pointed by impParams. 00444 */ 00445 } FrameQ_Params; 00446 00447 /*! 00448 * @brief Structure defining notification parameter structure. 00449 */ 00450 typedef struct FrameQ_NotifyParams_Tag { 00451 FrameQ_NotifyType notifyType; 00452 /*!< Notification type*/ 00453 UInt32 watermark; 00454 /*!< Minumum number of free frames required to generate notification 00455 * Same water mark for all the individual freeFramePools in the set. 00456 */ 00457 FrameQ_NotifyFunc cbFxnPtr; 00458 /*!< Cacll back function*/ 00459 Ptr cbContext; 00460 /*!< Context pointer that needs to be passed to call back function.*/ 00461 Ptr cbClientHandle; 00462 /*!< Handle that needs to be passed as first arg to call back. 00463 * Ideally this should be callers client handle.*/ 00464 } FrameQ_NotifyParams; 00465 00466 /* ============================================================================= 00467 * APIs 00468 * ============================================================================= 00469 */ 00470 /*! 00471 * @brief Function to know whether the give ctrlInterfaceType is supported. 00472 * 00473 * This function returns TRUE if the interface provide is supported 00474 * other wise returns FALSE. 00475 * 00476 * @param type type of interface see enum FrameQ_Interface for 00477 * details. 00478 * 00479 * @retval TRUE Given interface is supported. 00480 * @retval FALSE Given interface is no supported. 00481 * 00482 * @sa Enum FrameQ_Interface. 00483 */ 00484 Int32 FrameQ_isSupportedInterface(UInt32 type); 00485 00486 /*! 00487 * @brief Creates a new instance of FrameQ . 00488 * 00489 * This function create a new instance of FrameQ. It creates a 00490 * frameQ based on the params specific to implementations. 00491 * 00492 * @param params pointer to implementation specific params. 00493 * 00494 * @retval Handle Instance handle. 00495 * @retval NULL Create failed. 00496 * 00497 * @sa FrameQ_Shmem_params.FrameQ_delete(), FrameQ_open() and 00498 * FrameQ_close. 00499 */ 00500 FrameQ_Handle 00501 FrameQ_create (Ptr params); 00502 00503 /*! 00504 * @brief Function to delete an instance of FrameQ. 00505 * 00506 * This function delets FrameQ instance that created. 00507 * 00508 * @param pHandle Pointer to the created frameQ instance handle. 00509 * 00510 * @retval FrameQ_S_SUCCESS Delete successful. 00511 * @retval FrameQ_E_FAIL Delete failed. 00512 * @retval FrameQ_E_INVALIDARG Poiinter to Handle passed is null. 00513 * @retval FrameQ_E_INVALIDARG Handle passed is null. 00514 * 00515 * @sa FrameQ_create(), FrameQ_open() and FrameQ_close. 00516 */ 00517 Int32 00518 FrameQ_delete (FrameQ_Handle *pHandle); 00519 00520 /*! 00521 * @brief Function to open the created FrameQ instance.. 00522 * 00523 * This function opens the FrameQ instance in reader or writer 00524 * mode depending upon the open params passed to it. 00525 * 00526 * @param openParams Pointer to implementation specific open params. 00527 * @param handlePtr Return parameter.Instance opened in given mode. 00528 * 00529 * @retval FrameQ_S_SUCCESS open successful. 00530 * @retval FrameQ_E_INVALIDARG Invalid parameter specified. 00531 * @retval FrameQ_E_INVALIDSTATE Module is not initialized. 00532 * @retval FrameQ_E_MEMORY Memory_alloc failed. 00533 * @retval FrameQ_E_ALLOC_MEMORY Memory_alloc failed. 00534 * @retval FrameQ_E_FRAMEQBUFMGROPEN FrameQBufMge instance open failed. 00535 * @retval FrameQ_E_OPEN_GATEMP GateMP open failed. 00536 * @retval FrameQ_E_FAIL_CLIENTN0TIFYMGR_OPEN ClientNotifyMgr open failed. 00537 * @retval FrameQ_E_LISTMPOPEN Internal ListMP instance open failed. 00538 * @retval FrameQ_E_NOTFOUND Instance not found in FrameQ Nameserver. 00539 * 00540 * @sa FrameQ_ShMem_openParams, FrameQ_create(), FrameQ_delete() and 00541 * FrameQ_close. 00542 */ 00543 Int32 00544 FrameQ_open (Ptr openParams,FrameQ_Handle *handlePtr); 00545 00546 /*! 00547 * @brief Function to open the created FrameQ instance if shared address 00548 * is known. 00549 * 00550 * This function opens the FrameQ instance in reader or writer 00551 * mode depending upon the open params passed to it. Apps should 00552 * pass the valid shared addr of the created instance. 00553 * 00554 * @param openParams Pointer to implementation specific open params. 00555 * @param handlePtr Return parameter.Instance opened in given mode. 00556 * 00557 * @retval FrameQ_S_SUCCESS open successful. 00558 * @retval FrameQ_E_INVALIDARG Invalid parameter specified. 00559 * @retval FrameQ_E_INVALIDSTATE Module is not initialized. 00560 * @retval FrameQ_E_MEMORY Memory_alloc failed. 00561 * @retval FrameQ_E_ALLOC_MEMORY Memory_alloc failed. 00562 * @retval FrameQ_E_FRAMEQBUFMGROPEN FrameQBufMge instance open failed. 00563 * @retval FrameQ_E_OPEN_GATEMP GateMP open failed. 00564 * @retval FrameQ_E_FAIL_CLIENTN0TIFYMGR_OPEN ClientNotifyMgr open failed. 00565 * @retval FrameQ_E_LISTMPOPEN Internal ListMP instance open failed. 00566 * @retval FrameQ_E_NOTFOUND Instance not found in FrameQ Nameserver. 00567 * 00568 * @sa FrameQ_ShMem_openParams, FrameQ_create(), FrameQ_delete() and 00569 * FrameQ_close. 00570 */ 00571 Int32 00572 FrameQ_openByAddr(FrameQ_Handle *handlePtr, Ptr openParams); 00573 00574 /*! 00575 * @brief Function to close the opened FrameQ instance. 00576 * 00577 * This function closes FrameQ instance that is opened. 00578 * 00579 * @param pHandle Pointer to the opened frameQ instance handle. 00580 * 00581 * @retval FrameQ_S_SUCCESS Close successful. 00582 * @retval FrameQ_E_FAIL Close failed. 00583 * @retval FrameQ_E_INVALIDARG Poiinter to Handle passed is null. 00584 * @retval FrameQ_E_INVALIDARG Handle passed is null. 00585 * 00586 * @sa FrameQ_create(), FrameQ_open() and FrameQ_delete. 00587 */ 00588 Int32 00589 FrameQ_close (FrameQ_Handle* pHandle); 00590 00591 /*! 00592 * @brief Function to allocate frame. 00593 * 00594 * This function allocates a frame when called by FrameQ writer. 00595 * This API internally makes a call to configured FrameQbufMgr to 00596 * allocate a free frame. 00597 * 00598 * @param handle FrameQ writer handle. 00599 * @param framePtr Location to receive the allocated frame. 00600 * 00601 * @retval FrameQ_S_SUCCESS Successfully allocated frame. 00602 * @retval FrameQ_E_FAIL Internal FrameQBufMgr_alloc failed. 00603 * @retval FrameQ_E_INVALIDARG framePtr paased is null. 00604 * @retval FrameQ_E_INVALIDARG handle passed is null. 00605 * @retval FrameQ_E_ACCESSDENIED Provided handle can not allocate frames. 00606 * Only writer can allocate frames. 00607 * 00608 * @sa FrameQ_open(), FrameQ_free(), FrameQ_put() and FrameQ_get(). 00609 */ 00610 Int32 00611 FrameQ_alloc (FrameQ_Handle handle, FrameQ_Frame *framePtr); 00612 00613 /*! 00614 * @brief Function to allocate multiple frames. 00615 * 00616 * This function allocates frames from multiple free pools of 00617 * plugged in FrameQBufMgr.After API returns, numframes will 00618 * denotes the number of successfully allocated frames.The max size 00619 * of framePtr and freeQId array is defined by 00620 * macro FrameQ_MAX_FRAMESINVAPI. 00621 * 00622 * @param handle FrameQ writer handle. 00623 * @param framePtr Array to receive pointers to allocated frames. 00624 * @param freeQId Array of free frame pool nos of the plugged in 00625 * FrameQBufMgrfrom from which this API needs to 00626 * allocate frames actual size of that is allocated. 00627 * @param numFrames Number of frames that needs to be allocated. 00628 * 00629 * @retval FrameQ_S_SUCCESS Successfully allocated frames. 00630 * @retval FrameQ_E_FAIL Internal FrameQBufMgr_allocv failed. 00631 * @retval FrameQ_E_INVALIDARG framePtr passed is null. 00632 * @retval FrameQ_E_INVALIDARG handle passed is null. 00633 * @retval FrameQ_E_INVALIDARG freeQId passed is null. 00634 * @retval FrameQ_E_INVALIDARG numFrames passed is null. 00635 * @retval FrameQ_E_ACCESSDENIED Provided handle can not allocate frames. 00636 * Only writer can allocate frames. 00637 * Only writer can allocate frames. 00638 * 00639 * @sa FrameQ_open(), FrameQ_freev(), FrameQ_putv() and FrameQ_getv(). 00640 */ 00641 Int32 00642 FrameQ_allocv ( FrameQ_Handle handle, 00643 FrameQ_Frame framePtr[], 00644 UInt32 freeQId[], 00645 UInt8 *numFrames); 00646 00647 /*! 00648 * @brief Function to free frame. 00649 * 00650 * This function frees a frame when called by FrameQ writer or 00651 * reader. This API internally makes a call to configured 00652 * FrameQbufMgr to free the frame. 00653 * 00654 * @param handle Opened FrameQ instance handle. 00655 * @param frame Frame to be freed. 00656 * 00657 * @retval FrameQ_S_SUCCESS Successfully freed frame. 00658 * @retval FrameQ_E_FAIL Internal FrameQBufMgr_free failed. 00659 * @retval FrameQ_E_INVALIDARG frame passed is null. 00660 * @retval FrameQ_E_INVALIDARG handle passed is null. 00661 * @retval FrameQ_E_ACCESSDENIED Provided handle can not free frames. 00662 * Only writer or reader can free frames. 00663 * 00664 * @sa FrameQ_open(), FrameQ_alloc(), FrameQ_put() and FrameQ_get(). 00665 */ 00666 Int32 00667 FrameQ_free (FrameQ_Handle handle, FrameQ_Frame frame); 00668 00669 /*! 00670 * @brief Function to free multiple frames. 00671 * 00672 * This function frees multiple frames when called by 00673 * FrameQ writer or writer. This API internally makes a call to configured 00674 * FrameQbufMgr to free frames. 00675 * 00676 * @param handle Opened FrameQ instance handle. 00677 * @param framePtr Array of frames to be freed. 00678 * @param numFrames Number of Frames to be freed. 00679 * 00680 * @retval FrameQ_S_SUCCESS Successfully freed frames. 00681 * @retval FrameQ_E_FAIL Internal FrameQBufMgr_freev failed. 00682 * @retval FrameQ_E_INVALIDARG frame passed is null. 00683 * @retval FrameQ_E_INVALIDARG handle passed is null. 00684 * @retval FrameQ_E_ACCESSDENIED Provided handle can not free frames. 00685 * Only writer or reader can free frames. 00686 * 00687 * @sa FrameQ_open(), FrameQ_allocv(), FrameQ_putv() and FrameQ_getv(). 00688 */ 00689 Int32 00690 FrameQ_freev (FrameQ_Handle handle, 00691 FrameQ_Frame framePtr[], 00692 UInt32 numFrames); 00693 00694 /*! 00695 * @brief Function to insert frame in to FrameQ instance. 00696 * 00697 * This function inserts frame in to FrameQ. It inserts frame in to 00698 * filled frame queue 0 of FrameQ reader clients. 00699 * If multiple readers exist, 00700 * 1.FrameQ inserts the original gien frame into first reader's 00701 * queue 0. 00702 * 2.FrameQ duplicates the original frame and inserts duplicated 00703 * frames in to rest of the reader's queue 0. 00704 * 00705 * @param handle Opened FrameQ instance handle. 00706 * @param frame Frame to be inserted. 00707 * 00708 * @retval FrameQ_S_SUCCESS Successfully freed frames. 00709 * @retval FrameQ_E_FAIL Failed to put frame. 00710 * @retval FrameQ_E_INVALIDARG frame passed is null. 00711 * @retval FrameQ_E_INVALIDARG handle passed is null. 00712 * @retval FrameQ_E_ACCESSDENIED Provided handle can not free frames. 00713 * Only writer or reader can put frames. 00714 * 00715 * @sa FrameQ_get(). 00716 */ 00717 Int32 00718 FrameQ_put (FrameQ_Handle handle, FrameQ_Frame frame); 00719 00720 /*! 00721 * @brief Function to insert multiple frames in to queues of a 00722 * FrameQ reader client. 00723 * 00724 * If multiple readers exist, It dups the given 00725 * frames and inserts in to other readers' queues.The Size of 00726 * framePtr and filledQueueId should be atleast equal to numFrames. 00727 * The max size of framePtr and filledQueueId array is defined by 00728 * macro FrameQ_MAX_FRAMESINVAPI. 00729 * 00730 * @param handle Instance handle. 00731 * @param framePtr Array of frames to be inserted. 00732 * @param filledQueueId Array of filled queues of reader. 00733 * @param numFrames Number of frames. 00734 * 00735 * @retval FrameQ_S_SUCCESS Successfully inserted frames. 00736 * @retval FrameQ_E_FAIL Failed to put frames. 00737 * @retval FrameQ_E_INVALIDARG handle passed is null. 00738 * @retval FrameQ_E_INVALIDARG framePtr passed is null. 00739 * @retval FrameQ_E_INVALIDARG filledQueueId passed is null. 00740 * @retval FrameQ_E_ACCESSDENIED Provided handle can not put frames. 00741 * Only writer or reader can put frames. 00742 * 00743 * @sa FrameQ_getv(). 00744 */ 00745 Int32 00746 FrameQ_putv (FrameQ_Handle handle, 00747 FrameQ_Frame framePtr[], 00748 UInt32 filledQueueId[], 00749 UInt8 numFrames); 00750 00751 /*! 00752 * @brief Function to retrieve frame from FrameQ instance by reader client. 00753 * 00754 * This Function retrieves frame from the queue 0 of caller client. 00755 * Only readers are allowed to call this API. 00756 * 00757 * @param handle Instance handle. 00758 * @param framePtr Location to receive frame. 00759 * 00760 * @retval FrameQ_S_SUCCESS Successfully retrieved frame. 00761 * @retval FrameQ_E_FAIL Failed to get frame. 00762 * @retval FrameQ_E_INVALIDARG handle passed is null. 00763 * @retval FrameQ_E_INVALIDARG framePtr passed is null. 00764 * @retval FrameQ_E_ACCESSDENIED Provided handle can not retrieve frame. 00765 * Only reader client can retrieve frame. 00766 * 00767 * @sa FrameQ_put(). 00768 * 00769 * 00770 */ 00771 Int32 00772 FrameQ_get (FrameQ_Handle handle, FrameQ_Frame *framePtr); 00773 00774 /*! 00775 * @brief Function to retrieve frames from the given queues of a reader 00776 * client. 00777 * 00778 * This Function retrieves frames from the queues of caller client. 00779 * Only readers are allowed to call this API.It returns frames if 00780 * all the required frames are available in the FrameQ.The Size of 00781 * pframe and filledQueueId should be atleast equal to numFrames. 00782 * The max size of framePtr and filledQueueId array is defined by 00783 * macro FrameQ_MAX_FRAMESINVAPI. 00784 * 00785 * @param handle Instance handle. 00786 * @param pframe Location to receive frames the queues specified 00787 * in filledQueueId array argument. 00788 * @param filledQueueId Array of queue ids from which frames. 00789 * @param numFrames Denotes number of frames that needs to retrieved 00790 * from the filled Queues ids specified by 00791 * filledQueueId. The Size of pframe and 00792 * filledQueueId should be atleast equal to number 00793 * of frames specified in numFrames value can be max 00794 * FrameQ_MAX_FRAMESINVAPI. 00795 * 00796 * @retval FrameQ_S_SUCCESS Successfully retrieved frames. 00797 * @retval FrameQ_E_FAIL Failed to get frames. 00798 * @retval FrameQ_E_INVALIDARG handle passed is null. 00799 * @retval FrameQ_E_INVALIDARG pframe passed is null. 00800 * @retval FrameQ_E_INVALIDARG filledQueueId passed is null. 00801 * @retval FrameQ_E_INVALIDARG numFrames passed is null. 00802 * @retval FrameQ_E_ACCESSDENIED Provided handle can not retrieve frames. 00803 * Only reader client can retrieve frames. 00804 * 00805 * @sa FrameQ_putv(). 00806 * 00807 * 00808 */ 00809 Int32 00810 FrameQ_getv (FrameQ_Handle handle, 00811 FrameQ_Frame pframe[], 00812 UInt32 filledQueueId[], 00813 UInt8 *numFrames); 00814 00815 /*! 00816 * @brief Function to duplicate the given frame. 00817 * 00818 * This Function duplicates the given frame.It allocates one frame 00819 * header buffer and copies the header information given in 00820 * original frame and returns it. 00821 * 00822 * @param handle Instance handle. 00823 * @param frame frame to be duplicated. 00824 * @param dupedFrame Location to receive the duplicated frame. 00825 * 00826 * @retval FrameQ_S_SUCCESS Successfully retrieved frames. 00827 * @retval FrameQ_E_FAIL Failed to get frames. 00828 * @retval FrameQ_E_INVALIDARG handle passed is null. 00829 * @retval FrameQ_E_INVALIDARG frame passed is null. 00830 * @retval FrameQ_E_INVALIDARG dupedFrame passed is null. 00831 * @retval FrameQ_E_ACCESSDENIED Provided handle can not dup frames. 00832 * Only writer/reader client can dup frame. 00833 * 00834 * @sa FrameQ_alloc(). 00835 * 00836 * 00837 */ 00838 Int32 00839 FrameQ_dup (FrameQ_Handle handle, 00840 FrameQ_Frame frame, 00841 FrameQ_Frame* dupedFrame); 00842 00843 /*! 00844 * @brief API to register a call back function. 00845 * 00846 * For reader : 00847 * It registers notification function to notify about available 00848 * frames in the FrameQ. 00849 * For writer : 00850 * It registers notification function to notify about available 00851 * free frames in the Plugged in FrameQBufMgr. 00852 * 00853 * @param handle Instance handle. 00854 * @param notifyParams Pointer to notifyParams. 00855 * 00856 * @retval FrameQ_S_SUCCESS Operation successful. 00857 * @retval FrameQ_E_INVALIDARG handle passed is null. 00858 * @retval FrameQ_E_INVALIDARG notifyParams passed is null. 00859 * @retval FrameQ_E_INVALIDSTATE Module is not initialized. 00860 * @retval FrameQ_E_FAIL Failed to register notification. 00861 * 00862 * @sa FrameQ_unregisterNotifier 00863 */ 00864 00865 Int32 00866 FrameQ_registerNotifier ( FrameQ_Handle handle, 00867 FrameQ_NotifyParams *notifyParams); 00868 00869 /*! 00870 * @brief Function to un register call back function. 00871 * 00872 * 00873 * @param handle Reader/writer client Handle. 00874 * 00875 * @retval FrameQ_S_SUCCESS Successfully duped frame. 00876 * @retval FrameQ_E_INVALIDARG handle passed is null. 00877 * @retval FrameQ_E_INVALIDARG notifyParams passed is null. 00878 * @retval FrameQ_E_INVALIDSTATE Module is not initialized. 00879 * @retval FrameQ_E_FAIL Failed to register notification. 00880 * 00881 * @sa FrameQ_registerNotifier 00882 */ 00883 Int32 00884 FrameQ_unregisterNotifier (FrameQ_Handle handle); 00885 00886 /*! 00887 * @brief Function to send forced notification to the reader clients. 00888 * 00889 * 00890 * @param handle writer client Handle. 00891 * @param msg payload that needs to be send to reader. 00892 * 00893 * @retval FrameQ_S_SUCCESS Successfully sent notification. 00894 * @retval FrameQ_E_INVALIDARG handle passed is null. 00895 * @retval FrameQ_E_INVALIDSTATE Module is not initialized. 00896 * @retval FrameQ_E_FAIL Failed to send notification. 00897 * @retval FrameQ_E_ACCESSDENIED handle is not a writer handle.can not send 00898 * notification. 00899 * 00900 * @sa FrameQ_registerNotifier 00901 */ 00902 Int32 00903 FrameQ_sendNotify (FrameQ_Handle handle, UInt16 msg); 00904 00905 /*! 00906 * @brief Function to find out the number of available frames in a FrameQ . 00907 * 00908 * For Writer: 00909 * It returns the number of frames in the primary reader's filled 00910 * queue 0. 00911 * For Reader: 00912 * It returns the number of frames in the Reader's(caller)filledqueue 0. 00913 * 00914 * @param handle Reader client Handle. 00915 * @param numFrames Location to recieve the number of frames. 00916 * 00917 * @retval FrameQ_S_SUCCESS Operation successful. 00918 * @retval FrameQ_E_FAIL API failed. 00919 * 00920 * @sa 00921 */ 00922 Int32 00923 FrameQ_getNumFrames(FrameQ_Handle handle, UInt32 *numFrames); 00924 00925 /*! 00926 * @brief Function to find out the number of available frames in a FrameQ . 00927 * 00928 * For Reader this function is to get the available frames from 00929 * the queues associated with it. 00930 * For writer this function is to get the available frames from 00931 * the queues associated with the primary Reader(first reader). 00932 * 00933 * @param handle Writer/Reader client handle. 00934 * @param numFrames Location to recieve the number of frames. 00935 * @param filledQId Array of filled queues. 00936 * @param numFilledQids Number of queues specified in filledQId array. 00937 * 00938 * @retval FrameQ_S_SUCCESS Operation successful. 00939 * @retval FrameQ_E_FAIL API failed. 00940 * 00941 * @sa 00942 */ 00943 Int32 00944 FrameQ_getvNumFrames (FrameQ_Handle handle, 00945 UInt32 numFrames[], 00946 UInt8 filledQId[], 00947 UInt8 numFilledQids); 00948 00949 /*! 00950 * @brief Function to get the number of free frames. 00951 * 00952 * Function to get the number of free frames available in the 00953 * plugged in FrameQbufMgr's FreeFramePool 0 The returned number 00954 * free frames may not exist in the frameQbufMgr after this call. 00955 * This is because if allocs can be done by the other FrameQ 00956 * writers on the same FrameQBufMgr.If frames are freed by other frameQ 00957 * writers then the free Frames would be even more than the value that 00958 * this API returns. 00959 * 00960 * @param handle Instance handle. 00961 * @param numFreeFrames out parameter that denotes the number of free 00962 * frames available 00963 * 00964 * @retval FrameQ_S_SUCCESS Operation successful. 00965 * @retval FrameQ_E_FAIL API failed. 00966 * 00967 * @sa 00968 */ 00969 Int32 00970 FrameQ_getNumFreeFrames (FrameQ_Handle handle, UInt32* numFreeFrames) ; 00971 00972 /*! 00973 * @brief Function to get the number of free frames. 00974 * 00975 * Function to get the number of free frames available in the 00976 * plugged in FrameQbufMgr's FreeFramePools The returned number 00977 * free frames may not exist in the frameQbufMgr after this call. 00978 * This is because if allocs can be done by the other FrameQ 00979 * writers on the same FrameQBufMgr.If frames are freed by other frameQ 00980 * writers then the free Frames would be even more than the value that 00981 * this API returns. 00982 * 00983 * @param handle Instance handle. 00984 * @param numFreeFrames out parameter that denotes the number of free 00985 * frames available 00986 * @param freeQId Array of free queues. 00987 * @param numFreeQids Number of queues specified in freeQId array. 00988 * 00989 * @retval FrameQ_S_SUCCESS Operation successful. 00990 * @retval FrameQ_E_FAIL API failed. 00991 * 00992 * @sa 00993 */ 00994 Int32 00995 FrameQ_getvNumFreeFrames(FrameQ_Handle handle, 00996 UInt32 numFreeFrames[], 00997 UInt8 freeQId[], 00998 UInt8 numFreeQids); 00999 01000 /*! 01001 * @brief Provides a hook to perform implementation dependent operation 01002 * 01003 * @param handle Instance handle. 01004 * @param cmd Command to perform. 01005 * @param arg void * argument. 01006 * 01007 * @retval FrameQ_S_SUCCESS Operation successful. 01008 * @retval FrameQ_E_FAIL API failed. 01009 */ 01010 Int32 01011 FrameQ_control (FrameQ_Handle handle, 01012 Int32 cmd, 01013 Ptr arg); 01014 01015 /*! 01016 * @brief API to get the pointer to the extended header. 01017 * 01018 * @param frame pointer to frame 01019 * 01020 * @retval pointer Pointer to extended header pointer in frame header. 01021 */ 01022 Ptr FrameQ_getExtendedHeaderPtr(FrameQ_Frame frame); 01023 01024 01025 /*============================================================================= 01026 * Helper APIs 01027 *============================================================================= 01028 */ 01029 /*! 01030 * @brief Function to find out the number of frame buffers contained in a 01031 * frame. 01032 * 01033 * @param frame pointer to frame 01034 * 01035 * @retval number of frame buffers. 01036 */ 01037 UInt32 01038 FrameQ_getNumFrameBuffers (FrameQ_Frame frame); 01039 01040 /*! 01041 * @brief Function to get the framebuffer. 01042 * 01043 * @param frame pointer to frame 01044 * @param frameBufNum frame buffer index in the given frame 01045 * 01046 * @retval Pointer to frame buffer. 01047 */ 01048 Ptr 01049 FrameQ_getFrameBuffer (FrameQ_Frame frame, UInt32 frameBufNum); 01050 01051 /*! 01052 * @brief Function to get size of frame buffer. 01053 * 01054 * @param frame pointer to frame 01055 * @param frameBufNum frame buffer index in the given frame 01056 * 01057 * @retval size frame buffer size. 01058 */ 01059 UInt32 01060 FrameQ_getFrameBufSize (FrameQ_Frame frame, UInt32 frameBufNum); 01061 01062 /*! 01063 * @brief Function to get valid data size of a frame buffer. 01064 * 01065 * @param frame pointer to frame 01066 * @param frameBufNum frame buffer index in the given frame 01067 * 01068 * @retval size valid size of the frame buffer. 01069 */ 01070 UInt32 01071 FrameQ_getFrameBufValidSize (FrameQ_Frame frame, UInt32 frameBufNum); 01072 01073 /*! 01074 * @brief API to get the valid data start offset in framebuffer 01075 * identified by frameBufNum in a given frame 01076 * 01077 * @param frame pointer to frame 01078 * @param frameBufNum frame buffer index in the given frame 01079 * 01080 * @retval offset valid data offset in the frame buffer. 01081 */ 01082 UInt32 01083 FrameQ_getFrameBufDataStartOffset(FrameQ_Frame frame, 01084 UInt32 frameBufNum ); 01085 01086 /*! 01087 * @brief API to set the valid data size of a framebuffer identified by 01088 * frameBufNum in given frame. 01089 * 01090 * @param frame pointer to frame 01091 * @param frameBufNum frame buffer index in the given frame 01092 * @param validDataSize size of the valid data 01093 * 01094 * @retval FrameQ_S_SUCCESS Operation successful. 01095 * @retval FrameQ_E_FAIL API failed. 01096 */ 01097 Int32 01098 FrameQ_setFrameBufValidSize(FrameQ_Frame frame, 01099 UInt32 frameBufNum, 01100 UInt32 validDataSize ); 01101 01102 /*! 01103 * @brief API to set the valid data start offset of a framebuffer 01104 * identified by frameBufNum in a given frame. 01105 * 01106 * @param frame pointer to frame 01107 * @param frameBufNum frame buffer index in the given frame 01108 * @param dataStartOffset valid data startoffset that needs to set for the 01109 * frame buffer. 01110 * 01111 * @retval FrameQ_S_SUCCESS Operation successful. 01112 * @retval FrameQ_E_FAIL API failed. 01113 */ 01114 Int32 01115 FrameQ_setFrameBufDataStartOffset (FrameQ_Frame frame, 01116 UInt32 frameBufNum, 01117 UInt32 dataStartOffset); 01118 01119 01120 #if defined (__cplusplus) 01121 } 01122 #endif /* defined (__cplusplus) */ 01123 01124 01125 #endif /*FRAMEQ_H_0x6e6f*/
1.4.4