devf-generic

Generic flash filesystem


Note: You must be root to start this driver.

Syntax:

devf-generic 
    [-Aa] [-b priority] [-D] [-d log_method] [-E] [-e auto]
    [-f verifylevel] [-i arrayindex[,partindex]]
    [-L limit] [-l] [-m mountover]
    [-p backgroundpercent[,superlimit]] [-R] [-r]
    [-s base[,wsize[,aoffset[,asize[,usize[,bwidth[,ileave]]]]]]]
    [-t hi_water[,lo_water[,max]]] [-u update] [-V] [-v]
    [-w buffersize] [-x]

Runs on:

Neutrino

Targets:

Most flash devices

Options:

-A
When registering the path names for the partitions with resmgr_attach(), use the _RESMGR_FLAG_AFTER flag to force the path to be resolved after others with the same pathname at the same mountpoint.
-a
Don't automount filesystem partitions present on the media. If you specify both the -a and -R options, the driver ignores the -R option.
-b priority
Enable background reclaim at the specified priority. By default, background reclamation is disabled.
-D
Enable automatic detection of ECC mode. If you specify this option, you don't need to specify -x.

Note: Don't mix ECC-enabled partitions and ECC-disabled partitions; the driver doesn't support this.

-d log_method
Control the logging from the flash driver. The possible values for log_method are:
-E
Don't daemonize. If the driver detects a corrupt filesystem, the exit status is that filesystem's partition number plus 1.
-e auto
Only enumerate the flash partitions, instead of doing a full scan and mount. The flash driver automounts all partitions with a partition number less than or equal to auto.

For example, assume we have a flash layout as follows:

