Memory Domain HAL: Define HAL APIs.

- Add and document memory domain HAL APIs.
- Make necessary changes to the existing VTS codes to make them work
  with V1_3::Request.

Bug: 141353602
Bug: 141363565
Test: mma
Test: NNT_static
Test: 1.3 VTS
Change-Id: Ia32555d4fef149fad4a79728981c5d9cca675a1a
Merged-In: Ia32555d4fef149fad4a79728981c5d9cca675a1a
(cherry picked from commit 931d5a18bc)
This commit is contained in:
Xusong Wang 2019-11-27 12:46:48 -08:00
parent 7b37dc5d9c
commit b345a4688f
10 changed files with 337 additions and 24 deletions

View file

@ -622,10 +622,11 @@ bbeee9604128ede83ee755b67e73b5ad29e6e1dbac9ec41fea6ffe2745b0c50a android.hardwar
27ae3724053940462114228872b3ffaf0b8e6177d5ba97f5a76339d12b8a99dd android.hardware.keymaster@4.1::IKeymasterDevice
adb0efdf1462e9b2e742c0dcadd598666aac551f178be06e755bfcdf5797abd0 android.hardware.keymaster@4.1::IOperation
ac429fca0da4ce91218768ec31b64ded88251f8a26d8c4f27c06abdc5b1926d9 android.hardware.keymaster@4.1::types
9e59fffceed0dd72a9799e04505db5f777bbbea1af0695ba4107ef6d967c6fda android.hardware.neuralnetworks@1.3::IDevice
258825966435b3ed08832055bb736d81516013e405f161d9ccde9a90cfcdde83 android.hardware.neuralnetworks@1.3::IPreparedModel
4b5c8546533db9412fec6d32c0ef42b22e5e68dbf390c775ec3c22bb2d501102 android.hardware.neuralnetworks@1.3::IBuffer
234cc547d63d2f24a447aee0a9a76cab68b31c080adadc5a960598b827a69fa2 android.hardware.neuralnetworks@1.3::IDevice
058b48f0e2e725bb2b3fa2b7917b0f0a696383d03a4c57afe26f0eadb6a7af28 android.hardware.neuralnetworks@1.3::IPreparedModel
94e803236398bed1febb11cc21051bc42ec003700139b099d6c479e02a7ca3c3 android.hardware.neuralnetworks@1.3::IPreparedModelCallback
f3c1e7298da628a755b452cd3325e8d0fe867a2debb873069baab6a27434a72d android.hardware.neuralnetworks@1.3::types
2576ba54711218ce0d7f207baa533fca9af3c630756938ede6e73fe197b7ea38 android.hardware.neuralnetworks@1.3::types
3e01d4446cd69fd1c48f8572efd97487bc179564b32bd795800b97bbe10be37b android.hardware.wifi@1.4::IWifi
a64467bae843569f0d465c5be7f0c7a5b987985b55a3ef4794dd5afc68538650 android.hardware.wifi.supplicant@1.3::ISupplicant
44445b8a03d7b9e68b2fbd954672c18a8fce9e32851b0692f4f4ab3407f86ecb android.hardware.wifi.supplicant@1.3::ISupplicantStaIface

View file

