FreeCalypso > hg > freecalypso-tools

comparison doc/TIFFS-IVA-usage @ 217:dd3ec7c92bf1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ffstools/README renamed to README.old, ffstools/Usage moved to doc/TIFFS-IVA-usage
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 20 May 2017 18:10:49 +0000
parents ffstools/Usage@e7502631a0f9
children c44f31353f2f
comparison
equal deleted inserted replaced
216:7e3e3a958e3f 217:dd3ec7c92bf1
1 The generic tiffs utility needs to be invoked as follows:
2
3 tiffs [global-options] <imgfile> <org> <cmd> [command-args]
4
5 The first 3 non-optional arguments are the filename of the TIFFS image under
6 examination, the FFS organization being examined, and the operation to be
7 performed. The present utility is designed in the classic Unix manner in that
8 each invokation performs a single operation and exits, such that invokations of
9 tiffs (or one of the wrappers described below) may be plumbed into pipes and
10 the like.
11
12 The 2nd argument to tiffs after the FFS image filename describes how the TIFFS
13 instance under study is organized in terms of flash sectors. The syntax of
14 this argument is KxN, where K is the flash sector size in KiB and N is the
15 number of sectors occupied by the FFS. For MokoFFS images the correct
16 organization argument is 64x7 (7 sectors of 64 KiB each); for Pirelli's FFS
17 images it is 256x18 (18 sectors of 256 KiB each).
18
19 The following global options may be given before the image filename argument:
20
21 -a num
22
23 Use the specified flash block (sector) as the inode array block.
24
25 -o offset
26
27 The FFS image begins at the specified offset within the file, rather
28 than at the beginning. This option is useful when working with complete
29 device flash dumps of which FFS is only a part, starting somewhere
30 other than at 0.
31
32 -r ino
33
34 Use the specified inode as the root. Per Falcon's convention, TIFFS
35 inode numbers are always given in hex, hence this argument is
36 interpreted as hex without needing a 0x prefix.
37
38 The invokation syntax for mokoffs and pirffs wrappers is the same as for tiffs,
39 except that the FFS organization argument (64x7 or 256x18) is omitted; the
40 wrapper fills that argument in before passing the command to the main tiffs
41 program. The only other difference is that instead of the generic -o global
42 option, mokoffs takes a -f global option (no argument) which indicates that one
43 is working with a complete flash dump image, rather than just the FFS portion;
44 mokoffs -f gets translated into tiffs -o0x380000. (pirffs has no such option
45 at all because Pirelli's FFS starts at offset 0 within its respective flash
46 chip select.)
47
48 The next argument after the FFS organization for tiffs (or after the image
49 filename for mokoffs/pirffs) is the command (or operation) to be performed.
50 The following tiffs commands are currently available:
51
52 General information commands
53 ============================
54
55 These commands display general or summary information about the FFS image:
56
57 tiffs <...> blkhdr
58
59 This command displays the basic information contained in the header of each
60 flash erase block comprising the FFS image.
61
62 tiffs <...> fsinfo
63
64 This command displays some general information about the file system.
65
66 Standard listing/extraction commands
67 ====================================
68
69 These commands list or extract the normally-visible content of the FFS, i.e.,
70 the content which is visible when the FFS is "mounted" normally, and which the
71 FFS promises to preserve - as opposed to deleted or overwritten content.
72
73 tiffs <...> ls [-v[v]] [pathname...]
74
75 Tiffs ls without additional arguments yields a listing of the complete FFS
76 directory tree, akin to tar tv. Example output fragment:
77
78 fr 4096 /.journal
79 d /gsm
80 d /gsm/rf
81 d /gsm/rf/tx
82 f 512 /gsm/rf/tx/ramps.900
83 f 128 /gsm/rf/tx/levels.900
84 f 128 /gsm/rf/tx/calchan.900
85
86 The first character is 'f' for files or 'd' for directories. An 'r' following
87 immediately afterward means that the object has the read-only attribute set.
88 For files the listing includes the content size in bytes, and the last part is
89 the pathname of the object within the FFS.
90
91 With a single -v option added after ls, the output will include verbose
92 information as to the segmentation structure of each file. With two -v options
93 or with -vv, this additional output will also include the byte offset of each
94 data chunk, relative to the beginning of the FFS image.
95
96 Tiffs ls with a pathname argument yields information about the specified FFS
97 object; -v and -vv options act as already described, but are arguably more
98 useful when listing single files.
99
100 tiffs <...> cat [-v|-h] pathname
101
102 Just like the standard Unix cat(1) command, but cat'ing files from the FFS image
103 under study. The non-standard -h option means hex dump - it is handy because
104 almost all files in TI's GSM device FFS are binary, rather than ASCII.
105
106 tiffs <...> xtr dest-dir
107
108 This command extracts the complete content of the FFS into your ordinary Unix
109 file system. The sole argument is the local directory into which the root of
110 the GSM device FFS should be extracted.
111
112 Forensic analysis commands
113 ==========================
114
115 Unlike the "standard" listing/extraction commands which present TIFFS as a
116 "normal" Unix file system, using the "forensic" commands effectively requires
117 that the operator understands how TIFFS works, in particular, what an inode is
118 in TIFFS.
119
120 tiffs <...> lsino [-v[v]]
121
122 This command lists the FFS inode array from first to last; this listing order
123 will normally correspond to the forward chronological order of object creation.
124 -v and -vv options add verbosity.
125
126 '.' in the object type column means segment, '~' means a deleted object. The
127 lsino command only lists the inode array, and does not try to recover the
128 original type of deleted/overwritten objects from the journal or other clues.
129 The program attempts to recover the pathname of each inode, but because such
130 reverse mapping from inodes to pathnames is not an operation which TIFFS was
131 properly designed to support, and the pathname recovery algorithm in this TIFFS
132 IVA tool is made as generic as possible (doesn't look at the object types), the
133 lsino listing will occasionally include some bogus pathnames. Once again, it
134 is expected that the operator knows what s/he is doing when using these forensic
135 commands.
136
137 tiffs <...> lsino [-v[v]] [-f] ino...
138
139 This command works just like ls with an explicit pathname argument, but takes
140 one or more inode numbers instead. The -f option matters only if the requested
141 inode is in the deleted/overwritten state; it tells the lsino command to assume
142 that the object is/was the head inode of a file; -vf and -vvf combinations are
143 particularly useful.
144
145 tiffs <...> catino [-v|-h] ino
146
147 Just like regular cat, but takes an inode number instead of a pathname. Can be
148 used to cat the old content of deleted or overwritten files.