{"id":875,"date":"2025-04-03T15:10:21","date_gmt":"2025-04-03T13:10:21","guid":{"rendered":"https:\/\/www.codiax.se\/?post_type=kunskapsbank&p=875"},"modified":"2025-04-30T10:39:12","modified_gmt":"2025-04-30T08:39:12","slug":"booting-into-uefi-shell-2","status":"publish","type":"kunskapsbank","link":"https:\/\/www.codiax.se\/en\/knowledge-article\/booting-into-uefi-shell-2\/","title":{"rendered":"Booting into UEFI shell with GRUB"},"content":{"rendered":"\n

I recently had a need to update the UEFI (Unified Extensible Firmware Interface) firmware of an x86 module that one of our customers is using in their embedded device with Linux based on the Yocto project. The hardware manufacturer had provided us with a bunch of files for doing the update: The firmware binary, fw.bin<\/code>, a UEFI shell script, GO.nsh<\/code>, that can be called from the shell and that performs the update, a UEFI application, AfuEfix64.efi<\/code>, used by GO.nsh<\/code> to perform the actual programming, and a checksum file for verification.<\/p>\n\n\n\n

Until now I have been used to there being a built in shell in the UEFI firmware\nthat can be started during boot (commonly by pressing F7<\/code> early in the boot\nprocess), and from which a script such as GO.nsh<\/code> can be executed. But that is\nnot always the case. When there is no built in shell the UEFI shell binary needs\nto be provided at boot time, and started by the bootloader.<\/p>\n\n\n\n

\n

NOTE: An alternative way of starting the UEFI shell on boot this is most\nprobably to use the UEFI boot support and bypass GRUB entirely, but I needed a\nquick fix for this GRUB booted system.<\/p>\n<\/blockquote>\n\n\n\n

This is a short writeup of how I solved it with GRUB and a tailored USB image. I\ndid not want to spend time creating a full blown image recipe in Yocto, with a\nwic image and all, so I took a shortcut using an already existing bootable USB\nwith a FAT32 filesystem on the first partition. It looked something like this\nfrom the start<\/p>\n\n\n\n

.\n\u251c\u2500\u2500 EFI\n\u2502   \u2514\u2500\u2500 BOOT\n\u2502       \u251c\u2500\u2500 bootx64.efi\n\u2502       \u2514\u2500\u2500 grub.cfg\n\u251c\u2500\u2500 bzImage\n\u251c\u2500\u2500 initramfs-image.cpio.gz\n\u2514\u2500\u2500 microcode.cpio\n<\/code><\/pre>\n\n\n\n
For this purpose however, we do not need any Linux kernel (bzImage<\/code>), initramfs\nor microcode.cpio<\/code> files, so I removed those and kept just the .\/EFI\/BOOT<\/code>\ntree and placed the files from the hardware manufacturer on the top. The\n.\/EFI\/BOOT<\/code> tree includes the grub-efi binary, bootx64.efi<\/code>, and the GRUB\nconfiguration file. With UEFI, if there is a file \/EFI\/BOOT\/bootx64.efi<\/code> on the\npartition, and the partition is marked as bootable (active) and has some sort of\nFAT filesystem, then the bootx64.efi<\/code> will be loaded and executed on boot.<\/p>\n\n\n\n
The layout of the USB was now<\/p>\n\n\n\n
.\n\u251c\u2500\u2500 EFI\n\u2502   \u2514\u2500\u2500 BOOT\n\u2502       \u251c\u2500\u2500 bootx64.efi\n\u2502       \u2514\u2500\u2500 grub.cfg\n\u251c\u2500\u2500 AfuEfix64.efi\n\u251c\u2500\u2500 Checksum.efi\n\u251c\u2500\u2500 GO.nsh\n\u2514\u2500\u2500 fw.bin\n<\/code><\/pre>\n\n\n\n
The UEFI shell binary, Shellx64.efi<\/code><\/h2>\n\n\n\n
Next, I needed the UEFI shell binary that can be loaded by GRUB and that in its\nturn can be used to load the GO.nsh<\/code> script. The Tianocore\nproject<\/a> provides an open source implementation of\nUEFI, and while it can be built locally following the instructions on\nTianocore’s github<\/a>, I decided to just\ndownload the binary Shell.efi<\/code> file from\nhere<\/a>,\nand try it out. The file was renamed to Shellx64.efi<\/code> and copied alongsied the\nother files on the top level of the USB.<\/p>\n\n\n\n
Add chainloader command to GRUB<\/h2>\n\n\n\n
To load a file like Shellx64.efi<\/code> from GRUB, we need GRUB’s chainloader<\/code>\ncommand. Our current grub-efi build was not set up to include that command, so I\nbuilt a new one using my normal Yocto build setup. I added this line to our\nbbappend file for grub-efi, grub-efi_2.06.bbappend<\/code>. <\/p>\n\n\n\n
GRUB_BUILDIN += \"chain\" \n<\/code><\/pre>\n\n\n\n
As an alternative, this addition could have been made in e.g. local.conf<\/code> as\nGRUB_BUILDIN:pn-grub-efi += \"chain\"<\/code>.<\/p>\n\n\n\n
When the new grub-efi<\/code> had been built, the resulting file\nbuild\/tmp\/deploy\/images\/${MACHINE}\/grub-efi-bootx64.efi<\/code> was copied to the USB\nas EFI\/BOOT\/bootx64.efi<\/code>, replacing the original file.<\/p>\n\n\n\n
Modify grub.cfg<\/code> to load the UEFI shell<\/h2>\n\n\n\n
Next I modified the grub.cfg<\/code> file on the USB to contain only one menuentry<\/p>\n\n\n\n
serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1\ntimeout=3\n\nmenuentry 'Install new firmware'{\n    search --set=root --file \/Shellx64.efi\n    chainloader \/Shellx64.efi\n}\n<\/code><\/pre>\n\n\n\n
The menuentry<\/code> first issues a search for the partition containing\nShellx64.efi<\/code> and sets it to GRUB’s root such that the chainloader<\/code> on the\nnext line finds the file it needs to load.<\/p>\n\n\n\n
Booting into the UEFI shell<\/h2>\n\n\n\n
By plugging in this USB to the system and booting from it, we get into the UEFI\nshell, loaded by GRUB. To update the firmware we could do<\/p>\n\n\n\n
shell> fs0:\nfs0:> GO.nsh\n<\/code><\/pre>\n\n\n\n
Automatic firmware update on boot<\/h2>\n\n\n\n
Since we had 50+ systems that needed a firmware update, I wanted an automatic\nway to run this script directly on boot, so I renamed the script GO.nsh<\/code> to\nstartup.nsh<\/code>, such that it is started automatically by the UEFI shell, and\nmodified the contents of the script a bit, from being:<\/p>\n\n\n\n
AfuEfix64.efi fw.bin \/P \/N \/R \/X \/SHUTDOWN\n<\/code><\/pre>\n\n\n\n
to <\/p>\n\n\n\n
if exist fs0:startup.nsh then\n   fs0:\nelse\n   fs1:\nendif\n\nAfuEfix64.efi fw.bin \/P \/N \/R \/X \/SHUTDOWN\n<\/code><\/pre>\n\n\n\n
This starts by selecting the correct device fs0:<\/code> or fs1:<\/code> such that the\nAfuEfix64.efi<\/code> application and the fw.bin<\/code> files are found. It also handles\nthe case when the USB gets mapped to fs1:<\/code> instead of fs0:<\/code>, which happens\nwhen the eMMC on the system is already populated with a filesystem. This\nspecific trick works for this system, but is of course not universally useful.<\/p>\n\n\n\n
The final layout of the USB filesystem is<\/p>\n\n\n\n
.\n\u251c\u2500\u2500 EFI\n\u2502   \u2514\u2500\u2500 BOOT\n\u2502       \u251c\u2500\u2500 bootx64.efi\n\u2502       \u2514\u2500\u2500 grub.cfg\n\u251c\u2500\u2500 AfuEfix64.efi\n\u251c\u2500\u2500 Shellx64.efi\n\u251c\u2500\u2500 startup.nsh\n\u2514\u2500\u2500 fw.bin\n<\/code><\/pre>\n","protected":false},"featured_media":0,"template":"","class_list":["post-875","kunskapsbank","type-kunskapsbank","status-publish","hentry","kunskapskategori-guider"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.codiax.se\/en\/wp-json\/wp\/v2\/kunskapsbank\/875","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.codiax.se\/en\/wp-json\/wp\/v2\/kunskapsbank"}],"about":[{"href":"https:\/\/www.codiax.se\/en\/wp-json\/wp\/v2\/types\/kunskapsbank"}],"wp:attachment":[{"href":"https:\/\/www.codiax.se\/en\/wp-json\/wp\/v2\/media?parent=875"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}