Booting the image on your hardware

Image types

Depending on the configuration, Yocto creates different types of images. You can find the image files in your build directory in tmp/deploy/images. The variable IMAGE_FSTYPES can be used to set the types of images to be created.

The image files of the latest build can easily be accessed by using the links, that always point to the files most recently created. Older image files will be kept in this directory until they are deleted.

image.sdcard

This file can be used to create a bootable SD-card. It contains a boot partition (FAT) with the Linux kernel (uImage or zImage) and one or multiple device tree files (*.dtb). The second partition (EXT) contains the root file system (rootfs).

In case that the production-override is set in your local.conf, your SD-card might also contain a UBI-image to flash the system to the onboard memory and a bootloader image (u-boot.imx) to flash the bootloader.

image.tar.bz2

This file contains the compressed rootfs and can be used to load the filesystem via network after it was extracted.

image.ubi

This file is an UBI image, that can be written to an onboard flash chip.

uImage or zImage

This is the kernel image containing the linux kernel.

Using the bootloader

Upon supplying power to the hardware, the U-Boot bootloader stored in the NOR-Flash will be starting. If an SD-card containing a bootloader is available (e.g. from a Yocto *.sdcard-image) the bootloader from the SD-card will be starting.
The boot messages of the bootloader on the debug terminal will look something like this:

U-Boot 2014.04 (Sep 29 2015 - 15:17:53)

CPU:   Freescale i.MX6SOLO rev1.1 at 792 MHz
CPU:   Temperature 25 C, calibration data: 0x59e50869
Reset cause: POR
Board: MX6SEXCEET
I2C:   ready
DRAM:  1 GiB
NAND:  512 MiB
MMC:   FSL_SDHC: 0
SF: Detected EN25Q80 with page size 256 Bytes, erase size 4 KiB, total 1 MiB
Net:   Found Micrel KS8051/KS8081 PHY
FEC
Normal Boot
Hit any key to stop autoboot:  2 

After waiting for three seconds, the bootloader tries to boot the linux kernel and mount the root filesystem. To enter the bootloader commandline and change the bootloader settings, hit a key before the bootloader starts booting.

U-Boot > 

List of basic U-Boot commands:

Command Description
printenv print all variables and their values
printenv <variable> print content of <variable>
setenv <variable> <value> Set <variable> to <value>
setenv <variable> Delete <variable>
editenv <variable> Edit value of <variable>
saveenv save all variables to flash

Please note, that you can also modify the bootloader variables from within a running linux if the package u-boot-fw-utils is installed. Then you can use fw_printenv and fw_setenv the same way as you would use printenv and setenv in U-Boot.

Booting with the Serial Loader

The i.MX6 SOCs have the ability to load images and data from a host PC via USB to the internal SRAM and external DRAM.
This is mostly used in development or production environment. To use this feature the SOC has to be in serial loader mode, which means you should remove any other boot device such as an SD-card before powering the board.

Hint

Depending on the OTP-Fuses and if they were already burned, it might not be possible to put the SOC into serial loader mode anymore.
It is also possible, that the serial loader mode will not be activated until the boot from all other removable (SD-card) and non-removable (eMMC, NOR-Flash) fail.

When the SOC is in serial loader mode and you connect a Micro-USB cable to the OTG-Port of the board, your host PC should detect a new USB device.
On Linux you can check for the device with lsusb:

user@exceet:~$ lsusb | grep Freescale 
Bus 003 Device 003: ID 15a2:007d Freescale Semiconductor, Inc. 

To download and run content from your host PC on the device you can either use the official NXP/Freescale-Tool called MfgTool (latest version runs on Windows and Linux), or if you use Linux, you can use the simple commandline tool imx_usb_loader from Boundary Devices.

imx_usb_loader

To load a full system (Bootloader, Kernel, FDT, initramfs) to the RAM and start it, you can edit the configuration file mx6_usb_work.conf.
Here is an example:

mx6_qsb
#hid/bulk,[old_header,]max packet size, dcd_addr, {ram start, ram size}(repeat valid ram areas)
hid,1024,0x910000,0x10000000,128M,0x00900000,0x40000
/home/user/yocto-exceet/build-exceet-morty/tmp/deploy/images/u-boot.imx:dcd
/home/user/yocto-exceet/build-exceet-morty/tmp/deploy/images/zImage:load 0x82000000
/home/user/yocto-exceet/build-exceet-morty/tmp/deploy/images/zImage-imx6ul-testadapter.dtb:load 0x83000000
/home/user/yocto-exceet/build-exceet-morty/tmp/deploy/images/image-exceet-initramfs-production-mx6ul-testadapter.cpio.gz.u-boot:load 0x83C00000
/home/user/yocto-exceet/build-exceet-morty/tmp/deploy/images/u-boot.imx:clear_dcd,load,jump header

Then you need to start the tool (needs root privileges on most systems):

user@exceet:~/imx_usb_loader$ sudo ./imx_usb

Please read the documentation of the tool for further information about installing and additional options.

MfgTool

The MfgTool uses an XML file (ucl2.xml) for configuration.
An example:

