Debian Codegraph @

media_driver/agnostic/common/cm/cm_thread_space.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_thread_space.h
24 //! \brief Contains CmThreadSpace declarations.
25 //!
26
27 #ifndef MEDIADRIVER_AGNOSTIC_COMMON_CM_CMTHREADSPACE_H_
28 #define MEDIADRIVER_AGNOSTIC_COMMON_CM_CMTHREADSPACE_H_
29
30 #include "cm_def.h"
31
32 struct CM_DEPENDENCY
33 {
34 uint32_t count;
35 int32_t deltaX[CM_MAX_DEPENDENCY_COUNT];
36 int32_t deltaY[CM_MAX_DEPENDENCY_COUNT];
37 };
38
39 struct CM_COORDINATE
40 {
41 int32_t x;
42 int32_t y;
43 };
44
45 struct CM_THREAD_PARAM
46 {
47 CM_COORDINATE scoreboardCoordinates; //[X, Y] terms of the scoreboard values of the current thread.
48 uint8_t scoreboardColor; // dependency color the current thread.
49 uint8_t sliceDestinationSelect; //select determines the slice of the current thread must be sent to.
50 uint8_t subSliceDestinationSelect; //select determines the sub-slice of the current thread must be sent to.
51 };
52
53 //| CM different dispatch patterns for 26ZI media object
54 enum CM_26ZI_DISPATCH_PATTERN
55 {
56 VVERTICAL_HVERTICAL_26 = 0,
57 VVERTICAL_HHORIZONTAL_26 = 1,
58 VVERTICAL26_HHORIZONTAL26 = 2,
59 VVERTICAL1X26_HHORIZONTAL1X26 = 3
60 };
61
62 namespace CMRT_UMD
63 {
64 class CmKernel;
65
66 //!
67 //! \brief CmThreadSpace Class.
68 //! \details CmThreadSpace is a 2-dimensional space.Each unit is notated as
69 //! a pair of X/Y coordinates,which is in the range of [0, width -1]
70 //! or [0, heigh-1]. CmThreadSpace can be per task or per kernel.
71 //! If the thread space is used in CmQueue::Enqueue(CmTask * Task,
72 //! CmEvent *& pEvent, const CmThreadSpace * pTS = nullptr), it is a
73 //! per task thread space. In this case, each kernel in the task
74 //! uses the same thread space, i.e.same dimension, same dependency
75 //! etc.For per task CmThreadSpace, if CmThreadSpace::AssociateThread
76 //! or CmThreadSpace::AssociateThreadWithMask is called, the task
77 //! can only has one kernel. If the thread space is used in
78 //! CmKernel::AssociateThreadSpace(CmThreadSpace *& pTS), it is a
79 //! per kernel thread space. Per kernel thread space overwrites
80 //! per task thread space. \n
81 //! CmThreadSpace::AssociateThread or CmThreadSpace::AssociateThreadWithMask
82 //! are usually used together with CmKernel::SetThreadArg. If
83 //! anyone of these three functions are called, media object command
84 //! will be triggered. If none of CmThreadSpace::AssociateThread,
85 //! CmThreadSpace::AssociateThreadWithMask, or CmKernel::SetThreadArg
86 //! is called, media object walker command will be triggered. Details
87 //! of media object command and media object walker command can be
88 //! found at
89 //! https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol07-3d_media_gpgpu.pdf
90 //! or https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-kbl-vol07-3d_media_gpgpu.pdf. \n
91 //! In the case of media object, each thread gets coordinates set
92 //! through CmThreadSpace::AssociateThread or
93 //! CmThreadSpace::AssociateThreadWithMask. If CmThreadSpace::AssociateThread
94 //! or CmThreadSpace::AssociateThreadWithMask is not called
95 //! (i.e.only CmKernel::SetThreadArg is called), the coordinates
96 //! will be(0, 0), (1, 0), ..., (width - 1, 0), (0, 1), (1, 1), ...,
97 //! (width - 1, 1), ..., (0, height - 1), (1, height - 1), ...,
98 //! (width - 1, height1) for threadId 0, 1, 2, ..threadCount - 1. \n
99 //! In the case of media object walker, thread coordinates will be
100 //! (0, 0), (1, 0), ..., (width - 1, 0), (0, 1), (1, 1), ...,
101 //! (width - 1, 1), ..., (0, height - 1), (1, height - 1), ...,
102 //! (width - 1, height1), threadId or per thread arg can be calculated
103 //! using thread coordinates.
104 //!
105 class CmThreadSpace
106 {
107 public:
108 //!
109 //! \brief Associate the thread to the unit with cooridinates(x, y)
110 //! in thread space.
111 //! \details Threads in a thread space must come from a single kernel.
112 //! Each unit in thread space must be associated with a thread
113 //! (can't be empty) and associated with a unique thread.A
114 //! kernel's threads should be either all in thread space or
115 //! none in thread space. This function will trigger media
116 //! object command
117 //! \param [in] x
118 //! X coordinate of the unit in thread space.
119 //! \param [in] y
120 //! Y coordinate of the unit in thread space.
121 //! \param [in] kernel
122 //! Pointer to CmKernel.
123 //! \param [in] threadId
124 //! Thread index.
125 //! \retval CM_SUCCESS if the association is successful.
126 //! \retval CM_INVALID_ARG_VALUE if input parameters are invalid.
127 //!
128 CM_RT_API virtual int32_t AssociateThread(uint32_t x,
129 uint32_t y,
130 CmKernel *kernel,
131 uint32_t threadId) = 0;
132
133 //!
134 //! \brief Select from predefined dependency patterns.
135 //! \details There are 9 kinds of thread dependency patterns.Each
136 //! dependency pattern has specific delta in X coordinate
137 //! and the delta in Y coordinate.By default, the dependency
138 //! pattern is set CM_NONE_DEPENDENCY.
139 //! \param [in] pattern
140 //! Pattern index.CM_DEPENDENCY_PATTERN is a type-defined
141 //! enum value.
142 //! \retval CM_SUCCESS if the pattern is selected.
143 //! \retval CM_OUT_OF_HOST_MEMORY if the necessary memory allocation is
144 //! failed.
145 //! \retval CM_FAILURE otherwise.
146 //!
147 CM_RT_API virtual int32_t
148 SelectThreadDependencyPattern(CM_DEPENDENCY_PATTERN pattern) = 0;
149
150 //!
151 //! \brief Associate the thread to the unit with cooridinates(x, y)
152 //! in thread space with dependency mask.
153 //! \details Threads in a thread space must come from a single kernel.
154 //! Each unit in thread space must be associated with a thread
155 //! (can't be empty) and associated with a unique thread. A
156 //! kernel's threads should be either all in thread space or
157 //! none in thread space.The dependency mask is used to turn
158 //! off some or all of the dependencies set by the selected
159 //! dependency pattern for that thread. This function will
160 //! trigger media object command
161 //! \param [in] x
162 //! X coordinate of the unit in thread space.
163 //! \param [in] y
164 //! Y coordinate of the unit in thread space.
165 //! \param [in] kernel
166 //! Pointer to CmKernel.
167 //! \param [in] threadId
168 //! Thread index.
169 //! \param [in] dependencyMask
170 //! Dependency mask for the thread.
171 //! \retval CM_SUCCESS if the association is successful.
172 //! \retval CM_INVALID_ARG_VALUE if input parameters are invalid.
173 //!
174 CM_RT_API virtual int32_t
175 AssociateThreadWithMask(uint32_t x,
176 uint32_t y,
177 CmKernel* kernel,
178 uint32_t threadId,
179 uint8_t dependencyMask) = 0;
180
181 //!
182 //! \brief Set the color count the CmThreadSpace.
183 //! \details When color count is specified, the total thread count is
184 //! thread_space_width x thread_space_height x color_count.
185 //! This function is for media object walker only for now.
186 //! The CM instrinsic, unsigned short get_color(void) can be
187 //! used within the kernel to get the
188 //! thread's color count value. The return
189 //! value is from 0 to predefined thread space color value - 1.
190 //! Each color count specifies one set of threads that can have
191 //! dependency among them. The depenendcy is set by calling
192 //! SelectThreadDependencyPattern. There is no dependnecy
193 //! across set( or across color count).
194 //! The walking pattern set by calling SelectMediaWalkingPattern
195 //! is applied to thread coordinates(x,y). For each
196 //! cooridnates(x,y) there is a loop for color count.
197 //! \param [in] colorCount
198 //! Color count value,valid values 1~16 for platforms till CNL.
199 //! \retval CM_SUCCESS if the color count was set successfully.
200 //! \retval CM_INVALID_ARG_VALUE if invalid color count values.
201 //!
202 CM_RT_API virtual int32_t SetThreadSpaceColorCount(uint32_t colorCount) = 0;
203
204 //!
205 //! \brief Select the media walking pattern when there is no thread
206 //! space dependency.
207 //! \details API is only valid when no thread dependency has been
208 //! selected for the thread space.There are 7 kinds of media
209 //! walking patterns. By default, the media walking pattern
210 //! is set CM_WALK_DEFAULT.
211 //! \param [in] pattern
212 //! Media walking pattern index.CM_WALKING_PATTERN is a
213 //! type-defined enum value.
214 //! \retval CM_SUCCESS if media walking pattern is set successfully.
215 //! \retval CM_INVALID_MEDIA_WALKING_PATTERN if invalid walking pattern.
216 //! \retval CM_INVALID_DEPENDENCY_WITH_WALKING_PATTERN if thread
217 //! space dependency pattern does not equal NONE.
218 //! \note This API is implemented for media walker only.
219 //!
220 CM_RT_API virtual int32_t
221 SelectMediaWalkingPattern(CM_WALKING_PATTERN pattern) = 0;
222
223 //!
224 //! \brief Set the dispatch pattern for 26ZI dependency pattern.
225 //! \details There are 4 kinds of CM dispatch patterns for
226 //! 26ZI media objects.
227 //! \param [in] pattern
228 //! Dispatch pattern index. CM_26ZI_DISPATCH_PATTERN is a
229 //! type-defined enum value.
230 //! \retval CM_SUCCESS if 26ZI dependency pattern is set successfully.
231 //! \retval CM_FAILURE otherwise.
232 //!
233 CM_RT_API virtual int32_t
234 Set26ZIDispatchPattern(CM_26ZI_DISPATCH_PATTERN pattern) = 0;
235
236 //!
237 //! \brief Set the macro block size for 26ZI dependency pattern
238 //! \details The width and height of the macro block are used to
239 //! generate the 26ZI dispatch order.
240 //! \param [in] width
241 //! The width of the macro block, by default 16.
242 //! \param [in] height
243 //! The height of the macro block, by default 8.
244 //! \retval CM_SUCCESS if the macro block size is set successfully.
245 //! \retval CM_FAILURE otherwise.
246 //!
247 CM_RT_API virtual int32_t Set26ZIMacroBlockSize(uint32_t width,
248 uint32_t height) = 0;
249
250 //!
251 //! \brief Set the media walker groupIDSelect field.
252 //! \details GroupIDSelect chooses which of the nested loops of the
253 //! walker are used to identify threads which share a group id
254 //! and therefore a shared barrier and SLM. There are 6 kinds
255 // media walker group selects.By default, the groupIDSelect
256 //! is set CM_MW_GROUP_NONE.
257 //! \param [in] groupSelect
258 //! Goup ID Loop Select.CM_MW_GROUP_SELECT is a type-defined
259 //! enum value.
260 //! \returns CM_SUCCESS.
261 //! \note This API is implemented for media walker only.
262 //!
263 CM_RT_API virtual int32_t
264 SetMediaWalkerGroupSelect(CM_MW_GROUP_SELECT groupSelect) = 0;
265
266 //!
267 //! \brief Set the media walker parameters for the CmThreadSpace.
268 //! \details This API is used to set each field of MEDIA_OBJECT_WALKER
269 //! from an array of DWORDs.
270 //! \param [in] parameters
271 //! CM media walking parameters.CM_WALKING_PARAMETERS is a
272 //! structure which defines an array of Dword values.
273 //! \returns CM_SUCCESS.
274 //!
275 CM_RT_API virtual int32_t
276 SelectMediaWalkingParameters(CM_WALKING_PARAMETERS parameters) = 0;
277
278 //!
279 //! \brief Set the dependency vectors for the CmThreadSpace.
280 //! \details The depencency vector contains the vector of delta in X
281 //! coordinate, the vector of delta in Y coordinate and the array
282 //! size of vectors.The max array size is 8.
283 //! \param [in] dependVectors
284 //! CM_DEPENDENCY is a structure contains CM dependency
285 //! information.
286 //! \returns CM_SUCCESS.
287 //!
288 CM_RT_API virtual int32_t
289 SelectThreadDependencyVectors(CM_DEPENDENCY dependVectors) = 0;
290
291 //!
292 //! \brief Set the thread space order for the CmThreadSpace.
293 //! \details This API is used for enqueuing media-objects with explicited
294 //! scoreboard (x,y).
295 //! \param [in] threadCount
296 //! The count of total threads.
297 //! \param [in] threadSpaceOrder
298 //! CM_THREAD_PARAM is a structure defines the thread dispatch
299 //! order list
300 //! \retval CM_SUCCESS if thread space order is successfully set.
301 //! \retval CM_OUT_OF_HOST_MEMORY if the necessary memory allocation is
302 //! failed.
303 //! \retval CM_INVALID_ARG_VALUE if the input arg is not correct.
304 //! \note This API is implemented for media objects only.
305 //!
306 CM_RT_API virtual int32_t
307 SetThreadSpaceOrder(uint32_t threadCount,
308 const CM_THREAD_PARAM* threadSpaceOrder) = 0;
309 };
310 }; //namespace
311
312 #endif // #ifndef MEDIADRIVER_AGNOSTIC_COMMON_CM_CMTHREADSPACE_H_