RT-11 MULTIPROCESSOR SYSTEM MANUAL  (Version 20-MAR-85 NKGAZG)  PAGE








          M       M   PPPPPPP                 1         1      
          MM     MM   P      P               11        11      
          M M   M M   P      P              1 1       1 1      
          M  M M  M   P      P                1         1      
          M   M   M   PPPPPPP                 1         1      
          M       M   P                       1         1      
          M       M   P                       1         1      
          M       M   P                       1         1      
          M       M   P                     11111     11111    







			*************************
			* MULTIPROCESSOR RT-11  *
			*			*
			*     SYSTEM MANUAL	*
			*************************





		1.  Introduction

		2.  Contents of the distribution package

		3.  Making the Connection

		4.  Defining the job settings and device lists

		5.  Source conditionals & building programs

		6.  Handlers and Pseudo-Handlers

		7.  Bootstrapping

		8.  Updates/Known problems

		        APPENDIX

		A.  MP-11 V5 Release Notes
		B.  Toggle-in bootstrap examples

1. INTRODUCTION.
----------------

This manual is a guide for installing & maintaining the MULTIPROCESSOR
MP-11 package as developped at the University Hospital Groningen. Read the
MP-11 User's Guide and DECUS Proceedings papers carefully before pro-
ceeding. Also consult occasionally the program sources for further details.

Report all problems/suggestions, well documented, to:

  H. Haenen
  Dept. Clinical Neurology AZG
  P.O. Box 30.001
  9700 RB GRONINGEN
  The Netherlands

  Tel.  050-612497 / 612689
  (International 3150-612497 / 612689)
  Telex 53942


$
2. CONTENTS OF THE DISTRIBUTION PACKAGE
---------------------------------------

The distribution medium will generally contain at least the following
list of program sources.

  DCJB50.MAC  Data communication job

  QNJ50 .MAC  Job DMA handler for Qnector
  PDJ50 .MAC  Job handler for WB-11, WBV-11, DR-11C, DR-11K, DRV-11

  PD50  .MAC  Data communication Interrupt Handler, DR(V)-11(C)/WB(V)-11
  QN50  .MAC  Data communication Interrupt DMA Handler, Qnector


  JSHW50.MAC  JSHOW   displays device list, jobs active, Read/Write protection

  JOBDEF.MAC  JOBDEF  initializes job info file SY:JBINFO.DAT by
		      interactive query
  JOBDEF.COM          example indirect commandfile for JOBDEF
  MAIL50.MAC  MAIL    accesses mailbox, updates ASCII device list
  HELL50.MAC  HELLO   message exchange with remote mailbox
  WATC50.MAC  WATCH   monitors remote mailbox contents
  JBDA50.MAC  JBDATE  fetches remote DATE&TIME and sets locally
  JBHD50.MAC  JBHOLD  subroutines used by BG for blocking
                      of DC jobs by suspending/resuming them

  PSP50 .MAC  General purpose PSeudo handler,
	      default configured as the standard RT-11 lineprinter 
  MTP50 .MAC  Magtape Pseudo handler
  RDP50 .MAC  Universal Disk Pseudo handler
  HL50  .MAC  Message Handler for HELLO

  SROM50.MAC  Short primairy bootstraps for all hardware
	      Needs secundairy soft bootstrap BOOT50.MAC at remote site!
  BOOT50.MAC  Soft bootstrap program for DR/WB/Qnector(NOT to be PROMmed!)
	      To be used in combination with SROM50 or CROM50!  
  CROM50.MAC  Combined short primairy bootstrap+memory test 
	      for Qnector, WB(V)-11, DR(V)-11 (C), DL(V)-11
	      Needs secundairy soft bootstrap BOOT50.MAC at remote site! 

  DR11VC.TXT  Parallel hardware, DR(V)-11, connection details
  RSP30 .TXT  RSP documentation
  MANUAL.DOC  System manual
  USER  .DOC  User's Guide

