IN 93.6 VMS Driver for Unibus Magtapes Kevin Eng, Vicky White, and Tom Nicinski Fermilab Computing Department November 1988 A VMS driver for the TM02/TM03 controllers and the STC Unibus Interface is described. KEYWORDS: Device Driver Systems Supported: VAX/VMS V5 Software Version: STC MTDRIVER V7.0 CONTENTS CHAPTER 1 INSTALLATION 1.1 Introduction . . . . . . . . . . . . . . . . . . . 1-1 1.2 Installation . . . . . . . . . . . . . . . . . . . 1-1 1.2.1 Driver Version V3JB To Version V04F . . . . . . 1-1 1.2.2 Driver Version V5.0 To V6.1 . . . . . . . . . . 1-3 1.2.3 Driver Version V7.0 Onwards . . . . . . . . . . 1-4 CHAPTER 2 DIFFERENCES BETWEEN DRIVER VERSIONS 2.1 Version V03K . . . . . . . . . . . . . . . . . . . 2-1 2.2 Version V04 . . . . . . . . . . . . . . . . . . . 2-1 2.3 Version V04A . . . . . . . . . . . . . . . . . . . 2-2 2.4 Version V04B . . . . . . . . . . . . . . . . . . . 2-2 2.5 Version V04C . . . . . . . . . . . . . . . . . . . 2-2 2.6 Version V04D . . . . . . . . . . . . . . . . . . . 2-2 2.7 Version V04E . . . . . . . . . . . . . . . . . . . 2-3 2.8 Version V04F . . . . . . . . . . . . . . . . . . . 2-3 2.9 Version V5.0 . . . . . . . . . . . . . . . . . . . 2-3 2.10 Version V5.1 . . . . . . . . . . . . . . . . . . . 2-4 2.11 Version V5.2 . . . . . . . . . . . . . . . . . . . 2-4 2.12 Version V6.0 . . . . . . . . . . . . . . . . . . . 2-4 2.13 Version V6.1 . . . . . . . . . . . . . . . . . . . 2-4 2.14 Version X6.2 . . . . . . . . . . . . . . . . . . . 2-5 2.15 Version V7.0 . . . . . . . . . . . . . . . . . . . 2-5 CHAPTER 3 RESTRICTIONS AND PROBLEMS 3.1 Driver Functionality . . . . . . . . . . . . . . . 3-1 3.2 Tests Done On Driver . . . . . . . . . . . . . . . 3-1 3.3 Known Problems . . . . . . . . . . . . . . . . . . 3-2 3.4 Further Work / Tests On The Driver . . . . . . . . 3-3 APPENDIX A CHANGES TO THE DRIVER A.1 V03JB To V03K Changes . . . . . . . . . . . . . . A-1 A.2 V03K To V04 Changes . . . . . . . . . . . . . . . A-2 A.3 V04 To V04A Changes . . . . . . . . . . . . . . . A-2 A.4 V04A To V04B Changes . . . . . . . . . . . . . . . A-2 A.5 V04B To V04C Changes . . . . . . . . . . . . . . . A-3 A.6 V04C To V04D Changes . . . . . . . . . . . . . . . A-3 A.7 V04D To V04E Changes . . . . . . . . . . . . . . . A-3 A.8 V04E To V04F Changes . . . . . . . . . . . . . . . A-4 A.9 V04F To V5.0 Changes . . . . . . . . . . . . . . . A-4 A.10 V5.0 To V5.1 Changes . . . . . . . . . . . . . . . A-5 ii A.11 V5.1 To V5.2 Changes . . . . . . . . . . . . . . . A-6 A.12 V5.2 To V6.0 Changes . . . . . . . . . . . . . . . A-6 A.13 V6.0 To V6.1 Changes . . . . . . . . . . . . . . . A-8 A.14 V6.1 To X6.2 Changes . . . . . . . . . . . . . . . A-9 A.15 X6.2 To V7.0 Changes . . . . . . . . . . . . . . . A-9 APPENDIX B THE STC TRACE FACILITY B.1 Introduction . . . . . . . . . . . . . . . . . . . B-1 B.2 Driver Interface . . . . . . . . . . . . . . . . . B-1 B.3 User Interface . . . . . . . . . . . . . . . . . . B-2 B.3.1 Format Data File Format . . . . . . . . . . . . B-2 B.3.1.1 TRACE Entry Identifier . . . . . . . . . . . . . B-2 B.3.1.2 TRACE Entry Text . . . . . . . . . . . . . . . . B-2 B.3.1.3 Display Format . . . . . . . . . . . . . . . . . B-2 B.3.2 Sample Format Data File . . . . . . . . . . . . B-3 B.3.3 Command Format . . . . . . . . . . . . . . . . . B-4 B.3.3.1 Command Description . . . . . . . . . . . . . . B-5 B.3.3.1.1 COPYIO . . . . . . . . . . . . . . . . . . . . . B-5 B.3.3.1.2 COPYDMP . . . . . . . . . . . . . . . . . . . . B-5 B.3.3.1.3 DUMP . . . . . . . . . . . . . . . . . . . . . . B-6 B.3.3.1.4 REDUMP . . . . . . . . . . . . . . . . . . . . . B-6 B.3.3.1.5 SET . . . . . . . . . . . . . . . . . . . . . . B-6 B.3.3.1.6 SHOW . . . . . . . . . . . . . . . . . . . . . . B-7 B.3.3.1.7 DCL . . . . . . . . . . . . . . . . . . . . . . B-7 B.3.3.1.8 HELP . . . . . . . . . . . . . . . . . . . . . . B-7 B.3.3.1.9 EXIT . . . . . . . . . . . . . . . . . . . . . . B-7 B.3.3.1.10 QUIT . . . . . . . . . . . . . . . . . . . . . B-7 B.3.3.2 Command Summary . . . . . . . . . . . . . . . . B-7 CHAPTER 1 INSTALLATION 1.1 Introduction A VMS driver for TMO2/TMO3 magnetic tape controllers (TU16 or TE16 tape drives) and the STC Unibus interface has been obtained from CERN. This device driver was written by Norman Gee of the Rutherford Laboratory, for experiment WA42 at CERN. It has since been adopted and slightly modified by Guiseppe Mornachi of the CERN DD division, although CERN have now abandoned using the driver themselves. They have chosen to put a Massbus on all their VAXs. The driver which ran in the experiment WA42 was written for VMS version 2.5. The DD modified version (interrupt handler re-written) had been tested at CERN on VAX 11/750 with a TE16 drive only, under VMS version 3.0. 1.2 Installation 1.2.1 Driver Version V3JB To Version V04F The version of the driver received from CERN, as well as versions up to and including V04F created by us, based on the CERN driver, are on archive tape ZG0201. The tape is written at 1600 b.p.i. in VAX/VMS BACKUP (V3) format, with each version as a separate save set. The BACKUP save sets on the tape are MTV3JB .BCK Original version received from CERN. MTV3K .BCK Minimal change version. MTV4 .BCK Updated to current Digital TM driver standard. MTV4A .BCK Version 4 with minor changes needed for a VAX 11/730. MTV4B .BCK Minor bug fixes. MTV4C .BCK Bug fixes for incomplete emulation of the TM02/TM03 by the STC. 1-1 INSTALLATION MTV4D .BCK Bug fixes for improper emulation of the TM02/TM03 controller by the STC. MTV4E .BCK Bug fixes for improper emulation of the TM02/TM03 controller by the STC. MTV4F .BCK Bug fixes for improper emulation of the TM02/TM03 controller by the STC. Each BACKUP save set contains the driver source files MTDRIVER .MAR The driver source. MTDRIVER .COM Command file to assemble, link, and load the driver and connect units. MTVxx .SLP The SLP file to generate version XX from the previous version. To install the software, the system manager should set the default directory to the area to contain the STC driver and issue the following commands: $ SET DEFAULT stc_software_location $ SET UIC [stc_software] $ MOUNT /FOREIGN mag_tape /OVERRIDE= IDENTIFICATION $ BACKUP mag_tape:MTV4D.BCK /SAVE_SET [] /NEW_VERSION /OWNER= PARENT $ DISMOUNT mag_tape The system manager should build the driver using MTDRIVER.COM. The command file must be invoked in the directory it resides in. It also requires an argument: $ SET DEFAULT stc_software_location $ @MTDRIVER MAC Assemble the driver LINK Link the driver LOAD cu Load the driver, where C is the controller identifier and U is the tape unit number CONNECT cu Connect the tape unit, where C is the controller identifier and U is the tape unit number HELP To load the driver and connect the tape unit(s) during system bootup, the following commands should be put into the site-dependent startup file, SYS$MANAGER:SYSTARTUP.COM: $ SET DEFAULT stc_software_location $ @MTDRIVER LOAD cu $ @MTDRIVER CONNECT cu ! For each tape unit 1-2 INSTALLATION $ SET DEFAULT SYS$MANAGER: The LOAD command assumes a CSR of 772440 (octal) and a vector of 120 (octal). 1.2.2 Driver Version V5.0 To V6.1 Version V5.0 and future releases are on archive tape ZG0298. The tape is written in VAX/VMS BACKUP (V4) format at 1600 b.p.i. The save sets on the tape are STC_V5_0 .BCK Updated to VAX/VMS V4. TRACE facility added. STC_V5_1 .BCK Incorporated DEC fixes up to V03-014. STC_V5_2 .BCK Fixed drive offline upon unit initialization problem. STC_V6_0 .BCK Added support for the MicroVAX II / Microverter combination. STC_V6_1 .BCK Added support for directly specifying Q-bus address on a MicroVAX II / Microverter combination. Each save set contains the following files [save_set_name] | +---------+--------------+-----------+-------+-------+ | | | | | | [COM] [EXE] [LISTINGS] [TRACE] [MAINT] [SYSTEM] SETUP.COM MTDRIVER.EXE MTDRIVER.LIS | PRSTARTUP.COM MTDRIVER.STB MTDRIVER.MAP | SKIPDUMP.EXE SKIPDUMP.LIS | TAPEX.EXE TAPEX.LIS | IN0093nn.MEM | | +-----------+-------------------+ | | | [COM] [LIBRARY] [LISTINGS] SETUP.COM TRACE.EXE TRACE.MAP TRACE.HLB nnn.LIS TRACE_MT_FORMAT.DAT SETUP .COM Command procedure to define logical names. MTDRIVER .EXE The driver itself. MTDRIVER .STB Global symbol table for the driver. MTDRIVER .LIS Listing file for the driver. MTDRIVER .MAP LINK map for the driver. IN0093nn .MEM Internal document describing changes to the driver. PRSTARTUP .COM Command procedure executed at system 1-3 INSTALLATION startup to LOAD/CONNECT the driver. SKIPDUMP .EXE Debugging routine to dump a tape. SKIPDUMP .LIS Listing file for SKIPDUMP. TAPEX .EXE Tape exerciser. TAPEX .LIS Listing file for TAPEX. TRACE .EXE The TRACE program. TRACE .HLB HELP library for TRACE. TRACE_MT_FORMAT .DAT Data file describing TRACE code formats. TRACE .MAP LINK map for the TRACE facility. nnn .LIS Listing files for the TRACE facility. To load the driver when the system is booted, the system manager should place the following DCL commands into SYS$MANAGER:SYSTARTUP.COM: $ DEFINE /SYSTEM /EXECUTIVE_MODE /TRANSLATION_ATTRIBUTES= (CONCEALED, TERMINAL) stc$root device:[top_level.STC_V6_0.] $ @STC$ROOT:[SYSTEM]PRSTARTUP The command procedure STC$ROOT:[SYSTEM]PRSTARTUP.COM may need to be modified to reflect the correct CSR address and VECTOR address for the STC formatter interface. Version V5.0 and later releases of the driver have the TRACE facility built into them. The TRACE facility specific to the STC driver is described in Appendix B. 1.2.3 Driver Version V7.0 Onwards Version V7.0 is the current release version of the driver suitable for most VAX processor types (MicroVAX II, VAX 11/730, 11/750, 11/780). Future versions (if any) will be added as new backup save sets to the tape. The STC driver can be distributed using the DISTRIBUTE product: $ @BISON::DISTRIBUTE: You will be queried about which product (STC) and version you wish to distribute. Once the STC product is distributed, it must be configured for your system: $ @stc$root:[SYSTEM]PRINSTALL 1-4 INSTALLATION A series of questions will be asked. A configuration file will be created for the particular node on which the questions were asked. This permits multiple machines within a VAXcluster environment to have individual configurations and share the same code. To load the driver when the system is booted, the system manager can either use SITE_PRODUCTS or place the following DCL commands into SYS$MANAGER:SYSTARTUP.COM: $ DEFINE /SYSTEM /EXECUTIVE_MODE /TRANSLATION_ATTRIBUTES= (CONCEALED, TERMINAL) stc$root device:[top_level.STC_V7_0.] $ @stc$root:[SYSTEM]PRSTARTUP PRSTARTUP uses the configuration data file created by PRINSTALL. 1-5 CHAPTER 2 DIFFERENCES BETWEEN DRIVER VERSIONS This chapter details the changes made to the original CERN driver, version 3JB. 2.1 Version V03K The CERN driver (V03JB) would not run unchanged on a VAX-11/780. Some small changes were needed to make the driver work and handle density correctly with an STC 1935 interface. This version, although it will work under "normal" circumstances, has some bugs and deficiencies. It is essentially the 1979 version of Digital's TM driver, with changes for Unibus transfers. As such it has most of the bugs of Digital's 1979 TM driver. For example, BACKUP /NOREWIND does not work and CANCEL logic has flaws which under some circumstances can hang either the system or the process. Section A.1 details the changes made to V03JB. 2.2 Version V04 An attempt was made to bring the driver up to the level of the current Digital TM driver (for the Massbus interfaced TMO3). This could only be done by a visual comparison between the two drivers, since we do not have the source of the Digital TM driver in a machine readable form. Several routines were rewritten and a fair amount of code was added in the areas of Space File and Record, End of Volume handling, CANCEL and POWERFAIL. The new I/O function IO$_AVAILABLE was added. Section A.2 contains more details of the changes made. 2-1 DIFFERENCES BETWEEN DRIVER VERSIONS 2.3 Version V04A The working version 4 of the driver was transferred to a CDF VAX 11/730, where it crashed immediately. Changes were made to have all instructions referencing Unibus locations as words (two bytes). Section A.3 details changes to V04 of the driver. 2.4 Version V04B Troubles were experienced when length cables between the tape unit and the Unibus controller were used. The system hung. The problem was believed to be in the driver waiting at times for the controller to become ready. Section A.4 has information on the changes. 2.5 Version V04C When blank tapes were INITIALIZEd, the process would hang in MWAIT state if the INITIALIZE was aborted with control-Y. This was caused since the driver was interpreting an error on the driver (which is what blank tape returns) as an error not produced by blank tape. Section A.5 has more information on the changes. 2.6 Version V04D Whenever a BACKUP "recoverable error" was read back, the operation would time-out. This was due to the STC's incomplete emulation of a TM02/TM03 controller. When a block with an error is read, the driver backspaces over the block and attempts to re-read the block. The backspacing was performed using a WRITECHECK REVERSE controller function. The STC does not support both WRITECHECK and WRITECHECK REVERSE operations. After fixing the invalid function codes problem, the driver would return a parity error on a block that had a BACKUP "recoverable error". This occurred because the STC interprets the parity error bit in the error register differently than the TM02/TM03. The TM02/TM03 sets the bit when an unrecoverable CRC error occurs. On the other hand, the STC has error correction and sets this bit when it corrected a CRC error. Section A.6 details the changes to the V04C driver. 2-2 DIFFERENCES BETWEEN DRIVER VERSIONS 2.7 Version V04E The WRITECHECK function was removed from the driver function table. This version is a continuation of the fixes initiated with version V04D. Section A.7 details the changes to the V04D driver. 2.8 Version V04F Data loss was experienced on tapes. This occurred whenever a bad section of tape was detected. The problem was due to the error recovery algorithm used. Whenever a bad section of tape was detected, the driver would internally space back one record, write an extended interrecord gap, write the data block again, internally backspace a record (the one just written), and then perform a WRITECHECK operation. Since the WRITECHECK operation is a null (version V04D changes), the tape was position at the beginning of the just written record. The next write operation to the tape would then overwrite that record. Also, sometimes when routine MT_WAIT was invoked, the system would hang or crash. This was caused by the misuse of registers in passing information where the CSR of the tape controller resided. Section A.8 details the changes to the V04E driver. 2.9 Version V5.0 The major change involved updating the driver to operate under VAX/VMS V4. Also, sections of the source for the driver were moved around to make the code a bit easier to follow. The TRACE facility was added to the driver. TRACE permits run-time debugging of the driver by placing information into a TRACE buffer (circular). Section A.9 details the changes to the V04F driver. The development version of the driver was also placed under MMS/CMS (Module Management System and Code Management System), and a new directory structure. This version was never distributed publicly, and should not be used, as it contains a known bug where occassionally, an error would cause the driver to fail to perform operations. 2-3 DIFFERENCES BETWEEN DRIVER VERSIONS 2.10 Version V5.1 The DEC TMDRIVER fixes were incorporated into the STC driver. Not all the DEC changes were added though. The DEC fixes did fix a problem with the V5.0 driver, where the driver would occassionally fail to perform tape operations after an error (or abort). Section A.10 details the changes to the V5.0 driver. 2.11 Version V5.2 During unit initialization, if a tape was not LOADed and ONLINE when the unit initialization routine was called, the drive would be marked as offline (in the UCB). Subsequently, when a tape was mounted, the unsolicited interrupt routine would mark the drive online. This is an aesthetic fix rather than a real problem. The "problem" occurs in the STC Formatter's interpretation of the MOL (medium online) bit in the device type register (MTDT). The STC Formatter sets this bit whenever a tape is loaded and ONLINE. The TM03 calls the bit the slave present (SPR) bit, and sets it whenever the tape unit is powered up. Section A.11 details the changes to the V5.1 driver. 2.12 Version V6.0 This version added support for a MicroVAX II / Microverter combination. The Microverter is a board (available from Able) which performs mapping between a 22-bit Q-bus and an 18-bit Unibus. If the driver is running on a MicroVAX II, it assumes that the STC tape formatter is on a Unibus connected to the Q-bus via a Microverter. 2.13 Version V6.1 This version added support for a MicroVAX II / Microverter combination to permit users to directly specify Q-bus address to be used for transfers. This section of code is conditionalized (at assembly time) using the symbol Q2U$_EXPLICIT_QBUS_ADDR. If this symbol is non-zero, the Q-bus addressing functionality is included in the driver. The distribution version (on the ZG tape) does not include this functionality. This functionality is not fully supported, and therefore, interested users should contact the Computing Department to obtain a copy. 2-4 DIFFERENCES BETWEEN DRIVER VERSIONS 2.14 Version X6.2 This version fixes a problem where using P3 for the explicit Q-Bus address caused problems with some DEC software. P6 is now used. 2.15 Version V7.0 This version is upgraded to operated under VAX/VMS V5 in a uniprocessor (non-SMP) environment. 2-5 CHAPTER 3 RESTRICTIONS AND PROBLEMS 3.1 Driver Functionality The driver is written to support TMO2/TMO3 controllers and the STC unibus interface. According to the memo of G. Mornacchi sent with the software, having TE16 and STC drives co-existing is not a fully implemented feature. The hardware capability of "swapping" the order in which the bytes are written to tape is supported by the software, in one of two modes: 1. On each I/O request, by using the normally unused fourth QIO parameter 2. By a semi-permanent setup in one mode or the other, using the set mode or set characteristic I/O function. This is described in more detail in G. Mornacchi's attached memo. It will not normally concern us at all. A MOUNT command, which we always use, even if only MOUNT /FOREIGN will always reset the drive to its normal non-byte-swapping mode. Whatever anyone might choose to do with the mode of operation of the tape, either purposefully or accidentally, the next user of that drive will not be affected. Accidental passing of a 1 as the fourth QIO parameter would cause that record to be written or read byte-swapped. The driver is now capable of supporting all three densities of tape - 800, 1600 and 6250 bpi. The STC drive we used for testing supported only 1600 and 6250 bpi. 3.2 Tests Done On Driver The driver has so far been tested using only an STC Unibus interface (1935 type controller). No tests have yet been done 3-1 RESTRICTIONS AND PROBLEMS with TMO2/TMO3 controllers via a Unibus interface. Versions 4 and 4A of the driver have been tested on a Vax-11/780, both for a single unit, and for two units sharing the same controller. Tapes were read and written at 1600 and 6250 bpi using BACKUP and COPY. The CDF TU78 tape drives were used for the other end of the tests, reading and writing the 1600 and 6250 bpi tapes. BACKUP /VERIFY was used to check the correctness of data written to tape, and the DIFFERENCE utility was used to check files moved between VAX-4 and CDF VAX. These tests included both small and large physical block sizes. We successfully wrote multiple BACKUP save sets onto a single tape, with verification and no rewind on each save set. Tests with two units on the same controller revealed a problem. Occasionally it was found that use of both tape drives, interleaved, caused a positioning error on one of the drives. Similarly, unsolicited interrupts on one drive, while the other was writing, created spurious errors on the writing drive. The latter problem has been fixed by modifications to the unsolicited interrupt routine. Although the positioning errors which occur, once in a while, when two tapes are active, cannot be removed, their effect has been minimised, by a change to the software. The errors merely cause retries now. Apart from these minor difficulties, the software functioned correctly and was able to support simultaneous writing to the two units, including one unit at 1600 bpi and the other at 6250 bpi. The driver has also been tested on the CDF VAX 11/730 using a controller with a single unit attached. 3.3 Known Problems 1. The apparent interference effect between two tape drives on the same controller. This looks like a rather minor effect and may not be worth worrying about. STC has been asked if they have ever encountered this problem, but apparently they have not. 2. The software has been "patched" to force a unit to be marked as online whenever it creates an unsolicited interrupt. The STC hardware behaves differently than a TMO3 in a few minor ways and without this "patch", would cause a drive which had no tape online when the software driver was loaded to be marked offline permanently. Also the second unit on a controller gives different status bits on "unit online" interrupt than the first 3-2 RESTRICTIONS AND PROBLEMS unit! STC has been asked why. 3.4 Further Work / Tests On The Driver The driver will require a certain amount of maintenance to keep it in line with Digital's TM driver. A more careful visual comparison should perhaps be done sometime. Some of the updates to the Digital driver could not be immediately located, usually because they occurred in an area which contained Unibus transfer modifications. The essentially infinite combination of Controller hardware, Unit Hardware and Tape medium errors which can occur makes full testing of the software essentially impossible. If and when problems occur they may require investigation: we have spent about 6 working days on changes to the software, testing and documentation. 3-3 APPENDIX A CHANGES TO THE DRIVER A.1 V03JB To V03K Changes o A MOVZBL was changed to a MOVZBW in the Interrupt routine. o The REWIND bit UCB$V_MT_REWIND was set in the status word UCB$W_DEVSTS in all cases of rewind. Previously it had only been set when an exit without waiting for final interrupt was taken. (Routine RECAL, BISW at 20$: moved to before WFIRLCH instruction). This bit can then be tested in the routine TM_UNSOLNT, which can in fact be entered after the 2nd interrupt of a rewind. The STC 1935 controller puts up the SLA bit on completion of a rewind, then apparently puts it down again, and sets the BOT bit in the drive status register. However the interrupt at end of the rewind causes the unsolicited interrupt routine to be called and clear the VALID bit in the status word. This is obviously connected with the problem noted by Guiseppe of STC behaving differently in its use of the SLA bit. o I think that the VALID bit should be being set and cleared in UCB$W_STS in the interrupt routine - not UCB$W_DEVSTS. o The driver now supports all three densities 800,1600 and 6250 bpi. Some changes were necessary in both the mask DENSITY, the routine SETCHAR and the routine XFER. Note the density masks for the STC 1925 controller are different from the earlier version. A-1 CHANGES TO THE DRIVER A.2 V03K To V04 Changes o TMUNSOLNT - removed TRE bit on reset of device, do not clear valid bit on MOUNT. o Added 3 new fields to UCB and 2 new bits to UCB$WDEVSTS. o Added IO$AVAILABLE function and allowed IO$READPRESET function previously errored. o Update CANCEL routine completely to TM driver V2-027. o Save tape position at STARTIO o Clear RECORD and ORGPOS counters at REWIND/UNLOAD entry point o Updated SPCFILFOR and SPCRECFOR completely to TM driver V2-027. o Added EOV code just before SETEOF code. o Powerfail code updated to TM driver V2-027. o Dont clear VALID bit on positioning error. o Checks for CANCEL - extra check for BOT added. A.3 V04 To V04A Changes o All Byte and Longword mode references to unibus addresses changed to use only word mode o TMUNSOLNT called when BOT detected on unsolicited interrupt A.4 V04A To V04B Changes o Removed calls to MT_WAIT and TM_READY. This was necessary as the drive timed out when a long cable was used between the backplane and STC formatter. A-2 CHANGES TO THE DRIVER A.5 V04B To V04C Changes o Allow both OPI and FCE bits to be set when testing for recoverable error with byte count 0. A.6 V04C To V04D Changes General changes to the driver: o The Error Log buffer was changed from size 0 to a size based on the TM03 driver (TMDRIVER). o The minimum record size, MIN_RECORD, was changed from 0 to 14 (the VMS documented size). [Note: 0 is a legitimate size for GCR (6250 bpi) recording, but VMS documentation says 14, PE (1600 bpi) recording does not support records < 14 bytes. Due to the STC formatter's incomplete (and inaccurate) emulation of the TM03 controller, the following fixes were made: o The STC formatter does not support the WRITECHECK (reverse) functions. These were changed to NOPs and SS$_ILLCNTRFUNC is returned. o The F_INTSPCFOR and F_INTSPCREV functions were changed from WRITECHECK (reverse) functions to SPACE FORWARD and BACKWARD functions (under INTSPC:). o The bit corresponding to MT_ER_V_CRC (TM03) is not treated as an unrecoverable error by the STC formatter. Therefore, the error logic under READDATA: and READDATAR: was fixed. Another consideration is bit MT_ER_V_VPE (TM03) which the STC uses to indicate any tape error. A.7 V04D To V04E Changes Removed the WRITECHECK function from the FUNCTAB tables. A-3 CHANGES TO THE DRIVER A.8 V04E To V04F Changes o Fixed TM_SAVDRVSTS to place the CSR address into R4. MT_WAIT expects the CSR in R4, but calls to TM_SAVDRVSTS had the CSR address in R3 (and something else in R4). o Placed all calls to MT_WAIT and TM_READY back. This undoes most of fix V04B. o Modified MT_WAIT to use a simplified waiting loop that does not depend on internal register PR$_ICR. o Removed remaining calls to REQSCHAN and RELSCHAN at ERASE. These calls are required only for the MASSBUS. o Finished cleaning up V04D modifications for the internal spacing function. Since the SPACE FORWARD and SPACE REVERSE functions do not perform any data transfers, the sections which set up UBA parameters were removed (at INSTPC and RETREG, and routine TM_SETINTSPC). o Removed all data check operations (IO$MDATACHECK set) at READDATA, READDATAR, and WRITEDATA. The data check uses the WRITECHECK (REVERSE) functions, which the STC formatter does not support. I/O requests with IO$MDATACHECK set are performed, but data check portion is not executed. No indication is retured to the I/O requestor. A.9 V04F To V5.0 Changes Updated the driver for VAX/VMS V4. o Greatly modified documentation and style for (my) ease of reading and editing (including form feeds). This included moving routines around to more logical areas. o Changed MTWAIT to use the TIMEDWAIT macro rather than the processor specific register PR$ICR (non-existant in VMS V4). o Replaced the base of the device-dependent UCB fields for a tape driver from UCB$LDPC + 4 to UCB$KLCLTAPELENGTH (a suggestion from the VAX/VMS Release Notes V4.0). A-4 CHANGES TO THE DRIVER o Removed the CPUDISP macro definition, as it is defined in SYS$LIBRARY:LIB.MLB. o Added TRACE facility calls for debugging. A.10 V5.0 To V5.1 Changes Incorporated DEC fixes to TMDRIVER up to DEC version V03-014, 19-Jul-1984, from the VAX/VMS V4.2 microfiche set. Some (not all) of the major changes are o Dropped UCB$L_MT_RECORD from the UCB. UCB$L_RECORD is used in its place. o Dropped testing for minimum record length for PES (1600). o Modified error handling at TM_DTYPE, READDATA, READDATAR, CHECK_ERROR, and RETERG. Not all routines have been compared or corrected with the DEC driver. o Minor inconveniences: o Error logging is not enabled (in the DPT). The error logging and diagnostic buffer sizes need to be checked (the old ones are based on the Massbus TM03). o Associated with error logging, routine TM_REGDUMP needs to be compared with DEC's driver. o Under FDISPATCH, DEC performs the REQPCHAN just before the CASE. o The error correction under READDATA and READDATAR is slightly different. o XFER is different since it operates on a Unibus rather than a Massbus. The same is true for the device time-out code (above label TIMEOUT). The interrupt service routine, TM$INT, also "suffers" from non-Massbuss-ness. A-5 CHANGES TO THE DRIVER o Major worries (?): o DEC's POSIT routine branches to SETDEN (set density). This driver does not have SETDEN. o Under RECAL, DEC sets the REWIND bit in UCB$W_DEVSTS at local label 20$. o Dead track detection is not performed under RETREG, as UCB$W_MT_CC_SAV is not used by this driver; a check needs to be made where DEC's driver uses it. Other general changes: o Dropped DEBUG statements and related UCB$X_DEBUG. o Added additional TRACE calls. A.11 V5.1 To V5.2 Changes General fixes: o Fixed nuisance during Unit Initialization. If a tape is not LOADed and ONLINE, the unit is marked offline. The problem stems from the STC's use of the TM03's SPR (slave present) bit in the device type (MTDT) register. The STC uses it as a MOL (medium online) bit, saying a tape is both LOADed and ONLINE. The TM03 set SPR when the slave drive is powered up (present). If the MTCS2 register's NED (non-existant drive) bit is not set, then a drive will appear as online. o Changed TRACE codes TM_DTYPE and MT_UNIT_INIT. A.12 V5.2 To V6.0 Changes Added support for a MicroVAX II / Able Microverter / STC Tape combination under MicroVMS V4. The mnemonic Q2U refers to the Microverter. A-6 CHANGES TO THE DRIVER o The Microverter is a interface between the Q22 bus and an 18-bit Unibus. It permits mapping 22-bit address space to 18-bit address space and vice-versa. The STC Tape Formatter is a DMA device on the Unibus. o Added routine IOC_LOADQ2U and macro LOADQ2U. o Added additional TRACE entries. o Certain restrictions exist: o The Microverter registers and its Line Time Clock register are located at a compile-time address on the Q22 bus, Q2U_L_IOMAP and Q2U_W_LTC_SR. o Since there is no global means of keeping track of which Microverter registers are being used, only device may use the Microverter at a time (because the transfer starting address on the Unibus will always be the same). Watch out for multiple unit devices where the driver permits simultaneous outstanding standing (in progress) I/O on more than one unit. The transfer starting address on the Unibus is 0. This accomplished by using the first Microverter mapping reqister. Two routines have this hardwired into their logic, IOC_LOADQ2U and XFER. The bit UCB$V_MT_Q2U in UCB$L_MT_MAP is used to determine whether the Microverter is being used. o The Microverter forces the low bit of the Q-bus address to be zero, thus requiring the transfer buffer to be word aligned. A check for word alignment is made only if the Microverter is present (FDT routine CHECK_XFER_BUFFER). o Certain coding deficiencies exist. o This driver will not work on a MicroVAX I and will most likely cause system corruption and/or crashes. To alleviate the problem, MT_UNIT_INIT sets a unit offline and invalid (in UCB$L_STS). o If the transfer size is greater than the size that all the Microverter mapping registers can handle, the problem is ignored by using all the Microverter registers (so part of the transfer will not occur, without any error reporting to the user). A-7 CHANGES TO THE DRIVER The reason that this problem is not addressed is that the transfer size would have to be larger than 256Kbytes (18-bit addressing), but the transfer size must fit within 16 bits, in UCB$W_BCNT (watch out when this field becomes a longword!). o Since V04F commented out much of the code for the internal spacing functions at INTSPC and RETREG and at TM_SETINTSPC, no code was added to support any of the Microverter extensions. If the STC formatter does emulate the TM03 completely, then those sections should be uncommented and the Microverter support added there also (the major changes being those made under XFER). o In IOC_LOADQ2U, no check is made to see if the Q-bus address generated from VEC$W_MAPREG and UCB$W_BOFF is word aligned. The Microverter forces the low bit <0> of an address to be zero. This is not checked here as CHECK_XFER_BUFFER (FDT routine does this) and transfers use direct I/O. A.13 V6.0 To V6.1 Changes Added conditionalized code for the MicroVAX / Microverter environment. The code is conditionalized on the value of the symbol Q2U$_EXPLICIT_QBUS_ADDR. The code permits the user to specify a Q-bus address via the P3 argument in a QIO call. If the Q-bus address is passed, it is used to load the Microverter registers (routine IOC_LOADQ2U). If the Q-bus address is not passed, then the Q-bus address is computed as before. [NOTE: An address of zero implies that Q-bus address was NOT explicitly passed.] o The IRP field IRP$L_MEDIA is used to contain the QIO's P3 parameter (the Q-bus address). The FDT routine CHECK_XFER_BUFFER is used to place P3 into IRP$L_MEDIA. o Routine IOC_LOADQ2U does not compute the Q-bus address if a non-zero QIO P3 parameter was passed. Instead, it uses IRP$L_MEDIA. A-8 CHANGES TO THE DRIVER Since this is a quick fix that is not intended to be supported, the user must make sure that the following are legal: o The QIO arguments P1 and P2 are still processed by the standard FDT routines. Therefore, the user must pass a legal buffer address in P1 (as this buffer is locked locked down by the FDT routines). o No checks are made as to the legality of the passed Q-bus address (in P3). This means that such operations can crash the machine if care is not excercised. o Currently, any read or write operation (IO$_READnBLK, IO$_WRITEnBLK, and IO$_WRITECHECK) allow the passing of an explicit Q-bus address. Since virtual and logical operations are intercepted by the ACP / XQP interface, I don't know if the P3 argument from the original QIO is passed onto the subsequent QIOs from the ACP / XQP. o IRP$L_MEDIA is used. Care must be excercised, when any additional FDT routines are called, in how they treat IRP$L_MEDIA (for e.g., BYTE_SWAP uses IRP$L_MEDIA + 4). o The best solution would be to use separate I/O function codes or I/O function modifiers (QIO processing does not change the function modifiers). This would provide added security and solve the problem where the user wishes to pass a zero Q-bus address. A.14 V6.1 To X6.2 Changes Fix X6.1 to use P6 rather than P3 for the physical address. P1 through P5 can be used by ACP functions, thus causing problems with standard DEC software. A.15 X6.2 To V7.0 Changes Upgraded to operate under VAX/VMS V5. The existence of the symbol VMS_V5_FLAVOR indicates that the driver is to be compiled for VAX/VMS V5. The driver will only operate under UNIPROCESSOR mode; the SMP environment is N O T supported. A-9 CHANGES TO THE DRIVER o CRB$L_INTD+4 --> CRB$L_INTD+VEC$L_ISR o SETIPL --> SETIPL ENVIRON= UNIPROCESSOR o DSBINT --> DSBINT ENVIRON= UNIPROCESSOR o SYS$GL_OPRMBX --> SYS$AR_OPRMBX A-10 APPENDIX B THE STC TRACE FACILITY ______ Much of this appendix was taken verbatim from PN 186, Driver _____ _______ Debug Utility by Kevin Eng and Vicky White. B.1 Introduction A driver debug utility was developed for use in the development of the Connected Machines communication driver. This appendix will describe the functionality of the debugger, modified for the STC driver, at the user level. Details of the mechanism to interface to the driver itself may be found in the document _____ _______ ___ ___ _______ IN 80, TRACE Feature for VAX Drivers by Ruth Pordes. B.2 Driver Interface The interface to the driver is implemented with the use of the technique developed at CERN. An internal TRACE buffer is maintained inside the driver as a circular queue. TRACE entries are inserted into the queue at various points in the driver code. A single TRACE entry contains a list of numbers, a TRACE entry identifier and a set of TRACE data values. The debugger utility can then copy the driver TRACE buffer and other information about the driver into a buffer inside the debugger. What we get is a "snap shot" in time of the flow of execution of the driver. Details of the format of the driver TRACE buffer and routine that copies the driver TRACE buffer and information about the driver can be found in document IN 80. B-1 THE STC TRACE FACILITY B.3 User Interface The debug utility will first read in a format data file called TRACE$FORMAT (can be a logical name). This format file contains the display format for each possible TRACE entry. Finishing the data input, the TRACE utility will prompt the user for commands. The format of the data file and a description of the set of commands known to the debugger are explained in the following sections. B.3.1 Format Data File Format The format data file, TRACE$FORMAT, records describe how each type of TRACE entry in the TRACE buffer is to be displayed. The format of a record is simply The fields are separated by at least one blank. B.3.1.1 TRACE Entry Identifier - The TRACE entry identifier is a number that uniquely identifies a TRACE entry. The value may range from 1 to 999 inclusive. The entry identifier 999 is used as the default for those entries that do not have a corresponding display format in the data file. The data file should contain at minimum, a display format for a TRACE entry 999. B.3.1.2 TRACE Entry Text - The TRACE entry text contains an ASCII string that is to be displayed when the corresponding TRACE entry identifier is encounted in the TRACE buffer. The TRACE entry text begins with a exclamation mark ("!") with the display text string following it. B.3.1.3 Display Format - The display format specified the type and size of each value in the TRACE entry. An entry value may be a long word, a word, or a byte. The value may be displayed as a hexadecimal, decimal, or octal number, or a special field display. The display format of each value is specified by either a reserve word or a pseudonym B-2 THE STC TRACE FACILITY description. The set of reserved words are 1. DEVSTS. Displays the data a driver status fields. 2. EXESTS. Displays the data as status fields for the executive stream fork code. 3. UCB. Displays the data as a UCB address in the form of an unsigned hexadecimal number. 4. UNIT. Displays the data as the device unit in the form of a signed decimal number. 5. CSR. Displays the data as a field in the CSR of the STC Formatter. 6. STS. Displays the data as device status fields of the CSR. 7. IRP. Displays the data as an address of the I/O Request Packet, as an unsigned hexadecimal number. 8. IOFN. Displays the data as an I/O function. 9. PID. Displays the username of the PID encountered. 10. LONG. Displays a longword as a hexadecimal number. 11. WORD. Displays a word as a hexadecimal number. 12. BYTE. Displays a byte as a hexadecimal number. A pseudonym description is used to display a special string with the printed number. The format of a pseudonym description is sizetype No blanks are allowed within this format. Size by be LONG, WORD, or BYTE. Type may be HEXADECIMAL, DECIMAL, or OCTAL. Both may be shortened to one character. When used, the corresponding value in the TRACE entry is displayed as a number of the size and type specified with a display of the string between the angle brackets next to the number. B.3.2 Sample Format Data File The following is a sample format data file. B-3 THE STC TRACE FACILITY 1 ! MT_ctrl_init : 2 UCB WH ! MT_unit_init : 3 LH LH ! TM_cancelio : 4 IRP UCB LH IOFN LH ! TM_startio : 5 WH BH ! Fdispatch : 6 BH ! Testr : 7 WH WH ! Fatalerr : 999 LONG LONG LONG LONG ! Who knows? : If the following TRACE entries were found in the TRACE buffer | | +----------+ | 1 | <-- Controller Init TRACE identifier a | g | 2 | <-- Unit Init TRACE identifier d | r | 80088F80 | <-- UCB address d | o | 0 | <-- Unit number r | w | 4 | <-- Start I/O TRACE identifier e | t | 8001EEF0 | <-- IRP address s | h | 80088F80 | <-- UCB address s | | C | <-- I/O function V | C | <-- I/O function | 9DE0 | <-- UCB status +----------+ | | You would get a display of . : MT_ctrl_init : : MT_unit_init : : UCB = 80088F80 ucb$w_unit = 0 TM_startio : : IRP = 8001EEF0 UCB = 80088F80 irp$l_func = C IOFN = C READPBLK ucb$l_sts = 9DE0 . : B.3.3 Command Format The format of an interactive command is COMMAND parameter-1 parameter-2 ... Blanks separate the command and parameters. The command string need only be typed up to the point that uniquely identifies the command. Parameters are additional information that may be required by some commands. B-4 THE STC TRACE FACILITY B.3.3.1 Command Description - The following paragraphs describe the set of commands known to the debugger. B.3.3.1.1 COPYIO - The COPYIO command copies driver information and the driver TRACE buffer into the debugger buffer. B.3.3.1.2 COPYDMP - The COPYDMP command reads in a dump file, TRACE$DUMP by default, that contains a TRACE buffer. The dump file can be produced by the following sequence of commands in SDA SDA> SET OUTPUT dump-file-spec SDA> EXAMINE range-of-TRACE-buffer For example, if the TRACE buffer is 400 (hexadecimal) bytes long, located at 17A (hexadecimal) bytes off the DDT, 80088F80, of the driver, you would enter the following commands SDA> SET OUTPUT [my_area]driver.dump SDA> EXAMINE 80088F80 + 17A : 80088F80 + 17A + 400 You can actually use symbol offsets SDA> READ stc$exe:MTDRIVER.STB SDA> SET OUTPUT [my_area]driver.dump SDA> EXAMINE mtdriver + trace$w_len : mtdriver + trace$w_len + 400 To read in the dump file using TRACE $ ASSIGN [my_area]driver.dump TRACE$DUMP $ RUN trace$exe:TRACE TRC> COPYDMP or TRC> COPYDMP [my_area]driver.dump B-5 THE STC TRACE FACILITY B.3.3.1.3 DUMP - The DUMP command copies and displays the driver information and driver TRACE buffer. The specification for the display format is defined by the file TRACE$FORMAT. Further display control is possible be setting display variables. These variables are defined in the section that describes the SET command. Information that can be displayed is 1. DDB. Displays information from the driver DDB block. 2. TRACE. Displays the driver TRACE buffer. 3. UCB. Displays unit and device information. 4. ALL. Displays all the information in the debugger buffer. B.3.3.1.4 REDUMP - The REDUMP command redisplays the information already in the debugger buffer. New driver information and the driver TRACE buffer are not copied into the debugger buffer. The old information is preserved and can be reviewed. This command accepts the same parameters which DUMP accepts. B.3.3.1.5 SET - The SET command resets display format variables. The variables are WIDTH, CONTROLLER, UNIT, and OUTPUT. For example, if you entered TRC> SET CONTROLLER B TRC> SET WIDTH 132 TRC> SET OUTPUT sys$print Subsequent displays from DUMP or REDUMP would only show device information from controller B at 132 characters per line on the device SYS$PRINT. The defaults for CONTROLLER and UNIT are all controllers and units. The default for WIDTH is 80 and for OUTPUT is SYS$OUTPUT. B-6 THE STC TRACE FACILITY B.3.3.1.6 SHOW - The SHOW command displays the values of the display format variables. You can show WIDTH, CONTROLLER, UNIT, OUTPUT, TIME, and ALL. B.3.3.1.7 DCL - The DCL command is an interface to VMS. A single or a group of DCL commands can be executed as a sub-process. The format is either TRC> DCL command or TRC> DCL $ . $ : $ (commands) ! DCL commands $ . $ : $ ^Z ! Control-Z or empty line B.3.3.1.8 HELP - The HELP command will spawn a DCL HELP command to access the debugger help file TRACE$HELP. B.3.3.1.9 EXIT - The EXIT command exits the debugger utility. B.3.3.1.10 QUIT - The QUIT command exits the debugger utility. B.3.3.2 Command Summary - B-7 THE STC TRACE FACILITY The following is a command summary of the debugger utility. COPYIO COPYDMP dump-file (Default: TRACE$DUMP) DUMP ALL (Default: ALL) DDB UCB TRACE REDUMP ALL (Default: ALL) DDB UCB TRACE SET WIDTH (Default: 80) CONTROLLER (Default: ALL) UNIT (Default: ALL) OUTPUT (Default: SYS$OUTPUT) SHOW ALL (Default: ALL) WIDTH CONTROLLER UNIT OUTPUT blank DCL command (Default: DCL mode) EXIT QUIT B-8