FreeCalypso > hg > freecalypso-sw
comparison rvinterf/README @ 429:f114f5c547ec
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. |