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.
65void* NativeBridgeLoadLibrary(const char* libpath, int flag);
66
67// Get a native bridge trampoline for specified native method.
68void* 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.
71bool 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.
76uint32_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.
81NativeBridgeSignalHandlerFn 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.
87bool 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.
92bool NativeBridgeNameAcceptable(const char* native_bridge_library_filename);
93
94// Native bridge interfaces to runtime.
95struct 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.
175struct 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