# HG changeset patch # User Mychaela Falconia # Date 1495303849 0 # Node ID dd3ec7c92bf18a5b1cfaa7090d1d0f1e5e1cc2d8 # Parent 7e3e3a958e3f507cd52191ca575166162647182b ffstools/README renamed to README.old, ffstools/Usage moved to doc/TIFFS-IVA-usage diff -r 7e3e3a958e3f -r dd3ec7c92bf1 doc/TIFFS-IVA-usage --- /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] [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. diff -r 7e3e3a958e3f -r dd3ec7c92bf1 ffstools/README --- 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. diff -r 7e3e3a958e3f -r dd3ec7c92bf1 ffstools/README.old --- /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. diff -r 7e3e3a958e3f -r dd3ec7c92bf1 ffstools/Usage --- 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] [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.