Creating JFFS2 Images

TODO: {{#todo:Polish this|Mike Dean|oe 4,oe 5,md}}

Background

JFFS2 is the Second Journalling Flash File System. JFFS2 was created to provide a better filesystem for flash memory devices. It is a log-structured filesystem, which provides for wear-leveling of the flash. Unlike its predecessor, JFFS, JFFS2 supports NAND flash devices (used on all newer EMAC machines), hard links, compression and garbage collection (which enhances performance by no longer requiring the disk to be treated purely as a circular log).

This page describes the process of creating JFFS2 images on a Linux PC from existing files. This is often used to create new images from existing JFFS2 images in order to resize, modify, or change parameters on the image. If using this process to modify an existing image, please follow the steps in Mounting JFFS2 Images on a Linux PC to mount the existing image. The mounted directory structure will be used as the root directory for creating the new image.

Mkfs.jffs2 Usage

The mkfs.jffs2 application is used to create JFFS2 images. The output of mkfs.jffs2 --help is shown below and lists the available options with brief descriptions:

developer@ldc:~$ sudo mkfs.jffs2
mkfs.jffs2: Usage: mkfs.jffs2 [OPTIONS]
Make a JFFS2 file system image from an existing directory tree

Options:
  -p, --pad[=SIZE]        Pad output to SIZE bytes with 0xFF. If SIZE is
                          not specified, the output is padded to the end of
                          the final erase block
  -r, -d, --root=DIR      Build file system from directory DIR (default: cwd)
  -s, --pagesize=SIZE     Use page size (max data node size) SIZE (default: 4KiB)
  -e, --eraseblock=SIZE   Use erase block size SIZE (default: 64KiB)
  -c, --cleanmarker=SIZE  Size of cleanmarker (default 12)
  -m, --compr-mode=MODE   Select compression mode (default: priority)
  -x, --disable-compressor=COMPRESSOR_NAME
                          Disable a compressor
  -X, --enable-compressor=COMPRESSOR_NAME
                          Enable a compressor
  -y, --compressor-priority=PRIORITY:COMPRESSOR_NAME
                          Set the priority of a compressor
  -L, --list-compressors  Show the list of the avaiable compressors
  -t, --test-compression  Call decompress and compare with the original (for test)
  -n, --no-cleanmarkers   Don't add a cleanmarker to every eraseblock
  -o, --output=FILE       Output to FILE (default: stdout)
  -l, --little-endian     Create a little-endian filesystem
  -b, --big-endian        Create a big-endian filesystem
  -D, --devtable=FILE     Use the named FILE as a device table file
  -f, --faketime          Change all file times to '0' for regression testing
  -q, --squash            Squash permissions and owners making all files be owned by root
  -U, --squash-uids       Squash owners making all files be owned by root
  -P, --squash-perms      Squash permissions on all files
      --with-xattr        stuff all xattr entries into image
      --with-selinux      stuff only SELinux Labels into jffs2 image
      --with-posix-acl    stuff only POSIX ACL entries into jffs2 image
  -h, --help              Display this help text
  -v, --verbose           Verbose operation
  -V, --version           Display version information
  -i, --incremental=FILE  Parse FILE and generate appendage output for it

Please review the mkfs.jffs2 man page as well, which should be available after installing the mtd utilities. The parameters used to create the image will depend on the target system, including the flash type, erase block size, and partition size. Once the parameters have been determined, the JFFS2 image will be created by running mkfs.jffs2 and specifying the directory tree to use for making the image using the --root option. The following sections discuss the system variables affecting JFFS2 images.

Erase Block Size

The erase block size of the flash must be determined before creating the JFFS2 image. This can be found through the contents of /proc/mtd on a running system or through the system documentation. All NOR flashes currently used on EMAC products utilize 128 KiB erase blocks. NAND flashes use a variety of configurations, 128 KiB and 256 KiB are the most common. Contact EMAC if you unsure what value to use.

Endianess

Currently, all EMAC products that use JFFS2 filesystems are configured as little endian by default. Custom configurations or future products may result in the need for a big endian image. Contact EMAC if you are unsure which endianness to use.

Cleanmarkers

By default, JFFS2 writes cleanmarker nodes to the beginning of each erase block. While this is desired on NOR flash, it should not be used for NAND flash devices. If the target system uses a NAND flash, cleanmarkers will be disabled with the --no-cleanmarkers option.

Padding

Padding is extra space left for the creation of inodes, which are essentially pointers to files. The filesystem will automatically allocate space for the inodes needed for the files which are put into the filesystem at the time of creation. On NOR devices, padding needs to be added to allow additional files to be stored on the filesystem after the time of creation. On NAND flash, this is not needed due to the strictly sequential interface of NAND devices.

For NOR flash, padding is typically added to the end of the last erase block by specifying the --pad option with no size parameter. However, when using RedBoot as the bootloader the image should be padded to the full size of the JFFS2 partition. For example, when creating a new root filesytem for a board with a 28 MiB root partition running RedBoot, --pad=0x1C00000 would be specified to create a padded image.

NOTE: 0x1c00000 = 28 * (1024 * 1024) in hexadecimal

Examples

After determining what parameters to use for the target system, the image can be created. Several examples are provided for different common system types. These examples assume that the root directory is located at /tmp/rootfs and save the image in the output file emac-oe-rootfs.jffs2.

NAND Flash with 128 KiB Erase Blocks

developer@ldc:~$ sudo mkfs.jffs2 --root=/tmp/rootfs --output=emac-oe-rootfs.jffs2 \
--eraseblock=0x20000 --little-endian --no-cleanmarkers

NAND Flash with 256 KiB Erase Blocks

developer@ldc~$ sudo mkfs.jffs2 --root=/tmp/rootfs --output=emac-oe-rootfs.jffs2 \
--eraseblock=0x40000 --little-endian --no-cleanmarkers

NOR Flash with 128 KiB Erase Blocks for U-Boot

developer@ldc~$ sudo mkfs.jffs2 --root=/tmp/rootfs --output=emac-oe-rootfs.jffs2 \
--eraseblock=0x20000 --little-endian --pad

NOR Flash with 128 KiB Erase Blocks for RedBoot with 28 MiB Partition Size

developer@ldc:~$ sudo mkfs.jffs2 --root=/tmp/rootfs --output=emac-oe-rootfs.jffs2 \
--eraseblock=0x20000 --little-endian --pad=0x1C00000

Sumtool

Sumtool is a utility that creates JFFS2 erase block summary images. Summary information is an improvement to the original JFFS2 design that can speed up the mount process of JFFS2 filesystems by reducing the amount of the filesystem that must be scanned. JFFS2 summary support is included in default EMAC kernel configurations.

Summary JFFS2 images are created using an existing JFFS2 filesystem created with mkfs.jffs2. Typically, the only options required to use sumtool are the eraseblock size, input file, output file, and whether cleanmarkers should be used. Other options may be listed by running sumtool --help. For example, to create a summary image from the oe-rootfs.jffs2 file created in the examples above, the following commands should be used for a NAND flash with 128 KiB erase blocks:

developer@ldc:~$ sudo sumtool --input=emac-oe-rootfs.jffs2 --output=emac-oe-rootfs-summary.jffs2 \
--eraseblock=0x20000 --no-cleanmarkers

For a NOR flash with 128 KiB erase blocks, the no-cleanmarkers option is replaced by the pad option. Unfortunately there is no way to specify the padded size of the final image with sumtool, so summary images are not generally used on EMAC products with RedBoot. The command below will create a summary image for the NOR flash:

developer@ldc:~$ sudo sumtool --input=emac-oe-rootfs.jffs2 --output=emac-oe-rootfs-summary.jffs2 \
--eraseblock=0x20000 --pad