$
  HARDWARE DIAGNOSTICS:

  For WB-11, WBV-11, DR-11 C, DR-11 K, DRV-11:

  PDTEST.MAC  Transmits a testword and waits for receive, compares word
  PDECHO.MAC  Echo's a word received.

  For Qnector:

  DMTEST.MAC  Transmits a buffer, receives it and compares
  DMECHO.MAC  Echo's a buffer received
  QNTEST      Local test of Qnector without cable connection. Supplied
	      by Westvries Systems on request at purchase of hardware.


$
3.  MAKING THE CONNECTION
-------------------------


Start as simple as possible by setting up only ONE connection.
First of all prepare the HARDWARE connection. Use machine-ODT to do
as much checkout as possible, e.g.(DR/WB) put a value in the output
register and check if the transmitter flag goes down. Look on the
connected machine if the input ready flag is high and read the input
value and check. Now the input ready flag should be down and the
transmitter flag(on the other machine) should be up. Do the same test
for the reverse direction. For further checkout of the hardware you
can use the following programs. However, this is only possible if you
have already running RT-11 on both machines. If you do not have a disk
on a machine you could boot RT-11 through a serial line. A very handy
and cheap way to make a memory-only system temporarily stand-alone is to
use a TU58/DECTAPE II as system device. This cassette tape system needs
only a serial line to interface with the computer. Test the hardware
using the programs PDTEST & PDECHO or DMTEST & DMECHO & QNTEST.
 In the case of trouble, pay attention to hardware details and correct
cabling. E.g. cables crossing nearby power supplies or other strong
emitting apparatus may induce noise strong enough to disturb any
communication!

After hardware checkout FOLLOW THIS CHECKLIST ACCURATELY for software
installation (see remainder of manual for details):

  1. Set assembly conditionals in the sources.
  2. Assemble sources, build programs, handlers etc.
  3. Copy all programs and handlers to the corresponding SY: disk.
  4. Bootstrap all systems with disks when they are not running.
  5. Create the file JBINFO.DAT on SY: of DC-job(s) by running the
     JOBDEF program.
  6. Load all handlers to be used by the DC-(Data Communication) jobs.
     (except for Special Directory devices, e.g. MAGTAPE, which may be
     loaded later).
  7. SET USR NOSWAP. Load job handler, assign logical JOB:. FRUN/SRUN
     DC-job. Repeat for additional job(s) to be run.
  8. Execute SHOW JOBS and JSHOW for checkout.
  9. Boot memory only processors.



4. DEFINING THE JOB SETTINGS AND DEVICE LISTS
---------------------------------------------


Make a list of peripherals to be supported remote and which are present
on the configuration that runs the DC-job. I/O Channels to these devices
are opened at startup of the DC-job. So handlers should be loaded and remain
loaded. If a handler is not loaded at startup, no error message will
result but the associated device is not available to the job(see
JSHOW). The USR should be set to NOSWAP, as the job cannot
accommodate room for the USR. After startup the USR may be set to
SWAP. The special directory devices make an exception, as .LOOKUP and
.CLOSE processing is done by the job. So SET USR NOSWAP for
opening/closing on a special directory device, otherwise an error message
will be printed and the request will be aborted. 

Defenition of the DC job's devices, default read & write access and some
other job parameters are stored on the file JBINFO.DAT. Each hardware system
which runs DC jobs should have a dedicated JBINFO.DAT file.
The data in SY:JBINFO.DAT are setup with an interactive query using the
program JOBDEF. Store the answers in a file so that a next time, when you
want to make changes, you can run this answer file as an indirect command-
file!


/===============================\
! Description of JOBDEF utility !
\===============================/

MP-11 Utility to setup:

               1. Device lists
               2. Default Read/Write access
               3. Job handler list

Input for device list:
----------------------
[Dev:Filename.Ext/R:n/W:m]
/R:n  option to give READ ACCESS for job n to the
      device or file specified, no n means access
      for all jobs
/W:n  option for WRITE ACCESS, see /R:n for meaning n
/Q    Quit with current setup, again
Note: no terminal input advances to next device slot!
----- multiple /R and /W may be given on the same line!

