Initial commit of OpenSPARC T2 architecture model.

[OpenSPARC-T2-SAM] / legion / docs / readmes / README.save_restore

/*
 * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */
#pragma ident	"@(#)README.save_restore	1.2	06/11/15 SMI"


                  Legion Save/Restore Feature
                  ===========================


How to save a memory image from legion:
=======================================

1) bringover and build your legion gate.

2) setup your config file as follows :

// Add this optional directive to your legion config file.
// It should appear before the system directive.

debug {
        save_state {
		// The instruction count to initiate a save. If not specified,
		// user can initiate a save using ~% on the console or
		// using the dbx command 'simsave'.
                icount  2383700054;

		// legion is the default format. ie a list of mem.image.n
		// files will be produced along with a restore.conf file
		// that has the details of where in memory to load each
		// memory image. When using the axis format, a
		// single text file called mem_image.axis is produced
		// which can be loaded into Axis or can be converted back
		// into a series of mem.image.n files for use with legion
		// (using the mem_conv program in your legion build dir)
		format "axis";

                // When using the axis format, an optional filename can be
		// provided. If no filename is given, the default of
		// mem_image.axis is used.
		filename "mem_image.foo";

		// For N2, add the following. This will allow dumbreset to 
		// know to jump to the restore code on AXIS.
		patch 0xfff0000200 0x1;

		// For VF, add the following. This will allow standalone reset 
		// to know to jump to the restore code on AXIS/Palladium.
		patch 0xfff0002000 0x1;
        }
}


// Add this inside the addressmap directive in your config file
// savestate_<proc>.bin can be found in <legion-ws>/src/statesave/<proc>
// Note that for the bigger configs, the memory size needs to be
// increased. eg, for the largest VF config 2n8c8t, you need to have
// 			device "memory" 0x0 +320k {

                        // Save/Restore
                        device "memory" 0x0 +32k {
                                load +0x0 "savestate_<proc>.bin";
                        }

// XXX FIXME: There is a bug which means that you need to change
//		the size of the memory image that holds the disk
//		from 513M to 512M. So edit your config file to
//		change it so it looks like this:

 device "memory" 0x1f40000000 +512M  {


3) start your simulation

4) Initiate a save_state by one of the following:

   4a) typing ~% (tilde-percent) on the legion console window
       (where the OBP/Solaris boot messages appear). A save_state
	will be initiated immediately.

   4b) specifying an instruction count in the debug directive 
       in your config file. When this instruction count is reached
       the simulator will automatically initiate a save_state.
       You can still use the ~% even if you specify an icount
       in your config file if you want to save_state earlier.

   4c) Run legion using dbx, set a breakpoint in legion (break) or
       in Hypervisor/Guest code (simbreak) at the place where you
       want to initiate the save_state. Once dbx stops, you can
       initiate the save_state by typing 'simsave' at the dbx
       prompt. Use of this feature requires that you pick up the
       dbxrc file in the legion gate above and place this in your
       run directory as a file called .dbxrc. The dbxrc can be
       found at src/procs/sunsparc/debug/dbxrc in the legion gate.

   All of these will result in a file being created with the entire
   simulation memory image. This file will be created in the run
   directory using the filename that you provided in your config
   file(if you picked the AXIS format).
 
   This is a text file that can be processed back into multiple
   binary images that legion can digest. This file can also be
   loaded directly into Axis as a memory image. 

   NOTE NOTE NOTE:
   ===============
   For N2/VF, due to an AXIS bug, the SSI region needs to be 
   located at the top of this text file. The following extra steps
   are needed.
	grep -n 'Memory from fff0000000 to fff0800000' mem_image.txt
	using the line number obtained, do the following.
	tail +<line_num> mem_image.txt > mem_image_axis.txt
	head -<line_num -1> mem_image.txt >> mem_image_axis.txt

   mem_image_axis.txt is the file you hand over for AXIS testing.

5)  Loading a memory image back into legion

    5a) Run the conversion program to convert the text memory image
	back into multiple binaries so that legion can load them:
	NOTE: the mem_conv tool gets built as part of legion and
	      can be found in your build directory

	./mem_conv -i mem_image.axis 

        Running this command takes a few minutes depending on 
	the size of the memory image.

    5b) Once this command completes, you will now have a bunch of
        new files in your current directory:

	// Binary files for each memory segment
	mem.image.n files (usually 0-8)

	// Legion config file for loading in these binary memory images
        restore.conf

    5c)	You will now need to create a new config file for reloading
	the the memory images. This file should look the same as a
	regular 1up.conf file, except strip out all the device memory
	directives from the addressmap. NOTE: leave in the dumbserial, 
	dumbtod  and piu devices, just make sure you remove all the
	memory devices.

	Then, inside the addressmap directive, add the following:

	#include "restore.conf"

	So your addressmap directive should look like this(for Rock). 
	For N2/VF, leave the piu section in as well.
               addressmap {
                        // console
                        device "dumbserial" PUART0 +0x50 {
                                xterm "/pkg/X11/bin/xterm -l -lf guest1.log -geometry 80x35+200+30 -T 'Guest Partition #1 - 1 X Rock strand' -e /net/cpubringup.sfbay/export/bringup/niagara/tools/bin/netcons %s %d &";
                        }
                        device "dumbtod" HVTOD +0x8;
                        device "dumbserial" HVUART +0x50;

                        #include "restore.conf"
                }

    5d) You need to change the reset vector of your 1up.reload config
	file to start the processor executing from the restore code
	which is at offset 0x20 in the save_restore code. To do this
	edit your config file and change the rstv to 0x0; The processor
	always adds 0x20 to the reset_vector so this will cause the
	restore code at address 0x20 to start the restore process.
	NOTE: This step should not be done for VF/N2. The reset vector
	will remain at the original value as reset.bin needs to be run
	before the restore code.

    5e)	Then start your simulation using this new config file and voila,
	you should start executing from the exact point you iniated the
	save_state.