14.06: improve UEFI configuration instructions

Signed-off-by: Ryan Harkin <ryan.harkin@linaro.org>

2 files changed, 344 insertions, 24 deletions

diff --git a/android/images/armv8-android-juno-lsk/HOWTO_install.txt b/android/images/armv8-android-juno-lsk/HOWTO_install.txt
index 273b468..5a4e327 100644
--- a/android/images/armv8-android-juno-lsk/HOWTO_install.txt
+++ b/android/images/armv8-android-juno-lsk/HOWTO_install.txt
@@ -97,22 +97,182 @@ After the media create tool has finished executing, remove the USB drive from yo
 
 Before you can boot the image you will need to install the latest firmware on the board. The "instructions below":#firmware provide information on how to do this.
 
-See the "UEFI wiki":https://wiki.linaro.org/ARM/UEFI#Configure_UEFI for more information on how to configure UEFI to boot disk images.
+Once you have the latest firmware installed, you will need to configure UEFI to boot the kernel from the "boot" partition of the USB stick.
 
-In general terms, you use the UEFI Boot Manager to configure the "Boot Device":
-* select USB device's boot partition after selecting option @"[1] Add Boot Device Entry"@
-* note: due to problems detecting the USB disk partitions on the first attempt, you will need to press ESC to abort adding a new entry, then select option 1 again
-* then, continue to configure UEFI, thus:
 
-bc. File path of the EFI Application or the kernel: kernel
-Has FDT support? [y/n] y
-Add an initrd: [y/n] y
-File path of the initrd: ramdisk.img
-Arguments to pass to the binary: console=ttyAMA0,115200 earlyprintk=pl011,0x7ff80000 root=/dev/ram0 verbose debug
+h2. UEFI Configuration
 
-* select option @"[4] Update FDT path"@ from the Boot Menu, choose the boot partition, then:
+The example below shows how a test system was configured.  Please note:  some of the menu option numbers may be different on your board.  In particular, the menu option used to choose the boot partition may change number over a reboot.  In the example below, the partition named "boot" was option 4.  Please be careful that you choose the correct option that corresponds to the menu options you see on your board.
 
