.ll70
.lt77
.in7
.nf
.sp4
    T E S T      P L A N


    OF THE


    M O D U L A     C O M P I L E R         ( PDP-11 / UNIX SYSTEMS )
.fi
.sp12
.ce4
RELEASE   1
.sp
June 1978
.sp30
.ce
I. D.  Cottam
.sp
UNIVERSITY OF YORK      -       DEPARTMENT OF COMPUTER SCIENCE
.sp
Heslington, York, Y01 5DD, England        Telephone 0904-59861
.bp
.ce
TABLE OF CONTENTS
.sp4
.in+5
1. INTRODUCTION
.sp
2. SOFTWARE OVERVIEW
.sp
3. TEST PHILOSOPHY
.sp
   3.1 Objectives
   3.2 Test Configuration
   3.3 Test Vehicles
.sp
4. RESTRICTIONS AND LIMITATIONS
.sp
5. REFERENCES AND APPLICABLE DOCUMENTS
.in-5
.ce
.sp4
APPENDICES
.sp2
.in+5
I   :   SEQUENTIAL MODULA TEST PROGRAMS AND PROCEDURES
.sp
II  :   (CONCURRENT) MODULA TEST PROGRAMS AND PROCEDURES
.sp
III :   MODULA PROGRAMS OF GENERAL INTEREST
.in-5
.nr V1 0
.bp
.CH "INTRODUCTION"
This document is the test plan for the Release 1 MODULA compiling 
system produced by the Department of Computer Science at the 
University of York. The compiler is tested against references 1 
and 2:

"MODULA Compiler, Release 1, Functional Specification; May 1978;
University of York, Department of Computer Science."

&

"MODULA: A language for modular multiprogramming; N. Wirth,
Software - Practice and Experience; 7, No 1, 3 (1977)."


It is the intention that the tests specified herein serve two major
purposes. Firstly, the tests provide the University of York with a
yardstick by which a decision may be taken on whether a version of
the MODULA compiling system has reached a level of reliability such
that it is suitable for release to other institutions. Secondly,
receiving installations may run these tests, following the receipt
of a MODULA release package, in order to verify the success of the
transport operation.
.CH "SOFTWARE OVERVIEW"
.SE "MODULA - the language"
MODULA [2,3,4] is a recent product of the group at  ETH  Zurich  under  the
direction  of  Professor N.  Wirth.  The language is intended primarily for
programming dedicated computer systems, such  as  those  found  in  process
control applications, using mini-or micro-computers.
.sp
MODULA is based on PASCAL  but,  in  addition  to  the  conventional  block
structure  present  in  that language, it introduces a module structure.  A
module is a set of procedures, data types, and variables  where  the  names
that  are  "imported"  and  "exported"  from  the module must be explicitly
stated  in  the   module   heading.    MODULA   also   introduces   general
multiprogramming facilities in the form of processes, interface modules for
controlled access  to  shared  variables,  and  signals  for  inter-process
communication.   It allows the specification of machine-specific peripheral
references and operations within a form of the module structure known as  a
device module.
.SE "The York Compiler"
.SS "History"
The York MODULA Compiler was largely developed by Jeremy Holden during 1976
-  1977 while he was supported by a grant from the Science Research Council
(SRC) of Great Britain.
.sp
The original compiler ran under the DEC RSX-11D operating system,  but  has
been  modified  to  run  under  UNIX (A product of Bell Telephone Labs) the
operating system currently in  use  by  the  University's  Digital  Systems
Laboratory.
.SS "Compiler Features"
* The compiler is  capable  of  producing  code  for  a  PDP-11  or  LSI-11
processor with or without the Extended Instruction Set (EIS).
.sp
* Run-time Systems for the PDP-11 or  LSI-11,  with  or  without  EIS,  are
available.  The EIS version requires about 150 words while that for non-EIS
systems occupies about 200 words.
.sp
* High quality object code is produced by the compiler.  Tests suggest that
the  object  code  compares  favourably  with any other PDP-11 compiler not
performing complex global optimisation.
.sp
* The user may request a line numbered listing of the source file.   It  is
also  possible  to  list  the  assembly  code  file should the user wish to
inspect the compiled code.
.sp
* Recursive procedures are allowed.  The  maximum  depth  of  recursion  is
specified in the procedure heading.
.sp
* Several language extensions have been implemented.
.sp
* Compiler switches  are  provided  to  control:   object  code  production
(optimised  or not, and with or without EIS);  source listing;  and the use
of certain language extensions.
.SS "Languge Restrictions"
* All names must be declared before use.
.sp
* The standard procedures 'off' and  'among'  have  not  been  implemented.
Other language constructions allow their effect to be duplicated.
.sp
* The VALUE part of a level 0 block has not been implemented.
.SS "Language Extensions"
* Extensions are available at two levels.
.sp
Permanent extensions are simple in nature and do not require  the  user
to 'warn'
the  compiler  that  they  are  being  used.   Besides  the already
mentioned recursion depth indicator the following permanent extensions  are
implemented:
.sp
* 'Compile-time expressions' may be written anywhere  the  strict  language
specifies a constant.
.sp
* The additional comment brackets { } may be used.
.sp
* The standard procedure 'halt' may be called with  an  integer  parameter.
At  run-time  this  value  is  placed in register 0 before the processor is
halted.
.sp
Optional extensions are more complicated and will only be  recognised  when
the compiler's extension switch is set on.
.sp
* A CASE statement may have an ELSE part.
.sp
* Array constant displays are allowed.
.sp
e.g.  CONST row = (1,2,3)
.SS "Operational Characteristics"
* Written in BCPL the compiler uses a  four  pass  scheme  with  inter-pass
communication performed via sequential binary files.
.sp
* A memory area of 20K words is required for the compiler and  workspace  .
With this amount of space, programs of about 2000 lines may be compiled.
.sp
* Compilation speed is of the order of:
           5 + n/12 seconds
