View source for Booting with a USB Root Filesystem

It is possible to boot most EMAC OE systems using a USB thumb drive as the root filesystem and to optionally load a kernel from. This method can be especially useful for updating or recovering the root filesystem when a network connection or a network file server is not available. This page describes the steps required to boot into a root filesystem residing on a USB thumb drive.

__TOC__

==Prerequisites==

Some prerequisites must be met prior to being able to boot a root filesystem from a USB drive.

===USB Thumb Drive===

Any blank USB drive. If it is not blank, this process will completely wipe the data that exists on the USB drive.

===Root Filesystem===

A complete root filesystem for the EMAC OE system to boot from must be stored on the USB drive.

===Linux Host Computer===

Either a native Linux host or Windows host running a Linux virtual machine.

==Configuring the USB Thumb Drive==

In a terminal window, start the dmesg log with the follow option to watch for new devices.

{{cli | username=developer | hostname=ldc | pwd=~ | dmesg -w }}

Insert the USB drive and watch for the device to be announced.

{{clo}}
[ 2796.940110] scsi host6: usb-storage 1-1.2:1.0 <br />
[ 2797.963442] scsi 6:0:0:0: Direct-Access     Generic  STORAGE DEVICE   0272 PQ: 0 ANSI: 0 <br />
[ 2797.963905] sd 6:0:0:0: Attached scsi generic sg4 type 0 <br />
[ 2798.269544] sd 6:0:0:0: [sdd] 7774208 512-byte logical blocks: (3.98 GB/3.71 GiB) <br />
[ 2798.271027] sd 6:0:0:0: [sdd] Write Protect is off <br />
[ 2798.271030] sd 6:0:0:0: [sdd] Mode Sense: 0b 00 00 08 <br />
[ 2798.272502] sd 6:0:0:0: [sdd] No Caching mode page found <br />
[ 2798.272508] sd 6:0:0:0: [sdd] Assuming drive cache: write through <br />
[ 2798.279486]  sdd: <br />
[ 2798.283834] sd 6:0:0:0: [sdd] Attached SCSI removable disk <br />
{{clos}}

<br />
{{ imbox | type=notice | text=If using a virtual machine, wait for Windows to install the Virtualbox USB driver. Then make the virtual machine aware of the USB drive by going into the Devices menu option in virtualbox, then sub-option USB and select your USB device.}}
<br />

The output of the <code>dmesg</code> command shows that the root device node for the USB drive in this case is <code>sdd</code> and no partitions. Partitions on the drive would be listed as <code>sdd1</code>, <code>sdd2</code>, etc.  Inspect the output shown above to see the particular device node on the development PC where the USB drive is mounted. This will be different depending on the configuration of the development PC. The <code>/dev/</code> prefix will go before the device name, but is not shown in the output of <code>dmesg</code>. The device node will start with <code>sd</code>. The third letter will specify which of these devices is assigned to the USB drive. The number will indicate the partitions, if any. Press Ctrl and 'c' to exit dmesg.

* At this point, it is wise to double check that device node is actually the USB drive and not a hard drive in the system. Specifying the wrong device node could cause a complete loss of data on a hard drive.  <br /><br /> Continuing with <code>/dev/sdd</code> as the example device node, type the following command:

{{clo}}
{{clio | username=developer | hostname=ldc | pwd=~ | mount {{!}} grep sdd }}
/dev/sdd on /media/developer/FBF6-1988 type vfat
{{clos}}

This shows that the device node, <code>/dev/sdd</code>, is in fact the USB drive.  This is because:
* It is not mounted on one of the standard Linux filesystem mountpoints, such as <code>/</code>, <code>/boot</code>, <code>/usr</code>, or <code>/home</code>.
* It '''is''' mounted in the <code>/media</code> directory, where it is expected.  It may alternatively get mounted in <code>/mnt</code>, depending upon the configuration of the Linux distribution in use.

If nothing is returned, then the USB drive did not get automatically mounted. Proceed to the next step.

Use <code>fdisk -l</code> to inspect the device node. Use <code>sudo</code> with <code>fdisk</code> to gain the required <code>root</code> privileges to run <code>fdisk</code>

{{clop}}
{{cliop | username=developer | hostname=ldc | pwd=~ | sudo fdisk -l /dev/sdd }}<nowiki>

Disk /dev/sdd: 3.7 GiB, 3980394496 bytes, 7774208 sectors
Disk model: STORAGE DEVICE  
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x4fcf5773
</nowiki>
{{closp}}

The output of fdisk will also show information about any partitions that may exist on the USB drive. For example, another drive with a single FAT32 formatted partition will look like:
{{clop}}
{{cliop | username=developer | hostname=ldc | pwd=~ | sudo fdisk -l /dev/sdd }}<nowiki>

Disk /dev/sdd: 3.7 GiB, 3980394496 bytes, 7774208 sectors
Disk model: STORAGE DEVICE  
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0xe6077d37

Device     Boot Start     End Sectors  Size Id Type
/dev/sdh1        2048 7774207 7772160  3.7G  c W95 FAT32 (LBA)
</nowiki>
{{closp}}

* As can be seen from the output of the <code>fdisk -l</code> command above, the disk is 3.7 GB in size, which corresponds with the size of the 4 GB USB drive being used in this example.

Unmount all of the USB drives partitions that were listed from the <code>mount</code> command above.

{{cli | username=developer | hostname=ldc | pwd=~ | sudo umount /dev/sdd }}

If there is a partition listed:

{{cli | username=developer | hostname=ldc | pwd=~ | sudo umount /dev/sdd1 }}

==Repartition the USB Drive==

Once the correct drive letter is determined, we will create a new Linux partition.

{{clop}}
{{cliop | username=developer | hostname=ldc | pwd=~ | sudo fdisk /dev/sdd }}<nowiki>

Welcome to fdisk (util-linux 2.33.1).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.


Command (m for help): o
Created a new DOS disklabel with disk identifier 0x05d5e983.

Command (m for help): n
Partition type
   p   primary (0 primary, 0 extended, 4 free)
   e   extended (container for logical partitions)
Select (default p): p
Partition number (1-4, default 1): 1
First sector (2048-7774207, default 2048): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-7774207, default 7774207): 

Created a new partition 1 of type 'Linux' and of size 3.7 GiB.

Command (m for help): p
Disk /dev/sdd: 3.7 GiB, 3980394496 bytes, 7774208 sectors
Disk model: STORAGE DEVICE  
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x05d5e983

Device     Boot Start     End Sectors  Size Id Type
/dev/sdd1        2048 7774207 7772160  3.7G 83 Linux

Command (m for help): w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.
</nowiki>
{{closp}}

The fdisk commands are:

<code>o</code> - Create a new empty partition table

<code>n</code> - Create a new partition

<code>p</code> - The type of partition is a primary partition

<code>1</code> - Create the first partition

<code><ENTER></code> - Accept default start

<code><ENTER></code> - Accept default end

<code>p</code> - Print the new partition layout

<code>w</code> - Write the new partition layout and exit

==Format the Partition==

The first partition will be formatted with the ext4 filesystem.

{{cli | username=developer | hostname=ldc | pwd=~ | yes {{!}} sudo mkfs.ext4 /dev/sdd1 }}

==Mount the Partition==

The first partition of the USB drive will be mounted so that it is accessible to write to.

{{clop}}
{{clio | username=developer | hostname=ldc | pwd=~ | sudo mkdir -p /media/card }}
{{clio | username=developer | hostname=ldc | pwd=~ | sudo mount /dev/sdd1 /media/card }}
{{closp}}

The USB drive is now accessible through the <code>/media/card</code> directory.

==Extract Filesystem Archive==

Locate where the filesystem archive has been downloaded. If the archive is called rootfs.tar.gz and is in the users Downloads directory:

{{clop}}
{{clio | username=developer | hostname=ldc | pwd=~ | cd /media/card }}
{{clio | username=developer | hostname=ldc | pwd=/media/card | sudo tar zxf ~/Downloads/rootfs.tar.gz }}
{{clio | username=developer | hostname=ldc | pwd=/media/card | sync }}
{{clio | username=developer | hostname=ldc | pwd=/media/card | cd }}
{{clio | username=developer | hostname=ldc | pwd=~ | sudo umount /media/card }}
{{closp}}

It is now safe to remove the USB drive from the host computer.

==Configuring the Client to Boot from USB==

===Configuring U-Boot===

Insert the USB drive into an available port on the target board.
Set the bootargs variable to tell the kernel to boot into the USB filesystem:

 U-Boot> setenv bootargs "console=${console} root=/dev/sda1 rootfstype=ext4 rootwait"

This line sets up the environment needed to boot from the USB drive.  These options will be passed to the Linux kernel when booting it.  The <code>console=${console}</code> part tells Linux to use the console setting from the U-Boot environment variable; this will usually be something along the lines of <code>console=ttyS0,115200n8</code>.  The <code>root=/dev/sda1</code> directive tells Linux to instantiate with the USB block device, <code>/dev/sda1</code>, as the root filesystem. The <code>rootfstype=ext4</code> directive tells Linux that the root filesystem is of the EXT4 variety.  

If the kernel is already programmed into the flash, it can be used in most cases to boot into the USB root filesystem. Execute the next line to load and run the default kernel.

 U-Boot> boot

The machine should now boot, and show output on its console as it does so.

===Alternate Kernel Load===

An alternate kernel can be loaded into memory temporarily and booted if the kernel is not already programmed in the flash or a development kernel is to be tested. The below example assumes a kernel named zImage-test was placed in the /boot directory of the USB drive. Also see [[ Loading_Images_with_U-Boot#Executing_kernel_from_RAM  | Executing kernel from RAM ]]

 U-Boot> usb start
 U-Boot> usb storage
 U-Boot> ext2load usb 0:1 ${loadaddr} /boot/zImage-test
 U-Boot> bootz ${loadaddr}

The first two commands initialize the USB storage system in U-Boot. The <code>ext2load</code> line says to use the USB device 0 partition 1 and load into RAM at ${loadaddr} the file /boot/zImage-test from the USB drive. The last line boots the kernel that has been loaded into memory.

==Conclusion==

Using a USB thumb drive for the root filesystem allows boards to boot quickly into a rescue or known good version of a filesystem and provides a method for remotely backing up the filesystem installed on an embedded machine.  Setting up a machine to boot to a root filesystem via USB requires little work; most of the work is in setting up the USB thumb drive.

{{:Templateimpl:moreinfo | initials=MG | title=System Logging | desc=The page describes how to USB boot. | project=OE 5.0 }}
* [[Loading_Images_onto_eMMC_Devices | Loading Images onto eMMC Devices]]
* [[Loading_Images_with_U-Boot | Loading Images with U-Boot]]
* [[Loading_Linux_Kernels_Onto_a_Board | Loading Linux Kernels Onto a Board]]