grtest — Apollo

GRTEST (GRAPHICS_TEST) Revision 6.1, 08/11/88.

GRTEST -- Perform Graphics Subsystem Test on a Node.

1. Introduction
----------------

GRTEST is an on-line graphics exerciser which runs under
system level software (YOU MUST HAVE AEGIS SR9.5 OR LATER IN
ORDER TO RUN GRTEST). GRTEST relies upon several system services
such as the stream manager and program manager, as well as disk
storage for its complete operation. All communications to the
graphics device will be performed through the exclusive use of
the Graphics Primitives and Graphics Metafiles packages. This
test is intended to provide the highest level of hardware
exercise and fault detection permitted by the graphics
packages.

2. Modes of Operation
----------------------

There are two basic operating modes to GRTEST; INTERACTIVE
mode and REMOTE mode. Interactive mode assumes that an operator
is present and allows full control over all program parameters
and test selections by issuing a prompt and acting upon operator
input. Remote mode refrains from any operator intervention. The
mode of operation is selected via command line arguments as
listed below.

3. Command line keywords
-------------------------

The following keywords and their respective options may be
included on the command line which invokes GRTEST. Keywords on
the command line must be preceded by a hyphen. All options for a
specific keyword must immediately follow the keyword. Keyword
options are not preceded by a hyphen and are separated from one
another by at least one space. Keywords may be specified more
than once on the command line. If this is the case, operational
parameters will be assigned the last value specified on the
command line.

ex. 1 $ GRTEST -ERRLOG INIT MY_ERROR_FILE -PASS 10 -ERROR NOHALT TRACE

This command line loads GRTEST, initializes an error log file
in the current directory named "MY_ERROR_FILE" and assigns a
maximum pass limit of 10. It then tells GRTEST to continue on
error and report the level of program nesting on the occurrence of
an error. All other operational parameters will assume their default values.
GRTEST will now enter interactive mode, with these parameters set.

ex. 2 GRTEST -ALLTESTS NOVISUAL -BRIEF -ERROR DETAILED HALT TRACE -PASS 1 -STOP_ON_QUIT

This command line loads GRTEST, instructs it to run all valid tests, instructs
it not to run visual tests, instructs grtest to limit non error output, sets the mode of error
reporting to detailed, instructs it to halt on error and output program nesting at the time
of error, sets the maximum pass count to 1, and instructs it to pass a stop fault to the shell
if a quit fault is received.
GRTEST will now start testing in remote mode.

ex. 3 GRTEST -TEST 3 4 -DIRECT -BRIEF -ERROR DETAILED HALT TRACE -PASS 1 -STOP_ON_QUIT

This command line loads GRTEST, instructs it to run only test 3 and 4, instructs
it to run these tests in direct mode, instructs grtest to limit non error output, sets the mode
of error reporting to detailed, instructs it to halt on error and output program nesting at
the time of error, sets the maximum pass count to 1, and instructs it to pass a stop fault to the shell
if a quit fault is received. GRTEST will now start testing in remote mode.

ex. 4 GRTEST -ALLTESTS DIRECT NOVISUAL -BRIEF -ERROR DETAILED HALT TRACE -PASS 1 -STOP_ON_QUIT

This command line loads GRTEST, instructs it to run all valid tests for direct mode,
instructs it not to run visual tests, instructs grtest to limit non error output, sets the
mode of error reporting to detailed, instructs it to halt on error and output program nesting
at the time of error, sets the maximum pass count to 1, and instructs it to pass a stop fault to
the shell if a quit fault is received. GRTEST will now start testing in remote mode.

NOTE : keyword abbreviations are shown in capital letters.

-Alltests select automatic (remote) mode of program operation.
Select and execute all valid subtests. No operator interaction occurs.
(options) Novisuals do not execute visual tests
Visuals execute visual tests
The default is visual tests executed.

