FreeCalypso > hg > freecalypso-tools

comparison doc/Rvinterf-tools @ 432:5484dab78c33

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Rvinterf-tools write-up added
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 04 Nov 2018 09:58:50 +0000
parents
children 5b88ba62b9ae
comparison
equal deleted inserted replaced
431:579441d7dcd8 432:5484dab78c33
1 This document describes the basic usage principles for our rvinterf suite of
2 tools, which is the subset of FC host tools for talking to TI-based GSM devices
3 via the RVTMUX binary packet interface.
4
5 rvtdump
6 =======
7
8 Rvtdump is a utility that listens on a serial port, receives traces or any other
9 packets emitted by the running firmware of a GSM device in TI's RVTMUX format,
10 decodes them into readable ASCII and emits them to stdout and/or to a log file.
11 It is to be invoked as follows:
12
13 rvtdump [options] /dev/ttyXXX
14
15 where the sole non-option argument is the serial port it should open and listen
16 on.
17
18 The available options are:
19
20 -b
21
22 Normally the rvtdump process remains in the foreground and emits its
23 output on stdout. The -b option suppresses the normal output and causes
24 rvtdump to put itself in the background: fork at startup, then have the
25 parent exit while the child remains running. -b is not useful and not
26 allowed without -l.
27
28 -B baud
29
30 Selects which RVTMUX serial channel baud rate our tool should listen
31 for. Defaults to 115200 baud, which is TI's default and is correct for
32 our standard FreeCalypso firmwares, for Openmoko's legacy firmwares and
33 for Pirelli's proprietary fw. Use -B 57600 for Compal's RVTMUX, the
34 one accessible via **16379#.
35
36 -d <file descriptor number>
37
38 This option is not meant for direct use by human users. It is inserted
39 automatically when rvtdump is launched from fc-xram as the secondary
40 program that immediately takes over the serial channel.
41
42 -l logfile
43
44 Log all received and decoded packets into the specified file in addition
45 to (without -b) or instead of (with -b) dumping them on stdout. Each
46 line in the log file is also time-stamped; the timestamps are in GMT
47 (gmtime(3)) instead of local time - Spacefalcon the Outlaw dislikes
48 local times.
49
50 rvinterf
51 ========
52
53 Rvinterf (the specific program by this name) is an extended version of rvtdump
54 (see above) that decodes and dumps and/or logs any and all output generated by
55 the firmware running on the target just like rvtdump, but also creates a local
56 UNIX domain socket on the host machine to which "client" programs can connect.
57 "Client" programs connecting to rvinterf via this local socket interface can:
58
59 1. Receive copies of selected RVTMUX packets coming from the target;
60
61 2. Send arbitrary RVTMUX packets toward the target.
62
63 Rvinterf is invoked just like rvtdump:
64
65 rvinterf [options] /dev/ttyXXX
66
67 The following options have the same meaning as in rvtdump, see the rvtdump
68 section above for the details: -b, -B, -d and -l. The only difference is that
69 -b without -l is potentially useful and thus allowed.
70
71 Additional rvinterf options which don't exist in rvtdump are:
72
73 -n
74
75 Suppress the output on stdout like -b, but don't fork into background.
76 This option is passed by "client" programs when they invoke rvinterf
77 behind the scenes instead of connecting to an already-running rvinterf
78 instance.
79
80 -s pathname_for_socket
81
82 By default the local UNIX domain socket created by rvinterf is bound to
83 /tmp/rvinterf_socket; this option allows any other pathname to be
84 specified.
85
86 -S <file descriptor number>
87
88 This option is not meant for direct use by human users. It is passed
89 by "client" programs when they invoke rvinterf behind the scenes with
90 an unnamed and unbound socket pair instead of conecting to an already-
91 running rvinterf instance.
92
93 -w number_in_seconds
94
95 Reliable UART communication with a Calypso GSM device that can
96 potentially enter the so-called "deep sleep" mode requires certain
97 special workarounds that could be described as a bit of an ugly hack:
98 see the Deep-sleep-support article for the gory details. The hack
99 implemented in rvinterf is as follows: if a packet is to be sent to the
100 target and more than a set time has elapsed since the last transmitted
101 packet, the packet is preceded by a "wake-up shot" of 64 0 bytes
102 (outside of a packet, ignored by the fw) and a 100 ms pause.
103
104 The -w option changes the elapsed time threshold at which the "wake-up
105 shot" is sent; the default is 7 s. Specify -w 0 to disable this hack
106 altogether.
107
108 Client programs
109 ===============
110
111 We have an entire family of so-called "client" programs which connect to
112 rvinterf via the local socket interface and use rvinterf as the back-end engine
113 for communicating with GSM device firmwares. The main ones are fc-fsio,
114 fc-shell and fc-tmsh described in the RVTMUX article, and the less important
115 ones are fc-memdump, fc-dspapidump, fc-readcal and fc-tmsync listed in
116 Host-tools-overview. There is also the fcup-rvtat program which is invoked
117 behind the scenes by fcup-* tools (see User-phone-tools) when they are used
118 with the -R option.
119
120 All of these client programs can work in one of two ways: they can connect to
121 an already running rvinterf process through the UNIX domain socket mechanism,
122 or they can launch their own private instance of rvinterf behind the scenes,
123 using an unnamed and unbound socket pair. (Don't try to have two or more
124 rvinterf instances running on the same serial port, it won't work.) The
125 following command line options are standardized across all of our rvinterf
126 client programs:
127
128 -p /dev/ttyXXX
129
130 Don't connect to an already running rvinterf process, instead launch a
131 private instance of rvinterf on the named serial port.
132
133 -B baud
134 -l logfile
135 -w number_in_seconds
136
137 These options are valid only when -p is used, and are passed through to
138 rvinterf.
139
140 -s pathname_for_socket
141
142 Connect to a different local UNIX domain socket pathname instead of the
143 default /tmp/rvinterf_socket. This option is valid only when -p is not
144 used.
145
146 Interactive vs. one-shot operation
147 ==================================
148
149 Our main client programs fc-fsio, fc-shell, fc-tmsh and fc-tmsync can operate
150 in both interactive and one-shot modes. If there is a specific command given
151 on the invokation command line, that command is executed in the one-shot mode
152 (the program executes that one command, waits for the response from the target
153 if appropriate, and exits), otherwise each of the listed programs enters its
154 own interactive mode with its own prompt. The more specialized client programs
155 fc-memdump, fc-dspapidump and fc-readcal always operate in the one-shot manner.
156
157 fc-fsio, fc-tmsync and the just-listed specialized client programs are
158 synchronous in nature: whether they are used interactively or in a one-shot
159 manner (single command per program invokation), all of their operations are
160 built from command-response primitives: each internal low-level function sends
161 a command packet to the target via rvinterf and waits for a response from the
162 target; not getting a response or getting a wrong or unexpected response is a
163 fatal error. There is no such thing as a no-wait mode (one-shot or otherwise)
164 with these synchronous programs. Furthermore, what appears to be a single
165 command at the high level may consist of a large number of command-response
166 packet exchanges under the hood, and the one-shot mode can be used equally
167 easily to run a simple command or a script consisting of many commands. The
168 fcup-* -R mechanism (implemented by way of the fcup-rvtat back-end program) is
169 also synchronous like the fc-fsio and fc-tmsync family.
170
171 In contrast, fc-shell and fc-tmsh are asynchronous, and they work most naturally
172 in their interactive mode. An interactive fc-shell or fc-tmsh session is a
173 select loop that listens simultaneously for both user command input on the
174 terminal and packets from the target on the rvinterf socket; user commands cause
175 command packets to be sent to the target and any response packets received from
176 the target are decoded and displayed on the terminal, but these two directions
177 are completely decoupled from each other. The one-shot mode of operation is
178 inherently less natural with these programs, and constitutes a bit of a hack.
179
180 fc-tmsh offers the same repertoire of commands in both interactive and one-shot
181 modes, and each of these commands sends a Test Mode command packet to the
182 target. The one-shot mode is actually two modes: one-shot with a wait for a
183 target response (default) and one-shot with no wait (-n option). One-shot with
184 no wait is straighforward: fc-tmsh constructs the requested TM command packet,
185 sends it to the target via rvinterf and exits. In the other one-shot mode
186 without -n, fc-tmsh sends the command packet to the target and falls into a loop
187 processing input from rvinterf; as soon as some (any) packet is received from
188 the target on the TM channel, that packet (which is decoded and displayed) is
189 considered to be the response and the program exits with a success indication.
190
191 fc-shell is the oddest of the bunch: the set of one-shot commands is a subset
192 of those available in the interactive mode, as some of the commands cannot work
193 outside of the interactive mode select loop environment. Furthermore, almost
194 all of the one-shot commands in fc-shell always operate in the no-wait manner
195 whether -n is given or not. The only fc-shell one-shot commands which wait for
196 a target response in the absence of -n (similarly to fc-tmsh) are AT commands.
197
198 Startup synchronization hack
199 ============================
200
201 There is one annoying issue that has been seen with FTDI USB-serial adapters:
202 when the serial port served by an FTDI adapter has been receiving serial traffic
203 from the target while no host program is running with the port open to read it,
204 and then a host program is started, that newly started host program will often
205 get some stale or total garbage input from the freshly opened ttyUSBx port on
206 startup. In most usage scenarios this issue is not a killer for our rvinterf
207 suite, only an annoyance: if rvinterf is started on a serial port with this
208 initial garbage, there will be some garbage displayed by rvinterf initially,
209 but then it will quickly regain synchronization with the running firmware
210 target. If there is any delay between the starting of rvinterf and command-
211 response packet exchanges with the target (if rvinterf is run explicitly by the
212 operator first and then the client program, or if the client program that
213 launches rvinterf is an interactive one), no problems occur: rvinterf will be
214 in sync with the target with all initial garbage flushed by the time it needs
215 to do the first command-response packet exchange.
216
217 There is one potentially problematic usage scenario, though: consider what
218 happens when a one-shot operation is commanded, it is a type of one-shot
219 operation that includes waiting for a response from the target, and rvinterf is
220 being launched from the client program with -p. In this scenario there will be
221 a command packet sent to the target as soon as rvinterf starts up, and the
222 client program will expect rvinterf to capture and deliver the target fw's
223 response correctly, but there may not be enough time for rvinterf to clear the
224 initial garbage presented by the imperfect serial port hardware+driver
225 combination.
226
227 Our solution to this potential trouble source is a hack: in the special case
228 when rvinterf is being launched by the client program with -p and when the
229 client operation to be performed falls into the category of one-shot with a wait
230 for the target fw response, a 30 ms delay is inserted after the return from the
231 vfork call that launches rvinterf and before any actual operations. This hack
232 has been deemed to be acceptable because this combination of doing one-shot
233 operations while launching rvinterf with -p is not a very sensible way of using
234 our rvinterf tools generally, hence it has been deemed acceptable to add a bit
235 of slowdown to this rather contrived use case.