ACP Tutorial ACP TUTORIAL R. W. Stamerjohn 13-MAR-78 This paper is for oral presentation at the Spring, 1978 Decus Symposium in Chicago, IL on April 26, 1978. It will also be published in the proceedings of the Symposium. The paper is presented here for Monsanto corporate approval. The tutorial deals with the software components of Digital Equipment Corporation operating systems named Ancillary Control Processors (ACP's). These components are deeply involved with the input/output mechanism of the IAS/RSX-11 operating systems, however, little is known about their internal workings. The paper presents the knowledge we have gained about ACP's while implementing the Monsanto Digital Access Protocol. ACP Tutorial PAGE 2 1.0 INTRODUCTION [slide 01] Some of the most frequently used components of an IAS/RSX-11 operating system are the Ancillary Control Processors (ACP's). Yet the concept behind an ACP and the various ACP's perform and are implemented remain one of the least understood portions of the operating systems. This tutorial will attempt to shed some light on the subject and provide a starting point for anyone considering implementing an ACP. At Monsanto, we investigated the use of ACP's as a part of a project called Monsanto's Digital Access Protocol (MDAP). The MDAP project will implement Digital's DAP protocol between a DECsystem-10 and RSX-11M systems. An ACP will be used on the RSX-11M systems to provide remote file access from the File Control Services (FCS). In this session today, we will present what we haved learned about ACP's. The discussion will use RSX-11M V3.0 as a basis for any technical details. While only a cursory examination of RSX-11M version 3.1 was made at the time this presentation was prepared, few significate changes are expected in the new release. Users of RSX-11D and IAS should not assume these details will apply to their systems. While the actual ACP's may be similar, our technical focus will be on the environment an ACP is implemented within, not the internal workings of any particular Digital supplied ACP. The format of the session [slide 02] is basically the same as the outline given in the Symposium program guide. We will first define "ACP" and outline the attributes of current ACP's. Next, The relationship of an ACP to the other IAS/RSX-11 I/O components will be examined. In particular, the discussion will cover how FCS and the Digital ACP's interact to form a device independent I/O mechanism. We will then discuss how one determines if an ACP is the right solution to a problem. After a short break, we will begin a discussion on how to implement an ACP for a RSX-11M system. This section will detail a proposed method of implementing an user-written ACP's that was first discussed at the Fall, 1977 Decus Symposium in San Diego. This area will not apply to IAS or RSX-11D users. If enough interest is generated, the discussion will continue at a Birds-of-the-Feather session later this evening. During the tutorial, we will pause for questions at the end of each major topic. Please hold comments until this time also. ACP Tutorial PAGE 3 2.0 PHILOSPHY 2.1 Definition of 'ACP' The first step is to define the mystical word "ancillary". Before Digital used it, the word was not a part of most vocabularies. Webster's defines ancillary as either subordinate or auxiliary. Digital's use of the word draws on both definitions. This session will define Anillary Control Processor in the IAS/RSX-11 environment refers to a task which provides a protocol for a class of I/O device. 2.2 Attributes of ACP's This definition is drawn from the observed attributes of the three ACP's provided by Digital: the disk file system (F11ACP), ANSI magtapes (MTAACP) and the DDCMP and NSP portions of DECNET (NT....). Each of these ACP's have the following features in common: 1. [slide 03] An ACP is implemented as a privileged task and has all the attributes of a task (stack, priority, checkpointablity, task name, etc.) 2. [slide 04] An ACP implements a protocol for a class of devices [slide 05]: 1. F11ACP implements the Files-11 protocol for all disks (RK05, RP06, etc.) and DECtapes. 2. MTAACP implements the ANSI magtape protocol for all supported magtape drives (TU10, TU16, etc.). 3. NT.... implements DECNET protocols for a wide variety of communication interfaces (DL11, DU11, etc.). 3. [slide 06] The protocol provided by each ACP extends the functionality of the devices in several ways [slide 07]: 1. The burden of direct device manipulation is removed from the programmer. By using an ACP, ACP Tutorial PAGE 4 the programmer no longer must deal with device specific I/O requests. 2. The burden of direct data manipulation at the device level is removed from the programmer. The ACP strips off any data related to its protocol and returns only the items of concern to the application. 3. The device can be treated as a logical, rather than physical, enity. In the case of Files-11, the programmer deals with files and records versus physical disk blocks. A corollary of this statement is that different devices can be treated the same from the program's viewpoint. DECNET's support of asynchronous, synchronous, and parallel interface is the most vivid example of this fact. 4. The device can be shared for simultaneous access. Each accessing processes is protected from the others by the ACP and its protocol. The ACP's also synchronize access to the physical device. 5. The device is protected against unauthorized and destructive access. In an appropriately managed IAS/RSX-11 system, F11ACP provides an adequate file protection mechanism. 4. [slide 08] An ACP extends the functionality of the IAS/RSX-11 executives, particularly the I/O mechanism. An ACP can properly be considered a part of the executive; and in many cases operates at the executive level. 5. [slide 09] An ACP can be enabled/disabled for a given device (mounted/dismounted). When enabled, the device is typically available only for use in the context of the protocol provided by the ACP. In summary [slide 10], this session will define an ACP as the following: 1. A task.... 2. which provides a protocol..... 3. for a class of I/O devices. [questions] ACP Tutorial PAGE 5 3.0 I/O COMPONENTS An ACP is one component of the IAS/RSX-11 I/O mechanism [slide 11], but its functionality is often confused with the other major parts: the QIO directive processing, File Control Services (FCS), and device drivers. By contrasting the role of the ACP with the roles of these other components, we can gain a better understanding of the function of an ACP. The begining of all I/O is with the QIO directive. The directive can be issued directly by a program or indirectly from various run-time systems (F4POTS) or from the file control services. In all cases, the QIO directive is the only recognized method to request I/O service from an IAS/RSX-11 operating system. The action taken by the executive when a request is issued depends on the type of request, the type of device, whether an ACP is used for the device, and finally, whether the ACP is enabled or disabled (mounted/dismounted). The executive may pass a QIO directly to the designated device driver. The driver then performs the request I/O operation. However, when an ACP is enabled for a device, the I/O request is typically passed to it instead. The ACP may forward the request to the driver, issue it's own QIO's to service the request, or fulfill the function without any device I/O at all. The file control services library is the component of the I/O mechanism used to implement device independence. The FCS routines examine the device characteristics or the currently assigned device and issue QIO directives dependent on the device characteristics. A task which uses direct QIO's to perform terminal output cannot use the same code to output to the disk. However, if FCS is used to perform the output, this flexablity is possible. The QIO's issued by FCS to perform the write to the terminal differ from those to a line printer. FCS is very much aware of the existence of the Files-11 and magtape ACP's and issues QIO's designed for such device. The actual QIO's supported by these ACP's are quite different from the normal device QIO's and are not documented by Digital. In a short while, we will deal with the specific relationship between FCS and F11ACP and MTAACP. The lowest level of the I/O mechanism are the device drivers. A device driver provides basic device services for a single module of a device. These services typically related directly to the method the device physically performs I/O: read data, write data, position device. Device drivers require the QIO parameters to be specified in a basic, often device dependent, form. ACP Tutorial PAGE 6 By using an ACP in conjunction with device drivers, the user is allowed to request logical, rather than, physical device services. These logical request are massaged by the ACP into the basic, driver specific, I/O request. At this stage, we have developed a simplistic view of the IAS/RSX-11 I/O mechanism. The next slide [slide 12] shows the flow of a simple QIO issued from a task for a particular device. The flow is thru the executive's QIO processor to the device driver to the device. This slide [slide 13] adds FCS to the task. In this case, the task makes an I/O request to FCS which then issues the actual QIO. The last case [slide 14] adds an ACP to the process. Here, the I/O request from FCS is routed to the ACP by the executive's QIO processor. The ACP issue's its own request to the device driver to satisfy the request. In developing the MDAP project, we looked at this slide with great interest. If we could write an ACP that handled QIO's in a similar fashion to the Files-11 ACP (F11ACP), but used DECNET to communicate with a partner on a remote node, we could achieve network device and file independence. While this statement is not totally true, the ACP approach is still valid. The next section will explore this subject further and attempt to open the mysteries of FCS and ACP's. [questions] ACP Tutorial PAGE 7 4.0 FCS AND ACP'S As stated before, the File Control Services library (FCS) is the component of the I/O mechanism used to implement device independence. When a task uses FCS for its I/O, it does not care if the device is a disk, terminal, line printer, card reader, magtape, or any other block or record oriented device. The only RSX-11M devices not interfaced to FCS are either real-time (LPS, ICS) or communications (DECNET) in nature. The FCS library modules can be classified into four categories: parsing, device/file access, input/output, and device/file control. The parsing routines are used to set-up the filename block. The parsing routines also assign the lun to the specified device and fill in FDB locations F.RCTL and F.VBSZ. These locations are used later to determine the proper QIO request to issue to the device. The byte field F.RCTL is filled in with the low byte of the first characteristics word (U.CW1). The most important bit is bit 0 (FD.REC). If this bit is on, the device is record oriented, ie. not a disk. If off, the device is block-oriented and all records must be handled internally by FCS. The next important bit is bit 3 (FD.DIR). If this bit is on, the device contains Files-11 directories. Finally, bit 5 (FD.SEQ) classifies the device as sequential. The device/file access routines examine FD.DIR. If the device has directories, ie. a disk, dectape, or ANSI maptape, Files-11 QIO's are used to access the file. Otherwise, no file access is required. The input/output routines examine RD.REC to determine the type of I/O to perform. If the device is record-oriented, simple read/write virtual block QIO's are issued for each record. Otherwise, records are buffered into blocks and written to the file. FCS provides the only documented interface to the F11ACP and MTAACP. Knowledge of FCS is very important to writing your own ACP if the purpose of the ACP is to provide device/file independence to a non-Digital supported device. [questions] ACP Tutorial PAGE 8 5.0 USES FOR USER WRITTEN ACP As noted before, the Digital supplied ACP's perform many useful services in the RSX-11/IAS operating systems. As several sites have shown, it is possible to write other ACP's and successfully integrate them into the operating systems. Before continuing with an examination of how this is done for RSX-11M, let use consider possible applications for user-written ACP's. Before continuing, it must be pointed out that writing an ACP is a non-trivial task. You will probably invalidate any Digital software warranties and end up making massive modification to the operating system. Future releases of the operating system must be updated for your ACP and there is no guarentee Digital will not completely rewrite the ACP code. The advantages of a user-written ACP must be weighed against these disadvantages. By definition, an ACP implements an I/O protocol. While it would be possible to implement an ACP for other purposes, typically, better solutions could be found. The best application for an user-written ACP is to implement a non-Files-11 file system, particularly, if the ACP is interfaced to FCS for device/file independence. Several examples come to mind: 1. If your shop supports mixed systems (RT11 and RSX-11M), an ACP could be implemented to support the RT-11 file structure. If interfaced to FCS, the RSX-11M utilities could be used to access the RT-11 disk directly, without the need to FLX files between the two structures. 2. If you have a requirement to read foreign magtapes, again an ACP could be written for this task. This is basically what occured when MTAACP was introduced by Digital. ACP's can also be used to implement a communications protocol. Digital takes this approach with DECNET. A user-written ACP could be used to communicate with other computers via an established protocol (BYSYNC, SDLC, etc.) or your own protocol. The final example that comes to mind is to extend the functionality of a current Digital device. One method of implementing spooling on a RSX-11M system would be to implement a line-printer ACP. This ACP would intercept write request to the line-printer and send them to a disk file. When the output is terminated, the file is queued to ACP Tutorial PAGE 9 be printed on the line-printer. Notice that in all examples, the user-written ACP's extend functionality, not performance. If your application is performance-oriented, a special device driver or direct device access should be considered, not an ACP. At Monsanto, we are implementing an ACP that is both communication and file system oriented. Monsanto has a herichal network, consisting of a DECsystem-10 at the top, and two layers of RSX-11M systems below it. We are currently working on a project to implement the Digital Access Protocol (DAP) between our DECsystem-10 and the PDP-11's. The PDP-11 side will be implemented by an ACP. This ACP will be interfaced to FCS on one end and to the Digital supplied DECNET software on the other. When completed, we expect to have network file independence. Our programmers will be able to access remote files using the same language syntax used to access local files. [questions] At this time, let us take a 5 minute break. When we come back, the discussion will be on how RSX-11M interfaces to an ACP. The details presented apply on to RSX-11M and not to RSX-11D and IAS. [break] ACP Tutorial PAGE 10 6.0 MECHANISM'S From this point on, the session will deal with the detail's concerning ACP's. We will first take a look at the various device tables, concentrating on items which concern ACP's. We will then discuss the environment an ACP must work in, looking at the mount and dismount task, the executive ACP interface, and some internal ACP processing. I have a limited number of copies of this presentation and other notes. The notes are also being placed on the SIG tape as runoff files. If anyone is interested in obtaining a copy, see me after the session. [Because of the detail, the remaining presentation will be only outlined, not written in full]. 6.1 Device Tables 1. Overall View [slide 15] Mention the various tables on the slide by name but do not make any connection between tables. Show which tables are always associated with a device and which are only present for an ACP. Emphasize the flexibilty and latitude you have in setting up device tables for an ACP. Mention how each existing ACP uses a different approach and the lack of similarity bewteen the VCB's for example. 2. Device Driver Tables 1. QIO DPB [slide 16] Emphasize that the function code is only the high byte and that all modifiers for a particular function must still be the same type of request (ie. control). Also mention the required format of a transfer request. 2. I/O Packet [slide 17] Emphasize the usefulness of I.TCB and I.LN2 to an ACP. Also discuss I.PRM in terms of transfer versus control functions versus ACP functions. ACP Tutorial PAGE 11 3. DCB [slide 18] Emphasize function mask bits. Mention ACP functions must be greater than 7. Reference table 4-1 in Guide to Writing I/O Driver. Describe order functions mask are checked: legal, control, noop, ACP, and transfer. 4. UCB [slide 19] Emphasize U.STS and U.CW1. In particular mention US.MNT, US.FOR, US.MDM in U.STS and all bits in U.CW1, Reference page 4-22 in Guide to Writing I/O Driver. Point out how F11ACP, MTAACP, and NT.... are differentiated internally by U.CW1 and how FCS uses DV.REC, DV.CCL, DV.TTY and DV.DIR and U.CW4 for determining what type of I/O to perform. Talk about U.ACP and U.VCB. 5. SCB [slide 20] Mention fork block is cell, not header. Can only fork once for any 1 SCB. 3. ACP Tables 1. VCB [slide 21] Emphasize that only V.TRCT is required, all other locations are ACP unique. Mention VCB's created at mount time and destroyed at dismount. 2. LUT [slide 22] Emphasize importance of LUT and putting LUT2 to good use. Mention lock feature. 3. Other Tables Mention what a window is, how it typical is link to other tables. Tell about F11ACP and its FCB's and NT.... and its CCB's. 4. Summary [slide 23] Trace through the various links. [questions] ACP Tutorial PAGE 12 6.2 Environment 1. MOU Command 1. Purpose [slide 24] Explain purpose of MOU task: ACP option specification, protocol initialization, protocol verification, and ACP task startup. Explain that using the MOU command is not necessary, that an ACP could perform the necessary operation itself when it is initially run if written correctly. 2. Structure [slide 25] Explain each module's purpose and place, emphasizing what modules must be added for a new ACP and what modules must have code changes. 3. Program Flow 1. Device Parsing [slide 26] Tell what this process does: get command line, parse out device name, assign lun 2 to device, set $MDEV to UCB address, and dispatch on device characteristics. Explain how the dispatch is made. 2. Option Parsing [slide 27] Tell what these modules typically do: Allocate the VCB and any other storage blocks, set $MVCB and $MVCBL, parse options and set appropriate words in VCB and $MKEY, and check for necessary multiuser priveledges ($PVTST). 3. ACP Startup [slide 28] Tell what these modules typically do: check for legal access (label processing), complete table initialization, and invoke ACP. 4. VID Display [slide 29] Just mention module name ($MDISEP) and how invoked from root. ACP Tutorial PAGE 13 5. Error Handling [slide 30] Just mention module name ($MOUER), calling sequence (R0 = ASCIZ string, and table dealocation. [questions] 2. DMO Command Explain the DMO is fairly simple. The only ACP dependent code is if the device is Files-11. If not, it constructs a DMO QIO request, queues it di rectly to the ACP, increments the volume transaction count, sets the mark for dismount bit (US.MDM), and exits. 3. Executive ACP Interface 1. $DRQIO [slide 31] Explain flow through $DRQIO, mentioning points especially concerned with ACP's: lun interlock feature, ACP function handling, and polish data base. 2. $GTPKT [slide 32] Explain flow through $GTPKT, mention points especially concerned with ACP's: an ACP enabled device cannot be attached, an function greater than 7 for an ACP device is passed to the ACP (no matter what), and an read/write virtual to an ACP device is mapped by $MPPKT and only sent to the ACP if the mapping is unsucessful. 3. ACP Initialization [slide 33] Explain two entries: $EXRQP (by priority) and $EXRQF (FIFO) and calling parameters. Note that I/O packet is queued to receive queue and that the normal send process cannot send to an ACP. Also note that these entries can and are used elsewhere to queue packets to ACP's (MOU, DMO, etc.). 4. $IODON Note that no special processing is done here for an ACP, it however uses the I/O done processors to terminate a request. ACP Tutorial PAGE 14 5. Task Exit Explain how a nonzero, nonlocked second lun word is search for and IO.CLN issued if found. [questions] 4. Internal ACP Processing 1. ACP Mapping [slide 34] Explain ACP mapping and that full capablilties of the executive and a task are available to it. 2. State Switching [slide 35] Explain how to switch from being a task to being a part of the executive. 3. Dequing and Dispatching I/O Request [slide 36] Show example for proper dequing and stopping loop. 4. Terminating I/O Request Explain that nothing fancy is involved except decrementing the transaction count and watch for a dismountable state when a marked for dismount. 5. Issuing Internal QIO's [slide 37] Show example for different ways to issue QIO's: regular directive, at $DRQRQ, to an ACP. Also explain concept of driver co-routines. 6. Pool Management Show how internal and executive pools can be managed and what must be in executive pool only (VCB's and windows). Mention task header usage. 5. Summary [questions] ACP Tutorial PAGE 15 7.0 BLUESKYING 7.1 Implementation Hints 1. What to print. List off the important modules to get listing for but emphasize that everything should be listed. 2. What to read. List manuals and important code to read. 3. What to expect. Point out lack of Digital support and understanding for your effort, termination of support, problems with future releases, bugs you will find.