FreeCalypso > hg > freecalypso-sw

comparison rvinterf/README @ 429:f114f5c547ec

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
rvinterf/README: beginning of proper documentation
author Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
date Sat, 21 Jun 2014 19:36:32 +0000
parents f42854da4563
children
comparison
equal deleted inserted replaced
428:e61eacecd319 429:f114f5c547ec
1 I (Spacefalcon the Outlaw, FreeCalypso developer) am still learning what kinds 1 You are looking at the suite of FreeCalypso tools for talking to the RVTMUX
2 of traffic may be passed across TI's RVTMUX binary-packet serial interface. We 2 interface provided by TI-based GSM firmwares. If you haven't already, please
3 already know that much of this traffic is debug trace output, i.e., 3 read ../doc/RVTMUX first.
4 unidirectional and essentially unconditional output from the GSM device. All
5 of the "standard" firmwares we have (mokoN, our leo2moko which functions almost
6 identically, and Pirelli's fw) produce massive volumes of such trace output in
7 normal operation. We already know that this "unsolicited" trace output comes
8 in at least 3 different flavors:
9 4
10 * RiViera traces emitted by rvf_send_trace() 5 The fundamental difference between these tools and loadtools is that loadtools
11 * L1 traces 6 operate on a GSM device while its regular firmware is shut down, whereas the
12 * G23 traces 7 present rvinterf tools talk to active running GSM firmwares.
13 8
14 The RVTMUX interface can be used for more than just trace output, though: any 9 The following tools are currently implemented:
15 component in TI's fw suite can send and/or register to receive binary packets.
16 As I slowly work my way through various components which comprise TI's Leonardo
17 fw whose semi-source we use as our reference version, learning what they do and
18 reintegrating them in our own gsm-fw, I will undoubtedly uncover additional uses
19 to which the RVTMUX interface is put.
20
21 Aside from the trivial provision in the RVT module itself whereby an external
22 host can send a command to the target to set a filter masking some of the RV
23 trace output, so far the only entity I've come across which accepts packets from
24 an external host is ETM (Enhanced Test Mode). ETM implements a registration
25 system of its own, whereby other modules can register with ETM to receive
26 certain external command messages passing first through RVT, then through ETM.
27
28 Because I do not yet have a clear mental picture of *every* function for which
29 the RVTMUX interface will ever be used, it is correspondingly impractical to
30 decide on a once-and-for-all design of what the host-side software for talking
31 to this interface should be like. Therefore, it is currently premature to
32 expect any stability in the present rvinterf subdirectory of freecalypso-sw; I
33 may implement something one day, then toss it away the next day (without
34 providing much in the way of backward compatibility) when I come up with some
35 other idea.
36
37 The current roadmap for what the rvinterf suite of host tools is envisioned to
38 look like eventually is as follows:
39 10
40 rvtdump Opens the serial port, decodes TI's binary packet protocol, and 11 rvtdump Opens the serial port, decodes TI's binary packet protocol, and
41 simply dumps every received/decoded packet on stdout in a human- 12 simply dumps every received/decoded packet on stdout in a human-
42 readable form. No provision for sending anything to the target. 13 readable form. No provision for sending anything to the target.
43 Intended use: observing the debug trace output which all TI 14 Intended use: observing the debug trace output which all TI
44 firmwares emit as standard "background noise". This utility has 15 firmwares emit as standard "background noise". This utility
45 already been written, and it allows one to observe/log/study the 16 allows one to observe/log/study the "noise" that appears on
46 "noise" that appears on Pirelli's USB-serial port (running 17 Pirelli's USB-serial port (running Pirelli's original fw),
47 Pirelli's original fw), as well as that emitted on the IrDA 18 as well as that emitted on the IrDA (headset jack) port on the
48 (headset jack) port on the GTA02 by mokoN/leo2moko firmwares. 19 GTA02 by mokoN/leo2moko firmwares.
49 20
50 rvinterf My plan is to make a copy of rvtdump, called rvinterf, and have 21 rvinterf Provides a bidirectional interface to RVTMUX on the host side.
51 it act very much like rvtdump: receive TI's packets from the 22 It dumps and/or logs the "background noise" emitted by the
52 serial port, decode them and print the decoded form on stdout. 23 target just like rvtdump, but also creates a local UNIX domain
53 However, rvinterf will also create a listening UNIX domain 24 socket on the host machine to which other programs can connect,
54 socket to which other programs in the present suite will 25 replicating the MUXing function on the host side.
55 connect. These other programs connecting through rvinterf will
56 be able to send packets to the target, as well as register to
57 receive certain kinds of target->host message packets.
58 26
59 fc-tmsh FreeCalypso Test Mode Shell is my vision for the utility which 27 fc-tmsh Interactive asynchronous test mode shell. This program connects
60 will provide a practically usable interface to ETM. ETM's 28 to a target GSM device through rvinterf and allows a developer-
61 general mode of operation seems to be (weasel phrase inserted 29 operator to send various ETM commands to the target. ETM
62 because many other fw components may connect through ETM, and I 30 responses are decoded (sometimes only lightly) and displayed.
63 have yet to study all of them) command-response: an external 31 fc-tmsh is fully asynchronous in that it continuously listens
64 host sends a command to ETM, that command gets dispatched to the 32 (via select(2)) both for user input and for packets from the
65 proper registered handler, the command function is executed, a 33 target at the same time, translating any user-entered commands
66 response packet is composed, and finally that response is sent 34 into packets to the target and conversely, scribbling on the
67 back to the host. But because all code on the target side is 35 terminal when a packet arrives from the target. It has no
68 under active development and debugging, we should not expect 36 knowledge of any correspondence between commands and responses
69 perfect lock-step behaviour on the interface; instead, our 37 they normally elicit.
70 fc-tmsh should be fundamentally asynchronous: when the user
71 enters a command, the appropriate command packet is sent to the
72 target, but we are prepared for target->host messages at any
73 time, without enforcing strict correspondence to issued
74 commands: let the developer-operator sort that out instead.
75 38
76 The usage scenario I envision is that one will need to run rvinterf first 39 g23sh Like fc-tmsh (same asynchronous design), but for GPF/G23 rather
77 (either directly or through fc-xram) in one terminal window, leave it running, 40 than ETM. This tool and FreeCalypso project's understanding of
78 then run fc-tmsh in another terminal window, and have it connect to rvinterf 41 GPF/G23 in general are currently in the earliest stages, so it
79 via the local UNIX domain socket interface. Why such complexity, why not have 42 is premature to try to describe it any further at this point.
80 one program do everything? I suspect that in many debug/experimentation 43
81 sessions it will be necessary to use fc-tmsh on "noisy" targets, i.e., in 44 fc-sendsp Precursor to g23sh; even less worthy of further documentation.
82 scenarios where the target is continuously spewing its "normal" voluminous debug 45
83 trace output, such that the "interesting" output as in responses to commands 46 fc-fsio This program uses RVTMUX, ETM and TMFFS2 to access the live file
84 gets drowned in the noise. In such a scenario it would be helpful to have one 47 system of a running GSM firmware. Of the existing proprietary
85 terminal window in which one sees the transcript of the fc-tmsh session, 48 firmwares, the only one that implements the TMFFS2 protocol
86 consisting of issued commands and received ETM responses without the general 49 required for fc-fsio is Pirelli's, to the best of our knowledge.
87 noise, and another window in which one sees all RVTMUX interface activity in 50 This program connects to the target through rvinterf, but it
88 real time - the latter would allow one to observe commands having side effects 51 differs from fc-tmsh in that it operates in a synchronous
89 outside of ETM, such as crashing the whole fw. :-) 52 manner: the flow of operation is driven by user commands (just
53 like in fc-loadtool), and every time the program sends an ETM
54 command packet to the target, it expects a lock-step response.
55
56 tfc139 See ../doc/Compal-unlock
57
58 The fc-fsio, fc-tmsh and g23sh tools connect to the target not directly, but
59 via rvinterf. Two usage scenarios are supported:
60
61 1. The user explicitly runs rvinterf (either directly or secondary to fc-xram,
62 when testing an experimental FreeCalypso firmware ramImage), leaves it
63 running (either backgrounded or in its own terminal window), and then runs
64 one of the "client" programs: fc-fsio, fc-tmsh or g23sh. The two programs
65 connect via local UNIX domain sockets on the host machine.
66
67 2. All of the "client" programs under discussion can also launch rvinterf
68 themselves. An instance of rvinterf lauched in this manner becomes a child
69 process of the "client" program, terminating together with it, and the two
70 processes communicate via an unnamed and unbound socket pair.