FreeCalypso > hg > freecalypso-tools
comparison doc/Rvinterf-logs @ 951:297c7d5b57a2
doc/Rvinterf-logs: new document
| author | Mychaela Falconia <falcon@freecalypso.org> |
|---|---|
| date | Wed, 07 Jun 2023 07:52:55 +0000 |
| parents | |
| children |
comparison
equal
deleted
inserted
replaced
| 950:bdd92dba7dd9 | 951:297c7d5b57a2 |
|---|---|
| 1 The purpose of "live" output from rvinterf (stdout) is to allow FreeCalypso | |
| 2 developers (and tinkerer-level users) to see what the target firmware is doing | |
| 3 in real time; the purpose of the log file created with -l option is to allow | |
| 4 more detailed analysis at a later time. In most cases the same output lines are | |
| 5 printed to both stdout and the log file, but there are some hex dumps of sent | |
| 6 and received packets that are printed only to the log file when one is being | |
| 7 written, and get printed to stdout only when there is no log file - such | |
| 8 exceptions are listed under the respective log item descriptions in this | |
| 9 document. | |
| 10 | |
| 11 For the most part, every packet sent to the target (by way of a client program | |
| 12 connecting to the rvinterf socket interface) and every RVTMUX packet received | |
| 13 from the target results in a log item being printed. The only exceptions are | |
| 14 made for certain highly voluminous packet exchanges: packets going to and from | |
| 15 our FC-invented TCH tap mechanism are normally elided from the output, and | |
| 16 packets emitted on the obsolete EXTUI channel (implemented only in special hack | |
| 17 firmware versions from 2015) are also elided from stdout and log outputs when | |
| 18 that channel is piped to fc-lcdemu via -X option. | |
| 19 | |
| 20 In the new logging design as of fc-host-tools-r19, various packet types of | |
| 21 interest are logged as follows: | |
| 22 | |
| 23 * RiViera, L1 and GPF traces are expected to be ASCII strings. However, any | |
| 24 non-printable characters that occur in these traces (or any other context | |
| 25 where printable ASCII is normally expected, such as ATI exchanges) are printed | |
| 26 in C-style backslash escape form, using the following escapes: \r, \n, \0 | |
| 27 through \7 (when not followed by a digit) and \x00 through \xFF generic form. | |
| 28 Any already-present backslashes are doubled, thus the representation is | |
| 29 lossless. This design is a change from previous versions where we used | |
| 30 'cat -v' notation, which is a flawed representation because it does not allow | |
| 31 reconstruction of the original binary string. | |
| 32 | |
| 33 * When logging TM/ETM command packets sent to the target and the target's TM | |
| 34 response packets, rvinterf does a basic identification of what command it is, | |
| 35 or at least which TM or ETM component. By default only a single header line | |
| 36 is printed for each command packet and each response packet, giving this | |
| 37 identification. In rvinterf -v mode, a full hex dump of each TM/ETM packet | |
| 38 is also generated; if a log file is being written, this hex dump goes only to | |
| 39 that log, otherwise it goes to stdout. | |
| 40 | |
| 41 * Protocol stack binary primitives sent via GPF TST are printed as a header line | |
| 42 followed by a hex dump of all payload bytes after the opcode; the hex dump | |
| 43 portion goes only to the log if one is being written. | |
| 44 | |
| 45 * Unrecognized packet formats on the GPF channel (old version of GPF TST as seen | |
| 46 in the ancient 20020917 D-Sample firmware and on BenQ M32) are also printed as | |
| 47 hex dumps, however the new hex dump format includes ASCII on the right, thus | |
| 48 all ASCII strings emitted by those ancient firmwares will be readable. | |
| 49 | |
| 50 * Packets that are sent and received on FC-invented TCH RVTMUX channel are | |
| 51 normally not printed at all, as they are far too voluminous - instead a count | |
| 52 of sent and received TCH packets is printed in between other (usually trace) | |
| 53 packet types. To log these packets individually, run rvinterf -vv. In the | |
| 54 latter mode, if a log file is being written, the hex dump goes only to that | |
| 55 log, otherwise it goes to stdout. | |
| 56 | |
| 57 * If the firmware emits packets on EXTUI RVTMUX channel (also FC-invented, but | |
| 58 totally obsolete) but no LCD emulator pipe is created (rvinterf -X option), | |
| 59 each received EXTUI packet is logged as a single summary line; to add a full | |
| 60 hex dump (written to log file only if possible), run rvinterf -vv. | |
| 61 | |
| 62 * All other/unknown sent and received packet types are always dumped in hex, | |
| 63 both on stdout and in the log file. |