VxWorks Reference Manual : Libraries
tffsDrv - TrueFFS interface for VxWorks
tffsDrv( ) - initialize the TrueFFS system
tffsDevCreate( ) - create a TrueFFS block device suitable for use with dosFs
tffsDevOptionsSet( ) - set TrueFFS volume options
tffsDevFormat( ) - format a flash device for use with TrueFFS
tffsRawio( ) - low level I/O access to flash components
This module defines the routines that VxWorks uses to create a TrueFFS block device. Using this block device, dosFs can access a board-resident flash memory array or a flash memory card (in the PCMCIA slot) just as if it was a standard disk drive. Also defined in this file are functions that you can use to format the flash medium, as well as well as functions that handle the low-level I/O to the device.
To include TrueFFS for Tornado in a VxWorks image, you must edit your BSP's config.h and define INCLUDE_TFFS, or, for some hardware, INCLUDE_PCMCIA. If you define INCLUDE_TFFS, this configures usrRoot( ) to call tffsDrv( ). If you defined INCLUDE_PCMCIA, the call to tffsDrv( ) is made from pccardTffsEnabler( ). The call to tffsDrv( ) sets up the structures, global variables, and mutual exclusion semaphore needed to manage TrueFFS. This call to tffsDrv( ) also registers socket component drivers for each flash device found attached to the target.
These socket component drivers are not quite block devices, but they are an essential layer within TrueFFS. Their function is to manage the hardware interface to the flash device, and they are intelligent enough to handle formatting and raw I/O requests to the flash device. The other two layers within TrueFFS are known as the translation layer and the MTD (the Memory Technology Driver). The translation layer of TrueFFS implements the error recover and wear-leveling features of TrueFFS. The MTD implements the low-level programming (map, read, write, and erase) of the flash medium.
To implement the socket layer, each BSP that supports TrueFFS includes a sysTffs.c file. This file contains the code that defines the socket component driver. This file also contains a set of defines that you can use to configure which translation layer modules and MTDs are included in TrueFFS. Which translation layer modules and MTDs you should include depends on which types of flash devices you need to support. Currently, there are three basic flash memory technologies, NAND-based, NOR-based, and SSFDC. Within sysTffs.c, define:
- INCLUDE_TL_NFTL
- To include the NAND-based translation layer module.
- INCLUDE_TL_FTL
- To include the NOR-based translation layer module.
- INCLUDE_TL_SSFDC
- To include the SSFDC-appropriate translation layer module.
To support these different technologies, TrueFFS ships with three different implementations of the translation layer. Optionally, TrueFFS can include all three modules. TrueFFS later binds the appropriate translation layer module to the flash device when it registers a socket component driver for the device.
Within these three basic flash device categories there are still other differences (largely manufacturer-specific). These differences have no impact on the translation layer. However, they do make a difference for the MTD. Thus, TrueFFS ships with eight different MTDs that can support a variety of flash devices from Intel, Sharp, Samsung, National, Toshiba, AMD, and Fujitsu. Within sysTffs.c, define:
- INCLUDE_MTD_I28F016
- For Intel 28f016 flash devices.
- INCLUDE_MTD_I28F008
- For Intel 28f008 flash devices.
- INCLUDE_MTD_I28F008_BAJA
- For Intel 28f008 flash devices on the Heurikon Baja 4000.
- INCLUDE_MTD_AMD
- For AMD, Fujitsu: 29F0{40,80,16} 8-bit flash devices.
- INCLUDE_MTD_CDSN
- For Toshiba, Samsung: NAND CDSN flash devices.
- INCLUDE_MTD_DOC2
- For Toshiba, Samsung: NAND DOC flash devices.
- INCLUDE_MTD_CFISCS
- For CFI/SCS flash devices.
- INCLUDE_MTD_WAMD
- For AMD, Fujitsu 29F0{40,80,16} 16-bit flash devices.
The socket component driver and the MTDs are provided in source form. If you need to write your own socket driver or MTD, use these working drivers as a model for your own.
Most of the routines defined in this file are accessible through the I/O system only. However, four routines are callable externally. These are: tffsDrv( ), tffsDevCreate( ), tffsDevFormat( ), and tffsRawio( ).
The first routine called from this library must be tffsDrv( ). Call this routine exactly once. Normally, this is handled automatically for you from within usrRoot( ), if INCLUDE_TFFS is defined, or from within pccardTffsEnabler( ), if INCLUDE_PCMCIA is defined.
Internally, this call to tffsDrv( ) registers socket component drivers for all the flash devices connected to your system. After registering a socket component driver for the device, TrueFFS can support calls to tffsDevFormat( ) or tffsRawio( ). However, before you can mount dosFs on the flash device, you must call tffsDevCreate( ). This call creates a block device on top of the socket component driver, but does not mount dosFs on the device. Because mounting dosFs on the device is what you will want to do most of the time, the sysTffs.c file defines a helper function, usrTffsConfig( ). Internally, this function calls tffsDevCreate( ) and then does everything necessary (such as calling the dosFsDevInit( ) routine) to mount dosFs on the resulting block device.
LOW LEVEL I/O Normally, you should handle your I/O to the flash device using dosFs. However, there are situations when that level of indirection is a problem. To handle such situations, this library defines tffsRawio( ). Using this function, you can bypass both dosFs and the TrueFFS translation services to program the flash medium directly.
However, you should not try to program the flash device directly unless you are intimately familiar with the physical limits of your flash device as well as with how TrueFFS formats the flash medium. Otherwise you risk not only corrupting the medium entirely but permanently damaging the flash device.
If all you need to do is write a boot image to the flash device, use the tffsBootImagePut( ) utility instead of tffsRawio( ). This function provides safer access to the flash medium.
This driver responds to all ioctl codes by setting a global error flag. Do not attempt to format a flash drive using ioctl calls.
tffsDrv.h, fatlite.h
tffsDrv( ) - initialize the TrueFFS system
STATUS tffsDrv (void)
This routine sets up the structures, the global variables, and the mutual exclusion semaphore needed to manage TrueFFS. This call also registers socket component drivers for all the flash devices attached to your target.
Because tffsDrv( ) is the call that initializes the TrueFFS system, this function must be called (exactly once) before calling any other TrueFFS utilities, such as tffsDevFormat( ) or tffsDevCreate( ). Typically, the call to tffsDrv( ) is handled for you automatically. If you defined INCLUDE_TFFS in your BSP's config.h, the call to tffsDrv( ) is made from usrRoot( ). If your BSP's config.h defines INCLUDE_PCMCIA, the call to tffsDrv( ) is made from pccardTffsEnabler( ).
OK, or ERROR if it fails.
tffsDevCreate( ) - create a TrueFFS block device suitable for use with dosFs
BLK_DEV * tffsDevCreate ( int tffsDriveNo, /* TFFS drive number (0 - DRIVES-1) */ int removableMediaFlag /* 0 - nonremovable flash media */ )
This routine creates a TFFS block device on top of a flash device. It takes as arguments a drive number, determined from the order in which the socket components were registered, and a flag integer that indicates whether the medium is removable or not. A zero indicates a non removable medium. A one indicates a removable medium. If you intend to mount dosFs on this block device, you probably do not want to call tffsDevCreate( ), but should call usrTffsConfig( ) instead. Internally, usrTffsConfig( ) calls tffsDevCreate( ) for you. It then does everything necessary (such as calling the dosFsDevInit( ) routine) to mount dosFs on the just created block device.
BLK_DEV pointer, or NULL if it failed.
tffsDevOptionsSet( ) - set TrueFFS volume options
STATUS tffsDevOptionsSet ( TFFS_DEV * pTffsDev /* pointer to device descriptor */ )
This routine is intended to set various TrueFFS volume options. At present it only disables FAT monitoring. If VxWorks long file names are to be used with TrueFFS, FAT monitoring must be turned off.
OK, or ERROR if it failed.
tffsDevFormat( ) - format a flash device for use with TrueFFS
STATUS tffsDevFormat ( int tffsDriveNo, /* TrueFFS drive number (0 - DRIVES-1) */ int arg /* pointer to tffsDevFormatParams structure */ )
This routine formats a flash device for use with TrueFFS. It takes two parameters, a drive number and a pointer to a device format structure. This structure describes how the volume should be formatted. The structure is defined in dosformat.h. The drive number is assigned in the order that the socket component for the device was registered.
The format process marks each erase unit with an Erase Unit Header (EUH) and creates the physical and virtual Block Allocation Maps (BAM) for the device. The erase units reserved for the "boot-image" are skipped and the first EUH is placed at number (boot-image length - 1). To write to the boot-image region, call tffsBootImagePut( ).
If any of the erase units in the boot-image region contains an erase unit header from a previous format call (this can happen if you reformat a flash device specifying a larger boot region) TrueFFS fails to mount the device. To fix this problem, use tffsRawio( ) to erase the problem erase units (thus removing the outdated EUH).
The macro TFFS_STD_FORMAT_PARAMS defines the default values used for formatting a flask disk device. If the second argument to this routine is zero, tffsDevFormat( ) uses these default values.
OK, or ERROR if it failed.
tffsRawio( ) - low level I/O access to flash components
STATUS tffsRawio ( int tffsDriveNo, /* TrueFFS drive number (0 - DRIVES-1) */ int functionNo, /* TrueFFS function code */ int arg0, /* argument 0 */ int arg1, /* argument 1 */ int arg2 /* argument 2 */ )
Use the utilities provided by thisroutine with the utmost care. If you use these routines carelessly, you risk data loss as well as permanent physical damage to the flash device.
This routine is a gateway to a series of utilities (listed below). Functions such as mkbootTffs( ) and tffsBootImagePut( ) use these tffsRawio( ) utilities to write boot sector information. The functions for physical read, write, and erase are made available with the intention that they be used on erase units allocated to the boot-image region by tffsDevFormat( ). Using these functions elsewhere could be dangerous.
The arg0, arg1, and arg2 parameters to tffsRawio( ) are interpreted differently depending on the function number you specify for functionNo. The drive number is determined by the order in which the socket components were registered.
TFFS_GET_PHYSICAL_INFO writes the flash type, erasable block size, and media size to the user buffer specified in arg0.
Function Name arg0 arg1 arg2 TFFS_GET_PHYSICAL_INFO user buffer address N/A N/A TFFS_PHYSICAL_READ address to read byte count user buffer address TFFS_PHYSICAL_WRITE address to write byte count user buffer address TFFS_PHYSICAL_ERASE first unit number of units N/A TFFS_ABS_READ sector number number of sectors user buffer address TFFS_ABS_WRITE sector number number of sectors user buffer address TFFS_ABS_DELETE sector number number of sectors N/A TFFS_DEFRAGMENT_VOLUME number of sectors user buffer address N/A TFFS_PHYSICAL_READ reads arg1 bytes from arg0 and writes them to the buffer specified by arg2.
TFFS_PHYSICAL_WRITE copies arg1 bytes from the arg2 buffer and writes them to the flash memory location specified by arg0.
TFFS_PHYSICAL_ERASE erases arg1 erase units, starting at the erase unit specified in arg0.
TFFS_ABS_READ reads arg1 sectors, starting at sector arg0, and writes them to the user buffer specified in arg2.
TFFS_ABS_WRITE takes data from the arg2 user buffer and writes arg1 sectors of it to the flash location starting at sector arg0.
TFFS_ABS_DELETE deletes arg1 sectors of data starting at sector arg0.
TFFS_DEFRAGMENT_VOLUME calls the defragmentation routine with the minimum number of sectors to be reclaimed, arg0, and writes the actual number reclaimed in the user buffer by arg1. Calling this function through some low priority task will make writes more deterministic. No validation is done of the user specified address fields, so the functions assume they are writable. If the address is invalid, you could see bus errors or segmentation faults.
OK, or ERROR if it failed.