AMBER(1)                                                 AMBER(1)



NAME
       amber - creates TT6, TT6E and FULL instruction traces

SYNOPSIS
       amber [ -a pid ] [ -r basename ] [ -z ] [ -f format ] [ -s
             n ] [ -i ] [ -b addr ] [ -B symbol ] [ -e addr ] [
             -E symbol ] [ -x n ] [ executable [args... ] ]

DESCRIPTION
       This  manual  page  describes  amber, which is part of the
       Computer  Hardware  UnDerstanding  (CHUD)  Toolkit.  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 Sim_G4 G4 (Motorola 7400/7410) PowerPC simu-
       lator. TT6E extends  the  TT6  format  with  a  few  minor
       enhancements. 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 format are detailed in  /Developer/Documen-
       tation/CHUD/AmberTraceFormats.pdf.

OPTIONS
       -apid     Attach  to  a  currently process with the
                 specified PID. If a  PID  is  not  given,
                 amber  will launch a new process from the
                 specified executable. Either a  PID  with
                 the  -a  pid option or an executable must
                 be specified.

       -rbasename
                 Record traced  instructions  to  a  trace
                 file              named             base-
                 name_{x}/thread_{y}.{tt6,tt6e}. A session
                 number  beginning with 001 is substituted
                 for {x}. Likewise a thread number  begin-
                 ning  with  001  is  substituted for {y}.
                 Existing traces are never overwritten  by
                 amber,  rather the next unused trace ses-
                 sion number is used.

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

       -fformat  Specify  the  trace  format  to  be used.
                 Valid format specifiers  are  '6'  (TT6),
                 and  'e'  (TT6E).  If  no trace format is
                 given,  amber  defaults   to   the   TT6E
                 encoder.

       -sn       Skip n instructions before tracing.

       -i        The  traced  application has been instru-
                 mented with a pair of privileged instruc-
                 tions  (normally  illegal  in user space)
                 delimiting the start and stop of tracing.
                 The  first privileged instruction encoun-
                 tered will start  tracing  and  the  next
                 will cause it to stop.

       -baddr    Tracing  will begin when the address addr
                 (specified  in  hexadecimal)  is  encoun-
                 tered.

       -Bsymbol  Tracing  will begin when the address cor-
                 responding to the  first  instruction  in
                 symbol is encountered.

       -eaddr    Tracing  will  end  when the address addr
                 (specified  in  hexadecimal)  is  encoun-
                 tered.

       -Esymbol  Tracing  will end when the address corre-
                 sponding to the first instruction in sym-
                 bol is encountered.

       -xn       Stop tracing after n instructions.


SEE ALSO
       /Developer/Examples/CHUD/Amber



CHUD                       23 May 2002                   AMBER(1)