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 // ATTENTION: this is a local copy of system/core/include/nativebridge/native_bridge.h for v3,
18 // modded to remove interfaces used by the runtime to control native bridge.
19 // The copy makes berberis compile-time independent from native bridge version in
20 // system/core/libnativebridge.
21 
22 #ifndef BERBERIS_NATIVE_BRIDGE_NATIVE_BRIDGE_V7_H_
23 #define BERBERIS_NATIVE_BRIDGE_NATIVE_BRIDGE_V7_H_
24 
25 #include <signal.h>
26 #include <stdint.h>
27 #include <sys/types.h>
28 #include "jni.h"
29 
30 namespace android {
31 
32 enum JNICallType {
33   kJNICallTypeRegular = 1,
34   kJNICallTypeCriticalNative = 2,
35 };
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 using NativeBridgeSignalHandlerFn = bool (*)(int, siginfo_t*, void*);
44 
45 struct native_bridge_namespace_t;
46 
47 // Native bridge interfaces to runtime.
48 struct NativeBridgeCallbacks {
49   // Version number of the interface.
50   uint32_t version;
51 
52   // Initialize native bridge. Native bridge's internal implementation must ensure MT safety and
53   // that the native bridge is initialized only once. Thus it is OK to call this interface for an
54   // already initialized native bridge.
55   //
56   // Parameters:
57   //   runtime_cbs [IN] the pointer to NativeBridgeRuntimeCallbacks.
58   // Returns:
59   //   true iff initialization was successful.
60   bool (*initialize)(const NativeBridgeRuntimeCallbacks* runtime_cbs,
61                      const char* private_dir,
62                      const char* instruction_set);
63 
64   // Load a shared library that is supported by the native bridge.
65   //
66   // Parameters:
67   //   libpath [IN] path to the shared library
68   //   flag [IN] the standard RTLD_XXX defined in bionic dlfcn.h
69   // Returns:
70   //   The opaque handle of the shared library if successful, otherwise NULL
71   //
72   // Starting with v3, NativeBridge has two scenarios: with/without namespace.
73   // Use loadLibraryExt instead in namespace scenario.
74   void* (*loadLibrary)(const char* libpath, int flag);
75 
76   // Get a native bridge trampoline for specified native method. The trampoline has same
77   // sigature as the native method.
78   //
79   // Parameters:
80   //   handle [IN] the handle returned from loadLibrary
81   //   shorty [IN] short descriptor of native method
82   //   len [IN] length of shorty
83   // Returns:
84   //   address of trampoline if successful, otherwise NULL
85   void* (*getTrampoline)(void* handle, const char* name, const char* shorty, uint32_t len);
86 
87   // Check whether native library is valid and is for an ABI that is supported by native bridge.
88   //
89   // Parameters:
90   //   libpath [IN] path to the shared library
91   // Returns:
92   //   TRUE if library is supported by native bridge, FALSE otherwise
93   //
94   // Starting with v3, NativeBridge has two scenarios: with/without namespace.
95   // Use isPathSupported instead in namespace scenario.
96   bool (*isSupported)(const char* libpath);
97 
98   // Provide environment values required by the app running with native bridge according to the
99   // instruction set.
100   //
101   // Parameters:
102   //    instruction_set [IN] the instruction set of the app
103   // Returns:
104   //    NULL if not supported by native bridge.
105   //    Otherwise, return all environment values to be set after fork.
106   const struct NativeBridgeRuntimeValues* (*getAppEnv)(const char* instruction_set);
107 
108   // Added callbacks in version 2.
109 
110   // Check whether the bridge is compatible with the given version. A bridge may decide not to be
111   // forwards- or backwards-compatible, and libnativebridge will then stop using it.
112   //
113   // Parameters:
114   //     bridge_version [IN] the version of libnativebridge.
115   // Returns:
116   //     true iff the native bridge supports the given version of libnativebridge.
117   bool (*isCompatibleWith)(uint32_t bridge_version);
118 
119   // A callback to retrieve a native bridge's signal handler for the specified signal. The runtime
120   // will ensure that the signal handler is being called after the runtime's own handler, but before
121   // all chained handlers. The native bridge should not try to install the handler by itself, as
122   // that will potentially lead to cycles.
123   //
124   // Parameters:
125   //     signal [IN] the signal for which the handler is asked for. Currently, only SIGSEGV is
126   //                 supported by the runtime.
127   // Returns:
128   //     NULL if the native bridge doesn't use a handler or doesn't want it to be managed by the
129   //     runtime.
130   //     Otherwise, a pointer to the signal handler.
131   NativeBridgeSignalHandlerFn (*getSignalHandler)(int signal);
132 
133   // Added callbacks in version 3.
134 
135   // Decrements the reference count on the dynamic library handler. If the reference count drops
136   // to zero then the dynamic library is unloaded.
137   //
138   // Parameters:
139   //     handle [IN] the handler of a dynamic library.
140   //
141   // Returns:
142   //   0 on success, and nonzero on error.
143   int (*unloadLibrary)(void* handle);
144 
145   // Dump the last failure message of native bridge when fail to load library or search symbol.
146   //
147   // Parameters:
148   //
149   // Returns:
150   //   A string describing the most recent error that occurred when load library
151   //   or lookup symbol via native bridge.
152   const char* (*getError)();
153 
154   // Check whether library paths are supported by native bridge.
155   //
156   // Parameters:
157   //   library_path [IN] search paths for native libraries (directories separated by ':')
158   // Returns:
159   //   TRUE if libraries within search paths are supported by native bridge, FALSE otherwise
160   //
161   // Starting with v3, NativeBridge has two scenarios: with/without namespace.
162   // Use isSupported instead in non-namespace scenario.
163   bool (*isPathSupported)(const char* library_path);
164 
165   // Initializes anonymous namespace at native bridge side.
166   // NativeBridge's peer of android_init_anonymous_namespace() of dynamic linker.
167   //
168   // The anonymous namespace is used in the case when a NativeBridge implementation
169   // cannot identify the caller of dlopen/dlsym which happens for the code not loaded
170   // by dynamic linker; for example calls from the mono-compiled code.
171   //
172   // Parameters:
173   //   public_ns_sonames [IN] the name of "public" libraries.
174   //   anon_ns_library_path [IN] the library search path of (anonymous) namespace.
175   // Returns:
176   //   true if the pass is ok.
177   //   Otherwise, false.
178   //
179   // Starting with v3, NativeBridge has two scenarios: with/without namespace.
180   // Should not use in non-namespace scenario.
181   bool (*initAnonymousNamespace)(const char* public_ns_sonames, const char* anon_ns_library_path);
182 
183   // Create a namespace and pass the key of related namespaces to native bridge.
184   //
185   // Parameters:
186   //     name [IN] the name of the namespace.
187   //     ld_library_path [IN] the first set of library search paths of the namespace.
188   //     default_library_path [IN] the second set of library search path of the namespace.
189   //     type [IN] the attribute of the namespace.
190   //     permitted_when_isolated_path [IN] the permitted path for isolated namespace(if it is).
191   //     parent_ns [IN] the pointer of the parent namespace to be inherited from.
192   // Returns:
193   //     native_bridge_namespace_t* for created namespace or nullptr in the case of error.
194   //
195   // Starting with v3, NativeBridge has two scenarios: with/without namespace.
196   // Should not use in non-namespace scenario.
197   native_bridge_namespace_t* (*createNamespace)(const char* name,
198                                                 const char* ld_library_path,
199                                                 const char* default_library_path,
200                                                 uint64_t type,
201                                                 const char* permitted_when_isolated_path,
202                                                 native_bridge_namespace_t* parent_ns);
203 
204   // Creates a link which shares some libraries from one namespace to another.
205   // NativeBridge's peer of android_link_namespaces() of dynamic linker.
206   //
207   // Parameters:
208   //   from [IN] the namespace where libraries are accessed.
209   //   to [IN] the namespace where libraries are loaded.
210   //   shared_libs_sonames [IN] the libraries to be shared.
211   //
212   // Returns:
213   //   Whether succeeded or not.
214   //
215   // Starting with v3, NativeBridge has two scenarios: with/without namespace.
216   // Should not use in non-namespace scenario.
217   bool (*linkNamespaces)(native_bridge_namespace_t* from,
218                          native_bridge_namespace_t* to,
219                          const char* shared_libs_sonames);
220 
221   // Load a shared library within a namespace.
222   //
223   // Parameters:
224   //   libpath [IN] path to the shared library
225   //   flag [IN] the standard RTLD_XXX defined in bionic dlfcn.h
226   //   ns [IN] the pointer of the namespace in which the library should be loaded.
227   // Returns:
228   //   The opaque handle of the shared library if successful, otherwise NULL
229   //
230   // Starting with v3, NativeBridge has two scenarios: with/without namespace.
231   // Use loadLibrary instead in non-namespace scenario.
232   void* (*loadLibraryExt)(const char* libpath, int flag, native_bridge_namespace_t* ns);
233 
234   // Get native bridge version of vendor namespace.
235   // The vendor namespace is the namespace used to load vendor public libraries.
236   // With O release this namespace can be different from the default namespace.
237   // For the devices without enabled vendor namespaces this function should return null
238   //
239   // Returns:
240   //   vendor namespace or null if it was not set up for the device
241   //
242   // Starting with v5 (Android Q) this function is no longer used.
243   // Use getExportedNamespace() below.
244   struct native_bridge_namespace_t* (*getVendorNamespace)();
245 
246   // Get native bridge version of exported namespace. Peer of
247   // android_get_exported_namespace(const char*) function.
248   //
249   // Returns:
250   //   exported namespace or null if it was not set up for the device
251   struct native_bridge_namespace_t* (*getExportedNamespace)(const char* name);
252 
253   void (*preZygoteFork)();
254 
255   // This replaces previous getTrampoline call starting with version 7 of the
256   // interface.
257   //
258   // Get a native bridge trampoline for specified native method. The trampoline
259   // has same signature as the native method.
260   //
261   // Parameters:
262   //   handle [IN] the handle returned from loadLibrary
263   //   shorty [IN] short descriptor of native method
264   //   len [IN] length of shorty
265   //   jni_call_type [IN] the type of JNI call
266   // Returns:
267   //   address of trampoline if successful, otherwise NULL
268   void* (*getTrampolineWithJNICallType)(void* handle,
269                                         const char* name,
270                                         const char* shorty,
271                                         uint32_t len,
272                                         enum JNICallType jni_call_type);
273 
274   // Get a native bridge trampoline for specified native method pointer.
275   //
276   // Parameters:
277   //   method [IN] pointer to method (ususally registered via call to RegisterNatives)
278   //   shorty [IN] short descriptor of native method
279   //   len [IN] length of shorty
280   //   jni_call_type [IN] the type of JNI call
281   // Returns:
282   //   address of trampoline if successful, otherwise NULL
283   void* (*getTrampolineForFunctionPointer)(const void* method,
284                                            const char* shorty,
285                                            uint32_t len,
286                                            enum JNICallType jni_call_type);
287 };
288 
289 // Runtime interfaces to native bridge.
290 struct NativeBridgeRuntimeCallbacks {
291   // Get shorty of a Java method. The shorty is supposed to be persistent in memory.
292   //
293   // Parameters:
294   //   env [IN] pointer to JNIenv.
295   //   mid [IN] Java methodID.
296   // Returns:
297   //   short descriptor for method.
298   const char* (*getMethodShorty)(JNIEnv* env, jmethodID mid);
299 
300   // Get number of native methods for specified class.
301   //
302   // Parameters:
303   //   env [IN] pointer to JNIenv.
304   //   clazz [IN] Java class object.
305   // Returns:
306   //   number of native methods.
307   uint32_t (*getNativeMethodCount)(JNIEnv* env, jclass clazz);
308 
309   // Get at most 'method_count' native methods for specified class 'clazz'. Results are outputed
310   // via 'methods' [OUT]. The signature pointer in JNINativeMethod is reused as the method shorty.
311   //
312   // Parameters:
313   //   env [IN] pointer to JNIenv.
314   //   clazz [IN] Java class object.
315   //   methods [OUT] array of method with the name, shorty, and fnPtr.
316   //   method_count [IN] max number of elements in methods.
317   // Returns:
318   //   number of method it actually wrote to methods.
319   uint32_t (*getNativeMethods)(JNIEnv* env,
320                                jclass clazz,
321                                JNINativeMethod* methods,
322                                uint32_t method_count);
323 };
324 
325 };  // namespace android
326 
327 #endif  // BERBERIS_NATIVE_BRIDGE_NATIVE_BRIDGE_V7_H_
328