.TH IDE 1
.SH NAME
u64ide \-
Ultra64 Integrated Diagnostic Environment
.SH SYNOPSIS
/usr/diags/bin/u64ide
.SH DESCRIPTION
The Integrated Diagnostic Environment provides a programmable front-end
for unix-based diagnostics.  The command line oriented user interface is
intended to resemble the shell (/bin/sh) and 'C' in its syntax.  Simple
commands may be combined with variables, expressions and looping constructs
in order to create more complex commands.
.SS
.SS Commands and Statements
IDE commands have the same form as shell commands.  Multiple commands may
be specified on a single line if the commands are separated by semi-colons.
Arguments to commands may be integers, strings, IDE variables, or IDE
expressions.  Integers may be specified as decimal, octal, hex, or 
binary constants using `C' conventions.
Integer arguments are converted to a decimal string 
representation as the standard format when passed to a command.
A statement consists of either a simple statement or a compound statement.
Statements may be separated by either a newline or a semi-colon.  A 
compound statement is a semi-colon separated list of simple statements
surrounded by curly brackets.  The following are examples of statements:
.nf
	ide>> echo "Hello, world"

	ide>> { echo "Hello"; echo "world"; }

	ide>> {
	more>> echo "Hello"
	more>> echo "world"
	more>> }
.fi
.SS
.SS Variables
Two types of variables may be defined and used in u64ide: integer and string.
Variable names begin with a `$' and consist of at least one alphabetic
character followed by up to 31 alphanumerics.
A variable is defined
by its first appearance and its type is inferred by the context in which
it is used.  IDE variables are distinct from shell environment variables,
which are inherited by the IDE command line interpreter.  You may also use
setenv to add more environment variables, and use these variables wherever
you would use a symbol when giving the interpreter IDE commands.
.SS
.SS Expressions
Expression syntax is a subset of that provided by
.B C.
The following operators are supported:
.nf

     =,   ==,   !=,   <,   >,   >=,   <=,   !,   ~,   ^,   +,   -,   *,   /,

     %,   <<,   >>,   +=,   -=,   *=,   %=,   /=,   <<=,   >>=,   ^=

