Initial commit of OpenSPARC T2 architecture model.

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

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


                  Error Trap Generation Framework
                  ===============================

                           User Guide


What the Error Trap Generation framework supports:
--------------------------------------------------

The user will be able to specify a list of errors and/or arbitrary
traps to inject into the system along with specific conditions under
which the errors/traps are to be injected.

Optionally, the user may also specify a list of ASI override values
which Legion will use to serve up load requests (or noop store
requests).

Legion provides simulation of all the Error Status Registers and
Error Enabling Registers (error reporting and error recording)
associated with supported errors. Legion will also generate the
correct trap type depending on the error.

This framework does not, however, provide a simulation for actually
injecting real errors into TLBs, caches, etc. So you will have to
supply ASI override values for any diagnostic ASIs such as reading
raw cache line contents or TLB entries which may be needed by the
hypervisor error handling code being simulated.

Also, by using the arbitrary trap generation functionality combined
with ASI overrides, you can pretty much inject and simulate any
error -- even ones that have not been supported yet using the named
error method. This allows the Hypervisor developers to make forward
progress and not have to wait for various ASI registers to be fully
supported in Legion.


Enabling the Error Trap Generation framework:
---------------------------------------------

Modify the GNUMakefile by setting ERROR_TRAP_GEN to 1 or 2 (a value
of 2 generates more output and is mainly intended for use in Legion
development) and recompile Legion.

Then modify your Legion .conf file by adding error_asi {} and 
error_event {} definitions (described in detail later) to the
"processor" definition like this:

   ...
		processor "rock" {
			...
			error_asi { ... }
			error_asi { ... }
			...
			error_event { ... }
			error_event { ... }
			...
		}
   ...

Alternatively, you could just add all your error_asi and error_event
definitions to an error.conf file and #include that file from within
the "processor" definition like this:

   ...
		processor "rock" {
			...
			#include "error.conf"
			...
		}
   ...

User input/options:
-------------------

In order to inject error traps under this framework, the user
provides error_event {} definitions and error_asi {} definitions
in the Legion .conf file.

1) error_asi {}

These are used to specify ASI overrides. You can specify ASI 
overrides for ASI/VA pairs which are already supported in Legion 
or you can specify ASI overrides for accesses that would otherwise 
result in a DAX because they are not yet supported by Legion.

In the case of ASIs which Legion already supports, the masks
specified here are applied on top of the value that Legion would
normally return. In the case of ASIs which Legion does not yet
support, we record the value on a store, or retrieve the value
then apply the masks specified here on a load.

NOTE: In the case of an ASI which Legion does not yet support, if
you intend to write to multiple VAs and would like the values to
be retained, then each ASI/VA pair must have it's own error_asi
entry.

The format for an ASI override is as follows:

error_asi {

	// ASI number (required field)
	ASI 0x32;

	// VA for this override. If no VA is specified, this ASI
	// override will match on any VA for the given ASI.
	VA 0xec000018;

	// NAND mask value. This value is negated and then logically
	// "and"ed with the value being returned in the ldxa
	// operation. Defaults to 0 if not specified.
	NAND_MASK 0xff00;

	// OR mask value. This value is logically "or"ed with the
	// value being returned in the ldxa operation after we have
	// already applied the NAND_MASK. Defaults to 0 if not
	// specified.
	OR_MASK 0x4000000000;

	// Access count. This value defines the number of accesses
	// that an ASI overrides will be valid. Defaults to permanent 
	// override (for the duration of current Legion run) if not 
	// specified.
	ACCESS_CNT 0x5;

	// CPU mask. This value defines the 64bit mask of the cpus
	// for which this asi override is valid. If not specified
	// the ASI override will be valid for all cpus.
	CPU_MASK 0xf;
}


2) error_event {}

These are used to specify the type of error trap you want Legion
to generate and under what circumstance it will be injected. The
format is:

