# HG changeset patch # User Mychaela Falconia # Date 1686124375 0 # Node ID 297c7d5b57a21b6b18b16476c7dfbd450bb8f81b # Parent bdd92dba7dd9eaf4e2c4782d36b9701090cdc374 doc/Rvinterf-logs: new document diff -r bdd92dba7dd9 -r 297c7d5b57a2 doc/Rvinterf-logs --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Rvinterf-logs Wed Jun 07 07:52:55 2023 +0000 @@ -0,0 +1,63 @@ +The purpose of "live" output from rvinterf (stdout) is to allow FreeCalypso +developers (and tinkerer-level users) to see what the target firmware is doing +in real time; the purpose of the log file created with -l option is to allow +more detailed analysis at a later time. In most cases the same output lines are +printed to both stdout and the log file, but there are some hex dumps of sent +and received packets that are printed only to the log file when one is being +written, and get printed to stdout only when there is no log file - such +exceptions are listed under the respective log item descriptions in this +document. + +For the most part, every packet sent to the target (by way of a client program +connecting to the rvinterf socket interface) and every RVTMUX packet received +from the target results in a log item being printed. The only exceptions are +made for certain highly voluminous packet exchanges: packets going to and from +our FC-invented TCH tap mechanism are normally elided from the output, and +packets emitted on the obsolete EXTUI channel (implemented only in special hack +firmware versions from 2015) are also elided from stdout and log outputs when +that channel is piped to fc-lcdemu via -X option. + +In the new logging design as of fc-host-tools-r19, various packet types of +interest are logged as follows: + +* RiViera, L1 and GPF traces are expected to be ASCII strings. However, any + non-printable characters that occur in these traces (or any other context + where printable ASCII is normally expected, such as ATI exchanges) are printed + in C-style backslash escape form, using the following escapes: \r, \n, \0 + through \7 (when not followed by a digit) and \x00 through \xFF generic form. + Any already-present backslashes are doubled, thus the representation is + lossless. This design is a change from previous versions where we used + 'cat -v' notation, which is a flawed representation because it does not allow + reconstruction of the original binary string. + +* When logging TM/ETM command packets sent to the target and the target's TM + response packets, rvinterf does a basic identification of what command it is, + or at least which TM or ETM component. By default only a single header line + is printed for each command packet and each response packet, giving this + identification. In rvinterf -v mode, a full hex dump of each TM/ETM packet + is also generated; if a log file is being written, this hex dump goes only to + that log, otherwise it goes to stdout. + +* Protocol stack binary primitives sent via GPF TST are printed as a header line + followed by a hex dump of all payload bytes after the opcode; the hex dump + portion goes only to the log if one is being written. + +* Unrecognized packet formats on the GPF channel (old version of GPF TST as seen + in the ancient 20020917 D-Sample firmware and on BenQ M32) are also printed as + hex dumps, however the new hex dump format includes ASCII on the right, thus + all ASCII strings emitted by those ancient firmwares will be readable. + +* Packets that are sent and received on FC-invented TCH RVTMUX channel are + normally not printed at all, as they are far too voluminous - instead a count + of sent and received TCH packets is printed in between other (usually trace) + packet types. To log these packets individually, run rvinterf -vv. In the + latter mode, if a log file is being written, the hex dump goes only to that + log, otherwise it goes to stdout. + +* If the firmware emits packets on EXTUI RVTMUX channel (also FC-invented, but + totally obsolete) but no LCD emulator pipe is created (rvinterf -X option), + each received EXTUI packet is logged as a single summary line; to add a full + hex dump (written to log file only if possible), run rvinterf -vv. + +* All other/unknown sent and received packet types are always dumped in hex, + both on stdout and in the log file.