View source for Loading Images onto eMMC Devices

{{todo|Buggy (12.31.13-13:15->MD-)|Michael Welling|project=oe 4,oe 5,mw,Buggy,md}}

== Background ==
Newer EMAC products have started using eMMC in place of NAND flash. eMMC is an embedded MMC compliant memory that takes the form of an integrated circuit instead of a media card. 

U-Boot does not support writing to file systems in eMMC. To overcome this issue, the embedded target has to boot into Linux using an auxiliary method. Once U-Boot has been loaded into RAM, it can be used to load the target kernel using TFTP and boot into a file system stored in NFS. Once the board has booted into Linux, the eMMC can be partitioned and formatted, and the root file system can be extracted. The SoM-3517M requires a special FAT formatted partition that contains the bootloader and Linux kernel images. This article explains the general process of writing the eMMC from Linux as well as some specifics related to programming the SoM-3517M, SoM-9X25 and IPAC-9X25.


{{imbox | type=notice | text = The procedures below require that you have a TFTP and NFS server setup on a host computer. }}


* Instructions on setting up a TFTP server: [[Installing TFTP server]]
* Installation of a NFS with Linux: [[Setting up an NFS File Server]]
* Instruction for booting into NFS with U-Boot: [[Booting with an NFS Root Filesystem]]
* More information about MMC: http://en.wikipedia.org/wiki/MultiMediaCard


== Creating partitions and formatting eMMC ==

Once the Linux command prompt is reached, the Linux utilities can be used to create and format partitions on the eMMC. By partitioning the the eMMC, the partitions can be accessed individually and formatted differently as required. The <code>fdisk</code> utility can be used to create these partitions on the eMMC.

For example here is the procedure for creating a 128 MB primary partition:

 root@emac-oe:~# fdisk /dev/mmcblk0
 
 The number of cylinders for this disk is set to 57024.
 There is nothing wrong with that, but this is larger than 1024,
 and could in certain setups cause problems with:
 1) software that runs at boot time (e.g., old versions of LILO)
 2) booting and partitioning software from other OSs
    (e.g., DOS FDISK, OS/2 FDISK)
 Command (m for help): n
 Command action
    e   extended
    p   primary partition (1-4)
 p
 Partition number (1-4): 1
 First cylinder (1-57024, default 1): Using default value 1
 Last cylinder or +size or +sizeM or +sizeK (1-57024, default 57024): +128M
 
 Command (m for help): p
 
 Disk /dev/mmcblk0: 1868 MB, 1868562432 bytes
 4 heads, 16 sectors/track, 57024 cylinders
 Units = cylinders of 64 * 512 = 32768 bytes
 
         Device Boot      Start         End      Blocks  Id System
 /dev/mmcblk0p1               1        3907      125016  83 Linux
 
 Command (m for help): w
 The partition table has been altered!
 
 Calling ioctl() to re-read partition table
 [  566.062896]  mmcblk0: p1

For more information about <code>fdisk</code>, see:
http://tldp.org/HOWTO/Partition/fdisk_partitioning.html

