Debian Codegraph @

media_driver/linux/common/cm/hal/cm_surface_2d.h

raw
1 /*
2 * Copyright (c) 2007-2017, Intel Corporation
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included
12 * in all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
17 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
18 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20 * OTHER DEALINGS IN THE SOFTWARE.
21 */
22 //!
23 //! \file cm_surface_2d.h
24 //! \brief Contains CmSurface2D declaration.
25 //!
26 #ifndef MEDIADRIVER_LINUX_COMMON_CM_CMSURFACE2D_H_
27 #define MEDIADRIVER_LINUX_COMMON_CM_CMSURFACE2D_H_
28
29 #include "cm_def.h"
30 #include "cm_queue.h"
31
32 namespace CMRT_UMD
33 {
34 class CmEvent;
35
36 class CmSurface2D
37 {
38 public:
39 //!
40 //! \brief Retrieves surface index of this CmSurface2D.
41 //! \param [out] index
42 //! Reference to the pointer to an SurfaceIndex.
43 //! It will point to the internal SurfaceIndex.
44 //! \retval CM_SUECCESS.
45 //!
46 CM_RT_API virtual int32_t GetIndex(SurfaceIndex* &index) = 0;
47
48 //!
49 //! \brief Copies data in this CmSurface2D to system memory.
50 //! \details Copied data size is the same as surface data size.
51 //! This is a blocking function, i.e. the function will not return
52 //! until the copy operation is completed.
53 //! Copying will not happen until the status of the dependent event
54 //! becomes CM_STATUS_FINISHED.
55 //! It's the application's responsibility to make sure no other
56 //! task enqueued between the task corresponding to the event and
57 //! this fuction call.
58 //! If sysMemSize is given, it will be checked against the size of
59 //! the surface data.
60 //! \param [out] sysMem
61 //! Pointer to the system memory receiving surface data.
62 //! \param [in] event
63 //! Pointer to the dependent event used for sychronization.
64 //! \param [in] sysMemSize
65 //! Size of the system memory.
66 //! \retval CM_SUCCESS if this function succeeds.
67 //! \retval CM_INVALID_ARG_VALUE if sysMemSize is given but less than what
68 //! is needed.
69 //! \retval CM_LOCK_SURFACE_FAIL if surface locking fails.
70 //! \retval CM_FAILURE otherwise.
71 //!
72 CM_RT_API virtual int32_t
73 ReadSurface(unsigned char *sysMem,
74 CmEvent *event,
75 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0;
76
77 //!
78 //! \brief Copies data in system memory to this CmSurface2D.
79 //! \details Copied data size is the same as the surface data size.
80 //! This is a blocking function, i.e. the function will not return
81 //! until the copy operation is completed.
82 //! Copying will not happen until the status of the dependent event
83 //! becomes CM_STATUS_FINISHED.
84 //! If sysMemSize is given, it will be checked against the size of
85 //! the surface data.
86 //! \param [in] sysMem
87 //! Pointer to the system memory storing surface data.
88 //! \param [in] event
89 //! Pointer to the dependent event used for sychronization.
90 //! \param [in] sysMemSize
91 //! Size of the system memory.
92 //! \retval CM_SUCCESS if copy is successful.
93 //! \retval CM_INVALID_ARG_VALUE if sysMemSize is given but less than what
94 //! is needed.
95 //! \retval CM_LOCK_SURFACE_FAIL if surface locking fails.
96 //! \retval CM_FAILURE otherwise.
97 //!
98 CM_RT_API virtual int32_t
99 WriteSurface(const unsigned char *sysMem,
100 CmEvent *event,
101 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0;
102
103 //!
104 //! \brief Copies data in this CmSurface2D to system memory with system
105 //! memory stride.
106 //! \details Copied data size is the same as surface data size.
107 //! This is a blocking function, i.e. the function will not return
108 //! until the copy operation is completed.
109 //! Copying will not happen until the status of the dependent event
110 //! becomes CM_STATUS_FINISHED.
111 //! It's the application's responsibility to make sure no other
112 //! task enqueued between the task corresponding to the event and
113 //! this fuction call.
114 //! If sysMemSize is given, it will be checked against the size of
115 //! the surface data.
116 //! \param [out] sysMem
117 //! Pointer to the system memory receiving surface data.
118 //! \param [in] event
119 //! Pointer to the dependent event used for sychronization.
120 //! \param [in] stride
121 //! System memory stride in bytes.
122 //! It equals actual surface width in bytes plus extra padding bytes.
123 //! \param [in] sysMemSize
124 //! Size of the system memory.
125 //! \retval CM_SUCCESS if this function succeeds.
126 //! \retval CM_INVALID_ARG_VALUE if sysMemSize is given but less than what
127 //! is needed.
128 //! \retval CM_LOCK_SURFACE_FAIL if surface locking fails.
129 //! \retval CM_FAILURE otherwise.
130 //!
131 CM_RT_API virtual int32_t
132 ReadSurfaceStride(unsigned char *sysMem,
133 CmEvent *event,
134 const unsigned int stride,
135 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0;
136
137 //!
138 //! \brief Copies data in system memory to this CmSurface2D with system
139 //! memory stride.
140 //! \details Copied data size is the same as the surface data size.
141 //! This is a blocking function, i.e. the function will not return
142 //! until the copy operation is completed.
143 //! Copying will not happen until the status of the dependent event
144 //! becomes CM_STATUS_FINISHED.
145 //! If sysMemSize is given, it will be checked against the size of
146 //! the surface data.
147 //! \param [in] sysMem
148 //! Pointer to the system memory storing surface data.
149 //! \param [in] event
150 //! Pointer to the dependent event used for sychronization.
151 //! \param [in] stride
152 //! System memory stride in bytes.
153 //! It equals actual surface width in bytes plus extra padding bytes.
154 //! \param [in] sysMemSize
155 //! Size of the system memory.
156 //! \retval CM_SUCCESS if copy is successful.
157 //! \retval CM_INVALID_ARG_VALUE if sysMemSize is given but less than what
158 //! is needed.
159 //! \retval CM_LOCK_SURFACE_FAIL if surface locking fails.
160 //! \retval CM_FAILURE otherwise.
161 //!
162 CM_RT_API virtual int32_t
163 WriteSurfaceStride(const unsigned char *sysMem,
164 CmEvent *event,
165 const unsigned int stride,
166 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0;
167
168 //!
169 //! \brief Sets surface data to a unified value.
170 //! \details This is a blocking function, i.e. the function will not return
171 //! until the operation is completed.
172 //! Initialization will not happen until the status of the
173 //! dependent event becomes CM_STATUS_FINISHED.
174 //! \param [in] initValue
175 //! The value for initialization.
176 //! \param [in] event
177 //! Pointer to the dependent event used for sychronization.
178 //! \retval CM_SUCCESS if initialization is successful.
179 //! \retval CM_LOCK_SURFACE_FAIL if surface locking fails.
180 //! \retval CM_FAILURE otherwise.
181 //!
182 CM_RT_API virtual int32_t InitSurface(const unsigned int initValue,
183 CmEvent *event,
184 unsigned int useGPU = 0) = 0;
185
186 //!
187 //! \brief Retrieves libva surface ID.
188 //! \note This function is a Linux-only API.
189 //! \param [out] vaSurface
190 //! Reference to a VASurfaceID receiving libva surface ID.
191 //! \retval CM_SUCCESS.
192 //!
193 CM_RT_API virtual int32_t GetVaSurfaceID(VASurfaceID &vaSurface) = 0;
194
195 //!
196 //! \brief Hybrid memory copy from this CmSurface2D to system memory with system
197 //! memory strides.
198 //! \details Copied data size is the same as surface data size.
199 //! This is a blocking function, i.e. the function will not return
200 //! until the copy operation is completed.
201 //! Copying will not happen until the status of the dependent event
202 //! becomes CM_STATUS_FINISHED.
203 //! If sysMemSize is given, it will be checked against the size of
204 //! the surface data.
205 //! \param [out] sysMem
206 //! Pointer to the system memory receiving surface data.
207 //! \param [in] event
208 //! Pointer to the dependent event used for sychronization.
209 //! \param [in] horizontalStride
210 //! Horizontal stride of system memory in bytes.
211 //! \param [in] verticalStride
212 //! Vertical stride of system memory in rows.
213 //! \param [in] sysMemSize
214 //! Size of the system memory.
215 //! \param [in] option
216 //! Option to disable/enable hybrid memory copy.
217 //! \retval CM_SUCCESS if this function succeeds.
218 //! \retval CM_INVALID_ARG_VALUE if sysMemSize is given but less than what
219 //! is needed.
220 //! \retval CM_LOCK_SURFACE_FAIL if surface locking fails.
221 //! \retval CM_FAILURE otherwise.
222 //!
223 CM_RT_API virtual int32_t
224 ReadSurfaceHybridStrides(unsigned char *sysMem,
225 CmEvent *event,
226 const unsigned int horizontalStride,
227 const unsigned int verticalStride,
228 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL,
229 unsigned int option = 0) = 0;
230
231 //!
232 //! \brief Hybrid memory copy from system memory to this CmSurface2D with
233 //! system memory stride.
234 //! \details Copied data size is the same as the surface data size.
235 //! This is a blocking function, i.e. the function will not return
236 //! until the copy
237 //! operation is completed.
238 //! Copying will not happen until the status of the dependent event
239 //! becomes CM_STATUS_FINISHED.
240 //! If sysMemSize is given, it will be checked against the size of
241 //! the surface data.
242 //! \param [in] sysMem
243 //! Pointer to the system memory storing surface data.
244 //! \param [in] event
245 //! Pointer to the dependent event used for sychronization.
246 //! \param [in] horizontalStride
247 //! Horizontal stride of system memory in bytes.
248 //! \param [in] verticalStride
249 //! Vertical stride of system memory in rows.
250 //! \param [in] sysMemSize
251 //! Size of the system memory.
252 //! \param [in] option
253 //! Option to disable/enable hybrid memory copy.
254 //! \retval CM_SUCCESS if copy is successful.
255 //! \retval CM_INVALID_ARG_VALUE if sysMemSize is given but less than what
256 //! is needed.
257 //! \retval CM_LOCK_SURFACE_FAIL if surface locking fails.
258 //! \retval CM_FAILURE otherwise.
259 //!
260 CM_RT_API virtual int32_t
261 WriteSurfaceHybridStrides(const unsigned char *sysMem,
262 CmEvent *event,
263 const unsigned int horizontalStride,
264 const unsigned int verticalStride,
265 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL,
266 unsigned int option = 0) = 0;
267
268 //!
269 //! \brief Selects one of the pre-defined memory object control settings for
270 //! this CmSurface2D.
271 //! \note This function only works on Gen9+ paltforms.
272 //! \param [in] memCtrl
273 //! The selected pre-defined memory object control setting.
274 //! \retval CM_SUCCESS if the given parameter is valid
275 //! \retval CM_FAILURE otherwise.
276 //!
277 CM_RT_API virtual int32_t
278 SelectMemoryObjectControlSetting(MEMORY_OBJECT_CONTROL memCtrl) = 0;
279
280 //!
281 //! \brief Sets frame type of this CmSurface2D.
282 //! \details By default this CmSurface2D is a whole frame.
283 //! \param [in] frameType
284 //! A value in enumeration CM_FRAME_TYPE, frame type of this
285 //! CmSurface2D. It should be a whole frame or a field in an
286 //! interlaced frame.
287 //! \retval CM_SUCCESS.
288 //!
289 CM_RT_API virtual int32_t SetProperty(CM_FRAME_TYPE frameType) = 0;
290
291 //!
292 //! \brief Sets surface state parameters for an alias of this CmSurface2D.
293 //! \details If surfIndex is nullptr, default state of this CmSurface2D
294 //! is changed.
295 //! \param [in] surfIndex
296 //! Pointer to the surface index of an alias of this CmSurface2D. A new
297 //! surface state is created for this alias or the existing state is updated.
298 //! \param [in] surfStateParam
299 //! Pointer to a new state parameter.
300 //! \retval CM_INVALID_ARG_VALUE if any parameter is invalid.
301 //! \retval CM_SUCCESS if successful.
302 //!
303 CM_RT_API virtual int32_t
304 SetSurfaceStateParam(SurfaceIndex *surfIndex,
305 const CM_SURFACE2D_STATE_PARAM *surfStateParam) = 0;
306
307
308 // Pay Attention: below APIs only used in UMD. If you add an API exposed to application, please add it BEFORE this line.
309 public:
310
311 //!
312 //! \brief Selects one of the pre-defined MOS resource usage settings for
313 //! this CmSurface2D.
314 //! \note This function works only on Gen9+ paltforms.
315 //! \param [in] mosUsage
316 //! The selected pre-defined MOS resource usage for memory object control setting.
317 //! \retval CM_SUCCESS if the given parameter is valid
318 //! \retval CM_FAILURE otherwise.
319 //!
320 CMRT_UMD_API virtual int32_t SetResourceUsage(MOS_HW_RESOURCE_DEF mosUsage) = 0;
321
322 //!
323 //! \brief Sets the surface's read sync flag for synchronization between engines.
324 //! \details If the surface is shared between render engine and another engine,
325 //! the read sync flag is to tell whether the next engine should wait till
326 //! the kernel execution ends in render engine. If the read sync flag is set,
327 //! then it means the render engine only read this surface and the next engine
328 //! can also access it simultaneously. If the read sync flag
329 //! is not set (or set to false), then the next engine should assume the
330 //! render engine is writing to this surface and wait till the kernel execution
331 //! ends.
332 //! \param [in] readSync
333 //! value of read sync flag to be set to the surface
334 //! \retval CM_INVALID_ARG_VALUE if any parameter is invalid.
335 //! \retval CM_SUCCESS if successful.
336 //!
337 CMRT_UMD_API virtual int32_t SetReadSyncFlag(bool readSync, CmQueue *pCmQueue) = 0;
338
339 //!
340 //! \brief Set the UMD Resource and MOS Resource in the CmSurface2D
341 //! \details A callback function which allows CM callers to change the UMD Resource and
342 //! MOS Resource embedded in the CmSurface2D.
343 //! \param [in] umdResource
344 //! the UMD Resource set to the CmSurface2D
345 //! \param [in] updateMosResource
346 //! a flag indicating whether MOS resource needs updating. 0 mean keeping it
347 //! unchanged. Otherwise, set the MOS resource to parameter mosResource. Default
348 //! is 0.
349 //! \param [in] mosResource
350 //! the MOS Resource set to the CmSurface2D
351 //! \retval CM_SUCCESS always.
352 //!
353 CMRT_UMD_API virtual int32_t
354 NotifyUmdResourceChanged(UMD_RESOURCE umdResource,
355 int updateMosResource = 0,
356 PMOS_RESOURCE mosResource = nullptr) = 0;
357
358 };
359 }; //namespace
360
361 #endif // #ifndef MEDIADRIVER_LINUX_COMMON_CM_CMSURFACE2D_H_