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_ 313