Rev 2726 | Only display areas with differences | Regard whitespace | Details | Blame | Last modification | View Log | RSS feed
Rev 2726 | Rev 2787 | ||
---|---|---|---|
1 | ------------------------------------------------- |
1 | ------------------------------------------------- |
2 | Building EFI Applications Using the GNU Toolchain |
2 | Building EFI Applications Using the GNU Toolchain |
3 | ------------------------------------------------- |
3 | ------------------------------------------------- |
4 | 4 | ||
5 | David Mosberger <davidm@hpl.hp.com> |
5 | David Mosberger <davidm@hpl.hp.com> |
6 | 6 | ||
7 | 23 September 1999 |
7 | 23 September 1999 |
8 | 8 | ||
9 | 9 | ||
10 | Copyright (c) 1999-2003 Hewlett-Packard Co. |
10 | Copyright (c) 1999-2003 Hewlett-Packard Co. |
11 | 11 | ||
12 | Last update: 08/20/2003 |
12 | Last update: 08/20/2003 |
13 | 13 | ||
14 | * Introduction |
14 | * Introduction |
15 | 15 | ||
16 | This document has two parts: the first part describes how to develop |
16 | This document has two parts: the first part describes how to develop |
17 | EFI applications for IA-64 and x86 using the GNU toolchain and the EFI |
17 | EFI applications for IA-64 and x86 using the GNU toolchain and the EFI |
18 | development environment contained in this directory. The second part |
18 | development environment contained in this directory. The second part |
19 | describes some of the more subtle aspects of how this development |
19 | describes some of the more subtle aspects of how this development |
20 | environment works. |
20 | environment works. |
21 | 21 | ||
22 | 22 | ||
23 | 23 | ||
24 | * Part 1: Developing EFI Applications |
24 | * Part 1: Developing EFI Applications |
25 | 25 | ||
26 | 26 | ||
27 | ** Prerequisites: |
27 | ** Prerequisites: |
28 | 28 | ||
29 | To develop x86 EFI applications, the following tools are needed: |
29 | To develop x86 EFI applications, the following tools are needed: |
30 | 30 | ||
31 | - gcc-3.0 or newer (gcc 2.7.2 is NOT sufficient!) |
31 | - gcc-3.0 or newer (gcc 2.7.2 is NOT sufficient!) |
32 | As of gnu-efi-3.0b, the Redhat 8.0 toolchain is known to work, |
32 | As of gnu-efi-3.0b, the Redhat 8.0 toolchain is known to work, |
33 | but the Redhat 9.0 toolchain is not currently supported. |
33 | but the Redhat 9.0 toolchain is not currently supported. |
34 | 34 | ||
35 | - A version of "objcopy" that supports EFI applications. To |
35 | - A version of "objcopy" that supports EFI applications. To |
36 | check if your version includes EFI support, issue the |
36 | check if your version includes EFI support, issue the |
37 | command: |
37 | command: |
38 | 38 | ||
39 | objcopy --help |
39 | objcopy --help |
40 | 40 | ||
41 | and verify that the line "supported targets" contains the |
41 | and verify that the line "supported targets" contains the |
42 | string "efi-app-ia32". |
42 | string "efi-app-ia32". |
43 | 43 | ||
44 | - For debugging purposes, it's useful to have a version of |
44 | - For debugging purposes, it's useful to have a version of |
45 | "objdump" that supports EFI applications as well. This |
45 | "objdump" that supports EFI applications as well. This |
46 | allows inspect and disassemble EFI binaries. |
46 | allows inspect and disassemble EFI binaries. |
47 | 47 | ||
48 | To develop IA-64 EFI applications, the following tools are needed: |
48 | To develop IA-64 EFI applications, the following tools are needed: |
49 | 49 | ||
50 | - A version of gcc newer than July 30th 1999 (older versions |
50 | - A version of gcc newer than July 30th 1999 (older versions |
51 | had problems with generating position independent code). |
51 | had problems with generating position independent code). |
52 | As of gnu-efi-3.0b, gcc-3.1 is known to work well. |
52 | As of gnu-efi-3.0b, gcc-3.1 is known to work well. |
53 | 53 | ||
54 | - A version of "objcopy" that supports EFI applications. To |
54 | - A version of "objcopy" that supports EFI applications. To |
55 | check if your version includes EFI support, issue the |
55 | check if your version includes EFI support, issue the |
56 | command: |
56 | command: |
57 | 57 | ||
58 | objcopy --help |
58 | objcopy --help |
59 | 59 | ||
60 | and verify that the line "supported targets" contains the |
60 | and verify that the line "supported targets" contains the |
61 | string "efi-app-ia64". |
61 | string "efi-app-ia64". |
62 | 62 | ||
63 | - For debugging purposes, it's useful to have a version of |
63 | - For debugging purposes, it's useful to have a version of |
64 | "objdump" that supports EFI applications as well. This |
64 | "objdump" that supports EFI applications as well. This |
65 | allows inspect and disassemble EFI binaries. |
65 | allows inspect and disassemble EFI binaries. |
66 | 66 | ||
67 | 67 | ||
68 | ** Directory Structure |
68 | ** Directory Structure |
69 | 69 | ||
70 | This EFI development environment contains the following |
70 | This EFI development environment contains the following |
71 | subdirectories: |
71 | subdirectories: |
72 | 72 | ||
73 | inc: This directory contains the EFI-related include files. The |
73 | inc: This directory contains the EFI-related include files. The |
74 | files are taken from Intel's EFI source distribution, except |
74 | files are taken from Intel's EFI source distribution, except |
75 | that various fixes were applied to make it compile with the |
75 | that various fixes were applied to make it compile with the |
76 | GNU toolchain. |
76 | GNU toolchain. |
77 | 77 | ||
78 | lib: This directory contains the source code for Intel's EFI library. |
78 | lib: This directory contains the source code for Intel's EFI library. |
79 | Again, the files are taken from Intel's EFI source |
79 | Again, the files are taken from Intel's EFI source |
80 | distribution, with changes to make them compile with the GNU |
80 | distribution, with changes to make them compile with the GNU |
81 | toolchain. |
81 | toolchain. |
82 | 82 | ||
83 | gnuefi: This directory contains the glue necessary to convert ELF64 |
83 | gnuefi: This directory contains the glue necessary to convert ELF64 |
84 | binaries to EFI binaries. Various runtime code bits, such as |
84 | binaries to EFI binaries. Various runtime code bits, such as |
85 | a self-relocator are included as well. This code has been |
85 | a self-relocator are included as well. This code has been |
86 | contributed by the Hewlett-Packard Company and is distributed |
86 | contributed by the Hewlett-Packard Company and is distributed |
87 | under the GNU GPL. |
87 | under the GNU GPL. |
88 | 88 | ||
89 | apps: This directory contains a few simple EFI test apps. |
89 | apps: This directory contains a few simple EFI test apps. |
90 | 90 | ||
91 | ** Setup |
91 | ** Setup |
92 | 92 | ||
93 | It is necessary to edit the Makefile in the directory containing this |
93 | It is necessary to edit the Makefile in the directory containing this |
94 | README file before EFI applications can be built. Specifically, you |
94 | README file before EFI applications can be built. Specifically, you |
95 | should verify that macros CC, AS, LD, AR, RANLIB, and OBJCOPY point to |
95 | should verify that macros CC, AS, LD, AR, RANLIB, and OBJCOPY point to |
96 | the appropriate compiler, assembler, linker, ar, and ranlib binaries, |
96 | the appropriate compiler, assembler, linker, ar, and ranlib binaries, |
97 | respectively. |
97 | respectively. |
98 | 98 | ||
99 | If you're working in a cross-development environment, be sure to set |
99 | If you're working in a cross-development environment, be sure to set |
100 | macro ARCH to the desired target architecture ("ia32" for x86, "ia64" |
100 | macro ARCH to the desired target architecture ("ia32" for x86, "ia64" |
101 | for IA-64). For convenience, this can also be done from the make |
101 | for IA-64). For convenience, this can also be done from the make |
102 | command line (e.g., "make ARCH=ia64"). |
102 | command line (e.g., "make ARCH=ia64"). |
103 | 103 | ||
104 | 104 | ||
105 | ** Building |
105 | ** Building |
106 | 106 | ||
107 | To build the sample EFI applications provided in subdirectory "apps", |
107 | To build the sample EFI applications provided in subdirectory "apps", |
108 | simply invoke "make" in the toplevel directory (the directory |
108 | simply invoke "make" in the toplevel directory (the directory |
109 | containing this README file). This should build lib/libefi.a and |
109 | containing this README file). This should build lib/libefi.a and |
110 | gnuefi/libgnuefi.a first and then all the EFI applications such as a |
110 | gnuefi/libgnuefi.a first and then all the EFI applications such as a |
111 | apps/t6.efi. |
111 | apps/t6.efi. |
112 | 112 | ||
113 | 113 | ||
114 | ** Running |
114 | ** Running |
115 | 115 | ||
116 | Just copy the EFI application (e.g., apps/t6.efi) to the EFI |
116 | Just copy the EFI application (e.g., apps/t6.efi) to the EFI |
117 | filesystem, boot EFI, and then select "Invoke EFI application" to run |
117 | filesystem, boot EFI, and then select "Invoke EFI application" to run |
118 | the application you want to test. Alternatively, you can invoke the |
118 | the application you want to test. Alternatively, you can invoke the |
119 | Intel-provided "nshell" application and then invoke your test binary |
119 | Intel-provided "nshell" application and then invoke your test binary |
120 | via the command line interface that "nshell" provides. |
120 | via the command line interface that "nshell" provides. |
121 | 121 | ||
122 | 122 | ||
123 | ** Writing Your Own EFI Application |
123 | ** Writing Your Own EFI Application |
124 | 124 | ||
125 | Suppose you have your own EFI application in a file called |
125 | Suppose you have your own EFI application in a file called |
126 | "apps/myefiapp.c". To get this application built by the GNU EFI build |
126 | "apps/myefiapp.c". To get this application built by the GNU EFI build |
127 | environment, simply add "myefiapp.efi" to macro TARGETS in |
127 | environment, simply add "myefiapp.efi" to macro TARGETS in |
128 | apps/Makefile. Once this is done, invoke "make" in the top level |
128 | apps/Makefile. Once this is done, invoke "make" in the top level |
129 | directory. This should result in EFI application apps/myefiapp.efi, |
129 | directory. This should result in EFI application apps/myefiapp.efi, |
130 | ready for execution. |
130 | ready for execution. |
131 | 131 | ||
132 | The GNU EFI build environment allows to write EFI applications as |
132 | The GNU EFI build environment allows to write EFI applications as |
133 | described in Intel's EFI documentation, except for two differences: |
133 | described in Intel's EFI documentation, except for two differences: |
134 | 134 | ||
135 | - The EFI application's entry point is always called "efi_main". The |
135 | - The EFI application's entry point is always called "efi_main". The |
136 | declaration of this routine is: |
136 | declaration of this routine is: |
137 | 137 | ||
138 | EFI_STATUS efi_main (EFI_HANDLE image, EFI_SYSTEM_TABLE *systab); |
138 | EFI_STATUS efi_main (EFI_HANDLE image, EFI_SYSTEM_TABLE *systab); |
139 | 139 | ||
140 | - UNICODE string literals must be written as W2U(L"Sample String") |
140 | - UNICODE string literals must be written as W2U(L"Sample String") |
141 | instead of just L"Sample String". The W2U() macro is defined in |
141 | instead of just L"Sample String". The W2U() macro is defined in |
142 | <efilib.h>. This header file also declares the function W2UCpy() |
142 | <efilib.h>. This header file also declares the function W2UCpy() |
143 | which allows to convert a wide string into a UNICODE string and |
143 | which allows to convert a wide string into a UNICODE string and |
144 | store the result in a programmer-supplied buffer. |
144 | store the result in a programmer-supplied buffer. |
145 | 145 | ||
146 | 146 | ||
147 | * Part 2: Inner Workings |
147 | * Part 2: Inner Workings |
148 | 148 | ||
149 | WARNING: This part contains all the gory detail of how the GNU EFI |
149 | WARNING: This part contains all the gory detail of how the GNU EFI |
150 | toolchain works. Normal users do not have to worry about such |
150 | toolchain works. Normal users do not have to worry about such |
151 | details. Reading this part incurs a definite risk of inducing severe |
151 | details. Reading this part incurs a definite risk of inducing severe |
152 | headaches or other maladies. |
152 | headaches or other maladies. |
153 | 153 | ||
154 | The basic idea behind the GNU EFI build environment is to use the GNU |
154 | The basic idea behind the GNU EFI build environment is to use the GNU |
155 | toolchain to build a normal ELF binary that, at the end, is converted |
155 | toolchain to build a normal ELF binary that, at the end, is converted |
156 | to an EFI binary. EFI binaries are really just PE32+ binaries. PE |
156 | to an EFI binary. EFI binaries are really just PE32+ binaries. PE |
157 | stands for "Portable Executable" and is the object file format |
157 | stands for "Portable Executable" and is the object file format |
158 | Microsoft is using on its Windows platforms. PE is basically the COFF |
158 | Microsoft is using on its Windows platforms. PE is basically the COFF |
159 | object file format with an MS-DOS2.0 compatible header slapped on in |
159 | object file format with an MS-DOS2.0 compatible header slapped on in |
160 | front of it. The "32" in PE32+ stands for 32 bits, meaning that PE32 |
160 | front of it. The "32" in PE32+ stands for 32 bits, meaning that PE32 |
161 | is a 32-bit object file format. The plus in "PE32+" indicates that |
161 | is a 32-bit object file format. The plus in "PE32+" indicates that |
162 | this format has been hacked to allow loading a 4GB binary anywhere in |
162 | this format has been hacked to allow loading a 4GB binary anywhere in |
163 | a 64-bit address space (unlike ELF64, however, this is not a full |
163 | a 64-bit address space (unlike ELF64, however, this is not a full |
164 | 64-bit object file format because the entire binary cannot span more |
164 | 64-bit object file format because the entire binary cannot span more |
165 | than 4GB of address space). EFI binaries are plain PE32+ binaries |
165 | than 4GB of address space). EFI binaries are plain PE32+ binaries |
166 | except that the "subsystem id" differs from normal Windows binaries. |
166 | except that the "subsystem id" differs from normal Windows binaries. |
167 | There are two flavors of EFI binaries: "applications" and "drivers" |
167 | There are two flavors of EFI binaries: "applications" and "drivers" |
168 | and each has there own subsystem id and are identical otherwise. At |
168 | and each has there own subsystem id and are identical otherwise. At |
169 | present, the GNU EFI build environment supports the building of EFI |
169 | present, the GNU EFI build environment supports the building of EFI |
170 | applications only, though it would be trivial to generate drivers, as |
170 | applications only, though it would be trivial to generate drivers, as |
171 | the only difference is the subsystem id. For more details on PE32+, |
171 | the only difference is the subsystem id. For more details on PE32+, |
172 | see the spec at |
172 | see the spec at |
173 | 173 | ||
174 | http://msdn.microsoft.com/library/specs/msdn_pecoff.htm. |
174 | http://msdn.microsoft.com/library/specs/msdn_pecoff.htm. |
175 | 175 | ||
176 | In theory, converting a suitable ELF64 binary to PE32+ is easy and |
176 | In theory, converting a suitable ELF64 binary to PE32+ is easy and |
177 | could be accomplished with the "objcopy" utility by specifying option |
177 | could be accomplished with the "objcopy" utility by specifying option |
178 | --target=efi-app-ia32 (x86) or --target=efi-app-ia64 (IA-64). But |
178 | --target=efi-app-ia32 (x86) or --target=efi-app-ia64 (IA-64). But |
179 | life never is that easy, so here some complicating factors: |
179 | life never is that easy, so here some complicating factors: |
180 | 180 | ||
181 | (1) COFF sections are very different from ELF sections. |
181 | (1) COFF sections are very different from ELF sections. |
182 | 182 | ||
183 | ELF binaries distinguish between program headers and sections. |
183 | ELF binaries distinguish between program headers and sections. |
184 | The program headers describe the memory segments that need to |
184 | The program headers describe the memory segments that need to |
185 | be loaded/initialized, whereas the sections describe what |
185 | be loaded/initialized, whereas the sections describe what |
186 | constitutes those segments. In COFF (and therefore PE32+) no |
186 | constitutes those segments. In COFF (and therefore PE32+) no |
187 | such distinction is made. Thus, COFF sections need to be page |
187 | such distinction is made. Thus, COFF sections need to be page |
188 | aligned and have a size that is a multiple of the page size |
188 | aligned and have a size that is a multiple of the page size |
189 | (4KB for EFI), whereas ELF allows sections at arbitrary |
189 | (4KB for EFI), whereas ELF allows sections at arbitrary |
190 | addresses and with arbitrary sizes. |
190 | addresses and with arbitrary sizes. |
191 | 191 | ||
192 | (2) EFI binaries should be relocatable. |
192 | (2) EFI binaries should be relocatable. |
193 | 193 | ||
194 | Since EFI binaries are executed in physical mode, EFI cannot |
194 | Since EFI binaries are executed in physical mode, EFI cannot |
195 | guarantee that a given binary can be loaded at its preferred |
195 | guarantee that a given binary can be loaded at its preferred |
196 | address. EFI does _try_ to load a binary at it's preferred |
196 | address. EFI does _try_ to load a binary at it's preferred |
197 | address, but if it can't do so, it will load it at another |
197 | address, but if it can't do so, it will load it at another |
198 | address and then relocate the binary using the contents of the |
198 | address and then relocate the binary using the contents of the |
199 | .reloc section. |
199 | .reloc section. |
200 | 200 | ||
201 | (3) On IA-64, the EFI entry point needs to point to a function |
201 | (3) On IA-64, the EFI entry point needs to point to a function |
202 | descriptor, not to the code address of the entry point. |
202 | descriptor, not to the code address of the entry point. |
203 | 203 | ||
204 | (4) The EFI specification assumes that wide characters use UNICODE |
204 | (4) The EFI specification assumes that wide characters use UNICODE |
205 | encoding. |
205 | encoding. |
206 | 206 | ||
207 | ANSI C does not specify the size or encoding that a wide |
207 | ANSI C does not specify the size or encoding that a wide |
208 | character uses. These choices are "implementation defined". |
208 | character uses. These choices are "implementation defined". |
209 | On most UNIX systems, the GNU toolchain uses a wchar_t that is |
209 | On most UNIX systems, the GNU toolchain uses a wchar_t that is |
210 | 4 bytes in size. The encoding used for such characters is |
210 | 4 bytes in size. The encoding used for such characters is |
211 | (mostly) UCS4. |
211 | (mostly) UCS4. |
212 | 212 | ||
213 | In the following sections, we address how the GNU EFI build |
213 | In the following sections, we address how the GNU EFI build |
214 | environment addresses each of these issues. |
214 | environment addresses each of these issues. |
215 | 215 | ||
216 | 216 | ||
217 | ** (1) Accommodating COFF Sections |
217 | ** (1) Accommodating COFF Sections |
218 | 218 | ||
219 | In order to satisfy the COFF constraint of page-sized and page-aligned |
219 | In order to satisfy the COFF constraint of page-sized and page-aligned |
220 | sections, the GNU EFI build environment uses the special linker script |
220 | sections, the GNU EFI build environment uses the special linker script |
221 | in gnuefi/elf_$(ARCH)_efi.lds where $(ARCH) is the target architecture |
221 | in gnuefi/elf_$(ARCH)_efi.lds where $(ARCH) is the target architecture |
222 | ("ia32" for x86, and "ia64" for IA-64). This script is set up to |
222 | ("ia32" for x86, and "ia64" for IA-64). This script is set up to |
223 | create only eight COFF section, each page aligned and page sized. |
223 | create only eight COFF section, each page aligned and page sized. |
224 | These eight sections are used to group together the much greater |
224 | These eight sections are used to group together the much greater |
225 | number of sections that are typically present in ELF object files. |
225 | number of sections that are typically present in ELF object files. |
226 | Specifically: |
226 | Specifically: |
227 | 227 | ||
228 | .hash |
228 | .hash |
229 | Collects the ELF .hash info (this section _must_ be the first |
229 | Collects the ELF .hash info (this section _must_ be the first |
230 | section in order to build a shared object file; the section is |
230 | section in order to build a shared object file; the section is |
231 | not actually loaded or used at runtime). |
231 | not actually loaded or used at runtime). |
232 | 232 | ||
233 | .text |
233 | .text |
234 | Collects all sections containing executable code. |
234 | Collects all sections containing executable code. |
235 | 235 | ||
236 | .data |
236 | .data |
237 | Collects read-only and read-write data, literal string data, |
237 | Collects read-only and read-write data, literal string data, |
238 | global offset tables, the uninitialized data segment (bss) and |
238 | global offset tables, the uninitialized data segment (bss) and |
239 | various other sections containing data. |
239 | various other sections containing data. |
240 | 240 | ||
241 | The reason read-only data is placed here instead of the in |
241 | The reason read-only data is placed here instead of the in |
242 | .text is to make it possible to disassemble the .text section |
242 | .text is to make it possible to disassemble the .text section |
243 | without getting garbage due to read-only data. Besides, since |
243 | without getting garbage due to read-only data. Besides, since |
244 | EFI binaries execute in physical mode, differences in page |
244 | EFI binaries execute in physical mode, differences in page |
245 | protection do not matter. |
245 | protection do not matter. |
246 | 246 | ||
247 | The reason the uninitialized data is placed in this section is |
247 | The reason the uninitialized data is placed in this section is |
248 | that the EFI loader appears to be unable to handle sections |
248 | that the EFI loader appears to be unable to handle sections |
249 | that are allocated but not loaded from the binary. |
249 | that are allocated but not loaded from the binary. |
250 | 250 | ||
251 | .dynamic, .dynsym, .rela, .rel, .reloc |
251 | .dynamic, .dynsym, .rela, .rel, .reloc |
252 | These sections contains the dynamic information necessary to |
252 | These sections contains the dynamic information necessary to |
253 | self-relocate the binary (see below). |
253 | self-relocate the binary (see below). |
254 | 254 | ||
255 | A couple of more points worth noting about the linker script: |
255 | A couple of more points worth noting about the linker script: |
256 | 256 | ||
257 | o On IA-64, the global pointer symbol (__gp) needs to be placed such |
257 | o On IA-64, the global pointer symbol (__gp) needs to be placed such |
258 | that the _entire_ EFI binary can be addressed using the signed |
258 | that the _entire_ EFI binary can be addressed using the signed |
259 | 22-bit offset that the "addl" instruction affords. Specifically, |
259 | 22-bit offset that the "addl" instruction affords. Specifically, |
260 | this means that __gp should be placed at ImageBase + 0x200000. |
260 | this means that __gp should be placed at ImageBase + 0x200000. |
261 | Strictly speaking, only a couple of symbols need to be addressable |
261 | Strictly speaking, only a couple of symbols need to be addressable |
262 | in this fashion, so with some care it should be possible to build |
262 | in this fashion, so with some care it should be possible to build |
263 | binaries much larger than 4MB. To get a list of symbols that need |
263 | binaries much larger than 4MB. To get a list of symbols that need |
264 | to be addressable in this fashion, grep the assembly files in |
264 | to be addressable in this fashion, grep the assembly files in |
265 | directory gnuefi for the string "@gprel". |
265 | directory gnuefi for the string "@gprel". |
266 | 266 | ||
267 | o The link address (ImageBase) of the binary is (arbitrarily) set to |
267 | o The link address (ImageBase) of the binary is (arbitrarily) set to |
268 | zero. This could be set to something larger to increase the chance |
268 | zero. This could be set to something larger to increase the chance |
269 | of EFI being able to load the binary without requiring relocation. |
269 | of EFI being able to load the binary without requiring relocation. |
270 | However, a start address of 0 makes debugging a wee bit easier |
270 | However, a start address of 0 makes debugging a wee bit easier |
271 | (great for those of us who can add, but not subtract... ;-). |
271 | (great for those of us who can add, but not subtract... ;-). |
272 | 272 | ||
273 | o The relocation related sections (.dynamic, .rel, .rela, .reloc) |
273 | o The relocation related sections (.dynamic, .rel, .rela, .reloc) |
274 | cannot be placed inside .data because some tools in the GNU |
274 | cannot be placed inside .data because some tools in the GNU |
275 | toolchain rely on the existence of these sections. |
275 | toolchain rely on the existence of these sections. |
276 | 276 | ||
277 | o Some sections in the ELF binary intentionally get dropped when |
277 | o Some sections in the ELF binary intentionally get dropped when |
278 | building the EFI binary. Particularly noteworthy are the dynamic |
278 | building the EFI binary. Particularly noteworthy are the dynamic |
279 | relocation sections for the .plabel and .reloc sections. It would |
279 | relocation sections for the .plabel and .reloc sections. It would |
280 | be _wrong_ to include these sections in the EFI binary because it |
280 | be _wrong_ to include these sections in the EFI binary because it |
281 | would result in .reloc and .plabel being relocated twice (once by |
281 | would result in .reloc and .plabel being relocated twice (once by |
282 | the EFI loader and once by the self-relocator; see below for a |
282 | the EFI loader and once by the self-relocator; see below for a |
283 | description of the latter). Specifically, only the sections |
283 | description of the latter). Specifically, only the sections |
284 | mentioned with the -j option in the final "objcopy" command are |
284 | mentioned with the -j option in the final "objcopy" command are |
285 | retained in the EFI binary (see apps/Makefile). |
285 | retained in the EFI binary (see apps/Makefile). |
286 | 286 | ||
287 | 287 | ||
288 | ** (2) Building Relocatable Binaries |
288 | ** (2) Building Relocatable Binaries |
289 | 289 | ||
290 | ELF binaries are normally linked for a fixed load address and are thus |
290 | ELF binaries are normally linked for a fixed load address and are thus |
291 | not relocatable. The only kind of ELF object that is relocatable are |
291 | not relocatable. The only kind of ELF object that is relocatable are |
292 | shared objects ("shared libraries"). However, even those objects are |
292 | shared objects ("shared libraries"). However, even those objects are |
293 | usually not completely position independent and therefore require |
293 | usually not completely position independent and therefore require |
294 | runtime relocation by the dynamic loader. For example, IA-64 binaries |
294 | runtime relocation by the dynamic loader. For example, IA-64 binaries |
295 | normally require relocation of the global offset table. |
295 | normally require relocation of the global offset table. |
296 | 296 | ||
297 | The approach to building relocatable binaries in the GNU EFI build |
297 | The approach to building relocatable binaries in the GNU EFI build |
298 | environment is to: |
298 | environment is to: |
299 | 299 | ||
300 | (a) build an ELF shared object |
300 | (a) build an ELF shared object |
301 | 301 | ||
302 | (b) link it together with a self-relocator that takes care of |
302 | (b) link it together with a self-relocator that takes care of |
303 | applying the dynamic relocations that may be present in the |
303 | applying the dynamic relocations that may be present in the |
304 | ELF shared object |
304 | ELF shared object |
305 | 305 | ||
306 | (c) convert the resulting image to an EFI binary |
306 | (c) convert the resulting image to an EFI binary |
307 | 307 | ||
308 | The self-relocator is of course architecture dependent. The x86 |
308 | The self-relocator is of course architecture dependent. The x86 |
309 | version can be found in gnuefi/reloc_ia32.c, the IA-64 version can be |
309 | version can be found in gnuefi/reloc_ia32.c, the IA-64 version can be |
310 | found in gnuefi/reloc_ia64.S. |
310 | found in gnuefi/reloc_ia64.S. |
311 | 311 | ||
312 | The self-relocator operates as follows: the startup code invokes it |
312 | The self-relocator operates as follows: the startup code invokes it |
313 | right after EFI has handed off control to the EFI binary at symbol |
313 | right after EFI has handed off control to the EFI binary at symbol |
314 | "_start". Upon activation, the self-relocator searches the .dynamic |
314 | "_start". Upon activation, the self-relocator searches the .dynamic |
315 | section (whose starting address is given by symbol _DYNAMIC) for the |
315 | section (whose starting address is given by symbol _DYNAMIC) for the |
316 | dynamic relocation information, which can be found in the DT_REL, |
316 | dynamic relocation information, which can be found in the DT_REL, |
317 | DT_RELSZ, and DT_RELENT entries of the dynamic table (DT_RELA, |
317 | DT_RELSZ, and DT_RELENT entries of the dynamic table (DT_RELA, |
318 | DT_RELASZ, and DT_RELAENT in the case of rela relocations, as is the |
318 | DT_RELASZ, and DT_RELAENT in the case of rela relocations, as is the |
319 | case for IA-64). The dynamic relocation information points to the ELF |
319 | case for IA-64). The dynamic relocation information points to the ELF |
320 | relocation table. Once this table is found, the self-relocator walks |
320 | relocation table. Once this table is found, the self-relocator walks |
321 | through it, applying each relocation one by one. Since the EFI |
321 | through it, applying each relocation one by one. Since the EFI |
322 | binaries are fully resolved shared objects, only a subset of all |
322 | binaries are fully resolved shared objects, only a subset of all |
323 | possible relocations need to be supported. Specifically, on x86 only |
323 | possible relocations need to be supported. Specifically, on x86 only |
324 | the R_386_RELATIVE relocation is needed. On IA-64, the relocations |
324 | the R_386_RELATIVE relocation is needed. On IA-64, the relocations |
325 | R_IA64_DIR64LSB, R_IA64_REL64LSB, and R_IA64_FPTR64LSB are needed. |
325 | R_IA64_DIR64LSB, R_IA64_REL64LSB, and R_IA64_FPTR64LSB are needed. |
326 | Note that the R_IA64_FPTR64LSB relocation requires access to the |
326 | Note that the R_IA64_FPTR64LSB relocation requires access to the |
327 | dynamic symbol table. This is why the .dynsym section is included in |
327 | dynamic symbol table. This is why the .dynsym section is included in |
328 | the EFI binary. Another complication is that this relocation requires |
328 | the EFI binary. Another complication is that this relocation requires |
329 | memory to hold the function descriptors (aka "procedure labels" or |
329 | memory to hold the function descriptors (aka "procedure labels" or |
330 | "plabels"). Each function descriptor uses 16 bytes of memory. The |
330 | "plabels"). Each function descriptor uses 16 bytes of memory. The |
331 | IA-64 self-relocator currently reserves a static memory area that can |
331 | IA-64 self-relocator currently reserves a static memory area that can |
332 | hold 100 of these descriptors. If the self-relocator runs out of |
332 | hold 100 of these descriptors. If the self-relocator runs out of |
333 | space, it causes the EFI binary to fail with error code 5 |
333 | space, it causes the EFI binary to fail with error code 5 |
334 | (EFI_BUFFER_TOO_SMALL). When this happens, the manifest constant |
334 | (EFI_BUFFER_TOO_SMALL). When this happens, the manifest constant |
335 | MAX_FUNCTION_DESCRIPTORS in gnuefi/reloc_ia64.S should be increased |
335 | MAX_FUNCTION_DESCRIPTORS in gnuefi/reloc_ia64.S should be increased |
336 | and the application recompiled. An easy way to count the number of |
336 | and the application recompiled. An easy way to count the number of |
337 | function descriptors required by an EFI application is to run the |
337 | function descriptors required by an EFI application is to run the |
338 | command: |
338 | command: |
339 | 339 | ||
340 | objdump --dynamic-reloc example.so | fgrep FPTR64 | wc -l |
340 | objdump --dynamic-reloc example.so | fgrep FPTR64 | wc -l |
341 | 341 | ||
342 | assuming "example" is the name of the desired EFI application. |
342 | assuming "example" is the name of the desired EFI application. |
343 | 343 | ||
344 | 344 | ||
345 | ** (3) Creating the Function Descriptor for the IA-64 EFI Binaries |
345 | ** (3) Creating the Function Descriptor for the IA-64 EFI Binaries |
346 | 346 | ||
347 | As mentioned above, the IA-64 PE32+ format assumes that the entry |
347 | As mentioned above, the IA-64 PE32+ format assumes that the entry |
348 | point of the binary is a function descriptor. A function descriptors |
348 | point of the binary is a function descriptor. A function descriptors |
349 | consists of two double words: the first one is the code entry point |
349 | consists of two double words: the first one is the code entry point |
350 | and the second is the global pointer that should be loaded before |
350 | and the second is the global pointer that should be loaded before |
351 | calling the entry point. Since the ELF toolchain doesn't know how to |
351 | calling the entry point. Since the ELF toolchain doesn't know how to |
352 | generate a function descriptor for the entry point, the startup code |
352 | generate a function descriptor for the entry point, the startup code |
353 | in gnuefi/crt0-efi-ia64.S crafts one manually by with the code: |
353 | in gnuefi/crt0-efi-ia64.S crafts one manually by with the code: |
354 | 354 | ||
355 | .section .plabel, "a" |
355 | .section .plabel, "a" |
356 | _start_plabel: |
356 | _start_plabel: |
357 | data8 _start |
357 | data8 _start |
358 | data8 __gp |
358 | data8 __gp |
359 | 359 | ||
360 | this places the procedure label for entry point _start in a section |
360 | this places the procedure label for entry point _start in a section |
361 | called ".plabel". Now, the only problem is that _start and __gp need |
361 | called ".plabel". Now, the only problem is that _start and __gp need |
362 | to be relocated _before_ EFI hands control over to the EFI binary. |
362 | to be relocated _before_ EFI hands control over to the EFI binary. |
363 | Fortunately, PE32+ defines a section called ".reloc" that can achieve |
363 | Fortunately, PE32+ defines a section called ".reloc" that can achieve |
364 | this. Thus, in addition to manually crafting the function descriptor, |
364 | this. Thus, in addition to manually crafting the function descriptor, |
365 | the startup code also crafts a ".reloc" section that has will cause |
365 | the startup code also crafts a ".reloc" section that has will cause |
366 | the EFI loader to relocate the function descriptor before handing over |
366 | the EFI loader to relocate the function descriptor before handing over |
367 | control to the EFI binary (again, see the PECOFF spec mentioned above |
367 | control to the EFI binary (again, see the PECOFF spec mentioned above |
368 | for details). |
368 | for details). |
369 | 369 | ||
370 | A final question may be why .plabel and .reloc need to go in their own |
370 | A final question may be why .plabel and .reloc need to go in their own |
371 | COFF sections. The answer is simply: we need to be able to discard |
371 | COFF sections. The answer is simply: we need to be able to discard |
372 | the relocation entries that are generated for these sections. By |
372 | the relocation entries that are generated for these sections. By |
373 | placing them in these sections, the relocations end up in sections |
373 | placing them in these sections, the relocations end up in sections |
374 | ".rela.plabel" and ".rela.reloc" which makes it easy to filter them |
374 | ".rela.plabel" and ".rela.reloc" which makes it easy to filter them |
375 | out in the filter script. Also, the ".reloc" section needs to be in |
375 | out in the filter script. Also, the ".reloc" section needs to be in |
376 | its own section so that the objcopy program can recognize it and can |
376 | its own section so that the objcopy program can recognize it and can |
377 | create the correct directory entries in the PE32+ binary. |
377 | create the correct directory entries in the PE32+ binary. |
378 | 378 | ||
379 | 379 | ||
380 | ** (4) Convenient and Portable Generation of UNICODE String Literals |
380 | ** (4) Convenient and Portable Generation of UNICODE String Literals |
381 | 381 | ||
382 | As of gnu-efi-3.0, we make use (and somewhat abuse) the gcc option |
382 | As of gnu-efi-3.0, we make use (and somewhat abuse) the gcc option |
383 | that forces wide characters (WCHAR_T) to use short integers (2 bytes) |
383 | that forces wide characters (WCHAR_T) to use short integers (2 bytes) |
384 | instead of integers (4 bytes). This way we match the Unicode character |
384 | instead of integers (4 bytes). This way we match the Unicode character |
385 | size. By abuse, we mean that we rely on the fact that the regular ASCII |
385 | size. By abuse, we mean that we rely on the fact that the regular ASCII |
386 | characters are encoded the same way between (short) wide characters |
386 | characters are encoded the same way between (short) wide characters |
387 | and Unicode and basically only use the first byte. This allows us |
387 | and Unicode and basically only use the first byte. This allows us |
388 | to just use them interchangeably. |
388 | to just use them interchangeably. |
389 | 389 | ||
390 | The gcc option to force short wide characters is : -fshort-wchar |
390 | The gcc option to force short wide characters is : -fshort-wchar |
391 | 391 | ||
392 | * * * The End * * * |
392 | * * * The End * * * |
393 | 393 |