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

##
## Getting Started with Legion
##
## Legion is a fast instruction accurate simulator which provides a rapid
## means of developing and testing software functionality in the absence
## of actual hardware. Legion provides the fastest simulation environment
## for developing and testing SPARC Software and is the primary simulation
## environment for the Niagara firmware and software teams.
## 

[0] System Requirements:

    - Sparc system running Solaris 8 or higher
    - 700MB of disk space.
    - Root access to the system if you want to modify the contents of the
      disk image.

[1] Installation:

    This compressed tar file will install all the necessary binaries and
    config files needed to run the Legion simulation tool. The compressed
    tar file is approx 161MB and when installed requires approx 514MB of
    disk space.

    [1.1] Installing the Legion tar file

	# /usr/bin/zcat legion.tar.Z | /usr/bin/tar -xvf -
    
        This will create a directory called legion in the current directory.

[2] What is included:

	sim 		- Legion binary
	plugins		- Legion simulation plugins
	reset.bin	- Reset binary for basic processor configuration
	q.bin		- Hypervisor binary
	openboot.bin	- Openboot binary
	nvram1		- Non-Volatile Ram used by openboot
	disk1 		- Solaris 10 disk image (512MB, approx 250MB of
			  free space)
	netcons		- tool used to connect to legion console socket

	1up-hv.bin	--\
	1up-md.bin	---> Machine Description and Legion config files
	1up.conf	--/  for 1 processor configuration

	1g2p-hv.bin	--\
	1g2p-md.bin	---> Machine Description and Legion config files
	1g2p.conf	--/  for 2 processor configuration

	1g32p-hv.bin	--\
	1g32p-md.bin	---> Machine Description and Legion config files
	1g32p.conf	--/  for 32 processor configuration


[3] Environment requirements:

    - Make sure your DISPLAY variable is set so that you can run an xterm
      and have it display on your desktop.
    - Your path should include the following :
	/usr/openwin/bin/xterm	# or the path to the xterm of your choice
	/usr/lib/cpp		# or the path where cpp lives on your machine
	.			# Current directory

[4] Running Legion:

    [4.1] Starting Legion:

	Legion need to be run with the -a option and needs to have a config
	file specified. The config file can be one of 1up.conf, 1g2p.conf
	or 1g32p.conf.
	While the 2 and 32 processor configs will boot just fine on a single
	processor machine, the boot times will be much longer than the 
	single processor config. Legion is fully multi-threaded so it
	runs larger configs faster on host machines with more cpus.

	./sim -a 1up.conf

    [4.2] Log file of Console output:

	Legion maintains a log file of the Guest Console. This output
	is written to a file called guest1.log. The name of this file
	can be changed by modifying the filename in the legion config
	files (1up.conf, 1g2p.conf or 1g32p.conf). All output is
	appended to this file.

    [4.3] Booting Solaris from the ok prompt:

	Once you get the ok prompt, you can :

	[-] View the number of processors in your config:
	ok .cpu-state

	[-] Boot from the disk by typing 'boot disk' or
	    'boot disk -vV' for a verbose boot or boot
	    without any services for a quicker boot time
	    by 'boot disk -m milestone = none'.

	ok boot disk
	-or-
	ok boot disk -vV
	-or-
	ok boot disk -m milestone=none

	[-] There is no root password on this disk so just login as
	    root and hit return.

	[-] You can set the system to automatically boot by
	    setting auto-boot? to true at the ok prompt
	ok setenv auto-boot? true

	[-] To undo this you can set auto-boot? to false at the ok
	    prompt
		ok setenv auto-boot? false

	[-] If you corrupt your nvram file and want to start with
	    a new one, just remove the nvram1 file and re-create
	    it as a blank file and re-start the simulation. auto-boot?
	    will be set to true by default when you create a new nvram
	    file.
		# rm nvram1
		# mkfile 8k nvram1
		# ./sim -a 1up.conf

    [4.3] Killing the simulation

	When you are done with the simulation, you can terminate it by:
	- Ctrl-C in the window where you ran legion
	- ~z in the Guest console window	

