Skip to main content

Updating Files on Target

There are four parts that make up a running system: U-Boot, Linux kernel, device tree files and a root file system. The U-Boot and root file system must be flashed using MfgTool or UUU as described in Deploying Images. The Linux kernel and the device tree files are however much easier to update, and this appendix will show a couple of different ways to do this.

  • U-Boot USB Mass Storage Gadget - Quick, no extra software or network connection needed
  • Secure Copy From Target - Requires network but no extra software
  • Secure Copy To Target - Requires network and PC software. Target must be modified to allow incoming connection. The advantage is an application with a GUI.
  • USB memory stick - Only requires a Memory Stick but using it involves a lot of plugging/copying/unplugging

Note that the sections below focus on updating the Linux kernel and device tree files, but the same commands can be used to update any file on the target.

U-Boot USB Mass Storage Gadget

The U-Boot has a ums command that can export a mmc device as a USB Mass Storage making it accessible from a PC. The mmc device numbering is different for each board and changes with versions of the U-Boot, so the table below shows the command to use for version 2021.04 (imx93 appeared first in 2022.04).

COM boardCommand
iMX6 SoloX COMums 0 mmc 2
iMX6 Quad COMums 0 mmc 3
iMX6 DualLite COMums 0 mmc 3
iMX6 UltraLite COMums 0 mmc 1
iMX7 Dual COMums 0 mmc 2
iMX7 Dual uCOMums 0 mmc 2
iMX7ULP uCOMums 0 mmc 0
iMX8M Quad COMums 0 mmc 0
iMX8M Mini uCOMums 0 mmc 2
iMX8M Nano uCOMums 0 mmc 2
iMX93 uCOMums 0 mmc 0

To use the ums command, power on, stop in the U-Boot, connect the micro-USB cable in J11 (on a V2 COM Carrier Board) or J26 (on a V3 uCOM Carrier Board) and to the PC and then execute the command for your board. For iMX8M Mini uCOM it will look like this:

ums 0 mmc 2
UMS: LUN 0, dev 0, hwpart 0, sector 0x0, count 0x72c000

There will be a spinning character indicating that the command is running. After a few seconds the PC should detect the USB drive(s) and make them available.

The number of drives that appear and if they can be accessed, or not, depends on the operating system. Windows and Linux are both able to access the first drive as it is FAT formatted. It corresponds to the mmc partition with the Linux kernel and device tree files on it. As Linux has ext3/ext4 file system support it can also access the second drive which corresponds to the root file system of the target.

Add/remove files on the PC and then use the "safe unmounting" option in Windows/Linux to make sure all changes have been written. Finally, stop the ums command in the U-Boot by typing Ctrl+C in the terminal.

ums 0 mmc 2
UMS: LUN 0, dev 0, hwpart 0, sector 0x0, count 0x72c000
CTRL+C - Operation aborted

Some things to note

  • The U-Boot is single threaded so the transfer speed of files to/from the USB drive is quite low. That does not matter when updating the Linux kernel and/or device tree files but for large files it is probably quicker to boot into Linux first (and do the file transfer from there).
  • When accessing the root file system from a PC running Linux you may have to run the commands as root (for example using sudo) as all files are owned by root.
  • The ums support was first verified on the ea_v2018.03 branch of the U-Boot and connected to a PC running Windows 7, Windows 10 and Ubuntu 18.04.

Secure Copy from Target

The default file system on all iMX Developer's Kits come with the scp tool preinstalled. If the target is connected to the same network as you build computer and the build computer has an ssh server running then scp can be used to transfer files from the build server. The first step is to mount the mmc partition that holds the Linux kernel and device tree files. The mmc device numbering is different for each board, so the table below shows the command to use.

COM boardeMMC device in LinuxCommand
iMX6 SoloX COM/dev/mmcblk2mount /dev/mmcblk2p1 /mnt/mmc
iMX6 Quad COM/dev/mmcblk3mount /dev/mmcblk3p1 /mnt/mmc
iMX6 DualLite COM/dev/mmcblk3mount /dev/mmcblk3p1 /mnt/mmc
iMX6 UltraLite COM/dev/mmcblk1mount /dev/mmcblk1p1 /mnt/mmc
iMX7 Dual COM/dev/mmcblk2mount /dev/mmcblk2p1 /mnt/mmc
iMX7 Dual uCOM/dev/mmcblk2mount /dev/mmcblk2p1 /mnt/mmc
iMX7ULP uCOM/dev/mmcblk0mount /dev/mmcblk0p1 /mnt/mmc
iMX8M Quad COM/dev/mmcblk0mount /dev/mmcblk0p1 /mnt/mmc
iMX8M Mini uCOM/dev/mmcblk2mount /dev/mmcblk2p1 /mnt/mmc
iMX8M Nano uCOM/dev/mmcblk2mount /dev/mmcblk2p1 /mnt/mmc
iMX93 uCOM/dev/mmcblk0mount /dev/mmcblk0p1 /mnt/mmc