-bc. File path of the FDT blob: juno.dtb
+Also take care that the USB partitions are showing in the menu before selecting a menu option.  There is a known bug in UEFI where the partitions on USB drives does not show the first time the menu is displayed.  To overcome this, as shown in the example below, the user should enter the menu option @"[1] Add Boot Device Entry"@, by pressing @1@ followed by the enter key.  Then, when the list display and the USB partitions are missing, please press the @ESC@ key once.  This will exit out of the current menu prompt and leave you back at the Boot Menu again.  At this point, please press 1 again to re-enter the menu option @"[1] Add Boot Device Entry"@ and continue by selecting the partition named "boot" on the USB drive.
+
+UEFI outputs to UART0 on the board.  UART0 uses 115200 baud with 8 bits and no stop bit.  Please see the  "UARTs" section on the "Getting Started tab":https://releases.linaro.org/14.06/openembedded/juno-lsk/#tabs-4 for more details on the UART configuration of the board.
+
+
+h3. Example UEFI Configuration
+
+When booting your system, after a short time, you be presented by a boot countdown from 10, thus:
+
+bc.The default boot selection will start in   8 seconds
+
+When you see this prompt, please press the enter key to interrupt the countdown.  You will then be presented with a menu, thus:
+
+bc. [1] Linux from NOR Flash
+[2] Shell
+[3] Boot Manager
+Start:
+
+Depending on the configuration of your board, the menu option called "Boot Manager" may not be option 3.  In this example, we can see that the Boot Menu is indeed option "3", so we choose it by pressing the "3" key and pressing enter.  You will then be presented with a boot menu, thus:
+
+bc. [1] Add Boot Device Entry
+[2] Update Boot Device Entry
+[3] Remove Boot Device Entry
+[4] Update FDT path
+[5] Return to main menu
+Choice:
+
+The first thing we need to do is to delete all of the existing Boot Device Entries.  Deleting a Boot Device Entry is achieved by pressing the 3 key and pressing enter:
+
+bc. [1] Linux from NOR Flash
+Delete entry:
+
+In our example, using the default config from the first time you boot the board, there is only 1 Boot Device Entry: "Linux from NOR Flash".  You must delete this entry by pressing the 1 key and pressing enter.  After this, you will be returned to the Boot Menu where you should continue by deleting *all* Boot Device Entries that are configured.
+
+Once you have done this, you should continue by creating a new Boot Device Entry by selecting option 1 from from the Boot Menu.  After selecting the menu option by pressing the 1 key folllowed by enter, you will see a list of available Boot Devices, thus:
+
+bc. [1] Add Boot Device Entry
+[2] Update Boot Device Entry
+[3] Remove Boot Device Entry
+[4] Update FDT path
+[5] Return to main menu
+Choice: 1
+[1] Firmware Volume (0 MB)
+[2] Firmware Volume (0 MB)
+[3] NOR Flash (63 MB)
+[4] VenHw(E7223039-5836-41E1-B542-D7EC736C5E59)
+[5] VenHw(02118005-9DA7-443A-92D5-781F022AEDBB)
+[6] PXE on MAC Address: 00:02:F7:00:57:DD
+[7] TFTP on MAC Address: 00:02:F7:00:57:DD
+Select the Boot Device:  
+
+As you will see in the example above, there is no partition named "boot" available to the user.  At this point, the user must press the @ESC@ key to exit the "Select the Boot Device" option and return to the Boot Menu.  From the Boot Menu, please select option 1 again.  The example below shows how this looked on our test system, your results may differ:
+
+bc. [1] Add Boot Device Entry
+[2] Update Boot Device Entry
+[3] Remove Boot Device Entry
+[4] Update FDT path
+[5] Return to main menu
+Choice: 1
+[1] Firmware Volume (4068 MB)
+[2] Firmware Volume (4068 MB)
+[3] NOR Flash (63 MB)
+[4] boot (131 MB)
+[5] sdcard (13585 MB)
+[6] VenHw(E7223039-5836-41E1-B542-D7EC736C5E59)
+[7] VenHw(02118005-9DA7-443A-92D5-781F022AEDBB)
+[8] PXE on MAC Address: 00:02:F7:00:57:DD
+[9] TFTP on MAC Address: 00:02:F7:00:57:DD
+Select the Boot Device:
+
+As you will see, the menu option @"boot"@ has now appeared, allowing us to select the partition named "boot" on the USB drive.  In the example above, the partition named "boot" is option 4.  Your system may show a different option for the partition named boot on your USB drive.  Please examine the menu and choose the appropriate option.
+
+Once you have choosen the Boot Device, you will be prompted for the configuration of that Boot Device.
+
+The first quesion will ask for the file path of the kernel, thus:
+
+bc. File path of the EFI Application or the kernel:
+
+When configuring a system to boot Android, you enter the file path of the kernel as "kernel" without the quotes and followed by the enter key, for this is the filename of the kernel in the boot partition on the USB drive.
+
+Next you will be prompted if the kernel has Flattened Device Tree support:
+
+bc. Has FDT support? [y/n]
+
+The answer is yes, so please press the "y" key followed by enter.  Next you will be asked if you wish to configure an "initrd" for your system:
+
+bc. Add an initrd: [y/n]
+
+The answer is yes, so please press the "y" key followed by enter.  Next you will be asked for the file path of the initrd on your USB drive:
+
+bc. File path of the initrd:
+
+The file is called "ramdisk.img", so please type "ramdis.img" without the quotes, followed by the enter key.  After this you will be asked to supply the arguments required to boot the kernel:
+
+bc. Arguments to pass to the binary:
+
+Please note, cope and paste does not work well over the serial terminal.  The user is adviced to type the commandline arguments by hand, character at a time, followed by the enter key.  The commandline used to boot a Linaro Android build are below:
+
+bc. console=ttyAMA0,115200 earlyprintk=pl011,0x7ff80000 root=/dev/ram0 verbose debug
+
+Finally, after entering the commandline, the final question is simply asking for a title that will appear in the Boot Menu:
+
+bc. Description for this new Entry:
+
+You may enter a simple string of alphanumberic characters use to represent the name of this Boot Device.  On our example system, we chose to type the string "Linux on USB", without the quotes, followed by pressing the enter key.
+
+After entering the description string, you will then be returned to the boot menu:
+
+bc. [1] Add Boot Device Entry
+[2] Update Boot Device Entry
+[3] Remove Boot Device Entry
+[4] Update FDT path
+[5] Return to main menu
+
+It may take a long time, perhaps over a minute for UEFI to save the Boot Device Entry.
+
+After you have configured the Boot Device Entry, next you must configure the Flattened Device Tree (FDT) path.  You do this by selecting the option "Update FDT path" by pressing the 4 key and pressing enter.  As with the Add Boot Device Entry option, next you will be presented with a list of Boot Devices that can host the FDT file.  On our test system, the list looked like this:
+
+bc. [1] Firmware Volume (4068 MB)
+[2] Firmware Volume (4068 MB)
+[3] NOR Flash (63 MB)
+[4] boot (131 MB)
+[5] sdcard (13585 MB)
+[6] VenHw(E7223039-5836-41E1-B542-D7EC736C5E59)
+[7] VenHw(02118005-9DA7-443A-92D5-781F022AEDBB)
+[8] PXE on MAC Address: 00:02:F7:00:57:DD
+[9] TFTP on MAC Address: 00:02:F7:00:57:DD
+
+Choose the option that corresponds to the partition named "boot" on your system.  In the example above, this is option 4.  Enter the option number and press the enter key.  You will then be prompted for the file path for the FDT file:
+
+bc. File path of the FDT blob:
+
+At this prompt, type the filename "juno.dtb" and press the enter key.  The system may take some time to save the configuration.  After which, you will be returned to the Boot Menu:
+
+bc. [1] Add Boot Device Entry
+[2] Update Boot Device Entry
+[3] Remove Boot Device Entry
+[4] Update FDT path
+[5] Return to main menu
+
+At this point, we have completed our configuration and we can return to the main menu by selecting option 5 "Return to main menu".  To select option 5, press the 5 key and press enter.
+
+Once you are back at the main menu, you will see that the selection of Boot Devices has now changed.  On our test system, the selection looked like this:
+
+bc. [1] Linux on USB
+[2] Shell
+[3] Boot Manager
+Start:
+
+Where option 1, "Linux on USB" was the Boot Device Entry that we created by following the instructions above.
+
+You should now choose this option to boot from your USB drive.  When booting, you will see output similar to this:
+
+bc. [1] Linux on USB
+[2] Shell
+[3] Boot Manager
+Start: 1
+   PEI    217 ms
+   DXE     48 ms
+   BDS   3086 ms
+Total Time = 3352 ms
+[    0.000000] Initializing cgroup subsys cpu
+[    0.000000] Linux version 3.10.40-04499-g1866f48 (jenkins-build@ip-10-62-41-78) (gcc version 4.9.1 20140529 (prerelease) (Linaro GCC 4.9-2014.06) ) #1 SMP Tue Jun 17 02:28:46 UTC 2014
+[    0.000000] CPU: AArch64 Processor [410fd030] revision 0
+[    0.000000] Machine: Juno
+
+One important part of the output is the Linux version, shown above as 3.10.40-04499-g1866f48.  It is critical that you ensure you are booting Linux version 3.10.40-04499-g1866f48.  If you are not, it may be that you have mis-cofigured your system and you should revise your configuration by repeating the steps above.
+
+note: it is normal for the BDS to show a excessively long time to load the images.  This is a known intermittent bug.  It did not take such a long time to load.
 
 
 h2. DS-5 Configuration Files for Juno