@ -8,6 +8,7 @@ hidl_interface {
},
srcs: [
"types.hal",
"IBuffer.hal",
"IDevice.hal",
"IPreparedModel.hal",
"IPreparedModelCallback.hal",

View file

@ -0,0 +1,57 @@
/*
* Copyright (C) 2020 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.3;
import @1.0::ErrorStatus;
/**
* This interface represents a device memory buffer.
*/
interface IBuffer {
/**
* Retrieves the content of this buffer to a shared memory region.
*
* The IBuffer object must have been initialized before the call to IBuffer::copyTo.
* For more information on the state of the IBuffer object, refer to IDevice::allocate.
*
* @param dst The destination shared memory region.
* @return status Error status of the call, must be:
* - NONE if successful
* - DEVICE_UNAVAILABLE if driver is offline or busy
* - GENERAL_FAILURE if the IBuffer object is uninitialized, or there is an unspecified
* error
* - INVALID_ARGUMENT if provided memory is invalid
*/
copyTo(memory dst) generates (ErrorStatus status);
/**
* Sets the content of this buffer from a shared memory region.
*
* @param src The source shared memory region.
* @param dimensions Updated dimensional information. If the dimensions of the IBuffer object
* are not fully specified, then the dimensions must be fully specified here. If the
* dimensions of the IBuffer object are fully specified, then the dimensions may be empty
* here. If dimensions.size() > 0, then all dimensions must be specified here, and any
* dimension that was specified in the IBuffer object must have the same value here.
* @return status Error status of the call, must be:
* - NONE if successful
* - DEVICE_UNAVAILABLE if driver is offline or busy
* - GENERAL_FAILURE if there is an unspecified error
* - INVALID_ARGUMENT if provided memory is invalid, or if the dimensions is invalid
*/
copyFrom(memory src, vec<uint32_t> dimensions) generates (ErrorStatus status);
};

View file

@ -22,6 +22,12 @@ import @1.2::Constant;
import @1.2::DeviceType;
import @1.2::Extension;
import @1.2::IDevice;
import BufferDesc;
import BufferRole;
import Capabilities;
import Model;
import IBuffer;
import IPreparedModel;
import IPreparedModelCallback;
/**
@ -247,4 +253,61 @@ interface IDevice extends @1.2::IDevice {
uint8_t[Constant:BYTE_SIZE_OF_CACHE_TOKEN] token,
IPreparedModelCallback callback)
generates (ErrorStatus status);
/**
* Allocates a driver-managed buffer with the properties specified by the buffer descriptor
* as well as the input and output roles.
*
* The allocate function must verify its inputs are correct. If there is an error, or if a
* certain role or property is not supported by the driver, the allocate
* function must return with an appropriate ErrorStatus, a nullptr as the IBuffer, and 0 as the
* buffer token. If the allocation is successful, this method must return with ErrorStatus::NONE
* and the produced IBuffer with a positive token identifying the allocated buffer. A successful
* allocation must accommodate all of the specified roles and buffer properties.
*
* The buffer is allocated to an uninitialized state. An uninitialized buffer may only be used
* in ways that are specified by outputRoles. A buffer is initialized after it is used as an
* output in a successful execution, or after a successful invocation of IBuffer::copyFrom on
* the buffer. An initialized buffer may be used according to all roles specified in inputRoles
* and outputRoles. A buffer will return to the uninitialized state if it is used as an output
* in a failed execution, or after a failed invocation of IBuffer::copyFrom on the buffer.
*
* The dimensions of the buffer can be deduced from the buffer descriptor as well as the
* dimensions of the corresponding model operands of the input and output roles. The dimensions
* or rank of the buffer may be unknown at this stage. As such, some driver services may only
* create a placeholder and defer the actual allocation until execution time. Note that the
* same buffer may be used for different shapes of outputs on different executions. When the
* buffer is used as an input, the input shape must be the same as the output shape from the
* last execution using this buffer as an output.
*
* The driver must apply proper validatation upon every usage of the buffer, and must fail the
* execution immediately if the usage is illegal.
*
* @param desc A buffer descriptor specifying the properties of the buffer to allocate.
* @param preparedModels A vector of IPreparedModel objects. Must only contain IPreparedModel
* objects from the same IDevice as this method is being invoked on.
* @param inputRoles A vector of roles with each specifying an input to a prepared model.
* @param outputRoles A vector of roles with each specifying an output to a prepared model.
* Each role specified in inputRoles and outputRoles must be unique. The corresponding
* model operands of the roles must have the same OperandType, scale, zero point, and
* ExtraParams. The dimensions of the operands and the dimensions specified in the buffer
* descriptor must be compatible with each other. Two dimensions are incompatible if there
* is at least one axis that is fully specified in both but has different values.
* @return status Error status of the buffer allocation. Must be:
* - NONE if successful
* - DEVICE_UNAVAILABLE if driver is offline or busy
* - GENERAL_FAILURE if a certain buffer property or a certain role is not supported,
* or if there is an unspecified error
* - INVALID_ARGUMENT if one of the input arguments is invalid
* @return buffer The allocated IBuffer object. If the buffer was unable to be allocated
* due to an error, nullptr must be returned.
* @return token A positive token identifying the allocated buffer. The same token will be
* provided when referencing the buffer as one of the memory pools in the request of an
* execution. The token must not collide with the tokens of other IBuffer objects that are
* currently alive in the same driver service. If the buffer was unable to be allocated
* due to an error, the token must be 0.
*/
allocate(BufferDesc desc, vec<IPreparedModel> preparedModels, vec<BufferRole> inputRoles,
vec<BufferRole> outputRoles)
generates (ErrorStatus status, IBuffer buffer, int32_t token);
};

