KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
elf.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  kos/elf.h
4  Copyright (C)2000,2001,2003 Dan Potter
5 
6 */
7 
8 /** \file kos/elf.h
9  \brief ELF binary loading support.
10 
11  This file contains the support functionality for loading ELF binaries in
12  KOS. This includes the various header structures and whatnot that are used
13  in ELF files to store code/data/relocations/etc. This isn't necessarily
14  meant for running multiple processes, but more for loadable library support
15  within KOS.
16 
17  \author Dan Potter
18 */
19 
20 #ifndef __KOS_ELF_H
21 #define __KOS_ELF_H
22 
23 #include <sys/cdefs.h>
24 __BEGIN_DECLS
25 
26 #include <arch/types.h>
27 #include <sys/queue.h>
28 
29 /** \brief ELF file header.
30 
31  This header is at the beginning of any valid ELF binary and serves to
32  identify the architecture of the binary and various data about it.
33 
34  \headerfile kos/elf.h
35 */
36 struct elf_hdr_t {
37  uint8 ident[16]; /**< \brief ELF identifier */
38  uint16 type; /**< \brief ELF file type */
39  uint16 machine; /**< \brief ELF file architecture */
40  uint32 version; /**< \brief Object file version */
41  uint32 entry; /**< \brief Entry point */
42  uint32 phoff; /**< \brief Program header offset */
43  uint32 shoff; /**< \brief Section header offset */
44  uint32 flags; /**< \brief Processor flags */
45  uint16 ehsize; /**< \brief ELF header size in bytes */
46  uint16 phentsize; /**< \brief Program header entry size */
47  uint16 phnum; /**< \brief Program header entry count */
48  uint16 shentsize; /**< \brief Section header entry size */
49  uint16 shnum; /**< \brief Section header entry count */
50  uint16 shstrndx; /**< \brief String table section index */
51 };
52 
53 /** \defgroup elf_archs ELF architecture types
54 
55  These are the various architectures that we might care about for ELF files.
56 
57  @{
58 */
59 #define EM_386 3 /**< \brief x86 (IA32) */
60 #define EM_ARM 40 /**< \brief ARM */
61 #define EM_SH 42 /**< \brief SuperH */
62 /** @} */
63 
64 /** \defgroup elf_sections Section header types
65 
66  These are the various types of section headers that can exist in an ELF
67  file.
68 
69  @{
70 */
71 #define SHT_NULL 0 /**< \brief Inactive section */
72 #define SHT_PROGBITS 1 /**< \brief Program code/data */
73 #define SHT_SYMTAB 2 /**< \brief Full symbol table */
74 #define SHT_STRTAB 3 /**< \brief String table */
75 #define SHT_RELA 4 /**< \brief Relocation table, with addends */
76 #define SHT_HASH 5 /**< \brief Symbol hash table */
77 #define SHT_DYNAMIC 6 /**< \brief Dynamic linking info */
78 #define SHT_NOTE 7 /**< \brief Notes section */
79 #define SHT_NOBITS 8 /**< \brief A section that occupies no space in
80 the file */
81 #define SHT_REL 9 /**< \brief Relocation table, no addends */
82 #define SHT_SHLIB 10 /**< \brief Reserved */
83 #define SHT_DYNSYM 11 /**< \brief Dynamic-only sym tab */
84 #define SHT_LOPROC 0x70000000 /**< \brief Start of processor specific types */
85 #define SHT_HIPROC 0x7fffffff /**< \brief End of processor specific types */
86 #define SHT_LOUSER 0x80000000 /**< \brief Start of program specific types */
87 #define SHT_HIUSER 0xffffffff /**< \brief End of program specific types */
88 /** @} */
89 
90 /** \defgroup elf_hdrflags Section header flags
91 
92  These are the flags that can be set on a section header. These are related
93  to whether the section should reside in memory and permissions on it.
94 
95  @{
96 */
97 #define SHF_WRITE 1 /**< \brief Writable data */
98 #define SHF_ALLOC 2 /**< \brief Resident */
99 #define SHF_EXECINSTR 4 /**< \brief Executable instructions */
100 #define SHF_MASKPROC 0xf0000000 /**< \brief Processor specific mask */
101 /** @} */
102 
103 /** \defgroup elf_specsec Special section indeces
104 
105  These are the indices to be used in special situations in the section array.
106 
107  @{
108 */
109 #define SHN_UNDEF 0 /**< \brief Undefined, missing, irrelevant */
110 #define SHN_ABS 0xfff1 /**< \brief Absolute values */
111 /** @} */
112 
113 /** \brief ELF Section header.
114 
115  This structure represents the header on each ELF section.
116 
117  \headerfile kos/elf.h
118 */
119 struct elf_shdr_t {
120  uint32 name; /**< \brief Index into string table */
121  uint32 type; /**< \brief Section type \see elf_sections */
122  uint32 flags; /**< \brief Section flags \see elf_hdrflags */
123  uint32 addr; /**< \brief In-memory offset */
124  uint32 offset; /**< \brief On-disk offset */
125  uint32 size; /**< \brief Size (if SHT_NOBITS, amount of 0s needed) */
126  uint32 link; /**< \brief Section header table index link */
127  uint32 info; /**< \brief Section header extra info */
128  uint32 addralign; /**< \brief Alignment constraints */
129  uint32 entsize; /**< \brief Fixed-size table entry sizes */
130 };
131 /* Link and info fields:
132 
133 switch (sh_type) {
134  case SHT_DYNAMIC:
135  link = section header index of the string table used by
136  the entries in this section
137  info = 0
138  case SHT_HASH:
139  ilnk = section header index of the string table to which
140  this info applies
141  info = 0
142  case SHT_REL, SHT_RELA:
143  link = section header index of associated symbol table
144  info = section header index of section to which reloc applies
145  case SHT_SYMTAB, SHT_DYNSYM:
146  link = section header index of associated string table
147  info = one greater than the symbol table index of the last
148  local symbol (binding STB_LOCAL)
149 }
150 
151 */
152 
153 /** \defgroup elf_binding Symbol binding types.
154 
155  These are the values that can be set to say how a symbol is bound in an ELF
156  binary. This is stored in the upper 4 bits of the info field in elf_sym_t.
157 
158  @{
159 */
160 #define STB_LOCAL 0 /**< \brief Local (non-exported) symbol */
161 #define STB_GLOBAL 1 /**< \brief Global (exported) symbol */
162 #define STB_WEAK 2 /**< \brief Weak-linked symbol */
163 /** @} */
164 
165 /** \defgroup elf_symtype Symbol types.
166 
167  These are the values that can be set to say what kind of symbol a given
168  symbol in an ELF file is. This is stored in the lower 4 bits of the info
169  field in elf_sym_t.
170 
171  @{
172 */
173 #define STT_NOTYPE 0 /**< \brief Symbol has no type */
174 #define STT_OBJECT 1 /**< \brief Symbol is an object */
175 #define STT_FUNC 2 /**< \brief Symbol is a function */
176 #define STT_SECTION 3 /**< \brief Symbol is a section */
177 #define STT_FILE 4 /**< \brief Symbol is a file name */
178 /** @} */
179 
180 /** \brief Symbol table entry
181 
182  This structure represents a single entry in a symbol table in an ELF file.
183 
184  \headerfile kos/elf.h
185 */
186 struct elf_sym_t {
187  uint32 name; /**< \brief Index into file's string table */
188  uint32 value; /**< \brief Value of the symbol */
189  uint32 size; /**< \brief Size of the symbol */
190  uint8 info; /**< \brief Symbol type and binding */
191  uint8 other; /**< \brief 0. Holds no meaning. */
192  uint16 shndx; /**< \brief Section index */
193 };
194 
195 /** \brief Retrieve the binding type for a symbol.
196  \param info The info field of an elf_sym_t.
197  \return The binding type of the symbol.
198  \see elf_binding
199 */
200 #define ELF32_ST_BIND(info) ((info) >> 4)
202 /** \brief Retrieve the symbol type for a symbol.
203  \param info The info field of an elf_sym_t.
204  \return The symbol type of the symbol.
205  \see elf_symtype
206 */
207 #define ELF32_ST_TYPE(info) ((info) & 0xf)
209 /** \brief ELF Relocation entry (with explicit addend).
210 
211  This structure represents an ELF relocation entry with an explicit addend.
212  This structure is used on some architectures, whereas others use the
213  elf_rel_t structure instead.
214 
215  \headerfile kos/elf.h
216 */
217 struct elf_rela_t {
218  uint32 offset; /**< \brief Offset within section */
219  uint32 info; /**< \brief Symbol and type */
220  int32 addend; /**< \brief Constant addend for the symbol */
221 };
222 
223 /** \brief ELF Relocation entry (without explicit addend).
224 
225  This structure represents an ELF relocation entry without an explicit
226  addend. This structure is used on some architectures, whereas others use the
227  elf_rela_t structure instead.
228 
229  \headerfile kos/elf.h
230 */
231 struct elf_rel_t {
232  uint32 offset; /**< \brief Offset within section */
233  uint32 info; /**< \brief Symbol and type */
234 };
235 
236 /** \defgroup elf_reltypes ELF relocation types
237 
238  These define the types of operations that can be done to calculate
239  relocations within ELF files.
240 
241  @{
242 */
243 #define R_SH_DIR32 1 /**< \brief SuperH: Rel = Symbol + Addend */
244 #define R_386_32 1 /**< \brief x86: Rel = Symbol + Addend */
245 #define R_386_PC32 2 /**< \brief x86: Rel = Symbol + Addend - Value */
246 /** @} */
247 
248 /** \brief Retrieve the symbol index from a relocation entry.
249  \param i The info field of an elf_rel_t or elf_rela_t.
250  \return The symbol table index from that relocation entry.
251 */
252 #define ELF32_R_SYM(i) ((i) >> 8)
254 /** \brief Retrieve the relocation type from a relocation entry.
255  \param i The info field of an elf_rel_t or an elf_rela_t.
256  \return The relocation type of that relocation.
257  \see elf_reltypes
258 */
259 #define ELF32_R_TYPE(i) ((uint8)(i))
261 struct klibrary;
262 
263 /** \brief Kernel-specific definition of a loaded ELF binary.
264 
265  This structure represents the internal representation of a loaded ELF binary
266  in KallistiOS (specifically as a dynamically loaded library).
267 
268  \headerfile kos/elf.h
269 */
270 typedef struct elf_prog {
271  void *data; /**< \brief Pointer to program in memory */
272  uint32 size; /**< \brief Memory image size (rounded up to page size) */
274  /* Library exports */
275  ptr_t lib_get_name; /**< \brief Pointer to get_name() function */
276  ptr_t lib_get_version; /**< \brief Pointer to get_version() function */
277  ptr_t lib_open; /**< \brief Pointer to library's open function */
278  ptr_t lib_close; /**< \brief Pointer to library's close function */
280  char fn[256]; /**< \brief Filename of library */
282 
283 /** \brief Load an ELF binary.
284 
285  This function loads an ELF binary from the VFS and fills in an elf_prog_t
286  for it.
287 
288  \param fn The filename of the binary on the VFS.
289  \param shell Unused?
290  \param out Storage for the binary that will be loaded.
291  \return 0 on success, <0 on failure.
292 */
293 int elf_load(const char *fn, struct klibrary * shell, elf_prog_t * out);
294 
295 /** \brief Free a loaded ELF program.
296 
297  This function cleans up an ELF binary that was loaded with elf_load().
298 
299  \param prog The loaded binary to clean up.
300 */
301 void elf_free(elf_prog_t *prog);
302 
303 __END_DECLS
304 
305 #endif /* __OS_ELF_H */
306 
uint32 flags
Processor flags.
Definition: elf.h:44
Common integer types.
uint16 machine
ELF file architecture.
Definition: elf.h:39
uint16 type
ELF file type.
Definition: elf.h:38
ptr_t lib_get_version
Pointer to get_version() function.
Definition: elf.h:277
uint32 link
Section header table index link.
Definition: elf.h:127
uint32 size
Size (if SHT_NOBITS, amount of 0s needed)
Definition: elf.h:126
ELF Section header.
Definition: elf.h:120
uint16 shstrndx
String table section index.
Definition: elf.h:50
ELF Relocation entry (without explicit addend).
Definition: elf.h:232
uint32 version
Object file version.
Definition: elf.h:40
uint16 phnum
Program header entry count.
Definition: elf.h:47
uint8 info
Symbol type and binding.
Definition: elf.h:191
uint32 offset
Offset within section.
Definition: elf.h:219
Loaded library structure.
Definition: library.h:63
uint16 shnum
Section header entry count.
Definition: elf.h:49
uint32 info
Symbol and type.
Definition: elf.h:234
uint32 entry
Entry point.
Definition: elf.h:41
long int32
32-bit signed integer
Definition: types.h:32
ptr_t lib_open
Pointer to library's open function.
Definition: elf.h:278
uint16 phentsize
Program header entry size.
Definition: elf.h:46
uint32 entsize
Fixed-size table entry sizes.
Definition: elf.h:130
ptr_t lib_close
Pointer to library's close function.
Definition: elf.h:279
uint32 type
Section type.
Definition: elf.h:122
uint32 info
Symbol and type.
Definition: elf.h:220
uint32 size
Size of the symbol.
Definition: elf.h:190
unsigned short uint16
16-bit unsigned integer
Definition: types.h:29
uint32 info
Section header extra info.
Definition: elf.h:128
uint32 name
Index into file's string table.
Definition: elf.h:188
uint32 ptr_t
Pointer arithmetic type.
Definition: types.h:47
char fn[256]
Filename of library.
Definition: elf.h:281
uint8 ident[16]
ELF identifier.
Definition: elf.h:37
uint16 ehsize
ELF header size in bytes.
Definition: elf.h:45
uint32 offset
Offset within section.
Definition: elf.h:233
unsigned long uint32
32-bit unsigned integer
Definition: types.h:28
Kernel-specific definition of a loaded ELF binary.
Definition: elf.h:271
uint32 addr
In-memory offset.
Definition: elf.h:124
void * data
Pointer to program in memory.
Definition: elf.h:272
uint32 addralign
Alignment constraints.
Definition: elf.h:129
uint32 shoff
Section header offset.
Definition: elf.h:43
Symbol table entry.
Definition: elf.h:187
ELF file header.
Definition: elf.h:36
uint32 phoff
Program header offset.
Definition: elf.h:42
void elf_free(elf_prog_t *prog)
Free a loaded ELF program.
uint32 flags
Section flags.
Definition: elf.h:123
uint16 shentsize
Section header entry size.
Definition: elf.h:48
unsigned char uint8
8-bit unsigned integer
Definition: types.h:30
int32 addend
Constant addend for the symbol.
Definition: elf.h:221
uint32 offset
On-disk offset.
Definition: elf.h:125
uint16 shndx
Section index.
Definition: elf.h:193
ELF Relocation entry (with explicit addend).
Definition: elf.h:218
uint8 other
0. Holds no meaning.
Definition: elf.h:192
uint32 size
Memory image size (rounded up to page size)
Definition: elf.h:273
ptr_t lib_get_name
Pointer to get_name() function.
Definition: elf.h:276
int elf_load(const char *fn, struct klibrary *shell, elf_prog_t *out)
Load an ELF binary.
uint32 value
Value of the symbol.
Definition: elf.h:189
uint32 name
Index into string table.
Definition: elf.h:121
struct elf_prog elf_prog_t
Kernel-specific definition of a loaded ELF binary.