Input for job handler list: [Dev:]
----------------------------------
where  Dev:  is the job handler name
Note:  no input terminates list!
-----  no switches!

/=======================================\
! Example of interactive JOBDEF session !
\=======================================/

.JOBDEF
 JOBDEF Version 1.0, type /H for HELP text.

[Dev:Filename.ext/R:n/W:m] for device slots:
--------------------------------------------
Slot 00, DX0:/R
Slot 01, DX1:/R/W:1
Slot 02, DX2:/R
Slot 03, DX3:/R
Slot 04, DX4:/R
Slot 05, DX5:/R
Slot 06, RK:/R/W:0
Slot 07, DM:/R
Slot 08, SY:JBINFO.DAT/R/W
Slot 09, HL:/R/W
Slot 10, LP:/W
Slot 11, LP1:/W
Slot 12, LP2:/W
Slot 13, RD0:/R:0
Slot 14, RD1:/R:1

Free device description:
------------------------
Slot 00 :DX0  (System)    :
Slot 01 :DX1  (Removable) :
Slot 02 :DX2              :
Slot 03 :DX3              :
Slot 04 :DX4              :
Slot 05 :DX5              :
Slot 06 :RK05 (Removable) :
Slot 07 :RK07 (Removable) :
Slot 08 :JBINFO (Mailbox) :
Slot 09 :HELLO to nextone :
Slot 10 :SP  (SPOOLER LP) :
Slot 11 :SP1 (Wide LP)    :
Slot 12 :SP2 (Plotter)    :
Slot 13 :RD0 (Remote disk):
Slot 14 :RD1              :

Job handler names:
------------------
Job  0, DJ:
Job  1, WJ:
Job  2, 

-------------------------------------
Maximum no. of JOB's (1-7)    [3]:  :2  :
Message slot (JBINFO.DAT)     [8]:  :8  :
MAGTAPE slot (0-14) [no = RETURN]:  :   :
-------------------------------------

?JDF-I-Device & Jobhandler list update OK!

?JDF-W-No  BOOT file    for JOB 0 ! (Input file SY:DJBOOT.SYS).
?JDF-W-No  BOOT file    for JOB 1 ! (Input file SY:WJBOOT.SYS).


REMARK
======

 A maximum of 15 devices is supported by the jobs (1 is reserved for the
 JOB-handler). This limit is due to the maximum of 16 I/O channels which
 RT-11 default supports. Although this number could be extended to 256
 I/O channels, no coding is done until now for such an extension.


$
5.  SOURCE CONDITIONALS & BUILDING PROGRAMS
-------------------------------------------

Consider all conditionals specified below and set them to the appropri-
ate value in order to optimize your application:

 Source  Conditional  Purpose
 ------  -----------  -------
 DCJB50   SPDIR       Special Directory support is enabled for SPDIR=1
          BSTRP       1 = generate code for booting.

 DC/job
 Handler  CHK         1=Enable checksum calculation and checking.
		      If CHK=0 fixed pattern transmission.

          UNITS       No. of valid device units for this handler
          UNIT0       Equivalent RSP device unit for unit 0 of this device.	
          QLEN        Nr. of (pseudo)devices which can simultaneous generate
		      an I/O request (default set to 5).

          DR11        2=DR11K, 1= DR-11(V)/(C), 0= WB-11(V) HARDWARE
          FAST	      1=Fast interrupt processing.
          TIMOUT      Enable time-out support(Time=10.*TIMOUT sec., 50 Hz.).

          PDVEC       Vector of DC handler which controls the hardw. interface

 SROM50&
 BOOT50    INT        selects DR(V)-11 or WB(V)-11, Qnector hardware

 BOOT50   NPASSW      Nr.  of characters in the password.


Inspect DC and job handler for I/O-page address and vector setting.

If PD is NOT the name of the bootable driver on disk, then set B$DNAM=^RXX,
where XX.SYS is the name on disk. B$DNAM is located after the .DRBOT macro
in the handler source.