-Test select automatic (remote) mode of program operation.
Select and execute all following subtests. No operator interaction occurs.
(options) 'n n n ...' where 'n' = subtest number. The same subtest
number may be entered more than once; or 'n : m' where 'n'
is the starting subtest number of a range and 'm' is the
ending subtest number of the range. If no subtest number
is entered, default to all subtests. Up to 32 subtest IDs
may be entered when specifying individual test numbers.

-BRIEF Limit standard (non-error) output under automatic (remote) operation
(i.e., switch only valid with -Alltests, or -Test switches).
(options) none

-STOP_on_quit This switch will pass a stop fault back to the shell if a
"DQ" (control Q) is entered. This allows greater feedback to a
calling program about pre-mature termination. This will also
signal the shell to stop.
(options) none

-DIrect causes all test that can run in direct mode to do so
when selected.
(options) yes Run direct mode tests.
no Do not run direct mode tests.
Note - When running in direct mode GRTEST will not modify
the color values normally used by the display manager.
However, certain test may use the data values which
correspond to these colors (0-15). This may cause
the visual appearance of the test to differ from
borrow mode.

-BOrrow causes all test that can run with full display to do so
when selected.
(options) yes Run borrow mode tests.
no Do not run borrow mode tests.

-Log_file specify error log file parameters. The log
receives a copy of all error messages if enabled.
This error logging feature is in addition to that
afforded by the error out channel.
(options) Init initialize error file upon opening it. This
overwrites existing data if a file of the
specified name already exists.
None do not log errors to a disk file.
[text] any other text string up to 32 characters
specifies the new file name to log errors
to. If no name is specified, default to
`node_data/system_logs/grtest_error_log .

-SAVE_image specify image save file parameters. The image save file
is a bitmap file that receives a copy on the display
upon a diagnostic error. This will overwrite any bitmap
file of the same name. The switch will only store the
first failure and resets itself afterwards.
(options) None do not log errors to a disk file.
[text] any other text string up to 32 characters
specifies the file name to save the image in.
If no name is specified, default to
grtest.bitmap in the current working directory.

-ERRor specify error handling parameters.
(options) Short short error report (error nnnn... brief message)
Full full error report (error number, descr, good/bad)
Detailed troubleshooting error report (vector drawn from ... to etc.)
Halt halt on error
NOHalt continue after error
NExt goto next subtest after error
Trace include in the error printout the level of
program nesting by module and subroutine name.
(if GRTEST receives a fault, and this option is
selected, GRTEST will do a "trace back" of the
process nesting by procedure name and line number)
NOTrace do not report program nesting.
Base n sets the base numbering system for error reports.
currently only "Base 10" (decimal) and "Base 16"
(hexadecimal) are supported. If Base is entered
without "n" then base 16 will be set. The default
for error report is Base 16 (hexadecimal).
note - grtest error codes, pass counts, test numbers
etc. will be outputted in decimal.
note - If a number is in any other base then 10 it
will be preceeded by the base and the pound sign.
(ex. 16#12345678 )

-Pass set a maximum number of passes for test activity at
which time testing stops.
(options) n (16 bit signed number -32768..32767)
note: a negative value or a zero supplied with this argument
signifies an unlimited test loop. If a positive
number is supplied with this keyword, testing
continues until this pass limit reaches zero
or a halt on error occurs.

-Unit select a specific graphics unit to test.
(options) n a positive integer which defines the graphics
unit to be tested.
caution !! GPR and GMR3D currently support only one graphics
unit (unit 1).

note: -Alltest and -TEST determine default test selections. If
none of these options are chosen, GRTEST will enter interactive
mode, otherwise the order of priority of these options is as
listed above.

5. GRTEST keywords
-------------------

The above keywords ( with the exception of -brief ),
may be entered in response to the GRTEST prompt by excluding the
hyphen before the keyword. The following keywords may be entered
only in interactive mode (in response to GRTEST's prompt). Unlike
the command line where many keywords may be specified on a
single line, interactive mode will only process one keyword and its
options per input line.

ex. GRTEST> PASS 10
GRTEST> ERRLOG INIT MY_ERROR_FILE
GRTEST> TEST 1 3 4 8
GRTEST> HELP

NOTE : keyword abbreviations are shown in capital letters.

ADjust enter adjust mode. menu of visual tests will be displayed.
Allows selection of a particular visual test. The image
generated will remain on the screen until the 'SPACE' bar
is depressed.
(options) none.
note: the visual routines available are as follows :

display boundaries
horizontal/vertical grid
diagonal grid
circles
color map spectrum
colored bars
shaded surfaces
zoom factors
double buffered animation
fill screen with selected color
interlace monitor
grey scale pattern
imaging mode pattern
monitor focus pattern
3d gmr visual (teapot)
monitor rgb alignment pattern

Step through basic visuals

QUIT, return to GRTEST>

fill screen with selected color will bring up
another menu to select colors from.

NOTE : not all visuals are valid for every node type.
this menu shown will differ accordingly.

Help display GRTEST help file. (The file "grtest.hlp" must be in /sys/help directory.)
(options) none.

Mode display the current GRTEST operating mode
(options) none.
Example : (the actual text displayed will vary from system to system)

Graphics configuration........ (gpr_$ctl_color_2) 1280 x 1024 x 8
Unit # under test............. 1
True Color Capability ........ NO
GPU available................. YES
Total pass limit.............. 1
Display mode.................. BORROW
Halt on error................. ENABLED
Next on error................. DISABLED
Mode of error report.......... DETAILED
Report program nesting level.. ENABLED
Error log file................ ENABLED
Error log file name........... `node_data/system_logs/grtest_error_log
Image save file............... ENABLED
Image save filename........... grtest.bmf

