drivers/gpu/rogue_m/services/server/include/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_DROP_DATA:
  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_BLOCKING_RESERVE:
  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
  85 /*! Flags specifying stream and circular buffer behaviour */
  86 /*! Discard new data if the buffer is full */
  87 #define TL_FLAG_DROP_DATA              (1U<<0)
  88 /*! Block Reserve (subsequently Write) calls if there is not enough space
  89  *    until some space is freed. */
  90 #define TL_FLAG_BLOCKING_RESERVE            (1U<<1)
  91 /*! Do not destroy stream if there still are data that have not been
  92  *     copied in user space. BLock until the stream is emptied. */
  93 #define TL_FLAG_FORCE_FLUSH            (1U<<2)
  94 /*! Do not signal consumers on commit automatically when the stream buffer
  95  * transitions from empty to non-empty. Producer responsible for signal when
  96  * it chooses. */
  97 #define TL_FLAG_NO_SIGNAL_ON_COMMIT    (1U<<3)
  98
  99 /*! Structure used to pass internal TL stream sizes information to users.*/
 100 typedef struct _TL_STREAM_INFO_
 101 {
 102     IMG_UINT32 headerSize;          /*!< Packet header size in bytes */
 103     IMG_UINT32 minReservationSize;  /*!< Minimum data size reserved in bytes */
 104     IMG_UINT32 pageSize;            /*!< Page size in bytes */
 105     IMG_UINT32 pageAlign;           /*!< Page alignment in bytes */
 106 } TL_STREAM_INFO, *PTL_STREAM_INFO;
 107
 108 /*! Callback operations or notifications that a stream producer may handle
 109  * when requested by the Transport Layer.
 110  */
 111 #define TL_SOURCECB_OP_CLIENT_EOS 0x01  /*!< Client has reached end of stream,
 112                                          * can anymore data be supplied?
 113                                          * ui32Resp ignored in this operation */
 114
 115 /*! Function pointer type for the callback handler into the "producer" code
 116  * that writes data to the TL stream.  Producer should handle the notification
 117  * or operation supplied in ui32ReqOp on stream hStream. The
 118  * Operations and notifications are defined above in TL_SOURCECB_OP */
 119 typedef PVRSRV_ERROR (*TL_STREAM_SOURCECB)(IMG_HANDLE hStream,
 120                 IMG_UINT32 ui32ReqOp, IMG_UINT32* ui32Resp, IMG_VOID* pvUser);
 121
 122 /*************************************************************************/ /*!
 123  @Function      TLStreamCreate
 124  @Description   Request the creation of a new stream and open a handle.
 125                                 If creating a stream which should continue to exist after the
 126                                 current context is finished, then TLStreamCreate must be
 127                                 followed by a TLStreamOpen call. On any case, the number of
 128                                 create/open calls must balance with the number of close calls
 129                                 used. This ensures the resources of a stream are released when
 130                                 it is no longer required.
 131  @Output        phStream        Pointer to handle to store the new stream.
 132  @Input         szStreamName    Name of stream, maximum length:
 133                                   PRVSRVTL_MAX_STREAM_NAME_SIZE.
 134                                   If a longer string is provided,creation fails.
 135  @Input         ui32Size        Desired buffer size in bytes.
 136  @Input         ui32StreamFlags Flags that configure buffer behaviour.See above.
 137  @Input         pfProducerDB    Optional callback, may be null.
 138  @Input         pvProducerData  Optional user data for callback, may be null.
 139  @Return        PVRSRV_ERROR_INVALID_PARAMS  NULL stream handle or string name
 140                                                exceeded MAX_STREAM_NAME_SIZE
 141  @Return        PVRSRV_ERROR_OUT_OF_MEMORY   Failed to allocate space for stream
 142                                                handle.
 143  @Return        PVRSRV_ERROR_DUPLICATE_VALUE There already exists a stream with
 144                                                                                            the same stream name string.
 145  @Return        eError                       Internal services call returned
 146                                                eError error number.
 147  @Return        PVRSRV_OK
 148 */ /**************************************************************************/
 149 PVRSRV_ERROR
 150 TLStreamCreate(IMG_HANDLE *phStream,
 151                IMG_CHAR   *szStreamName,
 152                IMG_UINT32 ui32Size,
 153                IMG_UINT32 ui32StreamFlags,
 154                TL_STREAM_SOURCECB pfProducerCB,
 155                IMG_PVOID pvProducerUD);
 156
 157 /*************************************************************************/ /*!
 158  @Function      TLStreamOpen
 159  @Description   Attach to existing stream that has already been created by a
 160                   TLStreamCreate call. A handle is returned to the stream.
 161  @Output        phStream        Pointer to handle to store the stream.
 162  @Input         szStreamName    Name of stream, should match an already
 163                                   existing stream name
 164  @Return        PVRSRV_ERROR_NOT_FOUND        None of the streams matched the
 165                                                  requested stream name.
 166                                 PVRSRV_ERROR_INVALID_PARAMS        non NULL pointer to stream
 167                                                                                              handler is required.
 168  @Return        PVRSRV_OK                      Success.
 169 */ /**************************************************************************/
 170 PVRSRV_ERROR
 171 TLStreamOpen(IMG_HANDLE *phStream,
 172              IMG_CHAR   *szStreamName);
 173
 174 /*************************************************************************/ /*!
 175  @Function      TLStreamClose
 176  @Description   Detach from the stream associated with the given handle. If
 177                   the current handle is the last one accessing the stream
 178                                   (i.e. the number of TLStreamCreate+TLStreamOpen calls matches
 179                                   the number of TLStreamClose calls) then the stream is also
 180                                   deleted.
 181                                 On return the handle is no longer valid.
 182  @Input         hStream     Handle to stream that will be closed.
 183  @Return        None.
 184 */ /**************************************************************************/
 185 IMG_VOID
 186 TLStreamClose(IMG_HANDLE hStream);
 187
 188 /*************************************************************************/ /*!
 189  @Function      TLStreamReserve
 190  @Description   Reserve space in stream buffer. When successful every
 191                   TLStreamReserve call must be followed by a matching
 192                   TLStreamCommit call. While a TLStreamCommit call is pending
 193                   for a stream, subsequent TLStreamReserve calls for this
 194                   stream will fail.
 195  @Input         hStream         Stream handle.
 196  @Output        ppui8Data       Pointer to a pointer to a location in the
 197                                   buffer. The caller can then use this address
 198                                   in writing data into the stream.
 199  @Input         ui32Size        Number of bytes to reserve in buffer.
 200  @Return        PVRSRV_INVALID_PARAMS       NULL stream handler.
 201  @Return        PVRSRV_ERROR_NOT_READY      There are data previously reserved
 202                                               that are pending to be committed.
 203  @Return        PVRSRV_ERROR_STREAM_MISUSE  Misusing the stream by trying to
 204                                               reserve more space than the
 205                                               buffer size.
 206                 PVRSRV_ERROR_STREAM_FULL    Stream buffer full, data not written
 207  @Return        PVRSRV_OK                   Success, output arguments valid.
 208 */ /**************************************************************************/
 209 PVRSRV_ERROR
 210 TLStreamReserve(IMG_HANDLE hStream,
 211                 IMG_UINT8  **ppui8Data,
 212                 IMG_UINT32 ui32Size);
 213
 214 /*************************************************************************/ /*!
 215  @Function      TLStreamReserve2
 216  @Description   Reserve space in stream buffer. When successful every
 217                   TLStreamReserve call must be followed by a matching
 218                   TLStreamCommit call. While a TLStreamCommit call is pending
 219                   for a stream, subsequent TLStreamReserve calls for this
 220                   stream will fail.
 221  @Input         hStream         Stream handle.
 222  @Output        ppui8Data       Pointer to a pointer to a location in the
 223                                   buffer. The caller can then use this address
 224                                   in writing data into the stream.
 225  @Input         ui32Size        Ideal number of bytes to reserve in buffer.
 226  @Input         ui32SizeMin     Minimum number of bytes to reserve in buffer.
 227  @Input         pui32Available  Optional, but when present and the FULL error
 228                                   is returned, a size suggestion is returned
 229                                                                   in this argument which the caller can attempt
 230                                   to reserve again for a successful allocation.
 231  @Return        PVRSRV_INVALID_PARAMS       NULL stream handler.
 232  @Return        PVRSRV_ERROR_NOT_READY      There are data previously reserved
 233                                               that are pending to be committed.
 234  @Return        PVRSRV_ERROR_STREAM_MISUSE  Misusing the stream by trying to
 235                                               reserve more space than the
 236                                               buffer size.
 237                 PVRSRV_ERROR_STREAM_FULL    Stream buffer full, data not written
 238  @Return        PVRSRV_OK                   Success, output arguments valid.
 239 */ /**************************************************************************/
 240 PVRSRV_ERROR
 241 TLStreamReserve2(IMG_HANDLE hStream,
 242                 IMG_UINT8  **ppui8Data,
 243                 IMG_UINT32 ui32Size,
 244                 IMG_UINT32 ui32SizeMin,
 245                 IMG_UINT32* pui32Available);
 246
 247 /*************************************************************************/ /*!
 248  @Function      TLStreamCommit
 249  @Description   Notify TL that data have been written in the stream buffer.
 250                   Should always follow and match TLStreamReserve call.
 251  @Input         hStream         Stream handle.
 252  @Input         ui32Size        Number of bytes that have been added to the
 253                                   stream.
 254  @Return        PVRSRV_ERROR_INVALID_PARAMS  NULL stream handle.
 255  @Return        PVRSRV_ERROR_STREAM_MISUSE   Commit results in more data
 256                                                committed than the buffer size,
 257                                                the stream is misused.
 258  @Return        eError                       Commit was successful but
 259                                                internal services call returned
 260                                                eError error number.
 261  @Return        PVRSRV_OK
 262 */ /**************************************************************************/
 263 PVRSRV_ERROR
 264 TLStreamCommit(IMG_HANDLE hStream,
 265                IMG_UINT32 ui32Size);
 266
 267 /*************************************************************************/ /*!
 268  @Function      TLStreamWrite
 269  @Description   Combined Reserve/Commit call. This function Reserves space in
 270                   the specified stream buffer, copies ui32Size bytes of data
 271                   from the array pui8Src points to and Commits in an "atomic"
 272                   style operation.
 273  @Input         hStream         Stream handle.
 274  @Input         pui8Src         Source to read data from.
 275  @Input         ui32Size        Number of bytes to copy and commit.
 276  @Return        PVRSRV_ERROR_INVALID_PARAMS  NULL stream handler.
 277  @Return        eError                       Error codes returned by either
 278                                                Reserve or Commit.
 279  @Return        PVRSRV_OK
 280  */ /**************************************************************************/
 281 PVRSRV_ERROR
 282 TLStreamWrite(IMG_HANDLE hStream,
 283               IMG_UINT8  *pui8Src,
 284               IMG_UINT32 ui32Size);
 285
 286 /*************************************************************************/ /*!
 287  @Function      TLStreamSync
 288  @Description   Signal the consumer to start acquiring data from the stream
 289                 buffer. Called by producers that use the TL_FLAG_NO_SIGNAL_ON_COMMIT
 290                 flag to manually control when consumers starting reading the
 291                 stream. Used when multiple small writes need to be batched.
 292  @Input         hStream         Stream handle.
 293  @Return        PVRSRV_ERROR_INVALID_PARAMS  NULL stream handle.
 294  @Return        eError                       Error codes returned by either
 295                                                Reserve or Commit.
 296  @Return        PVRSRV_OK
 297  */ /**************************************************************************/
 298 PVRSRV_ERROR
 299 TLStreamSync(IMG_HANDLE hStream);
 300
 301
 302 /*************************************************************************/ /*!
 303  @Function      TLStreamMarkEOS
 304  @Description   Insert a EOS marker packet in the given stream.
 305  @Input         hStream         Stream handle.
 306  @Return        PVRSRV_ERROR_INVALID_PARAMS     NULL stream handler.
 307  @Return        eError                          Error codes returned by either
 308                                               Reserve or Commit.
 309  @Return        PVRSRV_OK                               Success.
 310 */ /**************************************************************************/
 311 PVRSRV_ERROR
 312 TLStreamMarkEOS(IMG_HANDLE hStream);
 313
 314 /*************************************************************************/ /*!
 315  @Function      TLStreamInfo
 316  @Description   Run time information about buffer elemental sizes.
 317                 It sets psInfo members accordingly. Users can use those values
 318                 to calculate the parameters they use in TLStreamCreate and
 319                 TLStreamReserve.
 320  @Output        psInfo          pointer to stream info structure.
 321  @Return        None.
 322 */ /**************************************************************************/
 323 IMG_VOID
 324 TLStreamInfo(PTL_STREAM_INFO psInfo);
 325
 326
 327 #endif /* __TLSTREAM_H__ */
 328 /*****************************************************************************
 329  End of file (tlstream.h)
 330 *****************************************************************************/
 331