--- /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.

--- a/ffstools/README	Sat May 20 12:48:38 2017 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,31 +0,0 @@
-You are looking at the source for the TIFFS In Vitro Analyzer utility.  You may
-have downloaded it either as a separate package or as part of the larger
-freecalypso-sw suite.
-
-See TIFFS-Overview (in ../doc if you are working with the full freecalypso-sw
-source tree) for a general description of what TIFFS is and why it matters.
-
-The utility contained in the present package runs on a general purpose GNU/Linux
-(or other Unix) host and enables "in vitro" examination of Flash File System
-images read out of TI-based GSM devices.  Using this utility, you can list the
-directory and file content of an FFS image, cat any individual file in the FFS,
-or extract the complete FFS content into your regular Unix file system.  Some
-"forensic" operations are also supported: by listing the inode array, one can
-deduce the order in which the present FFS content got created, and see what
-files have been overwritten or deleted in the span of still-visible history.
-One can then cat the old byte content of those overwritten or deleted files,
-if those data chunks are still in the FFS image (i.e., if the flash sector in
-question has not been reclaimed yet).
-
-Compilation and installation are straightforward: run 'make' to compile the
-source; you should get 3 executable binaries named tiffs, mokoffs and pirffs;
-then run 'make install' as root to install them in /usr/local/bin.  The binary
-named tiffs is the main program; mokoffs and pirffs are wrappers that simplify
-the most common current use cases.
-
-To install somewhere other than /usr/local/bin, edit the INSTBIN= setting in
-the subdirectory Makefiles.  You will also need to edit
-tiffs-wrappers/installpath.c accordingly, as the mokoffs and pirffs wrappers
-are designed to exec tiffs by its absolute installed pathname.
-
-See Usage for the usage instructions.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ffstools/README.old	Sat May 20 18:10:49 2017 +0000
@@ -0,0 +1,31 @@
+You are looking at the source for the TIFFS In Vitro Analyzer utility.  You may
+have downloaded it either as a separate package or as part of the larger
+freecalypso-sw suite.
+
+See TIFFS-Overview (in ../doc if you are working with the full freecalypso-sw
+source tree) for a general description of what TIFFS is and why it matters.
+
+The utility contained in the present package runs on a general purpose GNU/Linux
+(or other Unix) host and enables "in vitro" examination of Flash File System
+images read out of TI-based GSM devices.  Using this utility, you can list the
+directory and file content of an FFS image, cat any individual file in the FFS,
+or extract the complete FFS content into your regular Unix file system.  Some
+"forensic" operations are also supported: by listing the inode array, one can
+deduce the order in which the present FFS content got created, and see what
+files have been overwritten or deleted in the span of still-visible history.
+One can then cat the old byte content of those overwritten or deleted files,
+if those data chunks are still in the FFS image (i.e., if the flash sector in
+question has not been reclaimed yet).
+
+Compilation and installation are straightforward: run 'make' to compile the
+source; you should get 3 executable binaries named tiffs, mokoffs and pirffs;
+then run 'make install' as root to install them in /usr/local/bin.  The binary
+named tiffs is the main program; mokoffs and pirffs are wrappers that simplify
+the most common current use cases.
+
+To install somewhere other than /usr/local/bin, edit the INSTBIN= setting in
+the subdirectory Makefiles.  You will also need to edit
+tiffs-wrappers/installpath.c accordingly, as the mokoffs and pirffs wrappers
+are designed to exec tiffs by its absolute installed pathname.
+
+See Usage for the usage instructions.

--- a/ffstools/Usage	Sat May 20 12:48:38 2017 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,148 +0,0 @@
-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.