.ND "August 27, 1985"
.TL
The Diagnostic Disk Generator \(em Help for the IHVs                        
.AF "AT&T Information Systems"
.AU "M. E. Smith" MES FJ 01311 5804 1F-101A
.# re-created 91-03-17 Kris Kugel kak@hico2.westmark.com
.MT "Memorandum for Record"
.#
.# The below doesn't seem to center/nf the footer info
.# .BS C N
.# .B "AT&T INFORMATION SYSTEMS \- PROPRIETARY"
.# No portion of this document shall be used or disclosed
.# outside of  AT&T-ISL without the authorization of
.# the Director of the originating organization.
.# .BE
.PM BP
.H 1 "INTRODUCTION"
.sp
IHVs who develop hardware as an adjunct to the UNIX PC need
to be able to provide diagnostic tests specific to their
devices.
It is desirable that these vendors be able to
create these diagnostics with minimal effort.
Furthermore,
it is desirable that the diagnostics present a consistent
interface with respect to the official diagnostic disk that
is a member of the UNIX PC foundation set.
.P
This memo will describe the installation and use of a tool
that allows vendors to create a customized diagnostic disk
quickly while requiring that they only know the internals of
their devices.
The memo will also describe a set of
interrupt handling routines and stdio routines provided by
the generation environment to make it easier for users to
write their hardware-specific diagnostic routines.
.H 1 "INSTALLATION OF THE DIAGNOSTIC DISK GENERATOR"
A STORE user will automatically have the software installed
upon request using the Install Software from THE STORE
command.
The command will put the source files and Makefile
(see Section 5 below) in the empty directory.
It will also
create a subdirectory named "mkdiag."
This directory will
contain the diagnostic disk generator files.
The user
should change directory to mkdiag before proceeding to
generate diagnostic disk source.
.H 1 "THE DIAGNOSTIC DISK GENERATOR"
The diagnostic disk generator is invoked by typing the name
.sp
.ti 4
   diag
.sp
The diagnostic disk generator first asks  the  user  whether
he/she  wants  to  add,  change, delete, review, make source
code, or save.
.H 2 "Add command"
The generator prompts the user for the following:
.BL
.LI
A one-character identifier of the set of tests.
This
character should be a small number that will correspond
to the index into the menu for this set of tests.
.LI
An entry in a menu associated with a particular set of
tests.
.LI
A description used for help requests.
.LI
The list of tests, including the names of function
calls that implement the tests.
.LI
The number of "subtests" within each test.
.LE
.sp 1
At this point the generator creates an internal entry
containing the data just entered.
.H 2 "Change/Delete command"
In both cases the generator prompts the user for the onecharacter
identifier of the set of tests.
If "Delete" was
requested, the generator deletes the entry from its internal
buffer.
If "Change" was requested, the user is allowed to
re-enter data for this set of tests.
.H 2 "Review command"
This command causes the generator to dump its internal
buffer to the screen using some simple formatting so that
the user may review what he/she has entered so far.
.H 2 "Make Source command"
This command instructs the generator to create source files
from the contents of the generator's internal buffer.
The
result is two files, newmain.c and newmsg.c, that can be
compiled (using the Makefile) into a diagnostic executable
suitable for copying onto a disk (see below).
.H 2 "Save command"
The save command instructs the generator to write its
internal buffer to disk.
In this way a generation session
can be restarted at a later date.
.H 1 "CREATING THE SPECIFIC FUNCTIONS"
The user is responsible for creating source files that carry
out the tests on his/her hardware.
These functions may have
one argument: the subtest number.
A function may contain a
switch on this number if the user wants that function to
execute more than one test.
Note that the generator creates
subtests in the range 0 to n-1, where n is the number of
subtests specified for this test.
.H 1 "CREATING THE EXECUTABLE"
After the user has executed a "Make Source" command, the
files newmain.c and newmsg.c are resident in the mkdiag
directory.
These files should be copied to the parent
directory with the names main.c and msg.c; i.e.
.sp
.in +4
   cp newmain.c ../main.c
   cp newmsg.c ../msg.c
.in -4
.sp 1
Also, the files that the  user  has  created  to  carry  out
specific  diagnostic  tests  on  his/her  hardware should be
moved to mkdiag's parent directory.  All  the  source  files
should  then  be  compiled,  preferably  using  the packaged
Makefile (see make(1) in the UNIX System  V  User's  Manual)
with  additions  for  the user's source files. (The Makefile
included with the diagnostic disk  source  contains  "hooks"
for  names  of  user-defined source and object files.  Those
user-defined file names  should  be  substituted  for  those
"hooks.")
After compilation, the executable should be copied (using
"mount(7)" and "cp(1)") to a floppy disk.
The executable
(whose name is "s4diag" if the packaged Makefile is used)
must be named "unix" or linked to an executable with that
name in order for the boot rom to load the diagnostic disk
code into memory at boot time.
.H 1 "THE STANDARD ENVIRONMENT"
Certain standard UNIX routines are provided with the source
files that are compiled along with the user's hardware
diagnostics.
Thus the user can call these routines from
his/her hardware specific diagnostic code in order to save
development time.
Synopses of these routines can be found
in Appendix 2.
.H 1 "CONCLUSION"
The diagnostic disk generator provides a simple way to
create a diagnostic disk without knowing the internals of
the diagnostic disk software.
The resulting executable will
NOT contain any of the official diagnostic disk tests; if
the desire of the IHV is to integrate his/her tests with the
official tests, the IHV will have to understand the inner
workings of the diagnostic disk source (as briefly described
in Appendix 1 below).
.SG mes
.SK
.HU "Appendix 1: Internal Design of the Official Diagnostic Disk Software"
There are five outstanding parts of the diagnostic disk
software:
.AL 1
.LI
The menu entries, all of which are displayed when the
diagnostic disk is executed.
The entries are defined
in the structures pHdUD1 and pHdUD2 in the source file
msg.c.
.LI
For each menu entry, the set of tests executed.
The
set of tests is defined in the TestList structure in
main.c.
.LI
For each set of tests, the names of functions that
define the set.
These function names are defined in
the fn_array structure in main.c.
.LI
The code in each of those functions.
The code is
located in separate files; usually all the functions
defining a test are located in the same source file.
.LI
For each function, a set of subtests.
A subtest is a
number which is passed as the argument to the testing
function.
A switch statement in the function
interprets the argument and executes the associated
subtest.
.LE
.sp 1
Thus, when the diagnostic disk user requests an item from
the menu, the software executes a list of (function,
subtest) pairs.
That list defines the test (actually, the
set of tests) that the user requested.
.SK
Appendix 2: Standard Environment Interface
.br
.AL A
.LI
Interrupt Handling Routines
.AL 1
.LI
spl0(), spl1(), spl2(), spl3(), spl4(), spl5(),
spl6(), spl7():
These routines, which have no arguments, reset
the hardware priority to zero through seven
respectively.
They return an integer indicating
what the hardware priority was before the spl
call.
.LI
splhi():
This routine is identical to spl6().
.LI
splx(pri):
This routine resets the priority to the integer
pri.
It returns the an integer indicating what
the hardware priority was before the splx call.
.LE
.LI
Standard IO Routines
.AL 1
.LI
getchar():
Return the next character read from the console.
.LI
inflag():
Read Y or N from the console and return TRUE or
FALSE.
.LI
innum(pnum, snum, radix):
Read a number from the console of size snum into
an integer *pnum with the given radix.
.LI
input(pbuff, sbuff):
Read sbuff characters from the console into the
character buffer pbuff, or until EOL ('\r' or
'\n') or ESC ('\033').
.LI
printf(ctl, arg0, arg1, ...):
sprintf(buf, ctl, arg0, arg1, ...):
These routines work as described in printf(3S)
in the UNIX System V User's Manual except only
the following escape control sequences are
allowed.
.BL
.LI
%nd: Single precision signed decimal.
.LI
%nD: Double precision signed decimal.
.LI
%no: Single precision unsigned octal.
.LI
%n): Double precision unsigned octal.
.LI
%nx: Single precision unsigned hexadecimal.
.LI
%nX: Double precision unsigned hexadecimal.
.LI
%ns: String.
.LI
%c: Character.
.LI
%%: Percent.
.LE
.LI
In the above, "n" can be an integer or "v,"
whence the field width comes from the argument
list.
.LI
putchar(c):
Print the given character on the console.
.LE
.LE
.TC