FIELD SERVICE SOFTWARE ASSISTANCE BROCHURE The New England District PDP-8 DIAGNOSTIC SYSTEM Version 5 March 1981 Developed by: Rick Moore This document describes the FIELD SERVICE PDP-8 DIAGNOSTIC SYSTEM developed by the 12 Bit Group of New England District Support. It is imperative that users of this system fully understand that this service is provided by the New England District Support Team and is not to be construed as a commitment to the continual support of the system. It is a convienence only and in no way is meant to be a replacement for normal DEC diagnostic procedures. Please remember that new diagnostics are always being released. When the packs are created, the latest versions are included, but the ultimate responsibility for keeping your pack up to date is yours. A special thanks is extended to Dick Murphy of Western Region Software Support for his contributions to this latest version of the Diagnostic System. Dick wrote several of the utilities included such as the modified version of CCL, RXREAD, the RKB0 System Device handler that is bootable, the RX01/02 compatable floppy handlers, the BYTE mode handlers, and developed the disk recovery techniques described herein. SYSTEM OVERVIEW This Diagnostic System is essentially an OS-8 system. It has been slightly modified; special utilities have been added; it has features designed to assist the Field Service Engineer; it contains diagnostic tools; it has customized batch streams to manipulate files; and it is extensively documented; but it remains, never-the-less, OS-8. Most of the rules that pertain to OS-8 apply to this system as well. If you are at all familiar with OS-8 and DECX8 as they come from the SDC, a glance at the system directory shows some disparities. In particular, notice that the extensions ".DG", ".BX", ".BH", ".SY", and ".X8" are different. During the development of this system, it was decided to leave as much of the file manipulation required when creating systems on various media to "Batch Streams", a computer controlled process. There was a need to identify the various types of files to this process, therefore all diagnostics, which are really files in image format (.SV) are given the extension ".DG". The consequences of renaming all ".DG" files to ".SV" would be the loss of this batch ability. Renaming all ".BX" files to the standard ".BN" (as they are really binary format files) would cause even more problems since DECX8 has been modified to accept this default extension. In fact, the program DECX8.SV that appears on this system is a modified version in that it allows building on a PDP-8A or VT-78 with no switch register. Descriptions of other system conventions appear later in this text. There are two companion documents to this text; one concerning the building and use of DECX8, and another which addresses the OS-8 operating system in more detail. Both of these documents list specific DEC publications which may be referenced if even more detail is desired. At this time, it must be understood that OS-8 is an operating system that Digital sells for a considerable amount of money. It is not in our best interest, therefore, to leave copies of it laying around customer sites for free. Besides, this system has been modified and contains many utility programs that are not supported by Digital. In addition, the monitor and CUSPs (ie: PIP,FOTP,BATCH,etc) are the DEK versions that are distributed with the Device Extension Kit for the KT8A and memory above 32K. Were these to be mixed with the original V3D components that most customers run, the resulting operating system would experience failures due to version incompatability. If you feel the urge to leave a Diagnostic Pack on a customer site, be sure to create one using the command: .SUB CUSPAK This batch stream will create a bare bones copy of your pack with only the monitor, basic utilities, and diagnostics on it. DO NOT use any of the copy utilities to make a site pack! BOOTING the SYSTEM This system can be booted via the regular OS-8 bootstraps for the appropriate media. For the RK05, additional bootstraps are available that allow booting to any drive; "A" or "B" area. These are: Normal Any Drive "B" area ______ _________ ________ 30/ 6743 25/ 7604 27/ 1032 5031 6746 6743 6743 5031 7604 6260 5031 put drive # in SR bits 9,10 In addition, there is a program called "RKBOOT" that will allow any combination of the above to be run. For example: .R RKBOOT/ [dev] where [dev] can be 0 = RKA0 B = RKB0 1 = RKA1 1B = RKB1 When the system is initially booted, it may display a message on the terminal that highlights some of the features of the system. This feature is of importance to new users only and after a degree of comfort with the system is gained, the user may disable it. This is accomplished by issuing the commands: .SET SYS INIT HELP - enables startup message .SET SYS NO INIT - dissables message Regardless of the setting, the message may be printed at any time by typing: .HELP and more information may be gained by asking for: .HELP INFO and/or .HELP MORE LOADING DIAGNOSTICS The main purpose of this system is to provide a means of loading and running diagnostic programs that are located on the distribution media (disk, diskette, or DECtape). All diagnostics are identified by a unique six character (ie: DHRKCH) Maindec name and a two character extension. This system uses the extension ".DG" to identify a diagnostic program. Most of the more commonly used diagnostics are located on the "SYS:" or "RKA0:" area of the disk, although some of the more infrequently used ones are on the "RKB0:" area. To run a diagnostic, type: .R PROG.DG where "PROG" is the name of a diagnostic to be run from "SYS:" - or - .RUN RKB0: PROG.DG runs one from "RKB0:" For example, to run the RK8E Data Reliability test: .R DHRKCH.DG To run the CM8F Card Reader Test (which is on RKB0:) .RUN RKB0:DHCMAA.DG NOTE: The OS-8 system accepts input in UPPER CASE only. Be sure that the "CAPS LOCK" key on the terminal is depressed. RUNNING DIAGNOSTICS Once a diagnostic has been loaded, it will run normally,or as though it had been loaded via paper tape. It should be be noted that many (indeed most) of the newer diagnostics have been ammended to implement a "Software Switch Register" for the benefit of those systems that have no front panel switch register such as the PDP-8A and the VT-78. In these cases, the program will identify itself, then print: SR = 0000 and wait for the operator to input the desired switch register value. On these diagnostics, it is possible to enable or disable this feature by altering the contents of the following two locations: Loc Software Hardware ___ ________ ________ 21 0000 4000 22 0400 0000 These alterations may be made by using either the front panel switches if the processor is a PDP-8E, etc. or ODT if not. For more information on ODT, see the section on Advanced Techniques. ADDING NEW DIAGNOSTICS to the SYSTEM Place the new paper tape diagnostic in the PC04, then type: .LOAD PTR: ^ type a .SAVE SYS: PROG.DG where "PROG" is a six character name followed by a ".DG" ext. this new diagnostic can now be run by typing: .R PROG.DG HELP FILES This system has a file of "Help" messages that pertain to various programs, procedures, and diagnostics. This feature is used by typing: .HELP [foo] where "foo" is the name of the file, program, diagnostic, or procedure for which you desire help. For example: .HELP types the startup message .HELP INFO gives more system information .HELP FUTIL tells about the File UTILity program .HELP RK05 lists available RK05 diagnostics .HELP DIAG lists all diagnostics on the system The default output of HELP is to the terminal but can be sent to whichever printer is defined as "LPT:" by typing: .HELP [foo] - L For example: .HELP DIAG - L lists all the available diagnostics on the line printer. LISTING DIRECTORIES To list a directory, type: .DIR or to list the directory of the "SYS:" device .UA .DIR RKB0: or to list the directory of "RKB0:" .UB .DIR - L prints the directory of "SYS:" on the printer .DIR /E=4 - L prints same but in 4 columns across the page .DIR RKB0:/E=4-L etc., etc. BATCH STREAMS The "Batch Streams" that are located on the system allow the user to perform complicated file manipulation without knowing all the neccessary commands for "PIP" and "FOTP". They are accessed by the "SUBmit" command and are: .SUB CUSPAK to make a customer site diagnostic system .SUB RLPACK makes an RL01 diagnostic system .SUB FLOP1 a diagnostic diskette for VT78, 8A, 8E CPUs .SUB FLOP2 a diagnostic diskette for RX01/2, RK05, RL01/2 .SUB FLOP3 a diagnostic diskette for VTs, LAs, LPs, etc. .SUB FLOPX8 the DECX8 builder diskette .SUB TC08DG a TC08 diagnostic DECtape .SUB TC08X8 a TC08 DECX8 system .SUB TD8EDG a TD8E diagnostic DECtape .SUB TD8EX8 a TD8E DECX8 system These files can be identified on the system by the ".BI" extension. The floppies are made using the BYTE mode handler for more space, although this is transparent to the user. You MUST have the system device "WRITE ENABLED" to run Batch ! SYSTEM CONVENTIONS Extensions: .SV - system programs .BN - binary files .BH - binary handlers for BUILD .DG - diagnostic programs .SY - system heads .HN - compiled device handlers for .SET HANDLER .BI - batch control files .HL - "help" files .TX - text files .BX - DECX8 builder modules .X8 - customized DECX8 system exercisers .BA - Basic source files Devices: SYS: - the system device, also usually called DSK: - the default device; in the case of this pack RKA0: - the "A" area of RK05 Drive 0 RKB0: - the "B" area of RK05 Drive 0 RKA1: - the "A" area of RK05 Drive 1, etc. RL0A: - the "A" area of RL01 Drive 0 RL0B: - the "B" area of RL01 Drive 0 RXA0: - RX01/2 Drive 0 RXA1: - RX01/2 Drive 1 RXB0: - RX01/2 BYTE mode Drive 0 DTA0: - DECtape Drive 0 for TD8E or TC08 DTA1: - DECtape Drive 1 for TD8E or TC08 PTR: - PC04 reader PTP: - PC04 punch TTY: - the console terminal LPT: - the LP05, LA180, LQP8 line printers Some of these devices are initially enabled on the system when it is created. However, by using the program "BUILD", the system may be tailored to fit your particular hardware environment. Your attention is called to the section on SYSTEM CONFIGURATION before attempting any such action. Notice that handlers for both the LA180 and LQP type printers are called "LPT:" and TC08 and TD8E DECtapes are called "DTA0:". There are also two types of floppy handlers. These different types cannot be co-resident. The "SET HANDLER" command allows swapping of these handlers without going through the build process. More information on this is in the section on SYSTEM CONFIGURATION. All of the standard DEC handlers for all supported devices are included on the "RKB0:" area of the disk and can be added if the need arises. Examples of these are the RL01, RF08, and Card Reader handlers. USEFUL UTILITIES Some of the more useful utility programs that exist for your benefit are: RXREAD.SV - This program will allow you to check for defective floppys. It can be a big help in a "System vs. Bad Diskette" situation. When the program encounters a bad block, it prints out the error in a very definitive manner and even allows for a limited correction attempt. Before attempting to correct a bad block on a customer's diskette, BE SURE to get his approval! A successful recovery may not fix bad data, but at least the bad data can be read by the operating system and the diskette copy utilities will work again. More info on this utility can be gained by typing "HELP RXREAD". RKCOPY.SV - A disk copy utility that copies between any two drives and verifies the copy. Since this is a sector by sector image copy, it can be used to copy any PDP-8 operating system such as OS8, Typeset, or COS300. Total time to copy and verify is less than 90 seconds. RKUTIL.SV - This program is a very good RK05 utility that allows you to format, read check, copy (with verify), and run a 8 pattern disk confidence test (much like RSTS/E DSKINT). The later test is especially adapt at finding weak disks that format or copy with no errors. There are also disk alignment routines, but a much more comprehensive program exists for that purpose called ... ALIGNX.DG - This program is an RK05 Alignment Utility that allows the user, via either the hardware front panel switches, or a "software switch register" to completely align an RK05 Disk Drive. It will work with either an RK8E Controller (up to 4 drives) or the CSS RKS8E Controller (up to 8 drives). A simple one word patch defines the controller which is defaulted to the RK8E. More info on ALIGNX is available by listing the file on RKB0 called "ALIGN.TX". This documents a step by step alignment procedure developed by the New England District Support group. CONVRT.SV - This is an "un-saver" program that makes Binary Paper tapes from ".SV" or ".DG" programs. The most common use of this would be to make a paper tape of a diagnostic to take to a site that has no mass storage media. The tape can be read in with a PMK-01 reader using Binary Loader. Although the High Speed Punch is the default output for this program, it responds to any legal Command Decoder line. "HELP CONVRT" will get you more info. ADVANCED TECHNIQUES The information in this section is intended for advanced users of OS-8. It is not neccessary to be familiar with any of it in order to successfully utilize the Diagnostic System as it is distributed. However, anyone desiring to increase their OS-8 skills is encouraged to experiment; it is the best way of learning. It would be a wise idea to back your system up by using either "RKCOPY" or program 0 of "RKUTIL" before attempting any experimentation since most of this information, if improperly applied, can be fatal to the system! First, we should clear up some fine points on the "R", "RUN", and "GET" commands. Associated with each memory image file (.SV or .DG) is a block of data called the Core Control Block or CCB. The CCB is a table of information containing the program's starting address, areas of memory into which the program is to be loaded, and the programs Job Status Word or JSW. The JSW contains certain flags that affect OS-8 operations which, for the purposes of this discussion, are irrelevant. When a program is loaded, the starting address and JSW are read from the CCB and saved in memory. The CCB itself is saved in the last 200 (octal) words of block 37 on the system device unless the program was loaded with the "R" command (as opposed to the "RUN" or "GET" commands). This is a very important distinction that becomes apparent when we get to the section on "BUILD". Remember, "RUN" and "GET" save the CCB, "R" does not. This is because the purpose of the "R" command is to load and start execution of a program on the system device, not to alter it in any way. ALTERING PROGRAMS (ODT) The Octal Debugging Technique or ODT is a means in which temporary or permanent "patches" or alterations can be inserted into a program. One use of this could be to enable the software switch register option in some diagnostics. It can also be used to type in a short "toggle in" routine on a system that has no front panel switches. Example: Enable the software switch register on DHRKCH.DG .GET SYS DHRKCH.DG - first we must have a runable copy of the desired program in memory .ODT - involk ODT 21/ 4000 0000 - change location 21 from 4000 to 0000 (note that the computer prints out the "old" value and waits for the "new" value to be typed in.) 22/ 0400 0000 - change 22 from 0400 to 0000 ^C - type a C .SAVE SYS DHRKCH.DG - resave the program However, it is not neccessary to resave the program in order to run it if the patch is temporary. Before typing the C : 200G - starts execution of the program at location 200 This is just one of many possible uses of ODT. For a complete description of the Octal Debugging Technique, see the OS-8 System Reference Manual (AA-H607A-TA), Chapter 19. SYSTEM CONFIGURATION (BUILD and SET HANDLER) BUILD is the system generation program that allows you to use simple commands to manipulate the device handlers that make up the OS-8 peripheral configuration. Before starting to use BUILD, make sure that the system is write enabled and that ".SET SYS NO INIT" is in force. .RUN SYS BUILD starts the build process. Note the use of the "RUN" command. This allows resaving later. $ the "$" is BUILD's prompt character at this time, execute any of the BUILD commands neccessary to reconfigure the system, then type: $BOOT to reboot the system with the new handlers active. The system responds SYSTEM BUILT . and you are back in the monitor. At this time, it is possible to run and the new handlers will stay in force until the next time BUILD is run. The present configuration of BUILD may be saved by typing immediately upon return to monitor: .SAVE SYS BUILD Some of the commands that may be used to change the system configuration are: ALter - patches locations in a handler BOot - reboots the new monitor to the system device DElete - deactivates a handler DSK = - specifies the default device (usually = SYS) INsert - activates a handler LOad - loads a binary handler module from a device PRint - lists all handlers presently LOaded into BUILD UNload - removes a loaded handler from BUILD NAme - changes name of a device type All of the device handlers supplied with OS-8 are located on RKB0: and may be LOaded into BUILD and then INserted. However, only 15 devices may be active at any one time, so it may be neccessary to DElete something in order to have room. While BUILD must be run whenever you wish to change the system device, it is now possible to swap handlers without going through the build procedure. The "SET HANDLER" command allows substitution of non-system device handlers within the monitor. The command is of the form: .SET HANDLER [old name] = [new name] for example .SET HANDLER LPT = LQP changes the device name "LPT:" to reference the LQP8 printer instead of the LA180/LP05 printer. It is now possible to get output such as a directory listing or a HELP file directly on the LQP printer by involking the "- L" switch. For example: .DIR - L (or) .HELP [foo] - L To restore the system to its original state: .SET HANDLER LQP = LPT Other handler pairs that are available in this system are: FLOP (RX01/2) and BYTE (special floppy handler) TD8E and TC08 DECtape controllers LPT (LP05) and LQP (LQP8) printers The program "RESORC" will tell you which handlers are active in your system at any time. This program is accessed with the ".RES" command. For more information on BUILD, read the OS-8 System Reference Manual (AA-H607A-TA), Chapter 9. FLOPPY "BYTE MODE" HANDLERS The diagnostic floppies use a special "BYTE Mode" handler that allows over 600 blocks of data on the diskette (as opposed to the normal 494). These floppies run on the standard hardware with no modifications, but there are some differences that the user should be aware of. When the "BYTE" handlers are resident, these floppies are addressed as "RXB0:" and "RXB1:" instead of "RXA0:" and "RXB0:". Naturally, there is an exception to this rule. The program RXCOPY and the DUPLicate command have their own internal parsing and require the use of RXA0 and RXA1 exclusively. Don't let this worry you, it copies BYTE mode floppies just fine! If you are merely running the BYTE mode diskettes as the booted system device and running diagnostics or games from drive 0, the special handler is completely transparent to the operation. Just ignore the fact that it exists. This is the case for 95% of the applications. However, if you are trying to use BUILD to create such a diskette, you must first run the BUILD program, BOot to the new system device, run a special RXFIX program, and then proceed as normal. RXFIX must be run again before BUILD can be run again from that diskette. If all of this seems confusing, think of RXFIX as a software flip-flop; it is flipped to become a bootable medium and flopped to enable BUILD to run. If you don't ever intend to create your own BYTE mode diskettes, just forget about the whole thing, use the preconfigured diskettes, and be thankful for the extra space! By the way, the "FLOP" Batch streams that create the diagnostic diskettes use this method, so interested parties can examine them to help decipher the technique. PACK RECONSTRUCTION TECHNIQUES The remainder of this text addresses means of recovering from fatal "pack crashes". Since most "crashes" or "wiped out packs" result from either faulty hardware (we work on a lot of that!) or amateur programming efforts, it is possible with a degree of housekeeping disipline, to protect the pack from total fatality. Most hardware failures occur when the pack is loaded on a bad system and booted. Since the drive loads the heads onto cylinder 0, this is usually the damaged area. Cylinder 0 contains 40 (octal) blocks (of 256 words) which contain the device bootstrap, the RKA0 directory, and most of the OS-8 monitor (of 70 blocks). Therefore, if there were a way to replace the monitor and the directory, the pack could be salvaged. The following technique, once understood, can be used to reconstruct "wiped out" systems. Rememeber also that this involves a certain amount of periodic housekeeping chores in order to be effective. RECOVERING the SYSTEM HEAD There are several files located on the system that have ".SY" extensions. These are copies of the OS-8 monitor areas for various devices. For example, the system area for RKA0 is "RK8EA.SY" and for a floppy is "RX8E.SY". These files were created with "PIP" option /Y and can be replaced in a similiar manner. If a system area were to become corrupted, but the disk could somehow be accessed, it would be possible to recopy a new sytem area onto it. To do this: .R PIP *RKA0: