Updated spec for the rsForEachInternal API
Bug: 23535985
Missed the spec for rsForEachInternal in previous CLs.
The right prototype is
rsForEachInternal(int, rs_script_call*, int, int, ...)
or mangled as
_Z17rsForEachInternaliP14rs_script_calliiz
The bcc whitelist was correctly updated in previous CLs.
This is an internal API, therefore header files are not affected.
Updated the api generator to handle the new case of ellipsis being used
in a C++/overloadable, name-mangled function.
Change-Id: Ib6e1341b02eccc64574ebca04c54a7673cb9726e
diff --git a/api/GenerateHeaderFiles.cpp b/api/GenerateHeaderFiles.cpp
index 9d5b49a..ce778b3 100644
--- a/api/GenerateHeaderFiles.cpp
+++ b/api/GenerateHeaderFiles.cpp
@@ -239,7 +239,7 @@
if (p->isOutParameter) {
ps << "*";
}
- if (!p->specName.empty()) {
+ if (!p->specName.empty() && p->rsType != "...") {
ps << " " << p->specName;
}
const string s = ps.str();
diff --git a/api/GenerateStubsWhiteList.cpp b/api/GenerateStubsWhiteList.cpp
index 69afdbf..dcdbbeb 100644
--- a/api/GenerateStubsWhiteList.cpp
+++ b/api/GenerateStubsWhiteList.cpp
@@ -199,6 +199,9 @@
delta = mangleLongName(tokens->front());
isTerminal = true;
tokens->pop_front();
+ } else if (eatFront(tokens, "...")) {
+ delta = "z";
+ isTerminal = true;
} else {
const char* c = findManglingOfBuiltInType(tokens);
if (c) {
diff --git a/api/Scanner.cpp b/api/Scanner.cpp
index 1bd4973..aa382f3 100644
--- a/api/Scanner.cpp
+++ b/api/Scanner.cpp
@@ -177,7 +177,7 @@
if (nameStart == string::npos) {
if (s == "...") {
p->name = s;
- p->type = "";
+ p->type = s;
p->lineNumber = mLineNumber;
return p;
} else {
diff --git a/api/rs_for_each.spec b/api/rs_for_each.spec
index c9bb2e6..bfe8e7e 100644
--- a/api/rs_for_each.spec
+++ b/api/rs_for_each.spec
@@ -119,15 +119,15 @@
The kernel must be defined in the current script. In addition, more than one
inputs can be used.
-E.g.<code><br/>
+ E.g.<code><br/>
float __attribute__((kernel)) square(float a) {<br/>
return a * a;<br/>
}<br/>
-<br/>
+ <br/>
void compute(rs_allocation ain, rs_allocation aout) {<br/>
rsForEach(square, ain, aout);<br/>
}<br/>
-<br/></code>
+ <br/></code>
test: none
end:
@@ -176,7 +176,8 @@
function: rsForEach
version: UNRELEASED
intrinsic: true
-attrib: = # Not overloadable
+# Not overloadable
+attrib: =
ret: void
arg: rs_kernel kernel, "Function designator to a function that is defined with the kernel attribute."
arg: ..., "Input and output allocations"
@@ -186,7 +187,8 @@
function: rsForEachWithOptions
version: UNRELEASED
intrinsic: true
-attrib: = # Not overloadable
+# Not overloadable
+attrib: =
ret: void
arg: rs_kernel kernel, "Function designator to a function that is defined with the kernel attribute."
arg: rs_script_call_t* options, "Launch options"
@@ -201,15 +203,14 @@
and return value expected by the kernel function. The output allocation is
present if and only if the kernel has a non-void return value.
- E.g., <code><br/>
+ E.g.,<code><br/>
rs_script_call_t opts = {0};<br/>
opts.xStart = 0;<br/>
opts.xEnd = dimX;<br/>
opts.yStart = 0;<br/>
opts.yEnd = dimY / 2;<br/>
rsForEachWithOptions(foo, &opts, out, out);<br/>
-</code>
-
+ </code>
test: none
end:
@@ -219,10 +220,12 @@
ret: void
arg: int slot
arg: rs_script_call_t* options
-arg: rs_allocation input
-arg: rs_allocation output
+arg: int hasOutput, "Indicates whether the kernel generates output"
+arg: int numInputs, "Number of input allocations"
+arg: ..., "Input and output allocations"
summary: (Internal API) Launch a kernel in the current Script (with the slot number)
description:
+ Internal API to launch a kernel.
test: none
end:
diff --git a/scriptc/rs_for_each.rsh b/scriptc/rs_for_each.rsh
index 6a42b41..ec46e42 100644
--- a/scriptc/rs_for_each.rsh
+++ b/scriptc/rs_for_each.rsh
@@ -101,26 +101,34 @@
#endif
/*
- * rsForEach: Invoke the root kernel of a script
+ * rsForEach: Launches a kernel
*
- * Invoke the kernel named "root" of the specified script. Like other kernels, this root()
- * function will be invoked repeatedly over the cells of the specificed allocation, filling
- * the output allocation with the results.
+ * Runs the kernel over zero or more input allocations. They are passed after the
+ * rs_kernel argument. If the specified kernel returns a value, an output allocation
+ * must be specified as the last argument. All input allocations,
+ * and the output allocation if it exists, must have the same dimensions.
*
- * When rsForEach is called, the root script is launched immediately. rsForEach returns
- * only when the script has completed and the output allocation is ready to use.
+ * This is a synchronous function. A call to this function only returns after all
+ * the work has completed for all cells of the input allocations. If the kernel
+ * function returns any value, the call waits until all results have been written
+ * to the output allocation.
*
- * The rs_script argument is typically initialized using a global variable set from Java.
+ * Up to API level 23, the kernel is implicitly specified as the kernel named
+ * "root" in the specified script, and only a single input allocation can be used.
+ * Starting in API level *UNRELEASED*, an arbitrary kernel function can be used,
+ * as specified by the kernel argument. The script argument is removed.
+ * The kernel must be defined in the current script. In addition, more than one
+ * inputs can be used.
*
- * The kernel can be invoked with just an input allocation or just an output allocation.
- * This can be done by defining an rs_allocation variable and not initializing it. E.g.
- * rs_script gCustomScript;
- * void specializedProcessing(rs_allocation in) {
- * rs_allocation ignoredOut;
- * rsForEach(gCustomScript, in, ignoredOut);
+ * E.g.
+ * float __attribute__((kernel)) square(float a) {
+ * return a * a;
* }
*
- * If both input and output allocations are specified, they must have the same dimensions.
+ * void compute(rs_allocation ain, rs_allocation aout) {
+ * rsForEach(square, ain, aout);
+ * }
+ *
*
* Parameters:
* script: Script to call.
@@ -162,13 +170,28 @@
#if (defined(RS_VERSION) && (RS_VERSION >= 4294967295) && (defined(RS_DECLARE_EXPIRED_APIS) || RS_VERSION <= 4294967295))
extern void
- rsForEach(rs_kernel kernel, ...);
+ rsForEach(rs_kernel kernel, ...);
#endif
/*
- * rsForEachWithOptions: TBD
+ * rsForEachWithOptions: Launches a kernel with options
*
- * TBD
+ * Launches kernel in a way similar to rsForEach. However, instead of processing
+ * all cells in the input, this function only processes cells in the subspace of
+ * the index space specified in options. With the index space explicitly specified
+ * by options, no input or output allocation is required for a kernel launch using
+ * this API. If allocations are passed in, they must match the number of arguments
+ * and return value expected by the kernel function. The output allocation is
+ * present if and only if the kernel has a non-void return value.
+ *
+ * E.g.,
+ * rs_script_call_t opts = {0};
+ * opts.xStart = 0;
+ * opts.xEnd = dimX;
+ * opts.yStart = 0;
+ * opts.yEnd = dimY / 2;
+ * rsForEachWithOptions(foo, &opts, out, out);
+ *
*
* Parameters:
* kernel: Function designator to a function that is defined with the kernel attribute.
@@ -177,7 +200,7 @@
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 4294967295) && (defined(RS_DECLARE_EXPIRED_APIS) || RS_VERSION <= 4294967295))
extern void
- rsForEachWithOptions(rs_kernel kernel, rs_script_call_t* options, ...);
+ rsForEachWithOptions(rs_kernel kernel, rs_script_call_t* options, ...);
#endif
/*
