grtest — Apollo

GRTEST (GRAPHICS_TEST) Revision 5.15, 09/02/87.

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) DIrect runs all valid direct mode tests (within a window)
BOrrow runs all valid borrow mode tests (whole screen)
NOVIsual do not execute visual tests
The default is BOrrow mode, visual tests executed.
Note - DIrect and BOrrow are not opposite, both may be
selected. If so then GRTEST will run all valid tests in
the first mode and then run all valid test in the
second mode.

-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, -Test or -DMA 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

-Dma only execute that portion of GRTEST which performs large
data transfers.
(options) none

-DIrect causes all test that can run in direct mode to do so
when selected.
(options) none

-BOrrow causes all test that can run with full display to do so
when selected.
(options) none

-ERRLog specify error log file parameters. The error log
receives a copy of all error messages if enabled.
This error logging feature is in addition to that
afforded by the streams 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 , -TEST and -Dma 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 -dma and -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. (Help file 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.bitmap

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 Plane Mask Verification 0 0
2 Refresh Logic Functionality 0 0
3 Memory Array Test 0 0
4 BLTs within Display Memory 0 0
5 BLTs from/to Main Memory 0 0
6 Raster Ops ALU Test 0 0
7 Display list Test 0 0
8 Clip/Divide Test 0 0
9 Vector Draw Test 0 0
10 Area Fill Test 0 0
11 Visual Tests 0 0
12 Three Dimensional Transform Test 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 test 11) do data verification.

TEST 1 - PLANE MASK VERIFICATION TEST.
The test will display flashing short horizontal lines in the upper
left corner of the screen.

TEST 2 - REFRESH LOGIC FUNCTIONALITY.
Depending on the node you will see a vertical line on the left
side of the screen or a horizontal line running across the bottom
of the screen or both. If the node has zoom capability These lines
will disappear after being displayed.

TEST 3 - MEMORY ARRAY 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.

TEST 4 - BLT'S WITHIN DISPLAY MEMORY.
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 5 - 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 6 - RASTER OPS ALU TEST.
This is a test of the nodes raster opcodes. During the test the
display will show a horizontal rectangle in the upper left corner
and three vertical rectangles just off to the right side. The
horizontal rectangle will be BLTed onto each of the vertical
rectangles using a raster op. The first of the three BLTs
(the left most vertical rectangle) will be a BIT BLT, the next
will use PIXEL BLTs, and the third will use ADDITIVE BLTs. The
BLTs start at the top of the display with raster opcode 0 and
progress down the display for the next opcode, so that opcode
15 BLTs appear at the bottom of the screen. During execution of
this test progress messages will be displayed below the test window.

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 - 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 9 - VECTOR 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 10 - AREA FILLS 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 11 - 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.

TEST 12 - 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 randomly 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.

Museum