From 9ecf6c51674bcf182185d3c80788c5d796415487 Mon Sep 17 00:00:00 2001 From: David Gross Date: Mon, 4 Jun 2018 15:52:30 -0700 Subject: Document unspecified dimensions. Test: mm Bug: 77234888 Bug: 109687058 Change-Id: I8bc8aa1cb3d5092e94f34aa245bc4185516ac434 --- nn/runtime/include/NeuralNetworks.h | 101 ++++++++++++++++++++++++++---------- 1 file changed, 75 insertions(+), 26 deletions(-) diff --git a/nn/runtime/include/NeuralNetworks.h b/nn/runtime/include/NeuralNetworks.h index e0d09ae24..ce1d8842b 100644 --- a/nn/runtime/include/NeuralNetworks.h +++ b/nn/runtime/include/NeuralNetworks.h @@ -1911,11 +1911,48 @@ typedef struct ANeuralNetworksExecution ANeuralNetworksExecution; /** * ANeuralNetworksOperandType describes the type of an operand. * This structure is used to describe both scalars and tensors. + * + * A tensor operand type must have a specified rank (number of + * dimensions) but may have any of its dimensions unspecified. + * + * A tensor operand type with all dimensions specified is "fully + * specified". Whenever possible (i.e., whenever the dimensions are + * known at model construction time), a tensor operand type should be + * (but is not required to be) fully specified, in order to enable the + * best possible performance. + * + * If a tensor operand's type is not fully specified, the dimensions + * of the operand are deduced from the operand types and values of the + * operation for which that operand is an output. + * + *

In the following situations, a tensor operand type must be fully + * specified:

+ * + * A tensor operand type with some number of unspecified dimensions is + * represented by setting each unspecified dimension to 0. */ typedef struct ANeuralNetworksOperandType { /** The data type, e.g ANEURALNETWORKS_INT8. */ int32_t type; - /** The number of dimensions. It should be 0 for scalars. */ + /** The number of dimensions (rank). It should be 0 for scalars. */ uint32_t dimensionCount; /** The dimensions of the tensor. It should be nullptr for scalars. */ const uint32_t* dimensions; @@ -2037,10 +2074,11 @@ int ANeuralNetworksModel_finish(ANeuralNetworksModel* model); * {@link ANeuralNetworksExecution_setOutputFromMemory} and * {@link ANeuralNetworksExecution_setOperandValue}. * - * To build a model that can accomodate inputs of various sizes, as you may want - * to do for a CNN, set the size of the dimensions that will vary at run time to 0. - * If you do so, provide the full dimensions when calling - * {@link ANeuralNetworksExecution_setInput} or {@link ANeuralNetworksExecution_setInputFromMemory}. + * To build a model that can accommodate inputs of various sizes, as + * you may want to do for a CNN, leave unspecified the dimensions that + * will vary at run time. If you do so, fully specify dimensions + * when calling {@link ANeuralNetworksExecution_setInput} or + * {@link ANeuralNetworksExecution_setInputFromMemory}. * * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has been * called will return an error. @@ -2318,12 +2356,16 @@ void ANeuralNetworksExecution_free(ANeuralNetworksExecution* execution); * @param index The index of the input argument we are setting. It is * an index into the lists passed to * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is not - * the index associated with {@link ANeuralNetworksModel_addOperand}. - * @param type The {@link ANeuralNetworksOperandType} of the operand. This should - * be used to specify the dimensions that were set to 0 when the - * operand was added to the model. All other properties of the type - * must be the same as specified in the model. If the type is the - * same as specified when the model was built, NULL can be passed. + * the index associated with + * {@link ANeuralNetworksModel_addOperand}. + * @param type The {@link ANeuralNetworksOperandType} of the + * operand. Unless the input is omitted, this should be + * used to specify the dimensions that were left + * unspecified when the operand was added to the + * model. All other properties of the type must be the + * same as specified in the model. If the type is the same + * as specified when the model was built, NULL can be + * passed. * @param buffer The buffer containing the data. * @param length The length in bytes of the buffer. * @@ -2351,11 +2393,13 @@ int ANeuralNetworksExecution_setInput(ANeuralNetworksExecution* execution, int32 * an index into the lists passed to * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is not * the index associated with {@link ANeuralNetworksModel_addOperand}. - * @param type The {@link ANeuralNetworksOperandType} of the operand. This can be - * used to specify the dimensions that were set to 0 when the operand - * was added to the model. All other values must be the same as - * specified in the model. If the type is the same as specified when - * the model was built, NULL can be passed. + * @param type The {@link ANeuralNetworksOperandType} of the + * operand. This should be used to specify the dimensions + * that were left unspecified when the operand was added + * to the model. All other properties of the type must be + * the same as specified in the model. If the type is the + * same as specified when the model was built, NULL can be + * passed. * @param memory The memory containing the data. * @param offset This specifies the location of the data within the memory. * The offset is in bytes from the start of memory. @@ -2385,11 +2429,14 @@ int ANeuralNetworksExecution_setInputFromMemory(ANeuralNetworksExecution* execut * an index into the lists passed to * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is not * the index associated with {@link ANeuralNetworksModel_addOperand}. - * @param type The {@link ANeuralNetworksOperandType} of the operand. This can be - * used to specify the dimensions that were set to 0 when the operand - * was added to the model. All other values must be the same as - * specified in the model. If the type is the same as specified when - * the model was built, NULL can be passed. + * @param type The {@link ANeuralNetworksOperandType} of the + * operand. Unless the output is omitted, this should be + * used to specify the dimensions that were left + * unspecified when the operand was added to the + * model. All other properties of the type must be the + * same as specified in the model. If the type is the same + * as specified when the model was built, NULL can be + * passed. * @param buffer The buffer where the data is to be written. * @param length The length in bytes of the buffer. * @@ -2417,11 +2464,13 @@ int ANeuralNetworksExecution_setOutput(ANeuralNetworksExecution* execution, int3 * an index into the lists passed to * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is not * the index associated with {@link ANeuralNetworksModel_addOperand}. - * @param type The {@link ANeuralNetworksOperandType} of the operand. This can be - * used to specify the dimensions that were set to 0 when the operand - * was added to the model. All other values must be the same as - * specified in the model. If the type is the same as specified when - * the model was built, NULL can be passed. + * @param type The {@link ANeuralNetworksOperandType} of the operand. This should be + * used to specify the dimensions that were left + * unspecified when the operand was added to the + * model. All other properties of the type must be the + * same as specified in the model. If the type is the same + * as specified when the model was built, NULL can be + * passed. * @param memory The memory where the data is to be stored. * @param offset This specifies the location of the data within the memory. * The offset is in bytes from the start of memory. -- cgit v1.2.3