The generic tiffs utility needs to be invoked as follows:

tiffs [global-options] <imgfile> <org> <cmd> [command-args]

The first 3 non-optional arguments are the filename of the TIFFS image under
examination, the FFS organization being examined, and the operation to be
performed.  The present utility is designed in the classic Unix manner in that
each invokation performs a single operation and exits, such that invokations of
tiffs (or one of the wrappers described below) may be plumbed into pipes and
the like.

The 2nd argument to tiffs after the FFS image filename describes how the TIFFS
instance under study is organized in terms of flash sectors.  The syntax of
this argument is KxN, where K is the flash sector size in KiB and N is the
number of sectors occupied by the FFS.  For MokoFFS images the correct
organization argument is 64x7 (7 sectors of 64 KiB each), for Pirelli's FFS
images it is 256x18 (18 sectors of 256 KiB each), for TIFFS images read out of
Tango modules with S71PL064J flash it is 64x15 (15 sectors of 64 KiB each), and
for TIFFS images read out of FreeCalypso development boards with S71PL129N flash
it is 256x8 (8 sectors of 256 KiB each).

The following global options may be given before the image filename argument:

-a num

	Use the specified flash block (sector) as the inode array block.

-o offset

	The FFS image begins at the specified offset within the file, rather
	than at the beginning.  This option is useful when working with complete
	device flash dumps of which FFS is only a part, starting somewhere
	other than at 0.

-O

	The location field in the inode structure is 16 bits rather than 32,
	stored in the upper two bytes out of the four.  This old FFS format
	(limited to 1 MiB total FFS size) was used by *very* old versions of
	TI's firmware and is incompatible with our "current" fw versions;
	so far the only encountered example of this old FFS format was found on
	the D-Sample board which the Mother scored in 2015 - it came with a
	firmware image dated 20020917.

-r ino

	Use the specified inode as the root.  Per the Mother's convention,
	TIFFS inode numbers are always given in hex, hence this argument is
	interpreted as hex without needing a 0x prefix.

The invokation syntax for mokoffs and pirffs wrappers is the same as for tiffs,
except that the FFS organization argument (64x7 or 256x18) is omitted; the
wrapper fills that argument in before passing the command to the main tiffs
program.  The only other difference is that instead of the generic -o global
option, mokoffs takes a -f global option (no argument) which indicates that one
is working with a complete flash dump image, rather than just the FFS portion;
mokoffs -f gets translated into tiffs -o0x380000.  (pirffs has no such option
at all because Pirelli's FFS starts at offset 0 within its respective flash
chip select.)

tiffs-8m is another similar wrapper; it is a more recent addition for working
with TIFFS images from platforms like D-Sample and Tango that use TI's 8 MiB
flash configuration.  tiffs-8m strictly parallels mokoffs except than it is
64x15 instead of 64x7, and -f turns into -o0x700000 instead of -o0x380000.

The next argument after the FFS organization for tiffs (or after the image
filename for mokoffs, pirffs or tiffs-8m) is the command (or operation) to be
performed.  The following tiffs commands are currently available:

General information commands
============================

These commands display general or summary information about the FFS image:

tiffs <...> blkhdr

This command displays the basic information contained in the header of each
flash erase block comprising the FFS image.

tiffs <...> fsinfo

This command displays some general information about the file system.

Standard listing/extraction commands
====================================

These commands list or extract the normally-visible content of the FFS, i.e.,
the content which is visible when the FFS is "mounted" normally, and which the
FFS promises to preserve - as opposed to deleted or overwritten content.

tiffs <...> ls [-v[v]] [pathname...]

Tiffs ls without additional arguments yields a listing of the complete FFS
directory tree, akin to tar tv.  Example output fragment:

fr    4096 /.journal
d          /gsm
d          /gsm/rf
d          /gsm/rf/tx
f      512 /gsm/rf/tx/ramps.900
f      128 /gsm/rf/tx/levels.900
f      128 /gsm/rf/tx/calchan.900

The first character is 'f' for files or 'd' for directories.  An 'r' following
immediately afterward means that the object has the read-only attribute set.
For files the listing includes the content size in bytes, and the last part is
the pathname of the object within the FFS.

With a single -v option added after ls, the output will include verbose
information as to the segmentation structure of each file.  With two -v options
or with -vv, this additional output will also include the byte offset of each
data chunk, relative to the beginning of the FFS image.

Tiffs ls with a pathname argument yields information about the specified FFS
object; -v and -vv options act as already described, but are arguably more
useful when listing single files.

tiffs <...> cat [-v|-h] pathname

