summaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
Diffstat (limited to 'include')
-rw-r--r--include/nativebridge/native_bridge.h401
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
25namespace android {
26
27struct NativeBridgeRuntimeCallbacks;
28struct 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.
33typedef 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.
38bool 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.
43bool 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.
47bool 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.
51bool InitializeNativeBridge(JNIEnv* env, const char* instruction_set);
52
53// Unload the native bridge, if any. Should be called by Runtime::DidForkFromZygote.
54void UnloadNativeBridge();
55
56// Check whether a native bridge is available (opened or initialized). Requires a prior call to
57// LoadNativeBridge.
58bool NativeBridgeAvailable();
59
60// Check whether a native bridge is available (initialized). Requires a prior call to
61// LoadNativeBridge & InitializeNativeBridge.
62bool 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.
68void* NativeBridgeLoadLibrary(const char* libpath, int flag);
69
70// Get a native bridge trampoline for specified native method.
71void* 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.
78bool 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.
83uint32_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.
88NativeBridgeSignalHandlerFn 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.
94bool 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.
99bool 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.
103int 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.
107const char* NativeBridgeGetError();
108
109struct 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.
117bool 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.
128bool 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.
141native_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.
153bool 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.
162void* 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
165native_bridge_namespace_t* NativeBridgeGetVendorNamespace();
166
167// Native bridge interfaces to runtime.
168struct 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.
366struct 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_
generated by cgit v1.2.3 (git 2.39.2)