Developer Resources: Board support packages; Foundry27 projects; Forums

QNX Technical Articles

QNX® Momentics® Flash Filesystem and Embedding Technology Development Kit 1.1.0 Release Notes

QNX® Momentics®

Date of this edition: August 16, 2006

Target OS: QNX^® Neutrino^® 6.3.0 SP1 or later

Host OS: Microsoft Windows XP SP1 or SP2, 2000 SP4, NT SP6a; Sun Solaris 7, 8, or 9; QNX^® Neutrino^® 6.3.0 SP1 or later; Linux Red Hat 8, 9, or Enterprise WS 3 or 4

For information on installing this TDK, see the installation note.
For the most up-to-date version of these release notes, log into your myQNX account, and then go to the Download Center area of www.qnx.com.
QNX Neutrino 6.3 supports only the new flash filesystem (FFS3). The older flash filesystem (FFS2) has been discontinued.
Extra documentation, code samples, and benchmarks are available for this TDK. Please look for the extra documentation folder in this TDK's folder in the Download Center.

What's in this TDK?
Flash TDK and BSPs
Fixed issues
Known issues
Documentation
Technical support

Throughout this document, you may see reference numbers associated with particular issues, changes, etc. When corresponding with our Technical Support staff about a given issue, please quote the relevant reference number. You might also find the reference numbers useful for tracking issues as they become fixed.

The content of the Flash Filesystem & Embedding TDK has changed since version 6.3.0. This TDK used to include precompiled flash driver binaries for BSPs; it now includes only the following flash driver binaries:

devf-ram
devf-i365sl (x86 only)
devf-generic (all targets except ARMBE)

You can compile all the other flash binaries from the source provided with the BSP source distribution, and then link them against the Flash Filesystem library included in this TDK.

What's in this TDK?

This TDK includes a more advanced flash filesystem and introduces the Embedded Transaction Filesystem (ETFS).

There are several reasons why you should consider upgrading to the Flash Filesystem & Embedding TDK version 1.1.0:

New support for NAND flash devices

Version 1.1.0 of this TDK with the ETFS (Embedded Transaction Filesystem) now has support for directly controlling NAND devices. Previous versions of the Flash Filesystem & Embedding TDK didn't have this support.

For information about ETFS, see the Filesystems chapter of the System Architecture guide.

Highlights of QNX ETFS and NAND include:

POSIX semantics
reliability through the use of transactions that are used for data and metadata. This ensures that even if a power loss or system failure occurs, the filesystem integrity remains high. After a restart or power-on, the log of previous transactions is analyzed; transactions are resumed up to the last partial or damaged transaction.
dynamic wear-leveling, which maximizes the life of a NAND device by using blocks in an even fashion. This involves recording the number of erase cycles for each block.
static wear-leveling, which manages data blocks so that the filesystem uses the flash blocks evenly. This is especially important when the filesystem consists of some files that are mainly read-only while others are written to often. Static wear-leveling helps to even out the erase cycles for all data blocks.
CRC Error detection on each transaction (with rollback support). If an error is detected, ECC error correction is used to recover the data to a new block, and then the weak block is marked for erasing.
read-degradation monitoring. Blocks are marked for refresh before hitting the normal read degradation limit. This avoids possible ECC errors and the need to recover data.
reduced metadata corruption. ETFS reduces the number of writes needed for metadata, thereby reducing the potential for error.
automatic file defragmentation. Write buffering is used to consolidate small write transactions before they're written to NAND; this helps avoid fragmentation. Background defragmentation happens automatically (but is preempted by user activity).
bad block support
bulk copy support
512-byte and 2048-byte blocks are supported.

Please note that NAND devices that are managed using Compact Flash interfaces, USB, PCMCIA etc. don't require the use of ETFS. ETFS is designed for directly controlling access to the NAND device.

If you wish to directly program NAND devices on your hardware, then you need ETFS for NAND, which is part of this TDK.

NOR Flash support update: new features and bug fixes

QNX Neutrino has a filesystem designed for NOR flash devices called FFSv3 (Flash Filesystem Version 3). The core features of this filesystem have remained the same since version 1.0.0 of the Flash Filesystem & Embedding TDK, but this version includes additional features and bug fixes.

The core features of the Flash Filesystem version 3 include:

POSIX semantics
background reclaim and wear-leveling. Sectors marked for reclaim are managed so that the NOR device wears evenly.
fault recovery. Although FFSv3 isn't based on transactions, updates to metadata are done in carefully executed sequences. This allows for high filesystem integrity even after power-loss.
After a reset or power-on, the FFSv3 scans the filesystem and restores data integrity where possible.
bad sector handling. Sectors with errors are recorded and transparently avoided.

New features of FFSv3 in the Flash Filesystem & Embedding TDK 1.1.0 include:

support for pwrite() and pread()
flashctl supports the -F option.
The older flashctl and devf-* drivers (from version 1.0.0 of this TDK) check the bounds on the -o and -l arguments to flashctl, to ensure that the requested range falls within the partition specified by the -p option. If a partition becomes corrupted, the partition layout can change. If recovery code uses flashctl to erase and reformat a partition, the partition number may have changed.
The -F option lets you specify the fixed-position /dev/fs0p0 to the -p option, and give offsets relative to the start of flash for erasing and formatting. The flashctl utility determines what the correct argument for the -p option should have been to get the desired offset and issues the corrected command to the driver.
dumpefs can display FFSv3 images.
wear-leveling algorithms have been improved.
flash drivers now support a -R option that forces all flash partitions to be initially mounted as read-only. After the flash driver starts, you can remount selected partitions as read/write.

