Main Page | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

gpp/inc/ringiodefs.h

Go to the documentation of this file.
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) */

Generated on Fri Jul 16 14:34:03 2010 for DSP/BIOSLink by  doxygen 1.4.4