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