Difference between revisions of "Creating JFFS2 Images"

From wiki.emacinc.com
Jump to: navigation, search
(fixed code block line length)
 
(18 intermediate revisions by 5 users not shown)
Line 1: Line 1:
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.
+
{{todo|SEOKWREV (11.26.13-22:20->MD+)(12.10.13-12:00->MG+)(12.17.13-12:35->KY+)(02.26.14-15:30->MW+)(03.06.14-15:00->BS-);(04.11.14-10:45->BS+)|Mike Dean|project=oe 4,oe 5,md,SEOKWREV,mg,ky,bs}}
  
{{mbox | type = notice | text = This process requires that the mtd utilities packages is installed on the Linux PC. This may be done through the package manager or directly from source through the project website [http://www.linux-mtd.infradead.org/index.html Linux MTD].}} <br />
+
{{#seo:
 +
|title=Creating JFFS2 Images
 +
|titlemode=append
 +
|keywords=JFFS2,Nor Flash,Nand Flash,Linux MTD
 +
|description=This page describes the process of creating new images from existing JFFS2 images in order to resize, modify, or change parameters of the image.
 +
}}
 +
== Background ==
 +
JFFS2 (Journalling Flash File System version 2) 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.  JFFS2 supports NAND flash devices (used on all newer EMAC products), hard links, compression and garbage collection.
 +
 
 +
 
 +
This page describes the process of creating new images from existing JFFS2 images in order to resize, modify, or change parameters of the image. Please follow the steps in [[Mounting JFFS2 Images on a Linux PC | Mounting JFFS2 Images ]] to mount an existing JFFS2 image. The mounted directory structure will be used as the root directory for creating the new image.
 +
 
 +
{{mbox | type = notice | text = This process requires that the <code>mtd-utils</code> package is installed on the Linux PC. This may be done through the package manager or directly from source through the project website [http://www.linux-mtd.infradead.org/index.html Linux MTD].}} <br />
  
 
== Mkfs.jffs2 Usage ==
 
== Mkfs.jffs2 Usage ==
The <code>mkfs.jffs2</code> application is used to create JFFS2 images. The output of <code>mkfs.jffs2 --help</code> 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: priortiry)
 
  -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 <code>mkfs.jffs2</code> 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 <code>mkfs.jffs2</code> and specifying the directory tree to use for making the image using the <code>--root</code> option. The following sections discuss the system variables affecting JFFS2 images.
+
The <code>mkfs.jffs2</code> application is used to create JFFS2 images. 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 <code>mkfs.jffs2</code> and specifying the directory tree to use for making the image using the <code>--root</code> option. The following sections discuss the system variables affecting JFFS2 images. More information can be obtained by running <code>mkfs.jffs2 --help</code> and <code>man mkfs.jffs2</code>.
  
 
=== Erase Block Size ===
 
=== 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 <code>/proc/mtd</code> 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.
+
The erase block size of the flash must be determined before creating the JFFS2 image. This can be found through the contents of <code>/proc/mtd</code> 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.  
 +
 
 +
To determine the erase block size of a NAND flash from U-Boot run the following:
 +
U-Boot> nand info
 +
 
 +
The sector size reported corresponds to the erase block size.
 +
 
 +
 
 +
For example, 256 KiB erase block is reported as follows:
 +
Device 0: NAND 1GiB 3,3V 8-bit, sector size 256 KiB
  
 
=== Endianess ===
 
=== Endianess ===
Line 59: Line 42:
 
=== Padding ===
 
=== Padding ===
  
Padding is used to control the creation of additional JFFS2 nodes in the image beyond the nodes required to store the data in the files used to create the image. This option is not used with NAND flash images. For NOR flash, padding is typically added to the end of the last erase block by specifying the <code>--pad</code> 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, <code>--pad=0x1C00000</code> would be specified to create a padded image.
+
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 <code>--pad</code> 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.  
  
 
== Examples ==
 
== 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 <code>/tmp/rootfs</code> and save the image in the output file <code>emac-oe-rootfs.jffs2</code>.
+
After determining what parameters to use for the target system, the image can be created. The following are examples for different common system types. These examples assume that the root directory is located at <code>/tmp/rootfs</code> and the image in the output file is <code>emac-oe-rootfs.jffs2</code>.
  
 
; NAND Flash with 128 KiB Erase Blocks:  
 
; NAND Flash with 128 KiB Erase Blocks:  
Line 85: Line 70:
 
<code>Sumtool</code> 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.
 
<code>Sumtool</code> 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 <code>mkfs.jffs2</code>. Typically, the only options required to use <code>sumtool</code> are the eraseblock size, input file, output file, and whether cleanmarkers should be used. Other options may be listed by running <code>sumtool --help</code>. 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:
+
Summary JFFS2 images are created using an existing JFFS2 filesystem created with <code>mkfs.jffs2</code>. Typically, the only options required to use <code>sumtool</code> are the eraseblock size, input file, output file, and whether cleanmarkers should be used. Other options may be listed by running <code>sumtool --help</code>. 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 \
 
  developer@ldc:~$ sudo sumtool --input=emac-oe-rootfs.jffs2 --output=emac-oe-rootfs-summary.jffs2 \
 
  --eraseblock=0x20000 --no-cleanmarkers
 
  --eraseblock=0x20000 --no-cleanmarkers
  
For a NOR flash with 128 KiB erase blocks, the <code>no-cleanmarkers</code> option is replaced by the <code>pad</code> option. Unfortunately there is no way to specify the padded size of the final image with <code>sumtool</code>, so summary images are not generally used on EMAC products with RedBoot. The command below will create a summary image for the NOR flash:
+
For a NOR flash with 128 KiB erase blocks, the <code>no-cleanmarkers</code> option is replaced by the <code>pad</code> option. There is no way to specify the padded size of the final image with <code>sumtool</code>, 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 \
 
  developer@ldc:~$ sudo sumtool --input=emac-oe-rootfs.jffs2 --output=emac-oe-rootfs-summary.jffs2 \
 
  --eraseblock=0x20000 --pad
 
  --eraseblock=0x20000 --pad
 +
 +
== Using the Images ==
 +
 +
The JFFS2 file created above will need to be made available on a TFTP server for programming onto boards.  The [[Loading_JFFS2_Images_Onto_a_Board|Loading JFFS2 Images Onto a Board]] page describes how to load the image onto a board from a TFTP server.
  
 
[[Category:Filesystems]]
 
[[Category:Filesystems]]

Latest revision as of 10:48, 14 April 2014

TODO: {{#todo:SEOKWREV (11.26.13-22:20->MD+)(12.10.13-12:00->MG+)(12.17.13-12:35->KY+)(02.26.14-15:30->MW+)(03.06.14-15:00->BS-);(04.11.14-10:45->BS+)|Mike Dean|oe 4,oe 5,md,SEOKWREV,mg,ky,bs}}

Background

JFFS2 (Journalling Flash File System version 2) 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. JFFS2 supports NAND flash devices (used on all newer EMAC products), hard links, compression and garbage collection.


This page describes the process of creating new images from existing JFFS2 images in order to resize, modify, or change parameters of the image. Please follow the steps in Mounting JFFS2 Images to mount an existing JFFS2 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 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. More information can be obtained by running mkfs.jffs2 --help and man mkfs.jffs2.

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.

To determine the erase block size of a NAND flash from U-Boot run the following:

U-Boot> nand info

The sector size reported corresponds to the erase block size.


For example, 256 KiB erase block is reported as follows:

Device 0: NAND 1GiB 3,3V 8-bit, sector size 256 KiB

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.

Examples

After determining what parameters to use for the target system, the image can be created. The following are examples for different common system types. These examples assume that the root directory is located at /tmp/rootfs and the image in the output file is 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. 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. 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

Using the Images

The JFFS2 file created above will need to be made available on a TFTP server for programming onto boards. The Loading JFFS2 Images Onto a Board page describes how to load the image onto a board from a TFTP server.