PROLOD ( P/OS V2.0) release notes
---------------------------------
PROLOD is a system server task which is called via the POSSUM library
to load device drivers. The task image resides on LB:[ZZSYS]PROLOD.TSK
and it is installed by the system at boot. The installed task name is
$LOAD.
The PROLOD task image file for P/OS version 2.0, "PROLODV2.TSK", should
be copied from the floppy disk to LB:[ZZSYS]PROLOD.TSK. The system will
install this task during system startup processing.
There are several errors in the "Guide to Writing an I/O Driver and Advanced
Programmer Notes" which could confuse the driver developer.
1 The illustration of the KRB in figures 4-13 and 4-15 is incorrect.
The first two words shown are K.ICSR and K.SLT. These two words
are actually located between K.PRM and K.VCT as follows:
+-------------------------------+
K.PRM | Driver dependent storage |
+-------------------------------+
K.ICSR | interrupt controller CSR |
+-------------------------------+
K.SLT | reserved | slot number |
+-------------------------------+
K.VCT/K.CON | vector/4 | contrl. index |
+-------------------------------+
. | . |
. / . /
. / . /
. | . |
+-------------------------------+
2 Many of the labels, such as $DAT, described in the manual imply the the
device name is optional. It is not optional. The label in the example
mentioned should be of the form $xxDAT where "xx" is the logical device
name associated with the first DCB in the driver's database (D.NAM).
3 The "dev" argument in the GTPKT$, DDT$, and INTSV$ macro is described
as being optional. It is not.
4 The order of the last two DDT$ macro arguments are reversed (p4-5).
The correct format is:
DDT$ dev,nctrlr,iny,inx,ucbsv,new,buf,opt
5 The sample driver BMDRV has no "#" characters due to the text
preparation method used. Also, the following labels (and any
references to them) are incorrect:
Documented as: Should be:
------------- ---------
$DAT $BMDAT
$DCB $BMDCB
$END $BMEND
6 The description of the PROLOD call is in error. The correct description
and format of the argument list follow:
STATUS,REQUEST,FNAM,FNAMSZ
where,
STATUS The address of an eight word status block
REQUEST The address of a word containing a request value
corresponding to the operation to be performed.
The defined decimal values are:
1. = Load a driver and bring online all associated
controllers and units.
2. = Unload a driver after successfully bringing
all associated controllers and units offline.
FNAM The address of a word which contains the two ASCII
characters from which the actual driver task and
symbol table filenames may be derived by PROLOD.
The derived name is of the form LB:[ZZSYS]xxDRV.TSK
and lb:[ZZSYS]xxDRV.STB. Both files must be present
to successfully load a driver.
FNAMSZ The size of the aforementioned two bytes (in bytes).
Note, there are several other less standard request
values associated with PROLOD and these requests
require a larger buffer.
7 The CTB definition description was not documented. The following macro
excert describes the CTB:
;+
; CONTROLLER TABLE (CTB)
;
; THE CONTROLLER TABLE IS A CONTROL BLOCK THAT CONTAINS A VECTOR
; OF KRB ADDRESSES. THIS VECTOR MAY BE ADDRESSED BY THE CONTROLLER
; INDEX TAKEN FROM THE INTERRUPT PS BY $INTSI.
;
;-
.ASECT
.=177754
L.CLK:'L' .BLKW 8. ;START OF CLOCK BLOCK (CLK BLK IS
;OPTIONAL, AND DRIVER DEPENDENT.
;ALLOCATION OF THESE 8 WORDS IS NOT
;REQUIRED IN THE DRIVER'S DATABASE
;UNLESS USED BY THE DRIVER ITSELF)
L.DID:'L' .BLKW 1 ;HARDWARE DEVICE ID (WORD ALLOCATION
;ALWAYS REQUIRED. MAY BE 0.)
L.ICB:'L' .BLKW 1 ;ICB CHAIN FOR THIS CTB
L.LNK:'L' .BLKW 1 ;CTB LINK WORD
L.NAM:'L' .BLKW 1 ;GENERIC CONTROLLER NAME (ASCII)
L.DCB:'L' .BLKW 1 ;DCB ADDRESS OF THIS DEVICE
L.NUM:'L' .BLKB 1 ;NUMBER OF KRB ADDRESSES IN TABLE
L.STS:'L' .BLKB 1 ;CTB STATUS BYTE
L.KRB:'L' .BLKW 1 ;START OF KRB ADDRESSES.
;
; NOTE: THE SYMBOL $XXCTB:: IS DEFINED FOR EACH CTB, WHERE THE
; SYMBOL IS NOT THE START OF THE CTB, BUT INSTEAD THE START OF
; THE KRB TABLE AT THE END OF THE CTB (L.KRB). THE SYMBOL XXCTB (NO"$")
; IS GENERATED BY THE DDT$ MACRO AND IS USED TO IDENTIFY THE
; WORD IN THE DRIVER WHICH CONTAINS THE ADDRESS OF THE CONTROLLER'S
; CTB IN PRIMARY POOL. XXCTB IS REFERENCE BY THE CODE GENERATED IN THE
; INTSV$ MACRO WHEN DETERMINING THE UCB ADDRESS.
;
;+
; CONTROLLER TABLE STATUS BYTE BIT DEFINITIONS
;-
LS.CLK='B'1 ;CLOCK BLOCK AT TOP OF CTB (1=YES)
LS.MDC='B'2 ;MULTIDRIVER CTB. (1=YES)
LS.CBL='B'4 ;CLOCK BLK LINKED INTO CLK Q (1=YES)
LS.CIN='B'10 ;CONT. USE COMMON INT TABLE (1=YES)
LS.NET'B'=20 ;THIS IS DECNET DEVICE.
;ICB LISTHEAD IN K.PRM, L.DCB INVALID (1=YES)
Developer suggestions:
1 - Before attempting to load your device driver, be sure to load and
run XDT, so that you are prepared to handle any problems which
may arise.
2 - PROLOD attempts to return a meaningful error message to the
developer if and only if the loagical name "PROLOD$MSG" with
the equivalence name "0" is defined. Multiple errors may be
detected in the course of loading and sanity checking the driver
and it's database.
The error codes that PROLOD returns as server dependent errors are:
-1. File not a valid driver task image
-2. Privileged command
-3. Inconsistent argument length
-4. Illegal request function code
-5. Illegal unit name format specified
-6. Specified unit not found
-7. Illegal controller name specified
-8. Specified controller not found
-9. Failed to offline device
-10. I/O error on input file
-11. Failed to bring device online
-12. Controller already online
-13. Unit already online
-14. File has illegal STB format
-15. Device not found in system
-16. Illegal device name specified
-17. Database for not found in system or driver
-27. Partition/region not in system
-33. Device not mounted
-34. File not contiguous
-35. Open failure on file
-40. Task image I/O error in file
-46. Partition too small
-50. Illegal driver task APR usage
-51. Partition/region is a common
-60. Driver already resident
-61. Driver being loaded or unloaded
-62. Insufficient pool space
-63. Loadable driver support not in system
-64. Driver not loaded
-65. Driver cannot be unloaded, still online
-66. Device is attached, busy, online and/or mounted
-68. Invalid driver data base at offset in file
-69. Driver built with wrong executive STB file
-70. Warning - KRB interrupt vector too high
-71. Insufficient ICB pool space for CPU
-72. Warning - KRB interrupt vector in use
-73. Symbol is undefined in file
-74. Symbol is multiply defined by file
-75. Illegal value for symbol in file
-76. Driver dispatch table is inconsistent
-77. CTB is not supported by driver -- not loaded
-78. Cannot load/unload a pseudo device
-79. Too many symbols of the form in file
-80. CTB does not exist
-81. DCB table for CTB is full
-82. KRB table of CTB will not accept KRB
-83. KRB not in loadable data base
-84. CTB name is a duplicate
-85. Warning - loadable driver larger than 4K
-86. Partition/region is not a common
-87. KRB is not offline
-88. Illegal use of partition or region
The following macro program illustrates a PROLOD call. Another technique
for calling PROLOD is the DCL command "LOAD".
.TITLE LOAD - Example PROLOD call
.mcall qiow$s,exit$s ;request system macros
;
; This task requests PROLOD to load the driver XXDRV from LB:[ZZSYS]
;
start: mov #loaarg,r5 ;get args for sample call to PROLOD
call prolod ;load the driver
;print status block always
mov #stat,r2 ;point to status args
mov #fmt,r1 ;output format
mov #outbf,r0 ;output buffer
call $edmsg ;format it
qiow$s #io.wlb,#5,#5,,,,<#outbf,r1> ;print it
exit$s ;exit
;
; local data
;
loaarg: .word 4 ;four arguments (simple load call)
.word stat ;pointer to eight word status block
.word rqst ;pointer to PROLOD request
.word fnm ;pointer to filename size
.word fnmsiz ;pointer to size (in bytes) of fnm
stat: .blkw 8. ;eight word status block
fnmsiz: .word fnmsz ;word containing size of fnm
rqst: .word 1 ;load (and online all) request
fnm: .ascii /XX/ ;driver name
;implied filename "LB:[ZZSYS]XXDRV.TSK"
; AND "LB:[ZZSYS]XXDRV.STB"
fnmsz=.-fnm ;name extension as this can't be spec'd)
outbf: .blkb 132. ;output buffer for status display
fmt: .asciz /%Nload request status: %N%8P/ ;output bufer format string
.even
.end start