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 board | Command |
|---|---|
| iMX6 SoloX COM | ums 0 mmc 2 |
| iMX6 Quad COM | ums 0 mmc 3 |
| iMX6 DualLite COM | ums 0 mmc 3 |
| iMX6 UltraLite COM | ums 0 mmc 1 |
| iMX7 Dual COM | ums 0 mmc 2 |
| iMX7 Dual uCOM | ums 0 mmc 2 |
| iMX7ULP uCOM | ums 0 mmc 0 |
| iMX8M Quad COM | ums 0 mmc 0 |
| iMX8M Mini uCOM | ums 0 mmc 2 |
| iMX8M Nano uCOM | ums 0 mmc 2 |
| iMX93 uCOM | ums 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
umssupport 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 board | eMMC device in Linux | Command |
|---|---|---|
| iMX6 SoloX COM | /dev/mmcblk2 | mount /dev/mmcblk2p1 /mnt/mmc |
| iMX6 Quad COM | /dev/mmcblk3 | mount /dev/mmcblk3p1 /mnt/mmc |
| iMX6 DualLite COM | /dev/mmcblk3 | mount /dev/mmcblk3p1 /mnt/mmc |
| iMX6 UltraLite COM | /dev/mmcblk1 | mount /dev/mmcblk1p1 /mnt/mmc |
| iMX7 Dual COM | /dev/mmcblk2 | mount /dev/mmcblk2p1 /mnt/mmc |
| iMX7 Dual uCOM | /dev/mmcblk2 | mount /dev/mmcblk2p1 /mnt/mmc |
| iMX7ULP uCOM | /dev/mmcblk0 | mount /dev/mmcblk0p1 /mnt/mmc |
| iMX8M Quad COM | /dev/mmcblk0 | mount /dev/mmcblk0p1 /mnt/mmc |
| iMX8M Mini uCOM | /dev/mmcblk2 | mount /dev/mmcblk2p1 /mnt/mmc |
| iMX8M Nano uCOM | /dev/mmcblk2 | mount /dev/mmcblk2p1 /mnt/mmc |
| iMX93 uCOM | /dev/mmcblk0 | mount /dev/mmcblk0p1 /mnt/mmc |
Using iMX8M Mini uCOM as an example:
mkdir /mnt/mmc
mount /dev/mmcblk2p1 /mnt/mmc
ls /mnt/mmc/
Image
boot.scr
cm_TCM_hello_world.bin
cm_TCM_rpmsg_lite_pingpong_rtos_linux_remote.bin
cm_TCM_rpmsg_lite_str_echo_rtos.bin
imx8mm-ea-ucom-kit_v2-1mw.dtb
imx8mm-ea-ucom-kit_v2-m4.dtb
imx8mm-ea-ucom-kit_v2-ov5640.dtb
imx8mm-ea-ucom-kit_v2-pcie.dtb
imx8mm-ea-ucom-kit_v2.dtb
imx8mm-ea-ucom-kit_v3-1mw.dtb
imx8mm-ea-ucom-kit_v3-m4.dtb
imx8mm-ea-ucom-kit_v3-ov5640.dtb
imx8mm-ea-ucom-kit_v3-pcie.dtb
imx8mm-ea-ucom-kit_v3.dtb
The scp command looks like this:
scp <username>@<server>:<path> <destination>
To copy the kernel from server with IP address 192.168.0.10 as user bob it could look like this:
scp bob@192.168.0.10:/home/bob/linux-imx/arch/arm64/boot/Image /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 https://winscp.net/eng/download.php and install it.
Connect to Target
When WinSCP is started it asks for connection information. Enter the following information
| Field | Value |
|---|---|
| User name | root |
| Password | pass |
| Host name | The IP number of the target (found by running ifconfig on the target) |
| File protocol | SCP or SFTP |
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:
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.
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:
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/
ea-image-base-imx8mmea-ucom.tar.bz2
Image-imx8mmea-ucom.bin
imx8mm-ea-ucom-kit_v3.dtb
imx-boot-imx8mmea-ucom-sd.bin
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