* 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.
// 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'.
// 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)
// 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.
// For VF, add the following. This will allow standalone reset
// to know to jump to the restore code on AXIS/Palladium.
// 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 {
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 {
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.
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
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
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
Then, inside the addressmap directive, add the following:
So your addressmap directive should look like this(for Rock).
For N2/VF, leave the piu section in as well.
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;
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
5e) Then start your simulation using this new config file and voila,
you should start executing from the exact point you iniated the
projects / OpenSPARC-T2-SAM / blob