"successful preparation means successful execution" guarantee neglects bad operation inputs
Under certain circumstances, we guarantee that a prepared model can be
executed successfully. In describing those circumstances, we
neglected to specify that operation input operands must have legal
values for the guarantee to hold. For example, the guarantee doesn't
hold if an ADD operation has an activation input that is not one of
the defined values; or if a RESHAPE operation has a shape input in
which two or more components are -1.
This change modifies the guarantee to apply only when operation input
operands have legal values. It also documents this guarantee for
burst execution.
Note that if an operation has an input operand that can be proven to
have an illegal value at preparation time (e.g., a constant value that
is illegal), model preparation might (but is not required to) fail for
that reason.
Bug: 135933040
Test: $ cd neuralnetworks ; mma
Change-Id: I8b421550dd89e4bbbdae899e7cb5e9e88a46d2fb
diff --git a/current.txt b/current.txt
index 2aa9ef2..44eebf8 100644
--- a/current.txt
+++ b/current.txt
@@ -574,8 +574,8 @@
# ABI preserving changes to HALs during Android R
2410dd02d67786a732d36e80b0f8ccf55086604ef37f9838e2013ff2c571e404 android.hardware.camera.device@3.5::types
b69a7615c508acf5c5201efd1bfa3262167874fc3594e2db5a3ff93addd8ac75 android.hardware.keymaster@4.0::IKeymasterDevice
-ad431c8de51c07934a068e3043d8dd0537ac4d3158627706628b123f42df48dc android.hardware.neuralnetworks@1.0::IPreparedModel
+eb2fa0c883c2185d514be0b84c179b283753ef0c1b77b45b4f359bd23bba8b75 android.hardware.neuralnetworks@1.0::IPreparedModel
fb382e986c10b8fbb797a8546e8f9ea6d1107bfe6f3fb7e57f6bbbf1f807a906 android.hardware.neuralnetworks@1.2::IDevice
-aafcc10cf04ab247e86d4582586c71c6b4c2b8c479241ffa7fe37deb659fc942 android.hardware.neuralnetworks@1.2::IPreparedModel
+6c5081dd131eeb7eb02efece2187cd4d7d554197800bb520c92ff874cc238fa6 android.hardware.neuralnetworks@1.2::IPreparedModel
1a6e2bd289f22931c526b21916910f1d4c436b7acb9556e4243de4ce8e6cc2e4 android.hardware.soundtrigger@2.0::ISoundTriggerHwCallback
fd65298e1e09e0e3c781ab18305920d757dbe55a3b459ce17814ec5cf6dfee99 android.hardware.wifi@1.0::IWifiP2pIface
diff --git a/neuralnetworks/1.0/IPreparedModel.hal b/neuralnetworks/1.0/IPreparedModel.hal
index 5320050..3dc3202 100644
--- a/neuralnetworks/1.0/IPreparedModel.hal
+++ b/neuralnetworks/1.0/IPreparedModel.hal
@@ -49,11 +49,14 @@
* must not change the content of any of the data objects corresponding to
* 'request' inputs.
*
- * If the prepared model was prepared from a model wherein all
- * tensor operands have fully specified dimensions, and the inputs
- * to the function are valid, then the execution should launch
- * and complete successfully (ErrorStatus::NONE). There must be
- * no failure unless the device itself is in a bad state.
+ * If the prepared model was prepared from a model wherein all tensor
+ * operands have fully specified dimensions, and the inputs to the function
+ * are valid, then:
+ * - the execution should launch successfully (ErrorStatus::NONE): There
+ * must be no failure unless the device itself is in a bad state.
+ * - if at execution time every operation's input operands have legal
+ * values, the execution should complete successfully (ErrorStatus::NONE):
+ * There must be no failure unless the device itself is in a bad state.
*
* Multiple threads can call the execute function on the same IPreparedModel
* object concurrently with different requests.
diff --git a/neuralnetworks/1.2/IPreparedModel.hal b/neuralnetworks/1.2/IPreparedModel.hal
index ba16334..f3508fe 100644
--- a/neuralnetworks/1.2/IPreparedModel.hal
+++ b/neuralnetworks/1.2/IPreparedModel.hal
@@ -54,11 +54,14 @@
* must not change the content of any of the data objects corresponding to
* 'request' inputs.
*
- * If the prepared model was prepared from a model wherein all
- * tensor operands have fully specified dimensions, and the inputs
- * to the function are valid, then the execution should launch
- * and complete successfully (ErrorStatus::NONE). There must be
- * no failure unless the device itself is in a bad state.
+ * If the prepared model was prepared from a model wherein all tensor
+ * operands have fully specified dimensions, and the inputs to the function
+ * are valid, then:
+ * - the execution should launch successfully (ErrorStatus::NONE): There
+ * must be no failure unless the device itself is in a bad state.
+ * - if at execution time every operation's input operands have legal
+ * values, the execution should complete successfully (ErrorStatus::NONE):
+ * There must be no failure unless the device itself is in a bad state.
*
* Any number of calls to the execute, execute_1_2, and executeSynchronously
* functions, in any combination, may be made concurrently, even on the same
@@ -105,8 +108,9 @@
*
* If the prepared model was prepared from a model wherein all tensor
* operands have fully specified dimensions, and the inputs to the function
- * are valid, then the execution should complete successfully
- * (ErrorStatus::NONE). There must be no failure unless the device itself is
+ * are valid, and at execution time every operation's input operands have
+ * legal values, then the execution should complete successfully
+ * (ErrorStatus::NONE): There must be no failure unless the device itself is
* in a bad state.
*
* Any number of calls to the execute, execute_1_2, and executeSynchronously
@@ -145,6 +149,13 @@
* Configure a Burst object used to execute multiple inferences on a
* prepared model in rapid succession.
*
+ * If the prepared model was prepared from a model wherein all tensor
+ * operands have fully specified dimensions, and a valid serialized Request
+ * is sent to the Burst for execution, and at execution time every
+ * operation's input operands have legal values, then the execution should
+ * complete successfully (ErrorStatus::NONE): There must be no failure
+ * unless the device itself is in a bad state.
+ *
* @param callback A callback object used to retrieve memory resources
* corresponding to a unique identifiers ("slots").
* @param requestChannel Used by the client to send a serialized Request to