error_event {

	// ASCII name from PRM. e.g. DCDP or UE
	error "DCDP";

	// Arbitrary TT to inject (in lieu of a specific error).
	trap 0x63;

	// Arbitrary service processor (SP) interrupt level 
	// to inject (in lieu of a specific error).
	// 
	// NOTE: SP interrupts are currently only supported in
	// Rock (using the SCX library). SCX must be initialized
	// for both arbitrary SP interrupts and any built-in 
	// errors which generate SP interrupts. See README.scx 
	// for information on how to setup the SCX library.
	sp_intr 0x1;

	//
	// NOTE: Each error_event definition should include one of
	// ('error' or 'trap' or 'sp_intr')
	//

	// Instruction cycle count to wait for before injecting
	// the error trap. Defaults to 0x1 if unspecified.
	instn_cnt 0x10000;

	// %pc value to trigger the error trap. If the user also
	// specifies an instn_cnt, the %pc trigger will not get
	// loaded until the instn_cnt has first been reached.
	pc 0xf023972;

	// Strand ID of the CPU this error/trap is targetted at.
	// Defaults to 0x0 if unspecified.
	target_cpuid 0x4;

	// Address to which an access will trigger the error.
	// Address value of 0x0 means "any address". User can
	// optionally specify that the error will be tiggered by
	// either a "load" or a "store" -- default to both if
	// unspecified.
	address { 0x1f12080000; "store"; }

	//
	// NOTE: Each error_event definition should include at least
	// one of 'instn_cnt' or 'pc' value or address. A combination
	// off instn_cnt with pc or instn_cnt with address is also
	// possible.
	//

	// Privilege level the CPU should be in before the error
	// is injected. Defaults to "any priv level" if unspecified.
	priv "PRIV";

	// Trap level the CPU should be in before the error is
	// injected. Defaults to "any trap level" is unspecified.
	tl 0x1;

	// Error persistence can be set with a trigger_cnt
	// directive. 1 means single trigger (default, if not 
	// specified); > 1 means trigger N times.
	trigger_cnt 0x2; 

	// ASI overrides associated with this error event. The 
	// definition for these is the same as the error_asi {}'s 
	// defined outside the error_event except for the fact 
	// that they are enabled only after the error is triggered 
	// AND the default access count is one (if access_cnt is 
	// not specified, the override is valid for only one 
	// matching access).
	error_asi { }
}


Example error.conf file:
------------------------

error_asi { ASI 0x58; VA 0xa0000150; }
error_asi { ASI 0x37; VA 0x80000250; }
error_asi { ASI 0x37; VA 0x800002D0; }
error_asi { ASI 0x37; VA 0x80000350; }
error_asi { ASI 0x37; VA 0x800003d0; }
error_asi { ASI 0x4c; }
error_asi { ASI 0x32; VA 0xec000050; }

error_event {
	error "DCTM";
	instn_cnt 0x1;
	address { 0x0; "load"; }
	priv "PRIV";
}

error_event {
	error "WRFC";
	address { 0x1f12080000; "store"; }
	priv "USER";
}

error_event {
	trap 0x63;
	instn_cnt 0x2c38e3b;
	pc 0xf0239720;
	address { 0x0; "load"; }
	priv "PRIV";
	error_asi { ASI 0x32; VA 0xec000018; OR_MASK 0x4000000000; }
}

"Dynamic" error.conf file load:
---------------------------------

The user has the option of dynamically loading error_asi {} and 
error_event {} definitions while the simulation is executing.

1) Setting up dynamic error_event {} and error_asi {} definitions

Dynamic error_asi and error_event definitions must be included in a
separate error.conf file.  In addition, the error.conf filename must 
be specified, using an error_reload_file_name definition, within the 
"processor definition" section of the standard conf file.  If no
error_reload_file_name is provided when you start legion, the default
file called "reload.error.conf" will be opended and parsed.

example:

   ...
		processor "rock" {
			...
			error_reload_file_name "error.conf";
			...
		}
   ...

2) Loading dynamic error_event {} and error_asi {} definitions

To dynamically load the defined error file, type '~er' in the 
simulated console window.  

Note: "Dynamic" error_event {} definitions will be appended to the
existing list. Any error_asi {} definitions will be used to update
any existing error_asi defintions that match on ASI/VA. This can
be used to reset the access_cnt of an error_asi who's access_cnt
is now 0.

Other options available during the Legion run:
----------------------------------------------

1) The user can dump the error_event {} and error_asi {} lists by 
typing '~ed' in the simulated console window.

2) The user can dump the list of all supported (built-in) error names 
by typing '~es' in the simulated console window.

Notes, Limitations, and Known Bugs:
-----------------------------------

- Legion processes the error events in the order in which they are
listed in the .conf file and each CPU only monitors the trigger
conditions for one error event at a time. This means you must list
the error events in the order you wish to have them injected.