diff options
Diffstat (limited to 'include')
-rw-r--r-- | include/nativebridge/native_bridge.h | 401 |
1 files changed, 0 insertions, 401 deletions
diff --git a/include/nativebridge/native_bridge.h b/include/nativebridge/native_bridge.h deleted file mode 100644 index 9bfc93523..000000000 --- a/include/nativebridge/native_bridge.h +++ /dev/null | |||
@@ -1,401 +0,0 @@ | |||
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 | // | ||
66 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
67 | // Use NativeBridgeLoadLibraryExt() instead in namespace scenario. | ||
68 | void* NativeBridgeLoadLibrary(const char* libpath, int flag); | ||
69 | |||
70 | // Get a native bridge trampoline for specified native method. | ||
71 | void* NativeBridgeGetTrampoline(void* handle, const char* name, const char* shorty, uint32_t len); | ||
72 | |||
73 | // True if native library paths are valid and is for an ABI that is supported by native bridge. | ||
74 | // The *libpath* must point to a library. | ||
75 | // | ||
76 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
77 | // Use NativeBridgeIsPathSupported() instead in namespace scenario. | ||
78 | bool NativeBridgeIsSupported(const char* libpath); | ||
79 | |||
80 | // Returns the version number of the native bridge. This information is available after a | ||
81 | // successful LoadNativeBridge() and before closing it, that is, as long as NativeBridgeAvailable() | ||
82 | // returns true. Returns 0 otherwise. | ||
83 | uint32_t NativeBridgeGetVersion(); | ||
84 | |||
85 | // Returns a signal handler that the bridge would like to be managed. Only valid for a native | ||
86 | // bridge supporting the version 2 interface. Will return null if the bridge does not support | ||
87 | // version 2, or if it doesn't have a signal handler it wants to be known. | ||
88 | NativeBridgeSignalHandlerFn NativeBridgeGetSignalHandler(int signal); | ||
89 | |||
90 | // Returns whether we have seen a native bridge error. This could happen because the library | ||
91 | // was not found, rejected, could not be initialized and so on. | ||
92 | // | ||
93 | // This functionality is mainly for testing. | ||
94 | bool NativeBridgeError(); | ||
95 | |||
96 | // Returns whether a given string is acceptable as a native bridge library filename. | ||
97 | // | ||
98 | // This functionality is exposed mainly for testing. | ||
99 | bool NativeBridgeNameAcceptable(const char* native_bridge_library_filename); | ||
100 | |||
101 | // Decrements the reference count on the dynamic library handler. If the reference count drops | ||
102 | // to zero then the dynamic library is unloaded. | ||
103 | int NativeBridgeUnloadLibrary(void* handle); | ||
104 | |||
105 | // Get last error message of native bridge when fail to load library or search symbol. | ||
106 | // This is reflection of dlerror() for native bridge. | ||
107 | const char* NativeBridgeGetError(); | ||
108 | |||
109 | struct native_bridge_namespace_t; | ||
110 | |||
111 | // True if native library paths are valid and is for an ABI that is supported by native bridge. | ||
112 | // Different from NativeBridgeIsSupported(), the *path* here must be a directory containing | ||
113 | // libraries of an ABI. | ||
114 | // | ||
115 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
116 | // Use NativeBridgeIsSupported() instead in non-namespace scenario. | ||
117 | bool NativeBridgeIsPathSupported(const char* path); | ||
118 | |||
119 | // Initializes anonymous namespace. | ||
120 | // NativeBridge's peer of android_init_anonymous_namespace() of dynamic linker. | ||
121 | // | ||
122 | // The anonymous namespace is used in the case when a NativeBridge implementation | ||
123 | // cannot identify the caller of dlopen/dlsym which happens for the code not loaded | ||
124 | // by dynamic linker; for example calls from the mono-compiled code. | ||
125 | // | ||
126 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
127 | // Should not use in non-namespace scenario. | ||
128 | bool NativeBridgeInitAnonymousNamespace(const char* public_ns_sonames, | ||
129 | const char* anon_ns_library_path); | ||
130 | |||
131 | // Create new namespace in which native libraries will be loaded. | ||
132 | // NativeBridge's peer of android_create_namespace() of dynamic linker. | ||
133 | // | ||
134 | // The libraries in the namespace are searched by folowing order: | ||
135 | // 1. ld_library_path (Think of this as namespace-local LD_LIBRARY_PATH) | ||
136 | // 2. In directories specified by DT_RUNPATH of the "needed by" binary. | ||
137 | // 3. deault_library_path (This of this as namespace-local default library path) | ||
138 | // | ||
139 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
140 | // Should not use in non-namespace scenario. | ||
141 | native_bridge_namespace_t* NativeBridgeCreateNamespace(const char* name, | ||
142 | const char* ld_library_path, | ||
143 | const char* default_library_path, | ||
144 | uint64_t type, | ||
145 | const char* permitted_when_isolated_path, | ||
146 | native_bridge_namespace_t* parent_ns); | ||
147 | |||
148 | // Creates a link which shares some libraries from one namespace to another. | ||
149 | // NativeBridge's peer of android_link_namespaces() of dynamic linker. | ||
150 | // | ||
151 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
152 | // Should not use in non-namespace scenario. | ||
153 | bool NativeBridgeLinkNamespaces(native_bridge_namespace_t* from, native_bridge_namespace_t* to, | ||
154 | const char* shared_libs_sonames); | ||
155 | |||
156 | // Load a shared library with namespace key that is supported by the native bridge. | ||
157 | // NativeBridge's peer of android_dlopen_ext() of dynamic linker, only supports namespace | ||
158 | // extension. | ||
159 | // | ||
160 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
161 | // Use NativeBridgeLoadLibrary() instead in non-namespace scenario. | ||
162 | void* NativeBridgeLoadLibraryExt(const char* libpath, int flag, native_bridge_namespace_t* ns); | ||
163 | |||
164 | // Returns vendor namespace if it is enabled for the device and null otherwise | ||
165 | native_bridge_namespace_t* NativeBridgeGetVendorNamespace(); | ||
166 | |||
167 | // Native bridge interfaces to runtime. | ||
168 | struct NativeBridgeCallbacks { | ||
169 | // Version number of the interface. | ||
170 | uint32_t version; | ||
171 | |||
172 | // Initialize native bridge. Native bridge's internal implementation must ensure MT safety and | ||
173 | // that the native bridge is initialized only once. Thus it is OK to call this interface for an | ||
174 | // already initialized native bridge. | ||
175 | // | ||
176 | // Parameters: | ||
177 | // runtime_cbs [IN] the pointer to NativeBridgeRuntimeCallbacks. | ||
178 | // Returns: | ||
179 | // true if initialization was successful. | ||
180 | bool (*initialize)(const NativeBridgeRuntimeCallbacks* runtime_cbs, const char* private_dir, | ||
181 | const char* instruction_set); | ||
182 | |||
183 | // Load a shared library that is supported by the native bridge. | ||
184 | // | ||
185 | // Parameters: | ||
186 | // libpath [IN] path to the shared library | ||
187 | // flag [IN] the stardard RTLD_XXX defined in bionic dlfcn.h | ||
188 | // Returns: | ||
189 | // The opaque handle of the shared library if sucessful, otherwise NULL | ||
190 | // | ||
191 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
192 | // Use loadLibraryExt instead in namespace scenario. | ||
193 | void* (*loadLibrary)(const char* libpath, int flag); | ||
194 | |||
195 | // Get a native bridge trampoline for specified native method. The trampoline has same | ||
196 | // sigature as the native method. | ||
197 | // | ||
198 | // Parameters: | ||
199 | // handle [IN] the handle returned from loadLibrary | ||
200 | // shorty [IN] short descriptor of native method | ||
201 | // len [IN] length of shorty | ||
202 | // Returns: | ||
203 | // address of trampoline if successful, otherwise NULL | ||
204 | void* (*getTrampoline)(void* handle, const char* name, const char* shorty, uint32_t len); | ||
205 | |||
206 | // Check whether native library is valid and is for an ABI that is supported by native bridge. | ||
207 | // | ||
208 | // Parameters: | ||
209 | // libpath [IN] path to the shared library | ||
210 | // Returns: | ||
211 | // TRUE if library is supported by native bridge, FALSE otherwise | ||
212 | // | ||
213 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
214 | // Use isPathSupported instead in namespace scenario. | ||
215 | bool (*isSupported)(const char* libpath); | ||
216 | |||
217 | // Provide environment values required by the app running with native bridge according to the | ||
218 | // instruction set. | ||
219 | // | ||
220 | // Parameters: | ||
221 | // instruction_set [IN] the instruction set of the app | ||
222 | // Returns: | ||
223 | // NULL if not supported by native bridge. | ||
224 | // Otherwise, return all environment values to be set after fork. | ||
225 | const struct NativeBridgeRuntimeValues* (*getAppEnv)(const char* instruction_set); | ||
226 | |||
227 | // Added callbacks in version 2. | ||
228 | |||
229 | // Check whether the bridge is compatible with the given version. A bridge may decide not to be | ||
230 | // forwards- or backwards-compatible, and libnativebridge will then stop using it. | ||
231 | // | ||
232 | // Parameters: | ||
233 | // bridge_version [IN] the version of libnativebridge. | ||
234 | // Returns: | ||
235 | // true if the native bridge supports the given version of libnativebridge. | ||
236 | bool (*isCompatibleWith)(uint32_t bridge_version); | ||
237 | |||
238 | // A callback to retrieve a native bridge's signal handler for the specified signal. The runtime | ||
239 | // will ensure that the signal handler is being called after the runtime's own handler, but before | ||
240 | // all chained handlers. The native bridge should not try to install the handler by itself, as | ||
241 | // that will potentially lead to cycles. | ||
242 | // | ||
243 | // Parameters: | ||
244 | // signal [IN] the signal for which the handler is asked for. Currently, only SIGSEGV is | ||
245 | // supported by the runtime. | ||
246 | // Returns: | ||
247 | // NULL if the native bridge doesn't use a handler or doesn't want it to be managed by the | ||
248 | // runtime. | ||
249 | // Otherwise, a pointer to the signal handler. | ||
250 | NativeBridgeSignalHandlerFn (*getSignalHandler)(int signal); | ||
251 | |||
252 | // Added callbacks in version 3. | ||
253 | |||
254 | // Decrements the reference count on the dynamic library handler. If the reference count drops | ||
255 | // to zero then the dynamic library is unloaded. | ||
256 | // | ||
257 | // Parameters: | ||
258 | // handle [IN] the handler of a dynamic library. | ||
259 | // | ||
260 | // Returns: | ||
261 | // 0 on success, and nonzero on error. | ||
262 | int (*unloadLibrary)(void* handle); | ||
263 | |||
264 | // Dump the last failure message of native bridge when fail to load library or search symbol. | ||
265 | // | ||
266 | // Parameters: | ||
267 | // | ||
268 | // Returns: | ||
269 | // A string describing the most recent error that occurred when load library | ||
270 | // or lookup symbol via native bridge. | ||
271 | const char* (*getError)(); | ||
272 | |||
273 | // Check whether library paths are supported by native bridge. | ||
274 | // | ||
275 | // Parameters: | ||
276 | // library_path [IN] search paths for native libraries (directories separated by ':') | ||
277 | // Returns: | ||
278 | // TRUE if libraries within search paths are supported by native bridge, FALSE otherwise | ||
279 | // | ||
280 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
281 | // Use isSupported instead in non-namespace scenario. | ||
282 | bool (*isPathSupported)(const char* library_path); | ||
283 | |||
284 | // Initializes anonymous namespace at native bridge side. | ||
285 | // NativeBridge's peer of android_init_anonymous_namespace() of dynamic linker. | ||
286 | // | ||
287 | // The anonymous namespace is used in the case when a NativeBridge implementation | ||
288 | // cannot identify the caller of dlopen/dlsym which happens for the code not loaded | ||
289 | // by dynamic linker; for example calls from the mono-compiled code. | ||
290 | // | ||
291 | // Parameters: | ||
292 | // public_ns_sonames [IN] the name of "public" libraries. | ||
293 | // anon_ns_library_path [IN] the library search path of (anonymous) namespace. | ||
294 | // Returns: | ||
295 | // true if the pass is ok. | ||
296 | // Otherwise, false. | ||
297 | // | ||
298 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
299 | // Should not use in non-namespace scenario. | ||
300 | bool (*initAnonymousNamespace)(const char* public_ns_sonames, const char* anon_ns_library_path); | ||
301 | |||
302 | // Create new namespace in which native libraries will be loaded. | ||
303 | // NativeBridge's peer of android_create_namespace() of dynamic linker. | ||
304 | // | ||
305 | // Parameters: | ||
306 | // name [IN] the name of the namespace. | ||
307 | // ld_library_path [IN] the first set of library search paths of the namespace. | ||
308 | // default_library_path [IN] the second set of library search path of the namespace. | ||
309 | // type [IN] the attribute of the namespace. | ||
310 | // permitted_when_isolated_path [IN] the permitted path for isolated namespace(if it is). | ||
311 | // parent_ns [IN] the pointer of the parent namespace to be inherited from. | ||
312 | // Returns: | ||
313 | // native_bridge_namespace_t* for created namespace or nullptr in the case of error. | ||
314 | // | ||
315 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
316 | // Should not use in non-namespace scenario. | ||
317 | native_bridge_namespace_t* (*createNamespace)(const char* name, | ||
318 | const char* ld_library_path, | ||
319 | const char* default_library_path, | ||
320 | uint64_t type, | ||
321 | const char* permitted_when_isolated_path, | ||
322 | native_bridge_namespace_t* parent_ns); | ||
323 | |||
324 | // Creates a link which shares some libraries from one namespace to another. | ||
325 | // NativeBridge's peer of android_link_namespaces() of dynamic linker. | ||
326 | // | ||
327 | // Parameters: | ||
328 | // from [IN] the namespace where libraries are accessed. | ||
329 | // to [IN] the namespace where libraries are loaded. | ||
330 | // shared_libs_sonames [IN] the libraries to be shared. | ||
331 | // | ||
332 | // Returns: | ||
333 | // Whether successed or not. | ||
334 | // | ||
335 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
336 | // Should not use in non-namespace scenario. | ||
337 | bool (*linkNamespaces)(native_bridge_namespace_t* from, native_bridge_namespace_t* to, | ||
338 | const char* shared_libs_sonames); | ||
339 | |||
340 | // Load a shared library within a namespace. | ||
341 | // NativeBridge's peer of android_dlopen_ext() of dynamic linker, only supports namespace | ||
342 | // extension. | ||
343 | // | ||
344 | // Parameters: | ||
345 | // libpath [IN] path to the shared library | ||
346 | // flag [IN] the stardard RTLD_XXX defined in bionic dlfcn.h | ||
347 | // ns [IN] the pointer of the namespace in which the library should be loaded. | ||
348 | // Returns: | ||
349 | // The opaque handle of the shared library if sucessful, otherwise NULL | ||
350 | // | ||
351 | // Starting with v3, NativeBridge has two scenarios: with/without namespace. | ||
352 | // Use loadLibrary instead in non-namespace scenario. | ||
353 | void* (*loadLibraryExt)(const char* libpath, int flag, native_bridge_namespace_t* ns); | ||
354 | |||
355 | // Get native bridge version of vendor namespace. | ||
356 | // The vendor namespace is the namespace used to load vendor public libraries. | ||
357 | // With O release this namespace can be different from the default namespace. | ||
358 | // For the devices without enable vendor namespaces this function should return null | ||
359 | // | ||
360 | // Returns: | ||
361 | // vendor namespace or null if it was not set up for the device | ||
362 | native_bridge_namespace_t* (*getVendorNamespace)(); | ||
363 | }; | ||
364 | |||
365 | // Runtime interfaces to native bridge. | ||
366 | struct NativeBridgeRuntimeCallbacks { | ||
367 | // Get shorty of a Java method. The shorty is supposed to be persistent in memory. | ||
368 | // | ||
369 | // Parameters: | ||
370 | // env [IN] pointer to JNIenv. | ||
371 | // mid [IN] Java methodID. | ||
372 | // Returns: | ||
373 | // short descriptor for method. | ||
374 | const char* (*getMethodShorty)(JNIEnv* env, jmethodID mid); | ||
375 | |||
376 | // Get number of native methods for specified class. | ||
377 | // | ||
378 | // Parameters: | ||
379 | // env [IN] pointer to JNIenv. | ||
380 | // clazz [IN] Java class object. | ||
381 | // Returns: | ||
382 | // number of native methods. | ||
383 | uint32_t (*getNativeMethodCount)(JNIEnv* env, jclass clazz); | ||
384 | |||
385 | // Get at most 'method_count' native methods for specified class 'clazz'. Results are outputed | ||
386 | // via 'methods' [OUT]. The signature pointer in JNINativeMethod is reused as the method shorty. | ||
387 | // | ||
388 | // Parameters: | ||
389 | // env [IN] pointer to JNIenv. | ||
390 | // clazz [IN] Java class object. | ||
391 | // methods [OUT] array of method with the name, shorty, and fnPtr. | ||
392 | // method_count [IN] max number of elements in methods. | ||
393 | // Returns: | ||
394 | // number of method it actually wrote to methods. | ||
395 | uint32_t (*getNativeMethods)(JNIEnv* env, jclass clazz, JNINativeMethod* methods, | ||
396 | uint32_t method_count); | ||
397 | }; | ||
398 | |||
399 | }; // namespace android | ||
400 | |||
401 | #endif // NATIVE_BRIDGE_H_ | ||