freecalypso-tools: doc/Rvinterf-tools annotate

annotate doc/Rvinterf-tools @ 1014:961efadd530a default tip

fc-shell TCH DL handler: add support for CSD modes TCH DL capture mechanism in FC Tourmaline firmware has been extended to support CSD modes in addition to speech - add the necessary support on the host tools side. It needs to be noted that this mechanism in its present state does NOT provide the debug utility value that was sought: as we learned only after the code was implemented, TI's DSP has a misfeature in that the buffer we are reading (a_dd_0[]) is zeroed out when the IDS block is enabled, i.e., we are reading all zeros and not the real DL bits we were after. But since the code has already been written, we are keeping it - perhaps we can do some tests with IDS disabled.

author	Mychaela Falconia <falcon@freecalypso.org>
date	Tue, 26 Nov 2024 06:27:43 +0000
parents	bdd92dba7dd9
children

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
948 d16222179c67 doc/Rvinterf-tools: document rvinterf -v changes Mychaela Falconia <falcon@freecalypso.org> parents: 915 diff changeset	105 (stdout and/or log file) omits certain packet exchanges: for TM/ETM
d16222179c67 doc/Rvinterf-tools: document rvinterf -v changes Mychaela Falconia <falcon@freecalypso.org> parents: 915 diff changeset	106 packet exchanges only a one-line summary is printed (no full hex dump),
d16222179c67 doc/Rvinterf-tools: document rvinterf -v changes Mychaela Falconia <falcon@freecalypso.org> parents: 915 diff changeset	107 whereas for packet exchanges with FC firmware TCH tap feature only a
d16222179c67 doc/Rvinterf-tools: document rvinterf -v changes Mychaela Falconia <falcon@freecalypso.org> parents: 915 diff changeset	108 count of sent and received TCH packets is printed in between other
d16222179c67 doc/Rvinterf-tools: document rvinterf -v changes Mychaela Falconia <falcon@freecalypso.org> parents: 915 diff changeset	109 (usually trace) packet types. With a single -v option a full hex dump
d16222179c67 doc/Rvinterf-tools: document rvinterf -v changes Mychaela Falconia <falcon@freecalypso.org> parents: 915 diff changeset	110 is added to the log output for TM/ETM packet exchanges; specifying -vv
d16222179c67 doc/Rvinterf-tools: document rvinterf -v changes Mychaela Falconia <falcon@freecalypso.org> parents: 915 diff changeset	111 causes all TCH packets to be dumped in raw hex as well.
915 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
950 bdd92dba7dd9 doc/Rvinterf-tools: document rvinterf -X option Mychaela Falconia <falcon@freecalypso.org> parents: 948 diff changeset	128 -X <virtual LCD program>
bdd92dba7dd9 doc/Rvinterf-tools: document rvinterf -X option Mychaela Falconia <falcon@freecalypso.org> parents: 948 diff changeset	129
bdd92dba7dd9 doc/Rvinterf-tools: document rvinterf -X option Mychaela Falconia <falcon@freecalypso.org> parents: 948 diff changeset	130 This option exists only to support an obsolete interface for virtual LCD
bdd92dba7dd9 doc/Rvinterf-tools: document rvinterf -X option Mychaela Falconia <falcon@freecalypso.org> parents: 948 diff changeset	131 output, originally implemented as an experiment in 2015 and never used
bdd92dba7dd9 doc/Rvinterf-tools: document rvinterf -X option Mychaela Falconia <falcon@freecalypso.org> parents: 948 diff changeset	132 with much success. The program named with this option (the intended
bdd92dba7dd9 doc/Rvinterf-tools: document rvinterf -X option Mychaela Falconia <falcon@freecalypso.org> parents: 948 diff changeset	133 usage is -X fc-lcdemu) will be launched via popen(3), and any received
bdd92dba7dd9 doc/Rvinterf-tools: document rvinterf -X option Mychaela Falconia <falcon@freecalypso.org> parents: 948 diff changeset	134 output from the target on FC-invented EXTUI RVTMUX channel will be
bdd92dba7dd9 doc/Rvinterf-tools: document rvinterf -X option Mychaela Falconia <falcon@freecalypso.org> parents: 948 diff changeset	135 forwarded to this program.
bdd92dba7dd9 doc/Rvinterf-tools: document rvinterf -X option Mychaela Falconia <falcon@freecalypso.org> parents: 948 diff changeset	136
432 5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	137 Client programs
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	138 ===============
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 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	141 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	142 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	143 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	144 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	145 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	146 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	147 with the -R option.
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	148
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	149 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	150 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	151 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	152 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	153 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	154 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	155 client programs:
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 -p /dev/ttyXXX
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	158
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	159 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	160 private instance of rvinterf on the named serial port.
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 -B baud
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	163 -l logfile
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	164 -w number_in_seconds
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 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	167 rvinterf.
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 -s pathname_for_socket
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	170
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	171 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	172 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	173 used.
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 Interactive vs. one-shot operation
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
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	178 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	179 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	180 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	181 (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	182 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	183 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	184 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	185
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	186 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	187 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	188 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	189 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	190 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	191 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	192 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	193 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	194 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	195 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	196 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	197 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	198 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	199
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	200 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	201 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	202 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	203 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	204 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	205 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	206 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	207 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	208
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	209 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	210 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	211 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	212 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	213 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	214 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	215 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	216 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	217 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	218 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	219
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	220 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	221 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	222 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	223 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	224 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	225 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	226
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	227 Startup synchronization hack
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	228 ============================
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	229
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	230 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	231 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	232 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	233 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	234 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	235 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	236 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	237 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	238 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	239 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	240 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	241 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	242 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	243 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	244 to do the first command-response packet exchange.
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	245
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	246 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	247 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	248 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	249 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	250 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	251 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	252 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	253 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	254 combination.
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	255
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	256 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	257 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	258 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	259 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	260 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	261 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	262 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	263 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	264 of slowdown to this rather contrived use case.

FreeCalypso > hg > freecalypso-tools

annotate doc/Rvinterf-tools @ 1014:961efadd530a default tip