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 17header: 18summary: Kernel Invocation Functions and Types 19description: 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. 25end: 26 27type: rs_for_each_strategy_t 28enum: rs_for_each_strategy 29value: RS_FOR_EACH_STRATEGY_SERIAL = 0, "Prefer contiguous memory regions." 30value: RS_FOR_EACH_STRATEGY_DONT_CARE = 1, "No prefrences." 31#TODO explain this better 32value: RS_FOR_EACH_STRATEGY_DST_LINEAR = 2, "Prefer DST." 33value: RS_FOR_EACH_STRATEGY_TILE_SMALL = 3, "Prefer processing small rectangular regions." 34value: RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4, "Prefer processing medium rectangular regions." 35value: RS_FOR_EACH_STRATEGY_TILE_LARGE = 5, "Prefer processing large rectangular regions." 36summary: Suggested cell processing order 37description: 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. 43end: 44 45type: rs_kernel_context 46version: 23 47simple: const struct rs_kernel_context_t * 48summary: Handle to a kernel invocation context 49description: 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. 56end: 57 58type: rs_script_call_t 59struct: rs_script_call 60field: rs_for_each_strategy_t strategy, "Currently ignored. In the future, will be suggested cell iteration strategy." 61field: uint32_t xStart, "Starting index in the X dimension." 62field: uint32_t xEnd, "Ending index (exclusive) in the X dimension." 63field: uint32_t yStart, "Starting index in the Y dimension." 64field: uint32_t yEnd, "Ending index (exclusive) in the Y dimension." 65field: uint32_t zStart, "Starting index in the Z dimension." 66field: uint32_t zEnd, "Ending index (exclusive) in the Z dimension." 67field: uint32_t arrayStart, "Starting index in the Array0 dimension." 68field: uint32_t arrayEnd, "Ending index (exclusive) in the Array0 dimension." 69field: uint32_t array1Start, "Starting index in the Array1 dimension." 70field: uint32_t array1End, "Ending index (exclusive) in the Array1 dimension." 71field: uint32_t array2Start, "Starting index in the Array2 dimension." 72field: uint32_t array2End, "Ending index (exclusive) in the Array2 dimension." 73field: uint32_t array3Start, "Starting index in the Array3 dimension." 74field: uint32_t array3End, "Ending index (exclusive) in the Array3 dimension." 75summary: Cell iteration information 76description: 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. 84end: 85 86type: rs_kernel 87version: 24 88simple: void* 89summary: Handle to a kernel function 90description: 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. 93end: 94 95function: rsForEach 96version: 9 13 97ret: void 98arg: rs_script script, "Script to call." 99arg: rs_allocation input, "Allocation to source data from." 100arg: rs_allocation output, "Allocation to write date into." 101arg: const void* usrData, "User defined data to pass to the script. May be NULL." 102arg: 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." 103summary: Launches a kernel 104description: 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> 131test: none 132end: 133 134function: rsForEach 135version: 9 13 136ret: void 137arg: rs_script script 138arg: rs_allocation input 139arg: rs_allocation output 140arg: const void* usrData 141test: none 142end: 143 144function: rsForEach 145version: 14 20 146ret: void 147arg: rs_script script 148arg: rs_allocation input 149arg: rs_allocation output 150arg: const void* usrData 151arg: size_t usrDataLen, "Size of the userData structure. This will be used to perform a shallow copy of the data if necessary." 152arg: const rs_script_call_t* sc 153test: none 154end: 155 156function: rsForEach 157version: 14 20 158ret: void 159arg: rs_script script 160arg: rs_allocation input 161arg: rs_allocation output 162arg: const void* usrData 163arg: size_t usrDataLen 164test: none 165end: 166 167function: rsForEach 168version: 14 23 169ret: void 170arg: rs_script script 171arg: rs_allocation input 172arg: rs_allocation output 173test: none 174end: 175 176function: rsForEach 177version: 24 178intrinsic: true 179# Not overloadable 180attrib: = 181ret: void 182arg: rs_kernel kernel, "Function designator to a function that is defined with the kernel attribute." 183arg: ..., "Input and output allocations" 184test: none 185end: 186 187function: rsForEachWithOptions 188version: 24 189intrinsic: true 190# Not overloadable 191attrib: = 192ret: void 193arg: rs_kernel kernel, "Function designator to a function that is defined with the kernel attribute." 194arg: rs_script_call_t* options, "Launch options" 195arg: ..., "Input and output allocations" 196summary: Launches a kernel with options 197description: 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> 214test: none 215end: 216 217function: rsForEachInternal 218version: 24 219internal: true 220ret: void 221arg: int slot 222arg: rs_script_call_t* options 223arg: int hasOutput, "Indicates whether the kernel generates output" 224arg: int numInputs, "Number of input allocations" 225arg: rs_allocation* allocs, "Input and output allocations" 226summary: (Internal API) Launch a kernel in the current Script (with the slot number) 227description: 228 Internal API to launch a kernel. 229test: none 230end: 231 232function: rsGetArray0 233version: 23 234ret: uint32_t 235arg: rs_kernel_context context 236summary: Index in the Array0 dimension for the specified kernel context 237description: 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. 255test: none 256end: 257 258function: rsGetArray1 259version: 23 260ret: uint32_t 261arg: rs_kernel_context context 262summary: Index in the Array1 dimension for the specified kernel context 263description: 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. 268test: none 269end: 270 271function: rsGetArray2 272version: 23 273ret: uint32_t 274arg: rs_kernel_context context 275summary: Index in the Array2 dimension for the specified kernel context 276description: 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. 282test: none 283end: 284 285function: rsGetArray3 286version: 23 287ret: uint32_t 288arg: rs_kernel_context context 289summary: Index in the Array3 dimension for the specified kernel context 290description: 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. 295test: none 296end: 297 298function: rsGetDimArray0 299version: 23 300ret: uint32_t 301arg: rs_kernel_context context 302summary: Size of the Array0 dimension for the specified kernel context 303description: 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. 310test: none 311end: 312 313function: rsGetDimArray1 314version: 23 315ret: uint32_t 316arg: rs_kernel_context context 317summary: Size of the Array1 dimension for the specified kernel context 318description: 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. 323test: none 324end: 325 326function: rsGetDimArray2 327version: 23 328ret: uint32_t 329arg: rs_kernel_context context 330summary: Size of the Array2 dimension for the specified kernel context 331description: 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. 336test: none 337end: 338 339function: rsGetDimArray3 340version: 23 341ret: uint32_t 342arg: rs_kernel_context context 343summary: Size of the Array3 dimension for the specified kernel context 344description: 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. 349test: none 350end: 351 352function: rsGetDimHasFaces 353version: 23 354ret: bool, "Returns true if more than one face is present, false otherwise." 355arg: rs_kernel_context context 356summary: Presence of more than one face for the specified kernel context 357description: 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. 363test: none 364end: 365 366function: rsGetDimLod 367version: 23 368ret: uint32_t 369arg: rs_kernel_context context 370summary: Number of levels of detail for the specified kernel context 371description: 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. 379test: none 380end: 381 382function: rsGetDimX 383version: 23 384ret: uint32_t 385arg: rs_kernel_context context 386summary: Size of the X dimension for the specified kernel context 387description: 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(). 399test: none 400end: 401 402function: rsGetDimY 403version: 23 404ret: uint32_t 405arg: rs_kernel_context context 406summary: Size of the Y dimension for the specified kernel context 407description: 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(). 414test: none 415end: 416 417function: rsGetDimZ 418version: 23 419ret: uint32_t 420arg: rs_kernel_context context 421summary: Size of the Z dimension for the specified kernel context 422description: 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(). 429test: none 430end: 431 432function: rsGetFace 433version: 23 434ret: rs_allocation_cubemap_face 435arg: rs_kernel_context context 436summary: Coordinate of the Face for the specified kernel context 437description: 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. 443test: none 444end: 445 446function: rsGetLod 447version: 23 448ret: uint32_t 449arg: rs_kernel_context context 450summary: Index in the Levels of Detail dimension for the specified kernel context 451description: 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. 457test: none 458end: 459