path: root/members/arm/openembedded/juno-lsk/INSTALL.textile

h2. License

The use of Juno software is subject to the terms of the Juno "End User License Agreement":https://releases.linaro.org/15.03/members/arm/openembedded/juno-lsk/#tabs-5.

h2. Installation

Linaro OpenEmbedded releases are made up of the following components.

| *.img.gz | pre-built images for minimal and LAMP root filesystems |
| hwpack_*.tar.gz | hardware pack |
| linaro-image-*.rootfs.tar.gz | a choice of Root file system (RootFS) images |
| Image | kernel used by UEFI |
| juno_bl1.bin | ARM Trused Firmware BL1 binary |
| juno_fip.bin | ARM Trused Firmware Firmware Image Package (FIP) binary |
| juno.dtb | Device Tree Binary |

Other files such as *.manifest, *.txt and *.html provide information such as package contents or MD5SUMs about the files they share a common filename with.

Linaro OpenEmbedded images are made up of two components. The "Hardware Pack":https://wiki.linaro.org/HardwarePacks, which contains the kernel, boot loader and/or Device Tree blob and a Root file system (RootFS) of your choice to generate an image.

Linaro provides two methods for installing Linaro binary builds:

# Using a pre-built image, which you can download
# Assembling your own image using provided components

h2. Pre-Installation Steps

Before any installation begins, it is important that you ensure your board has the latest "firmware":#firmware installed. Please see "Juno Board Recovery Image and MCC firmware update":#firmware below for the latest updates and installation instructions.  We always recommend that users install the latest version available, which at the time of release is 0.10.1.

h2. Using pre-built image

h3. Prerequisites

* Ubuntu 12.04 64 bit or newer on your desktop PC ("www.ubuntu.com":http://www.ubuntu.com)
* 4GB USB drive or larger
* Latest firmware installed onto the board. Please see "Juno Board Recovery Image and MCC firmware update":#firmware section below
* This release pre-built image, which you can download from the above list of artifacts

h3. Installation Steps

* Unzip the downloaded pre-built image
* Insert USB drive into your PC and note the assigned @'/dev/sdX'@

bc. dmesg
DRIVE=/dev/sdX # USB drive found from dmesg above

* Unmount all partitions on the drive
** If you do not unmount all of the USB drive's partitions, you run the risk that the image will not be created successfully.
* Write the image to the drive

bc. gunzip *minimal*.img.gz
sudo dd if=*minimal*.img of=$DRIVE

Replace @*minimal*.img.gz@ with the full filename of the prebuilt image you are attempting to write to the disk.

After you have created the disk image and before you remove the USB drive from your system, you should make sure you wait for all writes to the USB drive to complete.

The following commands may help with this:

bc. $ sync
$ sudo eject $DRIVE

You should also ensure that you have written the image to the USB drive correctly.  To do this, after running the eject command, physically remove the USB drive from the system and re-connect the USB drive again.  You must unmount all partitions on the USB drive at this point.  Note, due to disconnecting and reconnecting the drive, the device path /dev/sdX may have changed.  You should check the @dmesg@ output again to ensure that you know the correct path of your USB drive.

Once you are ready, run the following commands:

bc. $ sudo cmp /dev/sdX *minimal*.img
$ sync
$ sudo eject /dev/sdX

Replace @*minimal*.img.gz@ with the full filename of the prebuilt image you are attempting to write to the disk.

When you are confident that the image was created successfully, skip down to the section "Booting the image".

*Note:* Windows users may use the "Image Writer for Windows":https://launchpad.net/win32-image-writer/+download

<hr>

h2. Building a custom image using pre-built components

Sometimes, you may wish to build your own custom image for your board. Perhaps you wish to use a more recent snapshot of the "hardware pack":https://wiki.linaro.org/HardwarePacks or take the latest Android build. Whatever the reason, you will want to use the "Linaro Image Tools":https://wiki.linaro.org/Linaro-Image-Tools to create a custom image.

Using components to generate the image will yield the same functionality found in the pre-built image of the same release.

h3. Prerequisites

* Ubuntu 12.04 64 bit or newer on your desktop PC, which you can download from "www.ubuntu.com":http://www.ubuntu.com
* Download Artifacts from above
* Get "Linaro image tools":https://wiki.linaro.org/Linaro-Image-Tools. There are multiple ways you can get the latest Linaro Image Tools:

** Method 1: Install them from the Linaro Image Tools "PPA":https://launchpad.net/~linaro-maintainers/+archive/tools

bc. sudo add-apt-repository ppa:linaro-maintainers/tools
sudo apt-get update
sudo apt-get install linaro-image-tools

** Method 2: Building from source

bc. wget http://releases.linaro.org/14.12/components/platform/linaro-image-tools/linaro-image-tools-2014.12.tar.gz

* Insert the USB drive and note the assigned @'/dev/sdX'@

bc. dmesg | less

Look for a line that looks like the following at the end of the log

@[288582.790722] sdc: sdc1 sdc2 sdc3 sdc4 <sdc5 sdc6 >@

*WARNING:* In the next step, make sure you use @/dev/"whatever you see above"@. *You can erase your hard drive* with the wrong parameter.

* Create media

bc. sudo linaro-media-create --mmc /dev/sdX --dev juno --hwpack <hwpack filename> --binary <rootfs filename>

After you have created the disk image and before you remove the USB drive from your system, you should make sure you wait for all writes to the USB drive to complete.

The following commands may help with this:

bc. $ sync
$ sudo eject /dev/sdX

Where /dev/sdX is the device node for the USB drive as discovered in the instructions above.


h2. Booting the image

After the media create tool has finished executing, remove the USB drive from your PC and insert it into the board.

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.

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.  See the steps directly below for instructions on how to configure UEFI.


h2. UEFI Configuration

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.

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/15.03/members/arm/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  10 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] Reorder Boot Device Entries
[5] Update FDT path
[6] Set Boot Timeout
[7] 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] Reorder Boot Device Entries
[5] Update FDT path
[6] Set Boot Timeout
[7] 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:

At this point you select the second of the "Firmware Volume" options from the list.  In the example above, this is option 2, so press the 2 key and press enter:

bc. File path of the EFI Application or the kernel: Shell.efi
Is your application an OS loader? [y/n] y
Arguments to pass to the EFI Application: 
Description for this new Entry: Run Shell on boot

Once the new entry is saved, you return to the main menu by pressing the 7 key followed by enter:

bc. [1] Add Boot Device Entry
[2] Update Boot Device Entry
[3] Remove Boot Device Entry
[4] Reorder Boot Device Entries
[5] Update FDT path
[6] Set Boot Timeout
[7] Return to main menu
Choice:7

From the main menu, you select option 1 to run the EFI Shell:

bc. [1] Run Shell on boot
[2] Shell
[3] Boot Manager
Choice:1

Once the EFI Shell is running, you will see a countdown.  Press the ESC key to abort this countdown.  Then, at the "Shell>" prompt, you can launch the kernel from the commandline, by typing the following command:

bc. Image dtb=juno/juno.dtb console=ttyAMA0,115200 rootwait root=/dev/sda2

You should see output similar to the following:

bc. EFI stub: Booting Linux Kernel...
[    0.000000] Initializing cgroup subsys cpu
[    0.000000] Linux version 3.10.0-1-linaro-lt-vexpress64 (buildslave@x86-64-07) (gcc version 4.9.2 20140904 (prerelease) (crosstool-NG linaro-1.13.1-4.9-2014.09 - Linaro GCC 4.9-2014.09) ) #1ubuntu1~ci+150324082033 SMP Tue Mar 24 08:21:16 UTC 2015
[    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.  It is critical that you ensure you are booting Linux version 3.10 and not 3.15 that comes installed with the ARM Firmware images.  If you are not, it may be that you have mis-configured your system and you should revise your configuration by repeating the steps above.


h2. Automating the EFI Shell boot command

You can automate EFI Shell to boot the kernel on your USB stick.

To do this, you create a file in the boot partition of your disk image called /boot/EFI/startup.nsh.  This is an EFI Shell script where you can place the command you use to launch the kernel.  For example, I inserted my USB stick into my host Ubuntu maching, mounted the boot partition and did the following:

bc.  mkdir -p <mount point of boot partition>/EFI/boot
echo "Image dtb=juno/juno.dtb console=ttyAMA0,115200 rootwait root=/dev/sda2" > <mount point of boot partition>/EFI/boot/startup.nsh

Then I unmounted the boot partition and inserted the USB drive into the Juno board.  From this point on, the board will boot directly into the kernel without intervention from the user.


h2. Restoring the default UEFI configuration

If you wish to restore UEFI to a clean default configuration:

1.  Start the board into the "ARM V2M-Juno Boot loader". Either:

* Turn on the power.
* If the board was already powered on, press the black HW RESET button.

The bootloader is accessible on the UART0 port (the top UART port on the back panel). The UART settings are 115200 bauds, 8 bits data, no parity, 1 bit for stop.

2.  Run the following commands:

bc. Cmd> flash
Flash> areas
Base      Area Size Blocks Block Size
----      --------- ------ ----------
0x08000000    65280K    255      256K
0x0BFC0000      256K      4        64K
Flash> eraserange 0x0BFC0000
Erasing Flash


h2. DS-5 Configuration Files for Juno

As an optional step, you may wish to install DS-5 configuration files that will allow you to debug Juno. The procedure is as follows:

1.      Extract the "DS-5 config files":https://wiki.linaro.org/ARM/Juno?action=AttachFile&do=get&target=DS-5_config.zip anywhere on your host PC.

2.      Start DS-5 and select &quot;Preferences&quot; from the &quot;Window&quot; menu.

3.      In the window that opens, expand the &quot;DS-5&quot; heading and select &quot;Configuration Database&quot;

4.      In the dialogue that opens, fill in:

&nbsp;&nbsp;a.    Name, which can be any string you like e.g. &quot;Juno&quot;.

&nbsp;&nbsp;b.    Location, which must be the directory that you extracted the DS-5 config files to. Note this is not the &quot;boards&quot; directory, but the parent directory that now contains &quot;boards&quot;.

5.      Click Ok to close the dialogue

6.      Back in the &quot;Configuration Database&quot; screen, click on &quot;Rebuild database&quot; then click Ok.

 

h2(#firmware). Firmware update

This section describes how to update the firmware on the Juno board.

The configuration of the Juno Development Platform board is determined by a set of files stored on a flash memory device on the board.  The flash memory can be accessed via a USB-B socket on the rear panel of the board.  When connected to a host computer, the flash memory will appear as a USB mass storage device with a FAT16 filesystem.  The files in this filesystem are edited to control the configuration of the board.

The configuration of the Juno Development Platform board can be returned to factory default by extracting the Juno board recovery image onto the flash memory device, replacing any files already in the flash memory.

To install firmware images that you have built yourself, the procedure is the same except that you will overwrite the contents of the /SOFTWARE/ directory with your own images.

To update the MCC firmware only, the procedure is the same except that the MCC firmware update bundle will contain only a subset of the files contained in the full recovery image.

<br>

To carry out a system recovery, update the MCC firmware, or install your own custom firmware images, follow these steps:

1.      Connect a serial terminal to the top 9-pin UART0 connector on the rear panel (115200 baud, 8, n, 1).

2.      Connect a USB cable between the USB-B connector on the rear panel and a USB port of your host computer.

3.      Connect the 12 volt power supply to the board.

The serial terminal will show the command prompt Cmd>

4.      At the Cmd> prompt on the serial terminal, issue the command usb_on

bc. Cmd> usb_on

The configuration flash memory should now be visible on the host computer as a mass storage device.

5.      Save to the host PC any of the existing files in the configuration flash memory that you wish to retain for future use.

6.      If you wish to update one or more of the firmware components then skip to step 7. Otherwise, for a full system recovery, format the configuration flash memory (FAT16).

7.      Extract the board recovery image ("board_recovery_image.tar.bz2":https://git.linaro.org/arm/vexpress-firmware.git/blob/5df1188de898f9eb44b9d8ed45408e6fe95fc8ba:/board_recovery_image.tar.bz2) to the root directory of the configuration flash memory, preserving the directory structure.

8.      If you are performing a system recovery or installing an update from ARM then skip to step 9. Otherwise if you wish to install firmware images that you have "built yourself":https://releases.linaro.org/15.03/members/arm/openembedded/juno-lsk/#tabs-3 then delete the bl1.bin and fip.bin from the /SOFTWARE/ directory in the configuration flash memory, and copy your own bl1.bin and fip.bin images into that directory to replace them.

9.      Safely eject the mass storage device, giving it time to write the files to the internal storage.

10.      Press the red ON/OFF button on the rear panel of the board and wait for reprogramming to complete.

The board will load the default configuration and boot up.