DS78NEW on CL7VAX::[MARK.CD] at present DS-78 DRAFT !!! RT-11 DESIGN SPECIFICATION FOR DR-11W LINK DRIVER Peter Heinicke, Mark Pyatetsky, David Ritchie,Vicky White 15 February 1982 A design specification of an RT11 Handler for a DR-11W interprocessor link is given. CHAPTER 1 RT-11 DR11-W LINK DRIVER - INTRODUCTION This document provides a description on how a RT-11 application program can communicate with a RT-11 or RSX-11M application program running in a different PDP-11 processor using DR11-W interprocessor link. More specifically, the document shows the levels of protocol for such a communication, provides a specification for a communication driver and lists the phases or milestones for the implementation of the driver. The motivation and goals for such interprocessor communication for data aquisition and analysis are explained in DS-77. DS-77 also defines the transmission protocol over DR11-W for such a communication and provides references to other related documents, describing RSX-11M implementation. The implementation of the DS-77 transmission protocol with standard "easy" and "clean" interface to the application program calls for a special software program to be written - the Communication Driver. Of course, separate Communication Drivers will exist for the RT-11 and RSX-11M environments. CHAPTER 2 RT-11 DR11-W LINK DRIVER - LEVELS OF PROTOCOL The following figure shows the various interfaces and protocols necessary to implement a three layered architecture: RT-11 RT-11 or RSX-11M Application Layer Layer 3 Application <- - - - - - - - - - - - -> Application Program Program (Logical) Protocol | | | Sftwre Drvr | | Intrfce--> | | | DS-77 | Layer 2 Communication <-- -- -- -- -- -- -- --> Communication Driver (RT-11) Protocol Driver (RT or RSX) | | Hrdwre | | Ints, Regs-> | | | Physical | Layer 1 DR-11W (Hardware) <-------------------> DR-11W (Hardware) Link (Parallel) Figure 1 CHAPTER 3 THE COMMUNICATION DRIVER (CD:) The communication driver in the RT-11 environment will be written as a formal RT-11 driver. This will allow standard I/O to the link (writes,reads,special functions) from the application program. It will also provide all application programs with a single standard interface to the DR11-W, and relieve them from having to implement the DS-77 transmission protocol, and hopefully insulate them from possible future changes in DR11-W (by DEC) and the DS-77 protocol. (It should also provide a model for drivers for other communications devices just as the MT driver provides a model for other higher density tape drivers such as MM, but this is just a beneficial byproduct, not a goal). 3.1 THE PACKET TYPE CODE (PTC) AND "READ" SESSIONS A Packet Type Code (PTC) is used for identification of various functional ("subapplication") entities within the application program, running under RT-11, as message destination. In a READ request to the Driver, a "subapplication" identifies itself as a receiver of a message with the PTC the "subaplication" specifies in its READ request. In a WRITE request to the Driver, the subapplication specifies the subapplication (RT-11) or task (RSX-11M) which is to receive its message in a destination PDP-11. In an SPFUN request to the driver a "Read Session" may be opened for a specified PTC. The "Read" Sessions significally improve the utilization of the interprocessor link. They address the following problem. When a PDP-11 processor attempts to send a message with a specific PTC to another processor on the link, the other processor may reject the message - either because it is has no buffer in which to put the message - "busy". - or it does not have any application program willing to accept the message with the given PTC. THE COMMUNICATION DRIVER (CD:) Page 3-2 THE PACKET TYPE CODE (PTC) AND "READ" SESSIONS By opening "Read" sessions, the application program (or its "subapplications") provides the driver with a list of those PTC's it is willing to accept. This authorization is valid until the application program closes the sessions. This in turn enables the driver in another PDP-11 to distinguish between "busy" and "PTC rejected" situations. The exact format of the open/close session programming requests is explained further in this write-up. 3.2 THE SOFTWARE INTERFACE TO THE DRIVER The driver will make the DR-11W appear to the application program as a sequential non-file structured device similar to a magtape filled with card images (in a "foreign" format). The driver will write into and read from the application program buffer area directly, i.e. the driver will NOT maintain its own buffers for sending and receiving the DMA messages over the DR11-W link. The buffer areas used by the application programs can be located anywhere in the 128K words available to memory mapped PDP-11's. The following RT-11 standard programming requests will be available to the application programs for interface with the driver: * LOOKUP (open logical channel) * READC (read with completion routine) * WRITEC (write with completion routine) * SPFUN (request special function from driver) * READ/READW (read/read and wait) * WRITE/WRITEW (write/write and wait) When using READC or WRITEC, the application programs will have to specify completion routines to cope with the asynchronous nature of the communication link (e.g. timeouts, error handling, unsolicited messages on the link, link failures, restart of transmission, etc.) The application program may, of course, issue READ, READW, WRITE, WRITEW and WAIT requests. Care should be taken in using READW or .WAIT after a READ request, since the application could wait indefinitely if no message of the requested PTC arrived. Also a READW or a WAIT request will wait until all the I/O requests on the specified channel have completed. The use of READC and WRITEC requests is preferred, in order to avoid confusion or possible deadlocks. THE COMMUNICATION DRIVER (CD:) Page 3-3 THE SOFTWARE INTERFACE TO THE DRIVER 3.2.1 CLOSE (close Logical Channel) Request This request should never be issued by the application programs. This is because the RT-11 Monitor does not notify the driver that the channel is closed. Hence, the driver will still be executing all outstanding requests with unpredictable results (application program memory areas overwritten, etc.). 3.3 DRIVER RESPONSES TO THE APPLICATION PROGRAM There will be two types of the driver responses to the application program: immediate and final. Immediate response will be given when the requests have incorrect format or data. Such requests will not be executed by the driver. In accordance with the RT-11 structure, the error code will be given in byte 52. Final responses will be given to correct requests indicating either successful completion of the operation or error. These responses will be placed in the control and status area specified in each request. The exact formats and codes for both types of responses will be explained in paragraph 3.8 of this write-up. 3.4 UNSOLICITED MESSAGES Since the driver does not have its own buffer space, it has to use the buffer space provided by the application program in its read or write requests. The driver will not accept unsolicited messages unless the application program has issued a READ request, providing the driver with the buffer area in which to put the message. 3.5 HOW THE READ/WRITE REQUESTS ARE PROCESSED BY THE DRIVER Several read and/or write requests can be outstanding at any time. All read requests will be processed randomly, i.e. as soon as the message with the requested PTC is received on the link. All write requests will be processed sequentually, i.e. in the order they are posted by the application program (or its "subapplications"). Two separate queues for the outstanding read and write requests will be internally maintained by the driver. The driver will attempt to process the write requests whenever the link is idle. THE COMMUNICATION DRIVER (CD:) Page 3-4 HOW THE READ/WRITE REQUESTS ARE PROCESSED BY THE DRIVER The application program will be able to optionally specify a timeout in its read or write requests. An application with more than one read or write request outstanding at one time may have to reserve sufficient extra I/O queue elements with .QSET requests. This must be done before issuing the READ or WRITE requests. 3.6 INITIALIZATION OF THE DRIVER AND THE LINK No separate procedure will be required to initialize the driver. However, the driver will have to be fetched before the application _______ program runs. It should not be permanently loaded. The link will be initialized by the driver at the time it is first called by the RT-11 Monitor. Every time the driver gets control, the link will be initialized if necessary. 3.7 MULTIPLE DR11-W LINKS In accordance with the RT-11 philosophy, up to eight units of the same device type can be supported by the driver. Hence, up to eight DR11-W links will be supported by the Communication Driver. 3.8 FORMATS OF PROGRAMMED REQUESTS 3.8.1 LOOKUP This request associates a particular channel with a device. The LOOKUP request is actually posted to the Monitor and not to the driver. The format of this request is fully described in the RT-11 Programmer's Manual. 3.8.2 SPFUN The SPFUN call to the driver is of the form (see also RT-11 Programmer's Manual) .SPFUN area,chan,func,buf,wcnt,blk,[crtn] buf - must be set to 0 crnt - should not normally be specified since this request will complete immediately and needs no completion routine. THE COMMUNICATION DRIVER (CD:) Page 3-5 FORMATS OF PROGRAMMED REQUESTS The SPFUN requests can be issued by the application programs with the following function codes: func = 377 (octal) - open "Read" session blk = PTC, for which the "Read" session is opened func = 376 (octal) - close "Read" session blk = PTC, for which the "Read" session is closed func = 375 (octal) - set new default request timeout blk = timeout value in number of 1/60 sec ticks. The maximum number of open sessions on all channels is 16. On return from an SPFUN request carry will be set if an error condition has occurred. Byte 52 will contain the error code. 0: Successful - Session Open Errors: 1: Invalid PTC (1-255) 2: Channel is not open 3: Maximum number of open sessions exceeded 4: No session open for this PTC (on func=376) 3.8.3 READ And WRITE The READ and WRITE call to the driver is of the form (see also RT-11 Programmer's Manual) .READ or .READW area,chan,buf,wcnt,blk .WRITE or .WRITEW area,chan,buf,wcnt,blk .READC or .WRITEC area,chan,buf,wcnt,crtn,blk buf - is the address of the buffer (word aligned) to receive the data read from the link. If buf is an odd address it is interpreted as referencing a descriptor for a buffer in upper memory. wcnt - is the maximum number of words which may be read. blk - is the address of a three word control and status area (word aligned) containing word 1 : Packet type code to be read or sent (1-255) word 2 : message block number (1-32) word 3 : error status will be returned here The message block number is optional and is provided for the convenience of the application in distinguishing between its various read/write requests, on completion. It will be returned to the application in bits 8 to 12 of the channel status word upon completion of the read/write. THE COMMUNICATION DRIVER (CD:) Page 3-6 FORMATS OF PROGRAMMED REQUESTS There will be a timeout period set up on the read or write if a negative value is given for the message number. The positive message number will still be returned in bits 8-12 of the CSW on completion. The value of the timeout period may be set up using an SPFUN request, described above. READ Requests ____ ________ A read will not be accepted unless a read session has been opened for the PTC specified in the control and status area - blk. A read will be rejected and on return from a read request the carry bit will be set in one of the following error conditions: Byte 52 will contain the error code (immediate response). Error: 1: Invalid PTC 2: Channel is not open 5: No session open for this PTC 6: Invalid blk address given 7: Word count is 0 In these conditions a completion routine, if specified, will not be called. A read which has been accepted, will complete when either a message with a suitable PTC is sent by the partner computer, or the timeout on the read expires, if such a timeout was specified. On completion of a read, the channel status word contains the message block number provided in the read, in bits 8 to 12. The status of the read will be found in the third word of the control and status area specified in the read (final response). It may have the following values Error: 1: Successful - message received negative: errors -100 Data received was truncated -300 Timeout on READ - no message received -400 Hardware errors .. -500 Timeout during message transfer A completion routine, if specified, will be called when the read completes. On entry to the completion routine R0 contains the channel status word for that READ. WRITE Requests _____ ________ A write will be rejected and the carry bit set on return from the write request in one of the following error conditions. Byte 52 will contain THE COMMUNICATION DRIVER (CD:) Page 3-7 FORMATS OF PROGRAMMED REQUESTS the error code (immediate response). Error: 1: Invalid PTC - (must be in range 1-255) 2: Channel is not open 6: Invalid blk address given 7: Word count is 0 In these conditions a completion routine, if specified, will not be called. A write which has been accepted, will complete or timeout, and an error status will be put in the third word of the control and status block given in the write (final response). It may have the following values: Error: 1: Successful - message transferred negative: errors -100 Only part of the data was accepted by receiver -200 PTC rejected - receiver has no open session for this PTC -300 Timeout -400 Hardware errors .. On completion of a write, the channel status word contains the message block number provided in the write, in bits 8 to 12. A completion routine, if specified, will be called when the write completes. On entry to the completion routine R0 contains the channel status word for that write. CHAPTER 4 DRIVER DEVELOPMENT PHASES Phase 1. - Single DR11-W - No request timeout - DS-77 protocol - External queuing Phase 2. Same as Phase 1 plus: - Internal queuing (instead of external) - Request timeout - Open/Close "Read" sessions Phase 3. Same as Phase 2 plus: - Multiple DR11-W (up to eight)