View file

@ -17,12 +17,12 @@
package android.hardware.neuralnetworks@1.3;
import @1.0::ErrorStatus;
import @1.0::Request;
import @1.2::IExecutionCallback;
import @1.2::IPreparedModel;
import @1.2::MeasureTiming;
import @1.2::OutputShape;
import @1.2::Timing;
import Request;
/**
* IPreparedModel describes a model that has been prepared for execution and
@ -33,7 +33,8 @@ interface IPreparedModel extends @1.2::IPreparedModel {
* Launches an asynchronous execution on a prepared model.
*
* The execution is performed asynchronously with respect to the caller.
* execute_1_3 must verify the inputs to the function are correct. If there is
* execute_1_3 must verify the inputs to the function are correct, and the usages
* of memory pools allocated by IDevice::allocate are valid. If there is
* an error, execute_1_3 must immediately invoke the callback with the
* appropriate ErrorStatus value, then return with the same ErrorStatus. If
* the inputs to the function are valid and there is no error, execute_1_3 must
@ -95,7 +96,8 @@ interface IPreparedModel extends @1.2::IPreparedModel {
*
* The execution is performed synchronously with respect to the caller.
* executeSynchronously_1_3 must verify the inputs to the function are
* correct. If there is an error, executeSynchronously_1_3 must immediately
* correct, and the usages of memory pools allocated by IDevice::allocate
* are valid. If there is an error, executeSynchronously_1_3 must immediately
* return with the appropriate ErrorStatus value. If the inputs to the
* function are valid and there is no error, executeSynchronously_1_3 must
* perform the execution, and must not return until the execution is

View file

@ -19,6 +19,7 @@ package android.hardware.neuralnetworks@1.3;
import @1.0::DataLocation;
import @1.0::OperandLifeTime;
import @1.0::PerformanceInfo;
import @1.0::RequestArgument;
import @1.2::OperandType;
import @1.2::OperationType;
import @1.2::SymmPerChannelQuantParams;
@ -5205,3 +5206,92 @@ struct Model {
LOW_BITS_TYPE = 16,
};
};
/**
* A buffer descriptor. Describes the properties of a buffer.
*/
struct BufferDesc {
/**
* Dimensions of the buffer. May have unknown dimensions or rank. A buffer with some number
* of unspecified dimensions is represented by setting each unspecified dimension to 0. A
* buffer with unspecified rank is represented by providing an empty dimensions vector.
*/
vec<uint32_t> dimensions;
};
/**
* Describes a role of an input or output to a prepared model.
*/
struct BufferRole {
/**
* The index of the IPreparedModel within the "preparedModel" argument passed in
* IDevice::allocate.
*/
uint32_t modelIndex;
/**
* The index of the input or output operand.
*/
uint32_t ioIndex;
/**
* A floating-point value within the range (0.0, 1.0]. Describes how likely the
* buffer is to be used in the specified role. This is provided as a hint to
* optimize the case when multiple roles prefer different buffer locations or data
* layouts.
*/
float frequency;
};
/**
* Inputs to be sent to and outputs to be retrieved from a prepared model.
*
* A Request serves two primary tasks:
* 1) Provides the input and output data to be used when executing the model.
* 2) Specifies any updates to the input operand metadata that were left
* unspecified at model preparation time.
*
* An output must not overlap with any other output, with an input, or
* with an operand of lifetime CONSTANT_REFERENCE.
*/
struct Request {
/**
* Input data and information to be used in the execution of a prepared
* model.
*
* The index of the input corresponds to the index in Model.inputIndexes.
* E.g., input[i] corresponds to Model.inputIndexes[i].
*/
vec<RequestArgument> inputs;
/**
* Output data and information to be used in the execution of a prepared
* model.
*
* The index of the output corresponds to the index in Model.outputIndexes.
* E.g., output[i] corresponds to Model.outputIndexes[i].
*/
vec<RequestArgument> outputs;
/**
* A memory pool.
*/
safe_union MemoryPool {
/**
* Specifies a client-managed shared memory pool.
*/
memory hidlMemory;
/**
* Specifies a driver-managed buffer. It is the token returned from IDevice::allocate,
* and is specific to the IDevice object.
*/
int32_t token;
};
/**
* A collection of memory pools containing operand data for both the
* inputs and the outputs to a model.
*/
vec<MemoryPool> pools;
};

