# HG changeset patch # User Mychaela Falconia # Date 1446879591 0 # Node ID 53114af707f26b9c32b772580ed5b848aca210f0 # Parent f46a914c455ee8a0d15adf55eff4580dafa47447 rvinterf: both README files are now outdated, moved into doc as README.old and README.older diff -r f46a914c455e -r 53114af707f2 rvinterf/README --- a/rvinterf/README Sat Nov 07 06:50:06 2015 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,70 +0,0 @@ -You are looking at the suite of FreeCalypso tools for talking to the RVTMUX -interface provided by TI-based GSM firmwares. If you haven't already, please -read ../doc/RVTMUX first. - -The fundamental difference between these tools and loadtools is that loadtools -operate on a GSM device while its regular firmware is shut down, whereas the -present rvinterf tools talk to active running GSM firmwares. - -The following tools are currently implemented: - -rvtdump Opens the serial port, decodes TI's binary packet protocol, and - simply dumps every received/decoded packet on stdout in a human- - readable form. No provision for sending anything to the target. - Intended use: observing the debug trace output which all TI - firmwares emit as standard "background noise". This utility - allows one to observe/log/study the "noise" that appears on - Pirelli's USB-serial port (running Pirelli's original fw), - as well as that emitted on the IrDA (headset jack) port on the - GTA02 by mokoN/leo2moko firmwares. - -rvinterf Provides a bidirectional interface to RVTMUX on the host side. - It dumps and/or logs the "background noise" emitted by the - target just like rvtdump, but also creates a local UNIX domain - socket on the host machine to which other programs can connect, - replicating the MUXing function on the host side. - -fc-tmsh Interactive asynchronous test mode shell. This program connects - to a target GSM device through rvinterf and allows a developer- - operator to send various ETM commands to the target. ETM - responses are decoded (sometimes only lightly) and displayed. - fc-tmsh is fully asynchronous in that it continuously listens - (via select(2)) both for user input and for packets from the - target at the same time, translating any user-entered commands - into packets to the target and conversely, scribbling on the - terminal when a packet arrives from the target. It has no - knowledge of any correspondence between commands and responses - they normally elicit. - -g23sh Like fc-tmsh (same asynchronous design), but for GPF/G23 rather - than ETM. This tool and FreeCalypso project's understanding of - GPF/G23 in general are currently in the earliest stages, so it - is premature to try to describe it any further at this point. - -fc-sendsp Precursor to g23sh; even less worthy of further documentation. - -fc-fsio This program uses RVTMUX, ETM and TMFFS2 to access the live file - system of a running GSM firmware. Of the existing proprietary - firmwares, the only one that implements the TMFFS2 protocol - required for fc-fsio is Pirelli's, to the best of our knowledge. - This program connects to the target through rvinterf, but it - differs from fc-tmsh in that it operates in a synchronous - manner: the flow of operation is driven by user commands (just - like in fc-loadtool), and every time the program sends an ETM - command packet to the target, it expects a lock-step response. - -tfc139 See ../doc/Compal-unlock - -The fc-fsio, fc-tmsh and g23sh tools connect to the target not directly, but -via rvinterf. Two usage scenarios are supported: - -1. The user explicitly runs rvinterf (either directly or secondary to fc-xram, - when testing an experimental FreeCalypso firmware ramImage), leaves it - running (either backgrounded or in its own terminal window), and then runs - one of the "client" programs: fc-fsio, fc-tmsh or g23sh. The two programs - connect via local UNIX domain sockets on the host machine. - -2. All of the "client" programs under discussion can also launch rvinterf - themselves. An instance of rvinterf lauched in this manner becomes a child - process of the "client" program, terminating together with it, and the two - processes communicate via an unnamed and unbound socket pair. diff -r f46a914c455e -r 53114af707f2 rvinterf/README.old --- a/rvinterf/README.old Sat Nov 07 06:50:06 2015 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,89 +0,0 @@ -I (Spacefalcon the Outlaw, FreeCalypso developer) am still learning what kinds -of traffic may be passed across TI's RVTMUX binary-packet serial interface. We -already know that much of this traffic is debug trace output, i.e., -unidirectional and essentially unconditional output from the GSM device. All -of the "standard" firmwares we have (mokoN, our leo2moko which functions almost -identically, and Pirelli's fw) produce massive volumes of such trace output in -normal operation. We already know that this "unsolicited" trace output comes -in at least 3 different flavors: - -* RiViera traces emitted by rvf_send_trace() -* L1 traces -* G23 traces - -The RVTMUX interface can be used for more than just trace output, though: any -component in TI's fw suite can send and/or register to receive binary packets. -As I slowly work my way through various components which comprise TI's Leonardo -fw whose semi-source we use as our reference version, learning what they do and -reintegrating them in our own gsm-fw, I will undoubtedly uncover additional uses -to which the RVTMUX interface is put. - -Aside from the trivial provision in the RVT module itself whereby an external -host can send a command to the target to set a filter masking some of the RV -trace output, so far the only entity I've come across which accepts packets from -an external host is ETM (Enhanced Test Mode). ETM implements a registration -system of its own, whereby other modules can register with ETM to receive -certain external command messages passing first through RVT, then through ETM. - -Because I do not yet have a clear mental picture of *every* function for which -the RVTMUX interface will ever be used, it is correspondingly impractical to -decide on a once-and-for-all design of what the host-side software for talking -to this interface should be like. Therefore, it is currently premature to -expect any stability in the present rvinterf subdirectory of freecalypso-sw; I -may implement something one day, then toss it away the next day (without -providing much in the way of backward compatibility) when I come up with some -other idea. - -The current roadmap for what the rvinterf suite of host tools is envisioned to -look like eventually is as follows: - -rvtdump Opens the serial port, decodes TI's binary packet protocol, and - simply dumps every received/decoded packet on stdout in a human- - readable form. No provision for sending anything to the target. - Intended use: observing the debug trace output which all TI - firmwares emit as standard "background noise". This utility has - already been written, and it allows one to observe/log/study the - "noise" that appears on Pirelli's USB-serial port (running - Pirelli's original fw), as well as that emitted on the IrDA - (headset jack) port on the GTA02 by mokoN/leo2moko firmwares. - -rvinterf My plan is to make a copy of rvtdump, called rvinterf, and have - it act very much like rvtdump: receive TI's packets from the - serial port, decode them and print the decoded form on stdout. - However, rvinterf will also create a listening UNIX domain - socket to which other programs in the present suite will - connect. These other programs connecting through rvinterf will - be able to send packets to the target, as well as register to - receive certain kinds of target->host message packets. - -fc-tmsh FreeCalypso Test Mode Shell is my vision for the utility which - will provide a practically usable interface to ETM. ETM's - general mode of operation seems to be (weasel phrase inserted - because many other fw components may connect through ETM, and I - have yet to study all of them) command-response: an external - host sends a command to ETM, that command gets dispatched to the - proper registered handler, the command function is executed, a - response packet is composed, and finally that response is sent - back to the host. But because all code on the target side is - under active development and debugging, we should not expect - perfect lock-step behaviour on the interface; instead, our - fc-tmsh should be fundamentally asynchronous: when the user - enters a command, the appropriate command packet is sent to the - target, but we are prepared for target->host messages at any - time, without enforcing strict correspondence to issued - commands: let the developer-operator sort that out instead. - -The usage scenario I envision is that one will need to run rvinterf first -(either directly or through fc-xram) in one terminal window, leave it running, -then run fc-tmsh in another terminal window, and have it connect to rvinterf -via the local UNIX domain socket interface. Why such complexity, why not have -one program do everything? I suspect that in many debug/experimentation -sessions it will be necessary to use fc-tmsh on "noisy" targets, i.e., in -scenarios where the target is continuously spewing its "normal" voluminous debug -trace output, such that the "interesting" output as in responses to commands -gets drowned in the noise. In such a scenario it would be helpful to have one -terminal window in which one sees the transcript of the fc-tmsh session, -consisting of issued commands and received ETM responses without the general -noise, and another window in which one sees all RVTMUX interface activity in -real time - the latter would allow one to observe commands having side effects -outside of ETM, such as crashing the whole fw. :-) diff -r f46a914c455e -r 53114af707f2 rvinterf/doc/README.old --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/rvinterf/doc/README.old Sat Nov 07 06:59:51 2015 +0000 @@ -0,0 +1,70 @@ +You are looking at the suite of FreeCalypso tools for talking to the RVTMUX +interface provided by TI-based GSM firmwares. If you haven't already, please +read ../doc/RVTMUX first. + +The fundamental difference between these tools and loadtools is that loadtools +operate on a GSM device while its regular firmware is shut down, whereas the +present rvinterf tools talk to active running GSM firmwares. + +The following tools are currently implemented: + +rvtdump Opens the serial port, decodes TI's binary packet protocol, and + simply dumps every received/decoded packet on stdout in a human- + readable form. No provision for sending anything to the target. + Intended use: observing the debug trace output which all TI + firmwares emit as standard "background noise". This utility + allows one to observe/log/study the "noise" that appears on + Pirelli's USB-serial port (running Pirelli's original fw), + as well as that emitted on the IrDA (headset jack) port on the + GTA02 by mokoN/leo2moko firmwares. + +rvinterf Provides a bidirectional interface to RVTMUX on the host side. + It dumps and/or logs the "background noise" emitted by the + target just like rvtdump, but also creates a local UNIX domain + socket on the host machine to which other programs can connect, + replicating the MUXing function on the host side. + +fc-tmsh Interactive asynchronous test mode shell. This program connects + to a target GSM device through rvinterf and allows a developer- + operator to send various ETM commands to the target. ETM + responses are decoded (sometimes only lightly) and displayed. + fc-tmsh is fully asynchronous in that it continuously listens + (via select(2)) both for user input and for packets from the + target at the same time, translating any user-entered commands + into packets to the target and conversely, scribbling on the + terminal when a packet arrives from the target. It has no + knowledge of any correspondence between commands and responses + they normally elicit. + +g23sh Like fc-tmsh (same asynchronous design), but for GPF/G23 rather + than ETM. This tool and FreeCalypso project's understanding of + GPF/G23 in general are currently in the earliest stages, so it + is premature to try to describe it any further at this point. + +fc-sendsp Precursor to g23sh; even less worthy of further documentation. + +fc-fsio This program uses RVTMUX, ETM and TMFFS2 to access the live file + system of a running GSM firmware. Of the existing proprietary + firmwares, the only one that implements the TMFFS2 protocol + required for fc-fsio is Pirelli's, to the best of our knowledge. + This program connects to the target through rvinterf, but it + differs from fc-tmsh in that it operates in a synchronous + manner: the flow of operation is driven by user commands (just + like in fc-loadtool), and every time the program sends an ETM + command packet to the target, it expects a lock-step response. + +tfc139 See ../doc/Compal-unlock + +The fc-fsio, fc-tmsh and g23sh tools connect to the target not directly, but +via rvinterf. Two usage scenarios are supported: + +1. The user explicitly runs rvinterf (either directly or secondary to fc-xram, + when testing an experimental FreeCalypso firmware ramImage), leaves it + running (either backgrounded or in its own terminal window), and then runs + one of the "client" programs: fc-fsio, fc-tmsh or g23sh. The two programs + connect via local UNIX domain sockets on the host machine. + +2. All of the "client" programs under discussion can also launch rvinterf + themselves. An instance of rvinterf lauched in this manner becomes a child + process of the "client" program, terminating together with it, and the two + processes communicate via an unnamed and unbound socket pair. diff -r f46a914c455e -r 53114af707f2 rvinterf/doc/README.older --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/rvinterf/doc/README.older Sat Nov 07 06:59:51 2015 +0000 @@ -0,0 +1,89 @@ +I (Spacefalcon the Outlaw, FreeCalypso developer) am still learning what kinds +of traffic may be passed across TI's RVTMUX binary-packet serial interface. We +already know that much of this traffic is debug trace output, i.e., +unidirectional and essentially unconditional output from the GSM device. All +of the "standard" firmwares we have (mokoN, our leo2moko which functions almost +identically, and Pirelli's fw) produce massive volumes of such trace output in +normal operation. We already know that this "unsolicited" trace output comes +in at least 3 different flavors: + +* RiViera traces emitted by rvf_send_trace() +* L1 traces +* G23 traces + +The RVTMUX interface can be used for more than just trace output, though: any +component in TI's fw suite can send and/or register to receive binary packets. +As I slowly work my way through various components which comprise TI's Leonardo +fw whose semi-source we use as our reference version, learning what they do and +reintegrating them in our own gsm-fw, I will undoubtedly uncover additional uses +to which the RVTMUX interface is put. + +Aside from the trivial provision in the RVT module itself whereby an external +host can send a command to the target to set a filter masking some of the RV +trace output, so far the only entity I've come across which accepts packets from +an external host is ETM (Enhanced Test Mode). ETM implements a registration +system of its own, whereby other modules can register with ETM to receive +certain external command messages passing first through RVT, then through ETM. + +Because I do not yet have a clear mental picture of *every* function for which +the RVTMUX interface will ever be used, it is correspondingly impractical to +decide on a once-and-for-all design of what the host-side software for talking +to this interface should be like. Therefore, it is currently premature to +expect any stability in the present rvinterf subdirectory of freecalypso-sw; I +may implement something one day, then toss it away the next day (without +providing much in the way of backward compatibility) when I come up with some +other idea. + +The current roadmap for what the rvinterf suite of host tools is envisioned to +look like eventually is as follows: + +rvtdump Opens the serial port, decodes TI's binary packet protocol, and + simply dumps every received/decoded packet on stdout in a human- + readable form. No provision for sending anything to the target. + Intended use: observing the debug trace output which all TI + firmwares emit as standard "background noise". This utility has + already been written, and it allows one to observe/log/study the + "noise" that appears on Pirelli's USB-serial port (running + Pirelli's original fw), as well as that emitted on the IrDA + (headset jack) port on the GTA02 by mokoN/leo2moko firmwares. + +rvinterf My plan is to make a copy of rvtdump, called rvinterf, and have + it act very much like rvtdump: receive TI's packets from the + serial port, decode them and print the decoded form on stdout. + However, rvinterf will also create a listening UNIX domain + socket to which other programs in the present suite will + connect. These other programs connecting through rvinterf will + be able to send packets to the target, as well as register to + receive certain kinds of target->host message packets. + +fc-tmsh FreeCalypso Test Mode Shell is my vision for the utility which + will provide a practically usable interface to ETM. ETM's + general mode of operation seems to be (weasel phrase inserted + because many other fw components may connect through ETM, and I + have yet to study all of them) command-response: an external + host sends a command to ETM, that command gets dispatched to the + proper registered handler, the command function is executed, a + response packet is composed, and finally that response is sent + back to the host. But because all code on the target side is + under active development and debugging, we should not expect + perfect lock-step behaviour on the interface; instead, our + fc-tmsh should be fundamentally asynchronous: when the user + enters a command, the appropriate command packet is sent to the + target, but we are prepared for target->host messages at any + time, without enforcing strict correspondence to issued + commands: let the developer-operator sort that out instead. + +The usage scenario I envision is that one will need to run rvinterf first +(either directly or through fc-xram) in one terminal window, leave it running, +then run fc-tmsh in another terminal window, and have it connect to rvinterf +via the local UNIX domain socket interface. Why such complexity, why not have +one program do everything? I suspect that in many debug/experimentation +sessions it will be necessary to use fc-tmsh on "noisy" targets, i.e., in +scenarios where the target is continuously spewing its "normal" voluminous debug +trace output, such that the "interesting" output as in responses to commands +gets drowned in the noise. In such a scenario it would be helpful to have one +terminal window in which one sees the transcript of the fc-tmsh session, +consisting of issued commands and received ETM responses without the general +noise, and another window in which one sees all RVTMUX interface activity in +real time - the latter would allow one to observe commands having side effects +outside of ETM, such as crashing the whole fw. :-)