1 # 2 # Copyright (C) 2015 The Android Open Source Project 3 # 4 # Licensed under the Apache License, Version 2.0 (the "License"); 5 # you may not use this file except in compliance with the License. 6 # You may obtain a copy of the License at 7 # 8 # http://www.apache.org/licenses/LICENSE-2.0 9 # 10 # Unless required by applicable law or agreed to in writing, software 11 # distributed under the License is distributed on an "AS IS" BASIS, 12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 # See the License for the specific language governing permissions and 14 # limitations under the License. 15 # 16 17 header: 18 summary: Kernel Invocation Functions and Types 19 description: 20 The @rsForEach() function can be used to invoke the root kernel of a script. 21 22 The other functions are used to get the characteristics of the invocation of 23 an executing kernel, like dimensions and current indices. These functions take 24 a @rs_kernel_context as argument. 25 end: 26 27 type: rs_for_each_strategy_t 28 enum: rs_for_each_strategy 29 value: RS_FOR_EACH_STRATEGY_SERIAL = 0, "Prefer contiguous memory regions." 30 value: RS_FOR_EACH_STRATEGY_DONT_CARE = 1, "No prefrences." 31 #TODO explain this better 32 value: RS_FOR_EACH_STRATEGY_DST_LINEAR = 2, "Prefer DST." 33 value: RS_FOR_EACH_STRATEGY_TILE_SMALL = 3, "Prefer processing small rectangular regions." 34 value: RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4, "Prefer processing medium rectangular regions." 35 value: RS_FOR_EACH_STRATEGY_TILE_LARGE = 5, "Prefer processing large rectangular regions." 36 summary: Suggested cell processing order 37 description: 38 This type is used to suggest how the invoked kernel should iterate over the cells of the 39 allocations. This is a hint only. Implementations may not follow the suggestion. 40 41 This specification can help the caching behavior of the running kernel, e.g. the cache 42 locality when the processing is distributed over multiple cores. 43 end: 44 45 type: rs_kernel_context 46 version: 23 47 simple: const struct rs_kernel_context_t * 48 summary: Handle to a kernel invocation context 49 description: 50 The kernel context contains common characteristics of the allocations being iterated 51 over, like dimensions. It also contains rarely used indices of the currently processed 52 cell, like the Array0 index or the current level of detail. 53 54 You can access the kernel context by adding a special parameter named "context" of type 55 rs_kernel_context to your kernel function. See @rsGetDimX() and @rsGetArray0() for examples. 56 end: 57 58 type: rs_script_call_t 59 struct: rs_script_call 60 field: rs_for_each_strategy_t strategy, "Currently ignored. In the future, will be suggested cell iteration strategy." 61 field: uint32_t xStart, "Starting index in the X dimension." 62 field: uint32_t xEnd, "Ending index (exclusive) in the X dimension." 63 field: uint32_t yStart, "Starting index in the Y dimension." 64 field: uint32_t yEnd, "Ending index (exclusive) in the Y dimension." 65 field: uint32_t zStart, "Starting index in the Z dimension." 66 field: uint32_t zEnd, "Ending index (exclusive) in the Z dimension." 67 field: uint32_t arrayStart, "Starting index in the Array0 dimension." 68 field: uint32_t arrayEnd, "Ending index (exclusive) in the Array0 dimension." 69 field: uint32_t array1Start, "Starting index in the Array1 dimension." 70 field: uint32_t array1End, "Ending index (exclusive) in the Array1 dimension." 71 field: uint32_t array2Start, "Starting index in the Array2 dimension." 72 field: uint32_t array2End, "Ending index (exclusive) in the Array2 dimension." 73 field: uint32_t array3Start, "Starting index in the Array3 dimension." 74 field: uint32_t array3End, "Ending index (exclusive) in the Array3 dimension." 75 summary: Cell iteration information 76 description: 77 This structure is used to provide iteration information to a rsForEach call. 78 It is currently used to restrict processing to a subset of cells. In future 79 versions, it will also be used to provide hint on how to best iterate over 80 the cells. 81 82 The Start fields are inclusive and the End fields are exclusive. E.g. to iterate 83 over cells 4, 5, 6, and 7 in the X dimension, set xStart to 4 and xEnd to 8. 84 end: 85 86 type: rs_kernel 87 version: 24 88 simple: void* 89 summary: Handle to a kernel function 90 description: 91 An opaque type for a function that is defined with the kernel attribute. A value 92 of this type can be used in a @rsForEach call to launch a kernel. 93 end: 94 95 function: rsForEach 96 version: 9 13 97 ret: void 98 arg: rs_script script, "Script to call." 99 arg: rs_allocation input, "Allocation to source data from." 100 arg: rs_allocation output, "Allocation to write date into." 101 arg: const void* usrData, "User defined data to pass to the script. May be NULL." 102 arg: const rs_script_call_t* sc, "Extra control information used to select a sub-region of the allocation to be processed or suggest a walking strategy. May be NULL." 103 summary: Launches a kernel 104 description: 105 Runs the kernel over zero or more input allocations. They are passed after the 106 @rs_kernel argument. If the specified kernel returns a value, an output allocation 107 must be specified as the last argument. All input allocations, 108 and the output allocation if it exists, must have the same dimensions. 109 110 This is a synchronous function. A call to this function only returns after all 111 the work has completed for all cells of the input allocations. If the kernel 112 function returns any value, the call waits until all results have been written 113 to the output allocation. 114 115 Up to API level 23, the kernel is implicitly specified as the kernel named 116 "root" in the specified script, and only a single input allocation can be used. 117 Starting in API level 24, an arbitrary kernel function can be used, 118 as specified by the kernel argument. The script argument is removed. 119 The kernel must be defined in the current script. In addition, more than one 120 input can be used. 121 122 E.g.<code><br/> 123 float __attribute__((kernel)) square(float a) {<br/> 124 return a * a;<br/> 125 }<br/> 126 <br/> 127 void compute(rs_allocation ain, rs_allocation aout) {<br/> 128 rsForEach(square, ain, aout);<br/> 129 }<br/> 130 <br/></code> 131 test: none 132 end: 133 134 function: rsForEach 135 version: 9 13 136 ret: void 137 arg: rs_script script 138 arg: rs_allocation input 139 arg: rs_allocation output 140 arg: const void* usrData 141 test: none 142 end: 143 144 function: rsForEach 145 version: 14 20 146 ret: void 147 arg: rs_script script 148 arg: rs_allocation input 149 arg: rs_allocation output 150 arg: const void* usrData 151 arg: size_t usrDataLen, "Size of the userData structure. This will be used to perform a shallow copy of the data if necessary." 152 arg: const rs_script_call_t* sc 153 test: none 154 end: 155 156 function: rsForEach 157 version: 14 20 158 ret: void 159 arg: rs_script script 160 arg: rs_allocation input 161 arg: rs_allocation output 162 arg: const void* usrData 163 arg: size_t usrDataLen 164 test: none 165 end: 166 167 function: rsForEach 168 version: 14 23 169 ret: void 170 arg: rs_script script 171 arg: rs_allocation input 172 arg: rs_allocation output 173 test: none 174 end: 175 176 function: rsForEach 177 version: 24 178 intrinsic: true 179 # Not overloadable 180 attrib: = 181 ret: void 182 arg: rs_kernel kernel, "Function designator to a function that is defined with the kernel attribute." 183 arg: ..., "Input and output allocations" 184 test: none 185 end: 186 187 function: rsForEachWithOptions 188 version: 24 189 intrinsic: true 190 # Not overloadable 191 attrib: = 192 ret: void 193 arg: rs_kernel kernel, "Function designator to a function that is defined with the kernel attribute." 194 arg: rs_script_call_t* options, "Launch options" 195 arg: ..., "Input and output allocations" 196 summary: Launches a kernel with options 197 description: 198 Launches kernel in a way similar to @rsForEach. However, instead of processing 199 all cells in the input, this function only processes cells in the subspace of 200 the index space specified in options. With the index space explicitly specified 201 by options, no input or output allocation is required for a kernel launch using 202 this API. If allocations are passed in, they must match the number of arguments 203 and return value expected by the kernel function. The output allocation is 204 present if and only if the kernel has a non-void return value. 205 206 E.g.,<code><br/> 207 rs_script_call_t opts = {0};<br/> 208 opts.xStart = 0;<br/> 209 opts.xEnd = dimX;<br/> 210 opts.yStart = 0;<br/> 211 opts.yEnd = dimY / 2;<br/> 212 rsForEachWithOptions(foo, &opts, out, out);<br/> 213 </code> 214 test: none 215 end: 216 217 function: rsForEachInternal 218 version: 24 219 internal: true 220 ret: void 221 arg: int slot 222 arg: rs_script_call_t* options 223 arg: int hasOutput, "Indicates whether the kernel generates output" 224 arg: int numInputs, "Number of input allocations" 225 arg: rs_allocation* allocs, "Input and output allocations" 226 summary: (Internal API) Launch a kernel in the current Script (with the slot number) 227 description: 228 Internal API to launch a kernel. 229 test: none 230 end: 231 232 function: rsGetArray0 233 version: 23 234 ret: uint32_t 235 arg: rs_kernel_context context 236 summary: Index in the Array0 dimension for the specified kernel context 237 description: 238 Returns the index in the Array0 dimension of the cell being processed, as specified 239 by the supplied kernel context. 240 241 The kernel context contains common characteristics of the allocations being iterated 242 over and rarely used indices, like the Array0 index. 243 244 You can access the kernel context by adding a special parameter named "context" of 245 type rs_kernel_context to your kernel function. E.g.<br/> 246 <code>short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) {<br/> 247 // The current index in the common x, y, z dimensions are accessed by<br/> 248 // adding these variables as arguments. For the more rarely used indices<br/> 249 // to the other dimensions, extract them from the kernel context:<br/> 250 uint32_t index_a0 = rsGetArray0(context);<br/> 251 //...<br/> 252 }<br/></code> 253 254 This function returns 0 if the Array0 dimension is not present. 255 test: none 256 end: 257 258 function: rsGetArray1 259 version: 23 260 ret: uint32_t 261 arg: rs_kernel_context context 262 summary: Index in the Array1 dimension for the specified kernel context 263 description: 264 Returns the index in the Array1 dimension of the cell being processed, as specified 265 by the supplied kernel context. See @rsGetArray0() for an explanation of the context. 266 267 Returns 0 if the Array1 dimension is not present. 268 test: none 269 end: 270 271 function: rsGetArray2 272 version: 23 273 ret: uint32_t 274 arg: rs_kernel_context context 275 summary: Index in the Array2 dimension for the specified kernel context 276 description: 277 Returns the index in the Array2 dimension of the cell being processed, 278 as specified by the supplied kernel context. See @rsGetArray0() for an explanation 279 of the context. 280 281 Returns 0 if the Array2 dimension is not present. 282 test: none 283 end: 284 285 function: rsGetArray3 286 version: 23 287 ret: uint32_t 288 arg: rs_kernel_context context 289 summary: Index in the Array3 dimension for the specified kernel context 290 description: 291 Returns the index in the Array3 dimension of the cell being processed, as specified 292 by the supplied kernel context. See @rsGetArray0() for an explanation of the context. 293 294 Returns 0 if the Array3 dimension is not present. 295 test: none 296 end: 297 298 function: rsGetDimArray0 299 version: 23 300 ret: uint32_t 301 arg: rs_kernel_context context 302 summary: Size of the Array0 dimension for the specified kernel context 303 description: 304 Returns the size of the Array0 dimension for the specified kernel context. 305 See @rsGetDimX() for an explanation of the context. 306 307 Returns 0 if the Array0 dimension is not present. 308 #TODO Add an hyperlink to something that explains Array0/1/2/3 309 # for the relevant functions. 310 test: none 311 end: 312 313 function: rsGetDimArray1 314 version: 23 315 ret: uint32_t 316 arg: rs_kernel_context context 317 summary: Size of the Array1 dimension for the specified kernel context 318 description: 319 Returns the size of the Array1 dimension for the specified kernel context. 320 See @rsGetDimX() for an explanation of the context. 321 322 Returns 0 if the Array1 dimension is not present. 323 test: none 324 end: 325 326 function: rsGetDimArray2 327 version: 23 328 ret: uint32_t 329 arg: rs_kernel_context context 330 summary: Size of the Array2 dimension for the specified kernel context 331 description: 332 Returns the size of the Array2 dimension for the specified kernel context. 333 See @rsGetDimX() for an explanation of the context. 334 335 Returns 0 if the Array2 dimension is not present. 336 test: none 337 end: 338 339 function: rsGetDimArray3 340 version: 23 341 ret: uint32_t 342 arg: rs_kernel_context context 343 summary: Size of the Array3 dimension for the specified kernel context 344 description: 345 Returns the size of the Array3 dimension for the specified kernel context. 346 See @rsGetDimX() for an explanation of the context. 347 348 Returns 0 if the Array3 dimension is not present. 349 test: none 350 end: 351 352 function: rsGetDimHasFaces 353 version: 23 354 ret: bool, "Returns true if more than one face is present, false otherwise." 355 arg: rs_kernel_context context 356 summary: Presence of more than one face for the specified kernel context 357 description: 358 If the kernel is iterating over a cubemap, this function returns true if there's more 359 than one face present. In all other cases, it returns false. See @rsGetDimX() for an 360 explanation of the context. 361 362 @rsAllocationGetDimFaces() is similar but returns 0 or 1 instead of a bool. 363 test: none 364 end: 365 366 function: rsGetDimLod 367 version: 23 368 ret: uint32_t 369 arg: rs_kernel_context context 370 summary: Number of levels of detail for the specified kernel context 371 description: 372 Returns the number of levels of detail for the specified kernel context. This is useful 373 for mipmaps. See @rsGetDimX() for an explanation of the context. 374 375 Returns 0 if Level of Detail is not used. 376 377 @rsAllocationGetDimLOD() is similar but returns 0 or 1 instead the actual 378 number of levels. 379 test: none 380 end: 381 382 function: rsGetDimX 383 version: 23 384 ret: uint32_t 385 arg: rs_kernel_context context 386 summary: Size of the X dimension for the specified kernel context 387 description: 388 Returns the size of the X dimension for the specified kernel context. 389 390 The kernel context contains common characteristics of the allocations being iterated 391 over and rarely used indices, like the Array0 index. 392 393 You can access it by adding a special parameter named "context" of 394 type rs_kernel_context to your kernel function. E.g.<br/> 395 <code>int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {<br/> 396 uint32_t size = rsGetDimX(context); //...<br/></code> 397 398 To get the dimension of specific allocation, use @rsAllocationGetDimX(). 399 test: none 400 end: 401 402 function: rsGetDimY 403 version: 23 404 ret: uint32_t 405 arg: rs_kernel_context context 406 summary: Size of the Y dimension for the specified kernel context 407 description: 408 Returns the size of the X dimension for the specified kernel context. 409 See @rsGetDimX() for an explanation of the context. 410 411 Returns 0 if the Y dimension is not present. 412 413 To get the dimension of specific allocation, use @rsAllocationGetDimY(). 414 test: none 415 end: 416 417 function: rsGetDimZ 418 version: 23 419 ret: uint32_t 420 arg: rs_kernel_context context 421 summary: Size of the Z dimension for the specified kernel context 422 description: 423 Returns the size of the Z dimension for the specified kernel context. 424 See @rsGetDimX() for an explanation of the context. 425 426 Returns 0 if the Z dimension is not present. 427 428 To get the dimension of specific allocation, use @rsAllocationGetDimZ(). 429 test: none 430 end: 431 432 function: rsGetFace 433 version: 23 434 ret: rs_allocation_cubemap_face 435 arg: rs_kernel_context context 436 summary: Coordinate of the Face for the specified kernel context 437 description: 438 Returns the face on which the cell being processed is found, as specified by the 439 supplied kernel context. See @rsGetArray0() for an explanation of the context. 440 441 Returns RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X if the face dimension is not 442 present. 443 test: none 444 end: 445 446 function: rsGetLod 447 version: 23 448 ret: uint32_t 449 arg: rs_kernel_context context 450 summary: Index in the Levels of Detail dimension for the specified kernel context 451 description: 452 Returns the index in the Levels of Detail dimension of the cell being processed, 453 as specified by the supplied kernel context. See @rsGetArray0() for an explanation of 454 the context. 455 456 Returns 0 if the Levels of Detail dimension is not present. 457 test: none 458 end: 459
