Debian Codegraph @

media_driver/agnostic/common/cm/cm_buffer.h

raw
1 /*
2 * Copyright (c) 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_buffer.h
24 //! \brief Contains Class CmBuffer/CmBufferUp definitions
25 //!
26
27 #ifndef MEDIADRIVER_AGNOSTIC_COMMON_CM_CMBUFFER_H_
28 #define MEDIADRIVER_AGNOSTIC_COMMON_CM_CMBUFFER_H_
29
30 #include "cm_def.h"
31
32 // Parameters used to set the surface state of the buffer
33 struct CM_BUFFER_STATE_PARAM
34 {
35 uint32_t uiSize;
36 uint32_t uiBaseAddressOffset;
37 CM_SURFACE_MEM_OBJ_CTRL mocs;
38 };
39
40 namespace CMRT_UMD
41 {
42 class CmEvent;
43
44 //! \brief CmBufferSVM Class to manage SVM (Shared Virtual Memory) resource.
45 //! \details CmBufferSVM represents a 1D surface in SVM (Shared Virtual Memory)
46 //! memory space that is shared between CPU and GPU. The SVM memory must
47 //! be page(4K Bytes) aligned and runtime allocates SVM memory when
48 //! CmDevice::CreateBufferSVM is called. CPU can access the memory by using
49 //! the address returned by GetAddress. GPU can access the memory in two ways
50 //! One way is to use the surfaceIndex returned by GetIndex, similiar to all
51 //! other surfaces and buffers. The other way is to pass the address to CM
52 //! kernel function(genx_main) as an argument for kernel to use.
53 //! \note Right now BufferSVM feature is not working on Linux yet.
54 class CmBufferSVM
55 {
56 public:
57
58 //!
59 //! \brief This function returns the SurfaceIndex object associated
60 //! with the SVM resource.
61 //! \param [out] index
62 //! Reference to the pointer to SurfaceIndex.
63 //! \returns CM_SUCCESS.
64 //!
65 CM_RT_API virtual int32_t GetIndex(SurfaceIndex* &index) = 0;
66
67 //!
68 //! \brief Get the pointer of allocated SVM memory starting address.
69 //! \param [out] addr
70 //! return the allocated SVM memory starting address.
71 //! \returns CM_SUCCESS.
72 //!
73 CM_RT_API virtual int32_t GetAddress(void* &addr) = 0;
74 };
75
76 //!
77 //! \brief CmBufferUP class to manage 1D surface in user provided system memory.
78 //! \details CmBufferUP represents a 1D surface in system memory. It is
79 //! created upon the UP(User Provided) memory. The UP memory
80 //! must be page(4K Bytes) aligned. CPU can access the memory
81 //! as usual.Each CmBufferUP object is associated with a SurfaceIndex
82 //! object containing a unique index value the surface is mapped to
83 //! when created by the CmDevice.The CmDevice keeps the mapping b/w
84 //! index and CmBufferUP. The SurfaceIndex is passed to CM kernel
85 //! function(genx_main) as argument to indicate the surface. It is
86 //! application's responsibility to make sure the accesses from CPU
87 //! and GPU are not overlapped.
88 //!
89 class CmBufferUP
90 {
91 public:
92 //!
93 //! \brief This function returns the SurfaceIndex object associated
94 //! with this CmBufferUp object.
95 //! \param [out] index
96 //! Reference to the pointer to SurfaceIndex.
97 //! \returns CM_SUCCESS.
98 //!
99 CM_RT_API virtual int32_t GetIndex(SurfaceIndex* &index) = 0;
100
101 //!
102 //! \brief Selects one of the pre-defined memory object control
103 //! settings for this buffer.
104 //! \param [in] memCtrl
105 //! The selected pre-defined memory object control setting.
106 //! \retval CM_SUCCESS if the memory object control is set successfully.
107 //! \retval CM_FAILURE otherwise.
108 //! \note This API is only supported for Gen9 and plus platform.
109 //!
110 CM_RT_API virtual int32_t
111 SelectMemoryObjectControlSetting(MEMORY_OBJECT_CONTROL memCtrl) = 0;
112
113 //!
114 //! \brief Selects one of the pre-defined mos resource usage
115 //! this cm_buffer
116 //! \note This function works on Gen9+ paltforms.
117 //! \param [in] mosUsage
118 //! The selected pre-defined MOS resource usage for memory object control setting.
119 //! \retval CM_SUCCESS if the given parameter is valid
120 //! \retval CM_FAILURE otherwise.
121 //!
122 CMRT_UMD_API virtual int32_t
123 SetResourceUsage(const MOS_HW_RESOURCE_DEF mosUsage) = 0;
124
125 };
126
127 //!
128 //! \brief CmBuffer Class to manage 1D surface in video memory.
129 //! \details CmBuffer represents a 1D surface in video memory. Each CmBuffer
130 //! object is associated with a SurfaceIndex object containing a
131 //! unique index value the surface is mapped to when created by the
132 //! CmDevice. The CmDevice keeps the mapping b/w index and CmBuffer.
133 //! The SurfaceIndex is passed to CM kernel function (genx_main) as
134 //! argument to indicate the surface.
135 //!
136 class CmBuffer
137 {
138 public:
139 //!
140 //! \brief This function returns the SurfaceIndex object associated
141 //! with this CmBuffer object.
142 //! \param [out] index
143 //! Reference to the pointer to SurfaceIndex.
144 //! \returns CM_SUCCESS.
145 //!
146 CM_RT_API virtual int32_t GetIndex(SurfaceIndex* &index) = 0;
147
148 //!
149 //! \brief Copies data in this buffer to system memory using CPU.
150 //! \details The size of data copied is the size of data in buffer.This
151 //! API is a blocking function, i.e. the function will not
152 //! return until the copy operation is completed. Buffer
153 //! reading will not happen until the status of the dependent
154 //! event becomes CM_STATUS_FINISHED. It is application's
155 //! responsibility to make sure no other task enqueued after
156 //! the task corresponding to the dependent task but before
157 //! ReadSurface. If sysMemSize is given, it will be checked
158 //! against the size needed for the buffer. If the sysMemSize
159 //! is less than the CmBuffer size, copy only happens for sysMemSize
160 //! bytes, not all data in CmBuffer.
161 //! \param [out] sysMem
162 //! Pointer to the system memory receiving buffer data.
163 //! \param [in] event
164 //! Pointer to the dependent event used for sychronization.
165 //! \param [in] sysMemSize
166 //! Size of the system memory in byte.
167 //! \retval CM_SUCCESS if copy is successful.
168 //! \retval CM_INVALID_ARG_VALUE if sysMem is nullptr.
169 //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed.
170 //! \retval CM_FAILURE otherwise.
171 //!
172 CM_RT_API virtual int32_t
173 ReadSurface(unsigned char* sysMem,
174 CmEvent* event,
175 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0;
176
177 //!
178 //! \brief Copies system memory content to this buffer usingg CPU.
179 //! \details The size of data copied is the size of data in the
180 //! buffer. This is a blocking function, i.e. the function will
181 //! not return until the copy operation is completed. Buffer
182 //! writing will not happen until the status of the dependent
183 //! event becomes CM_STATUS_FINISHED. The dependent event for
184 //! WriteSurface is usually NULL. If sysMemSize is given, it
185 //! will be checked against the size needed for the buffer.
186 //! If the sysMemSize is less than the CmBuffer size, copy only
187 //! happens for sysMemSize bytes, not all data in CmBuffer.
188 //! \param [in] sysMem
189 //! Pointer to the system memory storing the buffer data.
190 //! \param [in] event
191 //! Pointer to the dependent event used for sychronization.
192 //! \param [in] sysMemSize
193 //! Size of the system memory in byte.
194 //! \retval CM_SUCCESS if copy is successful.
195 //! \retval CM_INVALID_ARG_VALUE if sysMem pointer is nullptr.
196 //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed.
197 //! \retval CM_FAILURE otherwise.
198 //!
199 CM_RT_API virtual int32_t
200 WriteSurface(const unsigned char* sysMem,
201 CmEvent* event,
202 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0;
203
204 //!
205 //! \brief Sets memory in this buffer to uint32_t value using CPU.
206 //! \details The size of data initialized is the size of data in the
207 //! buffer. This is a blocking function, i.e. the function will
208 //! not return until the set operation is completed. Buffer
209 //! initialization will not happen until the status of the
210 //! dependent event becomes CM_STATUS_FINISHED. The dependent
211 //! event for InitSurface is usually NULL.
212 //! \param [in] initValue
213 //! uint32_t value used to initialize to.
214 //! \param [in] event
215 //! Pointer to the dependent event used for sychronization.
216 //! \retval CM_SUCCESS if copy is successful.
217 //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed.
218 //! \retval CM_FAILURE otherwise.
219 //!
220 CM_RT_API virtual int32_t InitSurface(const uint32_t initValue,
221 CmEvent* event) = 0;
222
223 //!
224 //! \brief Selects one of the pre-defined memory object control
225 //! settings for this buffer.
226 //! \param [in] memCtrl
227 //! The selected pre-defined memory object control setting.
228 //! \retval CM_SUCCESS if the memory object control is set successfully.
229 //! \retval CM_FAILURE otherwise.
230 //! \note This API is only supported for Gen9 and plus platform.
231 //!
232 CM_RT_API virtual int32_t
233 SelectMemoryObjectControlSetting(MEMORY_OBJECT_CONTROL memCtrl) = 0;
234
235 //!
236 //! \brief Sets the surface state of this buffer.
237 //! \details Set the new size, offset, and mocs to the surface index,
238 //! so they will take effect during surface state setting.
239 //! Usually, the surface index is an alias surface index created
240 //! by calling CmDevice::CreateBufferAlias. This function can be used to
241 //! reinterpret the size, offset, and mocs of an existing CmBuffer.
242 //! \param [in] surfIndex
243 //! Pointer to surface index of this buffer.
244 //! \param [in] bufferStateParam
245 //! The surface state parameter of this buffer. It contains
246 //! size, base address offset and memory object control setting. The
247 //! offset must be 16-aligned due to hardware requirement.
248 //! \retval CM_SUCCESS if the surface state is set successfully.
249 //! \retval CM_INVALID_ARG_VALUE if the surface state parameter is
250 //! invalid.
251 //! \retval CM_NULL_POINTER if any internal used pointer is nullptr.
252 //! \retval CM_FAILURE otherwise.
253 //!
254 CM_RT_API virtual int32_t
255 SetSurfaceStateParam(SurfaceIndex *surfIndex,
256 const CM_BUFFER_STATE_PARAM *bufferStateParam) = 0;
257
258 //!
259 //! \brief Selects one of the pre-defined mos resource usage
260 //! settings for this buffer.
261 //! \note This function works on Gen9+ paltforms.
262 //! \param [in] mosUsage
263 //! The selected pre-defined MOS resource usage for memory object control setting.
264 //! \retval CM_SUCCESS if the memory object control is set successfully.
265 //! \retval CM_FAILURE otherwise.
266 //! \note This API is only supported for Gen9 and plus platform.
267 //!
268 CMRT_UMD_API virtual int32_t
269 SetResourceUsage(const MOS_HW_RESOURCE_DEF mosUsage) = 0;
270 };
271
272 //! \brief CmBufferStateless Class to manage 1D surface created from vedio or
273 //! system memory.
274 //! \details CmBufferStateless represents a 1D surface in vedio memory or system
275 //! space that is stateless-accessed by GPU. The stateless buffer can be
276 //! created from vedio memory, which can be only accessed by GPU. It also
277 //! can be created from system memory, which is local shared memor
278 //! between GPU and CPU and can be access by both GPU and CPU. GPU can
279 //! access the memory by passing the graphics address to CM kernel
280 //! function(genx_main) as an argument for kernel to use. CPU can access the
281 //! system address dirtectly.
282 class CmBufferStateless
283 {
284 public:
285 //!
286 //! \brief Get the staring address in graphics memory space.
287 //! \param [out] gfxAddr
288 //! Staring address in graphics memory space.
289 //! \returns CM_SUCCESS.
290 //!
291 CM_RT_API virtual int32_t GetGfxAddress(uint64_t &gfxAddr) = 0;
292
293 //!
294 //! \brief Get the starting address in system memory space.
295 //! \param [out] sysAddr
296 //! Starting address in system memory space.
297 //! \returns CM_SUCCESS.
298 //!
299 CM_RT_API virtual int32_t GetSysAddress(void *&sysAddr) = 0;
300
301 //!
302 //! \brief Copies data in stateless buffer to system memory using CPU.
303 //! \details The size of data copied is the size of data in buffer.This
304 //! API is a blocking function, i.e. the function will not
305 //! return until the copy operation is completed. Buffer
306 //! reading will not happen until the status of the dependent
307 //! event becomes CM_STATUS_FINISHED. It is application's
308 //! responsibility to make sure no other task enqueued after
309 //! the task corresponding to the dependent task but before
310 //! ReadSurface. If sysMemSize is given, it will be checked
311 //! against the size needed for the buffer. If the sysMemSize
312 //! is less than the CmBufferStateless size, copy only happens
313 //! for sysMemSize bytes, not all data in CmBufferStateless.
314 //! \param [out] sysMem
315 //! Pointer to the system memory receiving buffer data.
316 //! \param [in] event
317 //! Pointer to the dependent event used for sychronization.
318 //! \param [in] sysMemSize
319 //! Size of the system memory in byte.
320 //! \retval CM_SUCCESS if copy is successful.
321 //! \retval CM_INVALID_ARG_VALUE if sysMem is nullptr.
322 //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed.
323 //! \retval CM_FAILURE otherwise.
324 //!
325 CM_RT_API virtual int32_t
326 ReadSurface(unsigned char *sysMem,
327 CmEvent *event,
328 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0;
329
330 //!
331 //! \brief Copies system memory content to stateless buffer usingg CPU.
332 //! \details The size of data copied is the size of data in the
333 //! buffer. This is a blocking function, i.e. the function will
334 //! not return until the copy operation is completed. Buffer
335 //! writing will not happen until the status of the dependent
336 //! event becomes CM_STATUS_FINISHED. The dependent event for
337 //! WriteSurface is usually NULL. If sysMemSize is given, it
338 //! will be checked against the size needed for the buffer.
339 //! If the sysMemSize is less than the CmBufferStateless size,
340 //! copy onlyhappens for sysMemSize bytes, not all data in
341 //! CmBufferStateless.
342 //! \param [in] sysMem
343 //! Pointer to the system memory storing the buffer data.
344 //! \param [in] event
345 //! Pointer to the dependent event used for sychronization.
346 //! \param [in] sysMemSize
347 //! Size of the system memory in byte.
348 //! \retval CM_SUCCESS if copy is successful.
349 //! \retval CM_INVALID_ARG_VALUE if sysMem pointer is nullptr.
350 //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed.
351 //! \retval CM_FAILURE otherwise.
352 //!
353 CM_RT_API virtual int32_t
354 WriteSurface(const unsigned char *sysMem,
355 CmEvent *event,
356 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0;
357 };
358
359 }//namespace
360
361 #endif // #ifndef MEDIADRIVER_AGNOSTIC_COMMON_CM_CMBUFFER_H_