TFSImage Image Tool




TFSImage is a tool developed by Blunk Microsystems to prepare binary volume images for use in pre-programming flash devices for production. TFSImage has a GUI interface for specifying the device, file system, and input file settings that define the image. A single image can contain up to four volumes. The resulting binary can be programmed into single or multiple devices.



The TFSImage user interface is divided into three panels. The upper left panel defines the flash device settings; most of these are constrained by the device hardware. The upper right panel contains global file system settings that impact all volumes, regardless of type. The lower panel holds definitions for up to four flash regions that can be made into separate volumes whose data is combined in the resulting binary image.

Device Settings

The Device Settings panel holds settings for the flash device type, the erasable block size, the total number of erasable blocks, the maximum bad block count (NAND devices only), and the page size. As shown below, the available device type choices are Single Level Cell (SLC) NOR, Multi Level Cell (MLC) NOR, M18 Sibley NOR (Numonyx), Eclipse NOR (Spansion), SLC NAND, and MLC NAND.



The block size entry specifies the device's minimum erasable block size. The choices range from 8KB to 512KB, in power of two increments.


The page size entry must equal the number of bytes that are read and written in the driver's page_read() and page_write() routines. For NAND flash, the page size is determined by the chip. Also, Eclipse and M18 NOR flash have a fixed page size of 512 and 1024 bytes, respectively. Otherwise, the page size is usually configurable, with 512 bytes a common choice. The Image Tool supports choices of 512, 1024, 2048, or 4096 bytes.

File System Settings

The file system settings include the maximum file name length. This must correspond to the FILENAME_MAX value used by the target file system. It also contains checkboxes to indicate whether UTF file name encoding and VFAT support (long FAT file names) are enabled in the target software. These features are enabled by the UTF_ENABLED and VFAT_ENABLED definitions, respectively, in 'config.h'.



This panel also contains the target byte order setting. Portions of TargetFFS control information are written to flash in the natural byte order of the target CPU. The Image Tool needs to know this byte order in order to write the control information correctly.

Region Settings

The Region Settings panel defines up to four regions. Each region has a beginning and ending block number and represents a unique volume. Region 1 begins with block 0. If the ending block number for region 1 is set to the highest block number, the image will only contain one region. If the value is less than that, the image will contain multiple regions.


The ending block numbers determine how the available blocks are split among the - up to four - regions. The last active region is the one with its ending block number set to the device's highest block number. Unused regions have their settings grayed out.


When NAND is selected for the device type, the TargetNDM bad block manager is used. (Except if "Disable NDM" is checked, but that is a special case not considered further here.). TargetNDM uses the last two blocks for its control information. So the highest block number will either be the Device Settings' "Number of Blocks" value minus 1 or, if NAND is used, the Device Settings' "Number of Blocks" value minus 3.


There are four types of regions. As shown below, the selections are: TargetFFS volume, TargetFAT/TargetFTL volume, TargetZFS volume, or "None", to indicate a region that is left as all 0xFF bytes.



Every type except "None" has an associated directory path. The contents of the specified directory become the contents of that region's volume when the binary image is created. Every subdirectory and file in the specified directory is replicated on the target when the binary image is mounted by the target file system.


TargetZFS regions contain an additional parameter setting: the compression level. TargetZFS is compressed read-only file system. The contents of a TargetZFS volume are dynamically decompressed when read on the target, in a manner that is transparent to the application.


The TFSImage toolbar contains four buttons and a drop-down menu. From left to right, the buttons clear the current settings, launch an 'Open' dialog to read previously saved settings, save the current settings (with a '.tfd' extension), or launch a 'Save As' dialog to generate and save the binary image output file (with a '.tfi' extension).



The drop menu specifies a DLL that is used for Error Correction Coding (ECC). It is grayed out unless the flash type is NAND. NAND flash requires ECC encoding of file system and user data before it is written to the flash. When the Image Tool creates the binary output file, it must apply the same ECC algorithm the target system will apply when it reads the data.


TargetFFS-NAND and TargetNDM include ECC routines for drivers that perform 1-bit and 4-bit correction per 512 bytes. The two DLLs included with the Image Tool, "ecc1Blunk.dll" and "ecc4Blunk.dll", perform the same ECC as the driver routines for 1-bit and 4-bit correction, respectively. A Visual Studio project is available for creating custom DLLs for other ECC algorithms, such as when hardware ECC is used.


TFSImage has two menu bar entries: File and Help. The New, Open, Save, Save As, history, and Exit choices in the File menu apply to .tfd settings files. The Help menu entry brings up the 'About' dialog.


Command Line Version

A command line version of the Image Tool is provided for production use. The command line version takes its settings from a specified '.tfd' file, which should have settings previously configured and saved by the GUI version. To generate a binary image, the command line format is:


TFSCLI [-v]  settings_file.tfd  image_file.tfi


where -v turns on verbose mode.


To update a directory path in a .tfd file, the command line format is:


TFSCLI  -r#  path  settings_file.tfd


where # is 1, 2, 3, or 4 and specifies the region that will have its directory path updated.


Some example commands are:


C:\TFSImage>tfscli -r1 C:/targetos/modules/filesys/ffs settings.tfd

TFSImage command line version 1.1

Changing region 1 to C:/targetos/modules/filesys/ffs...

File settings.tfd updated


C:\\TFSImage>tfscli settings.tfd image.tfi

TFSImage command line version 1.1

Processing settings.tfd...

Image file "image.tfi" created successfully.



TFSImage command line version 1.1

Not enough parameters


Usage: tfscli [-v] input_file(*.tfd) output_file(*.tfi) or

       tfscli -r# dir_path input_file(*.tfd)

-v: Verbose

-r# dir_path: Overwrite region #'s root directory path in the input_file

              #: 1 to 4

S-Record Conversion Tool

In binary format, image files created by the image tool are the same size as the specified flash memory. The binary image of an 8MB device will be 8MB. If the volume only contains a small amount of user data, most bytes in the image file will be 0xFF, representing unprogrammed memory, but the total will still be 8MB.


The above is exactly true for NOR flash. For NAND, the image tool binary output file will be slightly smaller than the flash memory size because the blocks reserved for bad block recovery are excluded from the image.


To make image files smaller when they contain mostly 0xFF bytes, we provide the tool tfi2srec. tfi2srec converts the binary image to the text-based S-record format. This format consists of records, each with an address followed by data bytes.


In binary format, the volume image must contain consecutive bytes because if any were left out, the file loader would not know where the hole was and could not place the data correctly. Since each record in the S-record format has an address, the data does not have to be consecutive. This allows tfi2srec to shorten the output file by skipping strings of 0xFF bytes.


If the image contains many 0xFF bytes, the converted S-record file will be smaller. As long as the flash programmer initializes its RAM buffer to all 0xFF before loading the S-record file, the same state will result as if the larger raw binary file were loaded. But the smaller file will give a faster download time. Flash programmers, such as from Data I/O or BP Microsystems, usually have a convenient command for initializing their input buffer to all 0xFF's.


So, tfi2srec has two contrary effects. First, it converts a binary file to a text format. This will tend toward making the output larger, because each binary data byte is converted to two ASCII characters, plus an address, a checksum, and some other characters are added to each record. But tfi2srec also omits strings of 0xFF bytes. If the file contains mostly 0xFF bytes, this will tend toward making the output smaller.


The result is that tfi2srec can convert a binary file into a larger text file, if the volume contains a large amount of user file data, but it can also convert a binary file into a smaller text file if the volume is mostly empty.


tfi2srec is meant to be applied to images that are mostly empty. Its command line format is:


tfi2srec input.tfi output.s19