Merge "NNAPI Burst -- HAL interface"

neuralnetworks/1.2/Android.bp

@@ -8,6 +8,8 @@ hidl_interface {
     },
     srcs: [
         "types.hal",
+        "IBurstCallback.hal",
+        "IBurstContext.hal",
         "IDevice.hal",
         "IExecutionCallback.hal",
         "IPreparedModel.hal",
@@ -20,6 +22,9 @@ hidl_interface {
         "android.hidl.safe_union@1.0",
     ],
     types: [
+        "DeviceType",
+        "FmqRequestDatum",
+        "FmqResultDatum",
         "Model",
         "Operand",
         "OperandType",
@@ -28,6 +33,7 @@ hidl_interface {
         "OperationType",
         "OperationTypeRange",
         "OutputShape",
+        "SymmPerChannelQuantParams",
     ],
     gen_java: false,
 }

neuralnetworks/1.2/IBurstCallback.hal

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.neuralnetworks@1.2;
+
+import @1.0::ErrorStatus;
+
+/**
+ * Callback object used by a service to retreive memory objects based on unique
+ * identifiers ("slots").
+ */
+interface IBurstCallback {
+    /**
+     * Get the memory regions that correspond to slot ids. The slot ids are are
+     * unique to the burst object.
+     *
+     * @param slots Values uniquely identifying memory regions within a Burst.
+     * @return status Indicates whether the memories were successfully returned;
+     *                must be:
+     *                - NONE if the memory region was successfully retrieved
+     *                - GENERAL_FAILURE if there is an unspecified error
+     *                - INVALID_ARGUMENT if a slot number is invalid
+     * @return buffers Memory buffers corresponding to the slot numbers. If an
+     *                 error occurs, an empty vector must be returned for
+     *                 buffers, otherwise slots.size() == buffers.size().
+     */
+    getMemories(vec<int32_t> slots) generates (ErrorStatus status, vec<memory> buffers);
+};

neuralnetworks/1.2/IBurstContext.hal

@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.neuralnetworks@1.2;
+
+/**
+ * Context object to manage the resources of a burst.
+ */
+interface IBurstContext {
+    /**
+     * freeMemory is used by the client to signal to the service that a memory
+     * buffer corresponding to a slot number is no longer needed by the client.
+     *
+     * The slot ids are unique to the burst object.
+     *
+     * @param slot Value uniquely identifying a memory region.
+     */
+    freeMemory(int32_t slot);
+};

neuralnetworks/1.2/IPreparedModel.hal

@@ -19,6 +19,8 @@ package android.hardware.neuralnetworks@1.2;
 import @1.0::ErrorStatus;
 import @1.0::IPreparedModel;
 import @1.0::Request;
+import IBurstCallback;
+import IBurstContext;
 import IExecutionCallback;
 
 /**
@@ -113,4 +115,34 @@ interface IPreparedModel extends @1.0::IPreparedModel {
      */
     executeSynchronously(Request request)
         generates (ErrorStatus status, vec<OutputShape> outputShapes);
+
+    /**
+     * Configure a Burst object used to execute multiple inferences on a
+     * prepared model in rapid succession.
+     *
+     * @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
+     *                       the Burst for execution. requestChannel must not be
+     *                       used to pass a second Request object until a result
+     *                       has been received from resultChannel.
+     * @param resultChannel Used by the service to return the results of an
+     *                      execution to the client: the status of the execution
+     *                      and OutputShape of all output tensors. resultChannel
+     *                      must be used to return the results if a Request was
+     *                      sent through the requestChannel.
+     * @return status Error status of configuring the execution burst, must be:
+     *                - NONE if the burst is successfully configured
+     *                - DEVICE_UNAVAILABLE if driver is offline or busy
+     *                - GENERAL_FAILURE if there is an unspecified error
+     *                - INVALID_ARGUMENT if one of the input arguments is
+     *                  invalid
+     * @return context Object containing all resources (such as cached
+     *                 hidl_memory) related to a Burst if successful, otherwise
+     *                 nullptr.
+     */
+    configureExecutionBurst(IBurstCallback callback,
+                            fmq_sync<FmqRequestDatum> requestChannel,
+                            fmq_sync<FmqResultDatum> resultChannel)
+                 generates (ErrorStatus status, IBurstContext context);
 };

neuralnetworks/1.2/types.hal

@@ -17,6 +17,7 @@
 package android.hardware.neuralnetworks@1.2;
 
 import @1.0::DataLocation;
+import @1.0::ErrorStatus;
 import @1.0::OperandLifeTime;
 import @1.0::OperandType;
 import @1.0::PerformanceInfo;
@@ -444,3 +445,195 @@ struct OutputShape {
      */
     bool isSufficient;
 };
