freecalypso-tools: doc/Rvinterf-tools annotate

annotate doc/Rvinterf-tools @ 505:7bf0d909c87e

fc-loadtool flash ID check: change of reset after the check logic This change only affects those flash configurations that have ID checks enabled. The logic for resetting the flash after the ID check has been changed as follows: 1) If the check fails, we return without attempting to reset the flash. 2) If the check is successful, we reset the flash using the configured method (could be AMD or Intel or Intel W30) instead of always doing an AMD flash reset as the original code did.

author	Mychaela Falconia <falcon@freecalypso.org>
date	Mon, 27 May 2019 19:58:01 +0000
parents	5484dab78c33
children	5b88ba62b9ae

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
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	80 -s pathname_for_socket
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	81
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	82 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	83 /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	84 specified.
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 -S <file descriptor number>
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	87
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	88 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	89 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	90 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	91 running rvinterf instance.
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	92
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	93 -w number_in_seconds
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 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	96 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	97 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	98 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	99 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	100 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	101 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	102 (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	103
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	104 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	105 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	106 altogether.
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 Client programs
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	109 ===============
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	110
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	111 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	112 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	113 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	114 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	115 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	116 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	117 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	118 with the -R option.
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	119
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	120 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	121 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	122 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	123 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	124 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	125 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	126 client programs:
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 -p /dev/ttyXXX
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 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	131 private instance of rvinterf on the named serial port.
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	132
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	133 -B baud
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	134 -l logfile
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	135 -w number_in_seconds
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 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	138 rvinterf.
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 -s pathname_for_socket
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	141
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	142 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	143 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	144 used.
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 Interactive vs. one-shot operation
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
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	149 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	150 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	151 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	152 (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	153 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	154 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	155 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	156
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	157 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	158 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	159 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	160 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	161 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	162 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	163 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	164 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	165 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	166 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	167 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	168 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	169 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	170
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	171 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	172 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	173 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	174 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	175 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	176 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	177 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	178 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	179
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	180 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	181 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	182 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	183 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	184 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	185 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	186 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	187 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	188 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	189 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	190
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	191 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	192 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	193 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	194 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	195 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	196 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	197
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	198 Startup synchronization 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
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	201 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	202 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	203 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	204 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	205 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	206 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	207 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	208 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	209 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	210 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	211 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	212 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	213 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	214 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	215 to do the first command-response packet exchange.
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	216
5484dab78c33 doc/Rvinterf-tools write-up added Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	217 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	218 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	219 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	220 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	221 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	222 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	223 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	224 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	225 combination.
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 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	228 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	229 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	230 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	231 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	232 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	233 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	234 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	235 of slowdown to this rather contrived use case.

FreeCalypso > hg > freecalypso-tools

annotate doc/Rvinterf-tools @ 505:7bf0d909c87e