FreeCalypso > hg > freecalypso-tools

annotate doc/Rvinterf-tools @ 924:d452188587b4

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