1376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler/* 2376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * Copyright (C) 2017 The Android Open Source Project 3376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * 4376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * Licensed under the Apache License, Version 2.0 (the "License"); 5376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * you may not use this file except in compliance with the License. 6376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * You may obtain a copy of the License at 7376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * 8376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * http://www.apache.org/licenses/LICENSE-2.0 9376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * 10376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * Unless required by applicable law or agreed to in writing, software 11376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * distributed under the License is distributed on an "AS IS" BASIS, 12376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * See the License for the specific language governing permissions and 14376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler * limitations under the License. 15376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler */ 16376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler 17376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butlerpackage android.hardware.neuralnetworks@1.0; 18376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler 19cf22a57c1a05272d055b0deaa10094852dece797Michael Butlerimport IPreparedModelCallback; 20376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler 21c7821107652db4724b6c60d483824d72b8a6b663Michael Butler/** 22c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * This interface represents a device driver. 23c7821107652db4724b6c60d483824d72b8a6b663Michael Butler */ 24376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butlerinterface IDevice { 25c7821107652db4724b6c60d483824d72b8a6b663Michael Butler /** 26c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * Gets the capabilities of a driver. 27c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * 28926df1e1823e633090a2248be0f1ac66933750edMichael Butler * @return status Error status of the call, must be: 29926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - NONE if successful 30926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - DEVICE_UNAVAILABLE if driver is offline or busy 31926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - GENERAL_FAILURE if there is an unspecified error 32c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * @return capabilities Capabilities of the driver. 33c7821107652db4724b6c60d483824d72b8a6b663Michael Butler */ 3461ae6edbe635759cece1102749ec4cb6e6b7e485Michael Butler getCapabilities() generates (ErrorStatus status, Capabilities capabilities); 35376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler 36c7821107652db4724b6c60d483824d72b8a6b663Michael Butler /** 37c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * Gets the supported operations in a model. 38c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * 39541e24311de0561a27bcba7f197f9bd46be67359David Gross * getSupportedOperations indicates which operations of a model are fully 40cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * supported by the vendor driver. If an operation may not be supported for 41cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * any reason, getSupportedOperations must return false for that operation. 42c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * 43c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * @param model A model whose operations--and their corresponding 44c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * operands--are to be verified by the driver. 45926df1e1823e633090a2248be0f1ac66933750edMichael Butler * @return status Error status of the call, must be: 46926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - NONE if successful 47926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - DEVICE_UNAVAILABLE if driver is offline or busy 48926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - GENERAL_FAILURE if there is an unspecified error 49cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * - INVALID_ARGUMENT if provided model is invalid 50c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * @return supportedOperations A list of supported operations, where true 51c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * indicates the operation is supported and 52c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * false indicates the operation is not 53c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * supported. The index of "supported" 54c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * corresponds with the index of the operation 55c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * it is describing. 56c7821107652db4724b6c60d483824d72b8a6b663Michael Butler */ 5761ae6edbe635759cece1102749ec4cb6e6b7e485Michael Butler getSupportedOperations(Model model) 58926df1e1823e633090a2248be0f1ac66933750edMichael Butler generates (ErrorStatus status, vec<bool> supportedOperations); 59376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler 60c7821107652db4724b6c60d483824d72b8a6b663Michael Butler /** 61cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * Creates a prepared model for execution. 62c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * 63c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * prepareModel is used to make any necessary transformations or alternative 64cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * representations to a model for execution, possiblly including 65c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * transformations on the constant data, optimization on the model's graph, 66cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * or compilation into the device's native binary format. The model itself 67cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * is not changed. 68cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * 69cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * The model is prepared asynchronously with respect to the caller. The 70cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * prepareModel function must verify the inputs to the prepareModel function 71cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * are correct. If there is an error, prepareModel must immediately invoke 72cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * the callback with the appropriate ErrorStatus value and nullptr for the 73cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * IPreparedModel, then return with the same ErrorStatus. If the inputs to 74cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * the prepareModel function are valid and there is no error, prepareModel 75cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * must launch an asynchronous task to prepare the model in the background, 76cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * and immediately return from prepareModel with ErrorStatus::NONE. If the 77cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * asynchronous task fails to launch, prepareModel must immediately invoke 78cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * the callback with ErrorStatus::GENERAL_FAILURE and nullptr for the 79cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * IPreparedModel, then return with ErrorStatus::GENERAL_FAILURE. 80cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * 81cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * When the asynchronous task has finished preparing the model, it must 82cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * immediately invoke the callback function provided as an input to 83cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * prepareModel. If the model was prepared successfully, the callback object 84cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * must be invoked with an error status of ErrorStatus::NONE and the 85cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * produced IPreparedModel object. If an error occurred preparing the model, 86cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * the callback object must be invoked with the appropriate ErrorStatus 87cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * value and nullptr for the IPreparedModel. 88c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * 89c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * The only information that may be unknown to the model at this stage is 90cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * the shape of the tensors, which may only be known at execution time. As 91cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * such, some driver services may return partially prepared models, where 92cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * the prepared model can only be finished when it is paired with a set of 93cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * inputs to the model. Note that the same prepared model object can be 94cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * used with different shapes of inputs on different (possibly concurrent) 95cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * executions. 96cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * 97cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * Multiple threads can call prepareModel on the same model concurrently. 98c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * 99c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * @param model The model to be prepared for execution. 100cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * @param callback A callback object used to return the error status of 101cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * preparing the model for execution and the prepared model 102cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * if successful, nullptr otherwise. The callback object's 103cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * notify function must be called exactly once, even if the 104cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * model could not be prepared. 105cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * @return status Error status of launching a task which prepares the model 106cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * in the background; must be: 107926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - NONE if preparation task is successfully launched 108926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - DEVICE_UNAVAILABLE if driver is offline or busy 109926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - GENERAL_FAILURE if there is an unspecified error 110cf22a57c1a05272d055b0deaa10094852dece797Michael Butler * - INVALID_ARGUMENT if one of the input arguments is 111926df1e1823e633090a2248be0f1ac66933750edMichael Butler * invalid 112c7821107652db4724b6c60d483824d72b8a6b663Michael Butler */ 113cf22a57c1a05272d055b0deaa10094852dece797Michael Butler prepareModel(Model model, IPreparedModelCallback callback) 114cf22a57c1a05272d055b0deaa10094852dece797Michael Butler generates (ErrorStatus status); 115376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler 116c7821107652db4724b6c60d483824d72b8a6b663Michael Butler /** 117c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * Returns the current status of a driver. 118c7821107652db4724b6c60d483824d72b8a6b663Michael Butler * 119926df1e1823e633090a2248be0f1ac66933750edMichael Butler * @return status Status of the driver, one of: 120926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - DeviceStatus::AVAILABLE 121926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - DeviceStatus::BUSY 122926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - DeviceStatus::OFFLINE 123926df1e1823e633090a2248be0f1ac66933750edMichael Butler * - DeviceStatus::UNKNOWN 124c7821107652db4724b6c60d483824d72b8a6b663Michael Butler */ 12561ae6edbe635759cece1102749ec4cb6e6b7e485Michael Butler getStatus() generates (DeviceStatus status); 126376ec0c0fd4a3f6b661599f37a03d66cbde9caa7Michael Butler}; 127