Trailing-Edge - PDP-10 Archives - BB-H311D-RM - swskit-tools/mtest.mem
There are 5 other files named mtest.mem in the archive. Click here to see a list.

                     Swskit Documentation For MTEST

MTEST is a program whose purpose is to allow the user to insert  MONITOR
instruction  execution  tests  at  any place in the TOPS-20 MONITOR.  It
functions as an interface to the UTEST  JSYS  (see  page  3-409  of  the
Monitor  Calls  Reference  Manual).   This  JSYS  provides  a method for
determining if every instruction in a section of monitor  code  actually
gets  executed.   It  confirms  that  a  test of the code is complete by
reporting the instructions that were executed during the test.

IMPORTANT NOTE:  Never insert a test over monitor data since  the  tests
cause  a  call  to  an internal UTEST JSYS routine to be inserted in the
words being tested.  If a test is made of monitor data, a corruption  of
the monitor data base is likely.

To allow examination of the test to be as convienient as  possible,  the
MTEST  program  provides  a  deassembler  for  the monitor instructions.
Symbols for various values are obtained using the SNOOP JSYS.   In  this
way  the  output  from MTEST should present the instructions in a format
similar to that of DDT.  Since the SNOOP JSYS allows an argument of  the
module  symbol table to search first for the symbol, MTEST also allows a
user to specify a default symbol table to search first.

One of the restrictions of the UTEST JSYS is that the section of monitor
code which is being tested cannot exceed a two page window.  This is due
to the data structures that TOPS-20 implements for this JSYS.  Not every
instruction  in  the  window  need  be  tested  nor  must  the  tests be
contiguous.  In other words, as many sections of  monitor  code  as  the
user  wishes  can  be  tested  at  the same time as long as the distance
between the first instruction and the last instruction to be  tested  is
no more that 2000 (octal) words.  If an attempt is made to insert a test
which exceeds this two page window, an error message will be printed  on
the terminal but all previous tests inserted will be preserved.

The actual test is not inserted into  the  MONITOR  until  the  test  is
started.  This allows a user to redefine the test if they so wish before
the test is started and it allows the user a means of setting up a  time
window  also  for  execution  of  the  test.   To facilitate the ease of
starting and stopping commands, a PSI channel is  dedicated  as  a  test
toggle.   Each  time  the specified control character is typed, the test
will either toggle on or off.

There is a command in MTEST  which  allows  a  user  to  simply  examine
monitor  code without affecting any of the tests which are set up.  This
allows the person to determine the exact instructions they wish to  test
before  they  insert  the  test.   To examine which tests the users have
already inserted, they need only type the command  RESULTS,  which  will
type  out  all  the  instructions  which  are  marked to be tested.  The
RESULTS command is also used to see the results of a test after the test
is  finished.   Each instruction which was executed will be preceeded by
an 'X'.  The results command is invalid while a test is in progress.
Swskit Documentation For MTEST                                    Page 2

A facility to run programs as inferior forks to MTEST is also available,
since  some  tests  will  need some JSYS, program, or EXEC command to be
specifically executed for the test.  For this reason there is a  command
to  enter  SDDT,  to  PUSH  to  an inferior EXEC, or to run any program.
These forks are ephemeral.

Other miscellaneous commands allow the user  to  reset  the  MTEST  data
base,  clear  default  symbol  table  and  redefine  the  toggle control

A summary of commands is listed below:

MTEST>? one of the following:
 Clear     Examine    Exit       Help       Insert     Push
 Reset     Results    Run        SDDT       Set        Start
 Stop      Toggle

        CLEAR           Clears the  default  symbol table  for  symbol

        EXAMINE         Examines a section of Monitor Code.

        EXIT            Exits from MTEST.   If a test  is in  progress
                        MTEST will not allow the EXIT command.

        HELP            Types this text.

        INSERT          Inserts a Monitor code test.  Note: this  does
                        not actually insert the test into the MONITOR,
                        rather, it sets up the MTEST data base so that
                        when the test  is started, MTEST  will have  a
                        test to insert.

        PUSH            Pushes to an inferior ephemeral EXEC.

        RESET           Resets the MTEST data base.

        RESULTS         Will  type  out  the  tests  which  have  been
                        inserted if  this command  is typed  before  a
                        test is started or  will type out the  results
                        of a test  if this  command is  typed after  a
                        test is stopped.  The command is illegal while
                        a test is in progress.

        RUN             Run a program in a ephemeral fork.

        SDDT            Runs an ephemeral SDDT fork.

        SET             Sets the default symbol table.

        START           Starts testing.

        STOP            Stops testing.
Swskit Documentation For MTEST                                    Page 3

        TOGGLE          Allows user  to specify  toggle character  for
                        test starting and stopping.

The following is a sample MTEST test.  Assume we are  getting  an  error
message  from  the  SWJFN  JSYS  and  we  wish to determine how the code
decided that there was an error condition.  What we wish to do is to set
up  a  test  of  the SWJFN code and see the path that the JSYS will take
upon executing it.

You need to be an enabled WHEEL to run this program
Do You Want to be enabled?YES
MTEST>SET (Lookup Module Name to) JSYSF
MTEST>TOGGLE (Character is) ^D
MTEST>EXAMINE (Monitor Code) 
Starting At: .SWJFN
Ending At: .SWJFN+10
.SWJFN+2    JRST BLKF6+116
.SWJFN+3    PUSHJ 17,F1+556515
.SWJFN+4    JSP 2,F1+10763
.SWJFN+5    PUSHJ 17,F1+2040
.SWJFN+6    JRST BLKF6+122
.SWJFN+10    XCT 4,BLKF5+317
Starting At: .SWJFN
Ending At: .SWJFN+10
1/   0   1
2/   0   1
[MTEST Test Started]
MTEST>STOP (Testing) 
  X  .SWJFN+2    JRST BLKF6+116
     .SWJFN+3    PUSHJ 17,F1+556515
     .SWJFN+4    JSP 2,F1+10763
     .SWJFN+5    PUSHJ 17,F1+2040
     .SWJFN+6    JRST BLKF6+122
     .SWJFN+7    PUSH 17,JFN
     .SWJFN+10    XCT 4,BLKF5+317

From this, it is seen that the error return is generated from SWJFN+2.