Manual Pages for UNIX Darwin command on man amber

AMBER(1) BSD General Commands Manual AMBER(1)

NAME

aammbbeerr - creates TT6, TT6E and FULL instruction traces

SYNOPSIS

aammbbeerr [-aa pid] [-AA pid] [-rr basename] [-zz] [-ff format] [-yy] [-pp]

[-ww count delay] [-dd delay] [-cc delay] [-ss count] [-ii] [-II] [-tt]

[-bb addr] [-BB symbol] [-ee addr] [-EE symbol] [-xx count] [executable

[args...]]

DESCRIPTION

aammbbeerr 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 ssiimmgg44 (Motorola 7400/7410) PowerPC simulator. TT6E extends the TT6 format with a few minor enhancements and is used by aacciidd, ssiimmgg44 and ssiimmgg55. 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.

NNOOTTEE:: Because of security constraints in recent versions of MacOS X

regarding inter-process communication, aammbbeerr can only be run using the

ssuuddoo command now. It will report an error and halt if it is not run in a privileged mode. OOPPTTIIOONNSS

-aa pid

-AA 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, aammbbeerr

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.

-rr 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 aammbbeerr, rather the next unused trace session number is used.

-zz Compress trace files on the fly using gzip compression.

-ff 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, aammbbeerr defaults to the TT6E encoder.

-yy Record symbol information file for all program counter

addresses encountered in a trace (encoded NSDictionary of NSValue (NSRange) to NSString mappings).

-pp Instrument trace files with synchronization point records

-ww count delay

Automatically record {count} sessions spaced {delay} (untraced) seconds apart.

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

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

-ss count Skip {count} instructions before tracing.

-ii 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 aammbbeerr is not actively tracing, tracing will start for all of the threads in the target process. If aammbbeerr is already tracing, the current session will end and tracing will stop.

-II 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 aammbbeerr is

not actively tracing, tracing will start ONLY for the instru-

mented thread. If aammbbeerr is already tracing, the current ses-

sion will end and tracing will stop.

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

-bb addr Tracing will begin when the address addr (specified in hexa-

decimal) is encountered.

-BB symbol Tracing will begin when the address corresponding to the

first instruction in symbol is encountered.

-ee addr Tracing will end when the address addr (specified in hexadec-

imal) is encountered.

-EE symbol Tracing will end when the address corresponding to the first

instruction in symbol is encountered.

-xx count Stop tracing after {count} instructions have been recorded.

AAMMBBEERR LLIIBBRRAARRYY

You can create a custom version of aammbbeerr 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/testfilter.c for an example of how the aammbbeerr library can be used. To link the example custom trace filter: cc

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