$
Assembling examples
-------------------

	MAC DCJB50			! Job
	
	MAC (JSHW,MAIL,HELL,WATC)50	! Utilities

	MAC JOBDEF                      ! Creates SY:JBINFO.DAT

	MAC (PD,QN,PDJ,QNJ)50 		! DC & job handlers
	(Depending on nr. jobs/hardware, assemble handlers again for
	 other hardware/IO page addresses and vectors)

	MAC (HL,RDP,PSP,MTP)50		! Pseudo handlers

	MAC/OBJ:xxBOOT BOOT50   ! After having selected the appropriate
				! hardware (xx= e.g. DJ / KJ / WJ or QJ)

$
Linking examples
----------------

Jobs:    
	LINK/FOREGR/EXE:DCJOB DCJB50


Utilities:
	LINK/EXE:JSHOW JSHW50
	LINK/EXE:HELLO HELL50
	LINK/EXE:MAIL MAIL50
	LINK/EXE:JOBDEF JOBDEF
	LINK/FOREGR/EXE:WATCH WATC50

Handlers:
	LINK/EXE:SY:PD.SYS PD50
	LINK/EXE:SY:HL.SYS HL50
	LINK/EXE:SY:LP.SYS PSP50
		.
		. etc.
BOOT-program:
	LINK/EXE:xxBOOT.SYS xxBOOT

		where e.g. xx = DJ for DR(V)-11(C) hardware
				KJ for DR-11 K
			  	WJ for WB(V)-11
			  	QJ for Qnector


6.  HANDLERS AND PSEUDO-HANDLERS
--------------------------------

Besides address and vector settings an important issue with DC handlers
is their device characteristic. Normally they are defined as random
access (disk) devices with variable volume size. This means that they
support special funtion request #373 (return device size) for each device
unit. The sizes and characteristics (device status) of remote devices are
stored and maintained in the remote file JBINFO.DAT. 

The pseudo-handler RDP50 is also defined as a disk device and may be used
to access disks on RSP units up to 14. (15. is used by JOB handler).

The pseudo-handler PSP50 is general purpose and is default configured as
the standard RT11 lineprinter handler (LP:). However, as it knows the
command SET XX STATUS=xxxxxx, the device status (including the device
identifier) may be changed without rebuilding the handler (note: REM XX
and INSTALL XX necessary!).  There is no special function support provided
in this handler, so when necessary this requires coding (inspect in that
case the MTP50 and RDP50 handler sources).

HL50 and MTP50 are the specialised pseudo-handlers for the program HELLO
and Magtape respectively.



$
7.  BOOTSTRAPPING
-----------------
  
When you have a running RT-11 system, you can bootstrap a DC-handler with
the command BOOT DC:.  First you should make the remote disk bootable
with the command COPY/BOOT DC:RT11FB DC: or, at the site where the DC-job
runs, 
  	COPY/BOOT:DC DSK:RT11FB DSK:, 
  				where DSK: is the handler name for the disk.

