diff --git a/current.txt b/current.txt index 89a0cbc390..523f408c64 100644 --- a/current.txt +++ b/current.txt @@ -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 diff --git a/neuralnetworks/1.3/Android.bp b/neuralnetworks/1.3/Android.bp index 0b07a5806a..08e824d6e6 100644 --- a/neuralnetworks/1.3/Android.bp +++ b/neuralnetworks/1.3/Android.bp @@ -8,6 +8,7 @@ hidl_interface { }, srcs: [ "types.hal", + "IBuffer.hal", "IDevice.hal", "IPreparedModel.hal", "IPreparedModelCallback.hal", diff --git a/neuralnetworks/1.3/IBuffer.hal b/neuralnetworks/1.3/IBuffer.hal new file mode 100644 index 0000000000..84241c579b --- /dev/null +++ b/neuralnetworks/1.3/IBuffer.hal @@ -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 dimensions) generates (ErrorStatus status); +}; diff --git a/neuralnetworks/1.3/IDevice.hal b/neuralnetworks/1.3/IDevice.hal index 1295d6ac23..9afd77830d 100644 --- a/neuralnetworks/1.3/IDevice.hal +++ b/neuralnetworks/1.3/IDevice.hal @@ -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 preparedModels, vec inputRoles, + vec outputRoles) + generates (ErrorStatus status, IBuffer buffer, int32_t token); }; diff --git a/neuralnetworks/1.3/IPreparedModel.hal b/neuralnetworks/1.3/IPreparedModel.hal index 7aea4160b0..00adc1f950 100644 --- a/neuralnetworks/1.3/IPreparedModel.hal +++ b/neuralnetworks/1.3/IPreparedModel.hal @@ -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 diff --git a/neuralnetworks/1.3/types.hal b/neuralnetworks/1.3/types.hal index 62c5833500..6c8fe43312 100644 --- a/neuralnetworks/1.3/types.hal +++ b/neuralnetworks/1.3/types.hal @@ -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 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 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 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 pools; +}; diff --git a/neuralnetworks/1.3/types.t b/neuralnetworks/1.3/types.t index 0d20d06f7d..b1c72a9a31 100644 --- a/neuralnetworks/1.3/types.t +++ b/neuralnetworks/1.3/types.t @@ -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 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 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 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 pools; +}; diff --git a/neuralnetworks/1.3/vts/functional/GeneratedTestHarness.cpp b/neuralnetworks/1.3/vts/functional/GeneratedTestHarness.cpp index eced063416..09ccc9a719 100644 --- a/neuralnetworks/1.3/vts/functional/GeneratedTestHarness.cpp +++ b/neuralnetworks/1.3/vts/functional/GeneratedTestHarness.cpp @@ -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& 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 outputShapes; @@ -284,6 +284,8 @@ void EvaluatePreparedModel(const sp& 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& preparedModel, const TestMo ASSERT_NE(nullptr, controller.get()); // create memory keys - std::vector keys(request.pools.size()); + std::vector keys(request10.pools.size()); for (size_t i = 0; i < keys.size(); ++i) { - keys[i] = reinterpret_cast(&request.pools[i]); + keys[i] = reinterpret_cast(&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& preparedModel, const TestMo } // Retrieve execution results. - const std::vector outputs = getOutputBuffers(request); + const std::vector outputs = getOutputBuffers(request10); // We want "close-enough" results. checkResults(testModel, outputs); diff --git a/neuralnetworks/1.3/vts/functional/ValidateRequest.cpp b/neuralnetworks/1.3/vts/functional/ValidateRequest.cpp index 8092d04bcb..96dc589d50 100644 --- a/neuralnetworks/1.3/vts/functional/ValidateRequest.cpp +++ b/neuralnetworks/1.3/vts/functional/ValidateRequest.cpp @@ -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& 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& preparedModel, const std::string& ASSERT_NE(nullptr, burst.get()); // create memory keys - std::vector keys(request.pools.size()); + std::vector keys(request10.pools.size()); for (size_t i = 0; i < keys.size(); ++i) { - keys[i] = reinterpret_cast(&request.pools[i]); + keys[i] = reinterpret_cast(&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& 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()); diff --git a/neuralnetworks/1.3/vts/functional/VtsHalNeuralnetworks.cpp b/neuralnetworks/1.3/vts/functional/VtsHalNeuralnetworks.cpp index 92d8fa7376..1140b68635 100644 --- a/neuralnetworks/1.3/vts/functional/VtsHalNeuralnetworks.cpp +++ b/neuralnetworks/1.3/vts/functional/VtsHalNeuralnetworks.cpp @@ -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(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& device, const Model& model); // Forward declaration from ValidateRequest.cpp -void validateRequest(const sp& preparedModel, const V1_0::Request& request); +void validateRequest(const sp& preparedModel, const Request& request); // Forward declaration from ValidateRequest.cpp -void validateRequestFailure(const sp& preparedModel, const V1_0::Request& request); +void validateRequestFailure(const sp& preparedModel, const Request& request); // Forward declaration from ValidateBurst.cpp void validateBurst(const sp& preparedModel, const V1_0::Request& request); @@ -139,7 +139,11 @@ void validateEverything(const sp& 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& device, const Model& model, const Request& request) { @@ -157,7 +161,7 @@ void validateFailure(const sp& 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 {