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