FreeCalypso > hg > freecalypso-sw

annotate doc/TIFFS-Overview @ 251:63cd64625597

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ffstools/Usage write-up done
author Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
date Sat, 01 Feb 2014 21:47:52 +0000
parents 3d88461d8284
children 14618bd924ec
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
224
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
1 All TI GSM firmwares known to this author (FreeCalypso developer Space Falcon)
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
2 implement some kind of flash file system, or FFS. Several different FFS code
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
3 implementations, and correspondingly several different on-flash data formats,
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
4 have been used throughout the history of TI's involvement in the wireless
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
5 terminal business. The FFS incarnation of primary interest to the FreeCalypso
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
6 project is the one invented by Mads Meisner-Jensen at TI in the early 2000s
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
7 (at least according to the comments in the sources available to us), and it is
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
8 relevant to us in the following ways:
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
9
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
10 * When targeting the GSM modem in Openmoko's GTA01/02 smartphones, we need to
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
11 work with the original FFS from the factory (call it MokoFFS), the same FFS
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
12 as used by the mokoN firmwares: this FFS contains the IMEI and the RF
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
13 calibration values from the factory, which we most certainly don't want to go
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
14 without.
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
15
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
16 * The Leonardo firmware semi-src which we are using as the reference for
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
17 building our own full source, multi-target GSM fw contains a turnkey-working
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
18 implementation of this very FFS, using the on-flash format in question and
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
19 providing run-time APIs expected by the rest of the GSM fw suite. Following
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
20 the principle of ``if it ain't broke, don't fix it'', we can use this FFS not
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
21 only on the gtamodem target, but also on other targets, including those where
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
22 we would be starting from a blank state and thus have the freedom to use
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
23 whatever FFS we like.
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
24
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
25 * The original proprietary fw on the Pirelli DP-L10 phone also happens to use
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
26 an FFS in the same format. Pirelli's FFS does *not* contain the IMEI or any
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
27 of the RF calibration values though, and trying to reuse it directly for our
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
28 own FC GSM fw seems to be more trouble than benefit - so we'll probably have
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
29 our fw start with a blank TIFFS instead - but there is still insight to be
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
30 gained from in-vitro examination of captured Pirelli FFS images.
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
31
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
32 Naming
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
33 ======
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
34
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
35 I have previously referred to the FFS format in question as Mokopir-FFS or
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
36 MPFFS, from "Moko" and "Pirelli". I was originally hesitant to call it TIFFS,
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
37 as lacking the source code, I had no way of knowing whether the FFS format and
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
38 implementation were of TI's own invention, or something that TI licensed as a
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
39 black box from one of their many proprietary software partners. (I was unable
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
40 to identify it as any well-known, industry-standard FFS format, but absence of
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
41 evidence is not evidence of absence.) But now that we have TI's original source
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
42 code which implements this FFS (first the MV100-0.1.rar source, then the full
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
43 Leonardo one), complete with comments and a HISTORY file, we know that our FFS
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
44 was invented and implemented by someone named Mads Meisner-Jensen at TI - I'm
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
45 guessing in the SSA group in Nice, France.
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
46
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
47 I am now making a naming transition from MPFFS to TIFFS: there is really no
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
48 link between this FFS format and the Openmoko+Pirelli duo, other than the
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
49 happenstance of me having first encountered this FFS on these two GSM device
2900fe603f8a beginning of MPFFS->TIFFS naming convention change
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents:
diff changeset
50 brands, and the name TIFFS is more neutrally-descriptive.
227
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
51
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
52 What it is
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
53 ==========
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
54
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
55 In a rare departure from TI's norm (most of TI's GSM firmware and associated
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
56 development tools suffer from heavy Windows poisoning), what I call TIFFS is
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
57 very Unixy. It is a file system with a hierarchical directory tree structure
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
58 and with Unixy forward-slash-separated, case-sensitive pathnames; the semantics
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
59 of "what is a file" and "what is a directory" are exactly the same as in UNIX;
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
60 and TIFFS even supports symlinks, although that support is a little under-
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
61 developed, and apparently no FFS symlinks were ever used in any production GSM
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
62 device. Thus the FFS implemented in TI-based GSM devices (modems and
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
63 "dumbphones") is really no different from, for example, JFFS2 in embedded Linux
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
64 systems.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
65
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
66 (The only traditional UNIX file system features which are missing in TIFFS are
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
67 the creation/modification/access timestamps and the ownership/permission
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
68 fields.)
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
69
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
70 The FFS in a GSM device typically stores two kinds of content:
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
71
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
72 * Factory data: IMEI, RF calibration values, device make/model/revision
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
73 ID strings etc. These files are expected to be programmed on the factory
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
74 production line and not changed afterward.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
75
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
76 * Dynamic data written into the FFS in normal device operation: when you use a
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
77 "dumbphone" running TI-based firmware, every time you store something "on the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
78 phone" or in "non-volatile memory", that item is actually stored in the FFS.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
79 (Where else, if you think of it?) That includes contacts and received SMS
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
80 stored "on the phone" instead of the SIM, any selections you make in the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
81 settings/preferences menus which persist across reboots (power cycles), call
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
82 history etc.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
83
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
84 It needs to be noted that the "dynamic data" aspect of FFS usage applies not
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
85 only to complete phones, but also to modems like the one used in the GTA01/02.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
86 One would naively think that non-volatile storage of data in flash outside of
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
87 factory programming would be needed only in a device with its own UI, and that
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
88 a modem subservient to external AT commands would be completely stateless
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
89 across reboot/power cycles; but that is not the case in actuality. TI's GSM
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
90 firmwares, including the Openmoko ones (the "standard" mokoN), are designed to
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
91 always "mount" their FFS with read/write access; TI's FFS implementation in the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
92 firmware has no concept of a "read-only mount".
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
93
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
94 I am still investigating just what kinds of data are routinely written into the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
95 non-volatile FFS by the firmware in normal operation on devices like the GTA0x
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
96 modem, but there most definitely are some.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
97
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
98 There is no hard separation between "static" and "dynamic" data in the file
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
99 system structure; TIFFS is thus akin to an embedded Linux system with just a
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
100 single root file system containing both "static" files like userland binaries
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
101 and "dynamic" ones like configuration files under /etc which the user is
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
102 expected to edit with vi after logging into the box, or log and similar files
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
103 created by the system itself under /var, for example.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
104
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
105 Where it lives
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
106 ==============
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
107
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
108 The type of flash memory used in Calypso GSM modems and "dumbphones" is called
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
109 NOR flash. This NOR flash memory is physically divided (by the design of the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
110 flash chip itself) into units called "sectors" or more descriptively, erase
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
111 blocks. The typical NOR flash sector size (in Calypso GSM devices) ranges from
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
112 64 KiB in the GTA02 modem's NOR flash (4 MiB total) to 256 KiB in the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
113 S71PL129NC0 flash+RAM chip used in the Pirelli DP-L10 (16 MiB of flash total).
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
114 The key physical property is that any bit may be changed from a '1' to a '0' at
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
115 any time, in any combination, but resetting of '0' bits back to ones can be
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
116 done only on the granularity of these largish sectors, in an operation called
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
117 "sector erase".
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
118
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
119 The location of TIFFS within the flash memory of a given GSM device is defined
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
120 by the firmware design of that device, but is always some integral number of
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
121 contiguous flash sectors. Some examples:
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
122
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
123 * On the GTA01/02 GSM modem, FFS occupies 7 sectors of 64 KiB each, starting at
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
124 flash offset 0x380000.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
125
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
126 * On the Pirelli DP-L10, the FFS used by the original proprietary fw occupies
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
127 18 sectors of 256 KiB each (for 4.5 MiB in total), starting at the beginning
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
128 of the 2nd flash chip select (0x02000000 in the ARM7 address space).
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
129
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
130 * The smallest real FFS configuration called for by the table in dev.c in TI's
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
131 original Leonardo fw source is 3 sectors of 64 KiB each; the same table also
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
132 sports a 4 KiB x 4 configuration for RAM-based testing (emulation of FFS in
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
133 RAM without real flash).
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
134
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
135 * The largest FFS configuration that has been envisioned by the original
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
136 designers seems to be somewhere around 128 sectors.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
137
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
138 Each flash sector used for TIFFS begins with this 6-byte signature:
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
139
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
140 46 66 73 23 10 02
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
141
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
142 The first 4 bytes are 'Ffs#' in ASCII, and the following two bytes are the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
143 format version number of 0x0210 in little-endian byte order. The following two
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
144 bytes give a count of how many times that sector has been erased and rewritten
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
145 (FF FF in "fresh" or "virgin" FFS images), and the following byte indicates
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
146 that block's role and status in the FFS life cycle.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
147
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
148 How it works
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
149 ============
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
150
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
151 Just like JFFS2 and other high-quality flash file systems, TIFFS is designed to
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
152 recover gracefully from any possible power failure or crash: one can yank the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
153 battery from the GSM device (or induce a firmware crash) at the most mis-
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
154 opportune moment in the middle of an FFS write operation, and the FFS is
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
155 expected to recover on the next boot cycle. I won't be able to document here
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
156 all gory details of exactly how this goal is achieved, partly because I haven't
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
157 studied the code to the requisite level of depth myself yet, but all of the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
158 responsible code lives under gsm-fw/services/ffs in this freecalypso-sw source
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
159 tree; feel free to study it.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
160
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
161 In its "normal" or "clean" state (i.e., when not in the middle of a write
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
162 operation or recovery from an ungracefully interrupted one), a TIFFS instance
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
163 consists of the following 3 types of blocks:
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
164
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
165 * One block containing inode records, indicated by AB in its type/flags/status
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
166 byte in the block header;
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
167 * N-2 blocks (where N is the total number of flash sectors allocated for the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
168 FFS) containing (or waiting to be filled with) data chunks - indicated by BD
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
169 in the type/flags/status byte;
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
170 * One "free" block, indicated by BF - destined to become a new AB or a new BD
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
171 at some point.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
172
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
173 Each object written into the FFS (file, directory or symlink) consists of a
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
174 16-byte inode record written into the AB block and a data chunk written into
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
175 one of the BD blocks. The data chunk includes the name of the object, hence
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
176 one is required even for directories. Data chunks are contiguous, uncompressed,
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
177 and subject to an upper size limit of 2048 or 8192 bytes, depending on the FFS
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
178 configuration. Files larger than this limit are stored in a "segmented" form,
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
179 giving rise to a 4th inode or object type (after file, directory and symlink):
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
180 segment. Each segment of a segmented file consists of not only a data chunk,
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
181 but also an inode record for the segment, which gives the location of the data
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
182 chunk and ties the segment object into the overall FFS structure, making it
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
183 accessible.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
184
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
185 Because aside from complete sector erasure, flash memory bits can only
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
186 transition from '1' to '0' but not the other way around, overwriting an existing
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
187 file with some new content (an operation which any reasonable file system must
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
188 implement in some way) cannot be done in place. Instead like most flash file
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
189 systems, TIFFS implements this common operation by writing the new version of
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
190 the file to a new location (previously blank flash) and then invalidating the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
191 old version - and doing all that while keeping in mind the possibility of an
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
192 ungraceful crash or powerdown at any moment, and the requirement of recovering
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
193 gracefully from any such event.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
194
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
195 Of course as an FFS receives more write activity, even if one keeps overwriting
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
196 some existing files with new content of the same size, without adding to the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
197 visible total content size (think du(1) command), eventually all remaining blank
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
198 flash space will fill up. At that point (or at some earlier point, depending
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
199 on the FFS design and/or configuration) the FFS has to invoke a compaction or
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
200 reclamation or garbage collection procedure: any "mixed" blocks containing both
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
201 valid and stale data are transitioned into a "stale-only" state by having the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
202 active data moved to a new block, and then the "all stale" blocks are subjected
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
203 to sector erasure, becoming new blank sectors. The logic responsible for these
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
204 operations once again needs to be resilient to the possibility of a crash or
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
205 powerdown occurring at the most mis-opportune moment, and it also needs to
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
206 implement flash wear leveling: there is a physical limit to how many times a
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
207 given flash sector can be erased and rewritten before it goes bad.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
208
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
209 All of the above are common and well-known principles, successfully implemented
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
210 in well-known flash file systems such as JFFS2 in Linux. TIFFS is absolutely
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
211 no different in this regard; for the implementation details, read the source
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
212 code.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
213
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
214 How this FFS comes into being
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
215 =============================
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
216
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
217 (This section is only relevant to you if you plan on physically producing your
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
218 own GSM phones or modems on your own factory production line, like this author
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
219 fancies doing in the not-too-distant future, or if you simply enjoy knowing
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
220 how it is done.)
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
221
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
222 To my knowledge, TI never used or produced a tool akin to mkfs.jffs2 in the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
223 embedded Linux world, which would produce a TIFFS image complete with some
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
224 initial directory and file content "in vitro". Instead it appears that the FFS
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
225 instances found in shipped products such as Openmoko phones have been created
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
226 "in vivo" by TI's firmware running on the device itself during the "production
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
227 test" phase.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
228
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
229 The process seems to go like this:
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
230
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
231 * When the printed circuit board is physically populated with components such
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
232 as the Calypso chip and the flash chip, the latter can be blank - if the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
233 board design has the nIBOOT pin pulled low, enabling the Calypso boot ROM
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
234 (Openmoko and Pirelli both good on this one, but shame on Compal!), there is
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
235 no need to preprogram the flash chip with anything prior to populating it on
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
236 the board, and the device remains fully unbrickable at all times afterward.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
237
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
238 * When the assembled board is powered up for the first time, with completely
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
239 blank flash, the Calypso boot ROM will sit there and patiently wait for a
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
240 code download on either of its two UARTs.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
241
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
242 * Using TI's FLUID (Flash Loader Utility Independent of Device) or FreeCalypso's
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
243 fc-loadtool free replacement, the factory production station loads the main
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
244 firmware image into the flash. Note, it is just the firmware image at this
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
245 step, and the FFS sectors remain blank.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
246
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
247 * The board is commanded to reboot (or power-cycled), and the firmware image
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
248 boots for the first time.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
249
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
250 * TI's FFS implementation code in their standard firmware reacts to all blank
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
251 flash in the FFS sectors as follows: it performs what they call the preformat
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
252 operation, writing the TIFFS signature and a BF state byte into every FFS
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
253 sector, but the main "format" operation, which sets up the AB/BD block roles,
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
254 creates the root inode and makes the FFS ready to accept the creation of its
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
255 first directories and files, is not done automatically.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
256
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
257 In order to perform the FFS format operation and then fill the new FFS with
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
258 whatever directories and files are deemed needed to be present in "fresh"
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
259 shipping products, the factory production station connects to the just-booted
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
260 firmware running on the target via the RVT/ETM protocol (see the RVTMUX
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
261 write-up), and sends "test mode" commands to this running firmware. These
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
262 "FFS test mode" (or TMFFS) commands include the format operation, an mkdir
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
263 operation to create directories, and a "file write" operation akin to doing
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
264 'cat > /dir/whatever/file', creating files in FFS and storing any desired data
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
265 in them.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
266
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
267 The IMEI is assigned and written into FFS in this process, but it is not the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
268 only data item that will be unique for each individual device made. Much more
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
269 important are the RF calibration values: I have yet to learn exactly what is
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
270 being (or needs to be) measured, how these measurements are performed (under
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
271 what conditions; what external test equipment is needed), and how these measured
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
272 and recorded RF calibration values affect GSM device operation, but this TI
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
273 presentation gives some clues:
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
274
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
275 ftp://ftp.ifctf.org/pub/GSM/Calypso/rf_calibration.pdf
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
276
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
277 All of these calibration values are stored in a bunch of files under the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
278 /gsm/rf subtree, and these files seem to be "owned" by the L1 code. The latter
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
279 has RAM data structures which correspond to these files; upon normal boot the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
280 initialization code looks in FFS, and if it finds any of the RF calibration
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
281 files, it reads each present file into the corresponding RAM data structure,
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
282 overwriting the compiled-in defaults. It appears (slightly uncertain because I
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
283 have not yet reintegrated the code in question into our own gsm-fw) that the RF
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
284 calibration files in FFS come into being as follows:
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
285
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
286 * The RF calibration code in L1 (i.e., part of the main GSM fw) performs the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
287 measurements and stores results in its RAM data structures as commanded by
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
288 the production test station through the "test mode" interface;
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
289
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
290 * A final test mode command directs the above L1 code to write its RAM data
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
291 structures into FFS.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
292
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
293 Once I actually learn this RF calibration process properly in connection with
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
294 building my own Calypso-based GSM "dumbphone", I'll be able to say exactly what
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
295 it would take to recreate these RF calibration values if they are lost. But
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
296 until then the only advice I can give is to make a backup copy of your modem
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
297 FFS with fc-loadtool, and to save it securely.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
298
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
299 FreeCalypso support for TIFFS
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
300 =============================
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
301
250
3d88461d8284 beginning of TIFFS IVA documentation
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 227
diff changeset
302 Aside from implementing and using it in our own gsm-fw, FreeCalypso offers
227
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
303 the following support for TIFFS:
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
304
250
3d88461d8284 beginning of TIFFS IVA documentation
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 227
diff changeset
305 1. We have a utility for "in vitro" examination of FFS images read out of GSM
3d88461d8284 beginning of TIFFS IVA documentation
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 227
diff changeset
306 devices with fc-loadtool. This tiffs utility (along with mokoffs and pirffs
3d88461d8284 beginning of TIFFS IVA documentation
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 227
diff changeset
307 wrappers) lives in the ffstools top-level directory of the freecalypso-sw
3d88461d8284 beginning of TIFFS IVA documentation
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 227
diff changeset
308 source tree. This TIFFS "in vitro analyzer" utility supplants the earlier
3d88461d8284 beginning of TIFFS IVA documentation
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 227
diff changeset
309 mpffs-* tools, and adds some additional examination functionality. It is
3d88461d8284 beginning of TIFFS IVA documentation
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 227
diff changeset
310 strictly a "read only" tool, however - it is not designed for "in vitro"
3d88461d8284 beginning of TIFFS IVA documentation
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 227
diff changeset
311 editing" of TIFFS images.
227
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
312
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
313 2. A number of FC tools may be strung together into a kit for editing the FFS
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
314 content of a GSM device, e.g., for changing the IMEI. The following pieces
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
315 will be involved:
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
316
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
317 * What is destined to eventually become our totally free GSM fw (the gsm-fw
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
318 source subtree at the top of freecalypso-sw) does not contain any of the
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
319 actual GSM protocol stack (or even L1) functionality yet, but it already
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
320 contains both the FFS code and those components (ETM and TMFFS[12]) which
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
321 are needed for interfacing an external "test mode shell" to this FFS
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
322 implementation through the RVTMUX interface. And when our gsm-fw does gain
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
323 the actual GSM functionality, the ability to build a minimal FFS+ETM-only
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
324 configuration will still be retained.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
325
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
326 * The minimal FFS+ETM subset of gsm-fw can be built into a ramImage (runs
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
327 entirely from RAM via fc-xram, no flashing), and run on a physical device
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
328 such as the GTA0x GSM modem via the fc-xram host utility;
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
329
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
330 * After loading the ramImage, fc-xram will immediately exec our rvinterf host
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
331 utility described in the RVTMUX write-up;
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
332
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
333 * Once the GSM device is running what is effectively an FFS editing agent out
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
334 of RAM, accessed via rvinterf over the serial channel, the user will be able
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
335 to run fc-tmsh (or perhaps the FFS operations will be implemented in some
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
336 other utility, we'll see), and that "test mode shell" will provide commands
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
337 for writing things to FFS exactly like one would do in the factory production
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
338 line environment for which TI taylored their tools.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
339
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
340 The "in vivo" method of editing the FFS content of a GSM device described above
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
341 will probably sound very convoluted, and you may find yourself asking for a way
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
342 to do it "in vitro" instead: read the FFS out of flash with fc-loadtool, edit
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
343 that image "in vitro" with some utility on your PC, and then use fc-loadtool
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
344 again to program it back into your device. But consider that an "in vitro" FFS
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
345 modification would involve erasing and rewriting all sectors of your FFS,
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
346 whereas an "in vivo" modification of some small file like the IMEI would be
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
347 just a short flash write operation without any erasures at all, i.e., kinder
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
348 on the flash.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
349
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
350 In any case, the "in vivo" method will definitely be available soon because all
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
351 of the components involved therein are also needed for other development uses
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
352 in the FreeCalypso project, whereas developing a fully-functional "in vitro"
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
353 alternative (one that can create an FFS image "de novo" from a tree of files
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
354 and directories a la mkfs.jffs2, or add new files to an existing TIFFS image
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
355 etc) would be a good amount of extra work which we otherwise don't need - hence
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
356 the latter is not very likely to be written any time soon.
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
357
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
358 However, if the "in vitro" modification you seek is something trivial like
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
359 changing the byte content of a file such as /pcm/IMEI or /gsm/com/rfcap without
250
3d88461d8284 beginning of TIFFS IVA documentation
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 227
diff changeset
360 changing its length, you can use the existing "in vitro, read-only" tiffs host
3d88461d8284 beginning of TIFFS IVA documentation
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 227
diff changeset
361 utility to find the exact byte location of the file data within the TIFFS image,
3d88461d8284 beginning of TIFFS IVA documentation
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 227
diff changeset
362 and then use your favourite hex editor to whack whatever new byte content you
227
1852900ce9ea doc/TIFFS write-up
Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
parents: 224
diff changeset
363 like at that offset.