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 __ANDROID_DLEXT_H__
18#define __ANDROID_DLEXT_H__
19
20#include <stdbool.h>
21#include <stddef.h>
22#include <stdint.h>
23#include <sys/cdefs.h>
24#include <sys/types.h>  /* for off64_t */
25
26__BEGIN_DECLS
27
28/* bitfield definitions for android_dlextinfo.flags */
29enum {
30  /* When set, the reserved_addr and reserved_size fields must point to an
31   * already-reserved region of address space which will be used to load the
32   * library if it fits. If the reserved region is not large enough, the load
33   * will fail.
34   */
35  ANDROID_DLEXT_RESERVED_ADDRESS      = 0x1,
36
37  /* As DLEXT_RESERVED_ADDRESS, but if the reserved region is not large enough,
38   * the linker will choose an available address instead.
39   */
40  ANDROID_DLEXT_RESERVED_ADDRESS_HINT = 0x2,
41
42  /* When set, write the GNU RELRO section of the mapped library to relro_fd
43   * after relocation has been performed, to allow it to be reused by another
44   * process loading the same library at the same address. This implies
45   * ANDROID_DLEXT_USE_RELRO.
46   */
47  ANDROID_DLEXT_WRITE_RELRO           = 0x4,
48
49  /* When set, compare the GNU RELRO section of the mapped library to relro_fd
50   * after relocation has been performed, and replace any relocated pages that
51   * are identical with a version mapped from the file.
52   */
53  ANDROID_DLEXT_USE_RELRO             = 0x8,
54
55  /* Instruct dlopen to use library_fd instead of opening file by name.
56   * The filename parameter is still used to identify the library.
57   */
58  ANDROID_DLEXT_USE_LIBRARY_FD        = 0x10,
59
60  /* If opening a library using library_fd read it starting at library_fd_offset.
61   * This flag is only valid when ANDROID_DLEXT_USE_LIBRARY_FD is set.
62   */
63  ANDROID_DLEXT_USE_LIBRARY_FD_OFFSET    = 0x20,
64
65  /* When set, do not check if the library has already been loaded by file stat(2)s.
66   *
67   * This flag allows forced loading of the library in the case when for some
68   * reason multiple ELF files share the same filename (because the already-loaded
69   * library has been removed and overwritten, for example).
70   *
71   * Note that if the library has the same dt_soname as an old one and some other
72   * library has the soname in DT_NEEDED list, the first one will be used to resolve any
73   * dependencies.
74   */
75  ANDROID_DLEXT_FORCE_LOAD = 0x40,
76
77  /* When set, if the minimum p_vaddr of the ELF file's PT_LOAD segments is non-zero,
78   * the dynamic linker will load it at that address.
79   *
80   * This flag is for ART internal use only.
81   */
82  ANDROID_DLEXT_FORCE_FIXED_VADDR = 0x80,
83
84  /* Instructs dlopen to load the library at the address specified by reserved_addr.
85   *
86   * The difference between ANDROID_DLEXT_LOAD_AT_FIXED_ADDRESS and ANDROID_DLEXT_RESERVED_ADDRESS
87   * is that for ANDROID_DLEXT_LOAD_AT_FIXED_ADDRESS the linker reserves memory at reserved_addr
88   * whereas for ANDROID_DLEXT_RESERVED_ADDRESS the linker relies on the caller to reserve the memory.
89   *
90   * This flag can be used with ANDROID_DLEXT_FORCE_FIXED_VADDR; when ANDROID_DLEXT_FORCE_FIXED_VADDR
91   * is set and load_bias is not 0 (load_bias is min(p_vaddr) of PT_LOAD segments) this flag is ignored.
92   * This is implemented this way because the linker has to pick one address over the other and this
93   * way is more convenient for art. Note that ANDROID_DLEXT_FORCE_FIXED_VADDR does not generate
94   * an error when min(p_vaddr) is 0.
95   *
96   * Cannot be used with ANDROID_DLEXT_RESERVED_ADDRESS or ANDROID_DLEXT_RESERVED_ADDRESS_HINT.
97   *
98   * This flag is for ART internal use only.
99   */
100  ANDROID_DLEXT_LOAD_AT_FIXED_ADDRESS = 0x100,
101
102  /* This flag used to load library in a different namespace. The namespace is
103   * specified in library_namespace.
104   */
105  ANDROID_DLEXT_USE_NAMESPACE = 0x200,
106
107  /* Mask of valid bits */
108  ANDROID_DLEXT_VALID_FLAG_BITS       = ANDROID_DLEXT_RESERVED_ADDRESS |
109                                        ANDROID_DLEXT_RESERVED_ADDRESS_HINT |
110                                        ANDROID_DLEXT_WRITE_RELRO |
111                                        ANDROID_DLEXT_USE_RELRO |
112                                        ANDROID_DLEXT_USE_LIBRARY_FD |
113                                        ANDROID_DLEXT_USE_LIBRARY_FD_OFFSET |
114                                        ANDROID_DLEXT_FORCE_LOAD |
115                                        ANDROID_DLEXT_FORCE_FIXED_VADDR |
116                                        ANDROID_DLEXT_LOAD_AT_FIXED_ADDRESS |
117                                        ANDROID_DLEXT_USE_NAMESPACE,
118};
119
120struct android_namespace_t;
121
122typedef struct {
123  uint64_t flags;
124  void*   reserved_addr;
125  size_t  reserved_size;
126  int     relro_fd;
127  int     library_fd;
128  off64_t library_fd_offset;
129  struct android_namespace_t* library_namespace;
130} android_dlextinfo;
131
132void* android_dlopen_ext(const char* filename, int flag, const android_dlextinfo* extinfo)
133  __INTRODUCED_IN(21);
134
135__END_DECLS
136
137#endif /* __ANDROID_DLEXT_H__ */
138