manpagez: man pages & more
man amber(1)
Home | html | info | man
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
© manpagez.com 2000-2025
Individual documents may contain additional copyright information.