View file

@ -21,6 +21,7 @@ package android.hardware.neuralnetworks@1.3;
import @1.0::DataLocation;
import @1.0::OperandLifeTime;
import @1.0::PerformanceInfo;
import @1.0::RequestArgument;
import @1.2::OperandType;
import @1.2::OperationType;
import @1.2::SymmPerChannelQuantParams;
@ -389,3 +390,92 @@ struct Model {
LOW_BITS_TYPE = 16,
};
};
/**
* A buffer descriptor. Describes the properties of a buffer.
*/
struct BufferDesc {
/**
* Dimensions of the buffer. May have unknown dimensions or rank. A buffer with some number
* of unspecified dimensions is represented by setting each unspecified dimension to 0. A
* buffer with unspecified rank is represented by providing an empty dimensions vector.
*/
vec<uint32_t> dimensions;
};
/**
* Describes a role of an input or output to a prepared model.
*/
struct BufferRole {
/**
* The index of the IPreparedModel within the "preparedModel" argument passed in
* IDevice::allocate.
*/
uint32_t modelIndex;
/**
* The index of the input or output operand.
*/
uint32_t ioIndex;
/**
* A floating-point value within the range (0.0, 1.0]. Describes how likely the
* buffer is to be used in the specified role. This is provided as a hint to
* optimize the case when multiple roles prefer different buffer locations or data
* layouts.
*/
float frequency;
};
/**
* Inputs to be sent to and outputs to be retrieved from a prepared model.
*
* A Request serves two primary tasks:
* 1) Provides the input and output data to be used when executing the model.
* 2) Specifies any updates to the input operand metadata that were left
* unspecified at model preparation time.
*
* An output must not overlap with any other output, with an input, or
* with an operand of lifetime CONSTANT_REFERENCE.
*/
struct Request {
/**
* Input data and information to be used in the execution of a prepared
* model.
*
* The index of the input corresponds to the index in Model.inputIndexes.
* E.g., input[i] corresponds to Model.inputIndexes[i].
*/
vec<RequestArgument> inputs;
/**
* Output data and information to be used in the execution of a prepared
* model.
*
* The index of the output corresponds to the index in Model.outputIndexes.
* E.g., output[i] corresponds to Model.outputIndexes[i].
*/
vec<RequestArgument> outputs;
/**
* A memory pool.
*/
safe_union MemoryPool {
/**
* Specifies a client-managed shared memory pool.
*/
memory hidlMemory;
/**
* Specifies a driver-managed buffer. It is the token returned from IDevice::allocate,
* and is specific to the IDevice object.
*/
int32_t token;
};
/**
* A collection of memory pools containing operand data for both the
* inputs and the outputs to a model.
*/
vec<MemoryPool> pools;
};

