[Previous] [Contents] [Index] [Next]

Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

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:

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.


Caution: 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

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.

Note:

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

See also:

fs-etfs-ram, mkefs, mketfs, mkifs

"Embedded transaction filesystem (ETFS)" in the Filesystems chapter of the System Architecture guide.


[Previous] [Contents] [Index] [Next]