After creating the partitions, they can formatted with the various <code>mkfs</code> utilities. The formatting used is dependent on how the partition is to be access. For eMMC root filesystems EMAC currently uses EXT3(http://en.wikipedia.org/wiki/Ext3). Other formatting options are available (EXT2,EXT4,etc) and can be used. It should be noted that the kernel must be configured to use the various filesystem options and the bootargs need to specify the correct type. 

{{imbox | type=notice | text =For additional information on configuring and compiling the Linux kernel see the following page: [[Building the Linux Kernel]] }}

As described above, the <code>bootargs</code> is used for signalling to the Linux kernel the root filesystem partition and formatting. The <code>root</code> parameter is used to specify the partition to use while the <code>rootfstype</code> parameter is used to specify formatting of the partition.

{{imbox | type=notice | text =For more information about the <code>bootargs</code> variable see this page: [[U-Boot Overview]] }}

Partitions accessed by processor boot ROM or U-Boot typically need to be formatted with FAT32 formatting. The SoM-3517M, for instance, requires a FAT32 formatted partition for the bootloader and kernel in order to boot properly from eMMC. For more specifics about the SoM-3517M, see the quick reference section below.

Formatting a partition with EXT3:
 root@emac-oe:~# mkfs.ext3 /dev/mmcblk0p1
 mke2fs 1.41.14 (22-Dec-2010)
 Filesystem label=
 OS type: Linux
 Block size=1024 (log=0)
 Fragment size=1024 (log=0)
 Stride=0 blocks, Stripe width=0 blocks
 31360 inodes, 125016 blocks
 6250 blocks (5.00%) reserved for the super user
 First data block=1
 Maximum filesystem blocks=67371008
 16 block groups
 8192 blocks per group, 8192 fragments per group
 1960 inodes per group
 Superblock backups stored on blocks: 
         8193, 24577, 40961, 57345, 73729
 
 Writing inode tables: done      
 Creating journal (4096 blocks): done
 Writing superblocks and filesystem accounting information: done
 
 This filesystem will be automatically checked every 39 mounts or
 180 days, whichever comes first.  Use tune2fs -c or -i to override.


Formatting a partition with FAT32:
 root@emac-oe:~# mkdosfs -F 32 /dev/mmcblk0p1
 mkdosfs 2.11 (12 Mar 2005)

== Extracting filesystems to eMMC ==
After formatting a partition correctly, the partition can be mounted and files can be loaded to the eMMC.

'''*************** What does this sequence of commands boil down to?  A plain-English explanation that: "The filesystem can be extracted from a tarball into the mounted, newly formatted partition.  Permissions are preserved... blah blah  Virtual filesystems... blah blah  The fstab file... blah"  can really help the reader understand the process. *********************'''

For example, here is the procedure for writing a root filesystem to the first partition of an eMMC card:
 root@emac-oe:~# mkdir -p /mnt/card
 root@emac-oe:~# mount /dev/mmcblk0p1 /mnt/card
 root@emac-oe:~# cd /mnt/card
 root@emac-oe:~# tar xzvf /images/emac-image.rootfs.tar.gz
     ⋮

== Quick Reference (by Target Type) ==
=== SoM-3517M ===
==== Partitioning the eMMC ====

 root@emac-oe:~# fdisk /dev/mmcblk0

The partitioning steps are as follows:

'''*********** Strictly speaking, the p's in these steps aren't necessary, since they just print the table.  An explanation that the first partition will be 64MB, and choosing defaults for the second means it will fill the remaining available space, will help the reader. ******************'''

# Create 1st partition (n,p,1,default,+64M)
# Create 2nd partition (n,p,2,default,default)
# Change 1st partition type to FAT32 (t,1,c)
# Make 1st partition ACTIVE (a,1)
# Write (w)

==== Formatting the eMMC ====

''' ***************** Maybe a note that there are many options that can be selectively enabled/disabled for the ext3 filesystem, and that they can find more info about that in the manpage? ****************'''

 root@emac-oe:~# mkfs.ext3 /dev/mmcblk0p2
 root@emac-oe:~# mkdosfs -F 32 /dev/mmcblk0p1

==== Adding Kernel and Bootloader ====

'''********** What is this uImage thing?  MLO?  Why do they go directly into the root of the filesystem?  Does the p1 mean partition 1, while p2 means partition 2?  So, is p1 a special boot partition instead of the root partition?  The poor reader is now lost... *****************'''

 root@emac-oe:~# mkdir -p /mnt/card
 root@emac-oe:~# mount /dev/mmcblk0p1 /mnt/card
 root@emac-oe:~# cd /images
 root@emac-oe:/images# cp MLO uImage u-boot.bin /mnt/card/
 root@emac-oe:/images# sync
 root@emac-oe:/images# umount /dev/mmcblk0p1

==== Extracting Root Filesystem ====
 root@emac-oe:/images# mount /dev/mmcblk0p2 /mnt/card
 root@emac-oe:/images# cd /mnt/card
 root@emac-oe:/mnt/card# tar xzvf /emac-image.rootfs.tar.gz
 root@emac-oe:/mnt/card# cd ..
 root@emac-oe:/mnt# sync
 root@emac-oe:/mnt# umount /dev/mmcblk0p2

=== SoM-9X25M / IPAC-9X25 ===
==== Partitioning the eMMC ====

'''*********** The sensible reader skipped reading about the 3517, because the reader doesn't possess one, and went straight to this section.  Now the reader asks for the same information that was provided for the 3517. ****************'''

 root@emac-oe:~# fdisk /dev/mmcblk0

The partitioning steps are as follows:

# Create 1st partition (n,p,1,default,default)
# Write (w)

==== Formatting the eMMC ====
 root@emac-oe:~# mkfs.ext3 /dev/mmcblk0p1

==== Extracting Root Filesystem ====
 root@emac-oe:~# mkdir -p /mnt/card
 root@emac-oe:~# mount /dev/mmcblk0p1 /mnt/card
 root@emac-oe:~# cd /mnt/card
 root@emac-oe:/mnt/card# tar xzvf /emac-image.rootfs.tar.gz
 root@emac-oe:/mnt/card# cd ..
 root@emac-oe:/mnt# sync
 root@emac-oe:/mnt# umount /dev/mmcblk0p1