There have been significant bug fixes in the new FFSv3 filesystem that version 1.1.0 of this TDK includes. These bug fixes involve areas of:

mount and umount
wear-leveling algorithms
disk-full conditions
recovery after power-loss
new errata on flash chip behavior
As chip errata are released, we'll implement design changes as required. One such design change involved AMD Mirrorbit flash. Timings on write were modified, as well as the behavior of suspend/resume on erase cycle. Also please note that Spansion parts are now being recommended as the successor to the Mirrorbit parts.

FAQ

Should I upgrade to the new FFSv3 filesystem?

If you are an existing user of FFSv3 with the Flash Filesystem & Embedding TDK 1.0.0, then you should seriously consider upgrading to version 1.1.0. This is especially important if your target system has any of the following characteristics:

The flash device is used for storing data (writable).
The target system can lose power in an uncontrolled way. For example, power could be lost during a data write.
The flash device can reach disk full condition.
You are unmounting and remounting the flash filesystem.

What concerns should you have about updating to Flash Filesystem & Embedding TDK 1.1.0?

As with any upgrade, we recommend that you thoroughly test the target system behavior in the laboratory before installing in the field. The only update concerns involve NOR flash:

The Flash Filesystem & Embedding TDK 1.1.0 is data-compatible with version 1.0.0. This means that EFS files created with the older version will mount correctly with the new version. You can start the new devf-* driver on your target system without having to reformat the flash.
There is a behavioral change when using the umount() function or the umount command in the new Flash Filesystem & Embedding TDK 1.1.0; umount() now sets errno to EBUSY if the filesystem is in use, unless you use the FORCE option (-f flag or _MOUNT_FORCE flag).

How do I upgrade to the new FFSv3 filesystem?

You must first install the Flash Filesystem & Embedding TDK 1.1.0 by following the instructions in the installation note. Then you must recompile and relink the devf-* driver that's specific to your target system.

The new features of the FFSv3 filesystem are contained in the libfs-flash3.a library. Make sure that the new libfs-flash3.a library is being properly linked with your devf-* driver.

The recommended place for the new libfs-flash3.a library is $QNX_TARGET/$CPU/usr/lib, where the CPU environment variable identifies the target processor (e.g. ppcbe).

There's a prebuilt version of the libfs-flash3.a library that's copied to the usr/lib directory for each CPU target. This means that to update to the new libfs-flash3.a library, you need only to recompile and relink the devf-* driver for your target.

Binaries

The following binary files are installed under $QNX_TARGET/, under the subdirectories for each supported target-platform:

ARMBE
- armbe/lib/libetfs.a
- armbe/sbin/devf-ram
- armbe/sbin/fs-etfs-ram
- armbe/sbin/inflator
- armbe/usr/bin/flashctl
- armbe/usr/bin/etfsctl
- armbe/usr/lib/libflash-nand.a
- armbe/usr/lib/libfs-flash3.a
ARMLE
- armle/lib/libetfs.a
- armle/sbin/devf-ram
- armle/sbin/devf-generic
- armle/sbin/fs-etfs-ram
- armle/sbin/inflator
- armle/usr/bin/flashctl
- armle/usr/bin/etfsctl
- armle/usr/lib/libflash-nand.a
- armle/usr/lib/libfs-flash3.a
MIPSBE
- mipsbe/lib/libetfs.a
- mipsbe/sbin/devf-ram
- mipsbe/sbin/devf-generic
- mipsbe/sbin/fs-etfs-ram
- mipsbe/sbin/inflator
- mipsbe/usr/bin/flashctl
- mipsbe/usr/bin/etfsctl
- mipsbe/usr/lib/libflash-nand.a
- mipsbe/usr/lib/libfs-flash3.a
MIPSLE
- mipsle/lib/libetfs.a
- mipsle/sbin/devf-ram
- mipsle/sbin/devf-generic
- mipsle/sbin/fs-etfs-ram
- mipsle/sbin/inflator
- mipsle/usr/bin/flashctl
- mipsle/usr/bin/etfsctl
- mipsle/usr/lib/libflash-nand.a
- mipsle/usr/lib/libfs-flash3.a
PPCBE
- ppcbe/lib/libetfs.a
- ppcbe/sbin/devf-ram
- ppcbe/sbin/devf-generic
- ppcbe/sbin/fs-etfs-ram
- ppcbe/sbin/inflator
- ppcbe/usr/bin/flashctl
- ppcbe/usr/bin/etfsctl
- ppcbe/usr/lib/libflash-nand.a
- ppcbe/usr/lib/libfs-flash3.a
SHLE
- shle/lib/libetfs.a
- shle/sbin/devf-ram
- shle/sbin/devf-generic
- shle/sbin/fs-etfs-ram
- shle/sbin/inflator
- shle/usr/bin/flashctl
- shle/usr/bin/etfsctl
- shle/usr/lib/libflash-nand.a
- shle/usr/lib/libfs-flash3.a
x86
- x86/lib/libetfs.a
- x86/sbin/devf-ram
- x86/sbin/devf-generic
- x86/sbin/devf-i365sl
- x86/sbin/fs-etfs-ram
- x86/sbin/inflator
- x86/usr/bin/flashctl
- x86/usr/bin/etfsctl
- x86/usr/lib/libflash-nand.a
- x86/usr/lib/libfs-flash3.a
Header files
- usr/include/sys/nand.h
- usr/include/sys/dcmd_f3s.h
- usr/include/sys/dcmd_mem.h
- usr/include/sys/f3s_api.h
- usr/include/sys/f3s_flash.h
- usr/include/sys/f3s_socket.h
- usr/include/sys/f3s_spec.h
- usr/include/sys/f3s_comp.h
- usr/include/fs/f3s_api.h
- usr/include/fs/f3s_flash.h
- usr/include/fs/f3s_socket.h
- usr/include/fs/f3s_spec.h
- usr/include/fs/etfs.h

