.TH IDE 8
.SH NAME
ide \-
Integrated Diagnostic Environment
.SH SYNOPSIS
/usr/diags/bin/ide
.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 seperated by either a newline or a semi-colon.  A 
compound statement is a semi-colon seperated 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 ide: 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 checkmem `$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 ($verbose == 0x4) echo "Warning: realtime clock not reset."

.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 ($verbose == 0x4) echo "Warning: realtime clock not reset."; fi

.fi
.SS
.SS Looping
Three different types of looping constructs are supported: for, while, and do.
All have syntax compatibile 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 diagdr peek/poke request which will loop infinitely, while reading or
writing the hardware under test.
.nf
Example:  ide>> $scopflg = 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 diagdr 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 "verbose" 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>> $verbose = 0x4 | INFO
.fi
.IP "traplvl" 1i
Error Trap Level.  This can be set to one of the following integer values:
.nf
1     Continue on all errors (default).
2     Return on severe errors.
3     Return on all errors.
Example:  ide>> $traplvl = 3
.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
.SS "IDE Built-in Functions"
.IP "echo [-l]" 1i
Similiar 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 ide 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 ide 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, similiar 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 the configuration
file labeled "diagcmds".  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 to be called with a communication structure pointer, and 4) the 
diagnostic description for help information.  These four descriptors must be
in fields separated by a single tab.
.nf

For example, edit the file: $ROOT/usr/src/periph/BOSTON/diags/ide/diagcmds by
appending an entry similar to the one below.

#
#  diagcmds - ide diagnostic functions
#
.
.
.
proto	DCMD	diagProto	Diagnostic prototype

.fi
.SS
.SS "IDE Input"
IDE supports three different types of input.  Commands may be entered from the
keyboard, or from a startup script linked in at compile time, or from a script
file located on the local disk drive via the "source" command.
.SH
FILES
By defaul IDE writes its diagnostic output to the file /usr/tmp/ide.log, this
name can be overidden by setting the environment variable IDE_LOG to the
desired file name.