AMBER(1) BSD General Commands Manual AMBER(1)
NAME
amber -- creates TT6, TT6E and FULL instruction traces
SYNOPSIS
amber [-a pid] [-A pid] [-r basename] [-z] [-f format] [-y] [-p] [-w count delay] [-d delay] [-c delay]
[-s count] [-i] [-I] [-t] [-b addr] [-B symbol] [-e addr] [-E symbol] [-x count] [executable
[args...]]
DESCRIPTION
amber traces all of the threads of execution in a process, recording every instruction and data access
to a trace file. Currently, three trace formats are supported: TT6, TT6E and FULL. TT6 is the oldest
and is primarily only used with the simg4 (Motorola 7400/7410) PowerPC simulator. TT6E extends the TT6
format with a few minor enhancements and is used by acid, simg4 and simg5. The FULL trace format
traces the contents of all PowerPC state along with each instruction. Differences between TT6 and TT6E
format as well as the specifics of the FULL trace formats are detailed in /Library/Documentation/Com-mands/amber/AmberTraceFormats.pdf. /Library/Documentation/Commands/amber/AmberTraceFormats.pdf.
mands/amber/AmberTraceFormats.pdf. NOTE: Because of security constraints in recent versions of MacOS X
regarding inter-process communication, amber can only be run using the sudo command now. It will
report an error and halt if it is not run in a privileged mode.
OPTIONS
-a pid
-A pid Attach to a currently running process with the specified PID. If the -A option is used,
tracing will begin immediately. If a PID is not given with either the -a or -A option,
amber will launch a new process from the specified executable. Either a PID with the -a or
-A pid option or an executable must be specified.
-r basename
Record traced instructions to a trace file named base-name_{x}/thread_{y}.{tt6,tt6e,br,full}. basename_{x}/thread_{y}.{tt6,tt6e,br,full}.
name_{x}/thread_{y}.{tt6,tt6e,br,full}. A session number beginning with 001 is substituted
for {x}. Likewise a thread number beginning with 001 is substituted for {y}. Existing
traces are never overwritten by amber, rather the next unused trace session number is used.
-z Compress trace files on the fly using gzip compression.
-f format Specify the trace format to be used. Valid format specifiers are '6' (TT6), 'e' (TT6E), and
'f' (FULL). If no trace format is given, amber defaults to the TT6E encoder.
-y Record symbol information file for all program counter addresses encountered in a trace
(encoded NSDictionary of NSValue (NSRange) to NSString mappings).
-p Instrument trace files with synchronization point records
-w count delay
Automatically record {count} sessions spaced {delay} (untraced) seconds apart.
-d delay Delay {delay} (untraced) seconds before tracing (beginning a new session). When used in
conjunction with the -w option, the delay specified by this option only occurs before tak-ing taking
ing the first session. Otherwise, the delay occurs before every session.
-c delay Delay {delay} microseconds between checks for newly spawned threads. This is useful when
tracing multi-threaded applications which may spawn new threads during a trace session.
Specifying delay=0 to disable this feature.
-s count Skip {count} instructions before tracing.
-i The traced application has been instrumented with pairs of privileged instructions (nor-mally (normally
mally illegal in user space) delimiting the start and stop of tracing. When an illegal
instruction is encountered, tracing is toggled. If amber is not actively tracing, tracing
will start for all of the threads in the target process. If amber is already tracing, the
current session will end and tracing will stop.
-I The traced application has been instrumented with pairs of privileged instructions (nor-mally (normally
mally illegal in user space) delimiting the start and stop of tracing. When an illegal
instruction is encountered, tracing is toggled. If amber is not actively tracing, tracing
will start ONLY for the instrumented thread. If amber is already tracing, the current ses-sion session
sion will end and tracing will stop.
-t Start tracing on first illegal instruction (use in conjunction with -i or -I). Subsequently
encountered illegal instructions appear in the trace as NOPs and do not control tracing.
-b addr Tracing will begin when the address addr (specified in hexadecimal) is encountered.
-B symbol Tracing will begin when the address corresponding to the first instruction in symbol is
encountered.
-e addr Tracing will end when the address addr (specified in hexadecimal) is encountered.
-E symbol Tracing will end when the address corresponding to the first instruction in symbol is
encountered.
-x count Stop tracing after {count} instructions have been recorded.
AMBER LIBRARY
You can create a custom version of amber using libamber. This primarily consists of creating an appli-cations applications
cations that supports the API described in /usr/include/amber.h. See /Library/Exam-ples/CHUD/Amber/ExternalTraceFilter/test_filter.c /Library/Examples/CHUD/Amber/ExternalTraceFilter/test_filter.c
ples/CHUD/Amber/ExternalTraceFilter/test_filter.c for an example of how the amber
library can be used. To link the example custom trace filter: cc test_filter.c -F/System/Library/Pri-vateFrameworks -F/System/Library/PrivateFrameworks
vateFrameworks -framework Foundation -framework CHUD -framework IOKit -lz -lamber -o myAmber The trace
is supplied to the external trace filter in TT6, TT6E or FULL trace format. It is the external trace
filter's responsibility to write the trace files (one per thread) to disk.
SEE ALSO
acid(1), /Developer/Examples/CHUD/Amber
April 2, 2008
|