view doc/Rvinterf-logs @ 956:b0b6966fa62e

doc/Target-boot-control: update for -Petmoff
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 07 Jun 2023 23:52:31 +0000
parents 297c7d5b57a2
children
line wrap: on
line source

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.