Using iMX8M Mini uCOM as an example:

mkdir /mnt/mmc
mount /dev/mmcblk2p1 /mnt/mmc
ls /mnt/mmc/

The scp command looks like this:

scp <username>@<server>:<path> <destination>

To copy the kernel from server with IP address as user bob it could look like this:

scp bob@ /mnt/mmc/

After copying the files from the build server make sure to unmount the mmc partition before rebooting:

umount /mnt/mmc

Secure Copy To Target - WinSCP

WinSCP is a Windows program that is very useful to transfer files from the PC to the target hardware. It can also be used to transfer the files from a yocto build to the PC where the files can be flashed using UUU as described in Deploying Images.

Download and Install

Download the program from and install it.

Connect to Target

When WinSCP is started it asks for connection information. Enter the following information

User nameroot
Host nameThe IP number of the target (found by running ifconfig on the target)
File protocolSCP or SFTP

WinSCP Login

Press the Login button to connect to the target.

The first time connecting to the target (or after a re-flash of the target) this dialog will appear:

WinSCP Warning

Press the Yes button to accept it.

If you get a dialog liked the one below asking for the password, and you are sure that you have entered the correct one (pass) then it is probably because the target is configured not to allow the root user to connect.

WinSCP Password

Allowing root access is a huge security threat, and it should never be allowed in a production system. To allow it during development in a controlled environment is ok and to do it run the following command on the target and then reboot to apply the change:

sed -i 's/#PermitRoot/PermitRoot/' /etc/ssh/sshd_config

If you prefer to edit the file manually then open /etc/ssh/sshd_config and search for

#PermitRootLogin yes

and then remove the preceding # sign.

Note that the command is persistent but needs to be executed again if you re-flash the file system.

Copy Files

This is what the program looks like after a successful login:

WinSCP Upload

Select a file on the left side (the PC), select a destination folder on the target (right side) and then click the Upload button to transfer the file.

Note that to copy files directly to the mmc partition, use the mount and unmount commands as described in Secure Copy from Target. You will then find the mounted partition under the mnt/mmc/ folder in WinSCP.

USB Memory Stick

If the build machine is not accessible over network, then copying the files on the build server onto a USB Memory Stick could be an option.

When the USB Memory Stick is inserted on the target some status messages will be printed in the console.

usb 1-1.3: new high-speed USB device number 5 using ci_hdrc
usb-storage 1-1.3:1.0: USB Mass Storage device detected
scsi1 : usb-storage 1-1.3:1.0
scsi 1:0:0:0: Direct-Access Kingston DataTraveler G2 1.00 PQ: 0 ANSI: 2
sd 1:0:0:0: [sda] 31252024 512-byte logical blocks: (16.0 GB/14.9 GiB)
sd 1:0:0:0: [sda] Write Protect is off
sd 1:0:0:0: [sda] Incomplete mode parameter data
sd 1:0:0:0: [sda] Assuming drive cache: write through
sd 1:0:0:0: [sda] Incomplete mode parameter data
sd 1:0:0:0: [sda] Assuming drive cache: write through
sda: sda1
sd 1:0:0:0: [sda] Incomplete mode parameter data
sd 1:0:0:0: [sda] Assuming drive cache: write through
sd 1:0:0:0: [sda] Attached SCSI removable disk

The interesting part above is the sda: sda1 which indicates which device (sda1) that the USB memory stick is assigned to.

To be able to access the memory stick it must first be mounted:

mkdir /mnt/usb
mount /dev/sda1 /mnt/usb

The memory stick is now available in the /mnt/usb directory on the file system:

ls /mnt/usb/

If the mmc partition has been mounted as described in Secure Copy from Target, then files can be copied from the directory to the mmc partition like this:

cp /mnt/usb/imx8mm-ea-ucom-kit_v3.dtb /mnt/mmc/

Make sure to unmount the mmc after completing the copying.

Before physically removing the memory stick from the COM Carrier Board, it should be unmounted to make sure that all pending write operations are committed to prevent data loss:

umount /mnt/usb