Index: lackey/docs/lk-manual.xml
===================================================================
--- lackey/docs/lk-manual.xml (revision 5788)
+++ lackey/docs/lk-manual.xml (working copy)
@@ -14,10 +14,10 @@
Overview
-Lackey is a simple valgrind tool that does some basic program
-measurement. It adds quite a lot of simple instrumentation to the
-program's code. It is primarily intended to be of use as an example
-tool.
+Lackey is a simple valgrind tool that does a simple trace ability and
+some basic program measurement. It adds quite a lot of simple
+instrumentation to the program's code. It is primarily intended to be of
+use as an example tool.It measures and reports:
@@ -63,6 +63,16 @@
When command line option
+ --trace-extent=calltree|function|all
+ is specified, this option specifies whether to trace the entire program, the
+ instructions in the function specified by
+ --fnname, or all instructions from entry
+ into the function until the function returns. The default is
+ calltree.
+
+
+
+ When command line option
--detailed-counts=yes is
specified, a table is printed with counts of loads, stores and ALU
operations for various types of operands.
@@ -70,15 +80,18 @@
The types are identified by their IR name ("I1" ... "I128",
"F32", "F64", and "V128").
+
+
+ When command line option
+ --trace-instrs=yes
+ is specified, it prints out every actually executed instructions.
+ When command line option
--trace-mem=yes is
specified, it prints out the size and address of almost every load and
- store made by the program. See Section 3.3.7 of Nicholas Nethercote's
- PhD dissertation "Dynamic Binary Analysis and Instrumentation", 2004,
- for details about the few loads and stores that it misses, and other
- caveats about the accuracy of the address trace.
+ store made by the program.
@@ -91,13 +104,6 @@
-Note that Lackey runs quite slowly, especially when
---detailed-counts=yes is specified.
-It could be made to run a lot faster by doing a slightly more
-sophisticated job of the instrumentation, but that would undermine
-its role as a simple example tool. Hence we have chosen not to do
-so.
-
@@ -116,8 +122,28 @@
Count calls to <name>.
+
+
+
+
+
-
+
+
+
+
+
+ Trace instructions.
+
+
+
+
+
+
+
+ Trace memory access.
+
+
@@ -132,4 +158,141 @@
+
+Trace Output
+
+The trace output consists of an ASCII-formatted trace of the instructions
+executed. The format is very simple to facilitate post-processing. The
+first character of each line ("record") indicates what kind of data is
+included in the line.
+
+
+Example
+Trace output is provided only if enabled. --trace-instr
+ enables H,
+I, J, and
+G records.
+--trace-mem=yes enables H, R, and W records.
+
+
+
+
+
+Record Definitions
+
+
+ H valgrind-itrace
+ Indicates the start of the trace, possibly with additional data in no
+specific format.
+
+
+ J aaaa xxxx [; symbol]
+ Instruction-with-address record. aaaa
+is the address of the instruction, xxxx is a
+byte dump of the instruction itself. All values are in hex.
+Optionally, a symbol name associated with the address may be provided.
+Note that J does not imply that a
+branch occurred, it merely indicates that the record includes the address
+of the instruction executed.
+
+
+ I xxxx
+ Instruction record for an instruction that immediately follows the
+previous instruction. The address can be determined from the length of
+the preceding instruction.
+
+
+ G
+ Indicates a gap in the trace. This will happen, for instance, when
+valgrind simulates a system call via an int 80 (on x86) or sc (on ppc)
+instruction, or when a branch occurs to code not being traced.
+
+
+ R aaaaaaaa rrrr
+ W aaaaaaaa wwww
+ Indicates that the previous instruction caused a read of the bytes
+rrrr at the addressaaaaaaaa
+, or a write of bytes wwww.
+The length of the read or write is indicated by the number of bytes shown.
+R and W
+records occur in logical order; for instance, an increment-memory instruction
+will show the read followed by the write.
+
+
+
+
+
+
+Limitations
+
+ Lackey runs quite slowly, especially when
+--detailed-counts=yes is specified. It could be made
+to run a lot faster by doing a slightly more sophisticated job of the
+instrumentation, but that would undermine its role as a simple example tool.
+Hence we have chosen not to do so.
+
+ Memory tracing cannot catch every load and store access. See section
+3.3.7 of Nicholas Nethercote's PhD dissertation "Dynamic Binary Analysis
+and Instrumentation", 2004, for details about the few loads and stores
+that is misses, and other caveats about the accuracy of the memory trace.
+
+
+ When --trace-extent=calltree is
+specified, the tracing will stop only when the function returns to its caller.
+Tracing will not stop if the function does not return to its caller.
+Some examples of this are raising C++ or Ada exceptions and longjump.
+Also, signals and task switching may cause unexpected code to be
+included in the trace.
+ Calltree tracing may not work, when lackey traces multithreaded
+code and signal handler, or VEX could not identify RET instructions on ISA.
+
+
+