legion/docs/readmes/README.lockstep

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

##
##      Lockstep Execution (lockstep)
##
## This explains how to enable and use the lockstep feature
##

[-] Enabling this Features:

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

[-] Lockstep Execution:

    Description:
    This feature allows you to run 2 simulators in lockstep. This could be
    used to run 2 copies of legion (one in 'master' mode and the other in
    'slave' mode) or to run legion in lockstep with another simulator or tool
    (assuming the other simulator/tool implements the 'slave' side of the
    lockstep feature).

    Each legion needs to have either a 'master' or a 'slave' lockstep
    directive added in order to be able to run them in lockstep.
    They must both be running on the same system and must have
    been started by the same user-id.

    Format:
         * debug_hook [lockstep] [mode] [start]
         *
         * [lockstep]   - we've already parsed this. That's how we got here.
         * [mode]       - master or slave
         *                master writes its data to shm region and waits for
         *                slave to compare. Dump any mismatches when simulators
         *                fall out of lockstep.
         * [start]      - optional, when supplied we enter into lockstep mode
         *                from this instn count onwards
         *

    Examples:
        Each legion needs to have either a 'master' or a 'slave' lockstep
        directive added to it's config file. Examples of both master and
        slave formats are below:

                processor "niagara" {
                        clkfreq 5000000 ;
                        cores 1;
                        vthreads 1;
                        nglobals 4;
                        nwins 8;
                        rstv 0xfff0000020;
                        maxtl 7;
                        // Lockstep examples:
                        // debug_hook lockstep master;
                        // debug_hook lockstep slave;
                        // debug_hook lockstep master 0x10;
                        // debug_hook lockstep slave 0x10;
                }

    Viewing Data:
    There is no data to be viewed until the simulators fall out of lockstep
    with each other. If this does happen, the instn and previous instn on
    both simualtors will be dumped with the complete register dump of both
    master and slave similators showing where the mismatch is.

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