# HG changeset patch
# User Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
# Date 1391291272 0
# Node ID 63cd64625597fd37bd780d996ac858c6531f4292
# Parent  3d88461d8284cc9f4dd01ab8b43c1eefad645aac
ffstools/Usage write-up done

diff -r 3d88461d8284 -r 63cd64625597 ffstools/Usage
--- a/ffstools/Usage	Fri Jan 31 07:37:39 2014 +0000
+++ b/ffstools/Usage	Sat Feb 01 21:47:52 2014 +0000
@@ -49,6 +49,20 @@
 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
 ====================================
 
@@ -56,7 +70,7 @@
 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.
 
-ls [-v[v]] [pathname...]
+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:
@@ -82,3 +96,53 @@
 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.