diff --git a/android/images/armv8-juice-juno-lsk/HOWTO_install.txt b/android/images/armv8-juice-juno-lsk/HOWTO_install.txt
index f34c5e2..b8fbad1 100644
--- a/android/images/armv8-juice-juno-lsk/HOWTO_install.txt
+++ b/android/images/armv8-juice-juno-lsk/HOWTO_install.txt
@@ -97,22 +97,182 @@ After the media create tool has finished executing, remove the USB drive from yo
 
 Before you can boot the image you will need to install the latest firmware on the board. The "instructions below":#firmware provide information on how to do this.
 
-See the "UEFI wiki":https://wiki.linaro.org/ARM/UEFI#Configure_UEFI for more information on how to configure UEFI to boot disk images.
+Once you have the latest firmware installed, you will need to configure UEFI to boot the kernel from the "boot" partition of the USB stick.
 
-In general terms, you use the UEFI Boot Manager to configure the "Boot Device":
-* select USB device's boot partition after selecting option @"[1] Add Boot Device Entry"@
-* note: due to problems detecting the USB disk partitions on the first attempt, you will need to press ESC to abort adding a new entry, then select option 1 again
-* then, continue to configure UEFI, thus:
 
-bc. File path of the EFI Application or the kernel: kernel
-Has FDT support? [y/n] y
-Add an initrd: [y/n] y
-File path of the initrd: ramdisk.img
-Arguments to pass to the binary: console=ttyAMA0,115200 earlyprintk=pl011,0x7ff80000 root=/dev/ram0 verbose debug
+h2. UEFI Configuration
 
