legion/docs/readmes/README.trace

/*
 * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */
#pragma ident   "@(#)README.trace       1.1     05/07/29 SMI"

##
##      Instruction Tracing (trace)
##
## This explains how to enable and use the tracing feature
##

[-] Enabling this Features:

    See README.debug_hook for full details on how to enable this feature.

[-] Instruction Tracing:

    Description:
    This feature allows you to specify a range of %pc values or instn count
    ranges for which you want to gather instructon traces for.

    Format:
         * debug_hook [trace] [mode] [regs] [start] [end];
         *
         * [trace] - we've already parsed this. That's how we got here.
         * [mode]  - is one of [all, pc, instn]
         *              all   : traces all instns (no start, end values)
         *              pc    : just trace when %pc is withing start-end range
         *              instn : just trace when instn count is within start-end
         * [regs]  - if defined, we dump the %g,%o,%l,%i regs with each sample.
         * [start]
         * [end]   - only trace when %pc or inst_cnt is within [start]-[end]
         *              range
         *
         * All instruction traces for %pc or instn within the range supplied will
         * be displayed.
         *

    Examples:
                processor "niagara" {
                        clkfreq 5000000 ;
                        cores 1;
                        vthreads 1;
                        nglobals 4;
                        nwins 8;
                        rstv 0xfff0000020;
                        maxtl 7;
                        // Select one of the following formats:
                        //
                        // debug_hook trace all;
                        // debug_hook trace all regs;
                        // debug_hook trace pc 0x10a200 0x10a208;
                        // debug_hook trace pc regs 0x10a200 0x10a208;
                        // debug_hook trace instn 0x0 0x100;
                        // debug_hook trace instn regs 0x0 0x100;
                }

    Viewing Data:
    All of the instruction trace data gets written to the legion startup window
    and is formatted as follows (the register dump for each instuction can
    be toggled using the optional 'regs' flag in the config file as defined above.

[cpu] Instn_# tl:tt/gl    state %pc [raw_instn]         instn

[0x0] 0x0 7:0/3     0x4 0xfff0000020 [0x30800038]       ba,a    0xfff0000100
g0=0x0000000000000000 o0=0x0000000000000000 l0=0x0000000000000000 i0=0x0000000000000000
g1=0x0000000000000000 o1=0x0000000000000000 l1=0x0000000000000000 i1=0x0000000000000000
g2=0x0000000000000000 o2=0x0000000000000000 l2=0x0000000000000000 i2=0x0000000000000000
g3=0x0000000000000000 o3=0x0000000000000000 l3=0x0000000000000000 i3=0x0000000000000000
g4=0x0000000000000000 o4=0x0000000000000000 l4=0x0000000000000000 i4=0x0000000000000000
g5=0x0000000000000000 o5=0x0000000000000000 l5=0x0000000000000000 i5=0x0000000000000000
g6=0x0000000000000000 o6=0x0000000000000000 l6=0x0000000000000000 i6=0x0000000000000000
g7=0x0000000000000000 o7=0x0000000000000000 l7=0x0000000000000000 i7=0x0000000000000000


    Modifying Source:
    The source for the coverage feature is contained in
        src/procs/sunsparc/debug/trace.c