Source code

This TDK includes the source to the lib/flash-nand.a library, as well as for the following binaries:

fs-etfs-ram
etfsctl
flashctl
inflator

After you've installed the source bundle, you can find the associated archive in $QNX_TARGET/usr/src/archives/qnx/tdk-efsys-src.zip.

If you have QNX Momentics PE, you can compile the source using the IDE or the command-line tools; if you have SE, you have to use the command-line tools.

Compiling with the IDE

Once you've installed the TDK, you can simply import the source into a project by doing the following:

Start the IDE.
Select File-->Import and select QNX Source Package.
Select the source package that you want to import, then follow the instructions on the screen.

Compiling with the command-line tools

Here's how to compile the source from the command line:

Decompress the archive:
- On Windows, use Winzip.
- On Linux, Solaris, and QNX Neutrino, type:
```
unzip -d dirname $QNX_TARGET/usr/src/archives/qnx/tdk-efsys-src.zip
    
```
  where dirname is the directory where you'd like to put the source files.
On Windows, start a bash shell in which to run the commands below.
Go to the directory where you saved the source:
```
cd dirname
  
```
Run the setenv.sh script to configure the environment to build things locally and not install over any existing binaries:
```
. ./setenv.sh
  
```
Type make to build the software. You'll find the results of the build in the dirname/install directory.

Flash TDK and BSPs

Once you've installed both the Flash TDK as well as a BSP that supports flash devices, you must rebuild your OS image in order to incorporate flash support. To do this, you'll need to modify the buildfile that generates the image.

The location of the buildfile depends on the type of BSP; for more information, see the Working with a BSP chapter of the Building Embedded Systems guide.

The general steps are as follows:

Locate the following lines in your buildfile:
```
# devf-name_of_board
# flashctl
```
where name_of_board identifies the specific flash driver (e.g. devf-mgt5200). Note that your buildfile may call the devf-generic driver.
Uncomment those two lines by deleting the # character at the start of each line.
Now generate a new OS image from your modified buildfile (e.g. mkifs buildfile).

For details, see the Working with a BSP chapter of the Building Embedded Systems guide.

Fixed issues

This version of the TDK addresses the following issues in the devf-* drivers:

