FreeCalypso > hg > freecalypso-tools

annotate doc/Rvinterf-logs @ 1010:1d144553a5d0

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