Repartitioning NAND Flash with JFFS2 for Linux

TODO: {{#todo:Needs to be broken into several sections|Mike Dean|oe 4,oe 5,md}}

Many of EMAC's ARM processor-based systems utilize NAND flash with JFFS2 filesystems. On these systems, the NAND flash is partitioned using the Linux MTD "Command line partition table parsing" feature. This allows the partition table for the flash to be specified on the kernel command line passed from the bootloader. By default, EMAC OE NAND flash images provide one partition for the root filesystem mounted read-only, and a second read/write auxiliary partition mounted on /root. This article describes how to modify the partition table and how to utilize and configure additional partitions.

Command Line Partition Table

EMAC OE NAND flash-based systems utilize MTD command line partition table parsing to specify the partition table for the flash. This is different from what you may be used to with other disks where the partition table is stored in the MBR. When the system is booted, the kernel looks at the partition table specified and creates device nodes corresponding to each partition at the given size or offset. These can be accessed like any other partition, but no information about the actual partition table is stored on the disk itself.

A brief description of the format and options for the partition table command line taken from the drivers/mtd/Kconfig is listed below:

The format for the command line is as follows:

mtdparts=<mtddef>[;<mtddef]
<mtddef>  := <mtd-id>:<partdef>[,<partdef>]
<partdef> := <size>[@offset][<name>][ro]
<mtd-id>  := unique id used in mapping driver/device
<size>    := standard linux memsize OR "-" to denote all
remaining space
<name>    := (NAME)

Due to the way Linux handles the command line, no spaces are
allowed in the partition definition, including mtd id's and partition
names.

Although the kernel command line is specified in the bootloader (the bootargs variable in U-Boot), the command line can be viewed through the /proc/cmdline file on a running Linux system. The example below illustrates the command line on a system. Note that the settings on your system will most likely differ from the configuration here depending on the required size for the root filesystem, processor type, and other variables.

root@emac-oe:~# cat /proc/cmdline
console=ttyS0,115200 root=/dev/mtdblock0 mtdparts=atmel_nand:128M(root),-(aux) ro rootfstype=jffs2 video=AMPIRE

In the example above, the mtdparts parameter specifies the partition table for one device: atmel_nand. This device name will vary depending on the type of processor on the board and the flash driver name. The first partition is 128MB and is named "root". Following that is a partition named "aux" which takes up the remaining space on the flash.

One method for viewing which device nodes correspond to each of these partitions is to view the /proc/mtd file. The partition names specified in the command line are reflected in the /proc/mtd contents as shown below. In this example, you can see that mtd0 corresponds to "root", and mtd1 corresponds to "aux". The remaining devices on this system are on the SPI DataFlash device, which uses a hard-coded partition table.

root@emac-oe:~# cat /proc/mtd
dev:    size   erasesize  name
mtd0: 08000000 00020000 "root"
mtd1: 08000000 00020000 "aux"
mtd2: 00042000 00000210 "df_boot"
mtd3: 00210000 00000210 "df_kernel"
mtd4: 001ce000 00000210 "df_aux"

The /etc/fstab file specifies how the NAND flash partitions should be mounted. For example, the system used for this example contains the following entries for the NAND flash partitions:

/dev/mtdblock0       /                    jffs2      ro                    0  0
/dev/mtdblock1       /root                jffs2      rw                    0  0

This configures the system to mount the root filesystem read-only, and to mount the "aux" partition read/write on /root.

The usage statistics for each filesystem can be viewed through the df command as listed below. This information can be helpful in determining the size requirements for the root partition.

root@emac-oe:~# df -h
Filesystem                Size      Used Available Use% Mounted on
/dev/root               128.0M     90.8M     37.2M  71% /
udev                     61.5M     76.0K     61.4M   0% /dev
media                     2.0M         0      2.0M   0% /media
/dev/mmcblk0p1            1.8G      2.3M      1.8G   0% /media/mmcblk0p1
/dev/mtdblock1          128.0M      3.0M    125.0M   2% /root
tmpfs                    61.5M     88.0K     61.4M   0% /var/volatile
tmpfs                    61.5M         0     61.5M   0% /dev/shm

Changing the Mount Point of the Auxiliary Partition

If existing partition scheme is acceptable for your application but you want to use the auxiliary partition for data logging rather than general storage and development, the easiest solution is to simply change the mount point of the second partition. The following steps can be used to do this:

1. Mount the flash read/write and create the new mount point, /mnt/data in this example.

   root@emac-oe:~# mount -o remount,rw /
   root@emac-oe:~# mkdir /mnt/data
   

2. Edit the /etc/fstab file to change the mount point of the auxiliary partition. The device node for the data partition will vary depending on the hardware. Simply find the entry for /root and change it to /mnt/data. (See this page for more information on how to edit a file.) After modifying the system used for this example, the entry for the data partition is as follows:

   /dev/mtdblock1       /mnt/data            jffs2      rw                    0  0
   

3. To complete the process, remount the root flash read only, and test the new fstab configuration for the data partition.

   root@emac-oe:~# mount -o remount,ro /
   root@emac-oe:~# cd /
   root@emac-oe:~# umount /root
   root@emac-oe:~# mount /mnt/data
   root@emac-oe:~# mount | grep mtdblock1
   /dev/mtdblock1 on /mnt/data type jffs2 (rw,relatime)
   

Modifying the Partition Table

If you need to specify additional partitions or change the sizes of the existing partitions, the process is more involved. To do this, you will need to archive the root filesystem, change the command line partition table specification, reprogram the root filesystem, and configure the system. Each of these steps are outlined below.

Archive the Root Filesystem

If you do not already have an archive of the root filesystem on the board, it will be necessary to create an archive now so that the root filesystem can be restored after the flash partitions have been modified.

1. Follow the instructions in Archiving JFFS2 Images to create a binary copy of the partition.
2. Use the procedure in Mounting JFFS2 Images on a Linux PC to mount the JFFS2 partition on a Linux PC.
3. Finally, create a new JFFS2 and summary image following the Creating JFFS2 Images procedure.

Specify the new Partition Table

The new partition table must be specified through the kernel command line passed from the bootloader. U-boot uses the bootargs environment variable to control this setting. In this example, the root partition will be resized from 128MB to 100MB, an additional data partition of 64MB will be created, and the rest of the flash will be reserved for an auxiliary partition. The resulting partition table specification would look like this:

mtdparts=atmel_nand:100M(root),64M(data),-(aux)

Follow the steps below to modify the bootargs variable with the new partition information.

1. Connect to the target board through the serial console.
2. Reset the board and press Enter when the U-Boot messages appear on the serial terminal to interrupt the boot process. A U-Boot> prompt should appear.
3. View the current bootargs variable using the printenv command as shown below:

   U-Boot> printenv bootargs
   console=ttyS0,115200 root=/dev/mtdblock0 mtdparts=atmel_nand:128M(root),-(aux) ro rootfstype=jffs2 video=AMPIRE
   

4. Modify the bootargs variable and replace the mtdparts definition with the new settings:

   U-Boot> setenv bootargs 'console=ttyS0,115200 root=/dev/mtdblock0 mtdparts=atmel_nand:100M(root),64M(data),-(aux) ro rootfstype=jffs2 video=AMPIRE'
   

5. Now save the change to flash so that it will persist. If this step is not performed, the above commandline will only be used on the very next boot.

   U-Boot> saveenv
   

Reload the Root Partition

Follow the instructions in Loading Images with U-Boot to load the archived root partition back onto the NAND flash. You will not need to reload the kernel. Once this is complete, restart the board and verify that it boots properly. For reference, the commands required for the system used in this example are shown below:

U-Boot> nand erase
U-Boot> tftp 0x70000000 rootfs-archive.jffs2
U-Boot> nand write.jffs2 0x70000000 0x0 ${filesize}

Configure the System

Once the system has booted, it must be configured to mount the partitions as desired. In this example, the newly created data partition will be mounted on /mnt/data and the auxiliary partition will be mounted on /root.

1. Log in as root, mount the flash read / write, and create the new mount point for the data partition:

   root@emac-oe:~# mount -o remount,rw /
   root@emac-oe:~# mkdir /mnt/data
   

2. Determine the device nodes for the partitions using the /proc/mtd file. The example output below shows that the data partition is on mtd1 and the auxiliary partition is on mtd2.

   root@emac-oe:~# cat /proc/mtd
   dev:    size   erasesize  name
   mtd0: 06400000 00020000 "root"
   mtd1: 04000000 00020000 "data"
   mtd2: 05c00000 00020000 "aux"
   mtd3: 00042000 00000210 "df_boot"
   mtd4: 00210000 00000210 "df_kernel"
   mtd5: 001ce000 00000210 "df_aux"
   

3. Modify the /etc/fstab file to mount the data and auxiliary partitions. This involves changing the device for /root, and adding an entry for /mnt/data. Note that the MTD block device corresponding to each partition must be used to mount the filesystems as JFFS2. The resulting /etc/fstab entries for the system used in this example are shown below:

   /dev/mtdblock1       /mnt/data            jffs2      rw                    0  0
   /dev/mtdblock2       /root                jffs2      rw                    0  0
   

4. Unmount /root and mount both partitions with the new fstab entries:

   root@emac-oe:~# cd /
   root@emac-oe:~# umount /root
   root@emac-oe:~# mount /root
   root@emac-oe:~# mount /mnt/data
   root@emac-oe:~# mount
   rootfs on / type rootfs (rw)
   /dev/root on / type jffs2 (rw,relatime)
   proc on /proc type proc (rw,relatime)
   sysfs on /sys type sysfs (rw,relatime)
   udev on /dev type tmpfs (rw,relatime,mode=755)
   media on /media type tmpfs (rw,relatime,size=2048k,mode=755)
   /dev/mmcblk0p1 on /media/mmcblk0p1 type vfat (rw,sync,relatime,fmask=0022,dmask=0000,allow_utime=0022,codepage=cp437,iocharset=iso8859-1)
   devpts on /dev/pts type devpts (rw,relatime,gid=5,mode=620)
   tmpfs on /var/volatile type tmpfs (rw,relatime)
   tmpfs on /dev/shm type tmpfs (rw,relatime,mode=777)
   /dev/mtdblock1 on /mnt/data type jffs2 (rw,relatime)
   /dev/mtdblock2 on /root type jffs2 (rw,relatime)
   

The system should automatically mount the partitions using this configuration on each boot.