--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/TIFFS-IVA-usage	Sat May 20 18:10:49 2017 +0000
@@ -0,0 +1,148 @@
+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).
+
+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.
+
+-r ino
+
+	Use the specified inode as the root.  Per Falcon'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.)
+
+The next argument after the FFS organization for tiffs (or after the image
+filename for mokoffs/pirffs) 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.
+
+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.