NXP Semiconductors
User's Guide
Document Number: IMXLUG
Rev. L4.1.15_2.1.0-ga, 05/2017
i.MX Linux® User's Guide
Contents
1
2
3
4
5
6
7
8
9
About This Book............................. ....................... 1
Introduction.............................................................3
Basic Terminal Setup.............................................. 3
Booting Linux OS......................... ..........................4
Enabling Solo Emulation...................................... 27
Power Management...............................................27
Multimedia............................ ............................... 29
Graphics.................................................................40
Connectivity........................... .............................. 43
10
Revision History................................................... 43
1 About This Book
This document describes how to build and install the i.MX
Linux® OS BSP, where BSP stands for Board Support
Package, on the i.MX platform. It also covers special i.MX
features and how to use them.
This document provides the steps to run the i.MX platform,
including board DIP switch settings, and instructions on
configuring and using the U-Boot bootloader.
The later chapters describe how to use some i.MX special
features when running the Linux OS kernel.
Features covered in this guide may be specific to particular
boards or SOCs. For the capabilities of a particular board or
SOC, see the i.MX Linux® Release Notes (IMXLXRN).
1.1 Audience
This document is intended for software, hardware, and system
engineers who are planning to use the product, and for anyone
who wants to understand more about the product.
1.2 Conventions
This document uses the following conventions:
About This Book
• Courier New font: This font is used to identify commands, explicit command parameters, code examples,
expressions, data types, and directives.
1.3 Supported hardware SoCs and boards
These are the systems covered in this guide:
• i.MX 6Quad SABRE-SD Board and Platform
• i.MX 6DualLite SABRE-SD Platform
• i.MX 6Quad SABRE-AI Platform
• i.MX 6DualLite SABRE-AI Platform
• i.MX 6SoloLite EVK
• i.MX 6SLL EVK
• i.MX 6SoloX SABRE-SD Platform
• i.MX 6SoloX SABRE-AI Platform
• i.MX 7Dual SABRE-SD platform
• i.MX 6QuadPlus SABRE-AI platform
• i.MX 6QuadPlus SABRE-SD platform
• i.MX 6UltraLite EVK platform
• i.MX 6ULL EVK platform
Some abbreviations are used in places in this document.
• SABRE-SD refers to the i.MX 6Quad SABRE-SD, i.MX 6DualLite SABRE-SD, i.MX 6QuadPlus SABRE-SD, and
i.MX 7Dual SABRE-SD boards.
• SABRE-AI refers to the i.MX 6Quad SABRE-AI, i.MX 6DualLite SABRE-AI, and i.MX 6QuadPlus SABRE-AI
boards.
• SoloLite refers to the i.MX 6SoloLite board.
• 6SLL refers to the i.MX 6SLL board.
• SoloX or SX refers to the i.MX 6SoloX SABRE-SD and SABRE-AI boards.
• UL refers to the i.MX 6UltraLite board
• ULL refers to the i.MX 6ULL board
1.4 References
This release includes the following references and additional information.
• i.MX Linux® Release Notes (IMXLXRN) - Provides the release information.
• i.MX Linux® User's Guide (IMXLUG) - Contains the information on installing U-Boot and Linux OS and using i.MX-
specific features.
• i.MX Yocto Project User's Guide (IMXLXYOCTOUG) - Contains the instructions for setting up and building Linux
OS in the Yocto Project.
• i.MX Linux® Reference Manual (IMXLXRM) - Contains the information on Linux drivers for i.MX.
• i.MX 6 Graphics User's Guide (IMX6GRAPHICUG) - Describes the graphics used.
• i.MX BSP Porting Guide (IMXXBSPPG) - Contains the instructions on porting the BSP to a new board.
• i.MX VPU Application Programming Interface Linux® Reference Manual (IMXVPUAPI) - Provides the reference
information on the VPU API.
The quick start guides contain basic information on the board and setting it up. They are on the NXP website.
• SABRE Platform Quick Start Guide (IMX6QSDPQSG)
• SABRE Board Quick Start Guide (IMX6QSDBQSG)
• i.MX 6UltraLite EVK Quick Start Guide (IMX6ULTRALITEQSG)
2
NXP Semiconductors
i.MX Linux® User's Guide, Rev. L4.1.15_2.1.0-ga, 05/2017
Introduction
• i.MX 6ULL EVK Quick Start Guide (IMX6ULLQSG)
• SABRE Automotive Infotainment Quick Start Guide (IMX6SABREINFOQSG)
• i.MX 6SoloLite Evaluation Kit Quick Start Guide (IMX6SLEVKQSG)
Documentation is available online at nxp.com.
• i.MX 6 information is at nxp.com/iMX6series
• i.MX SABRE information is at nxp.com/imxSABRE
• i.MX 6SoloLite EVK information is at nxp.com/6SLEVK
• i.MX 6SLL EVK information is at nxp.com/6SLLEVK
• i.MX 6UltraLite information is at nxp.com/iMX6UL
• i.MX 6ULL information is at nxp.com/iMX6ULL
• i.MX 7Dual information is at nxp.com/iMX7D
2 Introduction
The i.MX Linux BSP is a collection of binary files, source code, and support files that can be used to create a U-Boot
bootloader, a Linux kernel image, and a root file system for i.MX development systems. The Yocto Project is the framework
of choice to build the images described in this document, although other methods can be used.
All the information on how to set up the Linux OS host, how to run and configure a Yocto Project, generate an image, and
generate a rootfs, are covered in the i.MX Yocto Project User's Guide (IMXLXYOCTOUG).
When Linux OS is running, this guide provides information on how to use some special features that i.MX SoCs provide.
The release notes provide the features that are supported on a particular board.
3 Basic Terminal Setup
The i.MX boards can communicate with a host server (Windows® OS or Linux OS) using a serial cable. Common serial
communication programs such as HyperTerminal, Tera Term, or PuTTY can be used. The example below describes the serial
terminal setup using HyperTerminal on a host running Windows OS.
The i.MX 6Quad/QuadPlus/DualLite SABRE-AI boards connect to the host server using a serial cable.
The i.MX 6 SABRE-SD, i.MX 6SoloLite EVK, i.MX 6SoloX SABRE-AI, i.MX 7Dual SABRE-SD, i.MX 6UltraLite EVK
and i.MX 6ULL EVK boards connect the host driver using the micro USB connector. The USB to serial driver can be found
under www.ftdichip.com/Drivers/VCP.htm.
1. Connect the target and the PC running Windows OS using a serial cable on i.MX 6 SABRE-AI boards or a micro-B
USB cable on i.MX 6 SABRE boards.
2. Open HyperTerminal on the PC running Windows OS and select the settings as shown in the following figure.
NXP Semiconductors
3
i.MX Linux® User's Guide, Rev. L4.1.15_2.1.0-ga, 05/2017
Booting Linux OS
Figure 1. Teraterm settings for terminal setup
4 Booting Linux OS
Before the Linux OS kernel can boot on an i.MX board, the images (U-Boot, Linux kernel, device tree, and rootfs) need to be
copied to a boot device and the boot switches need to be set to boot that device. There are various ways that this can be done
for different boards, boot devices, and results desired. This section explains how to prepare a boot device, where files need to
be in the memory map, how to set switches for booting, and how to boot Linux OS from U-Boot.
4.1 Software overview
This section describes the software needed for the board to be able to boot and run Linux OS.
To boot a Linux image on i.MX 6 and i.MX 7, four elements are needed:
• Bootloader (U-Boot)
• Linux kernel image (zImage)
• A device tree file (.dtb) for the board being used
• A root file system (rootfs) for the particular Linux image
The system can be configured for a specific graphical backend. The graphical backends are X11, XWayland, and Frame
Buffer.
4.1.1 Bootloader
U-Boot is the tool recommended as the bootloader for i.MX 6 and i.MX 7. U-Boot must be loaded onto a device to be able to
boot from it. U-Boot images are board-specific and can be configured to support booting from different sources.
4
NXP Semiconductors
i.MX Linux® User's Guide, Rev. L4.1.15_2.1.0-ga, 05/2017
The pre-built or Yocto Project default bootloader names start with the name of the bootloader followed by the name of the
platform and board and followed by the name of the device that this image is configured to boot from: imx-boot-[platform]
[board]_[machine_configuration].bin. If no boot device is specified, it boots from SD/MMC.
The manufacturing tool can be used to load U-Boot onto all devices with i.MX 6 and i.MX 7. U-Boot can be loaded directly
onto an SD card using the Linux dd command. U-Boot can be used to load a U-Boot image onto some other devices.
Booting Linux OS
4.1.2 Linux kernel image and device tree
This i.MX BSP contains a pre-built kernel image based on the 4.1.15 version of the Linux kernel and the device tree files
associated with each platform.
The same kernel image is used for all the i.MX 6 and i.MX 7 boards. Device trees are kernel configuration files that allow a
common kernel to boot with different pin settings for different boards or configurations. Device tree files use the .dtb
extension. The configuration for a device tree can be found in the Linux source code under arch/arm/boot/dts in the *.dts
files.
The i.MX Linux delivery package contains pre-built device tree files for the i.MX boards in various configurations. File
names for the prebuilt images are named zImage--[kernel]-[platform]-[board]-[configuration].dtb.
The *ldo.dtb device trees are used for LDO-enabled feature support. By default, the LDO bypass is enabled. If your board
has the CPU set to 1.2 GHZ, you should use the *ldo.dtb device tree instead of the default, because LDO bypass mode is not
supported on the CPU at 1.2 GHZ. The device tree *hdcp.dtb is used to enable the DHCP feature because of a pin conflict,
which requires this to be configured at build time.
4.1.3 Root file system
The root file system package (or rootfs) provides busybox, common libraries, and other fundamental elements.
The i.MX BSP package contains several root file systems. The file system includes i.MX-specific libraries and common
Linux utilites. They are named with the following convention: [image recipe]-[backend]-[platform][board].[ext3|sdcard]. The
ext3 extension indicates a standard file system. It can be mounted as NFS, or its contents can be stored on a boot media such
as an SD/MMC card.
The graphical backend to be used is also defined by the rootfs.
4.2 Manufacturing Tool
The Manufacturing Tool (MfgTool) runs on a Windows OS host and is used to download images to different devices on an
i.MX board. The tar.gz file can be found with the pre-built images.
4.2.1 Configuring MfgTool
Decompress Mfgtools-Rel-[version]_UPDATER.tar.gz.
Instructions for MfgTool V2 can be found in the file Profiles/[SOC] Linux Update/OS Firmware/ucl2.xml. Read
and update the ucl2.xml file to understand the operations before using MfgTool.
Skip this step if a board in the supported list is used.
NXP Semiconductors
5
i.MX Linux® User's Guide, Rev. L4.1.15_2.1.0-ga, 05/2017
Booting Linux OS
It is important to correctly configure the cfg.ini and UICfg.ini files. For example, if only one board is supported,
PortMgrDlg=1 should be set in UICfg.ini. If four boards are supported, PortMgrDlg=4 should be set. An incorrect
configuration causes MfgTool to malfunction.
For i.MX 6SoloX, the default settings in the cfg.ini file need to be changed as follows.
MfgTool looks for the settings in the ucl2.xml file.
NOTE
[profiles]
chip = Linux
[platform]
board = SabreSD
[LIST]
name = SDCard
[variable]
board = sabresd
mmc = 0
sxuboot=17x17arm2
sxdtb=17x17-arm2
ldo=
4.2.2 Using MfgTool
Follow these instructions to use the MfgTool V2:
1. Connect a USB cable from a computer to the USB OTG port on the board.
2. Connect a USB cable from the OTG-to-UART port to the computer for console output.
3. Open a Terminal emulator program. See Section "Basic Terminal Setup" in this document.
4. Set the boot pin to MfgTool mode. See Section "Serial download mode for the Manufacturing Tool" in this document.
5. Choose the correct vbs file and double-click it to launch the MfgTool host tool.
6. The default profile of the Manufacturing Tool assumes that your file system is packed and compressed using the bzip2
algorithm. An example can be found in the MfgTool release package in the folder Profiles/Linux/OS Firmware/
files. To create this file, run the following commands as a root user on Linux OS. You can also modify the profile to
support other formats.
7. After the image downloading is done, set the boot pin to boot up the board. See Section "How to boot the i.MX boards"
in the document.
6
NXP Semiconductors
i.MX Linux® User's Guide, Rev. L4.1.15_2.1.0-ga, 05/2017
Booting Linux OS
Figure 2. Programming SD with the Manufacturing Tool – image downloading
NOTE
The Manufacturing Tool may sometimes report an error message when it is
downloading the file system to an SD card. This can be caused by insufficient
space on the SD card due to a small partition size. To fix this, decompress the file
Profiles/Linux/OS Firmware/mksdcard.sh.tar and modify the script to
increase the size of the partition and create more partitions according to your file
system requirements. After the modification is done,compress the script again.
4.3 Preparing an SD/MMC card to boot
This section describes the steps to prepare an SD/MMC card to boot up an i.MX board using a Linux host machine. These
instructions apply to SD and MMC cards although for brevity, often only SD card is listed.
For a Linux image to be able to run, four separate pieces are needed:
• Linux OS kernel image (zImage)
• Device tree file (*.dtb)
• U-Boot bootloader image
• Root file system (*.ext3 or *.ext4)
An .sdcard image contains all four images properly configured for an SD card. The release contains a pre-built .sdcard image
that is built specifically for the one board configuration. It runs the X11 graphical backend. It does not run on other boards
unless U-Boot, the device tree, and rootfs are changed.
The Yocto Project build creates an SD card image that can be flashed directly. This is the simplest way to load everything
needed onto the card with one command.
When more flexibility is desired, the individual components can be loaded separately, and those instructions are included
here as well. An SD card can be loaded with the individual components one-by-one or the .sdcard image can be loaded and
the individual parts can be overwritten with the specific components.
The rootfs on the default .sdcard image is limited to a bit less than 4 GB, but re-partitioning and re-loading the rootfs can
increase that to the size of the card. The rootfs can also be changed to specify the graphical backend that is used.
The device tree file (.dtb) contains board and configuration-specific changes to the kernel. Change the device tree file to
change the kernel for a different i.MX board or configuration.
NXP Semiconductors
7
i.MX Linux® User's Guide, Rev. L4.1.15_2.1.0-ga, 05/2017
Booting Linux OS
By default, the release uses the following layout for the images on the SD card. The kernel image and DTB move to use the
FAT partition without a fixed raw address on the SD card. The users have to change the U-Boot boot environment if the fixed
raw address is required.
Table 1.
Image layout
Start address (sectors)
Size (sectors)
Format
Description
0x400 bytes (2)
0x9FFC00 bytes (20478)
RAW
0xa00000 bytes (20480)
0x25800000 bytes (1228800) Remaining space
500 Mbytes (1024000)
FAT
Ext3/Ext4
i.MX 6 and i.MX 7 U-Boot and
reserved area
Kernel zImage and DTBs
Rootfs
4.3.1 Preparing the card
An SD/MMC card reader, such as a USB card reader, is required. It is used to transfer the bootloader and kernel images to
initialize the partition table and copy the root file system. To simplify the instructions, it is assumed that a 4GB SD/MMC
card is used.
Any Linux distribution can be used for the following procedure.
The Linux kernel running on the Linux host assigns a device node to the SD/MMC card reader. The kernel might decide the
device node name or udev rules might be used. In the following instructions, it is assumed that udev is not used.
To identify the device node assigned to the SD/MMC card, carry out the following command:
$ cat /proc/partitions
major minor #blocks name
8 0 78125000 sda
8 1 75095811 sda1
8 2 1 sda2
8 5 3028221 sda5
8 32 488386584 sdc
8 33 488386552 sdc1
8 16 3921920 sdb
8 18 3905535 sdb1
In this example, the device node assigned is /dev/sdb (a block is 1024 Bytes).
Make sure that the device node is correct for the SD/MMC card. Otherwise, it may
damage your operating system or data on your computer.
NOTE
4.3.2 Copying the full SD card image
The SD card image (with the extension .sdcard) contains U-Boot, the Linux image and device trees, and the rootfs for a 4 GB
SD card. The image can be installed on the SD card with one command if flexibility is not required.
Carry out the following command to copy the SD card image to the SD/MMC card. Change sdx below to match the one used
by the SD card.
$ sudo dd if=.sdcard of=/dev/sdx bs=1M && sync
The entire contents of the SD card are replaced. If the SD card is larger than 4 GB, the additional space is not accessible.
8
NXP Semiconductors
i.MX Linux® User's Guide, Rev. L4.1.15_2.1.0-ga, 05/2017