.fi
All commands are considered integer functions which may return a value
and be used within an expression.  To use an expression as an argument
to a command, surround the expression in single back-quotes (`).  For
example:
.nf

	ide>> repeat 10 rdram `$i++ * 100`

.fi
Operations on strings are limited
to the comparison operators and concatenation with the `+' operator.
Variables will be converted from one type to another as the context
requires.
.SS Control Flow
An if-then-else statement with
.B C
syntax is provided.  An optional "fi" should follow an if-then statement to
avoid ambiguity.  For example, if the following input is given to IDE,
.nf

 :
ide>> if ($printmask == 0x4) echo "Warning: only severe errors reported."

.fi
IDE will prompt for more input because it is not clear whether or not there
is going to be an "else" statement.  If the above statement were entered as
shown below, then there is no ambiguity and the statement would be evaluated
immediately.
.nf

 :
ide>> if ($printmask == 0x4) echo "Warning: only severe errors reported."; fi

.fi
.SS
.SS Looping
Three different types of looping constructs are supported: for, while, and do.
All have syntax compatible with the equivalent
.B C
statements.  For example:
.nf

	ide>> for ($i=0; $i < 10; $i++) {
	more>> $sum = $j = 0
	more>> do {
	more>> echo "hello"
	more>> $sum = $sum + $j
	more>> printf "0x%x\n" $sum
	more>> $j++
	more>> } while ($sum < 40)
	more>> }

.fi
.P
In addition, a "repeat" statement is available for looping on simple commands.
The repeat statement takes a single argument which is an integer repeat count.
For example:
.nf

	ide>> repeat 5 echo "hi."

	or

	ide>> repeat 5 {
	more>> echo "Hello"
	more>> echo "world"
	more>> }

.fi
Note, the opening bracket of a compound statement appears on the same line
as the repeat keyword.  This style is required by repeat, for, and while
loops as well.
.SS
.SS Logic Control Legal Specifiers
.nf
Positive logic is specified by any one of the following:    TRUE,  true,  ON,  on,  or  1.
Negative logic is specified by any one of the following:    FALSE,  false,  OFF,  off,  or  0.
.fi
.SS
.SS
.SS
.SS "IDE Reserved Variables"
.IP "initflg" 1i
Initialization Flag.  Select positive or negative logic specifier from above.
Positive logic (default) calls diagnostic module's initialization functions
required to run tests.  Negative logic selects execution of diagnostic module
without initialization.
.nf
Example:  ide>> $initflg = false
.fi
.IP "scopeflg" 1i
Scope Loop Flag.  Select positive or negative logic specifier from above.
The default is negative logic.  When set to positive logic within a diagnostic
module, the entry test number enters a scope loop.  The requested test will
send a target system peek/poke request which will loop infinitely, while 
reading or writing the hardware under test.
.nf
Example:  ide>> $scopeflg = TRUE
.fi
.IP "traceflg" 1i
Peek/Poke Trace Flag.  Select positive or negative logic specifier from above.
The default is negative logic.  When set to positive logic, the target
system peek/poke functions will print the address and data that they are 
writing to or reading from.  This variable allows tracking of all I/O 
activities if the system hangs while running a diagnostic module.
.nf
Example: ide>> $traceflg = 1
.fi
.IP "entrytst" 1i
Entry Test Number.  An integer value that allows the IDE diagnostic server to
request that a diagnostic module begin testing at a specific entry test number
within the sequence.
.nf


0(zero)         Sequence through all of the diagnostic module's tests beginning
                     with the first entry test number.
n(positive)     Sequence through all the diagnostic module's tests beginning
                      with entry test number n.  Skips all lower entry test numbers.
-n(negative)    Execute only the requested test number n.
Example: ide>> $entrytst = -4
.fi
.IP "printmask" 1i
Error Reporting Verbosity Level.  Error reporting levels are defined as follows:
.nf

0x1  INFO		Informative messages that are printed out as each test executes.
0x2  ERR_SIMPLE	Used to print individual error messages
0x4  ERR_SEVERE	Used to print messages indicating a functional block has failed.
0x8  DEBUG		Used to print messages for SW debug.
0x7  DEFAULT_MSGS	Prints all of the INFO and ERROR messages by default.

Any combination of levels may run simultaneously with mixed numeric and sym-
formats.
Example:  ide>> $printmask = 0x4 | INFO
.fi
.IP "exitmask" 1i
Error Trap Level.  Any time an error is reported with the errlog reporting 
function, the error reporting level (one of INFO, ERR_SIMPLE, ERR_SEVERE, or
DEBUG) is checked against the builtin ide variable "exitmask" to decide whether
or not to abort the test.  The default value is "6", exit on real errors.
.nf

Example:	ide>> $exitmask = 0x0		/* never exits */
		ide>> $exitmask = 0x6		/* only exits on real errors */

.fi
.IP "skiptst" 1i
Skip Test Numbers.  A null terminated array of positive test numbers which are
to be skipped by the diagnostic module.  The default condition is a null array.
.nf
Example:  ide>>  $skiptst = "2 5 9 11"
.fi
.SS
.IP "commtype" 1i
The library upon which the Ultra64 diags are based (libdg.a) uses this builtin
variable to decide how to initialization the communication with the debugging
agent on the target system.  7 different types of host to host communication
protocols are possible, depending on the value of the "commtype" builtin 
variable:
.nf
	value		communication protocol

	1		Verilog: we use dbgif to talk to an rmon agent
			"vermon", which talks to a verilog simulation.

	2		Tinymon running out of the PIF (Peripheral I/F)

	3		Tinymon running out of IMEM (rsp instruction memory)

	4		Tinymon running out of DMEM (rsp data memory)

	5		Tinymon running out of RDRAM (Rambus dram)

	6		The diags talk to the hw with dbgif, which talks to
			an rmon thread running on the development system.

	7		The diags talk to the hw with dbgif, which talks to
			an rmon thread running on the development system; a
			program capable of firing off a suitable rmon thread is
			explicitly downloaded.  This option is currently
			unavailable, and may be removed.

.fi
.SS
.SS "IDE Built-in Functions"
.IP "echo [-l]" 1i
Similar to the shell's echo command, except that no shell flags or special
escapes are supported.
.IP
The \fI-l\fP option is an optional flag to echo to the u64ide log file in 
addition to the screen.  For example:
.nf
	ide>>  echo -l "Hello world"
.fi
.IP
In the above example, the string "Hello world" will be printed to the 
screen, and the string "INFO:   Hello world" will be printed to
the u64ide log file.
.IP "exit" 1i
Quit IDE and return to the monitor.  An argument may be given which becomes
IDE's return value.
.IP "help" 1i
Displays summary help on all commands and statements.
.IP "?" 1i
Like "help", except that only information about commands is printed.
.IP "printenv" 1i
Print the environment variables (including those inherited from your parent shell).
.IP "setenv" 1i
Set an environment variable.
.IP "printf" 1i
Print arguments with a format, similar to printf(3C).
.IP "status" 1i
Print the IDE reserved variables
.IP "reset" 1i
Reset the IDE reserved variables to their default values.
.SS
.SS "IDE User Defined Functions"
The list of diagnostic functions to be called is located in awk configuration
files (e.g. "prcmd.awk").  This list may be modified by editing the function
descriptors.  New diagnostic functions may be appended by providing 1) the IDE
user defined function name, 2) the specifier "DCMD", 3) the name of the 
diagnostic function to be called with a communication structure pointer, 
and 4) the diagnostic description (to be used when printing formatted help 
information).  These four descriptors must be in fields separated by a 
single tab.
.P

For example, the following table outlines some of the diagnostic commands 
available for use by the Ultra64 diagnostic executable "u64ide":
.nf

ai	DCMD	aiEntry		Audio subsystem test.
e	DCMD	dgExamineMemEntry	Examine memory command (peek/poke mem).
io	DCMD	io	       	IO test
ndev_memtest DCMD	ndev_memtestEntry	GIO memory test (16MB of ramrom)
pi	DCMD	piTestEntry	DMA controller for Peripheral Interface tests
reg	DCMD	dgReg		Register read/write command
rdram	DCMD	rdram	       	RDRAM test
rsp	DCMD	rsp		All RSP Bring-up Tests
si	CMD	siTestEntry	Serial Interface subsystem test.
vi	DCMD	vi	       	vi test

.fi
.SS
.SS "IDE standard command line flags"
Most of the Project Reality tests listed above support the following two 
standard command line flags, intended to help you determine the number of 
subtests available from each top-level u64ide entry point, and to provide a 
way to run these subtests singularly, to help isolate faults.
.P
.IP "-h" 1i
prints out a summary of the subtests available for the given u64ide top level 
command.
.IP "-t < test number >" 1i
Causes IDE to only invoke the specified subtest, ignoring all others within 
that top level command.
.SS
.SS "IDE Input"
IDE supports three different types of input.  Commands may be entered from the
keyboard (or redirected from stdin), from a startup script linked in at compile
time, or from a script file via the "source" command.
.SS
.SS "FILES"
By default IDE writes its diagnostic output to the file /usr/tmp/ide.log; this
name can be overridden by setting the environment variable IDE_LOG to the
desired file name.