View source for CL-SOM-iMX6UL: Yocto Linux: Getting started

== Introduction ==
This article provides an introduction on how to install the Debian example root filesystem image on the CompuLab CL-SOM-iMX6UL System-on-Module / Computer-on-Module NAND or eMMC internal storage devices.

== Preparation steps ==
* Obtain a PC workstation with a serial communication port.
* For networked installation you need to install a TFTP server on the host PC. For Windows machines we recommend [http://tftpd32.jounin.net/ TFTPD32] included in the Linux package for CL-SOM-iMX6UL (link below).
* Download the Linux package for CL-SOM-iMX6UL from [http://compulab.co.il/products/computer-on-modules/cl-som-imx6ul/#devres CompuLab website]. Unzip the package to a directory on your host workstation.
* All image files mentioned below can be found in the {{filename|images}} subdirectory.
* Connect the host PC to the SBC-iMX6UL base-board (connector P8) via the serial cable supplied with the evaluation kit.
* Start the terminal emulation software on your PC. Set baud rate to 115200 bps, 8 bit per frame, 1 stop bit, no parity, no flow control.
* Turn on the CL-SOM-iMX6UL evaluation system. The U-Boot boot-loader will start and you will get a command prompt.
*: {{Note|If the boot settings of your CL-SOM-iMX6UL are different than the default, you may need to press and hold '''Ctrl-C''' while turning the CL-SOM-iMX6UL on, in order to get command prompt.}}

== Boot into the installation environment (ramdisk) ==
The first step in CL-SOM-iMX6UL Linux installation is starting the installation environment (Linux kernel and Ramdisk image).
This can be done using the following media:
* [[#Using installation environment on MMC/SD card|MMC/SD card]]
* [[#Using installation environment on USB storage|USB storage device]]
* [[#Using installation environment from TFTP server|Network TFTP server]]

=== Using installation environment on MMC/SD card ===
* Copy {{filename|kernel.img}}, {{filename|imx6ul-sbc-imx6ul.dtb}}, {{filename|ramdisk.img}} and {{filename|bootscr.img}} from [http://compulab.co.il/products/computer-on-modules/cl-som-imx6ul/#devres Linux package for CL-SOM-iMX6UL] to the root directory on the first partition of the MMC/SD card. The partition can be formatted either ext2/3/4 or FAT file system.
* Insert the MMC/SD card into the SD socket (P6) on the SBC-iMX6UL.
* Use the following U-Boot commands to boot the installation environment on the CL-SOM-iMX6UL configuration:
<pre>
CL-SOM-iMX6UL # mmc dev 0
CL-SOM-iMX6UL # mmc rescan
CL-SOM-iMX6UL # load mmc 0 ${loadaddr} bootscr.img
CL-SOM-iMX6UL # source ${loadaddr}
</pre>
* Continue to the [[#Install Kernel and Debian Linux Images | Install Kernel and Debian Linux Images]] section.

=== Using installation environment on USB storage ===
* Copy {{filename|kernel.img}}, {{filename|imx6ul-sbc-imx6ul.dtb}} and {{filename|ramdisk.img}} from [http://compulab.co.il/products/computer-on-modules/cl-som-imx6ul/#devres Linux package for CL-SOM-iMX6UL] to the root directory on the first partition of the USB storage. The partition can be formatted either ext2/3/4 or FAT file system.
* Insert the USB storage into a USB port on the SBC-iMX6UL.
* Use the following U-Boot commands to boot the installation environment on a CL-SOM-iMX6UL configuration:
<pre>
CL-SOM-iMX6UL # usb start
CL-SOM-iMX6UL # load usb 0 ${loadaddr} bootscr.img
CL-SOM-iMX6UL # source ${loadaddr}
</pre>
* Use the following U-Boot commands to boot the installation environment on a CL-SOM-iMX6UL configuration:
<pre>
CL-SOM-iMX6UL # setenv fdt_file imx6ul-sbc-imx6ul.dtb
CL-SOM-iMX6UL # setenv ramdisk_addr 0x82000000
CL-SOM-iMX6UL # setenv bootargs 'root=/dev/ram0 ramdisk_size=16384 console=ttymxc2,115200'
CL-SOM-iMX6UL # usb start
CL-SOM-iMX6UL # load usb 0 ${load_addr} kernel.img && load usb 0 ${fdt_addr} ${fdt_file} && load usb 0 ${ramdisk_addr} ramdisk.img
CL-SOM-iMX6UL # bootz ${load_addr} ${ramdisk_addr} ${fdt_addr}
</pre>
* Continue to the [[#Install Kernel and Debian Linux Images | Install Kernel and Debian Linux Images]] section.

=== Using installation environment from TFTP server ===
* Connect the CL-SOM-iMX6UL Ethernet port (connector P9 marked as "CM ETHERNET" on the SBC-iMX6UL) to your local network.
* Put {{filename|'''kernel.img'''}}, {{filename|'''imx6ul-sbc-imx6ul.dtb'''}} and {{filename|'''ramdisk.img'''}} from [http://compulab.co.il/products/computer-on-modules/cl-som-imx6ul/#devres Linux package for CL-SOM-iMX6UL] to a location accessible by the TFTP server:
*: - On Windows machine: copy {{filename|'''kernel.img'''}}, {{filename|'''imx6ul-sbc-imx6ul.dtb'''}} and {{filename|'''ramdisk.img'''}} to the same folder and point the TFTP server to that folder
*: - On Linux machine: copy {{filename|'''kernel.img'''}}, {{filename|'''imx6ul-sbc-imx6ul.dtb'''}} and {{filename|'''ramdisk.img'''}} to the TFTP server root directory, usually {{filename|'''/tftpboot'''}} or {{filename|'''/tftproot'''}}.
* You can use U-Boot {{cmd|dhcp}} command to obtain an IP address or manually set {{parameter|ipaddr}} environment variable:
<pre>
CL-SOM-iMX6UL # setenv ipaddr <CL-SOM-iMX6UL ip address>
</pre>
* Set the {{parameter|serverip}} environment variable:
<pre>
CL-SOM-iMX6UL # setenv serverip <tftp server host ip address>
</pre>
* Use the following U-Boot commands to boot Linux on CL-SOM-iMX6UL:
<pre>
CL-SOM-iMX6UL # setenv fdt_file imx6ul-sbc-imx6ul.dtb
CL-SOM-iMX6UL # setenv ramdisk_addr 0x82000000
CL-SOM-iMX6UL # setenv bootargs 'root=/dev/ram0 rw ramdisk_size=16384 console=ttymxc2,115200 ip=dhcp'
CL-SOM-iMX6UL # tftpboot ${load_addr} kernel.img && tftpboot ${fdt_addr} ${fdt_file} && tftpboot ${ramdisk_addr} ramdisk.img
CL-SOM-iMX6UL # bootz ${load_addr} ${ramdisk_addr} ${fdt_addr}
</pre>
* Continue to the [[#Install Kernel and Debian Linux Images | Install Kernel and Debian Linux Images]] section.

== Install Kernel and Yocto Linux Images ==
After the ramdisk image is loaded the Linux login prompt will appear. Login as {{parameter|root}} into the system. Use {{parameter|111111}} password for login:
<pre>
compulab login: root
Password: 111111
</pre>
The next step is installing the kernel and Yocto Linux images. The following media can be used as a source for installation:
* [[#Mount the MMC/SD Card|MMC/SD Card]]
* [[#Mount a USB Storage Device|USB storage device]]
* [[#Mount an NFS drive|NFS drive]]

=== Yocto Image ===

The latest [http://compulab.co.il/products/computer-on-modules/cl-som-imx6ul/#devres Linux package for CL-SOM-iMX6UL] contain a Yocto Linux rootfs image:
* {{filename|fsl-image-gui-cl-som-imx6ul.tar.bz2}}

=== Mount an MMC/SD Card ===
* Copy the {{filename|fsl-image-gui-cl-som-imx6ul.tar.bz2}}, {{filename|imx6ul-sbc-imx6ul.dtb}}, {{filename|imx6ul-sbc-imx6ul-wilink.dtb}}, and the {{filename|zImage-cl-som-imx6ul}} from the [http://compulab.co.il/products/computer-on-modules/cl-som-imx6ul/#devres Yocto Linux package for CL-SOM-iMX6UL] to the root directory of any partition on the MMC/SD card. The partition can be formatted as either ext2/3/4 or FAT file system.
* Insert the MMC/SD card into the SD socket (P9) on the SBC-iMX6UL.
* The MMC/SD card is mounted automatically under {{filename|/media/mmcblk0p'''X'''}}. Where '''X''' is the partition number.
* If for some reason the MMC/SD card hasn't been mounted automatically, use the following mount command:
<pre>
root@compulab:~# mkdir -p /media/mmcblk0pX && mount /dev/mmcblk0pX /media/mmcblk0pX
</pre>
* Continue to the [[#Install Images | Install Images]] section.

=== Mount a USB Storage Device ===
* Copy the {{filename|fsl-image-gui-cl-som-imx6ul.tar.bz2}}, {{filename|imx6ul-sbc-imx6ul.dtb}}, {{filename|imx6ul-sbc-imx6ul-wilink.dtb}}, and the {{filename|zImage-cl-som-imx6ul}} from the [http://compulab.co.il/products/computer-on-modules/cl-som-imx6ul/#devres Yocto Linux package for CL-SOM-iMX6UL] to the root directory of any partition on the USB storage device. The partition can be formatted as either ext2/3/4 or FAT file system.
* Plug the USB storage device to the lower port on the dual USB host connector P6 of the SBC-iMX6UL.
{{Note|SBC-iMX6UL jumper {{parameter|E7}} must be open}}
* The USB device is mounted automatically under {{filename|/media/sd{{parameter|XY}}}}. Where {{parameter|X}} is the device letter and {{parameter|Y}} is the partition number.
* If for some reason the USB storage device hasn't been mounted automatically, use the following mount command:
<pre>
root@compulab:~# mkdir -p /media/sdXY && mount /dev/sdXY /media/sdXY
</pre>
* Continue to the [[#Install Images | Install Images]] section.

=== Mount an NFS drive ===
* Connect the CL-SOM-iMX6UL Ethernet port (connector P21 on the SBC-iMX6UL) to your local network.
* Copy the {{filename|fsl-image-gui-cl-som-imx6ul.tar.bz2}}, {{filename|imx6ul-sbc-imx6ul.dtb}}, {{filename|imx6ul-sbc-imx6ul-wilink.dtb}}, and the {{filename|zImage-cl-som-imx6ul}} from the [http://compulab.co.il/products/computer-on-modules/cl-som-imx6ul/#devres Linux package for CL-SOM-iMX6UL] to a directory exported through NFS.
* Obtain an IP address for the CL-SOM-iMX6UL:
** Using DHCP:<pre>root@compulab:~# ifup `basename /sys/devices/platform/enet.0/net/eth?`</pre>
** If you do not have a DHCP server, you can set a static IP address using {{cmd|ifconfig}}:<pre>root@compulab:~# ifconfig `basename /sys/devices/platform/enet.0/net/eth?` <ip address></pre>
* Mount the NFS share containing the {{filename|'''zImage-cl-som-imx6ul'''}} and the {{filename|'''fsl-image-gui-cl-som-imx6ul.tar.bz2'''}} files:
<pre>
root@compulab:~# mount -o nolock <host ip>:/path/to/nfs/share /mnt/net
</pre>
* Continue to [[#Install Images | Install Images]] section.

=== Install Images ===
* In this subsection the term {{filename|/mount/point}} can be:
** {{filename|/mnt/net}} if NFS is used
** {{filename|/media/mmcblk0pX}} if an MMC/SD card is used, where X is the partition number.
** {{filename|/media/sdXY}} if USB storage is used, where X is the USB drive letter and Y is the partition number.
Once the ramdisk image is loaded and the media containing the CL-SOM-iMX6UL Kernel and Yocto Linux images is mounted, the installation can be done on:
* [[#Install on the NAND flash|NAND flash]]
* [[#Install on MMC/SD or eMMC|MMC/SD or eMMC]]
==== Install on the NAND flash ====
{{Warning|Required media size is at least '''1G'''.<br>Make sure that the nand device size meets these requirements}}

* In this subsection the term {{filename|/mount/point}} can be:
** {{filename|/mnt/net}} if NFS is used
** {{filename|/media/mmcblk0pX}} if an MMC/SD card is used, where X is the partition number.
** {{filename|/media/sdXY}} if a USB storage is used, where X is the USB drive letter and Y is the partition number.
* Select a correct device tree file that meets the configuration requirements:
:* MMC
:<pre> root@compulab:~# export fdt_file=imx6ul-sbc-imx6ul.dtb
</pre>
:* WiFi
:<pre> root@compulab:~# export fdt_file=imx6ul-sbc-imx6ul-wifi.dtb
</pre>
* Format the NAND flash kernel partition and write the kernel image onto it:
<pre>
root@compulab:~# flash_erase /dev/mtd3 0 0
root@compulab:~# nandwrite -p /dev/mtd3 /mount/point/zImage-cl-som-imx6ul
root@compulab:~# nandwrite -p /dev/mtd3 -s 0x780000 /mount/point/${fdt_file}
</pre>
* Format the NAND flash root filesystem partition:
<pre>
root@compulab:~# ubiformat /dev/mtd4
</pre>
* Attach the NAND flash root filesystem partition:
<pre>
root@compulab:~# ubiattach -m 4 -d 0
</pre>
* Create a ubi volume and name it "rootfs":
<pre>
root@compulab:~# ubimkvol /dev/ubi0 -m -N rootfs
</pre>
* Mount the ubi volume:
<pre>
root@compulab:~# mkdir -p /media/rootfs && mount -t ubifs ubi0:rootfs /media/rootfs
</pre>
* Extract the content of {{filename|fsl-image-gui-cl-som-imx6ul.tar.bz2}} onto the /media/rootfs:
<pre>
root@compulab:~# tar -xvpjf /mount/point/fsl-image-gui-cl-som-imx6ul.tar.bz2 -C /media/rootfs && sync
</pre>
* Unmount the ubi volume:
<pre>
root@compulab:~# umount /media/rootfs
</pre>
* Continue to the [[#After Installation | After Installation]] section.

==== Install on MMC/SD or eMMC ====
{{Note|The below procedure will work on an empty MMC device only.<br>If you have already used the MMC device, please delete all the partitions before proceeding.}}
* Define an environment variable that describes an MMC/SD device:
'''MMC/SD'''
<pre>
root@compulab:~# export TARGET_DEVICE=mmcblk0
</pre>
'''MMC/SD on a Linux host'''
{{Note|MMC/SD is a removable device.<br>Thus a Linux host can be used in order to deploy the Kernel and the Yocto Linux rootfs on it.<br>In this case it is up to the user to figure out what the MMC/SD card device is.<br>
For instance it can be '''/dev/sdg'''}}
<pre>
root@compulab:~# export TARGET_DEVICE=sdg
</pre>
'''eMMC'''
<pre>
root@compulab:~# export TARGET_DEVICE=mmcblk1
</pre>
* Clean up the on the '''TARGET_DEVICE''':
<pre>
root@compulab:~# dd if=/dev/zero of=/dev/${TARGET_DEVICE} bs=1M count=1
root@compulab:~# hdparm -z /dev/${TARGET_DEVICE}
</pre>
* Create two partitions for the Linux kernel (FAT32 100M) and root file system (EXT4 the rest of the disk) on the MMC device:
<pre>
root@compulab:~# echo -e "n\np\n1\n\n+100M\na\n1\nt\nc\nn\np\n2\n\n\nw\neof\n" | fdisk /dev/${TARGET_DEVICE}
</pre>
* Adjust the '''TARGET_DEVICE''' name:
<pre>
root@compulab:~# TARGET_DEVICE=$(awk -v device=${TARGET_DEVICE} 'BEGIN {if (device~/mmc/) {part="p"}; print device part}')
</pre>
* Format the first partition with FAT32 file system:
<pre>
root@compulab:~# mkfs.vfat -n boot /dev/${TARGET_DEVICE}1
</pre>
* Format the second partition with EXT4 file system:
<pre>
root@compulab:~# mkfs.ext4 -L rootfs /dev/${TARGET_DEVICE}2
</pre>
* Mount both partitions:
<pre>
root@compulab:~# mkdir -p /media/boot && mount /dev/${TARGET_DEVICE}1 /media/boot
root@compulab:~# mkdir -p /media/rootfs && mount /dev/${TARGET_DEVICE}2 /media/rootfs
</pre>
* Copy {{filename|zImage-cl-som-imx6ul}}, {{filename|imx6ul-sbc-imx6ul.dtb}} and {{filename|imx6ul-sbc-imx6ul-wilink.dtb}} to the first (FAT) partition:
<pre>
root@compulab:~# cp /mount/point/zImage-cl-som-imx6ul /mount/point/imx6ul*.dtb /media/boot && sync
</pre>
* Extract the content of {{filename|fsl-image-gui-cl-som-imx6ul.tar.bz2}} onto the second partition:
<pre>
root@compulab:~# tar --numeric-owner -xvpjf /mount/point/fsl-image-gui-cl-som-imx6ul.tar.bz2 -C /media/rootfs && sync
</pre>
* Unmount both partitions:
<pre>
root@compulab:~# umount /dev/${TARGET_DEVICE}1
root@compulab:~# umount /dev/${TARGET_DEVICE}2
</pre>
* Continue to the [[#After Installation | After Installation]] section.

== After Installation ==
{{Note|If the boot settings of the CL-SOM-iMX6UL are different than default, you may need to press and hold '''Ctrl-C''' while turning the CL-SOM-iMX6UL on, in order to get command prompt.}}

== Boot Environment ==
=== Common Environment Variables ===
<pre>
CL-SOM-iMX6UL # setenv bootdelay 3
CL-SOM-iMX6UL # setenv image zImage-cl-som-imx6ul
</pre>

=== Configuration Dependent Environment Variables ===
CL-SOM-iMX6UL makes use of the same interface for the first MMC and a WiFi.
These devices can't be used simultaneously, thus two different device tree files are provided.
{{Warning|In case that the bootable device is '''mmc 0''', then {{filename|'''imx6ul-sbc-imx6ul.dtb'''}} must be used.}}
* MMC
<pre>
CL-SOM-iMX6UL # setenv fdt_file imx6ul-sbc-imx6ul.dtb
</pre>
* WiFi
<pre>
CL-SOM-iMX6UL # setenv fdt_file imx6ul-sbc-imx6ul-wilink.dtb
</pre>

==== Display Options ====
SBC-iMX6UL has an option to connect either an LCD or a DVI display.<br>

Below are examples that show how to change the boot environment in order to set the correct interface
timing and geometry and work with either an LCD or a DVI display separately.

* DVI display enable function:
<pre>
CL-SOM-iMX6UL # setenv dvi+ 'fdt rm lcdif/display/display-timings/lcd'
</pre>
* LCD display enable function:
<pre>
CL-SOM-iMX6UL # setenv lcd+ 'fdt rm lcdif/display/display-timings/dvi'
</pre>

==== Storage Device Options ====
SBC-iMX6UL has an option to use either an eMMC or a NAND as a storage device.<br>
Both devices make use of the same SoC pads. As a result these device can't work simultaneously.
Device tree modification allows using one of these devices.
* NAND enable function:
<pre>
CL-SOM-iMX6UL # setenv nand+ 'fdt addr ${fdt_addr}; fdt set gpmi status "okay"; fdt set mmc1  status "disabled"'
</pre>
* eMMC enable function:
<pre>
CL-SOM-iMX6UL # setenv emmc+ 'fdt addr ${fdt_addr}; fdt set gpmi status "disabled"; fdt set mmc1  status "okay"'
</pre>

=== NAND flash ===
* Kernel and device tree loaders:
<pre>
CL-SOM-iMX6UL # setenv loadimage 'nand read ${loadaddr} 0 800000'
CL-SOM-iMX6UL # setenv loadfdt 'nand read ${fdt_addr} 780000 10000'
</pre>
* Set the {{parameter|bootargs}} environment variable:
<pre>
CM-FX6 # setenv bootargs 'console=ttymxc2,115200 root=ubi0:rootfs rw rootfstype=ubifs ubi.mtd=rootfs ip=dhcp'
</pre>

=== MMC/SD or eMMC ===
* {{parameter|mmcdev}} and {{parameter|fdt_file}} environment variables:
'''MMC'''
<pre>
CL-SOM-iMX6UL # setenv mmcdev 0
CL-SOM-iMX6UL # setenv fdt_file imx6ul-sbc-imx6ul.dtb
</pre>
'''eMMC'''
<pre>
CL-SOM-iMX6UL # setenv mmcdev 1
CL-SOM-iMX6UL # setenv fdt_file imx6ul-sbc-imx6ul-wilink.dtb
</pre>
* {{parameter|mmcroot}} environment variable:
<pre>
CL-SOM-iMX6UL # setenv mmcroot "/dev/mmcblk${mmcdev}p2 rootwait rw"
</pre>
* Kernel and device tree loaders:
<pre>
CL-SOM-iMX6UL # setenv loadimage 'load mmc ${mmcdev}:${mmcpart} ${loadaddr} ${image}'
CL-SOM-iMX6UL # setenv loadfdt 'load mmc ${mmcdev}:${mmcpart} ${fdt_addr} ${fdt_file}'
</pre>
* {{parameter|bootargs}} environment variable:
<pre>
CL-SOM-iMX6UL # setenv bootargs "console=ttymxc2,115200 root=${mmcroot} ip=dhcp"
</pre>

=== Boot command ===
* Default boot command:
<pre>
CL-SOM-iMX6UL # setenv bootcmd 'run loadimage; run loadfdt; bootz ${loadaddr} - ${fdt_addr}'
</pre>
* NAND boot command:
<pre>
CL-SOM-iMX6UL # setenv bootcmd 'run loadimage; run loadfdt; run nand+; bootz ${loadaddr} - ${fdt_addr}'
</pre>
{{Note|Make use of either {{parameter|dvi+}} or {{parameter|lcd+}} function depends on a desire display type}}
* DVI enabled boot command:
<pre>
CL-SOM-iMX6UL # setenv bootcmd 'run loadimage; run loadfdt; run dvi+; bootz ${loadaddr} - ${fdt_addr}'
</pre>
* LCD enabled boot command:
<pre>
CL-SOM-iMX6UL # setenv bootcmd 'run loadimage; run loadfdt; run lcd+; bootz ${loadaddr} - ${fdt_addr}'
</pre>
* To boot Linux, type:
<pre>
CL-SOM-iMX6UL # saveenv
CL-SOM-iMX6UL # boot
</pre>

== See also ==
* [[CL-SOM-iMX6UL: Linux: Debian]]
* [[CL-SOM-iMX6UL: Linux: Kernel]]
* [[Linux Development for ARM modules]]

[[Category:Linux]]
[[Category:CL-SOM-iMX6UL]]