1 /* 2 * Copyright (C) 2014 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 #ifndef ART_LIBNATIVEBRIDGE_INCLUDE_NATIVEBRIDGE_NATIVE_BRIDGE_H_ 18 #define ART_LIBNATIVEBRIDGE_INCLUDE_NATIVEBRIDGE_NATIVE_BRIDGE_H_ 19 20 #include <signal.h> 21 #include <stdbool.h> 22 #include <stdint.h> 23 #include <sys/types.h> 24 25 #include "jni.h" 26 27 #ifdef __cplusplus 28 namespace android { 29 extern "C" { 30 #endif // __cplusplus 31 32 // Loads a shared library from the system linker namespace, suitable for 33 // platform libraries in /system/lib(64). If linker namespaces don't exist (i.e. 34 // on host), this simply calls dlopen(). 35 void* OpenSystemLibrary(const char* path, int flags); 36 37 struct NativeBridgeRuntimeCallbacks; 38 struct NativeBridgeRuntimeValues; 39 40 // Function pointer type for sigaction. This is mostly the signature of a signal handler, except 41 // for the return type. The runtime needs to know whether the signal was handled or should be given 42 // to the chain. 43 typedef bool (*NativeBridgeSignalHandlerFn)(int, siginfo_t*, void*); 44 45 // Open the native bridge, if any. Should be called by Runtime::Init(). A null library filename 46 // signals that we do not want to load a native bridge. 47 bool LoadNativeBridge(const char* native_bridge_library_filename, 48 const struct NativeBridgeRuntimeCallbacks* runtime_callbacks); 49 50 // Quick check whether a native bridge will be needed. This is based off of the instruction set 51 // of the process. 52 bool NeedsNativeBridge(const char* instruction_set); 53 54 // Do the early initialization part of the native bridge, if necessary. This should be done under 55 // high privileges. 56 bool PreInitializeNativeBridge(const char* app_data_dir, const char* instruction_set); 57 58 // Prepare to fork from zygote. May be required to clean-up the enviroment, e.g. 59 // close emulated file descriptors, after doPreload() in app-zygote. 60 void PreZygoteForkNativeBridge(); 61 62 // Initialize the native bridge, if any. Should be called by Runtime::DidForkFromZygote. The JNIEnv* 63 // will be used to modify the app environment for the bridge. 64 bool InitializeNativeBridge(JNIEnv* env, const char* instruction_set); 65 66 // Unload the native bridge, if any. Should be called by Runtime::DidForkFromZygote. 67 void UnloadNativeBridge(); 68 69 // Check whether a native bridge is available (opened or initialized). Requires a prior call to 70 // LoadNativeBridge. 71 bool NativeBridgeAvailable(); 72 73 // Check whether a native bridge is available (initialized). Requires a prior call to 74 // LoadNativeBridge & InitializeNativeBridge. 75 bool NativeBridgeInitialized(); 76 77 // Load a shared library that is supported by the native bridge. 78 // 79 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 80 // Use NativeBridgeLoadLibraryExt() instead in namespace scenario. 81 void* NativeBridgeLoadLibrary(const char* libpath, int flag); 82 83 // Get a native bridge trampoline for specified native method. 84 void* NativeBridgeGetTrampoline(void* handle, const char* name, const char* shorty, uint32_t len); 85 86 // True if native library paths are valid and is for an ABI that is supported by native bridge. 87 // The *libpath* must point to a library. 88 // 89 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 90 // Use NativeBridgeIsPathSupported() instead in namespace scenario. 91 bool NativeBridgeIsSupported(const char* libpath); 92 93 // Returns the version number of the native bridge. This information is available after a 94 // successful LoadNativeBridge() and before closing it, that is, as long as NativeBridgeAvailable() 95 // returns true. Returns 0 otherwise. 96 uint32_t NativeBridgeGetVersion(); 97 98 // Returns a signal handler that the bridge would like to be managed. Only valid for a native 99 // bridge supporting the version 2 interface. Will return null if the bridge does not support 100 // version 2, or if it doesn't have a signal handler it wants to be known. 101 NativeBridgeSignalHandlerFn NativeBridgeGetSignalHandler(int signal); 102 103 // Returns whether we have seen a native bridge error. This could happen because the library 104 // was not found, rejected, could not be initialized and so on. 105 // 106 // This functionality is mainly for testing. 107 bool NativeBridgeError(); 108 109 // Returns whether a given string is acceptable as a native bridge library filename. 110 // 111 // This functionality is exposed mainly for testing. 112 bool NativeBridgeNameAcceptable(const char* native_bridge_library_filename); 113 114 // Decrements the reference count on the dynamic library handler. If the reference count drops 115 // to zero then the dynamic library is unloaded. Returns 0 on success and non-zero on error. 116 int NativeBridgeUnloadLibrary(void* handle); 117 118 // Get last error message of native bridge when fail to load library or search symbol. 119 // This is reflection of dlerror() for native bridge. 120 const char* NativeBridgeGetError(); 121 122 struct native_bridge_namespace_t; 123 124 // True if native library paths are valid and is for an ABI that is supported by native bridge. 125 // Different from NativeBridgeIsSupported(), the *path* here must be a directory containing 126 // libraries of an ABI. 127 // 128 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 129 // Use NativeBridgeIsSupported() instead in non-namespace scenario. 130 bool NativeBridgeIsPathSupported(const char* path); 131 132 // Initializes anonymous namespace. 133 // NativeBridge's peer of android_init_anonymous_namespace() of dynamic linker. 134 // 135 // The anonymous namespace is used in the case when a NativeBridge implementation 136 // cannot identify the caller of dlopen/dlsym which happens for the code not loaded 137 // by dynamic linker; for example calls from the mono-compiled code. 138 // 139 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 140 // Should not use in non-namespace scenario. 141 bool NativeBridgeInitAnonymousNamespace(const char* public_ns_sonames, 142 const char* anon_ns_library_path); 143 144 // Create new namespace in which native libraries will be loaded. 145 // NativeBridge's peer of android_create_namespace() of dynamic linker. 146 // 147 // The libraries in the namespace are searched by folowing order: 148 // 1. ld_library_path (Think of this as namespace-local LD_LIBRARY_PATH) 149 // 2. In directories specified by DT_RUNPATH of the "needed by" binary. 150 // 3. deault_library_path (This of this as namespace-local default library path) 151 // 152 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 153 // Should not use in non-namespace scenario. 154 struct native_bridge_namespace_t* NativeBridgeCreateNamespace( 155 const char* name, const char* ld_library_path, const char* default_library_path, uint64_t type, 156 const char* permitted_when_isolated_path, struct native_bridge_namespace_t* parent_ns); 157 158 // Creates a link which shares some libraries from one namespace to another. 159 // NativeBridge's peer of android_link_namespaces() of dynamic linker. 160 // 161 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 162 // Should not use in non-namespace scenario. 163 bool NativeBridgeLinkNamespaces(struct native_bridge_namespace_t* from, 164 struct native_bridge_namespace_t* to, 165 const char* shared_libs_sonames); 166 167 // Load a shared library with namespace key that is supported by the native bridge. 168 // NativeBridge's peer of android_dlopen_ext() of dynamic linker, only supports namespace 169 // extension. 170 // 171 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 172 // Use NativeBridgeLoadLibrary() instead in non-namespace scenario. 173 void* NativeBridgeLoadLibraryExt(const char* libpath, int flag, 174 struct native_bridge_namespace_t* ns); 175 176 // Returns exported namespace by the name. This is a reflection of 177 // android_get_exported_namespace function. Introduced in v5. 178 struct native_bridge_namespace_t* NativeBridgeGetExportedNamespace(const char* name); 179 180 // Native bridge interfaces to runtime. 181 struct NativeBridgeCallbacks { 182 // Version number of the interface. 183 uint32_t version; 184 185 // Initialize native bridge. Native bridge's internal implementation must ensure MT safety and 186 // that the native bridge is initialized only once. Thus it is OK to call this interface for an 187 // already initialized native bridge. 188 // 189 // Parameters: 190 // runtime_cbs [IN] the pointer to NativeBridgeRuntimeCallbacks. 191 // Returns: 192 // true if initialization was successful. 193 bool (*initialize)(const struct NativeBridgeRuntimeCallbacks* runtime_cbs, 194 const char* private_dir, const char* instruction_set); 195 196 // Load a shared library that is supported by the native bridge. 197 // 198 // Parameters: 199 // libpath [IN] path to the shared library 200 // flag [IN] the stardard RTLD_XXX defined in bionic dlfcn.h 201 // Returns: 202 // The opaque handle of the shared library if sucessful, otherwise NULL 203 // 204 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 205 // Use loadLibraryExt instead in namespace scenario. 206 void* (*loadLibrary)(const char* libpath, int flag); 207 208 // Get a native bridge trampoline for specified native method. The trampoline has same 209 // sigature as the native method. 210 // 211 // Parameters: 212 // handle [IN] the handle returned from loadLibrary 213 // shorty [IN] short descriptor of native method 214 // len [IN] length of shorty 215 // Returns: 216 // address of trampoline if successful, otherwise NULL 217 void* (*getTrampoline)(void* handle, const char* name, const char* shorty, uint32_t len); 218 219 // Check whether native library is valid and is for an ABI that is supported by native bridge. 220 // 221 // Parameters: 222 // libpath [IN] path to the shared library 223 // Returns: 224 // TRUE if library is supported by native bridge, FALSE otherwise 225 // 226 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 227 // Use isPathSupported instead in namespace scenario. 228 bool (*isSupported)(const char* libpath); 229 230 // Provide environment values required by the app running with native bridge according to the 231 // instruction set. 232 // 233 // Parameters: 234 // instruction_set [IN] the instruction set of the app 235 // Returns: 236 // NULL if not supported by native bridge. 237 // Otherwise, return all environment values to be set after fork. 238 const struct NativeBridgeRuntimeValues* (*getAppEnv)(const char* instruction_set); 239 240 // Added callbacks in version 2. 241 242 // Check whether the bridge is compatible with the given version. A bridge may decide not to be 243 // forwards- or backwards-compatible, and libnativebridge will then stop using it. 244 // 245 // Parameters: 246 // bridge_version [IN] the version of libnativebridge. 247 // Returns: 248 // true if the native bridge supports the given version of libnativebridge. 249 bool (*isCompatibleWith)(uint32_t bridge_version); 250 251 // A callback to retrieve a native bridge's signal handler for the specified signal. The runtime 252 // will ensure that the signal handler is being called after the runtime's own handler, but before 253 // all chained handlers. The native bridge should not try to install the handler by itself, as 254 // that will potentially lead to cycles. 255 // 256 // Parameters: 257 // signal [IN] the signal for which the handler is asked for. Currently, only SIGSEGV is 258 // supported by the runtime. 259 // Returns: 260 // NULL if the native bridge doesn't use a handler or doesn't want it to be managed by the 261 // runtime. 262 // Otherwise, a pointer to the signal handler. 263 NativeBridgeSignalHandlerFn (*getSignalHandler)(int signal); 264 265 // Added callbacks in version 3. 266 267 // Decrements the reference count on the dynamic library handler. If the reference count drops 268 // to zero then the dynamic library is unloaded. 269 // 270 // Parameters: 271 // handle [IN] the handler of a dynamic library. 272 // 273 // Returns: 274 // 0 on success, and nonzero on error. 275 int (*unloadLibrary)(void* handle); 276 277 // Dump the last failure message of native bridge when fail to load library or search symbol. 278 // 279 // Parameters: 280 // 281 // Returns: 282 // A string describing the most recent error that occurred when load library 283 // or lookup symbol via native bridge. 284 const char* (*getError)(); 285 286 // Check whether library paths are supported by native bridge. 287 // 288 // Parameters: 289 // library_path [IN] search paths for native libraries (directories separated by ':') 290 // Returns: 291 // TRUE if libraries within search paths are supported by native bridge, FALSE otherwise 292 // 293 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 294 // Use isSupported instead in non-namespace scenario. 295 bool (*isPathSupported)(const char* library_path); 296 297 // Initializes anonymous namespace at native bridge side. 298 // NativeBridge's peer of android_init_anonymous_namespace() of dynamic linker. 299 // 300 // The anonymous namespace is used in the case when a NativeBridge implementation 301 // cannot identify the caller of dlopen/dlsym which happens for the code not loaded 302 // by dynamic linker; for example calls from the mono-compiled code. 303 // 304 // Parameters: 305 // public_ns_sonames [IN] the name of "public" libraries. 306 // anon_ns_library_path [IN] the library search path of (anonymous) namespace. 307 // Returns: 308 // true if the pass is ok. 309 // Otherwise, false. 310 // 311 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 312 // Should not use in non-namespace scenario. 313 bool (*initAnonymousNamespace)(const char* public_ns_sonames, const char* anon_ns_library_path); 314 315 // Create new namespace in which native libraries will be loaded. 316 // NativeBridge's peer of android_create_namespace() of dynamic linker. 317 // 318 // Parameters: 319 // name [IN] the name of the namespace. 320 // ld_library_path [IN] the first set of library search paths of the namespace. 321 // default_library_path [IN] the second set of library search path of the namespace. 322 // type [IN] the attribute of the namespace. 323 // permitted_when_isolated_path [IN] the permitted path for isolated namespace(if it is). 324 // parent_ns [IN] the pointer of the parent namespace to be inherited from. 325 // Returns: 326 // native_bridge_namespace_t* for created namespace or nullptr in the case of error. 327 // 328 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 329 // Should not use in non-namespace scenario. 330 struct native_bridge_namespace_t* (*createNamespace)(const char* name, 331 const char* ld_library_path, 332 const char* default_library_path, 333 uint64_t type, 334 const char* permitted_when_isolated_path, 335 struct native_bridge_namespace_t* parent_ns); 336 337 // Creates a link which shares some libraries from one namespace to another. 338 // NativeBridge's peer of android_link_namespaces() of dynamic linker. 339 // 340 // Parameters: 341 // from [IN] the namespace where libraries are accessed. 342 // to [IN] the namespace where libraries are loaded. 343 // shared_libs_sonames [IN] the libraries to be shared. 344 // 345 // Returns: 346 // Whether successed or not. 347 // 348 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 349 // Should not use in non-namespace scenario. 350 bool (*linkNamespaces)(struct native_bridge_namespace_t* from, 351 struct native_bridge_namespace_t* to, const char* shared_libs_sonames); 352 353 // Load a shared library within a namespace. 354 // NativeBridge's peer of android_dlopen_ext() of dynamic linker, only supports namespace 355 // extension. 356 // 357 // Parameters: 358 // libpath [IN] path to the shared library 359 // flag [IN] the stardard RTLD_XXX defined in bionic dlfcn.h 360 // ns [IN] the pointer of the namespace in which the library should be loaded. 361 // Returns: 362 // The opaque handle of the shared library if sucessful, otherwise NULL 363 // 364 // Starting with v3, NativeBridge has two scenarios: with/without namespace. 365 // Use loadLibrary instead in non-namespace scenario. 366 void* (*loadLibraryExt)(const char* libpath, int flag, struct native_bridge_namespace_t* ns); 367 368 // Get native bridge version of vendor namespace. 369 // The vendor namespace is the namespace used to load vendor public libraries. 370 // With O release this namespace can be different from the default namespace. 371 // For the devices without enable vendor namespaces this function should return null 372 // 373 // Returns: 374 // vendor namespace or null if it was not set up for the device 375 // 376 // Starting with v5 (Android Q) this function is no longer used. 377 // Use getExportedNamespace() below. 378 struct native_bridge_namespace_t* (*getVendorNamespace)(); 379 380 // Get native bridge version of exported namespace. Peer of 381 // android_get_exported_namespace(const char*) function. 382 // 383 // Returns: 384 // exported namespace or null if it was not set up for the device 385 struct native_bridge_namespace_t* (*getExportedNamespace)(const char* name); 386 387 // If native bridge is used in app-zygote (in doPreload()) this callback is 388 // required to clean-up the environment before the fork (see b/146904103). 389 void (*preZygoteFork)(); 390 }; 391 392 // Runtime interfaces to native bridge. 393 struct NativeBridgeRuntimeCallbacks { 394 // Get shorty of a Java method. The shorty is supposed to be persistent in memory. 395 // 396 // Parameters: 397 // env [IN] pointer to JNIenv. 398 // mid [IN] Java methodID. 399 // Returns: 400 // short descriptor for method. 401 const char* (*getMethodShorty)(JNIEnv* env, jmethodID mid); 402 403 // Get number of native methods for specified class. 404 // 405 // Parameters: 406 // env [IN] pointer to JNIenv. 407 // clazz [IN] Java class object. 408 // Returns: 409 // number of native methods. 410 uint32_t (*getNativeMethodCount)(JNIEnv* env, jclass clazz); 411 412 // Get at most 'method_count' native methods for specified class 'clazz'. Results are outputed 413 // via 'methods' [OUT]. The signature pointer in JNINativeMethod is reused as the method shorty. 414 // 415 // Parameters: 416 // env [IN] pointer to JNIenv. 417 // clazz [IN] Java class object. 418 // methods [OUT] array of method with the name, shorty, and fnPtr. 419 // method_count [IN] max number of elements in methods. 420 // Returns: 421 // number of method it actually wrote to methods. 422 uint32_t (*getNativeMethods)(JNIEnv* env, jclass clazz, JNINativeMethod* methods, 423 uint32_t method_count); 424 }; 425 426 #ifdef __cplusplus 427 } // extern "C" 428 } // namespace android 429 #endif // __cplusplus 430 431 #endif // ART_LIBNATIVEBRIDGE_INCLUDE_NATIVEBRIDGE_NATIVE_BRIDGE_H_ 432