PROLOD release notes -------------------- PROLOD is a system server task which is called via the POSSUM library to load device drivers. The task image is named LB:[ZZSYS]PROLOD.TSK and it is automatically installed by the system at boot time. The installed task name is $LOAD. Since PROLOD was not ready for release at the time P/OS version 2.0 was shipped, a PROLOD server has been provided with the file name PROLODV2.TSK. For P/OS version 2.0 or 2.0A ONLY, you must copy this file to LB:[ZZSYS]PROLOD.TSK to use loadable drivers. For P/OS version 3.0 and later, the file is already included on the distribution kit and will be automatically installed with the rest of P/OS. There is a minor bug with the PROLODV2.TSK distributed on the P/OS V3.0 PRODCL2 floppy; it is corrected in the task image with this distribution, and an indirect command file for ZAP to apply the correction to the PROLODV2.TSK distributed on a P/OS version 3.0 kit is also included. The problem is that the documented feature of assigning the logical name PROLOD$MSG the equivalence of 0 to cause PROLOD to type diagnostic messages on your terminal will not work on 2.0 systems. Analysis of the problem shows that it is either a documentation error in the TLOG$ series of macros, or a bug in the TLOG$ macros themselves, take your pick. The bottom line is that if you code the source of a program using any of the TLOG$ macros (TLOG$, TLOG$C, or TLOG$S), and you place a zero in the third field, which is currently reserved, as opposed to just leaving the field blank, the DPB generated when assembling on a 3.0 system will be 10. words instead of the 9. words generated on a 2.0 system. The DPB will be regarded as invalid on a 2.0 system, and the request will always fail with the error IE.SDP, indicating invalid DIC or DPB size. PROLOD does not check for the cause of the failure; it just assumes the translation failed due to the absence of the logical, and skips typing the output message. The ZAP patch corrects the DPB to a 2.0-compatible DPB, and then everything works fine. By the way, if you desire your code to work on pre-3.0 systems, the fix currently is to leave the third field of a TLOG$ macro blank instead of placing a zero in it. This causes a DPB to be generated that will work on all versions of P/OS. There are several errors in the version 2.0 Tool Kit "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). 7 The CTB definition description was not documented. The following macro excerpt 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 logical 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. 3 - If your driver fails to load, correct the problem and reboot. 4 - Do not depend on any registers being preserved by $IODON. In particular this means R5 may under some circumstances (overlapped I/O completion) be trashed. The error codes that PROLOD returns as server dependent errors are: 0. Illegal request format - 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 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 - 72. Warning - KRB interrupt vector in use - 73. Symbol is undefined in file - 74. Symbol is doubly 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" on version 3.0 or later systems. .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 buffer format string .even .end start