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 <signal.h> 22 #include <stdint.h> 23 #include <sys/types.h> 24 25 namespace android { 26 27 struct NativeBridgeRuntimeCallbacks; 28 struct NativeBridgeRuntimeValues; 29 30 // Function pointer type for sigaction. This is mostly the signature of a signal handler, except 31 // for the return type. The runtime needs to know whether the signal was handled or should be given 32 // to the chain. 33 typedef bool (*NativeBridgeSignalHandlerFn)(int, siginfo_t*, void*); 34 35 36 // Open the native bridge, if any. Should be called by Runtime::Init(). A null library filename 37 // signals that we do not want to load a native bridge. 38 bool LoadNativeBridge(const char* native_bridge_library_filename, 39 const NativeBridgeRuntimeCallbacks* runtime_callbacks); 40 41 // Quick check whether a native bridge will be needed. This is based off of the instruction set 42 // of the process. 43 bool NeedsNativeBridge(const char* instruction_set); 44 45 // Do the early initialization part of the native bridge, if necessary. This should be done under 46 // high privileges. 47 bool PreInitializeNativeBridge(const char* app_data_dir, const char* instruction_set); 48 49 // Initialize the native bridge, if any. Should be called by Runtime::DidForkFromZygote. The JNIEnv* 50 // will be used to modify the app environment for the bridge. 51 bool InitializeNativeBridge(JNIEnv* env, const char* instruction_set); 52 53 // Unload the native bridge, if any. Should be called by Runtime::DidForkFromZygote. 54 void UnloadNativeBridge(); 55 56 // Check whether a native bridge is available (opened or initialized). Requires a prior call to 57 // LoadNativeBridge. 58 bool NativeBridgeAvailable(); 59 60 // Check whether a native bridge is available (initialized). Requires a prior call to 61 // LoadNativeBridge & InitializeNativeBridge. 62 bool NativeBridgeInitialized(); 63 64 // Load a shared library that is supported by the native bridge. 65 void* NativeBridgeLoadLibrary(const char* libpath, int flag); 66 67 // Get a native bridge trampoline for specified native method. 68 void* NativeBridgeGetTrampoline(void* handle, const char* name, const char* shorty, uint32_t len); 69 70 // True if native library is valid and is for an ABI that is supported by native bridge. 71 bool NativeBridgeIsSupported(const char* libpath); 72 73 // Returns the version number of the native bridge. This information is available after a 74 // successful LoadNativeBridge() and before closing it, that is, as long as NativeBridgeAvailable() 75 // returns true. Returns 0 otherwise. 76 uint32_t NativeBridgeGetVersion(); 77 78 // Returns a signal handler that the bridge would like to be managed. Only valid for a native 79 // bridge supporting the version 2 interface. Will return null if the bridge does not support 80 // version 2, or if it doesn't have a signal handler it wants to be known. 81 NativeBridgeSignalHandlerFn NativeBridgeGetSignalHandler(int signal); 82 83 // Returns whether we have seen a native bridge error. This could happen because the library 84 // was not found, rejected, could not be initialized and so on. 85 // 86 // This functionality is mainly for testing. 87 bool NativeBridgeError(); 88 89 // Returns whether a given string is acceptable as a native bridge library filename. 90 // 91 // This functionality is exposed mainly for testing. 92 bool NativeBridgeNameAcceptable(const char* native_bridge_library_filename); 93 94 // Native bridge interfaces to runtime. 95 struct NativeBridgeCallbacks { 96 // Version number of the interface. 97 uint32_t version; 98 99 // Initialize native bridge. Native bridge's internal implementation must ensure MT safety and 100 // that the native bridge is initialized only once. Thus it is OK to call this interface for an 101 // already initialized native bridge. 102 // 103 // Parameters: 104 // runtime_cbs [IN] the pointer to NativeBridgeRuntimeCallbacks. 105 // Returns: 106 // true iff initialization was successful. 107 bool (*initialize)(const NativeBridgeRuntimeCallbacks* runtime_cbs, const char* private_dir, 108 const char* instruction_set); 109 110 // Load a shared library that is supported by the native bridge. 111 // 112 // Parameters: 113 // libpath [IN] path to the shared library 114 // flag [IN] the stardard RTLD_XXX defined in bionic dlfcn.h 115 // Returns: 116 // The opaque handle of the shared library if sucessful, otherwise NULL 117 void* (*loadLibrary)(const char* libpath, int flag); 118 119 // Get a native bridge trampoline for specified native method. The trampoline has same 120 // sigature as the native method. 121 // 122 // Parameters: 123 // handle [IN] the handle returned from loadLibrary 124 // shorty [IN] short descriptor of native method 125 // len [IN] length of shorty 126 // Returns: 127 // address of trampoline if successful, otherwise NULL 128 void* (*getTrampoline)(void* handle, const char* name, const char* shorty, uint32_t len); 129 130 // Check whether native library is valid and is for an ABI that is supported by native bridge. 131 // 132 // Parameters: 133 // libpath [IN] path to the shared library 134 // Returns: 135 // TRUE if library is supported by native bridge, FALSE otherwise 136 bool (*isSupported)(const char* libpath); 137 138 // Provide environment values required by the app running with native bridge according to the 139 // instruction set. 140 // 141 // Parameters: 142 // instruction_set [IN] the instruction set of the app 143 // Returns: 144 // NULL if not supported by native bridge. 145 // Otherwise, return all environment values to be set after fork. 146 const struct NativeBridgeRuntimeValues* (*getAppEnv)(const char* instruction_set); 147 148 // Added callbacks in version 2. 149 150 // Check whether the bridge is compatible with the given version. A bridge may decide not to be 151 // forwards- or backwards-compatible, and libnativebridge will then stop using it. 152 // 153 // Parameters: 154 // bridge_version [IN] the version of libnativebridge. 155 // Returns: 156 // true iff the native bridge supports the given version of libnativebridge. 157 bool (*isCompatibleWith)(uint32_t bridge_version); 158 159 // A callback to retrieve a native bridge's signal handler for the specified signal. The runtime 160 // will ensure that the signal handler is being called after the runtime's own handler, but before 161 // all chained handlers. The native bridge should not try to install the handler by itself, as 162 // that will potentially lead to cycles. 163 // 164 // Parameters: 165 // signal [IN] the signal for which the handler is asked for. Currently, only SIGSEGV is 166 // supported by the runtime. 167 // Returns: 168 // NULL if the native bridge doesn't use a handler or doesn't want it to be managed by the 169 // runtime. 170 // Otherwise, a pointer to the signal handler. 171 NativeBridgeSignalHandlerFn (*getSignalHandler)(int signal); 172 }; 173 174 // Runtime interfaces to native bridge. 175 struct NativeBridgeRuntimeCallbacks { 176 // Get shorty of a Java method. The shorty is supposed to be persistent in memory. 177 // 178 // Parameters: 179 // env [IN] pointer to JNIenv. 180 // mid [IN] Java methodID. 181 // Returns: 182 // short descriptor for method. 183 const char* (*getMethodShorty)(JNIEnv* env, jmethodID mid); 184 185 // Get number of native methods for specified class. 186 // 187 // Parameters: 188 // env [IN] pointer to JNIenv. 189 // clazz [IN] Java class object. 190 // Returns: 191 // number of native methods. 192 uint32_t (*getNativeMethodCount)(JNIEnv* env, jclass clazz); 193 194 // Get at most 'method_count' native methods for specified class 'clazz'. Results are outputed 195 // via 'methods' [OUT]. The signature pointer in JNINativeMethod is reused as the method shorty. 196 // 197 // Parameters: 198 // env [IN] pointer to JNIenv. 199 // clazz [IN] Java class object. 200 // methods [OUT] array of method with the name, shorty, and fnPtr. 201 // method_count [IN] max number of elements in methods. 202 // Returns: 203 // number of method it actually wrote to methods. 204 uint32_t (*getNativeMethods)(JNIEnv* env, jclass clazz, JNINativeMethod* methods, 205 uint32_t method_count); 206 }; 207 208 }; // namespace android 209 210 #endif // NATIVE_BRIDGE_H_ 211
