00001 /** ============================================================================ 00002 * @file ringiodefs.h 00003 * 00004 * @path $(DSPLINK)/gpp/inc/usr/ 00005 * 00006 * @brief Global definitions for RingIO module 00007 * 00008 * @ver 1.65.00.03 00009 * ============================================================================ 00010 * @copyright Copyright (C) 2002-2009, Texas Instruments Incorporated - 00011 * http://www.ti.com/ 00012 * 00013 * Redistribution and use in source and binary forms, with or without 00014 * modification, are permitted provided that the following conditions 00015 * are met: 00016 * 00017 * * Redistributions of source code must retain the above copyright 00018 * notice, this list of conditions and the following disclaimer. 00019 * 00020 * * Redistributions in binary form must reproduce the above copyright 00021 * notice, this list of conditions and the following disclaimer in the 00022 * documentation and/or other materials provided with the distribution. 00023 * 00024 * * Neither the name of Texas Instruments Incorporated nor the names of 00025 * its contributors may be used to endorse or promote products derived 00026 * from this software without specific prior written permission. 00027 * 00028 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 00029 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 00030 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 00031 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 00032 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00033 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 00034 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 00035 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 00036 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 00037 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 00038 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00039 * ============================================================================ 00040 */ 00041 00042 00043 #if !defined (RINGIODEFS_H) 00044 #define RINGIODEFS_H 00045 00046 00047 /* ----------------------------------- DSP/BIOS LINK Headers */ 00048 #include <dsplink.h> 00049 #include <archdefs.h> 00050 #include <mpcsdefs.h> 00051 00052 00053 #if defined (__cplusplus) 00054 extern "C" { 00055 #endif /* defined (__cplusplus) */ 00056 00057 00058 /** ============================================================================ 00059 * @const RINGIO_INVALID_ATTR 00060 * 00061 * @brief This constant denotes an invalid attribute type. 00062 * This should not be used for any valid attribute. 00063 * ============================================================================ 00064 */ 00065 #define RINGIO_INVALID_ATTR (Uint16) 0xFFFFl 00066 00067 /** ============================================================================ 00068 * @const RINGIO_DATABUF_CACHEUSE, RINGIO_ATTRBUF_CACHEUSE, 00069 * RINGIO_ATTRBUF_CACHEUSE, RINGIO_NEED_EXACT_SIZE 00070 * 00071 * @brief These constants denote the flags provided while opening the RingIO. 00072 * ============================================================================ 00073 */ 00074 #define RINGIO_DATABUF_CACHEUSE 0x1u 00075 #define RINGIO_ATTRBUF_CACHEUSE 0x2u 00076 #define RINGIO_CONTROL_CACHEUSE 0x4u 00077 #define RINGIO_NEED_EXACT_SIZE 0x8u 00078 00079 /** ============================================================================ 00080 * @macro RINGIO_NAME_MAX_LEN 00081 * 00082 * @brief Maximum length of RingIO strings. 00083 * ============================================================================ 00084 */ 00085 #define RINGIO_NAME_MAX_LEN 32u 00086 00087 00088 /** ============================================================================ 00089 * @name RingIO_OpenMode 00090 * 00091 * @brief Enumeration of RingIO open modes. 00092 * 00093 * @param RINGIO_MODE_READ 00094 * Reader mode. 00095 * @param RINGIO_MODE_WRITE 00096 * Writer mode. 00097 * ============================================================================ 00098 */ 00099 typedef enum{ 00100 RINGIO_MODE_READ = 0u, 00101 RINGIO_MODE_WRITE 00102 } RingIO_OpenMode ; 00103 00104 /** ============================================================================ 00105 * @name RingIO_TransportType 00106 * 00107 * @brief Enumeration of RingIO transport types. 00108 * 00109 * @param RINGIO_TRANSPORT_DSP_DSP 00110 * Intra-DSP transport. 00111 * @param RINGIO_TRANSPORT_GPP_DSP 00112 * GPP<->DSP transport. 00113 * ============================================================================ 00114 */ 00115 typedef enum{ 00116 RINGIO_TRANSPORT_DSP_DSP = 1u, 00117 RINGIO_TRANSPORT_GPP_DSP 00118 } RingIO_TransportType ; 00119 00120 /** ============================================================================ 00121 * @name RingIO_NotifyType 00122 * 00123 * @brief Enumeration of RingIO notification types. 00124 * 00125 * @param RINGIO_NOTIFICATION_NONE 00126 * No notification required. 00127 * @param RINGIO_NOTIFICATION_ALWAYS 00128 * Notify whenever the other side sends data/frees up space. 00129 * @param RINGIO_NOTIFICATION_ONCE 00130 * Notify when the other side sends data/frees up space. Once the 00131 * notification is done, the notification is disabled until it is 00132 * enabled again 00133 * @param RINGIO_NOTIFICATION_HDWRFIFO_ALWAYS 00134 * Notify whenever the other side sends data/frees up space. 00135 * This notification is never disabled. 00136 * @param RINGIO_NOTIFICATION_HDWRFIFO_ONCE 00137 * Notify when the other side sends data/frees up space. Once the 00138 * notification is done, the notification is disabled until it is 00139 * enabled again. The notification is enabled once the watermark 00140 * is crossed and does not require buffer to get full/empty. 00141 * 00142 * ============================================================================ 00143 */ 00144 typedef enum { 00145 RINGIO_NOTIFICATION_NONE = 0u, 00146 RINGIO_NOTIFICATION_ALWAYS, 00147 RINGIO_NOTIFICATION_ONCE, 00148 RINGIO_NOTIFICATION_HDWRFIFO_ALWAYS, 00149 RINGIO_NOTIFICATION_HDWRFIFO_ONCE 00150 00151 } RingIO_NotifyType ; 00152 00153 00154 /** ============================================================================ 00155 * @name RingIO_Handle 00156 * 00157 * @brief This type is used for the handle to the RingIO Client structure. 00158 * ============================================================================ 00159 */ 00160 typedef Void * RingIO_Handle ; 00161 00162 /** ============================================================================ 00163 * @name RingIO_ControlHandle 00164 * 00165 * @brief This type is used for the handle to the Shared Control structure. 00166 * ============================================================================ 00167 */ 00168 typedef struct RingIO_ControlStruct_tag * RingIO_ControlHandle ; 00169 00170 /** ============================================================================ 00171 * @name RingIO_BufPtr 00172 * 00173 * @brief This type is used for the Buffer Pointer Type. 00174 * ============================================================================ 00175 */ 00176 typedef Void * RingIO_BufPtr ; 00177 00178 /** ============================================================================ 00179 * @name RingIO_NotifyParam 00180 * 00181 * @brief This type is used for the Notification Parameter. 00182 * ============================================================================ 00183 */ 00184 typedef Void * RingIO_NotifyParam ; 00185 00186 /** ============================================================================ 00187 * @name RingIO_NotifyMsg 00188 * 00189 * @brief This type is used for the Notification Message. 00190 * ============================================================================ 00191 */ 00192 00193 typedef Uint16 RingIO_NotifyMsg; 00194 00195 /** ============================================================================ 00196 * @name RingIO_NotifyFunc 00197 * 00198 * @brief Signature of function used as the Notification function. 00199 * 00200 * @param handle 00201 * Handle to the RingIO. 00202 * @param param 00203 * Parameter used while registering the notification. 00204 * @param msg 00205 * Message passed along with notification. 00206 * 00207 * @return None. 00208 * ============================================================================ 00209 */ 00210 typedef Void (* RingIO_NotifyFunc) (RingIO_Handle handle, 00211 RingIO_NotifyParam param, 00212 RingIO_NotifyMsg msg) ; 00213 00214 00215 /** ============================================================================ 00216 * @name RingIO_Attrs 00217 * 00218 * @brief This structure defines the RingIO Creation Parameters. 00219 * 00220 * @param transportType 00221 * Transport type - This specifies whether the data transport is 00222 * between DSP<-> DSP or DSP<->ARM. 00223 * @param ctrlPoolId 00224 * Pool to be used to allocate memory for control structure. 00225 * @param dataPoolId 00226 * Pool to be used to allocate memory for data buffer. 00227 * @param attrPoolId 00228 * Pool to be used to allocate memory for attribute buffer. 00229 * @param lockPoolId 00230 * Pool to be used to allocate memory for lock structure. 00231 * @param dataBufSize 00232 * Data Buffer Size in bytes. 00233 * @param footBufSize 00234 * Footer area for providing contiguous buffer to a reader. 00235 * @param attrBufSize 00236 * Attribute buffer size in bytes. 00237 * ============================================================================ 00238 */ 00239 typedef struct RingIO_Attrs_tag { 00240 RingIO_TransportType transportType ; 00241 PoolId ctrlPoolId ; 00242 PoolId dataPoolId ; 00243 PoolId attrPoolId ; 00244 PoolId lockPoolId ; 00245 Uint32 dataBufSize ; 00246 Uint32 footBufSize ; 00247 Uint32 attrBufSize ; 00248 } RingIO_Attrs ; 00249 00250 /** ============================================================================ 00251 * @name RingIO_ControlStruct 00252 * 00253 * @brief Forward declaration of RingIO_ControlStruct. 00254 * ============================================================================ 00255 */ 00256 typedef struct RingIO_ControlStruct_tag RingIO_ControlStruct; 00257 00258 /** ============================================================================ 00259 * @name RingIO_Client 00260 * 00261 * @brief This structure defines the RingIO Shared memory client structure. 00262 * The RingIO Reader or Writer state information is stored in this 00263 * structure 00264 * 00265 * @param procId 00266 * Processor Id where the client is executing 00267 * @param openMode 00268 * Indicates whether the client is a reader or writer 00269 * @param pDataStart 00270 * Virtual start address of the data buffer 00271 * @param pAttrStart 00272 * Virtual start address of the attr buffer 00273 * @param acqStart 00274 * Start offset of data buffer that has been acquired by the 00275 * application. 00276 * @param acqSize 00277 * Size of data that has been acquired 00278 * @param acqAttrStart 00279 * Start offset of the acquired attribute buffer 00280 * @param acqAttrSize 00281 * Size of attribute data that has been acquired 00282 * @param notifyType 00283 * Notification type 00284 * @param notifyFunc 00285 * Notification function for this client 00286 * @param notifyParam 00287 * Parameter to the Notification function 00288 * @param notifyWaterMark 00289 * Watermark that should be satisfied before notification is done 00290 * @param flags 00291 * Counting bits from MSB to LSB 0....31 00292 * B31 - Denotes whether the client uses cache for accessing the 00293 * data buffer (dataBufCacheUseFlag) 00294 * B30 - Denotes whether the client uses cache for accessing the 00295 * attribute buffer (attrBufCacheUseFlag) 00296 * B29 - Denotes whether the client uses cache for accessing the 00297 * control struct (controlStructCacheFlag) 00298 * B28 - Denotes whether requests for acquire buffer should always 00299 * be satisfied. If a contiguous request could not be 00300 * satisfied because of the buffer wrap, we need to mark an 00301 * early end and provide only a contiguous buffer 00302 * (contiguousBufFlag) 00303 * @param virtControlHandle 00304 * Handle to the Control structure. Apps do not have direct access 00305 * to the control structure. The Control structure can only be 00306 * accessed through the client handle 00307 * @param virtLockHandle 00308 * Virtual (GPP) address of the lock that should be used to protect 00309 * the Control structure from multiple accesses. 00310 * @param isValid 00311 * Indicates whether the Client is initialized 00312 * @param notifyFlag 00313 * Denotes whether notification needs to be done or not 00314 * @param refCount 00315 * Denotes whether RingIO has been re-opened or not 00316 * @param padding 00317 * Padding. 00318 * ============================================================================ 00319 */ 00320 typedef struct RingIO_Client_tag { 00321 Uint32 procId ; 00322 Uint32 openMode ; 00323 RingIO_BufPtr pDataStart ; 00324 RingIO_BufPtr pAttrStart ; 00325 Uint32 acqStart ; 00326 Uint32 acqSize ; 00327 Uint32 acqAttrStart ; 00328 Uint32 acqAttrSize ; 00329 Uint32 notifyType ; 00330 RingIO_NotifyFunc notifyFunc ; 00331 RingIO_NotifyParam notifyParam ; 00332 Uint32 notifyWaterMark ; 00333 Uint32 flags ; 00334 RingIO_ControlStruct * virtControlHandle ; 00335 Void * virtLockHandle; 00336 Uint32 isValid ; 00337 Uint32 refCount ; 00338 Uint16 notifyFlag ; 00339 ADD_PADDING (padding, RINGIO_CLIENT_PADDING) 00340 } RingIO_Client ; 00341 00342 /** ============================================================================ 00343 * @name RingIO_ControlStruct 00344 * 00345 * @brief This structure defines the RingIO Control Structure. This structure 00346 * is stored in shared memory and is accessible by all clients. The 00347 * control structure supports a single reader and a single writer for 00348 * the ring buffer. 00349 * 00350 * @param procId 00351 * ID of DSP processor. 00352 * @param entryId 00353 * ID of the RingIO within the entry array. 00354 * @param transportType 00355 * Transport type - This specifies whether the data transport is 00356 * between DSP<-> DSP or DSP<->ARM. 00357 * @param phyBufStart 00358 * Physical start address of the data buffer. 00359 * @param phyBufEnd 00360 * Total size of the Data buffer (offset from phyBufStart) 00361 * @param curBufEnd 00362 * Current buffer size. This may be <= dataBufEnd (offset from 00363 * phyBufStart) 00364 * @param dataBufEnd 00365 * Size of the main data buffer (offset from phyBufStart) 00366 * @param dataBufSize 00367 * Size of the data buffer 00368 * @param footBufSize 00369 * Size of the foot buffer used for providing linear buffer to a 00370 * reader 00371 * @param validSize 00372 * Amount of valid data available in the data buffer. Valid Data is 00373 * the total data that is readable by the reader using an acquire 00374 * call. This does not include the size of the data buffer already 00375 * acquired by the reader 00376 * @param emptySize 00377 * Amount of empty space in the data buffer. This does not include 00378 the empty space already acquired by the writer 00379 * @param phyAttrStart 00380 * Physical start address of the attr buffer 00381 * @param phyAttrBufEnd 00382 * Total Size of the attribute buffer (offset) 00383 * @param curAttrBufEnd 00384 * Current Attr buffer size. This may be <= the phyAttrBufEnd 00385 * (offset) 00386 * @param validAttrSize 00387 * Amount of valid attribute bytes available in the attribute 00388 * buffer. The valid attribute bytes does not include the attribute 00389 * bytes already acquired by the reader 00390 * @param emptyAttrSize 00391 * Amount of empty space in the attr buffer. This does not include 00392 * the empty attr space already acquired by the writer 00393 * @param prevAttrOffset 00394 * Offset of the most recent attribute 00395 * @param phyLockHandle 00396 * Physical (DSP) address of the lock that should be used to 00397 * protect the Control structure from multiple accesses. 00398 * @param padding 00399 * Padding. 00400 * @param writer 00401 * Writer state information 00402 * @param reader 00403 * Reader state information 00404 * ============================================================================ 00405 */ 00406 struct RingIO_ControlStruct_tag { 00407 Uint32 procId ; 00408 Uint32 entryId; 00409 Uint32 transportType; 00410 RingIO_BufPtr phyBufStart; 00411 Uint32 phyBufEnd; 00412 Uint32 curBufEnd; 00413 Uint32 dataBufEnd; 00414 Uint32 dataBufSize; 00415 Uint32 footBufSize; 00416 Uint32 validSize; 00417 Uint32 emptySize; 00418 RingIO_BufPtr phyAttrStart; 00419 Uint32 phyAttrBufEnd; 00420 Uint32 curAttrBufEnd; 00421 Uint32 validAttrSize; 00422 Uint32 emptyAttrSize; 00423 Int32 prevAttrOffset; 00424 Void * phyLockHandle; 00425 ADD_PADDING (padding, RINGIO_CONTROLSTRUCT_PADDING) 00426 RingIO_Client writer ; 00427 RingIO_Client reader ; 00428 } ; 00429 00430 /** ============================================================================ 00431 * @name RingIO_Entry 00432 * 00433 * @brief Entry structure for the RingIO data transport 00434 * 00435 * @param name 00436 * System wide unique identifier for the RingIO 00437 * @param phyControl 00438 * Physical (DSP) address of the Control structure for the RingIO. 00439 * @param virtControl 00440 * Virtual (GPP) address of the Control structure for the RingIO. 00441 * @param ownerProcId 00442 * Creator's processor ID of this ringio. 00443 * @param ctrlPoolId 00444 * Pool to be used to allocate memory for control structure. 00445 * @param dataPoolId 00446 * Pool to be used to allocate memory for data buffer. 00447 * @param attrPoolId 00448 * Pool to be used to allocate memory for attribute buffer. 00449 * @param lockPoolId 00450 * Pool to be used to allocate memory for lock structure. 00451 * @param padding 00452 * Padding. 00453 * ============================================================================ 00454 */ 00455 typedef struct RingIO_Entry_tag { 00456 Pvoid phyControl ; 00457 Pvoid virtControl ; 00458 Char8 name [RINGIO_NAME_MAX_LEN] ; 00459 PoolId ownerProcId ; 00460 PoolId ctrlPoolId ; 00461 PoolId dataPoolId ; 00462 PoolId attrPoolId ; 00463 PoolId lockPoolId ; 00464 ADD_PADDING (padding, RINGIO_ENTRY_PADDING) 00465 } RingIO_Entry ; 00466 00467 /** ============================================================================ 00468 * @name RingIO_Ctrl 00469 * 00470 * @brief This structure defines the control structure required by the 00471 * RINGIO component. It contains information about all RINGIO objects 00472 * shared between the GPP and a specific DSP. 00473 * 00474 * @param isInitialized 00475 * Flag to indicate if this region was initialized 00476 * @param dspId 00477 * ID of the DSP with which the RingIO Region is shared 00478 * @param maxEntries 00479 * Maximum number of RingIO instances supported by the RingIO. 00480 * @param ipsId 00481 * ID of the IPS to be used. 00482 * @param ipsEventNo 00483 * IPS Event number associated with the RingIO. 00484 * @param dspAddrEntry 00485 * Pointer to array in DSP address space of RINGIO objects that can 00486 * be created. 00487 * @param padding 00488 * Padding. 00489 * @param lockObj 00490 * Lock used to protect the shared RingIO_Ctrl from multiple 00491 * simultaneous accesses. 00492 * ============================================================================ 00493 */ 00494 typedef struct RingIO_Ctrl_tag { 00495 Uint32 isInitialized ; 00496 Uint32 dspId ; 00497 Uint32 maxEntries ; 00498 Uint32 ipsId ; 00499 Uint32 ipsEventNo ; 00500 RingIO_Entry * dspAddrEntry ; 00501 ADD_PADDING (padding, RINGIO_CTRL_PADDING) 00502 MPCS_ShObj lockObj ; 00503 } RingIO_Ctrl ; 00504 00505 00506 /** ============================================================================ 00507 * @deprecated The deprecated data structure RingIOEntry has been replaced 00508 * with RingIOEntry 00509 * 00510 * ============================================================================ 00511 */ 00512 #define RingIOEntry RingIO_Entry 00513 00514 /** ============================================================================ 00515 * @deprecated The deprecated data structure RingIORegion has been replaced 00516 * with RingIO_Ctrl 00517 * 00518 * ============================================================================ 00519 */ 00520 #define RingIORegion RingIO_Ctrl 00521 00522 /** ============================================================================ 00523 * @deprecated The deprecated API RingIO_SendNotify has been replaced 00524 * with RingIO_sendNotify 00525 * 00526 * ============================================================================ 00527 */ 00528 #define RingIO_SendNotify RingIO_sendNotify 00529 00530 #if defined (__cplusplus) 00531 } 00532 #endif /* defined (__cplusplus) */ 00533 00534 00535 #endif /* if !defined (RINGIODEFS_H) */