<UCL>
  <CFG>
    <STATE name="BootStrap" dev="MX6SL" vid="15A2" pid="0061"/>
  </CFG>

  <LIST name="mx6s-exceet" desc="Load Production System">

    <!-- Load U-Boot, uImage, DTB and initramfs into RAM -->
    <CMD state="BootStrap" type="boot" body="Recovery" file ="files/u-boot-prod.imx">Loading Production U-Boot...</CMD>
    <CMD state="BootStrap" type="load" file="files/zImage" address="0x18000000"
      loadSection="OTH" setSection="OTH" HasFlashHeader="FALSE">Loading Production Kernel...</CMD>
    <CMD state="BootStrap" type="load" file="files/initramfs" address="0x18C00000"
          loadSection="OTH" setSection="OTH" HasFlashHeader="FALSE">Loading Production Initramfs...</CMD>
    <CMD state="BootStrap" type="load" file="files/imxceet-solo-s.dtb" address="0x12800000"
      loadSection="OTH" setSection="OTH" HasFlashHeader="FALSE" ifdev="MX6SL">Loading device tree...</CMD>

    <!-- Start U-Boot -->
    <CMD state="BootStrap" type="jump" >Done</CMD>
  </LIST>
</UCL>

For any further information about the tool and how it can be used, please also see the manual.

Booting from SD-Card

Creation of a bootable SD-card

To create a bootable SD-card from an image file you can use the following command (replace image.sdcard with your image filename and mmc with your SD-card device, e.g. sdc or mmcblk0). Before writing to the card, ensure that it is unmounted. If you have a Yocto build environment installed, you can find the SD-card image file inside your build directory in tmp/deploy/images/.

Danger

The usage of the dd command in combination with sudo can be dangerous. If you use wrong parameters, this might cause severe loss of data on your hard disk or other drives!

> sudo dd if=image.sdcard of=/dev/mmc bs=1M conv=sync

Booting

To boot from the SD-card, set bootcmd=run bootcmd_mmc, and check that the variable dtb points to a valid dtb-file on the SD-card.
If you want your settings to be persistent, don't forget to run saveenv.
Then you are ready to boot by running boot.

Booting via network adapter (TFTP/NFS)

In a development environment where you need to do a lot of testing while changing the kernel and rootfs, it is often helpful to have the system on your development machine and share the files via network with your target device. Please use the eth0 Ethernet on the Kontron demoboard.

In combination with the Yocto build system you can export the <builddir>/tmp/deploy/images directory via TFTP to allow the target to fetch the kernel image, devicetrees, etc. To allow the target to use a rootfs over the network, you need to export the rootfs via NFS on your development machine.

Setup TFTP on the host

To install the TFTP-Server:

user@exceet:~$ sudo apt-get install tftp-hpa

Change the TFTP-settings by changing the content of /etc/default/tftp-hpa:

TFTP_USERNAME="tftp"
TFTP_DIRECTORY="/tftproot"
TFTP_ADDRESS="[::]:69"
TFTP_OPTIONS="--secure"

Setup NFS on the host

To install the NFS-Server:

user@exceet:~$ sudo apt-get install nfs-kernel-server 

Change the NFS-settings by changing the content of /etc/exports:

/nfsroot *(rw,no_root_squash,sync,no_subtree_check)

Boot

To extract the rootfs and initialize the servers, you can use the init-remote script in yocto-exceet/scripts:

user@exceet:~$ sudo init-remote <build-dir> <image-name> <machine-name>

For example:

user@exceet:~$ sudo init-remote build-exceet image-exceet mx6sexceet

or:

user@exceet:~$ sudo init-remote build-customer image-exceet mx6scustom

In the bootloader prepend or replace the list of boot_devices with the net entry (e.g. boot_devices=net emmc ubi) and check that the variable dtb points to a valid dtb-file in the deploy directory.
If you want your settings to be persistent, don't forget to run saveenv.
Then you are ready to boot by running boot.

Booting from flash

To create a ubi-image and a bootloader that can be written to the flash memory, build an image with the production-flag set in your local.conf and create an SD-card. After booting from the SD-card run the ptool-script to flash the ubi-image from the SD-card to the NAND-flash:

user@exceet:~$ ptool flash_ubi

To write the bootloader from the SD-card to the NOR-flash:

user@exceet:~$ ptool flash_bl

To boot from the flash the following changes have to be made in the bootloader: Set bootdevices to ubi, and check that the variable dtb_fs points to a valid dtb-file in the rootfs.
If you want your settings to be persistent, don't forget to run saveenv.
Then you are ready to boot by running boot.

Login

After a successful boot you will be greeted with a login prompt. The default (and only) user in an unmodified exceet image is the root user and it has no password.

Automatically executing scripts from an USB-drive or SD-card partition after booting

In some cases it is useful to execute scripts from external drives. Therefore the package 'udev-extraconf' is needed.
The script will automatically mount all connected USB-drives and SD-card partitions to /run/media/devicename. During the booting of the system all scripts which are executable and contained in the folder exceet-init on theses devices will be processed.