1 /*************************************************************************/ /*!
3 @Title Services Transport Layer UM Client API
4 @Copyright Copyright (c) Imagination Technologies Ltd. All Rights Reserved
5 @Description User mode Transport layer API for clients.
6 @License Dual MIT/GPLv2
8 The contents of this file are subject to the MIT license as set out below.
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:
17 The above copyright notice and this permission notice shall be included in
18 all copies or substantial portions of the Software.
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.
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.
32 This License is also included in this distribution in the file called
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 */ /**************************************************************************/
47 #if defined (__cplusplus)
53 #include "pvrsrv_error.h"
56 #include "pvr_tlcommon.h"
59 /**************************************************************************/ /*!
60 @Function PVRSRVTLConnect
61 @Description Initialise connection to Services kernel server transport layer
62 @Output ppsConnection Address of a pointer to a connection object
63 @Return PVRSRV_ERROR: for system error codes
64 */ /***************************************************************************/
66 PVRSRV_ERROR IMG_CALLCONV PVRSRVTLConnect(PVRSRV_CONNECTION **ppsConnection);
69 /**************************************************************************/ /*!
70 @Function PVRSRVTLDisconnect
71 @Description Disconnect from the Services kernel server transport layer
72 @Input psConnection Pointer to connection object as returned from
74 @Return PVRSRV_ERROR: for system error codes
75 */ /***************************************************************************/
77 PVRSRV_ERROR IMG_CALLCONV PVRSRVTLDisconnect(PVRSRV_CONNECTION* psConnection);
80 /**************************************************************************/ /*!
81 @Function PVRSRVTLOpenStream
82 @Description Open a descriptor onto an existing PVR transport stream. If
83 the stream does not exist it returns a NOT_FOUND error unless
84 the OPEN_WAIT flag is supplied. In this case it will wait for
85 the stream to be created. If it is not created in the wait
86 period a TIMEOUT error is returned.
87 @Input psConnection Address of a pointer to a connection object
88 @Input pszName Address of the stream name string, no longer
89 than PRVSRVTL_MAX_STREAM_NAME_SIZE.
90 @Input ui32Mode Flags defined in pvr_tlcommon.h
91 ACQUIRE_NONBLOCKING: Results in non-blocking reads
92 on stream. Reads are blocking by default
93 OPEN_WAIT: Causes open to wait for a brief moment
94 if the stream does not exist
95 @Output phSD Address of a pointer to an stream object
96 @Return PVRSRV_ERROR_NOT_FOUND: when named stream not found
97 @Return PVRSRV_ERROR_ALREADY_OPEN: stream already open by another
98 @Return PVRSRV_ERROR_STREAM_ERROR: internal driver state error
99 @Return PVRSRV_ERROR_TIMEOUT: block timed out, stream not found
100 @Return PVRSRV_ERROR: for other system codes
101 */ /***************************************************************************/
103 PVRSRV_ERROR IMG_CALLCONV PVRSRVTLOpenStream(PVRSRV_CONNECTION* psConnection,
109 /**************************************************************************/ /*!
110 @Function PVRSRVTLCloseStream
111 @Description Close and release the stream connection to Services kernel
112 server transport layer. Any outstanding Acquire will be
114 @Input psConnection Address of a pointer to a connection object
115 @Input hSD Handle of the stream object to close
116 @Return PVRSRV_ERROR_HANDLE_NOT_FOUND: when SD handle is not known
117 @Return PVRSRV_ERROR_STREAM_ERROR: internal driver state error
118 @Return PVRSRV_ERROR: for system codes
119 */ /***************************************************************************/
121 PVRSRV_ERROR IMG_CALLCONV PVRSRVTLCloseStream(PVRSRV_CONNECTION* psConnection,
126 /****************************************************************************
127 * Stream Buffer Data retrieval API(s)
129 * The client must ensure their use of this acquire/release API for a single
130 * connection/stream must not be shared with multiple execution contexts e.g.
131 * between a kernel thread and an ISR handler. It is the client’s
132 * responsibility to ensure this API is not interrupted by a high priority
134 ****************************************************************************/
136 /**************************************************************************/ /*!
137 @Function PVRSRVTLAcquireData
138 @Description When there is data available in the stream buffer this call
139 returns with the address and length of the data buffer the
140 client can safely read. This buffer may contain one or more
142 If no data is available then this call blocks until it becomes
143 available. However if the stream has been destroyed while
144 waiting then a resource unavailable error will be returned
145 to the caller. Clients must pair this call with a
147 @Input psConnection Address of a pointer to a connection object
148 @Input hSD Handle of the stream object to read
149 @Output ppPacketBuf Address of a pointer to an byte buffer. On exit
150 pointer contains address of buffer to read from
151 @Output puiBufLen Pointer to an integer. On exit it is the size
152 of the data to read from the packet buffer
153 @Return PVRSRV_ERROR_RESOURCE_UNAVAILABLE: when stream no longer exists
154 @Return PVRSRV_ERROR_HANDLE_NOT_FOUND: when SD handle not known
155 @Return PVRSRV_ERROR_STREAM_ERROR: internal driver state error
156 @Return PVRSRV_ERROR_RETRY: release not called beforehand
157 @Return PVRSRV_ERROR_TIMEOUT: block timed out, no data
158 @Return PVRSRV_ERROR: for other system codes
159 */ /***************************************************************************/
161 PVRSRV_ERROR IMG_CALLCONV PVRSRVTLAcquireData(PVRSRV_CONNECTION* psConnection,
163 IMG_PBYTE* ppPacketBuf,
164 IMG_UINT32* puiBufLen);
167 /**************************************************************************/ /*!
168 @Function PVRSRVTLReleaseData
169 @Description Called after client has read the stream data out of the buffer
170 The data is subsequently flushed from the stream buffer to make
171 room for more data packets from the stream source.
172 @Input psConnection Address of a pointer to a connection object
173 @Input hSD Handle of the stream object to read
174 @Return PVRSRV_ERROR_RESOURCE_UNAVAILABLE: when stream no longer exists
175 @Return PVRSRV_ERROR_HANDLE_NOT_FOUND: when SD handle not known to TL
176 @Return PVRSRV_ERROR_STREAM_ERROR: internal driver state error
177 @Return PVRSRV_ERROR_RETRY: acquire not called beforehand
178 @Return PVRSRV_ERROR: for system codes
179 */ /***************************************************************************/
181 PVRSRV_ERROR IMG_CALLCONV PVRSRVTLReleaseData(PVRSRV_CONNECTION* psConnection,
184 #if defined (__cplusplus)
188 #endif /* __PVR_TL_H__ */
190 /******************************************************************************
191 End of file (pvr_tl.h)
192 ******************************************************************************/