• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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