.Title DUCM - DU Multi-Unit Internally-Queueing Handler et alii .; 27-Apr-86 .; 10-Aug-86 Include Peter Miedecke's documentation as first half. .; 23-Sep-86 Update to V2 .; 23-Oct-86 V2a .; 10-Dec-86 V2b - DUCM allows "hidden" block I/O; WA may run unmapped. .; Addition of /D in DUCM programme section. .; 20-Feb-87 V2c - Addition of timeout facility; correction of bugs in .; serious error code .; 19-Apr-87 V2d - bug fix in timeout code; restrict timeout EMT to .; job 1 under TSX-plus .; 27-Aug-87 V2e - bug fix in P.STS testing code, as died on RQDX?. .; 6-Feb-88 V3 - Add MSCP bypass; remove SETs under TSX-plus. .; 17-Jun-88 V3a - Fix problem with initialization time-out. .; 5-Dec-88 V3b - Make initial call to RETIME at fork level, so that it .; doesn't upset getting queue elements away in the .; handler initialization. .; Make /D set all job units for DU6 & DU7. .; 1-Jan-89 V4 - Rewrite of front half of DU handler to make up for a .; TSX V6.31 bug where two elements (? possib more) .; could be handed to the handler at a time. .; WA suitable modified also. .; 23-Apr-89 V4a - Allow changing of all unit/partitions if job 1, so can .; set up multiple DU handlers from TSX without messing .; around with RT start-up files (special for SEQEB!). .; .; Make Unit Size SPFUN (SP.USZ) return the size of the .; unit relative to the partition specified in the .; request - ie the number of blocks available using .; physical I/O specifying this unit. .; 23-Jul-89 V4b - Tidy up bug in crash code, where after 10 disastrous .; controller errors the handler would start to scribble .; past the end of one of its internal tables. .; Add extra code to interrupt-faking sections, when the .; handler is mapped under TSX-plus, to add the extra .; stack values which get added in a mapped handler .; interrupt under TSX-plus. .; 22-Aug-89 V4c - Add /W to change units 6 & 7 for all jobs if job 1 under .; TSX; Repair bug in /D code; make time-out 10 seconds .; again. .; 13-Jan-89 V4d - Add ability to change the boot device name (with /d/v) .; 21-Jan-89 V4e - Fix bug where /D did not update boot unit/partition .; table. .; 11-Apr-90 V5 - Add COMPARE SPFUNs; fixes in SJ code; add fix for .; strange Emulex SC03 bug; make timeout 15 seconds .; to cope with 60Hz clocks making it a bit less. .; 22-Aug-90 V5a - Add option for SPLIT assembly: allows disc partitions .; to be split into several logical units. This has .; been implemented in a fairly primitive fashion, .; but I hope it will be adequate for the intended .; purposes. .; 26-Oct-90 V5c - Add more sophistication for SPLIT usage; remove .; necessity for handler to be loaded when running .; it at a programme (except for /C switch, which .; has no meaning if the handler is not loaded!) .; .; Add the DUCMIN mini-handler, for really tight .; systems. .; Add ability to get size of any physical unit on .; a controller (/S:n) .; Make it necessary to specify /B with /D if BYPASS .; should be altered, rather than getting it every time. .nhy .ps 60,75 .subtitlechapter .fg 10 .c;DU (MSCP) Handlers allowing TSX-Plus to use Large Discs .s 3 .c;DUCM Version V5c, 25-Oct-90 .s 5 Author: Chester Wilson, Charleville 4470, Australia. .s 4 As with all DECUS software, these programmes are distributed on an "as is, where is" basis. The author is interested in any bugs or problems, but makes no committment of any sort as to the maintenance of this product. .s 3 This manual contains three parts: .s .nf (1) Users' Guide (2) DUCM Manual (V5c) (3) WA (D0, D1 etc) Manual (V3) .s .f The Users' Guide should be sufficient reading to use these handlers, or for non-technical readers. For fuller details, see parts (2) _& (3). .page .c;Table of Contents .s 3 .nf USERS' GUIDE .s 1.1 Introduction 1.2 Disc Usage 1.3 Changing Handler Settings 1.3.1 Examples 1.4 TSX-Plus System Generation 1.5 Creating More Handlers 1.6 Modifying TSX .s 3 DUCM MANUAL ITSELF .s 2.1 Introduction 2.2 Update History 2.3 SET Commands 2.4 SPFUNs 2.4.1 Error Code I/O 2.4.2 Partition Table I/O 2.4.3 Partition Size 2.4.4 Unit Size 2.4.5 Status Table 2.4.6 Physical I/O 2.4.7 MSCP Bypass 2.4.8 Comparison SPFUNs 2.5 TSMUNG - Modifying TSX 2.6 Assembly Options 2.7 Running DUCM as a Programme 2.7.1 Examining _& Modifying the Handler in Memory 2.7.2 Examining _& Modifying the Handler on Disc 2.8 SPLIT Assembly - for Splitting Disc Partitions 2.9 DUCMIN mini-handler 2.10 Error Messages .s 3 WA - A MUNGING HANDLER FOR LARGE DISCS .s 3.1 Introduction 3.1 How it works 3.2 SET Commands 3.3 Running WA as a Programme 3.4 Restriction on /U _& /P 3.5 Setting Up 3.6 Safety Precautions _& Recommended Use 3.7 Example of Command File .s 3 INDEX .Chapter Users' Guide .x User's Guide .hl 1;Introduction. .s 2 These handlers allow large discs to be fully used under TSX-Plus. With the normal DEC or S#_&#H DU handlers a maximum of 256 Megabytes can be used. .s Four handlers are supplied: DUCM.TSX, D1.TSX D2.TSX and D3.TSX. These enable discs with a total capacity of 1024 Megabytes to be supported. More disc capacity can be handled - see "Creating More Handlers". .s These handlers consist of a primary handler, DUCM.TSX, that manages the disc controller, and the first 256 Megabytes of storage, and the secondary handlers D1,D2 and D3.TSX that allow the user access to the storage beyond this. The use of multiple handlers is the means of getting around the limitation of 8 units (each 32 megabytes) per handler imposed on any device handler by RT-11/TSX-Plus. .s NOTE THAT DUCM.TSX IS &N&O&T A COPY OF THE NORMAL TSX-Plus DU HANDLER SUPPLIED BY S#_&#H, DU.TSX. ONLY DUCM.TSX CAN BE USED WITH THESE "LARGE DISC" HANDLERS. It IS however designed to be used as a REPLACEMENT for DU.TSX. .s These handlers are delivered pre-configured for two 512 Megabyte drives. You may reconfigure them as shown below. .page .hl 1;Disc Usage. .s .x Disc Usage .x Limitation on RT disc storage RT-11 and TSX-Plus communicate with large MSCP discs by dividing them up into a number of "disc partitions". This is because the operating system refers to a disc by means of 16 bit blocks numbers - therefore 64K 512 byte blocks (32 Megabytes) is the maximum that can be referred to as a "logical unit". You use discs larger than 32 Megabytes by breaking them up into a number of 32 Megabyte "Partitions", each of which is referred to as a physical unit - i.e. DU0:, DU1:, DU7: etc. However, as their are only 8 units allowed per controller, with the present handlers you can only use a disc of 256 Megabytes (8 times 32 Megabytes), i.e.:- .s .macro t1 drive,part,descrip{ .lj 5;drive .lj 25;Part .lj 40;descrip } ..t1 Drive, Partition, Addressing Range (Megabytes) ..t1 , (Octal), ..t1 ,, ..t1 DU0:, 0, ##0-#31 ..t1 DU1:, 1, #32-#63 ..t1 DU2:, 2, #64-#95 ..t1 DU3:, 3, #96-127 ..t1 DU4:, 4, 128-159 ..T1 DU5:, 5, 160-191 ..T1 DU6:, 6, 192-223 ..T1 DU7:, 7, 224-255 .s 2 As you can see, each handler allows 256 megabytes of disc space to be used. This group of 256 megabytes may be on one physical drive or spread across a number of drives. .s For discs larger than 256 Megabytes, we add another handler (D1). Therefore D1 refers to:- .s ..t1 Drive, Partition, Addressing Range (Megabytes) ..t1 , (Octal), ..t1 ,, ..t1 D10:, 10, 256-287 ..t1 D11:, 11, 288-319 ..t1 D12:, 12, 320-351 ..t1 D13:, 13, 352-383 ..t1 D14:, 14, 384-415 ..T1 D15:, 15, 416-447 ..T1 D16:, 16, 448-479 ..T1 D17:, 17, 480-511 .s In the examples below we have four disc handlers to cater for 1024 Megabytes on two physical drives. .page .hl 1;Changing Handler Settings. .s .x Setting up Handlers We recommend that you change these setting by running the handler as a programme, and that you ONLY do this under RT-11. From version 3, the SETs have been removed from the DUCM handler if build for TSX-plus, for safety. You may use SETs on the secondary handlers D1, D2, and D3.TSX. .s .i 4 _.R D1.TSX (also D2.TSX, D3.TSX etc) .s The following options are available:- .s .macro t2 Option,descr{ .lj 5;option .lj 25;descr } ..t2 Option, Description .s ..t2 /H, Type help text .s ..t2 /L, List the current values in internal tables .s (in the following switches, "unit" is one of the handlers logical units. It must be a single digit in the range 0 - 7.) .s ..t2 unit/U:n, Specify the PHYSICAL unit number to which this ..t2 , logical unit refers. .s ..t2 unit/P:nn, Specify the PARTITION to which this logical ..t2 , unit refers. Append a "." to make the partition ..t2 , number decimal rather than octal. .s ..t2 /R, If "/R" is included in any command line, the logical ..t2 , unit is set to be READ ONLY. .s More options exist, full details may be found in chapter 3, the "WA Handler" documentation. .hl 2;Examples. .macro t3 example,descr{ .lj 2;example .lj 25;descr } ..t3 _.R D1.TSX, Run the driver under RT-11 .s ..t3 *4/U:3/P:1,Associate D14: with physical unit three ..t3 , partition 1 .s ..t3 *0/P:2/R, Associate D10: with physical unit zero ..t3 , partition 2 READ ONLY .s ..t3 *1/P:10., Associate D11: with physical unit zero ..t3 , partion 10. (12 octal) .page Here is an example of how to set up enough logical discs to be able to use the disc capacity of a controller with two Fujitsu Eagles - 2351's (400 Megabytes formatted each) .s The primary handler is set up so that the units D00: to D07: correspond to partitions 0 to 7. Do not alter these settings. .s Set up the second handler. ..t3 , ..t3 _.R D1.TSX, Run the second handler ..t3 *0/U:0/P:8., unit zero part 8 ..t3 *1/U:0/P:9., unit one part 9 ..t3 *2/U:0/P:10., unit two part ten ..t3 *3/U:0/P:11., unit three part eleven ..t3 *4/U:0/P:12., unit four part eleven (this last partition ..t3 , is not the full 32 megabytes - 64K blocks) ..t3 *_^C, .s This covers the first Eagle - D00 through D07 and D10 through D14 now refer to the 13 (decimal) 32 Megabyte partitions on the disc. .s 2 Now for the second Eagle. Set up the third handler:- ..t3 , ..t3 _.R D2.TSX, Run the third handler ..t3 *0/U:1/P:0, Start with unit zero part zero.... ..t3 *1/U:1/P:1, now unit 1 part 1 ..t3 *2/U:1/P:2, two ibid ..t3 *3/U:1/P:3, three and so forth ..t3 *4/U:1/P:4, four ..t3 *5/U:1/P:5, five ..t3 *6/U:1/P:6, six ..t3 *7/U:1/P:7, seven ..t3 *_^C, .tp 10 ..t3 , ..t3 _.R D3.TSX, Run the fourth handler ..t3 *0/U:1/P:8., unit zero part eight ..t3 *1/U:1/P:9., unit one part nine ..t3 *2/U:1/P:10., unit two part ten ..t3 *3/U:1/P:11., unit three part eleven ..t3 *4/U:1/P:12., unit four part twelve (this last partition ..t3 , is not the full 32 megabytes/64K blocks) ..t3 *_^C, .s And this is it. We now have 26 (decimal) logical units. God Bless TSX-Plus and all who sail upon her in large discs! .page .hl 1;TSX-Plus System Generation .s .x TSX System Generation Determine the number of 32 megabyte units you need for your configuration. As you can see from the example above, you need one handler per 8 units. Create enough handlers by copying D1.TSX. Remember DUCM.TSX is the handler that talks to the controller. You only have one of these per controller, but you can have as many "Large Disc Handlers" as you want. .s Edit TSGEN.MAC to include as many large disc handlers you require. They are specified as:- .s .i 10;DEVDEF ,MAPH,DMA,HANBUF .i 10;DEVDEF ,MAPH,DMA,HANBUF .I 10;DEVDEF ,MAPH,DMA,HANBUF .I 10;DEVDEF ,MAPH,DMA,HANBUF .s 2 You must copy DUCM.TSX across to your system so that it becomes DU.TSX: .s .i 20;_.copy ducm.tsx sy:du.tsx .hl 1;Creating More Handlers. .s The four handlers discussed above were copied as follows: .macro hc h1,h2,h3{ .lj 5;h1 .lj 20;h2 .lj 40;h3 } ..hc ,, ..hc Handler, Created From, Comments ..hc ,, ..hc DU.TSX, DUCM.TSX, The actual MSCP handler ..hc ,, ..hc D1.TSX, WA.TSX, Large disc Handler - first copy ..hc ,, ..hc D2.TSX, WA.TSX, Large disc Handler - second copy ..hc ,, ..hc D3.TSX, WA.TSX, Large disc Handler - third copy .s 2 You may create more. There is a command file LGSET.COM. It creates the handlers as above, and then sets them up for two 512 Megabyte drives. You may wish to edit this file for your own use. .page .fg 8 .hl 1;Modifying TSX .x Modifying TSX .x TSX Modification It is possible to run the DUCM DU handler "mapped". This saves low memory space, allowing your system to handle more jobs. To do this you must use the TSMUNG programme on your TSX.SAV or it will not allow the DU handler to be mapped. This programme is provided on this distribution. .s .i 10;_.Run TSMUNG SY:TSX.SAV .i 10;Successful TSX Modification .i 10;_. .s If you do this, you must NOT try to run using the DEC or S#_&#H DU handlers (the system will fail to start TSX-plus). .Chapter DUCM Manual Itself .x DUCM Manual .hl 1;Introduction DUCM is designed to speed multi-user DU use, notably under TSX-plus. TSGEN.MAC should be set up to allow DU to be mapped into high memory, as this conserves almost 1k of low memory. [Problem: with V6.01 this requires munging of TSX.SAV due to a new restriction - see TSMUNG later in manual.] .s 8 This document describes DUCM V5c, 25-Oct-90. The use of versions earlier than V1g on TSX+ V6 or later can lead to system crashes on heavily loaded systems, and versions earlier than V4 on TSX+ V6.31 can lead to lost queue elements if the spooler is active. .page .hl 1;Update History .x DUCM Update History Changes from V1 to V2 of DUCM: .s 2 (1) SPFUNs 377 and 376 (read _& write respectively, returning status) are now supported; .s (2) SPFUN 372 (DEC's partition table I/O) has been included - see details especially re RT V5.4 _& later in manual. .s (3) SPFUNs 361 _& 362 have been removed, being replaced by 372. .s (4) SETs are no longer allowed under TSX. .s 3 V2 to V2a [23-Oc-86] .br Bug fix which caused odd corruptions or crashes on rare occasions especially under heavy swapping. .s 3 V2b [8-Dec-86] .br Allow "hidden" block (block 65535) between partitions to be accessed. Fix bug where couldn't run DUCM as a programme under RT11 (don't give RT11 a .gval with a byte address!). Add /D option to allow setting up a handler without using monitor SETs. .s 3 V2c [20-Feb-87] .br Addition of time-out support; correction of bugs in serious error code. [This was added to track down a controller bug, but appears to be worth general inclusion. The ability to cause a pseudo disc timeout by running DUCM and using the /Z switch, which is capable of crashing systems, may be thought by some to be inadvisable. If so, assemble without timeout support!] .s 3 V2d [19-Apr-87] .br Repair a bug in timeout code where it was checking the wrong location to see whether there was a request being processed. Make the pseudo-EMT for timing out work only from job 1 (usually the CTY) on TSX-plus. .s 3 V2e [27-Aug-87] .br Bug fix in testing P.STS for errors: caused funnies getting device size on RQDX? board. Can anyone tell me why this board returns 20000 in this word? .s 3 V3 [6-Feb-88] .br Addition of MSCP Bypass. Completely remove SETs if built for TSX. NOTE: The code used by dec for getting the buffer address for the MSCP bypass buffer supplied by the user in the WCNT argument has restrictions, as this handler has not yet been modified for use with the AT (address translation) handler. Use of this requires that the user not change his PAR mapping for this buffer until the request has been completed. .s The STATU$ word has been added to the DUCM handler, as per the DEC DU handler, at . See DEC documentation for the use of this. The error table report now includes this word. .s .x Restriction - hardware bug .x Hardware bug restriction .x Bug - Hardware -> restriction There is an odd restriction in this version of DUCM. The SRQD11-A of Webster Computer Corporation has a bug inasmuch as if any of a series of blocks is read, that block number being in a range a little above the actual available length of the disc, an error is caused which causes all reads to return in error until a block from the first track is read. The code to get around this follows RWMSG: in the handler, and is commented. Unless you get rather a huge number of bad blocks, there should be no problem with the slight delay this code introduces. .s 2 V3a [17-Jun-88] .br A time-out error during initialization failed to realize that the element to return was not yet in the active queue, and consequently hung the system (thanks Chris Kleinschmidt!) .s 2 V3b [5-Dec-88] .br Make initial call to RETIME at fork level, so that it doesn't upset getting queue elements away in the handler initialization. This caused problems with TSX V6.31. .s Make /D change default for DU6 and DU7 for ALL jobs, not just job 0 (thanks Ralph Zwier!) .s 3 V4 [1-Jan-89] .br Rewrite of much of earlier part of handler to get round nasty TSX bug where multiple elements could be passed to a handler. NOT a pleasant task! .s 2 V4a [23-Apr-89] .br Allow changing of all unit/partitions if job 1, so can set up multiple DU handlers from TSX without messing around with RT start-up files (special for SEQEB!). .s Make Unit Size SPFUN (SP.USZ) return the size of the unit relative to the partition specified in the request - ie the number of blocks available using physical I/O specifying this unit. .s 2 V4b [23-Jul-89] .br Correct bug in disastrous error code, where after 10 disastrous controller errors the handler would write crash information past the end of one of its internal tables. .s Decrease time-out to 5 seconds (from 10 seconds). .s Add code to more accurately mimic TSX-plus mapped handler interrupts in the internal pseudo-interrupt code (stacks PAR5, #340, and a special return address). .s 2 V4c [22-Aug-89] .br Correct bug in /D code, where /D/V reset the IP register address but not the SA register address. .s Make time-out 10 seconds again, as occasionally get this time-out for unknown reasons, and 10 seconds reduces the number of these. .s Add /W switch to allow setting of all job units 6 _&/or 7 under TSX from job 1. .s 2 V4d [13-Jan-90] .br Add code to allow changing the boot device name. Note that TSX boots via RT-11 and therefore the boot code in a TSX handler is never used. Thus it does not matter what name is used - it only matters for RT-11 systems. Where there several DU controllers it is necessary to have extra handlers - DU, DV, DA, DB or whatever. If the boot device name is not properly set up, on a hard boot (or a boot/foreign) the bootstrap will search for DU.SYS instead of the desired handler. .s 2 V4e [21-Jan-90] .br Repair bug where /D did not update the boot unit/partition table. .s 2 V5 [11-Apr-90] .br Add Comparison SPFUNs [302 (normal) and 303 (physical)]. Add fix for strange behaviour of Emulex SC03 controller (can still blow up if you access a non-existent unit when the controller is heavily loaded with requests: set unused logical units to an extant physical unit with an impossible partition value, and all goes OK). Fix problem for RT SJ where _^C reset can leave a string of elements in limbo (again still occasional problems probably due to RT SJ pseudo-handling of FORKs - however it takes quite a bit of thrashing to cause problems now). Make timeout 15 seconds, to allow for those funny 60Hz clocks actually making it a bit shorter in some far-off places! .s 2 V5a [22-Aug-90] .br Add SPLIT assembly ability. .s 2 V5c [26-Oct-90] .br Add more sophistication to the SPLIT option, including auto-partition (/A) and double-precision offset (/2). .s Make the UNIT SIZE spfun accept an argument (the block number), which, if non-zero, causes this spfun to return the double-length size of the unit numbered . .s Make it necessary to add /B if it is desired to change/examine the BYPASS characteristic of the handler with /D, rather than asking for it regardless. .s Include the DUCMIN handler. This is about as small a functional MSCP handler as I could make, for really tight systems. It is 356 words long in the FB/SJ version, though it has the ability to split discs into software partitions. .page .hl 1;SET Commands .x DUCM SET Commands .x SET Commands - DUCM This is a single-port handler only, but can cope with multiple units on that port. The DEC commands .s .i 8;_.SET DUx UNIT=n .i 8;_.SET DUx PART=m .i 8;_.SET DU VECTOR=vvv########and .i 8;_.SET DU CSR=ccc .s are valid if used under RT-11. SETs are NOT permitted under TSX-plus on the DUCM handler itself, as TSX-plus conveniently rewrites that handler over itself. This is generally helpful, but with DUCM it causes loss of queue element information and kills the system. .s The SET DU PORT command merely returns an error message. .s An additional pair of commands allow the restriction of the MSCP Bypass facility where it is felt that it could be used in ways detrimental to the system: .s .i 8;_.SET DU NOBYPASS##########and conversely .i 8;_.SET DU BYPASS .s 2 Unit and partition values may be altered under programme control. These values will not be retained across a reboot or other re-load of the handler. Under RT-11 any logical unit may have its logical unit or partition altered, but under TSX-plus this is restricted to DU6 and DU7. Separate parameters are kept under TSX-plus for units 6 _& 7 for each job, the units DU0 through DU5 being common to all jobs. [They can only be set up by a SET command issued under RT-11]. .s If the handler is run as a job, it allows the user to examine the current partition table, and to alter the partition table as above. It also allows a handler to have its units and partitions set up for a different system, without having to use monitor SETs. .s 3 .x SETs for DUCM (under RT-11 only) As from Version 3, it is not possible to perform any SETs for DUCM.TSX even if it renamed to something else (eg XX.SYS) under RT-11. .s The setting of DUCM parameters has been much simplified from version 2b on. This is done by running the DUCM handler as a programme, and using a /D switch - see section 2.7. .lm 0 .page .hl 1;SPFUNs .x Error Code SPFUNs .x SP.RIO SPFUN .x SP.WIO SPFUN .hl 2;Error Code I/O (SP.RIO 377, SP.WIO 376) Read _& write returning error codes (SPFUNs 377 _& 376 respectively) have been implemented. These use the buffer address and word count as per normal I/O, but return a status word in the first word of the buffer (which therefore must be one word longer than the specified word count). This is used for bad block replacement purposes in RT-11 from version 5.4 on. Without it, DUP from the 5.4 release kit will not work. .s [Note that a negative word count causes either of these two SPFUNs to function as the other. This appears to be a feature... !] .s The error returns are: .lm 16 .i -8;100000 (_& carry clear): no error - normal return .i -8;100002 (_& carry clear): error which recovered upon retry .x Bad Block Replacement Error .i -8;100200 (_& carry set): BBR bit has been set for this block (no retries attempted) .i -8;177777 (_& carry set): I/O error occurred on this request and did not recover on retry .lm 0 .hl 2;Partition Table I/O (SP.DAT 372) .x Partition Table SPFUN .x SP.DAT SPFUN SP.DAT (372) which reads or writes the partition table has been implemented, with variations. .s .lm 8 .i -8;(1) Under TSX-plus, only units 6 _& 7 may have their units or partitions changed by use of this request, unless this request comes from job 1 (allowing special setting up for multiple computer systems). [Normally the read/write request form of this SPFUN has a word count argument of 1 or -1 respectively. If a value (octal) of 100000 is used from job 1 under TSX, the values for units 6 _& 7 will be reset for ALL jobs, rather than just job 1.] .s .i -8;(2) As this is a single-port handler, any value entered in the PORT byte will be taken as a high-order value for PARTITION. You will need a BIG disc to be able to use this! .s .x RT Partition Table .x V5.4 Partition Table .i -8;(3) RT-11 changed the format of the partition table. From version 5.4 onward there are two additional words at the start of the partition table: <.rad50#/DU/> and <.word#8.>. The DUCM handler checks which version of RT it is being run under (or which version of RT that TSX appears to be) and returns (or uses) the appropriate partition table format. .lm 0 .hl 2;Partition Size (SP.PSZ 373) .x Partition Size SPFUN .x SP.PSZ SPFUN .x Size of Partition SPFUN The partition size SPFUN is the same as that for the DEC DU handler. .hl 2;Unit Size (SP.USZ 300) .x Unit Size SPFUN .x SP.USZ SPFUN .x Size of Unit SPFUN This SPFUN returns unit size (rather than partition size) in two words in a manner analogous to SP.PSZ (373). The first word receives the high-order value of the size. .s From V4a on, the length returned is from the start of the partition to the end of the unit. Thus if the logical unit specified is partition zero, the full size of the corresponding physical unit will be returned. If the logical unit corresponds to partition 1, the size returned will be the physical unit size less 65536, or one partition. The size returned is the number of blocks which may validly be accessed on that logical unit using the physical I/O SPFUN (SP.PIO). [If the hendler is built with the SPLIT option, the value returned will additionally be less the OFFSET value for that logical unit.] .s From V5c on, the block number may be used to determine which physical unit to return the size of. If the block number is zero, this spfun functions as above. If the block number is non-zero, the physical unit whose size is returned is . For example, to determine the size of physical unit 3, provide a block number of 4. [This of course means that the size of the physical unit 65535 cannot be obtained using this spfun - sorry!]# The value returned using this version of the UNIT SIZE spfun will not have any partition or offset value subtracted from it: it will always reflect the total size of the physical unit. .hl 2;Status Table (SP.STS 363) .x Status Table SPFUN .x SP.STS SPFUN .x Version Number This has been included as a primitive form of error logging. This returns a table in the form: .s .nf 1 word (du.ver) Version Number (currently 206 octal) 1 word No. of init's performed successfully 1 word No. of retries performed in init'ing 1 word No. of bloody disasters (SA negative) 1 word No. of AVAIL errors 1 word No. of IO retries 1 word No. of IO errors 1 word No. of double-linked requests 1 word STATU$ word: status of last disc operation 1 word No. of Time-outs 2-word pairs (maximum of 30.) IP/SA pairs for each time-out. .s This was included mainly for debugging, but has not been removed. It has been extended to include the time-out support in V2c and the status word in V3, and the number of double-linked requests in V4. .f .hl 2;Fake Time-Out (SP.FAK 200) .x Fake Time-Out SPFUN .x SP.FAK SPFUN .x Time-Out Fake SPFUN For testing the time-out system a maintenance SPFUN, SP.FAK (200) has been included. This causes a fake disc time-out. When it is used, the block number must be set to 100000 or the SPFUN is ignored. It is ignored if DUCM is not assembled with time-out support. .s Under TSX-plus, for safety, this request must be made from job 1 (usually the CTY primary line). .page .hl 2;Physical I/O (SP.PIO 301) .x Physical I/O SPFUN .x SP.PIO SPFUN .x Absolute I/O SPFUN [For an alternative under TSX-plus, see associated WA handler and its documentation - chapter 3 of this manual.] .s Due to the restriction in RT-11 that normal I/O may only access 65565 blocks on any individual unit, and DU devices can extend rather dramatically beyond this limit, a means has been provided to allow simple access to a larger block number: .s SP.PIO is for physical rather than logical I/O. It allows a 24-bit block number, but only allows reading or writing whole blocks. This is done by using the Word Count word of the queue element as follows: .s .lm 16;.i -8 High-order byte: number of blocks to transfer (negative if write, positive if read, zero seek [useless]); .i -8 Low-order byte: high order eight bits of block address. [This byte does NOT change sign in a write!] .lm 0 .s 2 Note that physical I/O will use the UNIT parameter of whatever logical DU was selected, and adds the PARTITION parameter of that specified logical unit to the high-order word of the block number. [This was changed with DUCM V3; previous versions returned an error if the partition number was not zero.] The number of blocks available on a particular unit for access by physical I/O may be obtained by use of the unit size SPFUN (SP.USZ) [from V4a on]. .s If you are using an Emulex SC03 controller, take heed of the warning (under Update History) to set unused logical units so that they access an extant physical unit but use an impossible partition value. Otherwise accessing non-existant units at times of heavy disc use can crash the controller and sometimes the system. .x Emulex SC03 warning .s Thus: .nf .SET DU3 UNIT=2,PART=0 will allow physical I/O on DU3, starting at block 0, and .s .SET DU3 UNIT=0,PART=2 will allow physical I/O on DU3, starting at block 131072. .f .s 2 .lm 0 As an example of use of physical I/O, on the next page is a copy of the testing programme used with this handler: .s .i 4 [Note: .SPFUN area,channel,function,buffer,wordcount,block] .page .nf .lit .Title PIOTST - for testing physical I/O capability of DU: .Nlist bex,toc,sym .Enabl lc,gbl ; Must be assembled with CMAC, and linked with CVLLIB .mcall .csigen,.wait,.spfun sp.pio=301 ;Physical I/O SPFUN area: .blkw 7 ;General EMT area limit: .limit ;So we keep track of memory hlimit: 0 ;ibid (unused as yet) buffer: .blkw 256. ;I/O buffer defext: .rad50 / / ;Default extensions for CSIGEN Start:: .csigen limit+2,_#defext ;Find which device we want to read. mov r0,hlimit ;New memory limit after handlers loaded. .wait _#3 ;Did he specify a device? bcc s1 ;Yes - use it. type >;No - just tell him which version. br start s1: type > call rn2t ;Read double-precis number into R2/R3 ;(octal, decimal. or 0hex) tstb tlinb ;Check for null line in TT input buffer beq start ;If so, try for a different device. mov _#<1 * 400>,r5 ;1 block to read - <.byte 0,1> bisb r2,r5 ;Add in high-order block number ;(R3 has low-order block number) .spfun _#area,_#3,_#sp.pio,_#buffer,r5,r3 bcc s2 type > br s1 s2: type > mov buffer,r0 ;Show him the first word call w8t ;(in octal, to the terminal) call tcrlf ;Append a type > ;(Probably folly to allow him to alter?) call rnt ;Read single-precision number tstb tlinb ;If null line, don't alter anything. bne s3 type > br s1 s3: mov r0,buffer ;If he means it, alter it mov _#<-1 * 400>,r5 ;Write 1 block (negative = write) bisb r2,r5 ;High-order block number again. ;(R3 still has low order) .spfun _#area,_#3,_#sp.pio,_#buffer,r5,r3 bcc s1 type > br s1 .end start .eli .f .page .hl 2;MSCP Bypass Spfun .x Bypass - MSCP .x MSCP Bypass .x JREAD .x JWRITE .x IGTDUS Before DUCM V3, it was considered that to allow MSCP Bypass operation on a multi-user system such as TSX-plus was potentially dangerous. However, DEC are using this in the JREAD/JWRITE and IGTDUS subroutines, and to fail to allow it may limit the use of programmes designed for the use of this. .s Both the old (371) and the new (360) values for the BYPASS SPFUN are allowed. .s There is one restriction: the user's MSCP buffers must be 60 (octal) bytes long. This is the same size as DEC use, both in their handler and in the abovementioned subroutines, so there should be no problems. .s For higher security, the bypass option may be disabled. Under RT-11 this may be done by the command .s .i 8;_.SET DU NOBYPASS .s (to re-enable, use SET DU BYPASS), .s or through the use of the /D/B switches under TSX-plus, running DUCM.TSX as a programme [section 2.7]. .hl 2;Comparison SPFUNs .x Comparison SPFUNs .x SPFUNs for Direct Comparison In V5 two new SPFUNs were added, to enable direct use of the MSCP ability to directly compare data in user buffers with data on discs, without having to read then compare. This was added to enable the SAVRES disc save/restore programme to operate faster: however this is rather controller dependent. (The Webster controllers SRQD11-A and SRQD11-B are a case in point: on the SRQD11-A these commands provide a considerable speed advantage; on the SRQD11-B they are actually slower than using the computer itself to do the comparison!) .s SPFUN 302 operates as per a normal read or write, returning an error if the comparison failed (or if there were an I/O error). There is no way of returning the details of that error: if you need specific details (or even to check whether it is a comparison error or a disc read error) you will then need to perform a normal read and compare. .s SPFUN 303 is analogous to SPFUN 302, except that it uses the physical I/O abilities as per 2.4.7 rather than normal I/O block addresses. .page .hl 1;TSMUNG - for modifying TSX plus .x TSX Modifying .x Modifying TSX .x TSMUNG - For Modifying TSX .x Mapping DU Handler .x Mapping DY Handler With the advent of TSX-plus version 6, no matter what is specified in the TSGEN file (eg DEVDEF ,MAPH,HANBUF,DMA) TSX refuses to allow the DU (or the DY) handler to be mapped into high memory. This is fine to protect people trying to do this with DEC or S#_&#H handlers, but is a nuisance when we have a legitimate handler capable of mapped performance. .s A programme TSMUNG is provided. This modifies the default values set up for the DU (and optionally the DY) device. It is run, using the name of the TSX.SAV file to be modified appropriately. .s 2 To allow DU to be mapped, append /U to the filename. To allow DY to be mapped, append /Y to the filename. [No switches implies /U] .s .nf .i 8;_.Run TSMUNG .i 8;*sy:tsx.sav .i 8;Successful TSX modification .i 8;_. or .i 8;_.Run TSMUNG sy:tsx.sav .i 8;Successful TSX modification .i 8;_. .f .s 3 If it should be desired to run the DY handler mapped in addition to the DU handler (WARNING - again, make sure your handler is capable of being run mapped and is not the standard DEC or S#_&#H handler), append a /Y and a /U to the filename. For example: .s 2 .i 8;_.Run TSMUNG du:tsx.sav/y/u .i 8;Successful TSX modification .i 8;_. .s 2 (Merely specifying DU:TSX.SAV/Y will allow the DY handler to be mapped but NOT the DU handler.) .s 3 If TSMUNG cannot find the relevant string of device names in TSX, it will tell you so. If this is the case, you are probably trying to operate upon a version of TSX different from that for which TSMUNG was written (versions 6.01 through 6.2). .page .hl 1;Assembly Options NUMBER OF JOBS: .s .x Number of Jobs under TSX .x Jobs under TSX .x TS$JOB As TSX-plus now allows more than 32 jobs (and has a whole word set up in the queue element for the job number!), the number of jobs allowed for in the DUCM partition table is now an assembly parameter. .s The parameter is "ts$job", with a default value of 50 (decimal). .s It is defined such that a prefix file with a different value will override the definition within DUCM. .s 3 UNIBUS SYSTEMS: .s .x Unibus System Restriction Normally DUCM is set up to allow use of the WA handler to access multiple units and partitions of large discs. This can only be used under Q-bus systems (as under unibus systems the word used for passing partition and unit information across to DUCM is used for the unibus mapping register value). .s If you are using a unibus system, you will need to assemble DUCM with a prefix file containing .s .c;$XLINK=0 .s for safety. This suppresses the WA code linkage. .page .hl 1;Running DUCM as a Programme .x Running DUCM as Programme .x Programme use of DUCM .x Changing Partitions _& Units (DU) The handler may be run as a programme (R DU.TSX, or R DU.SYS). The format of this has been changed from earlier versions to allow multiple DU handlers on large systems. When run, it expects a normal CSI-style command string, with a device name (of a DU-type device - using the DUCM handler) and switches as necessary. .s From V2b on, it also allows a user to set up the partition table, CSR and vector within a handler file itself. This allows a user to set up a handler for another system without having to use monitor SET commands, with all their complications. .s .nf Switches available are shown by use of the /H switch: .s _.Run DUCM.SYS */H */h DUCM Internally-Queueing Multi-Unit DU Handler V5c 25-Oct-90 .s Switches available are: .s /B:ON or /B:OFF - Allow or disallow MSCP Bypass facility /E Type the error table /L Type the current units and partitions /S Type the size of the device by partitions /C:n Change the partition/unit for logical unit n (6 or 7 only if TSX unless job 1) used with one or both of the following two switches: .s /P:n Partition number /U:n Physical unit number .s /H Type this message /D Modify partitions _& units in disc handler, not memory (may only be used with /L, /V and /X - if used with /V allows alteration of CSR _& vector. /X Exit after performing relevant task. /W On TSX, allow /C to change units 6 _& 7 for ALL users. /Z Cause a false disc timeout. .s * .s 2 An unknown switch types the following message: .s ?DU-E-Illegal switch /x. For help type /H .s 2 .hl 2;Examining _& Modifying the Handler in Memory To see the size of a particular DU device: .s .x Size of DU Unit .x Getting Size of DU Unit _.R DU.SYS *du:/s Total unit physical size (starting at specified partition) = 622676 .s 9 partitions each of 65535 blocks 1 partition of 32852 blocks *_^C .tp 17 .s or, say to get the size of physical unit 2 (in DUCM V5c onwards): .s _.R DU.SYS *du:/s:2 Total unit physical size (starting at specified partition) = 622676 .s 9 partitions each of 65535 blocks 1 partition of 32852 blocks *_^C .tp 17 .s 2 To type the current units and partitions: .s .x List Current DU Partitions .x Current DU Partition Listing _.R DU.SYS *DU:/L Details of Handler in Memory: .s Logical Physical Partition Unit Unit 0 0 0 1 0 1 2 0 2 3 0 3 4 0 4 5 0 5 6 0 6 7 0 7 *_^C .s 2 .tp 13 To examine the error table: .s .x Error Table - Examining (DU) .x Examining Error Table (DU) .x Version Number (DU) _.R DU.SYS *du:/e Version Number: 206 Number of successful INIT's: 1 Number of retries on INIT's: 0 Number of INIT timeouts: 0 Number of bloody disasters: 0 Number of AVAILABLE errors: 2 Number of I/O retries: 2 Number of I/O errors: 0 # double-linked requests: 0 Value of STATU$ word: 0 Number of Time-out errors: 0 *_^C .s 2 .f It is possible to change the physical unit or partition value for logical unit 6 or unit 7 under TSX, or those of any unit under RT-11 (at your own risk if you change those of the system device!). This is done using the /C switch, in conjunction with /P (for partition number) and /U (for physical unit number). [From V4a on, a user on job 1 under TSX may change any unit. Altering units 0 through 5 affect everyone using the system, and altering units 6 and 7 usually only affect his job. From V4c on, if /W is added to the command line however, changing unit 6 or 7 is also global across the system. BE WARNED: this is designed for start-up only; if used while users are actually using unit 6 or 7 it will change their value on the fly!). For example, to change unit 6 to partition 3 on unit 2: .s .nf _.R DU.TSX *DU:/C:6/P:3/U:2 .s .f If the partition requested does not exist, the user will be informed. Under TSX-plus, only the DU unit (6 or 7) for the particular job (except at per the last paragraph) will be altered. [Under TSX-plus, the associated WA handler is recommended for safer and more consistent access in large systems.] .s 3 .hl 2;Examining _& Modifying the Handler on Disc (DU) .x Disc Handler - Modifying _& Examining (DU) .x Changing the DU Handler on Disc .x Partition Table - Changing DU Handler on Disc From Version 2b of DUCM on, a provision has been made for altering the physical unit _& partition table in a disc copy of a handler, without having to use monitor SETs. This provides considerable convenience in setting up handlers for systems other than the one being worked upon. The vector and the CSR may also be altered in this way. .s To examine the contents of the physical unit _& partition table in the handler being run as a programme, use the /D switch with the /L switch. .s To alter the contents of the physical unit _& partition table in the handler being run, use the /D switch alone. .s .x CSR Alteration (by running DUCM as programme) .x Vector Alteration (by running DUCM as programme) .x Boot Device Name Alteration (by running DUCM as programme) .x Name for Boot Device Alteration (by running DUCM as programme) To alter the CSR, vector and/or the name which will be used on a hard boot from the particular device, as well as the unit _& partition tables, use both /D and /V. .s 2 Examples: .s .nf _.RUN DUCM.SYS */d/l DUCM Internally-Queueing Multi-Unit DU Handler V5c 25-Oct-90 .s Details of DUX Handler on Disc: .s Built for TSX-plus .i 8;Includes device time-out support .s Vector: 154 CSR: 172150 Bypass allowed. .s Logical Physical Partition Unit Unit 0 0 0 1 0 1 2 0 2 3 0 3 4 0 4 5 0 5 6 0 6 7 0 7 .s .f To alter this table, use the /D switch alone. Add /B if you also wish to check or change the ability to use MSCP bypass. Instructions will be typed: .nf .s .tp 23 _.RUN DUCM.SYS */d/b############[Change partitions _& bypass] .s To alter the partition/unit table in the handler being run as a programme, enter three decimal numbers separated by spaces: respectively the logical unit number (0 through 7), then the corresponding physical unit number and partition number. When finished, type a blank line. .s > 0 0 0 > 1 1 0 > 2 2 0 > 3 3 0 > 4 4 0 > 5 5 0 > 6 6 0 > 7 7 0 > .s [For a TSX handler, from version 3b on, a change to unit 6 or 7 sets the default for ALL jobs, as DU6 and DU7 have a separate entry for each job on the system.] .s For the Bypass option, answer ON or OFF to allow or disallow the use of this facility on your system. (A blank line leaves it as it is.) .s Bypass is currently ON ON or OFF? OFF .tp 22 */d/l############[List details only] DUCM Internally-Queueing Multi-Unit DU Handler V5c 25-Oct-90 .s Details of DUX Handler on Disc: .s Built for TSX-plus .i 8;Includes device time-out support .s Vector: 154 CSR: 172154 Bypass disallowed. .s Logical Physical Partition Unit Unit 0 0 0 1 1 0 2 2 0 3 3 0 4 4 0 5 5 0 6 6 0 7 7 0 */x _. .s 2 .tp 24 _Run ducm.tsx */d/v############[Change vector, CSR, boot name, _& partitions] The present Vector _& CSR addresses will be typed. Enter the new values or merely a carriage-return if you do not wish to change that value. .s Vector [154]: 160 Control _& Status Register [172150]: 172154 .s Name of Device (for Boot Purposes) [DUX]: DV .lm 10 .f [Note that TSX boots via RT-11 and therefore the boot code in a TSX handler is never used. Thus it does not matter what name is used here - it only matters for RT-11 systems. Where there are several DU controllers it is necessary to have handlers named DU, DV, DA, DB or whatever. If the boot device name is not properly set up, on a hard boot (or a boot/foreign) the bootstrap will search for DU.SYS instead of the desired handler.] .lm 0 .nf .s To alter the partition/unit table in the handler being run as a programme, enter three decimal numbers separated by spaces: respectively the logical unit number (0 through 7), then the corresponding physical unit number and partition number. When finished, type a blank line. .s >################[Did not want to change partitions] .s */x .f .page .hl 1; SPLIT Assembly for Splitting Disc Partitions If DUCM.MAC is assembled with a prefix file containing the definition SPLIT=1, a version of DUCM is produced which can split discs up into a number of logical units. .s If you only have a small disc, it may be more useful to split it into a system portion and a data portion, without the use of logical discs. If you have a larger disc, it may still be that the 65535 block partition size is inconveniently large, or that you are left with an inconveniently small portion of disc left over after the partitions have been allocated. .s For these reasons the SPLIT option was devised. It allows discs (on the one controller) to be split by software into up to 8 partitions, each accessable via a normal RT-11 logical unit. .s These software units do not have to be related to the well-known 65536-block DU "partitions". They may be within these partitions if desired; alternatively they may span across partition boundaries. .s There are two extra switches which may be used when this flavour of the handler is run as a programme. /2 allows partition and offset values to be combined into one double-precision number. /A requests automatic setting up of the offset values, using the size values provided for each logical unit. Examples of the use of these are included below. .s Each of these units has the following parameters: .s .lm 10 .nf (1) logical unit number (0 through 7) (2) physical unit number (3) partition value (4) offset (from block 0 of partition) (5) size .s .i -10;It is possible to combine (3) and (4), using a /2 switch (v.i.): .s (1) logical unit number (0 through 7) (2) physical unit number (3) double-precision offset (from block 0 of disc) (4) size .s .lm 0 .f The size of a logical unit is specified in blocks. A value of zero implies a full partition size of 65536. .s A couple of restrictions/oddities came to the fore: .s .lm 8 .i -4 (1) Under TSX-plus, there is no separate DU6: and DU7: partition for each job - all jobs access the same partitions. .i -4 (2) The /C switch is invalid with the split DUCM handler. .i -4 (3) Determination of logical unit size requires some consideration. If neither size nor offset is provided, then merely the partition is used, as per the non-split handler. If a size is provided, then that size will be used. This is NOT checked! If an incorrect size which would allow overwriting across logical disc boundaries is provided, then two logical units may access the same portion of disc - NOT recommended! .s A size of zero implies 65536 - ie a whole partition. .s If the sizes and offsets are correctly set up however, DUCM will check during operation that I/O may not extend beyond logical unit boundaries. .s .i -4 (4) In one way this version of the handler has an additional safety feature. In MSCP discs, at the end of the available user space, come the replacement bad blocks. While normally the RT-11 file system provides some protection against writing in the area beyond the end of a file, it is left to the handler to intercept writing beyond the end of a device. .s The normal DU handlers do not check for this, as they do not actually keep an internal table of logical unit sizes. .s The split version of DUCM keeps such a table, and will check to prevent any access outside the size limits of a logical unit. .lm 0 .s 3 It is recommended that a command file be kept on unit 0, partition 0 of any disc using the SPLIT facility. This command file should run the handler and set up the handler appropriately. This will allow for easy resetting - eg new versions of the handlers, or transferring discs across machines. [Note: it is worth setting up the command file so that changes to the handler are made before any attempt is made at access which requires explicit or implicit loading or unloading of the handler. This is because the load and unload code accesses the CSR for the disc, and if the handler has not been properly set up before one tries to use it, whatever controller is at 172150 will be zapped! Make the changes, REMOVE the handler, INSTALL it again, then run it and use /A to adjust the final values for the partitions. See example below.] .s 2 The series of examples which follows will, hopefully, provide sufficient information for people to be able to use this facility. .page .nf Examples: (not easy, but worth following through!) .s 3 Demonstration of setting up a split DUCM handler. The example system has two units on the controller, units 0 and 1. .s !Take a copy of the DUCMS split handler: _.copy ducms.sys dv.sys .s !Run it as a programme: .s _.run dv.sys .s !First example: set up physical unit zero, partition zero to contain !three logical discs, the first starting at block zero, 6000 blocks !long; followed by one 20000 blocks long, then another 39535 blocks !(taking up the rest of that partition). ! !On physical unit 1, provide two units (3 & 4), dv3 being 30000 blocks !long, and dv4 being the remainder of partition 0, physical unit 1: .s */d .s To alter the partition/unit table in the handler being run as a programme, enter five decimal numbers separated by spaces: respectively the logical unit number (0 through 7), then the corresponding physical unit number and partition number, the starting offset and the size. When finished, type a blank line. .s > 0 0 0 0 6000 > 1 0 0 6000 20000 > 2 0 0 26000 39535 > 3 1 0 0 30000 > 4 1 0 30000 35565 > * .s !Now have a look at the result (in following examples we'll remove the !headings): .s */d/l DUCM Internally-Queueing Multi-Unit DU Handler V5c 25-Oct-90 (built for cope with splitting of disc partitions) .s Details of DU Handler on Disc: .s Built for RT-11 FB/SJ Monitor .s Vector: 154 CSR: 172150 Bypass allowed. .s Logical Physical Partition Offset Size Unit Unit 0 0 0 0 6000 1 0 0 6000 20000 2 0 0 26000 39535 3 1 0 0 30000 4 1 0 30000 35565 5 0 5 0 0 6 0 6 0 0 7 0 7 0 0 * .s 2 !Next example: each of the physical units is actually 131648 blocks !long - enough for two 65536 block and one 576 block partitions. !Split unit zero into five units: 6000, 3 x 40000, and 1 x 5648 block !units. Leave unit 1 as per standard partitioning: .s */d .s To alter the partition/unit table in the handler being run as a programme, enter five decimal numbers separated by spaces: respectively the logical unit number (0 through 7), then the corresponding physical unit number and partition number, the starting offset and the size. When finished, type a blank line. .s > 0 0 0 0 6000 > 1 0 0 6000 40000 > 2 0 0 46000 40000 > 3 0 1 20464 40000 > 4 0 1 60464 5648 > 5 1 0 0 0 > 6 1 1 0 0 > 7 1 2 0 0 > .s !Confirming this: .s */d/l .s Logical Physical Partition Offset Size Unit Unit 0 0 0 0 6000 1 0 0 6000 40000 2 0 0 46000 40000 3 0 1 20464 40000 4 0 1 60464 5648 5 1 0 0 0 6 1 1 0 0 7 1 2 0 0 * .s !That jumble of numbers comes from the 65536-block partitioning. To !see it in a more readable manner, add the /2 switch, to combine the !partition and offset values into one double-precision number: .s */d/l/2 .s Logical Physical Offset Size Unit Unit 0 0 0 6000 1 0 6000 40000 2 0 46000 40000 3 0 86000 40000 4 0 126000 5648 5 1 0 0 6 1 65536 0 7 1 131072 0 * .s !Indeed, using the /2 switch with the /D switch, one can set up the !same thing rather more clearly (for the unit 0 values!): .s */d/2 .s To alter the partition/unit table in the handler being run as a programme, enter four decimal numbers separated by spaces: respectively the logical unit number (0 through 7), then the corresponding physical unit number, the (double-precision) offset, and the size. When finished, type a blank line. .s > 0 0 0 6000 > 1 0 6000 40000 > 2 0 46000 40000 > 3 0 86000 40000 > 4 0 126000 5648 > .s */d/l/2 .s Logical Physical Offset Size Unit Unit 0 0 0 6000 1 0 6000 40000 2 0 46000 40000 3 0 86000 40000 4 0 126000 5648 5 1 0 0 6 1 65536 0 7 1 131072 0 * .s !It gets wearisome working out how much to allocate for the various !units. In addition, there is always the possibility of mistake, !typing in so many numbers. .s !The /A (auto-partition) switch has been added to try to make setting !up of such things more pleasant and safe. Use this with the /D !(and, if desired, the /2) switch: .s */d/a .s To alter the partition/unit table in the handler being run as a programme, enter five decimal numbers separated by spaces: respectively the logical unit number (0 through 7), then the corresponding physical unit number and partition number, the starting offset and the size. When finished, type a blank line. .s > 0 0 0 0 6000 > 1 0 0 0 40000 > 2 0 0 0 40000 > 3 0 0 0 40000 > 4 1 0 0 40000 > 5 1 0 0 40000 > 6 1 0 0 40000 > 7 1 0 0 40000 > Size of unit 0: 131648 Size of unit 1: 131648 .s * .s !Here, we were asked for the size of each unit. As you will see from !the confirmation listing, the partitions have been set up. Note that !any non-extant partitions have been given an invalid partition/offset, !causing an error if use of them should be attempted. .s */d/l .s Logical Physical Partition Offset Size Unit Unit 0 0 0 0 6000 1 0 0 6000 40000 2 0 0 46000 40000 3 0 1 20464 40000 4 1 0 0 40000 5 1 0 40000 40000 6 1 1 14464 40000 7 1 1 54464 11648 .s */d/l/2 .s Logical Physical Offset Size Unit Unit 0 0 0 6000 1 0 6000 40000 2 0 46000 40000 3 0 86000 40000 4 1 0 40000 5 1 40000 40000 6 1 80000 40000 7 1 120000 11648 * .s !It is even possible to have the handler get its own values for the unit !sizes. To do this, a virgin version of the handler is required, not !to do any actual access, but to get the sizes of the physical units: .s *dv:/d/a/2 .s To alter the partition/unit table in the handler being run as a programme, enter four decimal numbers separated by spaces: respectively the logical unit number (0 through 7), then the corresponding physical unit number, the (double-precision) offset, and the size. When finished, type a blank line. .s > 0 0 0 6000 > 1 0 0 40000 > 2 0 0 40000 > 3 0 0 40000 > 4 1 0 40000 > 5 1 0 40000 > 6 1 0 40000 > 7 1 0 40000 > Size of unit 0 is 131648 Size of unit 1 is 131648 .s */d/l .s Logical Physical Partition Offset Size Unit Unit 0 0 0 0 6000 1 0 0 6000 40000 2 0 0 46000 40000 3 0 1 20464 40000 4 1 0 0 40000 5 1 0 40000 40000 6 1 1 14464 40000 7 1 1 54464 11648 .s */d/l/2 .s Logical Physical Offset Size Unit Unit 0 0 0 6000 1 0 6000 40000 2 0 46000 40000 3 0 86000 40000 4 1 0 40000 5 1 40000 40000 6 1 80000 40000 7 1 120000 11648 * .s !There is no reason why the logical units should be in sequence of their !physical units: for example: .s *dv:/d/a/2 .s To alter the partition/unit table in the handler being run as a programme, enter four decimal numbers separated by spaces: respectively the logical unit number (0 through 7), then the corresponding physical unit number, the (double-precision) offset, and the size. When finished, type a blank line. .s > 0 0 0 6000 > 1 1 0 40000 > 2 0 0 40000 > 3 1 0 40000 > 4 0 0 40000 > 5 1 0 40000 > 6 0 0 40000 > 7 1 0 40000 > Size of unit 0 is 131648 Size of unit 1 is 131648 .s */d/l/2 .s Logical Physical Offset Size Unit Unit 0 0 0 6000 1 1 0 40000 2 0 6000 40000 3 1 40000 40000 4 0 46000 40000 5 1 80000 40000 6 0 86000 40000 7 1 120000 11648 * .page Example 2: .s .f This is a sample command file which is used to set up two units on the same discs as used in the previous example: units 0 and 1, with automatic setting of the final values. Note the two-stage procedure! .s .nf !DQ.COM - Set up DQ units ! !(1) Set the details internal to the handler: ! r dq.sys /d/v/2 160 172154 DQ 0 0 0 40000 1 0 0 40000 2 0 0 40000 3 0 0 40000 4 1 0 40000 5 1 0 40000 6 1 0 40000 7 1 0 40000 .s _^C ! !(2) Now use the new handler. While the partitions may not be ! finalized, at least the CSR and vector are right, and we ! can get the size of each of the units automatically. ! remove dq install dq r dq.sys /a _^C !Now all the details will be correct, and we can go ahead ! and use the handler normally. ! !End of DQ.COM .f .page .hl 1;DUCMIN - Miniature DU Handler .x Miniature DU Handler - DUCMIN .x Smallest DU Handler - DUCMIN .x DUCMIN - Miniature DU Handler One of the problems with DUCM is that it has grown - hence it is more useful (as it was indeed designed!) under TSX than under RT. There are applications where however space is critical, and for this purpose the DUCMIN handler was written. .s DUCMIN is a separate source file from DUCM rather than an assembly option. It is not a internally queueing handler, handling only one request at a time. .s To the system it appears actually to be an RK05 controller - so that the DU-specific spfuns (such as special I/O, partition table support) are not available (indeed return errors should they be used). The only spfuns supported are the partition size (373) and unit size (300). The latter is a la DUCM, with the difference that the value returned is ALWAYS the total size of the physical unit. The logical unit's partition and offset values are not subtracted. [This is because the use of this value on the DUCM handler includes physical I/O spfuns, which are not included in the mini-handler.] .s DUCMIN otherwise functions as a SPLIT DUCM handler (see previous section), allowing subdivision of small (or indeed any) discs in a manner which may be sufficient to obviate the use of the LD handler in space-critical systems. .s There is no ability in DUCMIN to change the partition table dynamically; this must be done by running DUCMIN as a programme. .s The size of the DUCMIN handler is 356 words (SJ/FB), and 419 words in the TSX version. .page .hl 1;Error Messages (Alphabetical Order): .fg 1 .x DUCM Error Messages .x Error Messages - DUCM .lm 10 .i -10 ?DU-E-/B must be associated with /D .br A /B without any argument may be used with /D to allow changing of the BYPASS setting of the handler on the disc. [Prior to V5c /D implied /B] .s .i -10 ?DU-E-/B must be either /B:ON or /B:OFF .br If a value be specified for /B, these are the only ones valid. .s 2 .i -10 ?DU-E-/C cannot be used on handler built for split discs .br The /C switch changes the partitioning in the handler currently running in memory. No facility to change this was provided with the SPLIT handler. .s .i -10 ?DU-E-/C out of range 0 through 7 .br The only valid units are DU0 through DU7 (or whatever name the handler was given). The number provided with /C refers to one of these units. .s .i -10 ?DU-E-/C requires /P _&/or /U to effect a change .br If you wish to change the part of a disc that a logical unit accesses, it is necessary to tell it which part of the disc to access. [It would be useful it computers did as we want them to, even if what we tell them to do is something different!] .s .i -10 ?DU-E-/C requires a value (6 or 7 only if TSX unless job 1) .br If you wish to change the part of a disc that a logical unit accesses, it is necessary to specify which logical unit you wish to access that part of the disc by using. .s .i -10 ?DU-E-/C requires handler to be LOADed .br As /C changes the handler in memory, not on disc, if the handler is not loaded with a LOAD command, modifications would only be made on the copy of the handler fetched by DUCM being run as a programme. When another programme accesses a fresh copy of the handler from the disc, any changes would not have been made! .s 2 .i -10 ?DU-E-/D must not have a device specified, .br /D accesses the handler on the disc, not the one in memory. Therefore it is unnecessary (and possibly confusing!) to reference one in the command. .s 2 .i -10 ?DU-E-/E, /C, /P, /U, _& /S may not be used with /D or /A .br The first 5 switches mentioned access the handler in memory. The last two work on the handler on the disc. Trying to mix the two only causes confusion! .s 2 .i -10 ?DU-E-/P must have a value specified .br /P specifies the number of a disc partition, and has no default values. .s .i -10 ?DU-E-/P requires /C to be of any use .br /P specifies the number of a disc partition, to change how that partition may be accessed through one of the 8 available logical units for this device. It is necessary to tell DUCM which logical unit to use. .s 2 .i -10 ?DU-E-/U must have a value specified .br /U specifies the number of a physical disc unit, and has no default values. .s .i -10 ?DU-E-/U requires /C to be of any use .br /U specifies the number of a physical disc unit, to change how that unit may be accessed through one of the 8 available logical units for this device. It is necessary to tell DUCM which logical unit to use. .s 2 .i -10 ?DU-E-/V may only be used with /D .br /V changes the vector used by the device. This may only be changed in the handler on the disc. /D permits changes to the handler on the disc. .s 2 .i -10 ?DU-E-CSR must be even and greater than 160000 .br This is a check against accidental entry of an invalid CSR. .s .i -10 ?DU-E-Cannot Read Status Table .br If this message occurs, you are probably trying to read the status table from a device which is not being driven by a DUCM handler (eg this message will occur if you try to read the error table with /E from a DEC DU handler). .s .i -10 ?DU-E-Cannot determine size of physical unit .br This usually means that the physical unit specified does not exist - eg trying to find the size of unit 1 on a controller which only has one drive connected as physical unit 0. .s .i -10 ?DU-E-Cannot restore status of input file .i -10 ?DU-E-Cannot save status of input file .br You have probably specified a magnetic tape device instead of a DU. .s .i -10 ?DU-E-DU class device not specified .br There are three possibilities: (1) you did not specify any device, when the command switches indicate that one was required; (2) you have specified a device which is not a DU (device identification number 50 octal in .dstatus request), or (3) the device you specified was not recognized by the system (ie .dstatus failed). .s .i -10 ?DU-E-Handler version (nnn) differs from that of programme being run (nnn) .br The version number of the handler in memory is checked to see that it is the same as that of the handler being run as a programme. This is necessary to make sure that the various special spfuns used by DUCM are interpreted properly. .s .i -10 ?DU-E-I/O Error on Handler Block .i -10 ?DU-E-I/O Error on Handler Block 1 .br This indicates a hardware error trying to reset the handler values with /D and/or /B. Is the disc write-locked? If not, you've got trouble! .s .i -10 ?DU-E-Illegal switch /x. For help type /H .br /H will give you a list of the available switches. .s .i -10 ?DU-E-Insufficient memory for Handler Block I/O .br Please try again with a few handlers unloaded, SL set OFF, or any other way of getting yourself a bit more room in memory. .s .i -10 ?DU-E-Logical Unit Numbers must be from 0 through 7 .br The only valid units are DU0 through DU7 (or whatever name the handler was given). The number provided with /C refers to one of these units. .s .i -10 ?DU-E-Non-existent unit/partition specified: unit u, partition p .br When /C is used to change disc access, a check is made to ensure that the requested partition exists on the requested unit. If not, no change is made, and this error message will be typed. .s .i -10 ?DU-E-Only one of any of /C, /P, or /U on any 1 line .br Sorry - a restriction: only one logical unit may be changed on any one command line. [While it would be possible to lift this restriction, it is not onerous, and the work involved would be considerable.] .s .i -10 ?DU-E-Partition table read failed .I -10 ?DU-E-Partition table write failed .br This indicates an spfun error trying to read or write the partition table in the handler. These should never occur ... .s .i -10 ?DU-E-Vector must be from 0-374, and divisible by 4 .br This is a check against accidental entry of an invalid vector. .f .Chapter WA - a Munging Handler for LARGE Discs .x WA - Munging Handler for LARGE Discs .x Handler for LARGE Discs - WA .x Large Discs - WA Handler This section descibes WA version 3, of 29-Dec-88 .s 3 The WA handler provides a fairly rigid way of accessing partitions on a DU disc under the TSX-plus operating system. Each copy of the WA handler installed allows access to a further eight partitions. .s Each of the WA units can be set up (either with SET commands, or by running the handler as a programme) to access any desired unit or partition within the disc. Additionally, it is possible to use WA to access individual disc image files (a la LD). .s Used sensibly, the WA handler can be a boon to a large disc system. Used without due caution, it suffers from the problem of putting a lot of power into careless hands. .s WA must be used with the internally-queueing DUCM DU: handler by the same author. Both the DU and the WA handler (and any copies of the WA handler used to access multiples of 8 units) may be mapped handlers under TSX-plus, though V2 of WA operates with unmapped handlers also. Use with the DEC handler will lead to disc errors or system crashes. Version 2a allows the WA handler to operate unmapped, possibly allowing extra speed for use with streaming magnetic tape at the expense of low memory. .s .x WA Handler - Unibus Restriction It can only be used on Q-bus systems, NOT unibus systems. With the handlers mapped, the processor must be capable of executing the MARK instruction. It cannot be used under RT-11. .s The WA handler is distributed as three handlers: D1.TSX, D2.TSX, and D3.TSX (see the first chapter of this manual). .page .figure 4 .c;Update History .s 3 V2 - initial release. .s 3 V2a [5-Dec-86] .br Allow unmapped WA for speedies mag tape handling .s 3 V2b [8-Feb-87] .br Make I/O past end of file return EOF a la LDs, rather than errors a la disc handlers. .s 3 V 3 [29-Dec-88] .br Allow WA to cope with multiple requests at handler initiation time, to manage nasty bug in TSX V6.31. .page .hl 1;How it works An I/O request passed to the WA handler is modified as appropriate then passed on to the DU handler for actual execution (similar to the LD handler under RT-11). Various details of the I/O request are modified, allowing access to physical units and partitions apart from those accessible by SET commands on the DU handler. .s .x Queue Elements .x Unibus Mapping Register Pointer .x Q$UMRX Offset [The TSX I/O queue element is longer than the RT-11 equivalent. There is a word in it for the address of a unibus mapping register table, q$umrx. This word is used for passing across the physical unit and partition number, one byte apiece. This limits the unit and partition number to a maximum of 255 (decimal), but with present disc hardware this does not appear to be a severe restriction! This is why this handler cannot be used on a unibus system, because this word is then used for its intended purposes.] .s Four pieces of information and a flag are stored within the WA handler for each unit. These are: .s .lm 20 .i -10 PHYSICAL UNIT NUMBER - the physical disc unit the desired partition is residing upon. This may well be different from the logical DU units (DU0 through DU7), as these may be set to different units and partitions. .i -10 PARTITION NUMBER - as RT-11/TSX can only access individual device units with a capacity of up to 65535 blocks (one 16-bit word), devices having more than this are broken up into "partitions", each 65535 blocks long. (There is a spare block between partitions, actually making each partition commence on a 16-bit boundary on the disc. This is necessary for the SIZE spfun to operate properly.) The lowest partition on a disc is partition zero, starting at physical block 0. The next partition, partition 1, commences on block 65536, and partition two on block 131072, et cetera. .i -10 OFFSET - This defines a starting offset within the partition. It is for use with the "pseudo-LD" facility of WA, and will not normally be used by people who are merely using WA to access large discs. It allows a disc-image file to be used as an apparent physical WA unit. For example, suppose you have the file TSX.DSK sitting on your system disc commencing at block 12345. It would be possible to access that file, if the offset within the relevant partition were set to 12345. .i -10 SIZE - Again, used with the "pseudo-LD" facility. If a file is to be used as an WA unit, its size should be put into this field. .i -10 WRITE FLAG - Each unit may be set to be READ ONLY if desired. .lm 0 .page .hl 1;SET Commands .x WA SET Commands .x SET Commands - WA The SET commands available for WA are: .s .lm 20 .i -16 SET WA HELP - types a list of available SET WA commands. .i -16 SET WA RELOAD - dummy SET command to force TSX to reload the first memory block of the handler, after modifying values by running WA.TSX as a programme. .i -16 SET WA DUVEC=oct - sets the vector assumed for the DU device (default 154) .i -16 SET WAn UNIT=u - sets the physical unit associated with logical unit WAn to the value u (decimal). .i -16 SET WAn PART=p - sets the partition associated with logical unit WAn to the value p (decimal). .i -16 SET WAn OFFSET=o - sets the offset value associated with logical unit WAn to the value o (decimal). .i -16 SET WAn SIZE=s - sets the size value associated with logical unit WAn to the value s (decimal). If this is not specified, device size spfun requests will be passed across to the DU handler. If size is specified, it will be used directly in response to these requests. .i -16 SET WA (NO)WRITE - (disallow)/allow writing on this unit. .i -16 SET WA TSX - allow SET WA commands from TSX-plus, and allow WA to be run as a user programme under TSX-plus. .i -16 SET WA NO TSX - disallow the use of WA SET commands unless running under RT-11 (ibid for running WA as a user programme). Once this option has been set, it is necessary to return to RT-11 to use SET WA TSX to unset it. It is recommended that all values necessary for WA be set up in an RT-11 command file, with this as the last command. .lm 0 .page .hl 1;Running WA as a Programme .x WA - Programme Use .x Programme use of WA Due to two factors: (1) the danger of allowing access to the fields of WA while running TSX, and (2) the inconvenience of having to rename WA.TSX to WA.SYS before being able to perform SETs under RT-11, another means of setting up the WA tables has been provided. .s .i 10;_.R WA.TSX .s Run the WA handler as a user programme. It uses normal CSI-style commands, as detailed here: .s 2 /H .s Type a help text. .s 2 /L .s List the current values in the internal table. .s 2 In the following switches, "unit" is one of the logical WA units. It must be specified as a single digit (0, 1, ..., 7). .s 2 unit/U:n. .s Sets the physical unit value associated with the relevant unit to the value n. It is necessary to append a "." to make the number decimal (octal being assumed otherwise). .s 2 unit/P:n. .s Sets the partition value associated with the relevant unit to the value n. (See comment under /U re decimal/octal values.) .s 2 unit/O:n. .s Sets the offset value associated with the relevant unit to the value n. .s 2 unit/S:n. .s Sets the size value associated with the relevant unit to the value n. .s 2 unit/F,filename .s Accesses the "filename" file (the second file in the CSI string), and uses its starting block number as the offset value, and its size as the size value to be associated with the desired unit. It is still necessary to specify relevant physical units and partitions, as otherwise the handler will assume physical unit zero, partition zero - despite the fact that the filename may be something like "DU2:MONITR.DSK". The default extension is ".DSK". .s 2 /R .s If /R is included in any command line, that unit is set READ ONLY. An attempt to write to that unit will return an error. .s 2 /T, /N .s /T allows running WA as a programme under TSX-plus. /N disallows it. (Analogous to the SET WA (NO) TSX command.) If a user tries to run WA under TSX after use of the /N switch, it will merely list the contents of its internal tables. .s 3 A unit specified with no switches merely has its table entries cleared to zero. All the specifications for a particular logical unit should be performed on the one line, as switches unspecified are assumed to have the value zero (/F implies /O _& /S). .s 4 Examples: .s Associate WA4 with physical unit 3, partition 1: .s *4/U:3/P:1 .s Associate WA0 with physical unit zero, partition 2, read only: .s *0/P:2/R .s Associate WA7 with SY:TSX.DSK .s *7/f,sy:tsx.dsk .s This assumes that SY: is DU:, unit zero, partition zero. If instead DU1, through SET commands, were associated with unit 4, partition 1, and we wished to set WA6 to being UCL.DSK on that particular disc, we would need to enter the command .s *6/f,du1:ucl/u:4/p:1 .s 2 At about this stage, you start to see why access to this facility should be restricted to the non-malevolent! .hl 1;Restriction on /U _& /P If the unit and partition are both specified to be zero (/U:0/P:0), rather that using unit zero, partition zero, the disc area accessed will be the current unit and partition for DU0:. (This is unlikely to be a problem.) .page .hl 1;Setting Up .x Setting up WA .x WA - Setting up .x TSX TSGEN for WA (1) Determine the number of WA units required for your system. If you need more than eight, you may need several copies of the WA handler on your system under different names (eg WA, WB, WC, or D0, D1, D2, .... etc). .s (2) Edit TSGEN.MAC to include whichever WA units you will require. The DEVDEF parameters for each WA device will be .s DEVDEF ,MAPH,DMA,HANBUF .s (3) Build your TSX system in the normal way. .s (4) Hack your TSX.SAV so that the value associated with DU: is 501, not the default 201. [See TSMUNG, in chapter 2.] Note that this is no longer essential with WA V2, but is preferable if you wish to generate a reasonably large TSX system. .s (5) Build your DU handler: .macro tsxpre+ducm/obj, link/nobit ducm. .s (6) Build your WA handler: .macro wa, link/nobit wa. .s (7) Get back to RT-11 .s (8) Copy ducm.sav to sy:du.tsx .s (9) Copy wa.sav to sy:wa.tsx, (also sy:wb.tsx et cetera, pro re nata). .s (10) Set up a command file to run the WA handlers and enter the required values (sample below) .s (11) Run these command files to set the tables in the handlers. .s (12) Boot your TSX-plus system. .page .hl 1;Safety Precautions _& Recommended Use .x Precautions for WA .x WA - Precautions - Make sure you are running on a Q-bus system. .s - Make sure you are NOT trying to use the DEC or S#_&#H DU handler for your TSX DU.TSX. .s - Make sure that unless you have some major reason for allowing it, access to the WA handlers is prohibited through the SET WA NO TSX command. .s - Set up your system so that if you are using pseudo-LD access, either there are no LD units mounted using the same files, or that there can be no cache controversy (eg make that WA handler NOMOUNT in TSGEN, or run with cache=0, or be bloody careful!). .s - If you alter WA, by running it as a programme under TSX, it is necessary then to type SET WA RELOAD to tell the operating system that modifications have been made so that it can re-load the handler with the new information. (RELOAD is a dummy SET which actually does nothing, forcing TSX to reload the first block of the handler.) .s - To run WA as a programme under TSX you need to have privileges to write to .TSX files on the system disc. .s - If you have a particular need for extremely high speed access, make your WA handlers UNMAPPED. This allows for less code in swapping the request to the DU handler at the expense of low memory space (about 400 words). [This may be more useful with 11/23 systems.] .page .hl 1;Example of Command File The SET Wx RELOAD commands are only necessary if these command files are to be run under TSX-plus rather than RT-11. .s 2 Set up WA to access the second group of eight partitions on the disc, with the last of these write protected: .s .nf ------------------------------ r wa.tsx 0/p:8. 1/p:9. 2/p:10. 3/p:11. 4/p:12. 5/p:13. 6/p:14. 7/p:15./r /n _^C set wa reload ------------------------------ .s 3 Set up both an WA and WB (a copy of WA) to cover a few things: .s ------------------------------ r wa.tsx 0/p:8. 1/p:9. 2/p:10. 3/p:11. 4/p:12. 5/p:13. 6/p:14. 7/p:15. /n _^C set wa reload r wb.tsx 0/p:16. 1/f,sy:tsx 2/f,sy:ucl 3/f,sy:monitr/r 4/f,sy:work1 5/f,du1:mordat/p:1/r 6/f,du5:again/u:1/p:2 7/p:23. _^C set wb reload ------------------------------ .page .c;Index .ps 60,120 .print index