View file

@ -60,7 +60,6 @@ using implementation::PreparedModelCallback;
using V1_0::DataLocation;
using V1_0::ErrorStatus;
using V1_0::OperandLifeTime;
using V1_0::Request;
using V1_1::ExecutionPreference;
using V1_2::Constant;
using V1_2::MeasureTiming;
@ -192,7 +191,7 @@ static bool isOutputSizeGreaterThanOne(const TestModel& testModel, uint32_t inde
return byteSize > 1u;
}
static void makeOutputInsufficientSize(uint32_t outputIndex, Request* request) {
static void makeOutputInsufficientSize(uint32_t outputIndex, V1_0::Request* request) {
auto& length = request->outputs[outputIndex].location.length;
ASSERT_GT(length, 1u);
length -= 1u;
@ -245,10 +244,11 @@ void EvaluatePreparedModel(const sp<IPreparedModel>& preparedModel, const TestMo
return;
}
Request request = createRequest(testModel);
V1_0::Request request10 = createRequest(testModel);
if (testConfig.outputType == OutputType::INSUFFICIENT) {
makeOutputInsufficientSize(/*outputIndex=*/0, &request);
makeOutputInsufficientSize(/*outputIndex=*/0, &request10);
}
Request request = nn::convertToV1_3(request10);
ErrorStatus executionStatus;
hidl_vec<OutputShape> outputShapes;
@ -284,6 +284,8 @@ void EvaluatePreparedModel(const sp<IPreparedModel>& preparedModel, const TestMo
break;
}
case Executor::BURST: {
// TODO(butlermichael): Check if we need to test burst in V1_3 if the interface remains
// V1_2.
SCOPED_TRACE("burst");
// create burst
@ -292,15 +294,15 @@ void EvaluatePreparedModel(const sp<IPreparedModel>& preparedModel, const TestMo
ASSERT_NE(nullptr, controller.get());
// create memory keys
std::vector<intptr_t> keys(request.pools.size());
std::vector<intptr_t> keys(request10.pools.size());
for (size_t i = 0; i < keys.size(); ++i) {
keys[i] = reinterpret_cast<intptr_t>(&request.pools[i]);
keys[i] = reinterpret_cast<intptr_t>(&request10.pools[i]);
}
// execute burst
int n;
std::tie(n, outputShapes, timing, std::ignore) =
controller->compute(request, testConfig.measureTiming, keys);
controller->compute(request10, testConfig.measureTiming, keys);
executionStatus = nn::convertResultCodeToErrorStatus(n);
break;
@ -361,7 +363,7 @@ void EvaluatePreparedModel(const sp<IPreparedModel>& preparedModel, const TestMo
}
// Retrieve execution results.
const std::vector<TestBuffer> outputs = getOutputBuffers(request);
const std::vector<TestBuffer> outputs = getOutputBuffers(request10);
// We want "close-enough" results.
checkResults(testModel, outputs);

View file

@ -28,7 +28,6 @@
namespace android::hardware::neuralnetworks::V1_3::vts::functional {
using V1_0::ErrorStatus;
using V1_0::Request;
using V1_2::MeasureTiming;
using V1_2::OutputShape;
using V1_2::Timing;
@ -93,9 +92,13 @@ static void validate(const sp<IPreparedModel>& preparedModel, const std::string&
}
// burst
// TODO(butlermichael): Check if we need to test burst in V1_3 if the interface remains V1_2.
{
SCOPED_TRACE(message + " [burst]");
ASSERT_TRUE(nn::compliantWithV1_0(request));
V1_0::Request request10 = nn::convertToV1_0(request);
// create burst
std::shared_ptr<::android::nn::ExecutionBurstController> burst =
android::nn::ExecutionBurstController::create(preparedModel,
@ -103,13 +106,13 @@ static void validate(const sp<IPreparedModel>& preparedModel, const std::string&
ASSERT_NE(nullptr, burst.get());
// create memory keys
std::vector<intptr_t> keys(request.pools.size());
std::vector<intptr_t> keys(request10.pools.size());
for (size_t i = 0; i < keys.size(); ++i) {
keys[i] = reinterpret_cast<intptr_t>(&request.pools[i]);
keys[i] = reinterpret_cast<intptr_t>(&request10.pools[i]);
}
// execute and verify
const auto [n, outputShapes, timing, fallback] = burst->compute(request, measure, keys);
const auto [n, outputShapes, timing, fallback] = burst->compute(request10, measure, keys);
const ErrorStatus status = nn::convertResultCodeToErrorStatus(n);
EXPECT_EQ(ErrorStatus::INVALID_ARGUMENT, status);
EXPECT_EQ(outputShapes.size(), 0);
@ -117,7 +120,7 @@ static void validate(const sp<IPreparedModel>& preparedModel, const std::string&
EXPECT_FALSE(fallback);
// additional burst testing
if (request.pools.size() > 0) {
if (request10.pools.size() > 0) {
// valid free
burst->freeMemory(keys.front());

View file

@ -25,6 +25,7 @@
#include "1.3/Callbacks.h"
#include "GeneratedTestHarness.h"
#include "TestHarness.h"
#include "Utils.h"
namespace android::hardware::neuralnetworks::V1_3::vts::functional {
@ -32,7 +33,6 @@ using HidlToken =
hidl_array<uint8_t, static_cast<uint32_t>(V1_2::Constant::BYTE_SIZE_OF_CACHE_TOKEN)>;
using implementation::PreparedModelCallback;
using V1_0::ErrorStatus;
using V1_0::Request;
using V1_1::ExecutionPreference;
// internal helper function
@ -124,9 +124,9 @@ INSTANTIATE_DEVICE_TEST(NeuralnetworksHidlTest);
// Forward declaration from ValidateModel.cpp
void validateModel(const sp<IDevice>& device, const Model& model);
// Forward declaration from ValidateRequest.cpp
void validateRequest(const sp<IPreparedModel>& preparedModel, const V1_0::Request& request);
void validateRequest(const sp<IPreparedModel>& preparedModel, const Request& request);
// Forward declaration from ValidateRequest.cpp
void validateRequestFailure(const sp<IPreparedModel>& preparedModel, const V1_0::Request& request);
void validateRequestFailure(const sp<IPreparedModel>& preparedModel, const Request& request);
// Forward declaration from ValidateBurst.cpp
void validateBurst(const sp<IPreparedModel>& preparedModel, const V1_0::Request& request);
@ -139,7 +139,11 @@ void validateEverything(const sp<IDevice>& device, const Model& model, const Req
if (preparedModel == nullptr) return;
validateRequest(preparedModel, request);
validateBurst(preparedModel, request);
// TODO(butlermichael): Check if we need to test burst in V1_3 if the interface remains V1_2.
ASSERT_TRUE(nn::compliantWithV1_0(request));
V1_0::Request request10 = nn::convertToV1_0(request);
validateBurst(preparedModel, request10);
}
void validateFailure(const sp<IDevice>& device, const Model& model, const Request& request) {
@ -157,7 +161,7 @@ void validateFailure(const sp<IDevice>& device, const Model& model, const Reques
TEST_P(ValidationTest, Test) {
const Model model = createModel(kTestModel);
const Request request = createRequest(kTestModel);
const Request request = nn::convertToV1_3(createRequest(kTestModel));
if (kTestModel.expectFailure) {
validateFailure(kDevice, model, request);
} else {