If you have not a running RT-11 system(e.g. a "memory only" system) with
a DC-link, then, after having made the remote disk bootable:

	Select the appropriate bootstrap code in SROM50.MAC
	and execute it in ROM/PROM  or as toggle-in. If you
	have enough room in the PROM you can also use the
	combined bootstrap in CROM50. Before doing this you
	should have put the BOOT-program (e.g. DJBOOT.SYS,
	WJBOOT.SYS or QJBOOT.SYS) on the remote system disk
	and the DC-job to be used should have been build with
	the conditional BSTRP=1. The boot programs require a
	password before bootstrapping is possible.
			


  8.  UPDATES/KNOWN PROBLEMS.
  ---------------------------

  1. If you use a DC-job with MAGTAPE support you should be aware of the
     following problem. If you have a file on MAGTAPE which is not properly
     closed, the job will not find this problematic file and hangs. Check
     the MAGTAPE directly under RT-11 and make a new tape with proper EOT.

  2. Using the Qnector. When the system running the Qnector-JOB is down, the
     other site will encounter a time-out when an I/O is requested. However,
     a 2nd I/O request will hang the system in case the QN-handler was loaded.
     Problem solved 10-jun-83 using STOP-bit to cancel outstanding QN-command.

  3. Reading stranger (probably ANSI tape created under RSTS) MAGTAGE caused
     fatal errors. Cause: these tapes contain header records shorter then the
     RT-11 512 bytes records. The SPFUN read physical block(-8) returns there-
     fore a hard error and the program driving the remote pseudo MT: aborted.
     Solution(19-mar-84): the program aborted because the job did not send any
     data from an SPFUN with hard error. The job was therefore  coded to send
     also data, even after a SPFUN hard error, in case of SPFUN read request.

  4. Remote DATE&TIME fetch (program JBDATE) implemented apr-84. HELLO now
     also checks differences between local and remote DATE&TIME.
     The abort entry code of DC and pseudo handlers has now been slightly
     changed: when the abort entry is accessed(due 2X ^C or .ABORT of the I/O
     requesting program) after the DC data transfer is started but when no
     actual data transfer has been done (e. g. remote system down) then the
     outstanding I/O is terminated immediately. However, when some data
     tranfer has taken place, the abort code does nothing and the I/O termi-
     nates after the current I/O request is completed.

  5. The time-out timeslice is since mar-84 basically 0.1 sec.( for 50 Hz.
     clock). This is valid for all jobs and interrupt handlers( not for the
     looping handlers!). So a TIMOUT=60. yields a 6 second timeout interval.
     The timeout is now also fixed and independent of size of the I/O request.
     One exception is made for SPFUN/SPDIR requests which may be very long
     lasting such as MAGTAPE searches. For these requests the timeout is
     automatically set to about 20. minutes.

  6. Variable volume size support code (V5 and later) is now present in the
     QN and PD handlers (code can be easily transferred to other handlers).

  7. Some new SET commands are introduced (see Chp. 5. and handlers sources).
     Due to the limited SET code space, it is not possible to implement them
     to all handlers.

  8. A major update was finished early 1985. See the release notes of
     MP-11 V5 in appendix A for details.

  9. Several bugs were fixed in the new release (V5). Setup JOB & DEVICE lists
     is now very easy (interactive query) with NEW utility JOBDEF.

APPENDIX A: MP-11 V5 Release Notes
==================================


This release results from some major improvements and requires RT-11 V5.0 or
higher. Some minor bugs were fixed. Improvements and new features are:


- The service job was restructured: the hardware dependent part was put
  in a separate handler, the JOB-handler. Therefore the JOB itself is now
  hardware independent. In order to implement new hardware only the JOB-
  handler and the datacommunication handler have to be programmed.

  The restructuring of the service job into a program and a handler makes
  the package more transportable to other systems. It is now a small step
  to implement the package under RT-11 compatible time-sharing environments
  such as TSX-plus and SHARE-11


- The default buffer space for the service job is 256. words (1 disk block).
  More space can now be allocated at startup:
  e.g. the command FRUN DCJOB/BUFFER:256. allocates an extra buffer of 256.
  words. The JOB internal buffer size is than 512. words (2 disk blocks)


- All datacommunication and pseudo handlers of remote random access devices
  (disks) are now defined as variable size volumes (defined in RT-11
  since V5.0). This means that always the correct size of a remote disk is
  returned. For example DUP issues a size request when a disk is squeezed.
  In case of remote disk this size request is transmitted to the service job
  as a special function #373 request. Unless the permanent code for special
  function support the size of service job + job-handler is decreased! The
  only option remained to be selected at assembly time is support for
  special directory devices and Magtape!


- The device list for the remote available devices no longer remains in
  the service job itself but in service job information file SY:JBINFO.DAT
  This is also true for the default read/write protection scheme's.
  Changes to the lists are now easier applied and do not affect the job
  code. The lists are setup with an interactive query.


- An extra list in JSHOW and HELLO utility display device properties such
  as status, disk size, characteristics. Also with this list one can "see
  through" logical assignments made at the service job site


		   ===================================