If you start the driver with -e 1, the driver creates all the raw entries in /dev, but mounts only /dev/fs0p1 (/dev/fs0p0 is raw, so it's never mounted, regardless of the -e option)

-f verifylevel
Enable flash verify. (default=0, 0=none, write=1, erase=2, all=3)
-i arrayindex[,partindex]
Starting socket index and first partition index; 0 ≥ index ≥15. The default is 0,0. Use this to give multiple drivers unique IDs. The -i option is just a suggestion for the resource database manager; the selected indexes can be larger.
-L limit
The number of retries to make if the physical flash erase function for a unit fails. The default is 0.
-l
List the available flash databases and exit.
-m mountover
Override the mountpoints assigned to the file system that are formatted with an empty (i.e. flashctl -p/dev/fs0p0 -f -n "") mountpoint. The mountover argument can include two %X format specifiers (like those for printf()) that are replaced by the socket index and the partition index.

Note: The -m option doesn't override a mountpoint specified with mkefs.

-p backgroundpercent[,superlimit]
Set the background-reclaim percentage trigger (stale space over free space) and, optionally, the superseded extent limit before reclaim. The default is 100,16.
-R
Mount any automount filesystems as read-only. This option doesn't affect raw partition mounts, and it has an effect only at startup and initialization. Any subsequent mounting (with either flashctl or mount) ignores the -R option. If you also specify the -a option, the driver ignores the -R option.
-r
Enable fault recovery for dirty extents, dangling extents, and partial reclaims.

Note: You should always specify the -r option unless you're trying to debug an issue concerning flash corruption.

If you don't specify -r, and a power failure occurs, the following can happen:

-s base[,wsize[,aoffset[,asize[,usize[,bwidth[,ileave]]]]]]
Set socket options, normally the base physical address, window size, array offset, array size, unit size, bus width, and interleave. The format is left flexible for socket services with customized drivers. This option must be specified.

The arguments are:

base
Physical base address of the flash part. This value is board-specific.
wsize
Size of the physically contiguous flash part.
aoffset
For SRAM, the offset from the base address to the start of the flash array.
asize
For SRAM, the size of the flash array. The default is equal to wsize.
usize
The size of a physical erase sector. For SRAM, this number can be any power of two. 64 KB should be the minimum, for performance reasons.
bwidth
The total width of the data bus, as seen from the microprocessor's perspective. This is the width of one flash chip multiplied by the interleave. The value must be a power of 2 (1, 2, 4, or 8).
ileave
The number of flash chips arranged on the data bus. Two 16-bit wide chips used as the upper and lower halves of a 32-bit databus give an interleave of 2. This number must be a power of 2 (1, 2, 4, or 8).

You can specify the base physical address, sizes, and offset in octal (1000), hexadecimal (0x200), or decimal (512). The sizes must be a power of two, and you can specify them with any of the following suffixes:

-t hi_water[,lo_water[,max]]
Set the high water, low water, and maximum attributes of the thread pool; the increment (i.e., the number of threads created at one time) is 1. The default is 4,2,100. The values must be related as follows:
-u update
Specify the update level for timestamps. POSIX specifies that timestamps be kept when you access, create, or modify a file. FFSv3 is documented as not supporting the access timestamp, in order to reduce wear on the hardware.

The values for update are:


Note: The -u2 option is very, very expensive and will cause many reclaims because the time updates have to flow right up to the root directory, so one file update may cause many directory updates.

-V
Display filesystem and MTD version information, and then exit.
-v
Be verbose; specify additional v characters for more verbosity. For more information, see Verbose output,” below.
-w buffersize
Write (append) buffer size in bytes. The default buffersize is 512. Using a larger write-buffer prevents the creation of very small extents, reducing overhead. If buffersize is 0, appending is disabled.
-x
Enable software ECC mode.

Note: Don't mix ECC-enabled partitions and ECC-disabled partitions; the driver doesn't support this.

Description:

The devf-generic manager provides Flash filesystem support for any standard flash device. Typically, all you need to do is to pass the address and size using the -s option. The manager should detect the device automatically.

For information on creating a custom variant of devf-generic for your embedded system, see the Customizing the Flash Filesystem chapter of Building Embedded Systems

The default filenames are as follows (you can use the -i option to change the ID, n, appended to /dev/fs):

/dev/fsn
Default mountpoint for socket n.
/dev/fsnp0
Raw access for socket n, partition 0.
mountpoint
Flash filesystem mountpoint for socket n, partition 0 with transparent decompression.

You can specify the mountpoint above with the mount attribute of the mkefs command, and override it with the -n option to flashctl. By default, it's /fsnp0.


Note: If you erase a raw partition or the raw array (socket), you might erase any boot monitor, BIOS, or other data installed by the manufacturer. Check the documentation for the board.

The driver probes the hardware to determine its block size. If you need to know the block size, you can:

Verbose output

If you specify the -v option, a devf-* driver provides some useful information. This section describes the output that you get if you specify -vvv; at higher levels of verbosity, the output also includes messages about the use of malloc() and free(), but these aren't likely to be useful to you.

The output starts with something like this:

Flash Development Library - HEAD
Build: Jan 15 2010 13:00:00
MTD Build: Jan 15 2010, 13:25:55

These lines identify the source branch of the build, as well as the build times for libfs-flash3.a and libmtd-flash.a.

The rest of the messages that the driver prints are variable; messages are printed as the driver discovers things of interest. The general format of a message is

(devf tN::function:line) Message string

where tN is the thread printing the message, function is the function emitting the message, and line is the line number that emitted the message.

The standard messages include the following:

(devf t1::f3s_skt_attach:109) fs0 socket RAM (flash simulation)
The flash driver located a flash socket, number zero (fs0). This message also indicates that the hardware identification succeeded.
(devf t1::f3s_flash_probe:248) chip total = 1, bus_width = 8, interleave = 2
After identifying the hardware, the driver prints the geometry. The chip total is the number of contiguous chips. The bus width is the size of the data bus, in bytes. The interleave is the number of physical chips sharing the data bus (high and low halves of the data bus, for example).

This particular example indicates that there are two physical chips sharing a 64-bit data bus.

(devf t1::f3s_skt_attach:135) fs0 array SRAM U: 80 S: 020000
The flash driver has allocated the flash array (i.e. the storage media) of type SRAM, with 0x80 hardware sectors, and a sector size of 0x020000 bytes.
(devf t1::f3s_recover_boot:248) fs0p0 boot P[00] U: 80
The filesystem is now scanning for partitions. It has found a boot header, and has named the partition /dev/fs0p0. The boot signature is located on physical block 0, and the partition has 0x80 sectors (called “units” in devf-* nomenclature).
(devf t1::f3s_recover_reclaim:989) fs0p0 spare P[7F]
The second phase of the startup scan is processing /dev/fs0p0, and has found a spare block. The spare block is located on physical sector 0x7F.
(devf t3::f3s_table_find:66) fs0p1 raw U: 09
A region of flash was found that isn't formatted. The region is given the name /dev/fs0p1; its size is 0x09 sectors.

Examples:

Start devf-generic and automatically mount the flash filesystem partitions at the base address 0xFF000 with a window size of 16 megabytes, with an initial fault recovery process, most POSIX semantics enabled and background reclaim at priority 5:

devf-generic -s 0xFF000,16M -r -u2 -b5 &

Create a 32 MB flash partition, with a 64 KB unit (sector) size:

devf-generic -s0,32m,,,64k  -v -r

Create a 128 MB flash partition, with large block sizes (to speed formatting):

devf-generic -s0,128m,,,512k -v -r

Create a 4 MB partition:

devf-generic -s0,4m,,,64k -v -r

Create a 16 MB flash partition, from a given physical address, with a 128 KB unit size, and a 16-bit wide data bus:

devf-generic -s0xa4000000,16m,,,128k,2 -v -r

Create a 16 MB flash partition, from a given physical address, with a 256 KB unit size, and a 32-bit-wide data bus, with an interleave of two:

devf-generic -s0,16m,,,256k,4,2 -v -r

Caveats:

You must specify the -s option when using this driver.

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

QNX Neutrino flash filesystem version 3 no longer provides built-in decompression. The flash filesystem's decompression functionality has moved into the inflator resource manager. You should now use the deflate utility to compress files.

Performance might be slow when multiple writers are writing randomly to a shared file or to a shared directory (e.g. using unlink or rename). In these cases, the offset pointers have to be rewound for every access. There's no performance penalty when appending to a file, or when creating files with open(O_CREAT), mkdir, mknod, or link.

See also:

deflate, devf-ram, flashctl, inflator, mkefs

Flash filesystems in the Working With Filesystems chapter of the User's Guide

Customizing the Flash Filesystem chapter of Building Embedded Systems