drivers/staging/imgtec/rogue/tlstream.h

   1 /*************************************************************************/ /*!
   2 @File
   3 @Title          Transport Layer kernel side API.
   4 @Copyright      Copyright (c) Imagination Technologies Ltd. All Rights Reserved
   5 @Description    TL provides driver components with a way to copy data from kernel
   6                 space to user space (e.g. screen/file).
   7
   8                 Data can be passed to the Transport Layer through the
   9                 TL Stream (kernel space) API interface.
  10
  11                 The buffer provided to every stream is a modified version of a
  12                 circular buffer. Which CB version is created is specified by
  13                 relevant flags when creating a stream. Currently two types
  14                 of buffer are available:
  15                 - TL_FLAG_RESERVE_DROP_NEWER:
  16                   When the buffer is full, incoming data are dropped
  17                   (instead of overwriting older data) and a marker is set
  18                   to let the user know that data have been lost.
  19                 - TL_FLAG_RESERVE_BLOCK:
  20                   When the circular buffer is full, reserve/write calls block
  21                   until enough space is freed.
  22
  23                 All size/space requests are in bytes. However, the actual
  24                 implementation uses native word sizes (i.e. 4 byte aligned).
  25
  26                 The user does not need to provide space for the stream buffer
  27                 as the TL handles memory allocations and usage.
  28
  29                 Inserting data to a stream's buffer can be done either:
  30                 - by using TLReserve/TLCommit: User is provided with a buffer
  31                                                  to write data to.
  32                 - or by using TLWrite:         User provides a buffer with
  33                                                  data to be committed. The TL
  34                                                  copies the data from the
  35                                                  buffer into the stream buffer
  36                                                  and returns.
  37                 Users should be aware that there are implementation overheads
  38                 associated with every stream buffer. If you find that less
  39                 data are captured than expected then try increasing the
  40                 stream buffer size or use TLInfo to obtain buffer parameters
  41                 and calculate optimum required values at run time.
  42 @License        Dual MIT/GPLv2
  43
  44 The contents of this file are subject to the MIT license as set out below.
  45
  46 Permission is hereby granted, free of charge, to any person obtaining a copy
  47 of this software and associated documentation files (the "Software"), to deal
  48 in the Software without restriction, including without limitation the rights
  49 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  50 copies of the Software, and to permit persons to whom the Software is
  51 furnished to do so, subject to the following conditions:
  52
  53 The above copyright notice and this permission notice shall be included in
  54 all copies or substantial portions of the Software.
  55
  56 Alternatively, the contents of this file may be used under the terms of
  57 the GNU General Public License Version 2 ("GPL") in which case the provisions
  58 of GPL are applicable instead of those above.
  59
  60 If you wish to allow use of your version of this file only under the terms of
  61 GPL, and not to allow others to use your version of this file under the terms
  62 of the MIT license, indicate your decision by deleting the provisions above
  63 and replace them with the notice and other provisions required by GPL as set
  64 out in the file called "GPL-COPYING" included in this distribution. If you do
  65 not delete the provisions above, a recipient may use your version of this file
  66 under the terms of either the MIT license or GPL.
  67
  68 This License is also included in this distribution in the file called
  69 "MIT-COPYING".
  70
  71 EXCEPT AS OTHERWISE STATED IN A NEGOTIATED AGREEMENT: (A) THE SOFTWARE IS
  72 PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
  73 BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  74 PURPOSE AND NONINFRINGEMENT; AND (B) IN NO EVENT SHALL THE AUTHORS OR
  75 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  76 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  77 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  78 */ /**************************************************************************/
  79 #ifndef __TLSTREAM_H__
  80 #define __TLSTREAM_H__
  81
  82
  83 #include "img_types.h"
  84 #include "pvrsrv_error.h"
  85
  86 /*! Flags specifying stream and circular buffer behaviour */
  87 /*! Reject new data if the buffer is full, producer may then decide to
  88  *    drop the data or retry after some time. */
  89 #define TL_FLAG_RESERVE_DROP_NEWER     (1U<<0)
  90 /*! Block Reserve (subsequently Write) calls if there is not enough space
  91  *    until some space is freed via a client read operation. */
  92 #define TL_FLAG_RESERVE_BLOCK          (1U<<1)
  93 /*! When buffer is full, advance the tail/read position to accept the new
  94  * reserve call (size permitting), effectively overwriting the oldest
  95  * data in the circular buffer. Not supported yet. */
  96 #define TL_FLAG_RESERVE_DROP_OLDEST    (1U<<2)
  97
  98 /*! Do not destroy stream if there still are data that have not been
  99  *     copied in user space. BLock until the stream is emptied. */
 100 #define TL_FLAG_FORCE_FLUSH            (1U<<8)
 101 /*! Do not signal consumers on commit automatically when the stream buffer
 102  * transitions from empty to non-empty. Producer responsible for signal when
 103  * it chooses. */
 104 #define TL_FLAG_NO_SIGNAL_ON_COMMIT    (1U<<9)
 105
 106 /*! Defer allocation of stream's shared memory until first open. */
 107 #define TL_FLAG_ALLOCATE_ON_FIRST_OPEN (1U<<10)
 108
 109 /*! Structure used to pass internal TL stream sizes information to users.*/
 110 typedef struct _TL_STREAM_INFO_
 111 {
 112     IMG_UINT32 headerSize;          /*!< Packet header size in bytes */
 113     IMG_UINT32 minReservationSize;  /*!< Minimum data size reserved in bytes */
 114     IMG_UINT32 pageSize;            /*!< Page size in bytes */
 115     IMG_UINT32 pageAlign;           /*!< Page alignment in bytes */
 116 } TL_STREAM_INFO, *PTL_STREAM_INFO;
 117
 118 /*! Callback operations or notifications that a stream producer may handle
 119  * when requested by the Transport Layer.
 120  */
 121 #define TL_SOURCECB_OP_CLIENT_EOS 0x01  /*!< Client has reached end of stream,
 122                                          * can anymore data be supplied?
 123                                          * ui32Resp ignored in this operation */
 124
 125 /*! Function pointer type for the callback handler into the "producer" code
 126  * that writes data to the TL stream.  Producer should handle the notification
 127  * or operation supplied in ui32ReqOp on stream hStream. The
 128  * Operations and notifications are defined above in TL_SOURCECB_OP */
 129 typedef PVRSRV_ERROR (*TL_STREAM_SOURCECB)(IMG_HANDLE hStream,
 130                 IMG_UINT32 ui32ReqOp, IMG_UINT32* ui32Resp, void* pvUser);
 131
 132 typedef void (*TL_STREAM_ONREADEROPENCB)(void *pvArg);
 133
 134 /*************************************************************************/ /*!
 135  @Function      TLAllocSharedMem
 136  @Description   Allocates shared memory for the stream.
 137  @Input         phStream    Stream handle.
 138  @Return        eError      Internal services call returned eError error
 139                             number.
 140  @Return        PVRSRV_OK
 141 */ /**************************************************************************/
 142 PVRSRV_ERROR
 143 TLAllocSharedMemIfNull(IMG_HANDLE hStream);
 144
 145 /*************************************************************************/ /*!
 146  @Function      TLFreeSharedMem
 147  @Description   Frees stream's shared memory.
 148  @Input         phStream    Stream handle.
 149 */ /**************************************************************************/
 150 void
 151 TLFreeSharedMem(IMG_HANDLE hStream);
 152
 153 /*************************************************************************/ /*!
 154  @Function      TLStreamCreate
 155  @Description   Request the creation of a new stream and open a handle.
 156                                 If creating a stream which should continue to exist after the
 157                                 current context is finished, then TLStreamCreate must be
 158                                 followed by a TLStreamOpen call. On any case, the number of
 159                                 create/open calls must balance with the number of close calls
 160                                 used. This ensures the resources of a stream are released when
 161                                 it is no longer required.
 162  @Output        phStream        Pointer to handle to store the new stream.
 163  @Input         szStreamName    Name of stream, maximum length:
 164                                   PRVSRVTL_MAX_STREAM_NAME_SIZE.
 165                                   If a longer string is provided,creation fails.
 166  @Input         ui32Size        Desired buffer size in bytes.
 167  @Input         ui32StreamFlags Flags that configure buffer behaviour.See above.
 168  @Input         pfProducerDB    Optional callback, may be null.
 169  @Input         pvProducerData  Optional user data for callback, may be null.
 170  @Return        PVRSRV_ERROR_INVALID_PARAMS  NULL stream handle or string name
 171                                                exceeded MAX_STREAM_NAME_SIZE
 172  @Return        PVRSRV_ERROR_OUT_OF_MEMORY   Failed to allocate space for stream
 173                                                handle.
 174  @Return        PVRSRV_ERROR_DUPLICATE_VALUE There already exists a stream with
 175                                                                                            the same stream name string.
 176  @Return        eError                       Internal services call returned
 177                                                eError error number.
 178  @Return        PVRSRV_OK
 179 */ /**************************************************************************/
 180 PVRSRV_ERROR
 181 TLStreamCreate(IMG_HANDLE *phStream,
 182                IMG_CHAR   *szStreamName,
 183                IMG_UINT32 ui32Size,
 184                IMG_UINT32 ui32StreamFlags,
 185                TL_STREAM_ONREADEROPENCB pfOnReaderOpenCB,
 186                void *pvOnReaderOpenUD,
 187                TL_STREAM_SOURCECB pfProducerCB,
 188                void *pvProducerUD);
 189
 190 /*************************************************************************/ /*!
 191  @Function      TLStreamOpen
 192  @Description   Attach to existing stream that has already been created by a
 193                   TLStreamCreate call. A handle is returned to the stream.
 194  @Output        phStream        Pointer to handle to store the stream.
 195  @Input         szStreamName    Name of stream, should match an already
 196                                   existing stream name
 197  @Return        PVRSRV_ERROR_NOT_FOUND        None of the streams matched the
 198                                                  requested stream name.
 199                                 PVRSRV_ERROR_INVALID_PARAMS        non NULL pointer to stream
 200                                                                                              handler is required.
 201  @Return        PVRSRV_OK                      Success.
 202 */ /**************************************************************************/
 203 PVRSRV_ERROR
 204 TLStreamOpen(IMG_HANDLE *phStream,
 205              IMG_CHAR   *szStreamName);
 206
 207 /*************************************************************************/ /*!
 208  @Function      TLStreamReconfigure
 209  @Description   Request the stream flags controlling buffer behaviour to
 210                 be updated.
 211                 In the case where TL_FLAG_RESERVE_BLOCK is to be used,
 212                 TLStreamCreate should be called without that flag and this
 213                 function used to change the stream mode once a consumer process
 214                 has been started. This avoids a deadlock scenario where the
 215                 TLStreaWrite/TLStreamReserve call will hold the Bridge Lock
 216                 while blocking if the TL buffer is full.
 217                 The TL_FLAG_RESERVE_BLOCK should never drop the Bridge Lock
 218                 as this leads to another deadlock scenario where the caller to
 219                 TLStreamWrite/TLStreamReserve has already acquired another lock
 220                 (eg. gHandleLock) which is not dropped. This then leads to that
 221                 thead acquiring locks out of order.
 222  @Input         hStream         Handle to stream to update.
 223  @Input         ui32StreamFlags Flags that configure buffer behaviour. See above.
 224  @Return        PVRSRV_ERROR_INVALID_PARAMS  NULL stream handle or inconsistent
 225                                              stream flags.
 226  @Return        PVRSRV_ERROR_NOT_READY       Stream is currently being written to
 227                                              try again later.
 228  @Return        eError                       Internal services call returned
 229                                                eError error number.
 230  @Return        PVRSRV_OK
 231 */ /**************************************************************************/
 232 PVRSRV_ERROR
 233 TLStreamReconfigure(
 234                 IMG_HANDLE hStream,
 235                 IMG_UINT32 ui32StreamFlags);
 236
 237 /*************************************************************************/ /*!
 238  @Function      TLStreamClose
 239  @Description   Detach from the stream associated with the given handle. If
 240                   the current handle is the last one accessing the stream
 241                                   (i.e. the number of TLStreamCreate+TLStreamOpen calls matches
 242                                   the number of TLStreamClose calls) then the stream is also
 243                                   deleted.
 244                                 On return the handle is no longer valid.
 245  @Input         hStream     Handle to stream that will be closed.
 246  @Return        None.
 247 */ /**************************************************************************/
 248 void
 249 TLStreamClose(IMG_HANDLE hStream);
 250
 251 /*************************************************************************/ /*!
 252  @Function      TLStreamReserve
 253  @Description   Reserve space in stream buffer. When successful every
 254                   TLStreamReserve call must be followed by a matching
 255                   TLStreamCommit call. While a TLStreamCommit call is pending
 256                   for a stream, subsequent TLStreamReserve calls for this
 257                   stream will fail.
 258  @Input         hStream         Stream handle.
 259  @Output        ppui8Data       Pointer to a pointer to a location in the
 260                                   buffer. The caller can then use this address
 261                                   in writing data into the stream.
 262  @Input         ui32Size        Number of bytes to reserve in buffer.
 263  @Return        PVRSRV_INVALID_PARAMS       NULL stream handler.
 264  @Return        PVRSRV_ERROR_NOT_READY      There are data previously reserved
 265                                               that are pending to be committed.
 266  @Return        PVRSRV_ERROR_STREAM_MISUSE  Misusing the stream by trying to
 267                                               reserve more space than the
 268                                               buffer size.
 269  @Return        PVRSRV_ERROR_STREAM_RESERVE_TOO_BIG  The reserve size requested
 270                                                      is larger than the free
 271                                                      space or maximum supported
 272                                                      packet size.
 273  @Return        PVRSRV_OK                   Success, output arguments valid.
 274 */ /**************************************************************************/
 275 PVRSRV_ERROR
 276 TLStreamReserve(IMG_HANDLE hStream,
 277                 IMG_UINT8  **ppui8Data,
 278                 IMG_UINT32 ui32Size);
 279
 280 /*************************************************************************/ /*!
 281  @Function      TLStreamReserve2
 282  @Description   Reserve space in stream buffer. When successful every
 283                   TLStreamReserve call must be followed by a matching
 284                   TLStreamCommit call. While a TLStreamCommit call is pending
 285                   for a stream, subsequent TLStreamReserve calls for this
 286                   stream will fail.
 287  @Input         hStream         Stream handle.
 288  @Output        ppui8Data       Pointer to a pointer to a location in the
 289                                   buffer. The caller can then use this address
 290                                   in writing data into the stream.
 291  @Input         ui32Size        Ideal number of bytes to reserve in buffer.
 292  @Input         ui32SizeMin     Minimum number of bytes to reserve in buffer.
 293  @Input         pui32Available  Optional, but when present and the
 294                                   RESERVE_TOO_BIG error is returned, a size
 295                                   suggestion is returned in this argument which
 296                                   the caller can attempt to reserve again for a
 297                                   successful allocation.
 298  @Return        PVRSRV_INVALID_PARAMS       NULL stream handler.
 299  @Return        PVRSRV_ERROR_NOT_READY      There are data previously reserved
 300                                               that are pending to be committed.
 301  @Return        PVRSRV_ERROR_STREAM_MISUSE  Misusing the stream by trying to
 302                                               reserve more space than the
 303                                               buffer size.
 304  @Return        PVRSRV_ERROR_STREAM_RESERVE_TOO_BIG  The reserve size requested
 305                                                      is larger than the free
 306                                                      space or maximum supported
 307                                                      packet size.
 308                                                      Check the pui32Available
 309                                                      value for the correct
 310                                                      reserve size to use.
 311  @Return        PVRSRV_OK                   Success, output arguments valid.
 312 */ /**************************************************************************/
 313 PVRSRV_ERROR
 314 TLStreamReserve2(IMG_HANDLE hStream,
 315                 IMG_UINT8  **ppui8Data,
 316                 IMG_UINT32 ui32Size,
 317                 IMG_UINT32 ui32SizeMin,
 318                 IMG_UINT32* pui32Available);
 319
 320 /*************************************************************************/ /*!
 321  @Function      TLStreamCommit
 322  @Description   Notify TL that data have been written in the stream buffer.
 323                   Should always follow and match TLStreamReserve call.
 324  @Input         hStream         Stream handle.
 325  @Input         ui32Size        Number of bytes that have been added to the
 326                                   stream.
 327  @Return        PVRSRV_ERROR_INVALID_PARAMS  NULL stream handle.
 328  @Return        PVRSRV_ERROR_STREAM_MISUSE   Commit results in more data
 329                                                committed than the buffer size,
 330                                                the stream is misused.
 331  @Return        eError                       Commit was successful but
 332                                                internal services call returned
 333                                                eError error number.
 334  @Return        PVRSRV_OK
 335 */ /**************************************************************************/
 336 PVRSRV_ERROR
 337 TLStreamCommit(IMG_HANDLE hStream,
 338                IMG_UINT32 ui32Size);
 339
 340 /*************************************************************************/ /*!
 341  @Function      TLStreamWrite
 342  @Description   Combined Reserve/Commit call. This function Reserves space in
 343                   the specified stream buffer, copies ui32Size bytes of data
 344                   from the array pui8Src points to and Commits in an "atomic"
 345                   style operation.
 346  @Input         hStream         Stream handle.
 347  @Input         pui8Src         Source to read data from.
 348  @Input         ui32Size        Number of bytes to copy and commit.
 349  @Return        PVRSRV_ERROR_INVALID_PARAMS  NULL stream handler.
 350  @Return        eError                       Error codes returned by either
 351                                                Reserve or Commit.
 352  @Return        PVRSRV_OK
 353  */ /**************************************************************************/
 354 PVRSRV_ERROR
 355 TLStreamWrite(IMG_HANDLE hStream,
 356               IMG_UINT8  *pui8Src,
 357               IMG_UINT32 ui32Size);
 358
 359 /*************************************************************************/ /*!
 360  @Function      TLStreamSync
 361  @Description   Signal the consumer to start acquiring data from the stream
 362                 buffer. Called by producers that use the TL_FLAG_NO_SIGNAL_ON_COMMIT
 363                 flag to manually control when consumers starting reading the
 364                 stream. Used when multiple small writes need to be batched.
 365  @Input         hStream         Stream handle.
 366  @Return        PVRSRV_ERROR_INVALID_PARAMS  NULL stream handle.
 367  @Return        eError                       Error codes returned by either
 368                                                Reserve or Commit.
 369  @Return        PVRSRV_OK
 370  */ /**************************************************************************/
 371 PVRSRV_ERROR
 372 TLStreamSync(IMG_HANDLE hStream);
 373
 374
 375 /*************************************************************************/ /*!
 376  @Function      TLStreamMarkEOS
 377  @Description   Insert a EOS marker packet in the given stream.
 378  @Input         hStream         Stream handle.
 379  @Return        PVRSRV_ERROR_INVALID_PARAMS     NULL stream handler.
 380  @Return        eError                          Error codes returned by either
 381                                               Reserve or Commit.
 382  @Return        PVRSRV_OK                               Success.
 383 */ /**************************************************************************/
 384 PVRSRV_ERROR
 385 TLStreamMarkEOS(IMG_HANDLE hStream);
 386
 387 /*************************************************************************/ /*!
 388  @Function      TLStreamInfo
 389  @Description   Run time information about buffer elemental sizes.
 390                 It sets psInfo members accordingly. Users can use those values
 391                 to calculate the parameters they use in TLStreamCreate and
 392                 TLStreamReserve.
 393  @Output        psInfo          pointer to stream info structure.
 394  @Return        None.
 395 */ /**************************************************************************/
 396 void
 397 TLStreamInfo(PTL_STREAM_INFO psInfo);
 398
 399
 400 #endif /* __TLSTREAM_H__ */
 401 /*****************************************************************************
 402  End of file (tlstream.h)
 403 *****************************************************************************/
 404