Just like the standard Unix cat(1) command, but cat'ing files from the FFS image
under study.  The non-standard -h option means hex dump - it is handy because
almost all files in TI's GSM device FFS are binary, rather than ASCII.

tiffs <...> xtr dest-dir

This command extracts the complete content of the FFS into your ordinary Unix
file system.  The sole argument is the local directory into which the root of
the GSM device FFS should be extracted.

tiffs <...> decode file-keyword [band]

For some files in TIFFS doing a hex dump with tiffs cat -h (see above) is
sufficient for easily understanding the content of the file, but for other files
such as RF parameter tables further developer-friendly decoding is greatly
desirable.  The generic solution is to extract the complete FFS content with
tiffs xtr and then apply further tools for analysis, but this fully generic
solution involves a lot of clutter.  For some TIFFS files which often need to be
looked at and for which tiffs cat -h is insufficient, tiffs decode offers a
shorthand.  The following files can be decoded in this way:

Command					File being decoded
----------------------------------------------------------
tiffs <...> decode adccal		/sys/adccal
tiffs <...> decode afcdac		/gsm/rf/afcdac
tiffs <...> decode afcparams		/gsm/rf/afcparams
tiffs <...> decode stdmap		/gsm/rf/stdmap
tiffs <...> decode tx-ramps <band>	/gsm/rf/tx/ramps.<band>
tiffs <...> decode tx-levels <band>	/gsm/rf/tx/levels.<band>
tiffs <...> decode tx-calchan <band>	/gsm/rf/tx/calchan.<band>
tiffs <...> decode tx-caltemp <band>	/gsm/rf/tx/caltemp.<band>
tiffs <...> decode rx-calchan <band>	/gsm/rf/rx/calchan.<band>
tiffs <...> decode rx-caltemp <band>	/gsm/rf/rx/caltemp.<band>
tiffs <...> decode rx-agcparams <band>	/gsm/rf/rx/agcparams.<band>
tiffs <...> decode pcm-IMEI		/pcm/IMEI

Forensic analysis commands
==========================

Unlike the "standard" listing/extraction commands which present TIFFS as a
"normal" Unix file system, using the "forensic" commands effectively requires
that the operator understands how TIFFS works, in particular, what an inode is
in TIFFS.

tiffs <...> lsino [-v[v]]

This command lists the FFS inode array from first to last; this listing order
will normally correspond to the forward chronological order of object creation.
-v and -vv options add verbosity.

'.' in the object type column means segment, '~' means a deleted object.  The
lsino command only lists the inode array, and does not try to recover the
original type of deleted/overwritten objects from the journal or other clues.
The program attempts to recover the pathname of each inode, but because such
reverse mapping from inodes to pathnames is not an operation which TIFFS was
properly designed to support, and the pathname recovery algorithm in this TIFFS
IVA tool is made as generic as possible (doesn't look at the object types), the
lsino listing will occasionally include some bogus pathnames.  Once again, it
is expected that the operator knows what s/he is doing when using these forensic
commands.

tiffs <...> lsino [-v[v]] [-f] ino...

This command works just like ls with an explicit pathname argument, but takes
one or more inode numbers instead.  The -f option matters only if the requested
inode is in the deleted/overwritten state; it tells the lsino command to assume
that the object is/was the head inode of a file; -vf and -vvf combinations are
particularly useful.

tiffs <...> catino [-v|-h] ino

Just like regular cat, but takes an inode number instead of a pathname.  Can be
used to cat the old content of deleted or overwritten files.

Support for SE K2xx extended filenames
======================================

As explained in the SE-K2xx-FFS article, Sony Ericsson K2xx phones use
TIFFS as their flexible data storage mechanism, but they also made their own
non-standard extension to TIFFS in terms of extended UCS-2 filenames.

In order to allow listing full FFS trees from SE K2xx phones with tiffs ls and
possibly also extracting them with tiffs xtr, we have made the following hackish
extension to our TIFFS IVA: whenever either of these two commands encounters an
"extended" filename (one which fails standard TIFFS filename validity checks but
has a terminating NUL that allows the name and data portions of the chunk to be
separated) in the visible tree walk, our tool replaces it (for the purpose of
listed pathname generation or extraction into host file system) with a
synthesized pseudonym of the form "!bogo%04x", where %04x is the FFS inode
number in hex.  In the case of tiffs ls, the actual extended filename is then
printed on a separate line (immediately following the synthesized listing), with
non-printable-ASCII characters escaped in \x hex form.  We've also extended the
individual-inode form of lsino command to list these extended filenames when
encountering such, and we've extended catino (which needs to skip past the name
to get to the beginning of the data portion of the head chunk) to not reject
file head chunks with extended filenames in them as long as the needed
separating NUL is found.