FreeCalypso > hg > freecalypso-tools

annotate doc/Rvinterf-tools @ 619:f82551c77e58

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
libserial-newlnx: ASYNC_LOW_LATENCY patch reverted Reports from Das Signal indicate that loadtools performance on Debian is about the same as on Slackware, and that including or omitting the ASYNC_LOW_LATENCY patch from Serg makes no difference. Because the patch in question does not appear to be necessary, it is being reverted until and unless someone other than Serg reports an actual real-world system on which loadtools operation times are slowed compared to the Mother's Slackware reference and on which Slackware-like performance can be restored by setting the ASYNC_LOW_LATENCY flag.
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 27 Feb 2020 01:09:48 +0000
parents 5b88ba62b9ae
children ad503b495e3e
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
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 -b without -l is potentially useful and thus allowed.
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 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
72
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 -n
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 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
76 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
77 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
78 instance.
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79
587
5b88ba62b9ae doc/Rvinterf-tools: rvinterf -P option documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 432
diff changeset
80 -P <boot control name>
5b88ba62b9ae doc/Rvinterf-tools: rvinterf -P option documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 432
diff changeset
81
5b88ba62b9ae doc/Rvinterf-tools: rvinterf -P option documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 432
diff changeset
82 See Target-boot-control article.
5b88ba62b9ae doc/Rvinterf-tools: rvinterf -P option documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 432
diff changeset
83
432
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 -s pathname_for_socket
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 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
87 /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
88 specified.
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 -S <file descriptor number>
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 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
93 by "client" programs when they invoke rvinterf behind the scenes with
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 an unnamed and unbound socket pair instead of conecting to an already-
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 running rvinterf instance.
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 -w number_in_seconds
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 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
100 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
101 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
102 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
103 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
104 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
105 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
106 (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
107
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 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
109 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
110 altogether.
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 Client programs
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 ===============
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 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
116 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
117 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
118 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
119 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
120 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
121 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
122 with the -R option.
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 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
125 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
126 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
127 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
128 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
129 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
130 client programs:
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132 -p /dev/ttyXXX
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134 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
135 private instance of rvinterf on the named serial port.
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137 -B baud
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138 -l logfile
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
139 -w number_in_seconds
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
140
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141 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
142 rvinterf.
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144 -s pathname_for_socket
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146 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
147 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
148 used.
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 Interactive vs. one-shot operation
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
151 ==================================
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 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
154 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
155 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
156 (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
157 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
158 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
159 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
160
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161 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
162 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
163 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
164 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
165 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
166 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
167 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
168 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
169 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
170 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
171 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
172 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
173 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
174
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175 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
176 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
177 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
178 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
179 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
180 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
181 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
182 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
183
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
184 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
185 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
186 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
187 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
188 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
189 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
190 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
191 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
192 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
193 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
194
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
195 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
196 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
197 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
198 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
199 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
200 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
201
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
202 Startup synchronization hack
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
203 ============================
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
204
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
205 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
206 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
207 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
208 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
209 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
210 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
211 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
212 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
213 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
214 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
215 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
216 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
217 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
218 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
219 to do the first command-response packet exchange.
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 potentially problematic usage scenario, though: consider what
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
222 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
223 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
224 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
225 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
226 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
227 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
228 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
229 combination.
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
230
5484dab78c33 doc/Rvinterf-tools write-up added
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
231 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
232 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
233 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
234 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
235 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
236 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
237 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
238 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
239 of slowdown to this rather contrived use case.