drivers/staging/imgtec/rogue/tlintern.h

   1 /*************************************************************************/ /*!
   2 @File
   3 @Title          Transport Layer internals
   4 @Copyright      Copyright (c) Imagination Technologies Ltd. All Rights Reserved
   5 @Description    Transport Layer header used by TL internally
   6 @License        Dual MIT/GPLv2
   7
   8 The contents of this file are subject to the MIT license as set out below.
   9
  10 Permission is hereby granted, free of charge, to any person obtaining a copy
  11 of this software and associated documentation files (the "Software"), to deal
  12 in the Software without restriction, including without limitation the rights
  13 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  14 copies of the Software, and to permit persons to whom the Software is
  15 furnished to do so, subject to the following conditions:
  16
  17 The above copyright notice and this permission notice shall be included in
  18 all copies or substantial portions of the Software.
  19
  20 Alternatively, the contents of this file may be used under the terms of
  21 the GNU General Public License Version 2 ("GPL") in which case the provisions
  22 of GPL are applicable instead of those above.
  23
  24 If you wish to allow use of your version of this file only under the terms of
  25 GPL, and not to allow others to use your version of this file under the terms
  26 of the MIT license, indicate your decision by deleting the provisions above
  27 and replace them with the notice and other provisions required by GPL as set
  28 out in the file called "GPL-COPYING" included in this distribution. If you do
  29 not delete the provisions above, a recipient may use your version of this file
  30 under the terms of either the MIT license or GPL.
  31
  32 This License is also included in this distribution in the file called
  33 "MIT-COPYING".
  34
  35 EXCEPT AS OTHERWISE STATED IN A NEGOTIATED AGREEMENT: (A) THE SOFTWARE IS
  36 PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
  37 BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  38 PURPOSE AND NONINFRINGEMENT; AND (B) IN NO EVENT SHALL THE AUTHORS OR
  39 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  40 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  41 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  42 */ /**************************************************************************/
  43 #ifndef __TLINTERN_H__
  44 #define __TLINTERN_H__
  45
  46
  47 #include "devicemem_typedefs.h"
  48 #include "pvrsrv_tlcommon.h"
  49 #include "device.h"
  50 #include "lock.h"
  51
  52 /* Forward declarations */
  53 typedef struct _TL_SNODE_* PTL_SNODE;
  54
  55 /*! TL stream structure container.
  56  *    pbyBuffer   holds the circular buffer.
  57  *    ui32Read    points to the beginning of the buffer, ie to where data to
  58  *                  Read begin.
  59  *    ui32Write   points to the end of data that have been committed, ie this is
  60  *                  where new data will be written.
  61  *    ui32Pending number of bytes reserved in last reserve call which have not
  62  *                  yet been submitted. Therefore these data are not ready to
  63  *                  be transported.
  64  *    hStreamLock - provides atomic protection for the ui32Pending & ui32Write
  65  *                  members of the structure for when they are checked and/or
  66  *                  updated in the context of a stream writer (producer)
  67  *                  calling DoTLStreamReserve() & TLStreamCommit().
  68  *                - Reader context is not multi-threaded, only one client per
  69  *                  stream is allowed. Also note the read context may be in an
  70  *                  ISR which prevents a design where locks can be held in the
  71  *                  AcquireData/ReleaseData() calls. Thus this lock only
  72  *                  protects the stream members from simultaneous writers.
  73  *
  74  *      ui32Read < ui32Write <= ui32Pending
  75  *        where < and <= operators are overloaded to make sense in a circular way.
  76  */
  77 typedef struct _TL_STREAM_
  78 {
  79         IMG_CHAR                        szName[PRVSRVTL_MAX_STREAM_NAME_SIZE];  /*!< String name identifier */
  80         IMG_BOOL                        bDrop;                                  /*!< Flag: When buffer is full drop new data instead of
  81                                                                                                                    overwriting older data */
  82         IMG_BOOL                        bBlock;                                 /*!< Flag: When buffer is full reserve will block until there is
  83                                                                                                                    enough free space in the buffer to fullfil the request. */
  84         IMG_BOOL                        bWaitForEmptyOnDestroy; /*!< Flag: On destroying a non empty stream block until
  85                                                                                                                    stream is drained. */
  86         IMG_BOOL            bNoSignalOnCommit;      /*!< Flag: Used to avoid the TL signalling waiting consumers
  87                                                            that new data is available on every commit. Producers
  88                                                            using this flag will need to manually signal when
  89                                                            appropriate using the TLStreamSync() API */
  90
  91         void                            (*pfOnReaderOpenCallback)(void *); /*!< Optional on reader connect callback */
  92         void                            *pvOnReaderOpenUserData; /*!< On reader connect user data */
  93         void                            (*pfProducerCallback)(void); /*!< Optional producer callback of type TL_STREAM_SOURCECB */
  94         void                            *pvProducerUserData;                 /*!< Producer callback user data */
  95
  96         volatile IMG_UINT32 ui32Read;                           /*!< Pointer to the beginning of available data */
  97         volatile IMG_UINT32 ui32Write;                          /*!< Pointer to already committed data which are ready to be
  98                                                                                                          copied to user space*/
  99         IMG_UINT32                      ui32BufferUt;                   /*!< Buffer utilisation high watermark, see
 100                                                                                                  * TL_BUFFER_UTILIZATION in tlstream.c */
 101         IMG_UINT32                      ui32Pending;                    /*!< Count pending bytes reserved in buffer */
 102         IMG_UINT32                      ui32Size;                               /*!< Buffer size */
 103         IMG_BYTE                        *pbyBuffer;                             /*!< Actual data buffer */
 104
 105         PTL_SNODE                       psNode;                                 /*!< Ptr to parent stream node */
 106         DEVMEM_MEMDESC          *psStreamMemDesc;               /*!< MemDescriptor used to allocate buffer space through PMR */
 107
 108         IMG_HANDLE                      hProducerEvent;                 /*!< Handle to wait on if there is not enough space */
 109         IMG_HANDLE                      hProducerEventObj;              /*!< Handle to signal blocked reserve calls */
 110
 111         POS_LOCK                        hStreamLock;                    /*!< Writers Lock for ui32Pending & ui32Write*/
 112 } TL_STREAM, *PTL_STREAM;
 113
 114 /* there need to be enough space reserved in the buffer for 2 minimal packets
 115  * and it needs to be aligned the same way the buffer is or there will be a
 116  * compile error.*/
 117 #define BUFFER_RESERVED_SPACE 2*PVRSRVTL_PACKET_ALIGNMENT
 118
 119 /* ensure the space reserved follows the buffer's alignment */
 120 static_assert(!(BUFFER_RESERVED_SPACE&(PVRSRVTL_PACKET_ALIGNMENT-1)),
 121                           "BUFFER_RESERVED_SPACE must be a multiple of PVRSRVTL_PACKET_ALIGNMENT");
 122
 123 /* Define the largest value that a uint that matches the
 124  * PVRSRVTL_PACKET_ALIGNMENT size can hold */
 125 #define MAX_UINT 0xffffFFFF
 126
 127 /*! Defines the value used for TL_STREAM.ui32Pending when no reserve is
 128  * outstanding on the stream. */
 129 #define NOTHING_PENDING IMG_UINT32_MAX
 130
 131
 132 /*
 133  * Transport Layer Stream Descriptor types/defs
 134  */
 135 typedef struct _TL_STREAM_DESC_
 136 {
 137         PTL_SNODE       psNode;                 /*!< Ptr to parent stream node */
 138         IMG_UINT32      ui32Flags;
 139         IMG_HANDLE      hReadEvent;     /*!< For wait call (only used/set in reader descriptors) */
 140         IMG_INT         uiRefCount;     /*!< Reference count to the SD */
 141 } TL_STREAM_DESC, *PTL_STREAM_DESC;
 142
 143 PTL_STREAM_DESC TLMakeStreamDesc(PTL_SNODE f1, IMG_UINT32 f2, IMG_HANDLE f3);
 144
 145 #define TL_STREAM_KM_FLAG_MASK  0xFFFF0000
 146 #define TL_STREAM_FLAG_TEST             0x10000000
 147 #define TL_STREAM_FLAG_WRAPREAD 0x00010000
 148
 149 #define TL_STREAM_UM_FLAG_MASK  0x0000FFFF
 150
 151 /*
 152  * Transport Layer stream list node
 153  */
 154 typedef struct _TL_SNODE_
 155 {
 156         struct _TL_SNODE_*  psNext;                             /*!< Linked list next element */
 157         IMG_HANDLE                      hReadEventObj;          /*!< Readers 'wait for data' event */
 158         PTL_STREAM                      psStream;                       /*!< TL Stream object */
 159         IMG_INT                         uiWRefCount;            /*!< Stream writer reference count */
 160         PTL_STREAM_DESC         psRDesc;                        /*!< Stream reader 0 or ptr only */
 161         PTL_STREAM_DESC         psWDesc;                        /*!< Stream writer 0 or ptr only */
 162 } TL_SNODE;
 163
 164 PTL_SNODE TLMakeSNode(IMG_HANDLE f2, TL_STREAM *f3, TL_STREAM_DESC *f4);
 165
 166 /*
 167  * Transport Layer global top types and variables
 168  * Use access function to obtain pointer.
 169  *
 170  * hTLGDLock - provides atomicity over read/check/write operations and
 171  *             sequence of operations on uiClientCnt, psHead list of SNODEs and
 172  *             the immediate members in a list element SNODE structure.
 173  *           - This larger scope of responsibility for this lock helps avoid
 174  *             the need for a lock in the SNODE structure.
 175  *           - Lock held in the client (reader) context when streams are
 176  *             opened/closed and in the server (writer) context when streams
 177  *             are created/open/closed.
 178  */
 179 typedef struct _TL_GDATA_
 180 {
 181         void      *psRgxDevNode;        /* Device node to use for buffer allocations */
 182         IMG_HANDLE hTLEventObj;         /* Global TL signal object, new streams, etc */
 183
 184         IMG_UINT   uiClientCnt;         /* Counter to track the number of client stream connections. */
 185         PTL_SNODE  psHead;              /* List of TL streams and associated client handle */
 186
 187         POS_LOCK        hTLGDLock;          /* Lock for structure AND psHead SNODE list */
 188 } TL_GLOBAL_DATA, *PTL_GLOBAL_DATA;
 189
 190 /*
 191  * Transport Layer Internal Kernel-Mode Server API
 192  */
 193 TL_GLOBAL_DATA* TLGGD(void);            /* TLGetGlobalData() */
 194
 195 PVRSRV_ERROR TLInit(PVRSRV_DEVICE_NODE *psDevNode);
 196 void TLDeInit(PVRSRV_DEVICE_NODE *psDevNode);
 197
 198 PVRSRV_DEVICE_NODE* TLGetGlobalRgxDevice(void);
 199
 200 void  TLAddStreamNode(PTL_SNODE psAdd);
 201 PTL_SNODE TLFindStreamNodeByName(const IMG_CHAR *pszName);
 202 PTL_SNODE TLFindStreamNodeByDesc(PTL_STREAM_DESC psDesc);
 203 IMG_UINT32 TLDiscoverStreamNodes(const IMG_CHAR *pszNamePattern,
 204                                  IMG_UINT32 *pui32Streams,
 205                                  IMG_UINT32 ui32Max);
 206 PTL_SNODE TLFindAndGetStreamNodeByDesc(PTL_STREAM_DESC psDesc);
 207 void TLReturnStreamNode(PTL_SNODE psNode);
 208
 209 /****************************************************************************************
 210  Function Name  : TLTryRemoveStreamAndFreeStreamNode
 211
 212  Inputs         : PTL_SNODE     Pointer to the TL_SNODE whose stream is requested
 213                         to be removed from TL_GLOBAL_DATA's list
 214
 215  Return Value   : IMG_TRUE      -       If the stream was made NULL and this
 216                                         TL_SNODE was removed from the
 217                                         TL_GLOBAL_DATA's list
 218
 219                   IMG_FALSE     -       If the stream wasn't made NULL as there
 220                                         is a client connected to this stream
 221
 222  Description    : If there is no client currently connected to this stream then,
 223                         This function removes this TL_SNODE from the
 224                         TL_GLOBAL_DATA's list. The caller is responsible for the
 225                         cleanup of the TL_STREAM whose TL_SNODE may be removed
 226
 227                   Otherwise, this function does nothing
 228 *****************************************************************************************/
 229 IMG_BOOL  TLTryRemoveStreamAndFreeStreamNode(PTL_SNODE psRemove);
 230
 231 /*****************************************************************************************
 232  Function Name  : TLUnrefDescAndTryFreeStreamNode
 233
 234  Inputs         : PTL_SNODE     Pointer to the TL_SNODE whose descriptor is
 235                         requested to be removed
 236                         : PTL_STREAM_DESC       Pointer to the STREAM_DESC
 237
 238  Return Value   : IMG_TRUE      -       If this TL_SNODE was removed from the
 239                                         TL_GLOBAL_DATA's list
 240
 241                   IMG_FALSE     -       Otherwise
 242
 243  Description    : This function removes the stream descriptor from this TL_SNODE
 244                   and,
 245                   If there is no writer (producer context) currently bound to this stream,
 246                         This function removes this TL_SNODE from the
 247                         TL_GLOBAL_DATA's list. The caller is responsible for the
 248                         cleanup of the TL_STREAM whose TL_SNODE may be removed
 249 ******************************************************************************************/
 250 IMG_BOOL  TLUnrefDescAndTryFreeStreamNode(PTL_SNODE psRemove, PTL_STREAM_DESC psSD);
 251
 252 /*
 253  * Transport Layer stream interface to server part declared here to avoid
 254  * circular dependency.
 255  */
 256 IMG_UINT32 TLStreamAcquireReadPos(PTL_STREAM psStream, IMG_UINT32* puiReadOffset);
 257 void TLStreamAdvanceReadPos(PTL_STREAM psStream, IMG_UINT32 uiReadLen);
 258
 259 DEVMEM_MEMDESC* TLStreamGetBufferPointer(PTL_STREAM psStream);
 260 IMG_BOOL TLStreamEOS(PTL_STREAM psStream);
 261
 262 /****************************************************************************************
 263  Function Name  : TLStreamDestroy
 264
 265  Inputs         : PTL_STREAM    Pointer to the TL_STREAM to be destroyed
 266
 267  Description    : This function performs all the clean-up operations required for
 268                         destruction of this stream
 269 *****************************************************************************************/
 270 void TLStreamDestroy (PTL_STREAM);
 271
 272 /*
 273  * Test related functions
 274  */
 275 PVRSRV_ERROR TUtilsInit (PVRSRV_DEVICE_NODE *psDeviceNode);
 276 PVRSRV_ERROR TUtilsDeinit (PVRSRV_DEVICE_NODE *psDeviceNode);
 277
 278
 279 #endif /* __TLINTERN_H__ */
 280 /******************************************************************************
 281  End of file (tlintern.h)
 282 ******************************************************************************/
 283