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 pri-
marily 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/Commands/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}. 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 taking
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 applica-
tions 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 (normally 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 (normally 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 instru-
mented thread. If amber is already tracing, the current ses-
sion will end and tracing will stop.
-t Start tracing on first illegal instruction (use in conjunc-
tion 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 hexa-
decimal) 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 hexadec-
imal) 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 applications that supports the API described in
/usr/include/amber.h. See /Library/Examples/CHUD/Amber/ExternalTrace-
Filter/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/PrivateFrameworks -framework Foundation
-framework CHUD -framework IOKit -lz -lamber -o myAmber The trace is sup-
plied 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
August 11, 2011
Mac OS X 10.7 - Generated Thu Aug 11 05:44:21 CDT 2011