/*
 * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */
#pragma ident	"@(#)README.coverage	1.3	06/10/25 SMI"

##
##	Code Coverage support in legion (coverage)
##
## This explains how to enable and use the coverage tool set.
##

[-] Enabling this Feature:

    See README.debug_hook for the overview of the debug_hook feature.

[-] Coverage Analysis:

    Description:
    This feature allows you to specify a range of %pc values for which you
    want to gather coverage data (ie. count the number of times each %pc
    is executed).

    Format:
         * debug_hook [coverage] [start] [end];
         *
         * [coverage]   - we've already parsed this. That's how we got here.
         * [datafile]   - name of the file to mmap (will contain coverage data)
         * [start]
         * [end]        - only trace when %pc is within [start]-[end] range
         *
         * All samples for %pc within the range supplied will be stored
         * in a data file (using the name provided in the directive). The
         * results of the coverage run can be viewed by running the
         * coverage_dump tool (in the build directory) at any time during
         * or after the run.
         * NOTE: this feature expects to create the datafile and will not
	 *       overwrite an existing one.

    Examples:
                processor "niagara" {
                        clkfreq 5000000 ;
                        cores 1;
                        vthreads 1;
                        nglobals 4;
                        nwins 8;
                        rstv 0xfff0000020;
                        maxtl 7;

			// gather coverage for all hypervisor %pc ranges 
			// and store the data in a file called datafile.
			debug_hook coverage datafile 0x100000 0x900000;
		}

    Viewing Data:
    All of the coverage data gets written to a datafile, the name of
    which is passed in as part of the config file. This file will
    contain the following format:
    Index: %pc: Ref_Cnt: Raw_Instn: Decoded_Instn

    There is a tool called coverage_dump which is provided in the build
    directory which can dump this datafile.
	see coverage_dump -h for more information

    Getting coverage data for Hypervisor:
    The coverage_dump tool will take the data that legion has written to
    your datafile and dump out raw coverage statistics for that range of
    %pc's. You can then use the coverage.pl script to analyze the raw
    data and to map it the dis-assembly output of your hypervisor. To do
    this you will need:

    1) add the coverage debug_hook in your legion config file (as
       shown above). Ensure that your range of addresses maps to the
       range where hypervisor runs from.

    2) boot legion and run whatever workload you are interested in using
       to exercise hypervisor (boot 4vvs, boot Solaris, trigger some error
       traps to exercise the error code paths)

    3) When legion is finished, run the coverage_dump utility passing it
       the name of your datafile eg:
	./coverage_dump -v datafile > coverage.log

    4) get a dis-assembly of your current hypervisor (the q.bin is not
       sufficient here, you will need the q binary that gets built in
       the same binary as your q.bin.
	eg:
	/usr/ccs/bin/dis q > q.dis
       If you have not built your own hypervisor, you can find the
       appropriate q binary from the gates section of the snapshot
       release directory. 
      (eg. /net/sunvx.sfbay/export/snapshot/sun4v_29/gates/hv-rock/src/rock/hypervisor/legion/q)

    5) run the coverage.pl script provided with legion. It expects to
       find a coverage.log and a q.dis file (as shown above) and it
       will create output files with the names coverage.txt and
       coverage.html.
       You need to specify the processor type [n1|n2|rock]
	eg:
	./coverage.pl rock

     6) You can now examine either the coverage.txt or coverage.html
        files to see which code paths in hypervisor were executed.

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