+
+/**
+ * FmqRequestDatum is a single element of a serialized representation of a
+ * {@link @1.0::Request} object which is sent across FastMessageQueue.
+ *
+ * The serialized representation for a particular execution is referred to later
+ * in these descriptions as a 'packet'.
+ *
+ * FastMessageQueue can only pass HIDL-defined types that do not involve nested
+ * buffers, handles, or interfaces.
+ *
+ * The {@link @1.0::Request} is serialized as follows:
+ * 1) 'packetInformation'
+ * 2) For each input operand:
+ *    2.1) 'inputOperandInformation'
+ *    2.2) For each dimension element of the operand:
+ *         2.2.1) 'inputOperandDimensionValue'
+ * 3) For each output operand:
+ *    3.1) 'outputOperandInformation'
+ *    3.2) For each dimension element of the operand:
+ *         3.2.1) 'outputOperandDimensionValue'
+ * 4) For each pool:
+ *    4.1) 'poolIdentifier'
+ */
+safe_union FmqRequestDatum {
+    /**
+     * Type to describe the high-level layout of the packet.
+     */
+    struct PacketInformation {
+        /**
+         * How many elements the packet contains, including the
+         * "packetInformation" datum.
+         */
+        uint32_t packetSize;
+
+        /**
+         * Number of input operands.
+         */
+        uint32_t numberOfInputOperands;
+
+        /**
+         * Number of output operands.
+         */
+        uint32_t numberOfOutputOperands;
+
+        /**
+         * Number of pool identifiers.
+         */
+        uint32_t numberOfPools;
+    };
+
+    /**
+     * Type representing the information for each operand.
+     */
+    struct OperandInformation {
+        /**
+         * If true, the argument does not have a value. This can be used for
+         * operations that take optional arguments. If true, the fields of
+         * 'location' are set to 0, 'numberOfDimensions' is set to 0,  and the
+         * dimensions information is omitted from the serialization.
+         */
+        bool hasNoValue;
+
+        /**
+         * The location within one of the memory pools passed in the Request.
+         */
+        DataLocation location;
+
+        /**
+         * Number of subsequent elements that belong to the dimensions vector.
+         */
+        uint32_t numberOfDimensions;
+    };
+
+    /**
+     * packetInformation is the first element of the packet and describes the
+     * remainder of the packet.
+     */
+    PacketInformation packetInformation;
+
+    /**
+     * Information for each input operand.
+     */
+    OperandInformation inputOperandInformation;
+
+    /**
+     * Element of the dimensions vector.
+     */
+    uint32_t inputOperandDimensionValue;
+
+    /**
+     * Information for each output operand.
+     */
+    OperandInformation outputOperandInformation;
+
+    /**
+     * Element of the dimensions vector.
+     */
+    uint32_t outputOperandDimensionValue;
+
+    /**
+     * Unique identifier for a pool.
+     *
+     * A {@link @1.0::Request} passes across one or more pools of shared memory
+     * for the inputs and outputs of an execution. However, these memory pools
+     * are not able to be sent across FastMessageQueue directly. Instead, the
+     * producing side of the FMQ represents each different pool with a unique
+     * identifier, and sends this identifier across the FMQ. Whenever the
+     * consuming side of the FMQ needs the memory corresponding to this unique
+     * identifier, it can pass the identifier to
+     * {@link IBurstCallback::getMemories} to retreive the memory. Although this
+     * HIDL Binder call is expensive compared to communication across FMQ, it is
+     * only needed in the cases when the consumer does not recognize the unique
+     * identifier.
+     */
+    int32_t poolIdentifier;
+};
+
+/**
+ * FmqResultDatum is a single element of a serialized representation of the
+ * values returned from an execution ({@link @1.0::ErrorStatus} and
+ * vec<{@link OutputShape}>) which is returned via FastMessageQueue.
+ *
+ * The serialized representation for a particular execution is referred to later
+ * in these descriptions as a 'packet'.
+ *
+ * FastMessageQueue can only pass HIDL-defined types that do not involve nested
+ * buffers, handles, or interfaces.
+ *
+ * The execution return values ({@link @1.0::ErrorStatus} and
+ * vec<{@link OutputShape}>) are serialized as follows:
+ * 1) 'packetInformation'
+ * 2) For each returned operand:
+ *    2.1) 'operandInformation'
+ *    2.2) For each dimension element of the operand:
+ *         2.2.1) 'operandDimensionValue'
+ */
+safe_union FmqResultDatum {
+    /**
+     * Type to describe the high-level layout of the packet.
+     */
+    struct PacketInformation {
+        /**
+         * How many elements the packet contains, including the
+         * "packetInformation" datum.
+         */
+        uint32_t packetSize;
+
+        /**
+         * Status of the execution.
+         */
+        ErrorStatus errorStatus;
+
+        /**
+         * Number of returned operands.
+         */
+        uint32_t numberOfOperands;
+    };
+
+    /**
+     * Type representing the information for each operand.
+     */
+    struct OperandInformation {
+        /**
+         * Indicates whether the operand's output buffer is large enough to
+         * store the operand's result data.
+         */
+        bool isSufficient;
+
+        /**
+         * Number of subsequent elements that belong to the dimensions vector.
+         */
+        uint32_t numberOfDimensions;
+    };
+
+    /**
+     * packetInformation is the first element of the packet and describes the
+     * remainder of the packet. It additionally includes the status of the
+     * execution.
+     */
+    PacketInformation packetInformation;
+
+    /**
+     * Information for each returned operand.
+     */
+    OperandInformation operandInformation;
+
+    /**
+     * Element of the dimensions vector.
+     */
+    uint32_t operandDimensionValue;
+};