-* select option @"[4] Update FDT path"@ from the Boot Menu, choose the boot partition, then:
+The example below shows how a test system was configured.  Please note:  some of the menu option numbers may be different on your board.  In particular, the menu option used to choose the boot partition may change number over a reboot.  In the example below, the partition named "boot" was option 4.  Please be careful that you choose the correct option that corresponds to the menu options you see on your board.
 
-bc. File path of the FDT blob: juno.dtb
+Also take care that the USB partitions are showing in the menu before selecting a menu option.  There is a known bug in UEFI where the partitions on USB drives does not show the first time the menu is displayed.  To overcome this, as shown in the example below, the user should enter the menu option @"[1] Add Boot Device Entry"@, by pressing @1@ followed by the enter key.  Then, when the list display and the USB partitions are missing, please press the @ESC@ key once.  This will exit out of the current menu prompt and leave you back at the Boot Menu again.  At this point, please press 1 again to re-enter the menu option @"[1] Add Boot Device Entry"@ and continue by selecting the partition named "boot" on the USB drive.
+
+UEFI outputs to UART0 on the board.  UART0 uses 115200 baud with 8 bits and no stop bit.  Please see the  "UARTs" section on the "Getting Started tab":https://releases.linaro.org/14.06/openembedded/juno-lsk/#tabs-4 for more details on the UART configuration of the board.
+
+
+h3. Example UEFI Configuration
+
+When booting your system, after a short time, you be presented by a boot countdown from 10, thus:
+
+bc.The default boot selection will start in   8 seconds
+
+When you see this prompt, please press the enter key to interrupt the countdown.  You will then be presented with a menu, thus:
+
+bc. [1] Linux from NOR Flash
+[2] Shell
+[3] Boot Manager
+Start:
+
+Depending on the configuration of your board, the menu option called "Boot Manager" may not be option 3.  In this example, we can see that the Boot Menu is indeed option "3", so we choose it by pressing the "3" key and pressing enter.  You will then be presented with a boot menu, thus:
+
+bc. [1] Add Boot Device Entry
+[2] Update Boot Device Entry
+[3] Remove Boot Device Entry
+[4] Update FDT path
+[5] Return to main menu
+Choice:
+
+The first thing we need to do is to delete all of the existing Boot Device Entries.  Deleting a Boot Device Entry is achieved by pressing the 3 key and pressing enter:
+
+bc. [1] Linux from NOR Flash
+Delete entry:
+
+In our example, using the default config from the first time you boot the board, there is only 1 Boot Device Entry: "Linux from NOR Flash".  You must delete this entry by pressing the 1 key and pressing enter.  After this, you will be returned to the Boot Menu where you should continue by deleting *all* Boot Device Entries that are configured.
+
+Once you have done this, you should continue by creating a new Boot Device Entry by selecting option 1 from from the Boot Menu.  After selecting the menu option by pressing the 1 key folllowed by enter, you will see a list of available Boot Devices, thus:
+
+bc. [1] Add Boot Device Entry
+[2] Update Boot Device Entry
+[3] Remove Boot Device Entry
+[4] Update FDT path
+[5] Return to main menu
+Choice: 1
+[1] Firmware Volume (0 MB)
+[2] Firmware Volume (0 MB)
+[3] NOR Flash (63 MB)
+[4] VenHw(E7223039-5836-41E1-B542-D7EC736C5E59)
+[5] VenHw(02118005-9DA7-443A-92D5-781F022AEDBB)
+[6] PXE on MAC Address: 00:02:F7:00:57:DD
+[7] TFTP on MAC Address: 00:02:F7:00:57:DD
+Select the Boot Device:  
+
+As you will see in the example above, there is no partition named "boot" available to the user.  At this point, the user must press the @ESC@ key to exit the "Select the Boot Device" option and return to the Boot Menu.  From the Boot Menu, please select option 1 again.  The example below shows how this looked on our test system, your results may differ:
+
+bc. [1] Add Boot Device Entry
+[2] Update Boot Device Entry
+[3] Remove Boot Device Entry
+[4] Update FDT path
+[5] Return to main menu
+Choice: 1
+[1] Firmware Volume (4068 MB)
+[2] Firmware Volume (4068 MB)
+[3] NOR Flash (63 MB)
+[4] boot (131 MB)
+[5] sdcard (13585 MB)
+[6] VenHw(E7223039-5836-41E1-B542-D7EC736C5E59)
+[7] VenHw(02118005-9DA7-443A-92D5-781F022AEDBB)
+[8] PXE on MAC Address: 00:02:F7:00:57:DD
+[9] TFTP on MAC Address: 00:02:F7:00:57:DD
+Select the Boot Device:
+
+As you will see, the menu option @"boot"@ has now appeared, allowing us to select the partition named "boot" on the USB drive.  In the example above, the partition named "boot" is option 4.  Your system may show a different option for the partition named boot on your USB drive.  Please examine the menu and choose the appropriate option.
+
+Once you have choosen the Boot Device, you will be prompted for the configuration of that Boot Device.
+
+The first quesion will ask for the file path of the kernel, thus:
+
+bc. File path of the EFI Application or the kernel:
+
+When configuring a system to boot Android, you enter the file path of the kernel as "kernel" without the quotes and followed by the enter key, for this is the filename of the kernel in the boot partition on the USB drive.
+
+Next you will be prompted if the kernel has Flattened Device Tree support:
+
+bc. Has FDT support? [y/n]
+
+The answer is yes, so please press the "y" key followed by enter.  Next you will be asked if you wish to configure an "initrd" for your system:
+
+bc. Add an initrd: [y/n]
+
+The answer is yes, so please press the "y" key followed by enter.  Next you will be asked for the file path of the initrd on your USB drive:
+
+bc. File path of the initrd:
+
+The file is called "ramdisk.img", so please type "ramdis.img" without the quotes, followed by the enter key.  After this you will be asked to supply the arguments required to boot the kernel:
+
+bc. Arguments to pass to the binary:
+
+Please note, cope and paste does not work well over the serial terminal.  The user is adviced to type the commandline arguments by hand, character at a time, followed by the enter key.  The commandline used to boot a Linaro Android build are below:
+
+bc. console=ttyAMA0,115200 earlyprintk=pl011,0x7ff80000 root=/dev/ram0 verbose debug
+
+Finally, after entering the commandline, the final question is simply asking for a title that will appear in the Boot Menu:
+
+bc. Description for this new Entry:
+
+You may enter a simple string of alphanumberic characters use to represent the name of this Boot Device.  On our example system, we chose to type the string "Linux on USB", without the quotes, followed by pressing the enter key.
+
+After entering the description string, you will then be returned to the boot menu:
+
+bc. [1] Add Boot Device Entry
+[2] Update Boot Device Entry
+[3] Remove Boot Device Entry
+[4] Update FDT path
+[5] Return to main menu
+
+It may take a long time, perhaps over a minute for UEFI to save the Boot Device Entry.
+
+After you have configured the Boot Device Entry, next you must configure the Flattened Device Tree (FDT) path.  You do this by selecting the option "Update FDT path" by pressing the 4 key and pressing enter.  As with the Add Boot Device Entry option, next you will be presented with a list of Boot Devices that can host the FDT file.  On our test system, the list looked like this:
+
+bc. [1] Firmware Volume (4068 MB)
+[2] Firmware Volume (4068 MB)
+[3] NOR Flash (63 MB)
+[4] boot (131 MB)
+[5] sdcard (13585 MB)
+[6] VenHw(E7223039-5836-41E1-B542-D7EC736C5E59)
+[7] VenHw(02118005-9DA7-443A-92D5-781F022AEDBB)
+[8] PXE on MAC Address: 00:02:F7:00:57:DD
+[9] TFTP on MAC Address: 00:02:F7:00:57:DD
+
+Choose the option that corresponds to the partition named "boot" on your system.  In the example above, this is option 4.  Enter the option number and press the enter key.  You will then be prompted for the file path for the FDT file:
+
+bc. File path of the FDT blob:
+
+At this prompt, type the filename "juno.dtb" and press the enter key.  The system may take some time to save the configuration.  After which, you will be returned to the Boot Menu:
+
+bc. [1] Add Boot Device Entry
+[2] Update Boot Device Entry
+[3] Remove Boot Device Entry
+[4] Update FDT path
+[5] Return to main menu
+
+At this point, we have completed our configuration and we can return to the main menu by selecting option 5 "Return to main menu".  To select option 5, press the 5 key and press enter.
+
+Once you are back at the main menu, you will see that the selection of Boot Devices has now changed.  On our test system, the selection looked like this:
+
+bc. [1] Linux on USB
+[2] Shell
+[3] Boot Manager
+Start:
+
+Where option 1, "Linux on USB" was the Boot Device Entry that we created by following the instructions above.
+
+You should now choose this option to boot from your USB drive.  When booting, you will see output similar to this:
+
+bc. [1] Linux on USB
+[2] Shell
+[3] Boot Manager
+Start: 1
+   PEI    217 ms
+   DXE     48 ms
+   BDS   3086 ms
+Total Time = 3352 ms
+[    0.000000] Initializing cgroup subsys cpu
+[    0.000000] Linux version 3.10.40-04499-g1866f48 (jenkins-build@ip-10-62-41-78) (gcc version 4.9.1 20140529 (prerelease) (Linaro GCC 4.9-2014.06) ) #1 SMP Tue Jun 17 02:28:46 UTC 2014
+[    0.000000] CPU: AArch64 Processor [410fd030] revision 0
+[    0.000000] Machine: Juno
+
+One important part of the output is the Linux version, shown above as 3.10.40-04499-g1866f48.  It is critical that you ensure you are booting Linux version 3.10.40-04499-g1866f48.  If you are not, it may be that you have mis-cofigured your system and you should revise your configuration by repeating the steps above.
+
+note: it is normal for the BDS to show a excessively long time to load the images.  This is a known intermittent bug.  It did not take such a long time to load.
 
 
 h2. DS-5 Configuration Files for Juno