Quit exit GRTEST.
(options) none.

Rops allows execution of a particular Raster Op test. menu
of raster ops will be displayed.
(options) none.
( see description under test 6 )

STatus display a menu of available tests including current
pass counts and error counts.
(options) none.
Example : (the actual text displayed will vary from system to system)

Test # Description # Passes # Errors
----------------------------------------------------------------------
1 Memory Access Test 0 0
2 Memory Verification Test 0 0
3 BLTs within Display Memory Test 0 0
4 BLTs from/to Main Memory Test 0 0
5 Raster Ops ALU Test 0 0
6 Draw Test 0 0
8 Fill Test 0 0
9 Clip/Divide Test 0 0
10 Three Dimensional Transform Test 0 0
12 Visual Tests 0 0
----------------------------------------------------------------------
System call errors = 0
----------------------------------------------------------------------
Total pass count = 0 Total error count = 0
----------------------------------------------------------------------

Test cause the execution of subtests.
(options) 'n n n ...' where 'n' = subtest number. The same subtest
number may be entered more than once; or 'n:m' where 'n'
is the starting subtest number of a range and 'm' is the
ending subtest number of the range. If no subtest number
is entered, default to all subtests. Up to 32 subtest IDs
may be entered when specifying individual test numbers.

? displays a list of available commands and options, with
a brief description of each.

6. Descriptions of Tests
-------------------------

The following describes for each test what should be seen on the screen for each
test. Note that all tests except 11 check data and report an error if the
test fails. Tests 11 is a visual tests and its correctness must be visually
verified by the user.
Note : not all tests are valid for all node types. (invalid tests will not
be displayed in the STatus menu)
Also, some test may be valid in borrow mode and not valid in
direct mode, "alltests" will run only valid tests.
Note : test may appear different in direct mode than they do in borrow,
however all test (except the visual test) do data verification.

TEST 1 - MEMORY ACCESS TEST.
The test will display flashing short horizontal lines in the upper
left corner of the screen.

TEST 2 - MEMORY VERIFICATION TEST.
On color nodes with true color capability this will fill the screen
with blue and green "shaded" boxes, each box having a slightly
different red shaded. Then the screen will fill with inversely
shaded blue and green boxes. This will continue until all red
values have been used.
On color nodes without true color capability the screen will be
filled with a rainbow pattern, and then it will be filled with an
inverted rainbow pattern.
On monochrome nodes the screen will fill with every other pixel
white (or green). Then the screen will then fill with an inverted
pattern.
If the node has zoom capability the first patterned displayed
will also be zoomed.

