--- /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.