APPENDIX B: TOGGLE-IN BOOTSTRAPS (All boot unit 0):	
===================================================

 DR(V)-11 (C) TOGGLE-IN Bootstrap (Status: CSR=167770) example:
 --------------------------------------------------------------
	address  code

      	000000	012706 	START:	MOV	#100000,SP	;Setup stack
		100000
     	000004	012746 		MOV	#340,-(SP)	;CPU prio -> 7
		000340
	000010	012746 		MOV	#.+6,-(SP)
		000016
	000014	000002 		RTI

	000016	012701 		MOV	#DRCSR,R1	;status
		167770
	000022	005761 		TST	4(R1)		;dump input
		000004
	000026	012761 		MOV	#10,2(R1)	;Transmit BOOT=10
		000010
		000002
	000034	012703 		MOV	#1000,R3	;Memory pointer
		001000
	000040	005711 	LOOP:	TST	(R1)		;Input?
	000042	100376 		BPL	LOOP
	000044	016123 		MOV	4(R1),(R3)+	;Store in memory!
		000004
	000050	022703 		CMP	#2000,R3	;All 256. words done?
		002000
	000054	101371 		BHI	LOOP
	000056	000137 		JMP	@#1000
		001000


 WB(V)-11  TOGGLE-IN Bootstrap (Status: CSR=175610) example:
 -----------------------------------------------------------
	address  code

      	000000	012706 	START:	MOV	#100000,SP	;Setup stack
		100000
     	000004	012746 		MOV	#340,-(SP)	;CPU prio -> 7
		000340
	000010	012746 		MOV	#.+6,-(SP)
		000016
	000014	000002 		RTI

	000016	012701 		MOV	#WBCSR,R1	;status
		175610
	000022	005761 		TST	2(R1)		;dump input
		000002
	000026	012761 		MOV	#10,6(R1)	;Transmit BOOT=10
		000010
		000006
	000034	012703 		MOV	#1000,R3	;Memory pointer
		001000
	000040	105711 	LOOP:	TSTB	(R1)		;Input?
	000042	100376 		BPL	LOOP
	000044	016123 		MOV	2(R1),(R3)+	;Store in memory!
		000002
	000050	022703 		CMP	#2000,R3	;All 256. words done?
		002000
	000054	101371 		BHI	LOOP
	000056	000137 		JMP	@#1000
		001000


 Qnector (DMA interface) TOGGLE-IN Bootstrap (Status: CSR=172410) example:
 -------------------------------------------------------------------------
	address  code

      	000000	012706 	START:	MOV	#100000,SP	;Setup stack
		100000
     	000004	012746 		MOV	#340,-(SP)	;CPU prio -> 7
		000340
	000010	012746 		MOV	#.+6,-(SP)
		000016
	000014	000002 		RTI
	000016	012701 	AGAIN:	MOV	#1000-2,R1
		000776
	000022	012711 		MOV	#10,(R1)	;BOOT code = 8.
		000010
	000026	012700 		MOV	#QNCSR,R0	;Load IO page address
		172410
	000032	010120 		MOV	R1,(R0)+	;Load BAR
	000034	012720 		MOV	#-1,(R0)+	; "   WCR
		177777
	000040	012710 		MOV	#CE+SND+GO,(R0)	; "   CSR
		000007
	000044	105710 	QNRDY1:	TSTB	(R0)		;Send BOOT code
	000046	100376 		BPL	QNRDY1
	000050	005710 		TST	(R0)
	000052	100761 		BMI	AGAIN
	000054	012760 		MOV	#-256.,-2(R0)
		177400
		177776
	000062	012710 		MOV	#GO,(R0)	;Receive BOOT(1 block)
		000001
	000066	105710 	QNRDY2:	TSTB	(R0)
	000070	100376 		BPL	QNRDY2
	000072	000137 		JMP	@#1000
		001000

-----------------------------------------------------------------------------
                                                                                                                                                                                                                                                                                                                                                                      