ACID(1) ACID(1)

NAME
       acid - TT6E instruction trace analyzer; version 2.7

SYNOPSIS
       aacciidd [ -i filename ]
            [ -o filename ]
            [ -x filename ]
            [ -j filename,filename,filename... ]
            [ -n number ]
            [ -k number ]
            [ -e number ]
            [ -r number ]
            [ -y address ]
            [ -z address ]
            [ -aa ] [ -AA ] [ -bb ] [ -dd ] [ -ff ] [ -ss ] [ -tt ]

DESCRIPTION
       This manual page describes aacciidd, which is part of the Computer Hardware
       Understanding Toolkit (CHUD). Acid  analyzes  TT6E  instruction  traces
       generated  by amber or other instruction tracing programs. Characteris-
       tics of the trace such as instruction mix, address accesses, and  load-
       use  distance are output. Acid can also detect potentially bad instruc-
       tions sequences, where bad is defined as  having  misaligned  operands,
       data dependency stalls, or spilled loads. Acid can also be used to dis-
       assemble a trace or prune a trace into a subset of the original  trace.
       Note  that Acid is not reliable for analyzing trace files that exceed 2
       billion instructions.

OOPPTTIIOONNSS
       -ii ffiilleennaammee
                 The name of the input file to  analyze.  If  no  input
                 file is specified, stdin is used.

       -oo ffiilleennaammee
                 The  name of the file to send output to. If no file is
                 specified, results will go to stdout.

       -xx ffiilleennaammee
                 The name of the file to write a subset trace to.  This
                 option can be used with -n and -k to get an exact sub-
                 set of instructions. It can also be used with  -y  and
                 -z to remove functions. When used with -t, this is the
                 name of the TT6 output file which can be fed to simg4.

       -jj ffiilleennaammee,,ffiilleennaammee,,ffiilleennaammee,,......
                 Concatenate  trace files by inserting a 'b 0' instruc-
                 tion between traces. In this  mode,  the  output  file
                 specified  by  -o  is a new TT6 or TT6E file. No trace
                 statistics are generated.  The  list  of  input  files
                 should be comma-separated with no spaces.

       -nn nnuummbbeerr Analyze 'number' of instructions or less.

       -kk nnuummbbeerr Skip 'number' instructions before analyzing.

       -ee nnuummbbeerr Show addresses accessed at '2^number' bytes of address
                 granularity. For example, '-e 10' will show  addresses
                 in  blocks  of  1024 bytes. The default setting is '-e
                 12', so addresses will be grouped by 4KB segments (4KB
                 =  one  PowerPC page). Using smaller granularities may
                 increase processing time.

       -rr nnuummbbeerr Show address accesses every 'number' of  instructions.
                 This  option  creates  two files (instruction and data
                 accesses) that can be fed into gnuplot. You can detect
                 access patterns over time with this option.

       -yy aaddddrreessss
                 Replace the instruction at 'address' with the instruc-
                 tion at the 'z' address. Address should be a hexadeci-
                 mal  number.  The  'y'  and 'z' options can be used to
                 stub a function call by replacing the  first  instruc-
                 tion  in  the function with the last instruction (usu-
                 ally a 'blr').

       -zz aaddddrreessss
                 Replace the instruction at the 'y'  address  with  the
                 instruction at 'address'. Address should be a hexadec-
                 imal number. The 'y' and 'z' options can  be  used  to
                 stub  a  function call by replacing the first instruc-
                 tion in the function with the last  instruction  (usu-
                 ally a 'blr').

       -aa        Show  instructions  in assembly language form, display
                 potential stalls for PPC7410 and PPC7450 class proces-
                 sors,  show  misaligned operands, serializing instruc-
                 tions, and load spills. The format for the output col-
                 umns  is instruction number, program counter (instruc-
                 tion address), stalls on PPC7410 and PPC7450, and dis-
                 assembly.  Execution time will be substantially longer
                 when using this option and the  output  file  will  be
                 much larger.

       -AA        Show  instructions  as  in  -a,  but add several other
                 facts about the code. The format  for  the  output  is
                 instruction   number,   program  counter  (instruction
                 address), branch target address  (if  branch  instruc-
                 tion),  data  address  (if load or store instruction),
                 extra information (byte count for load/store string or
                 RB for a dst), target to use distance, update register
                 to use  distance  (for  updating  load/store  instruc-
                 tions), use distance for the condition register if the
                 instruction sets the CR, use  distance  for  the  link
                 register  if  the  instruction  sets the LR, stalls on
                 PPC7410 and PPC7450, and disassembly. The size of  the
                 output  file will be approximately 20x the size of the
                 input file, so the user  must  ensure  that  there  is
                 enough  disk  space to hold the output file. Execution
                 time will be  substantially  longer  when  using  this
                 option.

       -bb        Disassemble based on program counter. This output mode
                 will  print  instructions  and  frequency  ordered  by
                 instruction  address  rather  than simply printing out
                 instructions in sequential order. This is a quick  way
                 to detect code loops and hot spots in the trace.

       -dd        Output  data  access  addresses.  Accesses are labeled
                 with 'r', 'w', 's', 'S', 'f', 'T', 'a', 'z', 'I', 'd',
                 'D',  or  'k'  for  load,  store, dcbst, dcbtst, dcbf,
                 dcbt,  dcba,  dcbz,  dcbi,   dst/dstt,   dstst/dststt,
                 dss/dssall  respectively. The output contains the fol-
                 lowing information:  number  of  instructions  between
                 memory  accesses,  type of memory access, data address
                 of  memory  access,  and  load-to-use   distance   (in
                 instructions)  for  reads.  This option can be used to
                 feed a memory access driven model.

       -ff        Fast mode. Only outputs  instruction  mix  statistics.
                 Executes 2-3x faster than regular mode.

       -ss        Print  results  to  stderr.  Default is output file or
                 stdout.

       -tt        Convert TT6E trace file to TT6  format  for  input  to
                 simg4.  Specify  the  output trace file name using -x.
                 TT6 format does not contain an effective address spec-
                 ification for DCB* instructions.




CHUD                              1 Jan 2004                           ACID(1)