TEST 3 - BLT'S WITHIN DISPLAY MEMORY TEST.
This test will display a square in the upper left center of the
screen, then a smaller square next to it. The smaller square
will grow to the size of the larger one. Next a border pattern
will be drawn around the screen starting at the upper left hand
corner. Next, a series of small squares will be drawn in the
upper left of the screen that move out along a diagonal line.
Then the small squares will move in along the same line.
Finally a square will be displayed in the middle left center of
the screen then a smaller square next to it. The smaller square
will grow to the size of the larger one.

TEST 4 - BLT'S FROM/TO MAIN MEMORY.
This test will display a square in the upper left corner of the
screen. The square will grow out from the corner in a diagonal
direction. On nodes with zoom capability the square will also
grow in size or zoom in and out. Color nodes will have rainbow
colored squares. Then another square will be displayed in the
upper left corner above the previous pattern.

TEST 5 - RASTER OPS ALU TEST.
The test will display a small pattern of "dots" in the upper
corner. It will then display several columns of large boxes, with
one box in the upper corner. Then some of the columns of boxes will
be changed via various raster operations (blts, fills etc). The
number of columns changed depends on the available functionality
of the system under test. This will be repeated with the single
box drawn in a different corner each time.

TEST 6 - DRAW TEST.
This test draws different types of lines to the display.
The pattern you see will be a diagonal line with a box below it,
and a square spiral drawn above it. This pattern will be displayed
three times during the test. The first pattern will be just above
the center of the screen, the second at the center and the third
just below the center. On color nodes the three patterns will be
drawn in red, green and blue. The test will then display various
"drawn" images and do data verification on them. This will test arcs,
multilines, boxes, and line styling.

TEST 7 - DISPLAY LIST TEST.
You will see a line rotated at the center of the display, on color
nodes the line will change color.

TEST 8 - FILL TEST.
This test displays filled areas. The sequence you should see is :
solid rectangle, tile filled rectangle, shaded rectangle, solid circle,
shaded circle, solid triangle, shaded triangle, solid trapezoid,
shaded trapezoid, solid octagon and shaded polygon. The shapes are
all drawn in the upper left of the display.

TEST 9 - CLIP/DIVIDE TEST.
The display will show a horizontal line growing outward from the
center of the screen and then a growing vertical line growing
outward from the center.

TEST 10 - THREE DIMENSIONAL TRANSFORM TEST.
This test runs on nodes with a graphics processor, and on nodes with true color
capabilty. This test will display two viewports, one containing a 3D
wireframe image and the other containing a textual definition of
the current test phase. It will then tumble the wireframe image.
On some node configurations different wireframe or solid images may
be displayed. GRTEST will perform a checksum comparison of both viewports.

TEST 11 - (reserved for future use).

TEST 12 - VISUAL TESTS.
Please note that not all visual tests may be valid for a node,
depending on the type of graphics subsystem it has. There are fourteen
subtests as follows;

display boundaries - outlines the boundaries of the screen.
horizontal/vertical grid - grid pattern.
diagonal grid - diagonal line grid.
circles - 9 circles
color map spectrum - Incrementally goes through all colors.
colored bars - vertical color bar pattern.
shaded surfaces - 8 Shaded spheres.
zoom factors - colored ring zoomed in x, y, and z directions.
double buffered animation - X Y Z zoom/rotate.
interlace monitor test - left and right side of screen are offset by a line.
grey scale pattern - shaded grey pattern from left to right.
focus pattern - 9 focus boxes at various locations
monitor rgb alignment pattern - red, green, blue and white boxes of varied intensity.
imaging mode - pattern on screen simulating either 8 planes for a 4 plane system
or 24 planes for a 8 plane system.

Museum