1 /* 2 * Copyright (C) 2021 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * @addtogroup NeuralNetworks 19 * @{ 20 */ 21 22 /** 23 * @file NeuralNetworksShim.h 24 */ 25 26 #pragma once 27 28 /****************************************************************** 29 * 30 * IMPORTANT NOTICE: 31 * 32 * This file is part of Android's set of stable system headers 33 * exposed by the Android NDK (Native Development Kit). 34 * 35 * Third-party source AND binary code relies on the definitions 36 * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. 37 * 38 * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) 39 * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS 40 * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY 41 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 42 */ 43 44 #include <stdbool.h> 45 #include <stddef.h> 46 #include <stdint.h> 47 #include <sys/cdefs.h> 48 49 #include "NeuralNetworksSupportLibraryImpl.h" 50 51 __BEGIN_DECLS 52 53 /** 54 * Result codes. 55 */ 56 typedef enum { 57 ANNSHIM_NO_ERROR = 0, 58 59 /** 60 * Failure caused by failure to load support library driver. 61 */ 62 ANNSHIM_FAILED_TO_LOAD_SL = 1, 63 64 /** 65 * Failure caused by failure to register HAL service. 66 */ 67 ANNSHIM_FAILED_TO_REGISTER_SERVICE = 2, 68 69 /** 70 * General failure. 71 */ 72 ANNSHIM_GENERAL_ERROR = 3, 73 74 /** 75 * Invalid argument 76 */ 77 ANNSHIM_INVALID_ARGUMENT = 4, 78 79 } ANeuralNetworksShimResultCode; 80 81 /** 82 * Supplementary information required to expose NNAPI HAL Service on top of 83 * a NNAPI SL Driver. 84 */ 85 typedef struct ANeuralNetworksShimDeviceInfo ANeuralNetworksShimDeviceInfo; 86 87 /** 88 * Additional parameters indicating how to devices should be registered. 89 */ 90 typedef struct ANeuralNetworksShimRegistrationParams ANeuralNetworksShimRegistrationParams; 91 92 /** 93 * Allocate ANeuralNetworksShimDeviceInfo struct with a device name. 94 * 95 * Available since API level 31. 96 * 97 * @param deviceInfo The {@link ANeuralNetworksShimDeviceInfo} to be created. 98 * Set to NULL if unsuccessful. 99 * @param deviceName has to match NNAPI Device name exposed by SL Driver. 100 * @param serviceName name of the AIDL service backed by this SL Driver device. 101 * If null, the deviceName will be used as the service name. 102 * @return {@link ANeuralNetworksShimResultCode} enum values. 103 * Returns ANNSHIM_NO_ERROR if successful. 104 */ 105 int ANeuralNetworksShimDeviceInfo_create( 106 ANeuralNetworksShimDeviceInfo* _Nullable* _Nonnull deviceInfo, 107 const char* _Nonnull deviceName, const char* _Nullable serviceName) __INTRODUCED_IN(31); 108 109 /** 110 * Free ANeuralNetworksShimDeviceInfo struct. 111 * 112 * Available since API level 31. 113 * 114 * @param deviceInfo The NNAPI shim device info to be destroyed. Passing NULL is acceptable and 115 * results in no operation. 116 */ 117 void ANeuralNetworksShimDeviceInfo_free(ANeuralNetworksShimDeviceInfo* _Nonnull deviceInfo) 118 __INTRODUCED_IN(31); 119 120 /** 121 * Allocate ANeuralNetworksShimRegistrationParams struct. 122 * 123 * Available since API level 31. 124 * 125 * @param nnapiSupportLibraryPackage Handle to a NNAPI SL implementation. 126 * @param outRegistrationParams The {@link ANeuralNetworksShimRegistrationParams} to be created. 127 * Set to NULL if unsuccessful. 128 * @return {@link ANeuralNetworksShimResultCode} enum values. 129 * Returns ANNSHIM_NO_ERROR if successful. 130 */ 131 int ANeuralNetworksShimRegistrationParams_create( 132 NnApiSLDriverImpl* _Nonnull nnapiSupportLibraryPackage, 133 ANeuralNetworksShimRegistrationParams* _Nullable* _Nonnull outRegistrationParams) 134 __INTRODUCED_IN(31); 135 136 /** 137 * Free ANeuralNetworksShimRegistrationParams struct. 138 * 139 * Available since API level 31. 140 * 141 * @param registrationParams The NNAPI shim registration parameters to be destroyed. Passing NULL is 142 * acceptable and results in no operation. 143 */ 144 void ANeuralNetworksShimRegistrationParams_free( 145 ANeuralNetworksShimRegistrationParams* _Nonnull registrationParams) __INTRODUCED_IN(31); 146 147 /** 148 * Add device info to the registration parameters. 149 * 150 * Available since API level 31. 151 * 152 * @param registrationParams The NNAPI shim registration parameter struct to be modified. 153 * @param devicesToRegister ANeuralNetworksShimDeviceInfo struct, with name and supplementary info 154 * about NNAPI device to register. 155 * @return {@link ANeuralNetworksShimResultCode} enum values. 156 * Returns ANNSHIM_NO_ERROR if successful. 157 */ 158 int ANeuralNetworksShimRegistrationParams_addDeviceInfo( 159 ANeuralNetworksShimRegistrationParams* _Nonnull registrationParams, 160 const ANeuralNetworksShimDeviceInfo* _Nonnull deviceInfo) __INTRODUCED_IN(31); 161 162 /** 163 * Set the number of listener threads for all registered services. 164 * 165 * By default, this value is 15, but this default may change in the future. The provided value must 166 * be non-zero. 167 * 168 * Available since API level 31. 169 * 170 * @param registrationParams The NNAPI shim registration parameter struct to be modified. 171 * @param numberOfListenerThreads Number of listener threads for the registered services. 172 * @return {@link ANeuralNetworksShimResultCode} enum values. 173 * Returns ANNSHIM_NO_ERROR if successful. 174 */ 175 int ANeuralNetworksShimRegistrationParams_setNumberOfListenerThreads( 176 ANeuralNetworksShimRegistrationParams* _Nonnull registrationParams, 177 uint32_t numberOfListenerThreads) __INTRODUCED_IN(31); 178 179 /** 180 * Set whether to register the service eagerly or lazily. 181 * 182 * By default, the service is eagerly registered. 183 * 184 * Available since API level 31. 185 * 186 * @param registrationParams The NNAPI shim registration parameter struct to be modified. 187 * @param asLazy 'false' if the services should be registered with 188 * {@link AServiceManager_addService}, 'true' if the services should be registered 189 * with {@link AServiceManager_registerLazyService}. 190 * @return {@link ANeuralNetworksShimResultCode} enum values. 191 * Returns ANNSHIM_NO_ERROR if successful. 192 */ 193 int ANeuralNetworksShimRegistrationParams_registerAsLazyService( 194 ANeuralNetworksShimRegistrationParams* _Nonnull registrationParams, bool asLazy) 195 __INTRODUCED_IN(31); 196 197 /** 198 * Specifies whether a minimum support device should be registered in the event a specified driver 199 * could not be registered from the NNAPI SL implementation. 200 * 201 * When called, {@link ANeuralNetworksShim_registerSupportLibraryService} will attempt to register 202 * all drivers specified by a {@link ANeuralNetworksShimDeviceInfo}. For some clients of this API 203 * (such as the legacy NNAPI vendor drivers), failing to register any driver should be considered 204 * an error, and {@link ANeuralNetworksShim_registerSupportLibraryService} should return with an 205 * error code. However, for other clients of this API (such as the NNAPI updatable vendor drivers), 206 * failing to register one driver should not prevent other drivers from being registered; instead, a 207 * driver with minimum support should instead be registered so that the devices registered with the 208 * Service Manager matches the service instances listed in the device manifest. 209 * 210 * By default, {@link ANeuralNetworksShim_registerSupportLibraryService} will immediately return 211 * with an error instead of registering a minimum support device. 212 * 213 * Available since API level 31. 214 * 215 * @param registrationParams The NNAPI shim registration parameter struct to be modified. 216 * @param fallback 'true' if a minimal device should be registered when the actual device is not 217 * able to be registered, 'false' if 218 * {@link ANeuralNetworksShim_registerSupportLibraryService} should instead 219 * immediately fail with an error. 220 * @return {@link ANeuralNetworksShimResultCode} enum values. 221 * Returns ANNSHIM_NO_ERROR if successful. 222 */ 223 int ANeuralNetworksShimRegistrationParams_fallbackToMinimumSupportDevice( 224 ANeuralNetworksShimRegistrationParams* _Nonnull registrationParams, bool fallback) 225 __INTRODUCED_IN(31); 226 227 /** 228 * Register NNAPI support library driver as HAL services. 229 * 230 * Takes a NNAPI SL implementation and registers each NNAPI Device it exposes as a 231 * separate HAL/AIDL service. 232 * 233 * If loading SL driver is successful, it blocks and never returns. If there's 234 * any problem with the support library driver, it returns on error. 235 * 236 * Available since API level 31. 237 * 238 * @param registrationParams Additional arguments for how the devices should be registered. 239 * @return {@link ANeuralNetworksShimResultCode} enum values. 240 * Blocks forever if successful. 241 */ 242 int ANeuralNetworksShim_registerSupportLibraryService( 243 const ANeuralNetworksShimRegistrationParams* _Nonnull registrationParams) 244 __INTRODUCED_IN(31); 245 246 __END_DECLS 247 248 /** @} */ 249