[5] Debug Tools

    [5.1] Verbose mode:

	Legion can be started in verbose mode using the -v or --verbose flag
	# ./sim -v -a 1up.conf	

    [5.2] Debug mode:

	Legion can be started in debug mode which will dump out debug state
	while the simulation is running. An example is if you want to see
	the %pc and all sparc instruction that the simulator is executing
	along with the register and relevant processor state at each instn
	you would use -debug 0x2

	# ./sim -debug 0x2 -a 1up.conf

	The list of debug flags that you can pass is:

	0000.0000.0000.0001 Parsing messages, initialization,
	0000.0000.0000.0002 PC & Instruction
	0000.0000.0000.8000 Hypervisor Calls
	0000.0000.0001.0000 Performance Counters
	0000.0000.0002.0000 Exceptions, XIR
	0000.0000.0004.0000 hpstate changes
	0000.0000.0008.0000 MMU 
	0000.0000.0010.0000 MMU miss
	0000.0000.0020.0000 Memory controllers
	0000.0000.0040.0000 TSTATE, etc.
	0000.0000.0080.0000 Error injection
	0000.0000.0100.0000 SSI interrupts
	0000.0000.0200.0000 Little Endian
	0000.0000.0400.0000 Alignment errors
	0000.0000.0800.0000 Mondo
	0000.0000.1000.0000 SOFTINT 
	0000.0000.2000.0000 TICK 
	0000.0000.4000.0000 Instruction decode
	0000.0000.8000.0000 Device
	0000.0001.0000.0000 Execution Loop
	0000.0002.0000.0000 Error Traps

	You can combine multiple debug flags by OR'ing them together.
	So if you want to see all the hypervisor calls (0x8000) along
	with the parsing information (0x1), you can run it as follows:
	
	# ./sim -debug 0x8001 -a 1up.conf

    [5.3] Dynamic tilde escape sequences:

	Once you have started the simulation you can use the ~ (tilde)
	escape sequence in your Legion Guest Console window to dump out
	some processor state. The list of tilde commands supported is
	as follows:

        #  BREAK
        ~  generate tilde
        z  exit simulator
        i  dump I-TLB contents for CPUs in same domain
        d  dump D-TLB contents for CPUs in same domain
        b  toggle the debug output enable bits
        n  dump the current and delta instruction count for each CPU
        ?  this message

	So if you want to turn on the %pc and instruction tracing after
	you have started the simulation, you can type ~b in the Legion
	Guest console window. Typing this gain will turn off the
	extra debug output.

	If you want to view the contents of the I-TLB (Instruction TLB)
	you can dump it out for all cpus by typing ~i in the Guest
	Console window.

	The output will appear in the window where you started legion.
  
[6] Modifying the Disk Image

    [6.1] Adding/Removing files to/from the disk

	If you want to add/remove/modify files on the disk image provided,
	you will need root access on a system. Here are the instructions
	for doing this on a Solaris system.

	# Use the loopback file driver to moun the disk image:

	/usr/sbin/lofiadm -a /export/legion/disk1

	# Mount this device onto a mount point:
	# where /dev/lofi/1 is the value returned from lofiadm

   	/usr/sbin/mount /dev/lofi/1 /mnt 
	cd /mnt

	You can now add/remove files to/from your disk image
	If you get permission problems when accessing the files:
	1) As root, chown/chmod the file/dir that you are modifying
	2) only modify files as the root-user on your host machine

	Once you are done, you can umount the disk image and boot
	the simulator. It's always advisable to unmount the disk image
	before booting it in the simulator.

	/usr/sbin/umount /mnt
	/usr/sbin/lofiadm -d /dev/lofi/1

    [6.2] Making your disk writable

	By default, legion mounts it's disk image as read-only. That means
	that any changes to the disk while running legion will not be
	written back to the disk image file on the host machine. If you
	want to preserve the changes to the disk, you will have to mount
	the disk under legion in write mode (or shared).
	To do this:
	- edit your legion config file and locate the block where the disk
	  is mounted (search for virtual_disk).
	- change the rom keyword to shared
	- now when you boot legion, any changes to the file system within
	  the simulation will be reflected on the disk image file. You
  	  can get log files off the disk image my lofi mounting it as
	  described above.

	WARNING!!!: When mounting a disk as shared, you must gracefully exit
	the simulation to avoid file system corruption on the disk image.
	To do this, sync;halt Solaris within the simulation and wait until
	you return to the ok prompt before terminating the simulation by
	typing ~z in the Guest Console window.
	WARNING!!!


[7] Limitations of this Environment:
    - Legion only implements enough of the processor state to boot the
      firmware and software needed to boot Solaris. There are many areas
      of the processor that are not needed in this boot flow and are most
      likely not implemented. Areas like caches, RAS, are not implemented
      in legion.
    - This simulation environment does not simulate any IO devices
      therefore you cannot telnet into or out of the simulation
    - The configs are currently 1 proc, 2 proc and 32 proc. Binary
      users do not have the ability at this time to create new configs.