[U-Boot] [PATCH] efi: Update README.efi to clarify build and test instructions
The doc has a misleading 'make menuconfig' when building the EFI application and payload. Clarify this and also update information on test with QEMU.
Signed-off-by: Bin Meng bmeng.cn@gmail.com ---
doc/README.efi | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-)
diff --git a/doc/README.efi b/doc/README.efi index 7c95579..e4872ed 100644 --- a/doc/README.efi +++ b/doc/README.efi @@ -49,18 +49,21 @@ Build Instructions First choose a board that has EFI support and obtain an EFI implementation for that board. It will be either 32-bit or 64-bit.
-To build U-Boot as an EFI application (32-bit EFI required), enable -CONFIG_EFI and CONFIG_EFI_APP. The efi-x86 config is set up for this. +To build U-Boot as an EFI application (32-bit EFI required), enable CONFIG_EFI +and CONFIG_EFI_APP. The efi-x86 config (efi-x86_defconfig) is set up for this.
-To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), adjust -an existing config to enable CONFIG_EFI, CONFIG_EFI_STUB and either -CONFIG_EFI_STUB_32BIT or CONFIG_EFI_STUB_64BIT. +To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), adjust an +existing config (like qemu-x86_defconfig) to enable CONFIG_EFI, CONFIG_EFI_STUB +and either CONFIG_EFI_STUB_32BIT or CONFIG_EFI_STUB_64BIT.
Then build U-Boot as normal, e.g.
+For building an EFI application, run: + make efi-x86_defconfig + make + +For building an EFI payload, run: make qemu-x86_defconfig - make menuconfig (or make xconfig if you prefer) - # change the settings as above make
You will end up with one of these files: @@ -71,8 +74,9 @@ You will end up with one of these files:
Trying it out ------------- -Qemu is an emulator and it can emulate an x86 machine. You can run the -payload with something like this: +QEMU [1] is an emulator and it can emulate an x86 machine. Please make sure +your QEMU version is 2.3.0 or above to test this. You can run the payload with +something like this:
mkdir /tmp/efi cp /path/to/u-boot*.efi /tmp/efi @@ -80,7 +84,8 @@ payload with something like this:
Add -nographic if you want to use the terminal for output. Once it starts type 'fs0:u-boot-payload.efi' to run the payload or 'fs0:u-boot-app.efi' to -run the application. 'bios.bin' is the EFI 'BIOS'. +run the application. 'bios.bin' is the EFI 'BIOS'. Check [2] to obtain a +prebuilt EFI BIOS for QEMU or you can build one from source as well.
To try it on real hardware, put u-boot-app.efi on a suitable boot medium, such as a USB stick. Then you can type something like this to start it: @@ -235,3 +240,6 @@ common/cmd_efi.c Ben Stoltz, Simon Glass Google, Inc July 2015 + +[1] http://www.qemu.org +[2] http://www.tianocore.org/ovmf/
Hi Bin,
On 14 August 2015 at 13:47, Bin Meng bmeng.cn@gmail.com wrote:
The doc has a misleading 'make menuconfig' when building the EFI application and payload. Clarify this and also update information on test with QEMU.
Signed-off-by: Bin Meng bmeng.cn@gmail.com
doc/README.efi | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-)
diff --git a/doc/README.efi b/doc/README.efi index 7c95579..e4872ed 100644 --- a/doc/README.efi +++ b/doc/README.efi @@ -49,18 +49,21 @@ Build Instructions First choose a board that has EFI support and obtain an EFI implementation for that board. It will be either 32-bit or 64-bit.
Here I would add something like:
Alternatively, you can opt for using QEMU and the OVMF, as detailed below.
-To build U-Boot as an EFI application (32-bit EFI required), enable -CONFIG_EFI and CONFIG_EFI_APP. The efi-x86 config is set up for this. +To build U-Boot as an EFI application (32-bit EFI required), enable CONFIG_EFI +and CONFIG_EFI_APP. The efi-x86 config (efi-x86_defconfig) is set up for this.
-To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), adjust -an existing config to enable CONFIG_EFI, CONFIG_EFI_STUB and either -CONFIG_EFI_STUB_32BIT or CONFIG_EFI_STUB_64BIT. +To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), adjust an +existing config (like qemu-x86_defconfig) to enable CONFIG_EFI, CONFIG_EFI_STUB +and either CONFIG_EFI_STUB_32BIT or CONFIG_EFI_STUB_64BIT.
It might also be useful to give a short explanation (or a link to a short explanation, if you know of any) of EFI application vs EFI payload.
I'm still not sure I got that right, even after consulting the EFI specs.
Then build U-Boot as normal, e.g.
+For building an EFI application, run:
- make efi-x86_defconfig
- make
Why is this one named efi-x86_defconfig, while the other is not? Could it be efi-x86-application_defconfig, or something similarly stating what sort of EFI binary it is?
+For building an EFI payload, run: make qemu-x86_defconfig
- make menuconfig (or make xconfig if you prefer)
- # change the settings as above make
It is mostly redundant, but I'd still prefer to have a reference defconfig that just works also for the payload. Maybe not one for each word size, but at least one.
You will end up with one of these files: @@ -71,8 +74,9 @@ You will end up with one of these files:
Trying it out
-Qemu is an emulator and it can emulate an x86 machine. You can run the -payload with something like this: +QEMU [1] is an emulator and it can emulate an x86 machine. Please make sure +your QEMU version is 2.3.0 or above to test this. You can run the payload with +something like this:
mkdir /tmp/efi cp /path/to/u-boot*.efi /tmp/efi@@ -80,7 +84,8 @@ payload with something like this:
Add -nographic if you want to use the terminal for output. Once it starts type 'fs0:u-boot-payload.efi'
This didn't work for me, with the Tianocore binary I had to use uppercase for the drive name, as in:
FS0:u-boot-payload.efi
to run the payload or 'fs0:u-boot-app.efi' to
-run the application. 'bios.bin' is the EFI 'BIOS'. +run the application. 'bios.bin' is the EFI 'BIOS'. Check [2] to obtain a +prebuilt EFI BIOS for QEMU or you can build one from source as well.
To try it on real hardware, put u-boot-app.efi on a suitable boot medium, such as a USB stick. Then you can type something like this to start it: @@ -235,3 +240,6 @@ common/cmd_efi.c Ben Stoltz, Simon Glass Google, Inc July 2015
+[1] http://www.qemu.org
+[2] http://www.tianocore.org/ovmf/
1.8.2.1
One more thing that I found somewhat confusing, but maybe it's just because of my very limited experience with U-Boot on x86: where is the prompt supposed to appear vs where is the logging happening?
In some cases the logging seems to go to the screen (that's what I used), but in some other cases the logging goes to a serial port. And maybe (but I could have misunderstood) it goes also to some reserved memory area (maybe inspected with an ICE/ICD tool?).
Hi Igor,
On Fri, Aug 14, 2015 at 7:46 PM, Stoppa, Igor igor.stoppa@intel.com wrote:
Hi Bin,
On 14 August 2015 at 13:47, Bin Meng bmeng.cn@gmail.com wrote:
The doc has a misleading 'make menuconfig' when building the EFI application and payload. Clarify this and also update information on test with QEMU.
Signed-off-by: Bin Meng bmeng.cn@gmail.com
doc/README.efi | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-)
diff --git a/doc/README.efi b/doc/README.efi index 7c95579..e4872ed 100644 --- a/doc/README.efi +++ b/doc/README.efi @@ -49,18 +49,21 @@ Build Instructions First choose a board that has EFI support and obtain an EFI implementation for that board. It will be either 32-bit or 64-bit.
Here I would add something like:
Alternatively, you can opt for using QEMU and the OVMF, as detailed below.
OK.
-To build U-Boot as an EFI application (32-bit EFI required), enable -CONFIG_EFI and CONFIG_EFI_APP. The efi-x86 config is set up for this. +To build U-Boot as an EFI application (32-bit EFI required), enable CONFIG_EFI +and CONFIG_EFI_APP. The efi-x86 config (efi-x86_defconfig) is set up for this.
-To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), adjust -an existing config to enable CONFIG_EFI, CONFIG_EFI_STUB and either -CONFIG_EFI_STUB_32BIT or CONFIG_EFI_STUB_64BIT. +To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), adjust an +existing config (like qemu-x86_defconfig) to enable CONFIG_EFI, CONFIG_EFI_STUB +and either CONFIG_EFI_STUB_32BIT or CONFIG_EFI_STUB_64BIT.
It might also be useful to give a short explanation (or a link to a short explanation, if you know of any) of EFI application vs EFI payload.
I'm still not sure I got that right, even after consulting the EFI specs.
It is already documented, see section "Inner workings" in the same file.
Then build U-Boot as normal, e.g.
+For building an EFI application, run:
- make efi-x86_defconfig
- make
Why is this one named efi-x86_defconfig, while the other is not? Could it be efi-x86-application_defconfig, or something similarly stating what sort of EFI binary it is?
This is the default naming convention that U-Boot uses. U-Boot see a *board*. The efi-x86 is a *board* that represents the EFI application. In the future we may add efi-arm for ARM EFI application.
+For building an EFI payload, run: make qemu-x86_defconfig
- make menuconfig (or make xconfig if you prefer)
- # change the settings as above make
It is mostly redundant, but I'd still prefer to have a reference defconfig that just works also for the payload. Maybe not one for each word size, but at least one.
See my comments in another thread.
You will end up with one of these files: @@ -71,8 +74,9 @@ You will end up with one of these files:
Trying it out
-Qemu is an emulator and it can emulate an x86 machine. You can run the -payload with something like this: +QEMU [1] is an emulator and it can emulate an x86 machine. Please make sure +your QEMU version is 2.3.0 or above to test this. You can run the payload with +something like this:
mkdir /tmp/efi cp /path/to/u-boot*.efi /tmp/efi@@ -80,7 +84,8 @@ payload with something like this:
Add -nographic if you want to use the terminal for output. Once it starts type 'fs0:u-boot-payload.efi'
This didn't work for me, with the Tianocore binary I had to use uppercase for the drive name, as in:
FS0:u-boot-payload.efi
This is probably out of this scope for this doc. I don't know if this is something special related to how the prebuilt EFI BIOS was built, but I built a BIOS from the source and it worked fine. And it even worked without 'fs0' and just type 'u-boot-payload.efi'. You probably could ask in the edk2 community.
to run the payload or 'fs0:u-boot-app.efi' to
-run the application. 'bios.bin' is the EFI 'BIOS'. +run the application. 'bios.bin' is the EFI 'BIOS'. Check [2] to obtain a +prebuilt EFI BIOS for QEMU or you can build one from source as well.
To try it on real hardware, put u-boot-app.efi on a suitable boot medium, such as a USB stick. Then you can type something like this to start it: @@ -235,3 +240,6 @@ common/cmd_efi.c Ben Stoltz, Simon Glass Google, Inc July 2015
+[1] http://www.qemu.org
+[2] http://www.tianocore.org/ovmf/
1.8.2.1
One more thing that I found somewhat confusing, but maybe it's just because of my very limited experience with U-Boot on x86: where is the prompt supposed to appear vs where is the logging happening?
I don't understand. U-Boot does not require login.
In some cases the logging seems to go to the screen (that's what I used), but in some other cases the logging goes to a serial port. And maybe (but I could have misunderstood) it goes also to some reserved memory area (maybe inspected with an ICE/ICD tool?).
--
Regards, Bin
Hi Bin,
On 14 August 2015 at 15:34, Bin Meng bmeng.cn@gmail.com wrote:
Hi Igor,
On Fri, Aug 14, 2015 at 7:46 PM, Stoppa, Igor igor.stoppa@intel.com wrote:
[...]
I'm still not sure I got that right, even after consulting the EFI specs.
It is already documented, see section "Inner workings" in the same file.
Yes, I did read it. That section is - unsurprisingly - written from the perspective of a U-Boot developer/user.
However the remaining lingering doubt is: is EFI application vs payload something that exists only from U-Boot perspective or does the EFI BIOS have this concept? The fact that I couldn't find anything about this differentiation on the EFI specs probably means that it's a concept specific to U-Boot, but it's inferred rather than stated by the docs.
[...]
This is the default naming convention that U-Boot uses. U-Boot see a *board*. The efi-x86 is a *board* that represents the EFI application. In the future we may add efi-arm for ARM EFI application.
I see, probably this ties into my previous question about payload vs app.
[...]
This is probably out of this scope for this doc. I don't know if this is something special related to how the prebuilt EFI BIOS was built, but I built a BIOS from the source and it worked fine. And it even worked without 'fs0' and just type 'u-boot-payload.efi'. You probably could ask in the edk2 community.
Ok, I didn't know either if it was an issues with the specific build I used. I just wanted to mention it.
[...]
One more thing that I found somewhat confusing, but maybe it's just because of my very limited experience with U-Boot on x86: where is the prompt supposed to appear vs where is the logging happening?
I don't understand. U-Boot does not require login.
"logging" as: printing/showing traces
In some cases the logging seems to go to the screen (that's what I used), but in some other cases the logging goes to a serial port. And maybe (but I could have misunderstood) it goes also to some reserved memory area (maybe inspected with an ICE/ICD tool?).
Hi Igor,
On Fri, Aug 14, 2015 at 8:46 PM, Stoppa, Igor igor.stoppa@intel.com wrote:
Hi Bin,
On 14 August 2015 at 15:34, Bin Meng bmeng.cn@gmail.com wrote:
Hi Igor,
On Fri, Aug 14, 2015 at 7:46 PM, Stoppa, Igor igor.stoppa@intel.com wrote:
[...]
I'm still not sure I got that right, even after consulting the EFI specs.
It is already documented, see section "Inner workings" in the same file.
Yes, I did read it. That section is - unsurprisingly - written from the perspective of a U-Boot developer/user.
Yes, they are for hackers.
However the remaining lingering doubt is: is EFI application vs payload something that exists only from U-Boot perspective or does the EFI BIOS have this concept? The fact that I couldn't find anything about this differentiation on the EFI specs probably means that it's a concept specific to U-Boot, but it's inferred rather than stated by the docs.
I did not check EFI spec, but I believe only application is mentioned on the spec. From EFI perspective, they don't have any difference. U-Boot EFI application and payload, they are actually the same application type images from EFI perspective.
[...]
This is the default naming convention that U-Boot uses. U-Boot see a *board*. The efi-x86 is a *board* that represents the EFI application. In the future we may add efi-arm for ARM EFI application.
I see, probably this ties into my previous question about payload vs app.
[...]
This is probably out of this scope for this doc. I don't know if this is something special related to how the prebuilt EFI BIOS was built, but I built a BIOS from the source and it worked fine. And it even worked without 'fs0' and just type 'u-boot-payload.efi'. You probably could ask in the edk2 community.
Ok, I didn't know either if it was an issues with the specific build I used. I just wanted to mention it.
[...]
One more thing that I found somewhat confusing, but maybe it's just because of my very limited experience with U-Boot on x86: where is the prompt supposed to appear vs where is the logging happening?
I don't understand. U-Boot does not require login.
"logging" as: printing/showing traces
Oops, I misread. Do you mean the console output from U-Boot application and payload?
In some cases the logging seems to go to the screen (that's what I used), but in some other cases the logging goes to a serial port. And maybe (but I could have misunderstood) it goes also to some reserved memory area (maybe inspected with an ICE/ICD tool?).
Regards, Bin
Hi Bin,
On 14 August 2015 at 15:54, Bin Meng bmeng.cn@gmail.com wrote:
Hi Igor,
On Fri, Aug 14, 2015 at 8:46 PM, Stoppa, Igor igor.stoppa@intel.com wrote:
[...]
Yes, I did read it. That section is - unsurprisingly - written from the perspective of a U-Boot developer/user.
Yes, they are for hackers.
Heh, nice answer, yet my observation was on the lines of:
"written from the perspective of a U-Boot developer/user vs the perspective of an EFI developer/user"
IOW it was not clear to me if the jargon EFI payload / EFI app was limited to the U-Boot world or not. Now I know that it is :-)
[...]
Oops, I misread. Do you mean the console output from U-Boot application and payload?
yes, at least in the stub.c file it is clearly visible that the console output can be routed either to the serial port or to the screen.
It might be worth mentioning under which circumstances this happen in a certain way and under which circumstances it happen in another way, if it's something that is specific to EFI.
Hi Igor,
On Fri, Aug 14, 2015 at 9:03 PM, Stoppa, Igor igor.stoppa@intel.com wrote:
Hi Bin,
On 14 August 2015 at 15:54, Bin Meng bmeng.cn@gmail.com wrote:
Hi Igor,
On Fri, Aug 14, 2015 at 8:46 PM, Stoppa, Igor igor.stoppa@intel.com wrote:
[...]
Yes, I did read it. That section is - unsurprisingly - written from the perspective of a U-Boot developer/user.
Yes, they are for hackers.
Heh, nice answer, yet my observation was on the lines of:
"written from the perspective of a U-Boot developer/user vs the perspective of an EFI developer/user"
IOW it was not clear to me if the jargon EFI payload / EFI app was limited to the U-Boot world or not. Now I know that it is :-)
[...]
Oops, I misread. Do you mean the console output from U-Boot application and payload?
yes, at least in the stub.c file it is clearly visible that the console output can be routed either to the serial port or to the screen.
At the stub phase, it is still the EFI application phase, and U-Boot uses EFI console output protocol to print messages. If you read the hacker part, it is already documented. Or maybe if you are familiar with EFI, at this stage it is still under EFI control so you may be seeing either serial or display or both. After exit boot services call, EFI no longer control the system and it is solely a U-Boot payload running so which console output depends on U-Boot driver support in that payload.
It might be worth mentioning under which circumstances this happen in a certain way and under which circumstances it happen in another way, if it's something that is specific to EFI.
Does this really matter? An example would be: when I boot Linux I may get part of the kernel output on the serial and the other part on the screen, or maybe nothing. But finally I know it's booting, that's enough. But if I want to figure out *when* this switch happens I may have to dig into the source codes. After all, it is open source and you can read it by yourself :-)
Regards, Bin
participants (2)
-
Bin Meng -
Stoppa, Igor