00001 /** 00002 * @file RingIO.h 00003 * 00004 * @brief This will have definitions for interfaces and structures for 00005 * RingIO module. 00006 * 00007 * The RingIO component provides data streaming between GPP and DSP 00008 * using ring buffer data as the transport. 00009 * 00010 * In a multiprocessor system having shared access to a memory 00011 * region, an efficient mode of data transfer can be implemented, 00012 * which uses a ring buffer created within the shared memory. 00013 * The reader and writer of the ring buffer can be on different 00014 * processors. 00015 * 00016 * The RingIO component on each processor shall provide the ability 00017 * to create RingIO buffers within the memory provided by the 00018 * application. The memory provided may be within the shared 00019 * memory region between two processors. If the RingIO buffer is 00020 * created within shared memory, it shall be accessible to reader 00021 * and writer present on the two processors between which the 00022 * memory is shared. The application can obtain a handle to the 00023 * RingIO through a call to open it. 00024 * 00025 * The RingIO component shall provide the ability for the writer to 00026 * acquire empty regions of memory within the data buffer. The 00027 * contents of the acquired region are committed to memory when the 00028 * data buffer is released by the writer. 00029 * 00030 * The RingIO component shall provide the ability for the reader to 00031 * acquire regions of memory within the data buffer with valid data 00032 * within them. On releasing the acquired region, the contents of 00033 * this region are marked as invalid. 00034 * 00035 * The RingIO component shall also support APIs for enabling 00036 * synchronous transfer of attributes with data. End of Stream 00037 * (EOS), Time Stamps, Stream offset etc. are examples of such 00038 * attributes and these shall be associated with offsets in the ring 00039 * buffer. 00040 * 00041 * A client using RingIO is a single unit of execution. It may be a 00042 * process or thread on the GPP or the DSP. 00043 * 00044 * - The RingIO instance can be created between a client on the 00045 * ARM and a client on the DSP or between two DSP clients. 00046 * 00047 * - Either the reader or writer can create or delete the RingIO 00048 * instance. 00049 * 00050 * - The RingIO instance should be created in a shared memory 00051 * region which can be accessed directly by both the reader 00052 * and the writer. 00053 * 00054 * - Both the reader and the writer need to open the RingIO 00055 * instance and get a handle. Any data access on the RingIO 00056 * instance should be made using these handles. 00057 * 00058 * - Each RingIO can have a single writer client and a single 00059 * reader client. A RingIO handle may not be shared between 00060 * multiple clients on the GPP or DSP. 00061 * 00062 * The RingIO client can be closed only if there is no currently 00063 * acquired data or attributes. If there is any unreleased data or 00064 * attributes, they must be released or cancelled before the RingIO 00065 * client can be closed. 00066 * 00067 * The RingIO can be deleted only when both reader and writer 00068 * clients have successfully closed their RingIO clients. 00069 * 00070 * Each RingIO instance has an associated footer area, if 00071 * configured. The foot buffer can be configured to be of zero size 00072 * if not required. If configured, the 00073 * foot-buffer is physically contiguous with the data buffer, and 00074 * hence the memory size specified must be equal to (data buffer 00075 * size + foot buffer size). 00076 * 00077 * The RingIO data and attribute buffer sizes must comply with 00078 * any constraints imposed by the heap that they are specified to 00079 * be allocated from. For example, for the Shared Memory Heap, 00080 * the buffer sizes must be aligned to DSP cache line. 00081 * 00082 * 00083 * @ver 02.00.00.68_beta1 00084 * 00085 * ============================================================================ 00086 * 00087 * Copyright (c) 2008-2009, Texas Instruments Incorporated 00088 * 00089 * Redistribution and use in source and binary forms, with or without 00090 * modification, are permitted provided that the following conditions 00091 * are met: 00092 * 00093 * * Redistributions of source code must retain the above copyright 00094 * notice, this list of conditions and the following disclaimer. 00095 * 00096 * * Redistributions in binary form must reproduce the above copyright 00097 * notice, this list of conditions and the following disclaimer in the 00098 * documentation and/or other materials provided with the distribution. 00099 * 00100 * * Neither the name of Texas Instruments Incorporated nor the names of 00101 * its contributors may be used to endorse or promote products derived 00102 * from this software without specific prior written permission. 00103 * 00104 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 00105 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 00106 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 00107 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 00108 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00109 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 00110 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 00111 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 00112 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 00113 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 00114 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00115 * Contact information for paper mail: 00116 * Texas Instruments 00117 * Post Office Box 655303 00118 * Dallas, Texas 75265 00119 * Contact information: 00120 * http://www-k.ext.ti.com/sc/technical-support/product-information-centers.htm? 00121 * DCMP=TIHomeTracking&HQS=Other+OT+home_d_contact 00122 * ============================================================================ 00123 * 00124 */ 00125 00126 00127 #ifndef RINGIO_H_0xd3f4 00128 #define RINGIO_H_0xd3f4 00129 00130 /* Utilities headers */ 00131 #include <ti/syslink/SysLink.h> 00132 00133 #if defined (__cplusplus) 00134 extern "C" { 00135 #endif 00136 00137 00138 /* ============================================================================= 00139 * All success and failure codes for the module 00140 * ============================================================================= 00141 */ 00142 /*! 00143 * @def RingIO_S_PENDINGATTRIBUTE 00144 * @brief Indicates that either: 00145 * 1) The amount of data requested could not be 00146 * serviced due to the presence of an attribute 00147 * 2) During an attribute read if another is also present 00148 * at the same offset. 00149 */ 00150 #define RingIO_S_PENDINGATTRIBUTE 4 00151 00152 /*! 00153 * @def RingIO_S_NOTCONTIGUOUSDATA 00154 * @brief Indicates that Valid data is present in the buffer but is not 00155 * contiguous as data has been copied from top to footer area. 00156 */ 00157 #define RingIO_S_NOTCONTIGUOUSDATA 3 00158 00159 /*! 00160 * @def RingIO_S_BUSY 00161 * @brief The resource is still in use 00162 */ 00163 #define RingIO_S_BUSY 2 00164 00165 /*! 00166 * @def RingIO_S_ALREADYSETUP 00167 * @brief The module has been already setup 00168 */ 00169 #define RingIO_S_ALREADYSETUP 1 00170 00171 /*! 00172 * @def RingIO_S_SUCCESS 00173 * @brief Operation is successful. 00174 */ 00175 #define RingIO_S_SUCCESS 0 00176 00177 /*! 00178 * @def RingIO_E_FAIL 00179 * @brief Operation is not successful. 00180 */ 00181 #define RingIO_E_FAIL -1 00182 00183 /*! 00184 * @def RingIO_E_INVALIDARG 00185 * @brief There is an invalid argument. 00186 */ 00187 #define RingIO_E_INVALIDARG -2 00188 00189 /*! 00190 * @def RingIO_E_MEMORY 00191 * @brief Operation resulted in memory failure. 00192 */ 00193 #define RingIO_E_MEMORY -3 00194 00195 /*! 00196 * @def RingIO_E_ALREADYEXISTS 00197 * @brief The specified entity already exists. 00198 */ 00199 #define RingIO_E_ALREADYEXISTS -4 00200 00201 /*! 00202 * @def RingIO_E_NOTFOUND 00203 * @brief Unable to find the specified entity. 00204 */ 00205 #define RingIO_E_NOTFOUND -5 00206 00207 /*! 00208 * @def RingIO_E_TIMEOUT 00209 * @brief Operation timed out. 00210 */ 00211 #define RingIO_E_TIMEOUT -6 00212 00213 /*! 00214 * @def RingIO_E_INVALIDSTATE 00215 * @brief Module is not initialized. 00216 */ 00217 #define RingIO_E_INVALIDSTATE -7 00218 00219 /*! 00220 * @def RingIO_E_OSFAILURE 00221 * @brief A failure occurred in an OS-specific call 00222 */ 00223 #define RingIO_E_OSFAILURE -8 00224 00225 /*! 00226 * @def RingIO_E_RESOURCE 00227 * @brief Specified resource is not available 00228 */ 00229 #define RingIO_E_RESOURCE -9 00230 00231 /*! 00232 * @def RingIO_E_RESTART 00233 * @brief Operation was interrupted. Please restart the operation 00234 */ 00235 #define RingIO_E_RESTART -10 00236 00237 /*! 00238 * @def RingIO_E_INVALIDMSG 00239 * @brief Operation is successful. 00240 */ 00241 #define RingIO_E_INVALIDMSG -11 00242 00243 /*! 00244 * @def RingIO_E_NOTOWNER 00245 * @brief Not the owner 00246 */ 00247 #define RingIO_E_NOTOWNER -12 00248 00249 /*! 00250 * @def RingIO_E_REMOTEACTIVE 00251 * @brief Operation is successful. 00252 */ 00253 #define RingIO_E_REMOTEACTIVE -13 00254 00255 /*! 00256 * @def RingIO_E_INVALIDHEAPID 00257 * @brief Operation is successful. 00258 */ 00259 #define RingIO_E_INVALIDHEAPID -14 00260 00261 /*! 00262 * @def RingIO_E_INVALIDPROCID 00263 * @brief Operation is successful. 00264 */ 00265 #define RingIO_E_INVALIDPROCID -15 00266 00267 /*! 00268 * @def RingIO_E_MAXREACHED 00269 * @brief Operation is successful. 00270 */ 00271 #define RingIO_E_MAXREACHED -16 00272 00273 /*! 00274 * @def RingIO_E_INUSE 00275 * @brief Indicates that the instance is in use.. 00276 */ 00277 #define RingIO_E_INUSE -17 00278 00279 /*! 00280 * @def RingIO_E_INVALIDCONTEXT 00281 * @brief Indicates that the api is called with wrong handle 00282 */ 00283 #define RingIO_E_INVALIDCONTEXT -18 00284 00285 /*! 00286 * @def RingIO_E_BADVERSION 00287 * @brief Versions don't match 00288 */ 00289 #define RingIO_E_BADVERSION -19 00290 00291 /*! 00292 * @def RingIO_E_BUFWRAP 00293 * @brief Indicates that the amount of data requested could not be serviced 00294 * due to the ring buffer getting wrapped 00295 */ 00296 #define RingIO_E_BUFWRAP -20 00297 00298 /*! 00299 * @def RingIO_E_BUFEMPTY 00300 * @brief Indicates that there is no data in the buffer for reading 00301 */ 00302 #define RingIO_E_BUFEMPTY -21 00303 00304 /*! 00305 * @def RingIO_E_BUFFULL 00306 * @brief Indicates that the buffer is full 00307 */ 00308 #define RingIO_E_BUFFULL -22 00309 00310 /*! 00311 * @def RingIO_E_PENDINGDATA 00312 * @brief Indicates that there is no attribute at the current, 00313 * but attributes are present at a future offset 00314 */ 00315 #define RingIO_E_PENDINGDATA -23 00316 00317 /*! 00318 * @def RingIO_E_VARIABLEATTRIBUTE 00319 * @brief Indicates that attibute get() failed, need to extract 00320 * variable length message getv() 00321 */ 00322 #define RingIO_E_VARIABLEATTRIBUTE -24 00323 00324 00325 /*! 00326 * @def RingIO_E_WRONGSTATE 00327 * @brief Indicates that the RingIO is in a wrong state 00328 */ 00329 #define RingIO_E_WRONGSTATE -25 00330 /*! 00331 * @def RingIO_E_NOTIFYFAIL 00332 * @brief Indicates that the the underlying notification call 00333 * failed 00334 */ 00335 #define RingIO_E_NOTIFYFAIL -26 00336 00337 /*! 00338 * @def RingIO_E_PENDINGATTRIBUTE 00339 * @brief Indicates that the the acquire failed as attribute is 00340 * present at current read offset 00341 */ 00342 #define RingIO_E_PENDINGATTRIBUTE -27 00343 00344 00345 /* ============================================================================= 00346 * Typedefs 00347 * ============================================================================= 00348 */ 00349 /*! 00350 * @def RingIO_BufPtr 00351 * 00352 * @brief This type is used for the Buffer Pointer Type. This type is used to 00353 * indicate the pointer to a data or attribute buffer. 00354 */ 00355 typedef Ptr RingIO_BufPtr; 00356 00357 /*! 00358 * @def RingIO_NotifyMsg 00359 * 00360 * @brief This type is used for the notification message. This is a 16 bit 00361 * payload which can be sent to the remote processor in a notification 00362 * call. 00363 */ 00364 typedef UInt16 RingIO_NotifyMsg; 00365 00366 /* ============================================================================= 00367 * Forward declarations 00368 * ============================================================================= 00369 */ 00370 /*! 00371 * @brief Handle for the RingIO instance. 00372 */ 00373 typedef struct RingIO_Object * RingIO_Handle; 00374 /* ============================================================================= 00375 * Structures & Enums 00376 * ============================================================================= 00377 */ 00378 00379 typedef enum RingIO_Type_Tag { 00380 RingIO_Type_SHAREDMEM = 0x0 00381 /*!< interface type for ringio delegate 00382 */ 00383 }RingIO_Type; 00384 /* ============================================================================= 00385 * Structures for instance related configuration 00386 * ============================================================================= 00387 */ 00388 /*! 00389 * @brief Structure defining config parameters for the RingIO module. 00390 */ 00391 typedef struct RingIO_Config_Tag { 00392 UInt32 maxNameLen; 00393 /*!< Maximum length of the name of RingIO instance */ 00394 UInt32 maxInstances; 00395 /*!< Maximum number of RingIO's that can be made */ 00396 } RingIO_Config; 00397 /*! 00398 * @brief Common parameters required to create RingIO instance of 00399 * any implementation. It should be the first element of the actual 00400 * implementaton params structure . 00401 */ 00402 typedef struct RingIO_Params_Tag { 00403 String name; 00404 /*!< Name of the instance */ 00405 RingIO_Type interfaceType; 00406 /*!< interface type for ringio delegate */ 00407 } RingIO_Params; 00408 00409 00410 /*! 00411 * @brief Structure defining config parameters for opening the RingIO 00412 * instances. 00413 */ 00414 typedef struct RingIO_openParams_Tag { 00415 UInt32 flags; 00416 /*!< Cache flags. See RingIO_Flags */ 00417 UInt32 openMode; 00418 /*!< Mode in which client will be opened */ 00419 } RingIO_openParams; 00420 00421 00422 /*! 00423 * @brief Structure defining config parameters for opening the RingIO 00424 * instances. 00425 */ 00426 typedef struct RingIO_sharedMemReqDetails_tag { 00427 UInt32 ctrlSharedMemReq; 00428 /*!< Instance specific control shared memory requirements */ 00429 UInt32 dataSharedMemReq; 00430 /*!< Data buffer shared memory requirements */ 00431 UInt32 attrSharedMemReq; 00432 /*!< Attribute buffer shared memory requirements */ 00433 } RingIO_sharedMemReqDetails; 00434 00435 00436 /*! 00437 * @def RingIO_DATABUF_CACHEUSE, 00438 * RingIO_ATTRBUF_CACHEUSE, 00439 * RingIO_CONTROL_CACHEUSE, 00440 * RingIO_NEED_EXACT_SIZE 00441 * 00442 * @brief These constants denote the flags provided while opening the RingIO. 00443 */ 00444 typedef enum RingIO_Flags_tag { 00445 RingIO_DATABUF_CACHEUSE = 0x1, 00446 /*!< Denotes whether the client uses cache for accessing the 00447 * data buffer 00448 */ 00449 RingIO_ATTRBUF_CACHEUSE = 0x2, 00450 /*!< Denotes whether the client uses cache for accessing the 00451 * attribute buffer 00452 */ 00453 RingIO_CONTROL_CACHEUSE = 0x4, 00454 /*!< Denotes whether the client uses cache for accessing the 00455 * control structure 00456 */ 00457 RingIO_NEED_EXACT_SIZE = 0x8 00458 /*!< Denotes whether requests for acquire buffer should always 00459 * be satisfied. If a contiguous request could not be 00460 * satisfied because of the buffer wrap, we need to mark an 00461 * early end and provide only a contiguous buffer 00462 */ 00463 } RingIO_Flags; 00464 00465 /*! 00466 * @brief Enumerates the notification types for RingIO 00467 */ 00468 typedef enum RingIO_NotifyType_Tag { 00469 RingIO_NOTIFICATION_NONE = SysLink_NOTIFICATION_NONE, 00470 /*!< No notification is required. */ 00471 RingIO_NOTIFICATION_ALWAYS = SysLink_NOTIFICATION_ALWAYS, 00472 /*!< Notify whenever the other client sends data/frees up space.*/ 00473 RingIO_NOTIFICATION_ONCE = SysLink_NOTIFICATION_ONCE, 00474 /*!< Notify when the other side sends data/frees up space. Once the 00475 * notification is done, the notification is disabled until it is 00476 * enabled again. 00477 */ 00478 RingIO_NOTIFICATION_HDWRFIFO_ALWAYS = 00479 SysLink_NOTIFICATION_HDWRFIFO_ALWAYS, 00480 /*!< Notify whenever the other side sends data/frees up space. 00481 * This notification is never disabled. 00482 */ 00483 RingIO_NOTIFICATION_HDWRFIFO_ONCE = 00484 SysLink_NOTIFICATION_HDWRFIFO_ONCE 00485 /*!< Notify when the other side sends data/frees up space. Once the 00486 * notification is done, the notification is disabled until it is 00487 * enabled again. The notification is enabled once the watermark 00488 * is crossed and does not require buffer to get full/empty. 00489 */ 00490 } RingIO_NotifyType; 00491 00492 /*! 00493 * @brief Enumeration of RingIO open modes. 00494 * 00495 */ 00496 typedef enum RingIO_OpenMode_Tag { 00497 RingIO_MODE_READER = 0x0, 00498 /*!< If specifed in params, open call returns a reader handle.*/ 00499 RingIO_MODE_WRITER = 0x1, 00500 /*!< If specifed in params, open call returns a writer handle.*/ 00501 RingIO_MODE_NONE = 0x2 00502 /*!< Mode of the handle after a create call and before a open call .*/ 00503 } RingIO_OpenMode; 00504 00505 /*! 00506 * @brief Prototype of the RingIO call back function. 00507 * 00508 * @param RingIO_Handle Pointer to the RingIO instance structure 00509 * in which the default params is to be returned. 00510 * Ptr Argument to callback function e.g. handle to 00511 * semaphore to be posted from callback 00512 * UInt32 message 00513 * 00514 * @retval None 00515 */ 00516 typedef void (* RingIO_NotifyFxn ) (RingIO_Handle, Ptr, UInt32); 00517 00518 00519 /* ============================================================================= 00520 * APIs to be used in Application 00521 * ============================================================================= 00522 */ 00523 /* ============================================================================= 00524 * Instance creation and deletion related API's 00525 * ============================================================================= 00526 */ 00527 /*! 00528 * @brief Function to initialize the parameters for the RingIO instance. 00529 * 00530 * This function can be called by the application to get their 00531 * configuration parameter to RingIO_create filled in by the 00532 * RingIO module with the default parameters. 00533 * 00534 * @param params Pointer to the RingIO interface type specific params, 00535 * refer to Interface type specific header file for 00536 * details on interface type specific params 00537 * 00538 * @retval None 00539 * 00540 * @sa RingIO_create 00541 */ 00542 Void RingIO_Params_init (Void * params); 00543 00544 /*! 00545 * @brief Function to create a RingIO object for a specific slave 00546 * processor. 00547 * 00548 * This function creates an instance of the RingIO module and 00549 * returns an instance handle, which is used to access the 00550 * specified RingIO. 00551 * Instance-level configuration needs to be provided to this 00552 * function. If the user wishes to change some specific config 00553 * parameters, then RingIO_Params_init can be called to get the 00554 * configuration filled with the default values. After this, only 00555 * the required configuration values can be changed. 00556 * 00557 * @param params Pointer to the RingIO interface type specific params, 00558 * refer to Interface type specific header file for 00559 * details on interface type specific params 00560 * 00561 * @retval Valid_handle_of_type_RingIO_Handle Operation successful 00562 * @retval NULL Operation unsuccessful 00563 * 00564 * @sa RingIO_delete, RingIO_open, RingIO_close 00565 */ 00566 RingIO_Handle RingIO_create (const Void * params); 00567 00568 /*! 00569 * @brief Function to delete a RingIO object for a specific slave 00570 * processor. 00571 * 00572 * Once this function is called, other RingIO instance level APIs 00573 * that require the instance handle cannot be called. 00574 * 00575 * @param handlePtr Pointer to Handle to the RingIO object 00576 * Reset to NULL when the function successfully 00577 * completes. 00578 * 00579 * @retval RingIO_E_INVALIDSTATE Module is in an invalid state 00580 * Instance was not created on this processor 00581 * @retval RingIO_E_INVALIDARG handlePtr pointer passed is NULL 00582 * @retval RingIO_E_INVALIDARG *handlePtr passed is NULL 00583 * @retval RingIO_S_SUCCESS Operation Successful 00584 * 00585 * @sa RingIO_create 00586 */ 00587 Int RingIO_delete (RingIO_Handle * handlePtr); 00588 00589 /*! 00590 * @brief Get shared memory requirements. Params_init must be called to 00591 * initialize the parameters before calling this function. 00592 * 00593 * @param params Pointer to the RingIO interface type specific params, 00594 * refer to Interface type specific header file for 00595 * details on interface type specific params. 00596 * @param sharedMemDetails Control, Data and Attr shared memory details 00597 * 00598 * @retval Shared-memory-requirements Operation successfully completed. 00599 * The out parameter of sharedMemDetails contains the values for 00600 * ctrlSharedMemReq : Control shared memory requirements 00601 * dataSharedMemReq : Data Buffer shared memory requirements 00602 * attrSharedMemReq : Attribute buffer shared memory requirements 00603 * 00604 * @sa None 00605 */ 00606 UInt32 00607 RingIO_sharedMemReq (const Void * params, 00608 RingIO_sharedMemReqDetails * sharedMemReqDetails); 00609 00610 /* ============================================================================= 00611 * Instance opening and closing related API's 00612 * ============================================================================= 00613 */ 00614 /*! 00615 * @brief Opens a created instance of RingIO module by the shared memory 00616 * address of the instance. 00617 * 00618 * @param name Name of the RingIO instance to be opened 00619 * @param params Parameters for opening the RingIO instance. 00620 * @param procIds Array of processor IDs to search for the RingIO 00621 * instance. If NULL is specified, all processors are 00622 * checked. 00623 * @param handlePtr OUT parameter: Holds the RingIO handle on success. 00624 * 00625 * @retval RingIO_E_INVALIDSTATE Module is in an invalid state 00626 * @retval RingIO_E_NOTFOUND RingIO not found 00627 * @retval RingIO_E_FAIL Failed to open the gate associated with 00628 * the RingIO instance. 00629 * Failed to open the clientnotifymgr associated 00630 * with the RingIO instance. 00631 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00632 * @retval RingIO_S_SUCCESS Operation Successful 00633 * 00634 * @sa RingIO_close, RingIO_openParams 00635 */ 00636 Int 00637 RingIO_open ( String name, 00638 const RingIO_openParams * params, 00639 UInt16 * procIds, 00640 RingIO_Handle * handlePtr); 00641 00642 /*! 00643 * @brief Opens a created instance of RingIO module. 00644 * 00645 * @param ctrlSharedAddr Shared address at which the instance exists 00646 * @param params Parameters for opening the RingIO instance. 00647 * @param remoteProcId Processor ID of the processor where the RingIO 00648 * instance exists 00649 * @param handlePtr OUT parameter: Holds the RingIO handle on 00650 * success. 00651 * 00652 * @retval RingIO_E_INVALIDSTATE Module is in an invalid state 00653 * @retval RingIO_E_NOTFOUND RingIO not found 00654 * @retval RingIO_E_FAIL Failed to open the gate associated with 00655 * the RingIO instance. 00656 * Failed to open the clientnotifymgr associated 00657 * with the RingIO instance. 00658 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00659 * @retval RingIO_S_SUCCESS Operation Successful 00660 * @retval 00661 * 00662 * @sa RingIO_create, RingIO_delete, RingIO_close 00663 */ 00664 Int 00665 RingIO_openByAddr ( Ptr ctrlSharedAddr, 00666 const RingIO_openParams * params, 00667 UInt16 remoteProcId, 00668 RingIO_Handle * handlePtr); 00669 00670 /*! 00671 * @brief Closes previously opened/created instance of RingIO module. 00672 * 00673 * @param handlePtr Pointer to handle for the opened RingIO instance. 00674 * Reset to invalid when the function successfully 00675 * completes. 00676 * 00677 * @retval RingIO_E_INVALIDSTATE Module is in an invalid state 00678 * @retval RingIO_E_FAIL Failed to open the gate associated with 00679 * the RingIO instance. 00680 * Failed to open the clientnotifymgr associated 00681 * with the RingIO instance. 00682 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00683 * @retval RingIO_S_SUCCESS Operation Successful 00684 * 00685 * @sa RingIO_create, RingIO_delete, RingIO_open 00686 */ 00687 Int RingIO_close (RingIO_Handle * handlePtr); 00688 00689 00690 /* ============================================================================= 00691 * Instance Notification related API's 00692 * ============================================================================= 00693 */ 00694 /*! 00695 * @brief Function to register a call back function. 00696 * 00697 * This function sets Notification parameters for the RingIO Client. 00698 * Both the reader and writer can set their notification mechanism 00699 * using this function 00700 * 00701 * RingIO_open for both reader and writer has been successful. 00702 * No DSP/BIOS Link API should be called from a callback function 00703 * registered through the RingIO or NOTIFY module. On DSP-side or 00704 * on operating systems such as PrOS, the callback functions are 00705 * run from ISR context and must not perform any operations that 00706 * may take a lock or block, which is done by most DSPLink APIs. 00707 * Minimum functionality must be used in the callback functions, 00708 * most often limited to posting a semaphore on which application 00709 * is waiting, posting SWI etc. 00710 * 00711 * @param handle RingIO client Handle. 00712 * @param notifyType Type of notification. 00713 * @param watermark WaterMark 00714 * @param notifyFunc Call back function 00715 * @param cbContext Context pointer that needs to be passed to call back. 00716 * 00717 * @retval RingIO_E_INVALIDSTATE Module is in an invalid state 00718 * RingIO_open is not called yet 00719 * @retval RingIO_E_FAIL Failed to open the gate associated with 00720 * the RingIO instance. 00721 * Failed to open the clientnotifymgr associated 00722 * with the RingIO instance. 00723 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00724 * @retval RingIO_S_SUCCESS Operation Successful 00725 * 00726 * @sa None 00727 */ 00728 Int RingIO_registerNotifier (RingIO_Handle handle, 00729 RingIO_NotifyType notifyType, 00730 UInt32 watermark, 00731 RingIO_NotifyFxn notifyFunc, 00732 Ptr cbContext); 00733 00734 /*! 00735 * @brief Function to un-register call back function. 00736 * 00737 * @param handle RingIO client Handle. 00738 * @param notifyType Type of notification. 00739 * @param watermark WaterMark 00740 * @param condition Unused for RingIO. 00741 * @param notifyFunc Call back function 00742 * @param cbContext Context pointer that needs to be passed to call back. 00743 * 00744 * @retval RingIO_E_INVALIDSTATE Module is in an invalid state 00745 * RingIO_open is not called yet 00746 * @retval RingIO_E_FAIL Failed to open the gate associated with 00747 * the RingIO instance. 00748 * Failed to open the clientnotifymgr associated 00749 * with the RingIO instance. 00750 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00751 * @retval RingIO_S_SUCCESS Operation Successful 00752 * 00753 * @sa RingIO_registerNotifier 00754 */ 00755 Int RingIO_unregisterNotifier (RingIO_Handle handle, 00756 RingIO_NotifyType notifyType , 00757 UInt32 watermark, 00758 RingIO_NotifyFxn notifyFunc, 00759 Ptr cbContext); 00760 00761 /*! 00762 * @brief Function to set client's watermark 00763 * 00764 * @param handle RingIO client Handle. 00765 * @param watermark Watermark value 00766 * 00767 * @retval -1 Operation unsuccessful 00768 * @retval watermark Operation successful 00769 * 00770 * @sa RingIO_registerNotifier 00771 */ 00772 Int RingIO_setWaterMark (RingIO_Handle handle, 00773 UInt32 watermark); 00774 00775 /*! 00776 * @brief Function to set the notify type 00777 * 00778 * @param handle Instance handle. 00779 * @param notifyType Type of notification 00780 * 00781 * @retval RingIO_E_FAIL Operation unsuccessful 00782 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00783 * @retval RingIO_S_SUCCESS Operation Successful 00784 * 00785 * @sa RingIO_NotifyType, RingIO_registerNotifier 00786 */ 00787 Int 00788 RingIO_setNotifyType (RingIO_Handle handle, 00789 RingIO_NotifyType notifyType); 00790 00791 /*============================================================================= 00792 * Main RingIO APIs called by application for RingIO functions 00793 *============================================================================= 00794 */ 00795 /*! 00796 * @brief Acquires data from the RingIO instance 00797 * This function acquires a data buffer from RingIO for reading or 00798 * writing, depending on the mode in which the client (represented 00799 * by the handle) has been opened. 00800 * 00801 * @param handle RingIO handle 00802 * @param pData Location to store the pointer to the acquired data 00803 * buffer. 00804 * @param pSize Pointer to the size of data buffer acquired. Holds 00805 * the size of buffer to be acquired. Returns the size 00806 * of buffer actually acquired. 00807 * 00808 * @retval RingIO_S_SUCCESS Operation successfully completed. 00809 * @retval RingIO_E_PENDINGATTRIBUTE No data buffer could be acquired 00810 * because an attribute was 00811 * present at the current read offset. 00812 * @retval RingIO_S_PENDINGATTRIBUTE Flag RingIO_NEED_EXACT_SIZE is set. 00813 * Partial Data buffer is retuned till 00814 * the offset where an attribute was 00815 * present/ 00816 * @retval RingIO_E_BUFFULL Requested size of data buffer could 00817 * not be returned because the total available 00818 * size is less than requested size. A smaller 00819 * sized buffer may have been returned, 00820 * if available. 00821 * @retval RingIO_E_BUFWRAP Requested size of data buffer could 00822 * not be returned because the 00823 * available contiguous size till end 00824 * of buffer is less than requested size. 00825 * A smaller sized buffer may have been returned, 00826 * if available. 00827 * @retval RingIO_E_FAIL General failure. 00828 * Contiguous buffer requirement cannot 00829 * be satisfied even by setting early end. 00830 * @retval RingIO_S_NOTCONTIGUOUSDATA Valid data is present but is not 00831 * contiguous because the data has been 00832 * acquired using the foot buffer. 00833 * @retval RingIO_E_BUFEMPTY No data available to acquire 00834 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00835 * 00836 * @sa RingIO_release 00837 */ 00838 Int 00839 RingIO_acquire (RingIO_Handle handle, 00840 RingIO_BufPtr * pData, 00841 UInt32 * pSize); 00842 00843 00844 00845 /*! 00846 * @brief Releases data from the RingIO instance 00847 * 00848 * @param handle RingIO handle 00849 * @param size Size of the released buffer 00850 * 00851 * @retval RingIO_E_FAIL General Failure 00852 * Invalid size argument > 00853 * client acquired size passed 00854 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00855 * @retval RingIO_E_NOTIFYFAIL Failure when sending notification 00856 * to other client. 00857 * @retval RingIO_S_SUCCESS Operation Successful 00858 * 00859 * @sa RingIO_acquire 00860 */ 00861 Int 00862 RingIO_release (RingIO_Handle handle, 00863 UInt32 size); 00864 00865 00866 /*! 00867 * @brief Cancel the previous acquired buffer to 00868 * the RingIO instance 00869 * This function cancels any data buffers acquired by reader or 00870 * writer. In the case of writer, all attributes that are set since 00871 * the first acquire are removed. In the case of reader, all 00872 * attributes that were obtained since the first acquired 00873 * are re-instated in the RingIO instance. 00874 * 00875 * @param handle RingIO handle 00876 * 00877 * @retval RingIO_E_FAIL General Failure 00878 * No data acquired 00879 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00880 * @retval RingIO_S_SUCCESS Operation Successful 00881 * 00882 * @sa RingIO_acquire 00883 */ 00884 Int 00885 RingIO_cancel (RingIO_Handle handle); 00886 00887 /*! 00888 * @brief Get attribute from the RingIO instance 00889 * This function gets an attribute with a variable-sized payload 00890 * from the attribute buffer. 00891 * If an attribute is present, the attribute type, the optional 00892 * parameter, a pointer to the optional payload and the payload 00893 * size are returned. 00894 * 00895 * @param handle RingIO handle 00896 * @param type 00897 * Location to receive the user-defined type of attribute. 00898 * @param param 00899 * Location to receive an optional parameter which depends on the 00900 * attribute type. 00901 * @param vptr 00902 * Pointer to buffer to receive the optional payload. 00903 * @param pSize 00904 * Location with the size of the variable attribute. On return, 00905 * this stores the actual size of the payload. 00906 * 00907 * @retval RingIO_E_FAIL General Failure 00908 * No attribute present 00909 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00910 * @retval RingIO_S_SUCCESS Operation Successful 00911 * @retval RingIO_S_PENDINGATTRIBUTE Additional attributes are present at 00912 * the current read offset. 00913 * @retval RingIO_E_VARIABLEATTRIBUTE No buffer has been provided to receive 00914 * the variable attribute 00915 * payload. 00916 * @retval RingIO_E_PENDINGDATA More data must be read before reading 00917 * the attribute. 00918 * 00919 * @sa RingIO_getAttribute 00920 */ 00921 Int 00922 RingIO_getvAttribute (RingIO_Handle handle, 00923 UInt16 * type, 00924 UInt32 * param, 00925 RingIO_BufPtr vptr, 00926 UInt32 * pSize); 00927 00928 00929 /*! 00930 * @brief Set attribute in the RingIO instance 00931 * This function sets an attribute with a variable sized payload at 00932 * the offset provided in the acquired data buffer. 00933 * If the offset is not in the range of the acquired data buffer, 00934 * the attribute is not set, and an error is returned. One 00935 * exception to this rule is when no data buffer has been acquired. 00936 * In this case an attribute is set at the next data buffer offset 00937 * that can be acquired 00938 * 00939 * @param handle Handle to the RingIO Client. 00940 * @param type User-defined type of attribute. 00941 * @param param Optional parameter which depends on the 00942 * attribute type. 00943 * @param pData Pointer to attribute payload buffer. 00944 * @param size Size of the attribute payload. 00945 * @param sendNotification Flag to indicate whether notification should 00946 * be sent or not on successful setting of an 00947 * attribute 00948 * @retval RingIO_E_FAIL General Failure 00949 * No attribute present 00950 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00951 * @retval RingIO_S_SUCCESS Operation Successful 00952 * @retval RingIO_E_WRONGSTATE 00953 * Do not allow setting an attribute 00954 * when it falls into reader 00955 * region. The following scenarios cover this condition: 00956 * - The buffer is completely full. In this case, attribute can only 00957 * be set at offset 0. But offset 0 falls into reader region. 00958 * - The buffer is completely acquired by the writer. Part or none 00959 * of this buffer may be released. Writer is attempting to set an 00960 * attribute at the end of its acquired range. In this case, end 00961 * of writer buffer is the same as beginning of reader buffer. 00962 * If the reader has acquired and released some data, resulting in 00963 * its moving further such that its acquire start is not at the 00964 * same location where writer may be able to set an attribute, the 00965 * above conditions do not hold true, and the attribute is allowed 00966 * to be set. 00967 * @retval RingIO_E_NOTIFYFAIL Failure when sending notification 00968 * to other client. 00969 * 00970 * @sa RingIO_acquire 00971 */ 00972 Int 00973 RingIO_setvAttribute (RingIO_Handle handle, 00974 UInt16 type, 00975 UInt32 param, 00976 RingIO_BufPtr pData, 00977 UInt32 size, 00978 Bool sendNotification); 00979 00980 00981 /*! 00982 * @brief This function gets a fixed-size attribute from the attribute 00983 * buffer. 00984 * If an attribute is present, the attribute type and a related 00985 * parameter are returned. 00986 * 00987 * @param handle RingIO handle 00988 * @param type 00989 * Location to receive the user-defined type of attribute. 00990 * @param param 00991 * Location to receive an optional parameter which depends on the 00992 * attribute type. 00993 * 00994 * @retval RingIO_E_FAIL General Failure 00995 * No attribute present 00996 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 00997 * @retval RingIO_S_SUCCESS Operation Successful 00998 * @retval RingIO_S_PENDINGATTRIBUTE Additional attributes are present at 00999 * the current read offset. 01000 * @retval RingIO_E_VARIABLEATTRIBUTE A variable attribute exists.The application 01001 * must call RingIO_getvAttribute () 01002 * to get the variable attribute. 01003 * @retval RingIO_E_PENDINGDATA More data must be read before reading 01004 * the attribute. 01005 * 01006 * @sa RingIO_getvAttribute 01007 */ 01008 Int 01009 RingIO_getAttribute (RingIO_Handle handle, 01010 UInt16 * type, 01011 UInt32 * param); 01012 01013 /*! 01014 * @brief This function sets a fixed-size attribute at the offset provided 01015 * in the acquired data buffer. 01016 * This function sets a fixed-size attribute at the offset provided 01017 * in the acquired data buffer. 01018 * If the offset is not in the range of the acquired data buffer, 01019 * the attribute is not set, and an error is returned. One 01020 * exception to this rule is when no data buffer has been acquired. 01021 * In this case an attribute is set at the next data buffer offset 01022 * that can be acquired 01023 * 01024 * @param handle 01025 * Handle to the RingIO Client. 01026 * @param offset 01027 * Offset in the acquired data buffer to which the attribute 01028 * corresponds 01029 * @param type 01030 * User-defined type of attribute. 01031 * @param param 01032 * Optional parameter which depends on the attribute type. 01033 * @param sendNotification 01034 * Flag to indicate whether notification should be sent or not 01035 * on successful setting of an attribute 01036 * 01037 * @retval RingIO_E_FAIL General Failure 01038 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 01039 * @retval RingIO_S_SUCCESS Operation Successful 01040 * @retval RingIO_E_WRONGSTATE 01041 * Do not allow setting an attribute 01042 * when it falls into reader 01043 * region. The following scenarios cover this condition: 01044 * - The buffer is completely full. In this case, attribute can only 01045 * be set at offset 0. But offset 0 falls into reader region. 01046 * - The buffer is completely acquired by the writer. Part or none 01047 * of this buffer may be released. Writer is attempting to set an 01048 * attribute at the end of its acquired range. In this case, end 01049 * of writer buffer is the same as beginning of reader buffer. 01050 * If the reader has acquired and released some data, resulting in 01051 * its moving further such that its acquire start is not at the 01052 * same location where writer may be able to set an attribute, the 01053 * above conditions do not hold true, and the attribute is allowed 01054 * to be set. 01055 * @retval RingIO_E_NOTIFYFAIL Failure when sending notification 01056 * to other client. 01057 * 01058 * 01059 */ 01060 Int 01061 RingIO_setAttribute (RingIO_Handle handle, 01062 UInt16 type, 01063 UInt32 param, 01064 Bool sendNotification); 01065 01066 01067 /*! 01068 * @brief Flush the buffer in the RingIO instance 01069 * 01070 * This function flushes the data buffer. 01071 * This function is used to flush the data from the RingIO. 01072 * Behavior of this function depends on the value of hardFlush 01073 * argument 01074 * When hardFlush is false: 01075 * If function is called for the writer, all the valid data in 01076 * buffer after the first attribute location will be discarded. 01077 * In case there are no attributes, no data will be cleared from 01078 * the buffer. Note that this does not include the data that has 01079 * been already acquired by the reader. Note that the attribute 01080 * will also be cleared from the attribute buffer. 01081 * For the reader, all the data till the next attribute location 01082 * will be discarded. And if there is no attribute in the buffer, 01083 * all valid data will get discarded. Note that the attribute will 01084 * remain the attribute buffer. This is different from the 01085 * behavior mentioned for the writer. 01086 * When hardFlush is true: 01087 * If function is called from the writer, all committed data and 01088 * attributes that is not acquired by reader are removed from 01089 * the RingIO instance. The writer pointer is moved to point to 01090 * reader's head pointer 01091 * If function is called from the reader, all data and attributes 01092 * that can be subsequently acquired from the reader are removed. 01093 * 01094 * @param handle 01095 * Handle to the RingIO Client. 01096 * @param hardFlush 01097 * Mode in which the flush operation discards committed data 01098 * and attributes 01099 * @param type 01100 * Location to receive the User-defined type of attribute. 01101 * @param param 01102 * Location to receive an optional parameter which depends on the 01103 * attribute type. 01104 * @param bytesFlushed 01105 * Location to recieve the size of the buffer flushed. 01106 * 01107 * @retval RingIO_E_FAIL General Failure 01108 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 01109 * @retval RingIO_S_SUCCESS Operation Successful 01110 * @retval RingIO_E_NOTIFYFAIL Failure when sending notification 01111 * to other client. 01112 * 01113 * 01114 * @sa RingIO_acquire 01115 */ 01116 Int 01117 RingIO_flush (RingIO_Handle handle, 01118 Bool hardFlush, 01119 UInt16 * type, 01120 UInt32 * param, 01121 UInt32 * bytesFlushed); 01122 01123 01124 /*! 01125 * @brief Send a force notification to the other client manually 01126 * 01127 * @param handle Handle to RingIO instance 01128 * @param msg Payload to notification 01129 * 01130 * @retval RingIO_E_FAIL General Failure 01131 * @retval RingIO_E_INVALIDARG Parameters passed are invalid 01132 * @retval RingIO_S_SUCCESS Operation Successful 01133 * @retval RingIO_E_NOTIFYFAIL Failure when sending notification 01134 * to other client. 01135 * 01136 * @sa None 01137 */ 01138 Int 01139 RingIO_notify (RingIO_Handle handle, 01140 RingIO_NotifyMsg msg); 01141 01142 01143 /*============================================================================= 01144 * Helper APIs 01145 *============================================================================= 01146 */ 01147 /*! 01148 * @brief Function to get valid data buffer size. 01149 * 01150 * @param handle RingIO client Handle. 01151 * 01152 * @retval Valid_data_buffer_size Operation successful 01153 * @retval -1 Operation unsuccessful. 01154 */ 01155 UInt 01156 RingIO_getValidSize (RingIO_Handle handle); 01157 01158 /*! 01159 * @brief Function to get empty data buffer size. 01160 * 01161 * @param handle RingIO client Handle. 01162 * 01163 * @retval Empty_data_buffer_size Operation successful 01164 * @retval -1 Operation unsuccessful 01165 */ 01166 UInt 01167 RingIO_getEmptySize (RingIO_Handle handle); 01168 01169 /*! 01170 * @brief Function to get valid attribute size. 01171 * 01172 * @param handle RingIO client Handle. 01173 * 01174 * @retval Valid_attribute_size Operation successful 01175 * @retval -1 Operation unsuccessful 01176 */ 01177 UInt 01178 RingIO_getValidAttrSize (RingIO_Handle handle); 01179 01180 /*! 01181 * @brief Function to get empty attribute size. 01182 * 01183 * @param handle RingIO client Handle. 01184 * 01185 * @retval Empty_attribute_size Operation successful 01186 * -1 Operation unsuccessful 01187 */ 01188 UInt 01189 RingIO_getEmptyAttrSize (RingIO_Handle handle); 01190 01191 /*! 01192 * @brief Function to get client's acquired offset 01193 * 01194 * @param handle RingIO client Handle. 01195 * 01196 * @retval Acquired_offset Operation successful 01197 * @retval -1 Operation unsuccessful 01198 */ 01199 UInt 01200 RingIO_getAcquiredOffset (RingIO_Handle handle); 01201 01202 /*! 01203 * @brief Function to get client's acquired size 01204 * 01205 * @param handle RingIO client Handle. 01206 * 01207 * @retval Acquired_Size Operation successful 01208 * @retval -1 Operation unsuccessful 01209 */ 01210 UInt 01211 RingIO_getAcquiredSize (RingIO_Handle handle); 01212 01213 /*! 01214 * @brief Function to get client's watermark 01215 * 01216 * @param handle RingIO client Handle. 01217 * 01218 * @retval Watermark_value Operation successful 01219 * -1 Operation unsuccessful 01220 */ 01221 UInt 01222 RingIO_getWaterMark (RingIO_Handle handle); 01223 01224 /* ============================================================================= 01225 * APIs used internally by Ipc module 01226 * ============================================================================= 01227 */ 01228 /*! 01229 * @brief Function to get the default configuration for the RingIO 01230 * module. 01231 * 01232 * This function can be called by the application to get their 01233 * configuration parameter to RingIO_setup filled in by the 01234 * RingIO module with the default parameters. If the user does 01235 * not wish to make any change in the default parameters, this API 01236 * is not required to be called. 01237 * 01238 * @param cfgParams Pointer to the RingIO module configuration structure 01239 * in which the default config is to be returned. 01240 * 01241 * @sa RingIO_setup 01242 */ 01243 Void RingIO_getConfig (RingIO_Config * cfgParams); 01244 01245 /*! 01246 * @brief Function to setup the RingIO module. 01247 * 01248 * This function sets up the RingIO module. This function must 01249 * be called before any other instance-level APIs can be invoked. 01250 * Module-level configuration needs to be provided to this 01251 * function. If the user wishes to change some specific config 01252 * parameters, then RingIO_getConfig can be called to get the 01253 * configuration filled with the default values. After this, only 01254 * the required configuration values can be changed. If the user 01255 * does not wish to make any change in the default parameters, the 01256 * application can simply call RingIO with NULL parameters. 01257 * The default parameters would get automatically used. 01258 * 01259 * @param cfgParams Optional RingIO module configuration. If provided as 01260 * NULL, default configuration is used. 01261 * 01262 * @retval 01263 * 01264 * @sa RingIO_destroy 01265 * NameServer_create 01266 * GateMutex_create 01267 * Memory_alloc 01268 */ 01269 Int RingIO_setup (const RingIO_Config * cfgParams); 01270 01271 /*! 01272 * @brief Function to destroy the RingIO module. 01273 * 01274 * Once this function is called, other RingIO module APIs, except 01275 * for the RingIO_getConfig API cannot be called anymore. 01276 * 01277 * @retval 01278 * @sa RingIO_setup, NameServer_delete, GateMutex_delete 01279 */ 01280 Int RingIO_destroy (Void); 01281 01282 01283 01284 #if defined (__cplusplus) 01285 } 01286 #endif /* defined (__cplusplus) */ 01287 01288 01289 #endif /* RINGIO_H_0xd3f4 */
1.4.4