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 NATIVE_BRIDGE_H_ 18 #define NATIVE_BRIDGE_H_ 19 20 #include "jni.h" 21 #include <stdint.h> 22 #include <sys/types.h> 23 24 namespace android { 25 26 struct NativeBridgeRuntimeCallbacks; 27 struct NativeBridgeRuntimeValues; 28 29 // Open the native bridge, if any. Should be called by Runtime::Init(). A null library filename 30 // signals that we do not want to load a native bridge. 31 bool LoadNativeBridge(const char* native_bridge_library_filename, 32 const NativeBridgeRuntimeCallbacks* runtime_callbacks); 33 34 // Quick check whether a native bridge will be needed. This is based off of the instruction set 35 // of the process. 36 bool NeedsNativeBridge(const char* instruction_set); 37 38 // Do the early initialization part of the native bridge, if necessary. This should be done under 39 // high privileges. 40 bool PreInitializeNativeBridge(const char* app_data_dir, const char* instruction_set); 41 42 // Initialize the native bridge, if any. Should be called by Runtime::DidForkFromZygote. The JNIEnv* 43 // will be used to modify the app environment for the bridge. 44 bool InitializeNativeBridge(JNIEnv* env, const char* instruction_set); 45 46 // Unload the native bridge, if any. Should be called by Runtime::DidForkFromZygote. 47 void UnloadNativeBridge(); 48 49 // Check whether a native bridge is available (opened or initialized). Requires a prior call to 50 // LoadNativeBridge. 51 bool NativeBridgeAvailable(); 52 53 // Check whether a native bridge is available (initialized). Requires a prior call to 54 // LoadNativeBridge & InitializeNativeBridge. 55 bool NativeBridgeInitialized(); 56 57 // Load a shared library that is supported by the native bridge. 58 void* NativeBridgeLoadLibrary(const char* libpath, int flag); 59 60 // Get a native bridge trampoline for specified native method. 61 void* NativeBridgeGetTrampoline(void* handle, const char* name, const char* shorty, uint32_t len); 62 63 // True if native library is valid and is for an ABI that is supported by native bridge. 64 bool NativeBridgeIsSupported(const char* libpath); 65 66 // Returns whether we have seen a native bridge error. This could happen because the library 67 // was not found, rejected, could not be initialized and so on. 68 // 69 // This functionality is mainly for testing. 70 bool NativeBridgeError(); 71 72 // Returns whether a given string is acceptable as a native bridge library filename. 73 // 74 // This functionality is exposed mainly for testing. 75 bool NativeBridgeNameAcceptable(const char* native_bridge_library_filename); 76 77 // Native bridge interfaces to runtime. 78 struct NativeBridgeCallbacks { 79 // Version number of the interface. 80 uint32_t version; 81 82 // Initialize native bridge. Native bridge's internal implementation must ensure MT safety and 83 // that the native bridge is initialized only once. Thus it is OK to call this interface for an 84 // already initialized native bridge. 85 // 86 // Parameters: 87 // runtime_cbs [IN] the pointer to NativeBridgeRuntimeCallbacks. 88 // Returns: 89 // true iff initialization was successful. 90 bool (*initialize)(const NativeBridgeRuntimeCallbacks* runtime_cbs, const char* private_dir, 91 const char* instruction_set); 92 93 // Load a shared library that is supported by the native bridge. 94 // 95 // Parameters: 96 // libpath [IN] path to the shared library 97 // flag [IN] the stardard RTLD_XXX defined in bionic dlfcn.h 98 // Returns: 99 // The opaque handle of the shared library if sucessful, otherwise NULL 100 void* (*loadLibrary)(const char* libpath, int flag); 101 102 // Get a native bridge trampoline for specified native method. The trampoline has same 103 // sigature as the native method. 104 // 105 // Parameters: 106 // handle [IN] the handle returned from loadLibrary 107 // shorty [IN] short descriptor of native method 108 // len [IN] length of shorty 109 // Returns: 110 // address of trampoline if successful, otherwise NULL 111 void* (*getTrampoline)(void* handle, const char* name, const char* shorty, uint32_t len); 112 113 // Check whether native library is valid and is for an ABI that is supported by native bridge. 114 // 115 // Parameters: 116 // libpath [IN] path to the shared library 117 // Returns: 118 // TRUE if library is supported by native bridge, FALSE otherwise 119 bool (*isSupported)(const char* libpath); 120 121 // Provide environment values required by the app running with native bridge according to the 122 // instruction set. 123 // 124 // Parameters: 125 // instruction_set [IN] the instruction set of the app 126 // Returns: 127 // NULL if not supported by native bridge. 128 // Otherwise, return all environment values to be set after fork. 129 const struct NativeBridgeRuntimeValues* (*getAppEnv)(const char* instruction_set); 130 }; 131 132 // Runtime interfaces to native bridge. 133 struct NativeBridgeRuntimeCallbacks { 134 // Get shorty of a Java method. The shorty is supposed to be persistent in memory. 135 // 136 // Parameters: 137 // env [IN] pointer to JNIenv. 138 // mid [IN] Java methodID. 139 // Returns: 140 // short descriptor for method. 141 const char* (*getMethodShorty)(JNIEnv* env, jmethodID mid); 142 143 // Get number of native methods for specified class. 144 // 145 // Parameters: 146 // env [IN] pointer to JNIenv. 147 // clazz [IN] Java class object. 148 // Returns: 149 // number of native methods. 150 uint32_t (*getNativeMethodCount)(JNIEnv* env, jclass clazz); 151 152 // Get at most 'method_count' native methods for specified class 'clazz'. Results are outputed 153 // via 'methods' [OUT]. The signature pointer in JNINativeMethod is reused as the method shorty. 154 // 155 // Parameters: 156 // env [IN] pointer to JNIenv. 157 // clazz [IN] Java class object. 158 // methods [OUT] array of method with the name, shorty, and fnPtr. 159 // method_count [IN] max number of elements in methods. 160 // Returns: 161 // number of method it actually wrote to methods. 162 uint32_t (*getNativeMethods)(JNIEnv* env, jclass clazz, JNINativeMethod* methods, 163 uint32_t method_count); 164 }; 165 166 }; // namespace android 167 168 #endif // NATIVE_BRIDGE_H_ 169