drivers/staging/imgtec/rogue/tlclient.h

   1 /*************************************************************************/ /*!
   2 @File           tlclient.h
   3 @Title          Services Transport Layer shared API
   4 @Copyright      Copyright (c) Imagination Technologies Ltd. All Rights Reserved
   5 @Description    Transport layer common API used in both clients and server
   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
  44 #ifndef TLCLIENT_H_
  45 #define TLCLIENT_H_
  46
  47
  48 #include "img_defs.h"
  49 #include "pvrsrv_error.h"
  50
  51
  52 /* This value is used for the hSrvHandle argument in the client API when
  53  * called directly from the kernel which will lead to a direct bridge access.
  54  */
  55 #define DIRECT_BRIDGE_HANDLE    ((IMG_HANDLE)0xDEADBEEFU)
  56
  57
  58 /**************************************************************************/ /*!
  59  @Function              TLClientOpenStream
  60  @Description   Open a descriptor onto an existing kernel transport stream.
  61  @Input                 hSrvHandle      Address of a pointer to a connection object
  62  @Input                 pszName                 Address of the stream name string, no longer
  63                                                                 than PRVSRVTL_MAX_STREAM_NAME_SIZE.
  64  @Input                 ui32Mode                Unused
  65  @Output                phSD                    Address of a pointer to an stream object
  66  @Return                PVRSRV_ERROR_NOT_FOUND:        when named stream not found
  67  @Return                PVRSRV_ERROR_ALREADY_OPEN:     stream already open by another
  68  @Return                PVRSRV_ERROR_STREAM_ERROR:     internal driver state error
  69  @Return        PVRSRV_ERROR_TIMEOUT:          block timed out, stream not found
  70  @Return                PVRSRV_ERROR:                          for other system codes
  71 */ /***************************************************************************/
  72 IMG_INTERNAL
  73 PVRSRV_ERROR TLClientOpenStream(IMG_HANDLE hSrvHandle,
  74                 const IMG_CHAR* pszName,
  75                 IMG_UINT32   ui32Mode,
  76                 IMG_HANDLE*  phSD);
  77
  78
  79 /**************************************************************************/ /*!
  80  @Function              TLClientCloseStream
  81  @Description   Close and release the stream connection to Services kernel
  82                                 server transport layer. Any outstanding Acquire will be
  83                                 released.
  84  @Input                 hSrvHandle      Address of a pointer to a connection object
  85  @Input                 hSD                             Handle of the stream object to close
  86  @Return                PVRSRV_ERROR_HANDLE_NOT_FOUND: when SD handle is not known
  87  @Return                PVRSRV_ERROR_STREAM_ERROR:        internal driver state error
  88  @Return                PVRSRV_ERROR:                             for system codes
  89 */ /***************************************************************************/
  90 IMG_INTERNAL
  91 PVRSRV_ERROR TLClientCloseStream(IMG_HANDLE hSrvHandle,
  92                 IMG_HANDLE hSD);
  93
  94 /**************************************************************************/ /*!
  95  @Function      TLClientDiscoverStreams
  96  @Description   Finds all streams that's name starts with pszNamePattern and
  97                 ends with a number.
  98  @Input         hSrvHandle      Address of a pointer to a connection object
  99  @Input         pszNamePattern  Name pattern. Must be beginning of a string.
 100  @Output        pui32Streams    Array of numbers from end of the discovered
 101                 names.
 102  @inOut         pui32Count      When input max number of number that can fit
 103                                 into pui32Streams. When output number of
 104                                 discovered streams.
 105  @Return                PVRSRV_ERROR    for system codes
 106 */ /***************************************************************************/
 107 IMG_INTERNAL
 108 PVRSRV_ERROR TLClientDiscoverStreams(IMG_HANDLE hSrvHandle,
 109                 const IMG_CHAR *pszNamePattern,
 110                 IMG_UINT32 *pui32Streams,
 111                 IMG_UINT32 *pui32NumFound);
 112
 113 /**************************************************************************/ /*!
 114  @Function      TLClientReserveStream
 115  @Description   Reserves a region with given size in the stream. If the stream
 116                 is already reserved the function will return an error.
 117  @Input         hSrvHandle      Address of a pointer to a connection object
 118  @Input         hSD             Handle of the stream object to close
 119  @Output        ppui8Data       pointer to the buffer
 120  @Input         ui32Size        size of the data
 121  @Return
 122 */ /***************************************************************************/
 123 IMG_INTERNAL
 124 PVRSRV_ERROR TLClientReserveStream(IMG_HANDLE hSrvHandle,
 125                 IMG_HANDLE hSD,
 126                 IMG_UINT8 **ppui8Data,
 127                 IMG_UINT32 ui32Size);
 128
 129 /**************************************************************************/ /*!
 130  @Function      TLClientStreamReserve2
 131  @Description   Reserves a region with given size in the stream. If the stream
 132                 is already reserved the function will return an error.
 133  @Input         hSrvHandle      Address of a pointer to a connection object
 134  @Input         hSD             Handle of the stream object to close
 135  @Output        ppui8Data       pointer to the buffer
 136  @Input         ui32Size        size of the data
 137  @Input         ui32SizeMin     minimum size of the data
 138  @Input         ui32Available   available space in buffer
 139  @Return
 140 */ /***************************************************************************/
 141 IMG_INTERNAL
 142 PVRSRV_ERROR TLClientReserveStream2(IMG_HANDLE hSrvHandle,
 143                 IMG_HANDLE hSD,
 144                 IMG_UINT8 **ppui8Data,
 145                 IMG_UINT32 ui32Size,
 146                 IMG_UINT32 ui32SizeMin,
 147                 IMG_UINT32 *pui32Available);
 148
 149 /**************************************************************************/ /*!
 150  @Function      TLClientStreamCommit
 151  @Description   Commits previously reserved region in the stream and therefore
 152                 allows next reserves.
 153                 This function call has to be preceded by the call to
 154                 TLClientReserveStream or TLClientReserveStream2.
 155  @Input         hSrvHandle      Address of a pointer to a connection object
 156  @Input         hSD             Handle of the stream object to close
 157  @Input         ui32Size        Size of the data
 158  @Return
 159 */ /***************************************************************************/
 160 IMG_INTERNAL
 161 PVRSRV_ERROR TLClientCommitStream(IMG_HANDLE hSrvHandle,
 162                 IMG_HANDLE hSD,
 163                 IMG_UINT32 ui32Size);
 164
 165 /**************************************************************************/ /*!
 166  @Function              TLClientAcquireData
 167  @Description   When there is data available in the stream buffer this call
 168                                 returns with the address and length of the data buffer the
 169                                 client can safely read. This buffer may contain one or more
 170                                 packets of data.
 171                                 If no data is available then this call blocks until it becomes
 172                                 available. However if the stream has been destroyed while
 173                                 waiting then a resource unavailable error will be returned
 174                                 to the caller. Clients must pair this call with a
 175                                 ReleaseData call.
 176  @Input                 hSrvHandle      Address of a pointer to a connection object
 177  @Input                 hSD                             Handle of the stream object to read
 178  @Output                ppPacketBuf             Address of a pointer to an byte buffer. On exit
 179                                                                 pointer contains address of buffer to read from
 180  @Output                puiBufLen               Pointer to an integer. On exit it is the size
 181                                                                 of the data to read from the packet buffer
 182  @Return                PVRSRV_ERROR_RESOURCE_UNAVAILABLE: when stream no longer exists
 183  @Return                PVRSRV_ERROR_HANDLE_NOT_FOUND:     when SD handle not known
 184  @Return                PVRSRV_ERROR_STREAM_ERROR:             internal driver state error
 185  @Return                PVRSRV_ERROR_RETRY:                                release not called beforehand
 186  @Return        PVRSRV_ERROR_TIMEOUT:              block timed out, no data
 187  @Return                PVRSRV_ERROR:                                      for other system codes
 188 */ /***************************************************************************/
 189 IMG_INTERNAL
 190 PVRSRV_ERROR TLClientAcquireData(IMG_HANDLE hSrvHandle,
 191                 IMG_HANDLE  hSD,
 192                 IMG_PBYTE*  ppPacketBuf,
 193                 IMG_UINT32* puiBufLen);
 194
 195
 196 /**************************************************************************/ /*!
 197  @Function              TLClientReleaseData
 198  @Description   Called after client has read the stream data out of the buffer
 199                                 The data is subsequently flushed from the stream buffer to make
 200                                 room for more data packets from the stream source.
 201  @Input                 hSrvHandle      Address of a pointer to a connection object
 202  @Input                 hSD                             Handle of the stream object to read
 203  @Return                PVRSRV_ERROR_RESOURCE_UNAVAILABLE: when stream no longer exists
 204  @Return                PVRSRV_ERROR_HANDLE_NOT_FOUND:   when SD handle not known to TL
 205  @Return                PVRSRV_ERROR_STREAM_ERROR:           internal driver state error
 206  @Return                PVRSRV_ERROR_RETRY:                              acquire not called beforehand
 207  @Return                PVRSRV_ERROR:                    for system codes
 208 */ /***************************************************************************/
 209 IMG_INTERNAL
 210 PVRSRV_ERROR TLClientReleaseData(IMG_HANDLE hSrvHandle,
 211                 IMG_HANDLE hSD);
 212
 213 /**************************************************************************/ /*!
 214  @Function      TLClientWriteData
 215  @Description   Writes data to the stream.
 216  @Input         hSrvHandle      Address of a pointer to a connection object
 217  @Input         hSD             Handle of the stream object to read
 218  @Input         ui32Size        Size of the data
 219  @Input         pui8Data        Pointer to data
 220 */ /***************************************************************************/
 221 IMG_INTERNAL
 222 PVRSRV_ERROR TLClientWriteData(IMG_HANDLE hSrvHandle,
 223                 IMG_HANDLE hSD,
 224                 IMG_UINT32 ui32Size,
 225                 IMG_BYTE *pui8Data);
 226
 227
 228 #endif /* TLCLIENT_H_ */
 229
 230 /******************************************************************************
 231  End of file (tlclient.h)
 232 ******************************************************************************/