Unmounting a flash filesystem and raw partitions returns EBUSY if some other process is using the filesystem, unless the you specify the -f (force) flag, in which case the unmount takes effect immediately, and any pending I/O is lost. (Ref# 25759)
inflator now publishes a different decompressed mountpoint. (Ref# 24894)
devf-* resource managers now have the -R option, which causes automounted filesystem partitions to be mounted read-only. (Ref# 24811, 24183)
The flash filesystem resource managers no longer crash if an open() request fails because the filesystem is full. (Ref# 24449)
devf-ram no longer marks flash extents as deleted when they shouldn't be. (Ref# 24411)
The flash driver no longer crashes during a write-error simulation test. (Ref# 24337)
devf-ram: mmap() no longer hangs. (Ref# 24291)
The devf-ram driver no longer faults while unarchiving tar archives. (Ref# 23862)
devf-bigsur no longer crashes with a SIGSEGV when it's writing data to a small number of files on a full flash partition. (Ref# 23855)
devf-ram no longer deadlocks on x86 SMP targets. (Ref# 23807)
devf-ram no longer deadlocks during a truncate(). (Ref# 23806)
devf-ram no longer faults when one process calls truncate() and another calls open() specifying O_TRUNC on the same file. (Ref# 23687)
devf-ram: calling truncate() and mkdir() when the disk is full no longer corrupts the filesystem. (Ref# 23681)
devf-ram: truncate() now behaves correctly when the disk is full. (Ref# 23674)
df now correctly reports the mount flags for a flash filesystem. (Ref# 23647)
devf-ram no longer corrupts deallocated memory because of I/O operations that were allowed to take place after the partition had been unmounted. This corruption also manifested itself as deadlocks because mount() and umount() code was taking attribute locks in a different order than I/O operations. (Ref# 23644, 23645)
devf-ram: multiple mountpoints now show up correctly in the output from df. (Ref# 23637)
If any Status bit fields in an extent header are corrupted, the entire block is no longer erased, because it's possible to recover from this type of corruption. (Ref# 23572)
An example in the entry for flashctl in the Utilities Reference has been corrected. (Ref# 23003)
The documentation for flashctl now explains that, for devf-ram partitions only, you must format and erase a partition before you can mount the flash filesystem. Otherwise, you may get an error message flashctl: mounting partition failed. (Ref# 23002)

Foreground reclaiming of small files no longer leads to improper wear-leveling. (Ref# 22901)

The fix for this issue has the side effect of doubling the time that a reclaim operation requires. The new wear-levelling code generates twice as many erase cycles as the old code, but these erasures are divided evenly among all blocks in the partition, resulting in lower maximum erase counts.

devf-*: i28f008_reset no longer causes a SIGBUS when the offset is unaligned. (Ref# 21710)
devf-*: A reclaim failure no longer causes a double call to F3S_UNIT_LEAVE(). (Ref# 21404)
inflator no longer relies on an implicit override of iofunc_ocb_calloc(). (Ref# 21382)
inflator now displays the correct message if you run it as a non-root user. (Ref# 21117)
inflator now correctly reports information about links in flash filesystems. It used to give the information about the file that the link pointed to. (Ref# 20744)
flashctl now has an -F option that you can use if you need to use offsets outside of the specified partition. (Ref# 20519)
dumpefs now supports FFS3 images. (Ref# 20385)
libfs-flash3 now defines SYMLINK_MAX. (Ref# 19208)
libfs-flash3 now correctly handles O_EXCL and O_CREAT with symbolic links (i.e. open() fails and sets errno to EEXIST, regardless of the contents of the symbolic link). (Ref# 18913)
libfs-flash3 no longer ignores a trailing slash when resolving symbolic links. (Ref# 18902)
devf-ram no longer supports the -c option. (Ref# 18734)
devf-ram no longer fails to work if you start it after you've started devf-generic. (Ref# 18733)
_PC_NAME_MAX is now correctly 255 for libfs-flash3. (Ref# 18519)
libfs-flash3 now supports pread() and pwrite() for UNIX98 support. (Ref# 18517)
libfs-flash3: mkfifo() now sets errno to EEXIST instead of to ENODIR if the given path is too long. (Ref# 18513)
flashctl no longer lets you specify -p/dev/fs0p0 -f on partitions other than fs0p0. (Ref# 11736)

Known issues

If you're using QNX Momentics 6.3.0 SP1, you'll need to download the mkxfs patch (patch ID 104) from our website and install it. QNX Momentics 6.3.0 Service Pack 2 incorporates this patch. (Ref# 24147, 24213, 25770)
In previous versions of this TDK, a program that called umount() without the _MOUNT_FORCE flag would behave as if the flag was provided (i.e. the flash filesystem would be unconditionally unmounted regardless of any operations either pending or in progress on the filesystem).
In this version of the TDK, umount() sets errno to EBUSY if any pending or in-progress flash filesystem operations exist on the filesystem unless you specify _MOUNT_FORCE. The same applies for scripts that call the umount utility without the -f option. This has implications for applications that expect _MOUNT_FORCE behavior but don't specify it.
libfs-flash3 loses blocks with ftruncate(). (Ref# 25132)
There's a memory leak of approximately 1 KB when you unmount a raw flash filesystem partition (e.g. dev/fsxpy). (Ref# 23643)
ETFS: file creation doesn't update parent directory times as POSIX requires. (Ref# 23243)
There's currently no flash probe utility. (Ref# 23136)
libfs-flash3 doesn't have an iofdinfo() handler for mtree tests. (Ref# 18432)
If you create a 255-character filename using the TDK 1.1.0 flash library (libfs-flash3) and the flash filesystem is subsequently mounted using an earlier version of libfs-flash3, the filename won't appear in the filesystem, but it is still present (i.e. if the filesystem is subsequently mounted again with the TDK 1.1.0 libfs-flash3, the filename will reappear). This behavior applies only to forward compatibility whereby an older flash filesystem library is used to mount a newer filesystem. Backward compatibility (the ability of the new filesystem library to mount older filesystems) isn't affected.
During a power failure, the flash filesystem can be corrupted if the NOR device's power supply is in the indeterminate state. The solution is to design the hardware so that the NOR flash device enters RESET the moment the power supply drops below the proper operating range. (Ref# 24679)
During a reclaim copy, if the last bit is set incorrectly, the flash filesystem won't notice until after it has copied the incorrectly set head. (Ref# 20149)
Due to the 32 MB limit on the virtual address space on ARM processors, devf-ram can't open a flash disk larger than 8 MB. (Ref# 25614)
If two or more instances of inflator are running with the same mountpoint arguments, the string Inflator: Unable to reserve a device number (errno) is printed. The message should include the string This is most likely caused by running two instances on the same mointpoint. (Ref# 21118)
In Microsoft Windows, certain programs (e.g. Norton Ghost) add directories inside double quotation marks (e.g. ...;"c:\Program Files\Norton Ghost\";...) to your PATH environment variable. This causes the Cygwin spawn() function to fail, which in turn causes cp to fail when called by ln-w. (Ref# 20046)
Workaround: Modify your PATH environment variable and remove any quotation marks.

Be sure to check the QNX Momentics release notes for related issues.

Documentation

The functionality provided by the TDKs is already described within the QNX Momentics documentation set. For information on flash, see:

Filesystems chapter of the System Architecture guide
Working with Filesystems chapter of the Neutrino User's Guide
Customizing the Flash Filesystem chapter of Building Embedded Systems
devf-* entries in the Utilities Reference

The documentation doesn't yet include the following:

etfsctl
fs-etfs-ram
mketfs

so we've included them below.

`etfsctl`

Control an embedded transaction filesystem for RAM/SRAM

Syntax:

etfsctl [options]

Runs on:

ARM, MIPS, PowerPC, SH4, x86, and XScale processors

Options:

-c

Make the filesystem on the device continue or resume operations.

-d device

Connect to the specified device.

/dev/etfs1: Raw partition for boot images.
/dev/etfs2: Filesystem partition for etfs files.

-D

Request a defragmentation operation on the .filetable for the ETFS filesystem. The background processing of the ETFS filesystem does its own defragmenting as needed. This option lets you force it to happen on demand.

-e

Erase the device. For NAND flash, factory-marked bad blocks aren't erased. Blocks that become bad during normal use (worn-out blocks) are also skipped during the erasing.

-f

Erase as in -e, then format an empty filesystem. Don't use this option with -w, since -w assumes an erased partition with no filesystem.

-i

Print info about the filesystem. See the “Description” below.

-r file

Read all data from the device and save it in the specified file. The data is saved as a series of transactions. This data can be written to another flash part as long as that part has the same:

cluster size
block size (number of clusters in a block)

The data format is endian-neutral and free of any device-specific characteristics such as how it stores CRCs or ECCs. You can now read and write filesystems across different classes of devices, for example for NAND and RAM.

-R file

Read all data from the device, including blank or erased blocks, and save it in the specified file. This is the raw version of -r option.

-s

Stop the filesystem on the device.

-S

Similar to -s, but wait for the filesystem to stop before returning.

-w file

Write transactions from the specified file to the device. This transaction file can be created by reading it from this or another device via the -r option of etfsctl or by the mketfs utility. The transactions are block-location-independent on the device. This allows bulk programming of devices with bad blocks in any location. The only requirement is that enough good blocks should be available to hold all transactions.

-W file

Write transactions from the specified file to the device. Also, copy any blank or erased blocks. This is a raw version of the -w option.

Description:

The etfsctl utility is used to manage an embedded transaction filesystem (ETFS). The utility interacts with the running filesystem using devctl() messages. Using etfsctl, you can erase and format a partition, read or write an entire transaction log (and thus its entire filesystem) from or to the device, stop the filesystem, make it continue or get statistical information.

Options are processed from left to right in order. The first option must be a -d device where:

/dev/etfs1: Raw partition for boot image.
/dev/etfs2: Filesystem partition for etfs files.

The raw partition is used for boot images and is always at the start of the device. It may be zero bytes long if no boot image is needed. The filesystem partition consists of a series of transactions that together form a filesystem. You can use the -r option to read the transactions from the device and save them to a regular file, typically on another filesystem. You can then use the -w option to write this transaction log to another ETFS filesystem.

When writing, you must erase the filesystem first; failure to do so corrupts the data on the device.

Another application can be written as follows:

etfsctl -d /dev/etfs1 -e -w image.ifs

The -w option is most often used to write transaction logs created by the mketfs utility.

You can request the filesystem to stop accepting new open requests by using the -s or -S option. Once the last file currently open by any application is closed, the filesystem enters the stopped state. A filesystem partition must be stopped in order for you to write a transaction log to it. You can start the filesystem again using the -c option.

The -i option provides useful statistical information about a running filesystem. This option is so common that it assumes /dev/etfs2, thus saving you from having to enter the -d option before it. The information is displayed in following groups:

Device
Pools
Counts
Errors

Device

Name: Name of the device. The name usually encodes a part number or size.
Blocks: Number of blocks on the device.
Clusters/Block: Number of clusters to a block on the device.
Clustersize: Size of a cluster. Typically 1 KB or 2 KB.
Totalsize: Total size of the device, in bytes.

Pools

Clean: Number of erased blocks immediately ready for writing.
Spare: Number of spare blocks.
Filthy: Number of free blocks that are waiting to be erased and made clean.
Inactive: Number of clusters not being used but trapped.
Xpool: Number of cache buffers.
Cache: Number of cluster cache buffers.

Counts

Erase: Number of erases on the part (while running).
Avg: Average erase count per block.
Read: Number of cluster reads from the device.
Cache: Number of cluster reads from cache.
Write: Number of cluster writes to the device.
Mine: Number of mining operations to recover dead space in a block. This is how inactive clusters create filthy blocks, which become clean after being erased.
Copy: Number of block-copy operations. Copies occur two ways: the first way is a read in a block that has a soft ECC error, which is an indication that the block is getting weak. The block is copied to a new fresh block and the block with the ECC error is erased. In the second way, a block with a low erase count is forced into service by copying its data to a new block and erasing and putting this block into service.
Defrag: Number of files defragmented.
BadBlks: Number of blocks marked as bad and taken out of service

Errors

Ecc: Number of CRC data errors that are corrected by ECC.
Chksum: Number of CRC data errors.
Device: Number of hard device errors. This is bad and usually indicates a hardware problem.

The error statistics currently aren't collected, so these values are always 0.

Examples:

Print information about a filesystem. If you omit the -d option, etfsctl assumes /dev/etfs2.

etfsctl -i
etfsctl -d /dev/etfs2 -i

Write a boot image built by mkifs into the raw partition:

etfsctl -d /dev/etfs1 -e -w image.ifs

Format an empty filesystem:

etfsctl -d /dev/etfs2 -S -f -c

Write a filesystem built by mketfs:

etfsctl -d /dev/etfs2 -S -e -w fsys.etfs -c

Write a boot image and a filesystem:

etfsctl -d /dev/etfs1 -e -w image.ifs -d /dev/etfs2 \ 
-S -e -w fsys.etfs -c

Save entire filesystem. Erase the part, and restore the filesystem:

etfsctl -d /dev/etfs2 -r debug.etfs
etfsctl -d /dev/etfs2 -S -e -w debug.etfs -c

`fs-etfs-ram`

Embedded transaction filesystem for RAM/SRAM

Syntax:

fs-etfs-ram [common-options] [-Ddriver-options]

Runs on:

ARM, MIPS, PowerPC, SH4, x86, and XScale processors

Options:

Common options

-a

Update access times (atime). Default is to not update atime, to reduce the number of flash writes.

-b priority

Run background reclaim at this priority. Default is 8.

-B

Don't detach and run in the background. This is useful for debugging.

-c nclusters

Set the cache size. The cache holds recently read clusters in RAM, reducing the need to access the device if the same cluster is read again. It's also used to combine small writes into larger writes consisting of multicluster transactions. This reduces file fragmentation across the device and improves filesystem startup time. Since most devices are very fast, a small cache is usually acceptable. Larger caches may be desirable if many files are being written with small writes concurrently. The default value is 64 clusters, where cluster size is usually 1 KB or 2 KB, depending on the device.

-C 0|1|2

Disable error checking/correction.

0: No CRC check, no ECC correction (RAM).
1: CRC check, no ECC correction (SRAM or NOR Flash).
2: CRC check, ECC correction (NAND Flash).

Default: use CRCs for error checking and ECCs for error correction.

-e

Erase the device and create an empty filesystem that is ready to use. For NAND flash, factory-marked bad blocks are not erased. Blocks that become bad during normal use (worn-out blocks) are also skipped during the erasing.

-f numfiles

Set maximum number of files. The default value is 4096, with a maximum of 32,767.

-F num

Defragment if the average extent is less than num clusters. The value of num must be in the range from 0 through 16. Default is 6. The fs-etfs-ram utility doesn't defragment if num is 0.

-I

Perform internal integrity checks of internal data structures while the filesystem is running. This slows down the filesystem. Its main purpose is for debugging new drivers and new versions of the filesystem.

-m mountpoint

Set the directory for fs-etfs-ram to use as its mountpoint. On an embedded system where ETFS is the major filesystem, this is set as -m / for taking over the root. Default is /fs/etfs.

-o numattr

Set the number of attributes to cache, which speeds up opens slightly. Default is 8.

-r kbytes

Set the size of the raw partition /dev/etfs1, in kilobytes. This partition, if present, is typically used to hold a boot image made using the mkifs utility. The default size is 0.

-R

Reserve a percentage of the flash to avoid issues that arise when a flash device becomes completely full. Default is 5% (of the device size).

-S

Implement transaction checksum using a fast and simple sum calculation rather than the default polynomial CRC algorithm. This may be faster but less robust.

-s num

Set the number of flash blocks to use as spares. One spare block is required to perform a reclaim. During normal operation, flash devices wear, which causes flash blocks to fail. More than one spare block provides extra redundancy. Default is 4.

-t sec

Set a timer for background operations. Default is 5 seconds.

-v[v...]

Set verbosity. Each -v increases verbosity.

-W erasediff

Set wear-leveling span. Allow flash blocks to have erase counts that differ by more than erasediff before attempting to either :

force them into service if they are below erasediff
Or:
give them a rest if they are above erasediff.

The default value is 50.

-x nextents

Cache this number of file extent offsets. This option reduces the processing needed to read through file extents on the device. Default is 8.

Driver options

use: Get a list of driver-specific options. This option causes the filesystem to print a usage message and then terminate without accessing the device.
size=nnM: Set the size of the RAM disk to nn megabytes. Default is 16 MB.

Description:

The embedded transaction filesystem (ETFS) implements a high-reliability filesystem for use with embedded solid-state memory devices with particular attention to NAND flash memory. The filesystem supports a fully hierarchical directory structure with POSIX semantics as shown in the table below:

POSIX capability	Supported by ETFS
Access date	Yes (if enabled with -`a` command-line option)
Modification date	Yes
Status change date	Yes
Max filename length	91 characters
User permission	Yes
Group permissions	Yes
Other permissions	Yes
Directories	Yes
Hard links	No
Symbolic links	Yes

When started, ETFS creates two devices as follows:

/dev/etfs1: Raw partition for boot image
/dev/etfs2: Filesystem partition for etfs files.

The raw partition is used for boot images and is always at the start of the device. It may be zero bytes long if no boot image is needed. The filesystem partition is mounted in the pathname space as specified by the -m option. If the -m option is absent, the default mountpoint is /fs/etfs.

ETFS is a filesystem composed entirely of transactions. Every write operation, whether of user data or filesystem metadata, consists of a transaction. A transaction either succeeds or is treated as if it never occurred.

For more information, see “Embedded transaction filesystem (ETFS)” in the Filesystems chapter of the System Architecture guide.

Examples:

Start ETFS to implement a temporary filesystem in RAM mounted at /tmp. Since it's not persistent across a reboot, and since RAM is reliable, you should disable all data error detection and correction (-C 0). The -e option initializes an empty filesystem ready to go upon startup. Since the filesystem is in high-speed RAM, you should specify the smallest cache possible with the -c 0 option.

fs-etfs-ram -C 0 -e -c 0 -m /tmp

Caveats:

Although ETFS supports most POSIX semantics, some functionality isn't implemented in order to keep the driver simple and efficient. The unsupported POSIX semantics include:

Hard links, and related links. For example the . and .. directories aren't returned in a readdir(). Symlinks are fully supported.
Access times aren't updated on the media unless the -a option is specified, to reduce flash writes.
The parent directory's modification time isn't updated when the directory content changes (files are created or deleted).

`mketfs`

Build an embedded transaction filesystem (QNX)

Syntax:

mketfs  [-l inputline] [-nv] [buildfile [outputfile]]

Options:

-l inputline: (“el”) Process inputline before interpretation of the buildfile begins. Input lines given to mketfs should be quoted to prevent interpretation by the shell (as mketfs input lines often contain spaces). Multiple -l options are processed in the order specified. No default.
-n: Don't use timestamps in the files. Using the -n option permits identical images in binary format. Specifying additional -n options strips all time information from files.
-v[v..]: Operate verbosely. Specifying additional -v options increases verbosity. Default is quiet operation.

Description:

The mketfs utility reads a text buildfile describing an embedded transaction filesystem (ETFS) and produces a binary image file containing the ETFS as a sequence of transactions. You can copy this file to flash at a later stage, using etfsctl.

Don't confuse this command with mkifs, which builds an OS image filesystem, or mkefs, which builds an embedded filesystem.

The input and output files are specified on the command line:

buildfile: The filename of the buildfile that describes the contents of the embedded filesystem; use “-” to specify standard input (the default).
outputfile: The filename of the image file containing the ETFS; use “-” to specify standard output (the default). Note that you can specify the outputfile only if you specified a buildfile.

Buildfiles

The buildfile uses the same grammar as the mkifs command, but supports different attributes.

The buildfile is basically just a list of files that you want to be included in the ETFS image file when it's built by mketfs. As well as the files to be included, you can specify various attributes that are used to set parameters of the filesystem and the files in it. For example, you can specify the maximum size of the filesystem, or the user and group IDs of the individual files.

You can't use a backslash (\) to break long lines into smaller pieces.

In a buildfile, a pound sign (#) indicates a comment; anything between it and the end of the line is ignored. There must be a space between a buildfile command and the pound sign.

Each line is in the form:

[attributes] file_specification

where the attributes (with the enclosing square brackets) and the file specification are both optional.

Attributes provide information about the file following the attribute. They're enclosed in square brackets; when combining attributes (e.g. to specify both the user ID and the group ID), enclose both attribute tokens in the same pair of square brackets. For example:

# correct way
[uid=5 gid=5] filename

# incorrect way
[uid=5] [gid=5] filename

There are two types of attributes:

boolean attributes: Those prefixed with a plus (“+”) or minus (“-”) sign.
value attributes: Those ending with an equals sign (“=”) followed by a value. Don't put any spaces around the equals sign.

A question mark (?) before an attribute makes the setting conditional. The attribute is set only if it hasn't already been set. For example, ?+bigendian sets the +bigendian attribute only if +bigendian or -bigendian hasn't already been set.

The file_specification takes one of the following forms:

path

The path is the same on the host as in the image.

target_path=host_path

The specified file or contents of the specified directory are fetched from the host filesystem and placed into the image.

target_path={contents}

An inline definition. The contents of the file are listed within the buildfile itself, enclosed in braces ({ }) — the file doesn't exist on the host system anywhere. The contents of the inline file can't be on the same line as the opening or closing brace.

The mketfs utility doesn't parse the contents of an inline file for anything but the closing brace. For example, mketfs doesn't interpret a pound sign (#) in an inline file as the beginning of a comment. The syntax of the inline file depends on what it's used for on the target system.

Closing braces (}) and backslashes (\) in an inline file must be escaped with a backslash.

You can enclose a filename in double quotes ("") if it includes spaces or unusual characters.

Attributes

The mketfs command supports the following attributes:

+|-bigendian
block_size=bsize
cd=filename
cluster_size=csize
dperms=dperm_spec
filter=filter_spec
+|-followlink
gid=id_spec
mount=filename
num_blocks=num
+|-optional
perms=perm_spec
prefix=prefix_spec
search=path:path…
type=file_type
uid=id_spec

You should explicitly specify the cluster_size, block_size and num_blocks attributes as appropriate for your flash device to ensure that the image produced is fully compatible with your specific device.

An OR-bar indicates that either the first element or the second element must be present, but not both (e.g. +|- bigendian means either +bigendian or -bigendian, but not +-bigendian).

`bigendian` attribute (boolean)

+|-bigendian

Set the byte order for the embedded filesystem to either big (via +bigendian) or little (via -bigendian) endian. The default is little endian.

`block_size` attribute

block_size=bsize

Set the block size for the ETFS. The block size depends on what memory device you have in your target hardware. The default block size is 16 KB.

`cd` attribute

cd=filename

Set the current working directory to the specified pathname before attempting to open the host file. Default is the directory from which mketfs was invoked.

`cluster_size` attribute

cluster_size=csize

Set the cluster size for the ETFS. The cluster size depends on what memory device you have in your target hardware. The default cluster size is 1 KB.

`dperms` attribute

dperms=dperms_spec

Set the access permissions of the directory. If specified as a number, the permissions are set to that number (just like the chmod command). If specified as an asterisk (*), the host directory's permissions are used; for an inline directory, the permissions are obtained from the umask of the user running mketfs. Otherwise, a symbolic mode string (which is a subset of chmod's) is used to delete, add, or set permissions.

The symbolic mode string consists of:

a combination of u, g, o, and a
one of -, =, or +
a combination of r, w, x, s, g, and t.

You can include more than one symbolic mode string, separating them with a comma (,).

The default dperms_spec is *.

`filter` attribute

filter=filter_spec

Run the host file through the filter program specified, presenting the host file data as standard input to the program and using the standard output from the program as the data to be placed into the embedded filesystem. Default is no filter.

`followlink` attribute (boolean)

[+|-followlink]target_path=host_path

If you specify +followlink or omit it, mketfs follows any links and makes target_path a copy of host_path.

If you specify -followlink, mketfs creates a link called target_path that points to whatever host_path points at. It's up to you to make sure that the file pointed to is placed in the image.

`gid` attribute

gid=id_spec

Set the group ID number for the file. The value of this attribute may be either a number or an asterisk (*). If it's an asterisk, the group ID is taken from the host file; for an inline file, the group ID is the group of the user running mketfs. The default value for this attribute is *.

`mount` attribute

mount=filename

Specify the mountpoint for the ETFS. This option is ignored for mketfs. You can set the mountpoint with the -m option to the fs-etfs-ram command.

The default is "", which makes the ETFS drivers (fs-etfs-*) use the appropriate default, usually /fs/etfs.

`num_blocks` attribute

num_blocks=num

Set the number of blocks in the ETFS. If the number of blocks is specified, then the image file will be padded out to that size.

`optional` attribute (boolean)

+|-optional

If true, and the host file can't be found, output a warning and continue building the embedded filesystem. If false, and the host file can't be found, output an error message and exit mketfs. The default is false.

`perms` attribute

perms=perms_spec

Set the access permissions of the file. If specified as a number, the permissions are set to that number (just like the chmod command). If specified as an asterisk (*), the host file's permissions are used; for an inline file, the permissions are obtained from the umask of the user running mketfs. Otherwise, a symbolic mode string (which is a subset of chmod's) is used to delete, add, or set permissions.

The symbolic mode string consists of:

a combination of u, g, o, and a
one of -, =, or +
a combination of r, w, x, s, g, and t.

You can include more than one symbolic mode string, separating them with a comma (,).

The default perms_spec is *.

When running on a Windows host, mketfs cannot get the execute (x) permissions from the file. Specify the permissions of executable files using the perms attribute.

`prefix` attribute

prefix=prefix_spec

Set the prefix on the target file names. The default is the empty string.

`search` attribute

search=path:path:…

This attribute specifies that mketfs should search for the file in the named locations on the host system. The search directory portion of the host file name isn't included in the name that's stored in the ETFS.

`type` attribute

type=file_type

Sets the type of the files being created in the ETFS. Allowable types are:

link — a symbolic link
file — a regular, everyday file (the default)
dir — a directory.

Specifying [type=dir] tells mketfs to make the named file a directory; you don't need to specify the type when you're copying the contents of a directory. For example, this command:

[type=dir]/usr/bin=/usr/nto/x86/bin

marks all the contents of /usr/bin as directories. To copy /usr/nto/x86/bin to /usr/bin, you just need to specify:

/usr/bin=/usr/nto/x86/bin

`uid` attribute

uid=id_spec

Set the user ID number for the file. The value of this attribute may be either a number or an asterisk (*). If it's an asterisk, the user ID is taken from the host file; for an inline file, the user ID is the user running mketfs. The default value for this attribute is *.

Examples:

Here's a sample buildfile, my_etfs.bld:

# A sample buildfile for mketfs

[cluster_size=1k block_size=64k num_blocks=240]
/home/jgarvey/nto_flash

In this example, we've specified a cluster_size of 1 KB, a block_size of 64 KB and a total device size of 240 blocks (which is the default configuration of fs-etfs-ram). The files and subdirectories from the /home/jgarvey/nto_flash directory on the host system are to be recursively copied into the root directory of the ETFS.

To create an ETFS image file using the above buildfile, invoke mketfs as follows:

mketfs my_etfs.bld my_image.etfs

This creates the my_image.etfs file containing the ETFS filesystem, which can then be copied to the target system as follows:

etfsctl -d /dev/etfs2 -S -e -w my_image.etfs -c

Exit status:

0: Successful completion.
1: An error occurred.

Technical support

If you have any questions, comments, or problems with a QNX product, please contact Technical Support. For more information, see the How to Get Help chapter of the Welcome to QNX Momentics guide or visit our website, www.qnx.com.