xref: /freebsd/usr.sbin/kldxref/ef.h (revision 97530894)
1 /*-
2  * SPDX-License-Identifier: BSD-4-Clause
3  *
4  * Copyright (c) 2000, Boris Popov
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  * 1. Redistributions of source code must retain the above copyright
11  *    notice, this list of conditions and the following disclaimer.
12  * 2. Redistributions in binary form must reproduce the above copyright
13  *    notice, this list of conditions and the following disclaimer in the
14  *    documentation and/or other materials provided with the distribution.
15  * 3. All advertising materials mentioning features or use of this software
16  *    must display the following acknowledgement:
17  *    This product includes software developed by Boris Popov.
18  * 4. Neither the name of the author nor the names of any co-contributors
19  *    may be used to endorse or promote products derived from this software
20  *    without specific prior written permission.
21  *
22  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
23  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
26  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32  * SUCH DAMAGE.
33  */
34 
35 #ifndef _EF_H_
36 #define _EF_H_
37 
38 #include <sys/linker_set.h>
39 #include <stdbool.h>
40 
41 #define EF_CLOSE(ef) \
42     (ef)->ef_ops->close((ef)->ef_ef)
43 #define EF_SEG_READ_REL(ef, address, len, dest) \
44     (ef)->ef_ops->seg_read_rel((ef)->ef_ef, address, len, dest)
45 #define EF_SEG_READ_STRING(ef, address, len, dest) \
46     (ef)->ef_ops->seg_read_string((ef)->ef_ef, address, len, dest)
47 #define EF_SYMADDR(ef, symidx) \
48     (ef)->ef_ops->symaddr((ef)->ef_ef, symidx)
49 #define EF_LOOKUP_SET(ef, name, startp, stopp, countp) \
50     (ef)->ef_ops->lookup_set((ef)->ef_ef, name, startp, stopp, countp)
51 
52 /* XXX, should have a different name. */
53 typedef struct ef_file *elf_file_t;
54 
55 /* FreeBSD's headers define additional typedef's for ELF structures. */
56 typedef Elf64_Size GElf_Size;
57 typedef Elf64_Hashelt GElf_Hashelt;
58 
59 struct elf_file;
60 
61 struct elf_file_ops {
62 	void (*close)(elf_file_t ef);
63 	int (*seg_read_rel)(elf_file_t ef, GElf_Addr address, size_t len,
64 	    void *dest);
65 	int (*seg_read_string)(elf_file_t ef, GElf_Addr address, size_t len,
66 	    char *dest);
67 	GElf_Addr (*symaddr)(elf_file_t ef, GElf_Size symidx);
68 	int (*lookup_set)(elf_file_t ef, const char *name, GElf_Addr *startp,
69 	    GElf_Addr *stopp, long *countp);
70 };
71 
72 typedef int (elf_reloc_t)(struct elf_file *ef, const void *reldata,
73     Elf_Type reltype, GElf_Addr relbase, GElf_Addr dataoff, size_t len,
74     void *dest);
75 
76 struct elf_reloc_data {
77 	unsigned char class;
78 	unsigned char data;
79 	GElf_Half machine;
80 	elf_reloc_t *reloc;
81 };
82 
83 #define	ELF_RELOC(_class, _data, _machine, _reloc)			\
84 	static struct elf_reloc_data __CONCAT(elf_reloc_data_, __LINE__) = { \
85 	    .class = (_class),						\
86 	    .data = (_data),						\
87 	    .machine = (_machine),					\
88 	    .reloc = (_reloc)						\
89 	};								\
90 	DATA_SET(elf_reloc, __CONCAT(elf_reloc_data_, __LINE__))
91 
92 struct elf_file {
93 	elf_file_t ef_ef;
94 	struct elf_file_ops *ef_ops;
95 	const char *ef_filename;
96 	Elf *ef_elf;
97 	elf_reloc_t *ef_reloc;
98 	GElf_Ehdr ef_hdr;
99 	size_t ef_pointer_size;
100 	int ef_fd;
101 };
102 
103 #define	elf_class(ef)		((ef)->ef_hdr.e_ident[EI_CLASS])
104 #define	elf_encoding(ef)	((ef)->ef_hdr.e_ident[EI_DATA])
105 
106 /*
107  * "Generic" versions of module metadata structures.
108  */
109 struct Gmod_depend {
110 	int	md_ver_minimum;
111 	int	md_ver_preferred;
112 	int	md_ver_maximum;
113 };
114 
115 struct Gmod_version {
116 	int	mv_version;
117 };
118 
119 struct Gmod_metadata {
120 	int		md_version;	/* structure version MDTV_* */
121 	int		md_type;	/* type of entry MDT_* */
122 	GElf_Addr	md_data;	/* specific data */
123 	GElf_Addr	md_cval;	/* common string label */
124 };
125 
126 struct Gmod_pnp_match_info
127 {
128 	GElf_Addr	descr;	/* Description of the table */
129 	GElf_Addr	bus;	/* Name of the bus for this table */
130 	GElf_Addr	table;	/* Pointer to pnp table */
131 	int entry_len;		/* Length of each entry in the table (may be */
132 				/*   longer than descr describes). */
133 	int num_entry;		/* Number of entries in the table */
134 };
135 
136 __BEGIN_DECLS
137 
138 /*
139  * Attempt to parse an open ELF file as either an executable or DSO
140  * (ef_open) or an object file (ef_obj_open).  On success, these
141  * routines initialize the 'ef_ef' and 'ef_ops' members of 'ef'.
142  */
143 int ef_open(struct elf_file *ef, int verbose);
144 int ef_obj_open(struct elf_file *ef, int verbose);
145 
146 /*
147  * Direct operations on an ELF file regardless of type.  Many of these
148  * use libelf.
149  */
150 
151 /*
152  * Open an ELF file with libelf.  Populates fields other than ef_ef
153  * and ef_ops in '*efile'.
154  */
155 int	elf_open_file(struct elf_file *efile, const char *filename,
156     int verbose);
157 
158 /* Close an ELF file. */
159 void	elf_close_file(struct elf_file *efile);
160 
161 /* Is an ELF file the same architecture as hdr? */
162 bool	elf_compatible(struct elf_file *efile, const GElf_Ehdr *hdr);
163 
164 /* The size of a single object of 'type'. */
165 size_t	elf_object_size(struct elf_file *efile, Elf_Type type);
166 
167 /* The size of a pointer in architecture of 'efile'. */
168 size_t	elf_pointer_size(struct elf_file *efile);
169 
170 /*
171  * Read and convert an array of a data type from an ELF file.  This is
172  * a wrapper around gelf_xlatetom() which reads an array of raw ELF
173  * objects from the file and converts them into host structures using
174  * native endianness.  The data is returned in a dynamically-allocated
175  * buffer.
176  */
177 int	elf_read_data(struct elf_file *efile, Elf_Type type, off_t offset,
178     size_t len, void **out);
179 
180 /* Reads "raw" data from an ELF file without any translation. */
181 int	elf_read_raw_data(struct elf_file *efile, off_t offset, void *dst,
182     size_t len);
183 
184 /*
185  * A wrapper around elf_read_raw_data which returns the data in a
186  * dynamically-allocated buffer.
187  */
188 int	elf_read_raw_data_alloc(struct elf_file *efile, off_t offset,
189     size_t len, void **out);
190 
191 /*
192  * Read relocated data from an ELF file and return it in a
193  * dynamically-allocated buffer.  Note that no translation
194  * (byte-swapping for endianness, 32-vs-64) is performed on the
195  * returned data, but any ELF relocations which affect the contents
196  * are applied to the returned data.  The address parameter gives the
197  * address of the data buffer if the ELF file were loaded into memory
198  * rather than a direct file offset.
199  */
200 int	elf_read_relocated_data(struct elf_file *efile, GElf_Addr address,
201     size_t len, void **buf);
202 
203 /*
204  * Read the program headers from an ELF file and return them in a
205  * dynamically-allocated array of GElf_Phdr objects.
206  */
207 int	elf_read_phdrs(struct elf_file *efile, size_t *nphdrp,
208     GElf_Phdr **phdrp);
209 
210 /*
211  * Read the section headers from an ELF file and return them in a
212  * dynamically-allocated array of GElf_Shdr objects.
213  */
214 int	elf_read_shdrs(struct elf_file *efile, size_t *nshdrp,
215     GElf_Shdr **shdrp);
216 
217 /*
218  * Read the dynamic table from a section of an ELF file into a
219  * dynamically-allocated array of GElf_Dyn objects.
220  */
221 int	elf_read_dynamic(struct elf_file *efile, int section_index, size_t *ndynp,
222     GElf_Dyn **dynp);
223 
224 /*
225  * Read a symbol table from a section of an ELF file into a
226  * dynamically-allocated array of GElf_Sym objects.
227  */
228 int	elf_read_symbols(struct elf_file *efile, int section_index,
229     size_t *nsymp, GElf_Sym **symp);
230 
231 /*
232  * Read a string table described by a section header of an ELF file
233  * into a dynamically-allocated buffer.
234  */
235 int	elf_read_string_table(struct elf_file *efile, const GElf_Shdr *shdr,
236     long *strcnt, char **strtab);
237 
238 /*
239  * Read a table of relocation objects from a section of an ELF file
240  * into a dynamically-allocated array of GElf_Rel objects.
241  */
242 int	elf_read_rel(struct elf_file *efile, int section_index, long *nrelp,
243     GElf_Rel **relp);
244 
245 /*
246  * Read a table of relocation-with-addend objects from a section of an
247  * ELF file into a dynamically-allocated array of GElf_Rela objects.
248  */
249 int	elf_read_rela(struct elf_file *efile, int section_index, long *nrelap,
250     GElf_Rela **relap);
251 
252 /*
253  * Read a string from an ELF file and return it in the provided
254  * buffer.  If the string is longer than the buffer, this fails with
255  * EFAULT.  The address parameter gives the address of the data buffer
256  * if the ELF file were loaded into memory rather than a direct file
257  * offset.
258  */
259 int	elf_read_string(struct elf_file *efile, GElf_Addr address, void *dst,
260     size_t len);
261 
262 /* Return the address extracted from a target pointer stored at 'p'. */
263 GElf_Addr elf_address_from_pointer(struct elf_file *efile, const void *p);
264 
265 /*
266  * Read a linker set and return an array of addresses extracted from the
267  * relocated pointers in the linker set.
268  */
269 int	elf_read_linker_set(struct elf_file *efile, const char *name,
270     GElf_Addr **buf, long *countp);
271 
272 /*
273  * Read and convert a target 'struct mod_depend' into a host
274  * 'struct Gmod_depend'.
275  */
276 int	elf_read_mod_depend(struct elf_file *efile, GElf_Addr addr,
277     struct Gmod_depend *mdp);
278 
279 /*
280  * Read and convert a target 'struct mod_version' into a host
281  * 'struct Gmod_version'.
282  */
283 int	elf_read_mod_version(struct elf_file *efile, GElf_Addr addr,
284     struct Gmod_version *mdv);
285 
286 /*
287  * Read and convert a target 'struct mod_metadata' into a host
288  * 'struct Gmod_metadata'.
289  */
290 int	elf_read_mod_metadata(struct elf_file *efile, GElf_Addr addr,
291     struct Gmod_metadata *md);
292 
293 /*
294  * Read and convert a target 'struct mod_pnp_match_info' into a host
295  * 'struct Gmod_pnp_match_info'.
296  */
297 int	elf_read_mod_pnp_match_info(struct elf_file *efile, GElf_Addr addr,
298     struct Gmod_pnp_match_info *pnp);
299 
300 /*
301  * Apply relocations to the values obtained from the file. `relbase' is the
302  * target relocation address of the section, and `dataoff/len' is the region
303  * that is to be relocated, and has been copied to *dest
304  */
305 int	elf_reloc(struct elf_file *ef, const void *reldata, Elf_Type reltype,
306     GElf_Addr relbase, GElf_Addr dataoff, size_t len, void *dest);
307 
308 __END_DECLS
309 
310 #endif /* _EF_H_*/
311