for an n line program running on a PDP-11/40 with an RP03 disk.
.CH "TEST PHILOSOPHY"
.SE "Objectives"
* All language features defined by [2] (modified by information
contained in section 3 of [1] 'Language Comparison with MODULA
Report') to be checked for correctness.
.sp
* All specific compiler features to be checked for conformity to
the Functional Specification [1].
.sp
* No modifications to be made to the compiler during testing.
.sp
* Two sets of test programs to be employed for each pass of the
compiler. One set to produce the errors detected by the pass; the
other to contain every valid construct processed by the pass.
Every statement in the compiler to be executed at least once.
.sp
* A final objective of this test set organisation is to aid in
the debugging of future releases of the compiler. Since the
intermediate (or final) code output by a pass may be listed
(see reference [7]), a simple comparison can be made between the
results of a new 'experimental' compiler and the, tested, released
version.
.SE "Test Configuration"
The test configuration used by the University of York consists of
a PDP11-40/UNIX system:
.nf
.sp
.in+10
*  PDP11-40 processor with EIS option
*  64K words of core store
*  50M byte RP03 exchangable disk
*  DECwriter II
.in-10
.sp
.fi
plus a DL-11 link to another PDP11-40/RSX-11M system:
.sp
.nf
.in+10
*  PDP11-40 processor without EIS option
*  28K words of core store
*  2 x RK05 disks
*  DECwriter 
.in-10
.sp
.fi
The minimal PDP-11 equipment configuration suitable for compiling
and running the test cases is that required by the UNIX operating
system. For further details consult reference [10].
.sp
The UNIX machine is used for compiling all the test programs and,
additionally, running all the programs containing only sequential
features (so-called 'Sequential-MODULA' programs). Test programs
exploiting MODULA's concurrent processing features are copied down
the DL-11 teletype link to the second PDP11-40 (referred to locally
as 'p2') and run as completely free-standing systems.
( Installations with only a single PDP11/UNIX configuration will,
naturally, have to 'take down' UNIX in order to execute the concurrent
test programs. )
.SE "Test Vehicles"
The following software test vehicles have been written to automate
and ease the testing effort:
.sp
*  A Sequential-MODULA Nucleus: seqmod.s.
This is an assembly code segment which, when assembled together with
the output from the MODULA compiler, allows programs not containing
processes to be run under UNIX control. This Nucleus also contains
code to interface with the UNIX I/O system routines:  fopen, fcreat,
getc, putc, and flush.
.sp
*  A MODULA module: CharacterIOviaUNIX.
This module is used by all the sequential test programs and exports 
the following identifiers:
.sp
.fi
     rewrite        -        PROCEDURE(ARRAY integer OF char)
                             Creates/opens the file whose name
                             is supplied as actual parameter.
.sp
     writec         -        PROCEDURE(char)
     writen         -        PROCEDURE(integer)
     writes         -        PROCEDURE(ARRAY integer OF char)
     writeb         -        PROCEDURE(boolean)
     writebits      -        PROCEDURE(bits)
                             Output a character(integer/string/
                             boolean/bits) to the file previ-
                             ously  specified in the  call of
                             rewrite.
.sp
     newline         -        PROCEDURE
                              Equivalent to the call:
                              writec(12C).
.sp
.fi
*  A Sequential-MODULA program to produce a test report: testsum.s.
Source program is supplied in file :  testsum.mod.
.sp
*  Shell command files to:
.sp
.nf
 .  Compile a sequential test program incorporating, via ed, the
    Nucleus and the module CharacterIOviaUNIX: tstseqmod.
.sp
 .  Compile, using tstseqmod, and run a single sequential test program:
.fi
.sp
.nf
.ce2
.in+10
run1 run1g run1n run1gn
run2 run2g run2n run2gn
.in-10
.fi
.sp
.in+4
The 'run1' set is used for programs which produce 'expected versus
obtained' results. The 'run2' set is used for programs which produce
output that must be compared with another file containing the expected
results. The 'g' and 'n' suffixes indicate that the appropriate compiler
switches are set (see reference [1] for an explanation of compiler
switches).
.in-4
.sp3
.nf
 .  Compile and run all the sequential test cases: runseqmodtests,
                 runwithnoeis, runwithnoopt, runnoeisnoopt.
.sp
        runseqmodtests        uses           run1   and   run2
        runwithnoeis          uses           run1g  and   run2g
        runwithnoopt          uses           run1n  and   run2n
        runnoeisnoopt         uses           run1gn and   run2gn.
.fi
.CH "RESTRICTIONS AND LIMITATIONS"
This test set is not complete. However, in the interest of
distributing the MODULA Release 1 system without undue delay, it
was decided to issue the current (1978 June 28) test cases.
It is the intention to continually add test programs to the
set presented herein, and periodically issue updates to this 
document. Users are encouraged to criticise the test set and/or
contribute new programs. Contributions may vary from a few lines,
perhaps testing a sequential feature, to 'real-life' systems
containing many concurrent processes.
.sp
The following error messages are not produced by any of the test
set programs:
.sp
.ce11
      Message                          Pass No.
.sp
  Dictionary overflow                     1
  Unexpected end-of-file                  1
  '.' expected                            1
  Fatal symbol table overflow             2
  Unrecognised symbol                     3
  Not enough workspace                    3
  Unrecognised operator                   3
  Values still present                    3
  Too few values                          3
  Unexpected error                        3
.sp
No formal tests are included for the compiler's BASE and PASS0
segments (i.e. such events as overlay file failure and incorrect
arguments to '/bin/modula').
.CH "REFERENCES AND APPLICABLE DOCUMENTS"
.nf
1.  MODULA Compiler, Release 1, Functional Specification;
    May 1978; University of York, Dept. of Computer Science.

2.  N.Wirth, MODULA: A language for modular multiprogramming
    Software - Practice and Experience,7, No.1, 3 (1977).

3.  N. Wirth, The Use of MODULA.
    ibid, 37

4.  N. Wirth, Design and Implementation of MODULA.
    ibid, 67.

5.  N. Wirth, Towards a Discipline of Real-Time Programming.
    CACM, 20, No.8, 577 (1977).

6.  MODULA Compiler, Release 1, Installation Guide 
    University of York, Dept. of Computer Science.

7.  MODULA Compiler Release 1, Implementation and Maintenance
    Specification, University of York, Dept. of Computer Science
    Not Yet Available.

8.  J.Holden and I.C Wand, Experience with the programming
    language MODULA.
    University of York, Dept. of Computer Science YCS.5 (1977).

9.  J.Holden and I.C Wand, An Assessment of MODULA.
    To be published.

10. Documents for use with the UNIX Time-Sharing System,
    Sixth edition, undated, Bell Telephone Laboratories.

11. K.Thompson, and D.M Richie, UNIX Programmer's Manual,
    Sixth edition, May 1975, Bell Telephone Laboratories.

12. Digital Equipment Corporation, PDP-11/05,10,35,40
    Processor Handbook (1973).
.fi
.bp
.sp2
.ce
APPENDIX  1
.sp7
.ce
SEQUENTIAL-MODULA  TEST  PROGRAMS AND PROCEDURES
.bp
.nf
.ce
A1.1 TEST PROCEDURE FOR SEQUENTIAL-MODULA
.sp3
(a) Change current directory to '/usr/mod/tc'.
                 chdir  /usr/mod/tc

(b) To run all the sequential test cases enter one of:
                 runseqmodtests
                 runwithnoeis
                 runwithnoopt
                 runnoeisnoopt
    depending upon the desired settings of the compiler's g 
    and n switches.

(c) The four shell command files referred to in (b) each create
    two files of interest to the user:  testresults, seqmodtest.rep

    where:

       testresults    contains    expected v. obtained results
    and
       seqmodtest.rep contains    success/fail message for each test.
.sp4
Notes:

  (i)  On the University of York PDP11-40/UNIX installation
       the sequential test cases require ~ 1 hour and 10
       minutes elapsed time (one user logged-in).

  (ii) For each test case, the right most column of the report
       file seqmodtest.rep should contain "Successful". Should
       a test fail then this column will, instead, contain the
       word "Failure".
.bp
.in1
.ce
A1.2 SEQUENTIAL-MODULA TEST PROGRAMS
.sp3
.bp
.ce
APPENDIX  II


     (CONCURRENT) MODULA TEST PROGRAMS AND PROCEDURES
.bp
A2.1 TEST PROCEDURE FOR (CONCURRENT) MODULA

(a) Change current directory to  '/usr/mod/tc'
                    chdir  /usr/mod/tc

(b) Compile the program  tick2.mod
                    mod p2 tick2.mod

(c) p2 should be running RSX-11M and be connected to the PDP11/UNIX
    system via a DL-11 operating at 4800 bps. Enter the following
    commands at the p2 DECwriter console:
                    SET  /UIC=[200,30]
                    RUN  LOAD
    Before running the loader prints out a question mark. Any 
    character typed in return will start the loader; thereafter
    code may be copied into p2 by typing:
                    cp  a.out  /dev/ttya
    at a UNIX terminal, assuming that the DL-11 of p2 is connected
    to ttya. Note that the loader cannot be used again until RSX-11M
    is reloaded.

(d) The program will start automatically and should send a BEL
    character to the DECwriter every second.

(e) Compile the program  test8.mod
                    mod p2 test8.mod

(f) Repeat step (c).

(g) The operation of this test program is described in reference [8].
.bp
.ce
A2.2 (CONCURRENT) MODULA TEST PROGRAMS
.sp3
.bp
.ce
APPENDIX III
.sp5
.ce
MODULA  PROGRAMS  OF GENERAL  INTEREST
.sp8
         Note:
               The programs in this appendix rely
               heavily on the equipment available
               at the University of York - Digital
               Systems Laboratory  (e.g. CAMAC).
.sp
               They may however prove useful to
               other institutions either directly
               or as program models.
.bp
