.PAGE SIZE 58, 85 .NONUMBER .; for VAX .;.LEFT MARGIN 10 .;.RIGHT MARGIN 75 .; for RSX .LEFT MARGIN 0 .RIGHT MARGIN 65 .AUTOPARAGRAPH # .SKIP 5 .CENTER THE RSX MULTI-TASKER .SKIP .CENTER February 1989 .SKIP .CENTER "In hoc signo foobar" .SKIP .CENTER Fine Realtime Commentary Since 1975 .SKIP 6 .CENTER ^&TABLE OF CONTENTS\& .SKIP .LITERAL RSX SIG NEWS Editor's Corner RSX-1 Submitting Articles to the Multi-Tasker RSX-1 Bulletin Board Notes RSX-2 Chairman's Corner RSX-2 ARTICLES I/O Page Commons for RSX RSX-3 .END LITERAL .SKIP 10 Opinions expressed in the Multi-Tasker are those of individual members. They do not represent the official position of the RSX SIG or that of DECUS leadership in general. .PAGE .CENTER ^&RSX SIG NEWS\& .SKIP 2 .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT Editor's Corner .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .SKIP 4 .CENTER Editor's Corner .SKIP .LITERAL Jim McGlinchey, Managing Editor Phil Hannay, Production Editor Bruce Mitchell, Minister of Propaganda .END LITERAL .SKIP .TEST PAGE 15 .SKIP 2 .CENTER ----- Submitting Articles to the Multi-Tasker ----- You are encouraged to submit articles to the Multi-Tasker. No article is too big or too small. They can be serious or funny, and of any techinical level. Please submit machine readable media if possible. Hardcopy submissions are okay if they are fairly short. Illustrations and drawings that can be photocopied may accompany the article. Most any media is acceptable, however RX50, RX01/2, TK50 and 1600 BPI magtape are preferred. All RSX volume formats are acceptable, and VMS formats are also acceptable on RX50, TK50 and 1600 BPI magtape. You can also submit articles through the RSX bulletin board system at (612) 777-7664. Kermit the file into your account and then send it via MAIL to username MULTITASKER. The Multi-Tasker begins life as a RUNOFF file, so feel free to submit your articles in RUNOFF format. The page size will be 80 columns by 58 lines, with the left margin at 10 and right margin at 75. Use literal format for code examples. If you change margins, use incremental changes rather than absolute. Mail your articles and other submissions to the expansive Multi-Tasker offices: .LITERAL Phil Hannay Cargill Research Bldg Box 9300 Minneapolis, MN. 55440 tel. 612-475-5433 (daytime) .END LITERAL .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT Bulletin Board Notes .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .TEST PAGE 15 .SKIP 4 .CENTER Bulletin Board Notes .SKIP The RSX Bulletin Board is online. Software availability: RSX MAIL, Kermit, old issues of The Multi-Tasker and various other items. Free advice from everybody who logs in too. The system can always use additional hardware. Anything, including archaic items. We are still looking for an RL02 drive. Contact Jim Bostwick, at 612-475-6264 (daytime) if you wish to donate some equipment. The BBS number: 612-SPR-PONG (612-777-7664). This line is autobaud 110 - 1200 baud. To request an account, log in with account name ACCOUNT, password REQUEST. .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT Chairman's Corner .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .test page 15 .skip 4 .center Chairman's Corner .SKIP .center Jim Bostwick .skiP Nothing new this month. .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT Articles .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .PAGE .CENTER ^&ARTICLES\& .SKIP 2 .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT I/O Page Commons for RSX .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .TEST PAGE 15 .SKIP 4 .C;I/O Page Commons for RSX .SK .C;A Technical Note .SK .C;by .C;James A. McGlinchey .SK 18 .C;James A. McGlinchey .C;Software Engineering Consultant .C;427-3 Amherst St. .C;Suite 303 .C;Nashua, NH 03063 .C;(802) 879-6014 .SK .ST Description .PG .F The creation of I/O page COMMONs for RSX is a simple process in principle, often confusing in execution. The entire recipe is contained in the RSX-11M/M-PLUS Task Builder Manual, in the section on Shared Regions. This section, however, leaves a few things to be desired, namely: .LS .LE The example in the TKB manual shows a limited example, carefully chosen to expose only a few device registers in the I/O Page. .LE The example shows how to access the I/O Page from MACRO-11 only. No consideration is given to FORTRAN, for instance. .LE The example shows how to access word locations only. Accessing byte location are left to the reader to work out. .ELS .SK This RSX Technical Note contains an entire worked out example of creating and using an I/O Device COMMON from both MACRO-11 and FORTRAN, with complete code examples and procedures. All pieces are sufficiently short that they can be presented here in source form. Even an non-typist reader should be able to type all the source files in a short time. .SK The source code consists of six (6) files: .SK .NF .LM +4 IODEV.MAC Source code for creating the COMMON IODEV.CMD Command file for creating and installing the COMMON .SK IODEVTST.FTN Test/Demo program in FORTRAN IODEVTST.CMD Command file for same .SK TEST.MAC Test/Demo program in MACRO-11 TEST.CMD Command file for same .SK .LM -4 .F An I/O Device (IODEV) COMMON is a technique used to expose the PDP-11 I/O Page in the virtual address space of an RSX task. The I/O Page appears to occupy all virtual address space mapped by the task's Active Page Register (APR) number 7, thus occupying task virtual addresses 160000 (octal) through 177776. .SK The IODEV COMMON presented in this technical note differs from the one in the RSX TKB Manual in that it exposes the entire I/O page for both MACRO and FORTRAN. No changes are needed for a particular device. MACRO-11 gets a Global Label (IODEV::) at the base of the I/O Page. FORTRAN gets a PSECT IODEV defined over the I/O Page which it can access as a INTEGER*2(4096) array in a labeled COMMON. The user must compute the index to a particular device's control registers; the formulas for doing so are given later. .SK .TP 12 .NT;WARNING ^&DO NOT\& TRY TO ACCESS LOCATIONS IN THE DEVICE COMMON JUST TO 'SEE WHAT HAPPENS'. LOCATIONS IN THIS COMMON ARE NOT MEMORY, BUT ARE I/O DEVICE REGISTERS. INCORRECT ACCESS OF THESE REGISTERS MAY RESULT IN SYSTEM CRASHES, DISK CORRUPTIONS AND OTHER NON-RECOVERABLE DAMAGE TO YOUR SYSTEM. .EN .ST Installation Procedure .PG ^&Installation\& .SK The procedure for installation and use of the I/O Page COMMON is: .LS .LE;Create the I/O Device COMMON (do this only once). .SK Type in the files IODEV.MAC and IODEV.CMD, then execute IODEV.CMD .NF .SK MCR>@IODEV MCR>PIP LB:[1,1]/RE=IODEV.TSK,.STB .SK .F .LE;Install the I/O Device COMMON. .SK .NF Enter the next two lines in your STARTUP.CMD file: .SK MCR>SET/MAIN=IODEV:177600:200:DEV MCR>INS LB:[1,1]IODEV (not needed for RSX-11M-PLUS) .SK .F Then re-boot. .SK The above two lines can also be done by hand for test purposes. You must be a privileged user to perform these operations by hand. .F .LE;Create the test program. .SK The test programs are shown later. Note the .NF .LM +4 .SK COMMON=IODEV:RW:7 .LM -4 .F .SK command in the Task Build Command File for either task. This command causes the task builder to allocate APR 7 to the I/O Page. .SK .NF MCR>@TEST (for MACRO-11 test) .SK MCR>@IODEVTST (for FORTRAN test) .SK .F Typical sessions for each test are included at the end of this technical note. .ELS .ST Accessing I/O Device Registers .PG .F ^&Accessing Registers\& .SK You're in for a lot of surprises. .SK You constantly have to remind yourself the locations in the I/O Page are NOT MEMORY. They do not necessarily behave like memory. For example: .LS .LE;What you read may not be what you have just written. .LE;You may be reading to one register but writing to another, even though you're accessing the same I/O Page location. .LE;A given register my be read-only. .LE;A given register my be write-only. .LE;A given register my be read-once. .LE;A given register my be write-once. .LE;Setting/clearing bits in registers is troublesome. .SK Avoid using any instruction that involves a read-modify-write cycle (See all above for reasons). .SK It's best to develop the bit pattern in a register or integer variable, then move it into the register. If you must, keep a 'shadow' of the register in a local variable so that you can diddle bits. .SK The following MACRO-11 instructions can cause problems: .SK .NF .LM +4 BIC or BIS CLR or CLRB (use MOV(B) _#0,Register) ASH MUL DIV .LM -4 .SK .F In FORTRAN, do not use a register reference in an arithmetic expression. There's no telling what the FORTRAN-77 or FORTRAN-IV-PLUS optimizer will do to it. Copy the I/O register to a local variable and use the local variable in expressions. .LE;DMA Addresses .SK A PDP-11's software deals in virtual addresses; i.e., addresses relative to the beginning of a program in memory. DMA hardware deals with physical addresses. Be careful - an RSX task may be at one physical address one moment, and at another the next. If you must deal with DMA devices, you're better off writing a device driver, for this and a lot of other reasons. .LE;Hardware Idiosyncrasies .SK I am sure an appropriate place in Hell has been reserved for hardware designers. There's no telling what hardware designers will do. I've seen device registers where bits are set in order to clear them (that's right), and devices where a given register location may contain the contents of one of several different device registers, depending on some other bits in some other registers. Just be careful, and read all the descriptions about each bit in each hardware register. .ELS .ST Bugs .PG ^&Bugs\& .SK The most likely bug you'll run into in using an I/O device COMMON is the Odd Address Trap. The notice from RSX will look like: .NF .SK .LM +4 TT0 -- Exiting due to ERROR 3 Odd address trap (SST0) at PC = 011646 in ".MAIN." at or after 11 .LM -4 .SK .F This error has several implications, as this message results from all traps through location 4 (check your processor manual): .LS .LE;You may really have accessed an odd address as a word. Accesses to full words (I*2 variables in FORTRAN) must be made to the IOPAGE array. .LE;You may have miscomputed the offset for use as the index into the array. Go check your calculations, making sure you did the calculations in ^&OCTAL\&. .LE;The device may not be installed. Remember, I/O Page addresses are NOT MEMORY. They exist only if the device has been physically plugged into your backplane. .LE;It may be a hardware problem, where the I/O device registers do not respond even though the device is plugged in. .ELS .ST IODEV COMMON Definition .PG .NF ^&IODEV.MAC\&: .SK .lit .TITLE I/O Page Common for RSX .PSECT IODEV RW,D,OVR,GBL ; ; Define a COMMON for the Whole I/O Page ; IODEV:: .BLKW 4096. .END .eli .ST IODEV Assembly/TKB Command File .PG ^&IODEV.CMD\&: .SK .lit .ENABLE SUBSTITUTION ; ; Create I/O Page Global COMMON Image ; PIP IODEV.OBJ;*/DE/NM,.LST;*,.TSK;*,.MAP;*,.STB;* PIP IODEV.MAC/PU,.CMD MAC IODEV,IODEV/-SP=IODEV .OPEN IODEVBLD.CMD .DATA IODEV/-HD/PI,IODEV/-SP,IODEV=IODEV .DATA / .DATA STACK=0 .DATA PAR=IODEV:0:20000 .DATA // .CLOSE TKB @IODEVBLD PIP IODEVBLD.CMD;*/DE,IODEV.OBJ;* ;+ ;To Install: ; ; PIP LB:[1,1]/RE=IODEV.TSK,.STB ; SET/MAIN=IODEV:177600:200:DEV ; INS IODEV ; ;To Link a Task to it: ; ; COMMON=IODEV:RW:7 ;- .eli .ST Test/Demo program for MACRO-11: .PG ^&TEST.MAC\&: .SK .lit .TITLE TEST - IODEV ACCESS TEST .MCALL EXIT$S START:: MOV BASE,R0 ; locate base. MOV (R0),R1 ; then access all device regs. MOV 2(R0),R2 MOV 4(R0),R3 MOV 6(R0),R4 BPT EXIT$S ; ; Base address(es) of I/O Page locations to be accessed. ; BASE: .WORD IODEV+<177560-160000> .END START .eli .ST MACRO-11 Demo/Test Command file: .PG ^&TEST.CMD\&: .SK .lit .ENABLE SUBSTITUTION PIP TEST.OBJ;*/DE/NM,.LST;*,.TSK;*,.MAP;* PIP TEST.MAC/PU,.CMD MAC TEST,TEST/-SP=TEST .OPEN TESTBLD.CMD .DATA TEST/DA,TEST/-SP=TEST .DATA / .DATA COMMON=IODEV:RW:7 .DATA // .CLOSE TKB @TESTBLD PIP TESTBLD.CMD;*/DE,TEST.OBJ;* .eli .ST Test/Demo program for FORTRAN: .PG ^&IODEVTST.FTN\&: .SK .lit C IODEVTST.FTN C C----------------------------------------------------- C C Program to verify and demonstrate access to an I/O C Page COMMON from FORTRAN-77 or FORTRAN-IV-PLUS C running under RSX-11M or RSX-11M-PLUS C C----------------------------------------------------- C C The I/O Page COMMON is defined as any array of C 4096 I*2's. Although this array is incompletely C populated (not all locations would respond if C accessed), the user is expected to know which C locations are to be accessed. C C----------------------------------------------------- C *** WARNING WARNING WARNING WARNING *** C C DO NOT, REPEAT, DO NOT TRY TO ACCESS LOCATIONS C IN THIS DEVICE COMMON JUST TO 'SEE WHAT HAPPENS'. C LOCATIONS IN THIS COMMON ARE NOT MEMORY, BUT ARE C I/O DEVICE REGISTERS. INCORRECT ACCESS OF THESE C REGISTERS MAY RESULT IN SYSTEM CRASHES, DISK C CORRUPTIONS AND OTHER NON-RECOVERABLE DAMAGE TO C YOUR SYSTEM. C C *** WARNING WARNING WARNING WARNING *** C----------------------------------------------------- C IMPLICIT INTEGER*2 (A-Z) C COMMON /IODEV/IOPAGE(4096) !define COMMON as words C LOGICAL*1 IOBYTE(8192) !define COMMON as bytes EQUIVALENCE (IOPAGE(1),IOBYTE(1)) C C------------------------------------------------------ C Calculation of an index for a single-word device register: C C INDEX = (address(8) - 160000(8))/2, C converted to decimal, plus 1. C C Each byte of the word register may be accessed C by referring to IOPAGE by the equivalent array, C IOBYTE. The corresponding index is calculated C via the formula: C C (low byte) C ILBYTE = (address(8) - 160000(8)), C converted to decimal, plus 1. C This is also ((INDEX-1)*2)+1 C C (high byte) C IHBYTE = ILBYTE + 1 C This is also ((INDEX-1)*2)+2 C C Note: Incorrect calculation any of these indices C will cause the application task to abort with C an Odd Address Trap error. C C Examples: C C Address is 177560, the console Read CSR. C INDEX = (177560 - 160000)/2 C INDEX = 17560(8)/2 = 7672(8) C INDEX = 4024(10) +1 = 4025 C Low byte of 177560 has index of 8049 C C Address is 170420, a KWV-11/P Register address C INDEX = (170420 - 160000)/2 C INDEX = 110420(8)/2 = 4210(8) C INDEX = 2184(10) +1 = 2185 C C--------------------------------------------------- C Define PARAMETER symbols for indices (always C reference device registers by these symbols C to avoid Magic Numbers in the code) C C PARAMETER DLRCSR = 4024 !Will force an OD: abort C ! for illustration. PARAMETER DLRCSR = 4025 !This is the good value. PARAMETER DLRDAT = DLRCSR+1 PARAMETER DLXCSR = DLRCSR+2 PARAMETER DLXDAT = DLRCSR+3 C C Low byte of 177560 has index of 8049 C PARAMETER DLBYTE = 8049 C C Register base for a KWV-11/P C PARAMETER DLKWV = 2185 C C As a test, display contents of console registers C as words C WRITE (5,900) IOPAGE(DLRCSR), IOPAGE(DLRDAT), 1 IOPAGE(DLXCSR), IOPAGE(DLXDAT) C C Now as bytes. C WRITE (5,901) (IOBYTE(DLBYTE-1+I),I=1,8) C C And now for the KWV-11/P... C C WRITE (5,910) IOPAGE(DLKWV) CALL EXIT C--------------------------------------------------- C F O R M A T S C 900 FORMAT ('0Console DL-11 Registers:'/ 1 ' Read CSR: ',O6/, 2 ' Read DAT: ',O6/, 3 ' Xmit CSR: ',O6/, 4 ' Xmit DAT: ',O6//) 901 FORMAT ('0Console DL-11 Registers, as bytes:'// 1 ' Lower Byte Upper Byte'/ 2 ' ---------- ----------'/ 3 8(3X,O6,8X,O6/)) 910 FORMAT ('0KWV-11/P Registers:'/ 1 ' CSR: ',O6//) END .eli .ST FORTRAN Demo/Test Command File: .PG ^&IODEVTST.CMD\&: .SK .lit .ENABLE SUBSTITUTION ; ; CREATE TASK TO TEST I/O DEVICE ; COMMON ACCESS FROM FORTRAN ; PIP IODEVTST.OBJ;*/DE/NM,.LST;*,.TSK;*,.MAP;*,IODEVTST.TKB;* PIP IODEVTST.FTN/PU,.CMD F77 IODEVTST,IODEVTST/-SP=IODEVTST .OPEN IODEVTST.TKB .DATA IODEVTST,IODEVTST/-SP=IODEVTST,LB:[1,1]F4POTS/LB .DATA / .DATA COMMON=IODEV:RW:7 .DATA // .CLOSE TKB @IODEVTST.TKB PIP IODEVTST.OBJ;*/DE/NM,.TKB;* ; ; DONE. ; .eli .ST