Document unspecified dimensions.
Test: mm
Bug: 77234888
Bug: 109687058
Change-Id: Ia8928e494d8c712bc9cfb592d67476fde9753f45
(cherry picked from commit 8939b5df129777b6597f5f973552ae99ab956b35)
Merged-In: Ia8928e494d8c712bc9cfb592d67476fde9753f45
diff --git a/current.txt b/current.txt
index 28f0f99..018ef20 100644
--- a/current.txt
+++ b/current.txt
@@ -249,7 +249,7 @@
# Future changes to HALs
5804ca86611d72e5481f022b3a0c1b334217f2e4988dad25730c42af2d1f4d1c android.hardware.neuralnetworks@1.0::IDevice
12e8dca4ab7d8aadd0ef8f1b438021938e2396139e85db2ed65783b08800aa52 android.hardware.neuralnetworks@1.0::IExecutionCallback
-18e6885e184fe48401c2c53f1d1b8bfb07240f40c81ae6b9d2e336fca6efdbb7 android.hardware.neuralnetworks@1.0::types
+86b77e06da756a76aa3685be88765852dd982a86d8c90b8b4fc1130ed4184c8f android.hardware.neuralnetworks@1.0::types
# Documentation fixups for b/78135149
9e7a0b650d0e461ece2cfec0e1072abf8676f592b41a7fb48f01e88fc3c8f780 android.hardware.broadcastradio@1.0::types
diff --git a/neuralnetworks/1.0/types.hal b/neuralnetworks/1.0/types.hal
index 4efa13a..1ae1726 100644
--- a/neuralnetworks/1.0/types.hal
+++ b/neuralnetworks/1.0/types.hal
@@ -1519,6 +1519,41 @@
/**
* Dimensions of the operand.
+ *
+ * For a scalar operand, dimensions.size() must be 0.
+ *
+ * For a tensor operand, dimensions.size() must be at least 1;
+ * however, any of the dimensions may be unspecified.
+ *
+ * A tensor operand with all dimensions specified has "fully
+ * specified" dimensions. Whenever possible (i.e., whenever the
+ * dimensions are known at model construction time), a tensor
+ * operand should have (but is not required to have) fully
+ * specified dimensions, in order to enable the best possible
+ * performance.
+ *
+ * If a tensor operand's dimensions are not fully specified, the
+ * dimensions of the operand are deduced from the operand
+ * dimensions and values of the operation for which that operand
+ * is an output.
+ *
+ * In the following situations, a tensor operand's dimensions must
+ * be fully specified:
+ *
+ * . The operand has lifetime CONSTANT_COPY or
+ * CONSTANT_REFERENCE.
+ *
+ * . The operand has lifetime MODEL_INPUT or MODEL_OUTPUT. Fully
+ * specified dimensions must either be present in the
+ * Operand or they must be provided in the corresponding
+ * RequestArgument.
+ * EXCEPTION: If the input or output is optional and omitted
+ * (by setting the hasNoValue field of the corresponding
+ * RequestArgument to true) then it need not have fully
+ * specified dimensions.
+ *
+ * A tensor operand with some number of unspecified dimensions is
+ * represented by setting each unspecified dimension to 0.
*/
vec<uint32_t> dimensions;
@@ -1662,10 +1697,19 @@
/**
* Updated dimension information.
*
- * If dimensions.size() > 0, dimension information was provided along with
- * the argument. This can be the case for models that accept inputs of
- * varying size. This can't change the rank, just the value of the
- * dimensions that were unspecified in the model.
+ * If dimensions.size() > 0, dimension information was provided
+ * along with the argument. This can be the case for models that
+ * accept inputs of varying size. This can't change the rank, just
+ * the value of the dimensions that were unspecified in the
+ * model. If dimensions.size() > 0, then all dimensions must be
+ * specified here; and any dimension that was specified in the
+ * model must have the same value here.
+ *
+ * If the dimensions in the model are not fully specified, then
+ * they must be fully specified here, unless hasNoValue is set to
+ * true. If the dimensions in the model are fully specified, then
+ * either dimensions.size() may be 0, or the dimensions in the
+ * model must be identical to the dimensions here.
*/
vec<uint32_t> dimensions;
};