OVERVIEW OF PROGRAMMING USER-WRITTEN DRIVER CODE

To create the source code to drive a device, you must perform the follow:;ng steps:

1. Thoroughly read and understand this manual.

2. Familiarize yourself in detail with the physical device and its operational characteristics.

3. Determine the level of support required for the device.

4. Determine actions to be taken at the driver entry points.

5. Create the driver source code.

You can write driver code for RSX-llM-PLUS that does one of the follow:,ng:

1. Supports standard functions and runs on RSX-llM-PLUS only.

2.

3.

Supports standard functions and is written so that compatible with use on both RSX-llM and RSX-llM-PLUS.

driver needs separate data bases for each system.) Supports advanced features and runs on RSX-llM-PLUS

(Although Chapter 1 discusses advanced features, this does not describe how to program advanced features.

best guide to utilizing advanced features is to DIGITAL-supplied driver as a model.)

it is (This only.

manual Your use a To assist you in generating proper code for your user-written driver and to provide a stable user-level interface from one release of the system to another, RSX-llM-PLUS provides the macro calls listed in Table 4-1.

The definitions of the system macro calls for drivers are in the Execut ve assembly prefix file RSXMC.MAC. The following subsections describe the format of the macro calls and other features of user-written driver code. Driver code details (such as labeling

requir.~ments and entry point conditions) are presented in Section 4.5.

4.3.1 Generate Driver Dispatch Table Macro Call - DDT$

The DDT$ macro call facilitates generation of the driver dispatch table. The format of the DDT$ macro call is as follows:

DDT$ dev,nctrlr,iny,inx,ucbsv,NEW,OPT,BUF

Table 4-2 lists the arguments of the DDT$ macro call. The macro constructs the DDT, using as addresses those locations indicated by the standard labels. The macro has arguments allowing you to tailor some of the standard entry points. The format of the DDT generated by the DDT$ macro is described in Section 4.5.1.

4-4

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER driver dispatch table containing the addresses of entry points in the order in which the Executive

interrupting device into R5 Table 4-2 generated for the controller.

If you specify an argument list of the form

<aaa,bbb, ••• >, the macro generates multiple cells containing addresses defined by unconventional labels of the form $xxaaa and $xxbbb. This latter mechanism allows you to define multiple interrupt entry points in the driver. For example, the argument list

<INP,OUT> generates two interrupt address labels of the form $xxINP and $xxOUT, the typical names used by drivers with two interrupt entry points.

(continued on next page)

Argunent

distinguishes between RSX-IIM-PLUS and RSX-IIM drivers. If you specify this argument (any character RSX-IIM unless the two routines are conditionalized.

If the argument is null, the macro generates code to use the xxPWF entry point for controller and unit on-line and off-line status changes.

opn indicates that the driver supports seek optimization.

Bur

RSX-IIM drivers implicitly handle controller and unit on-line and off-line status changes as power failures. Although this default operation (enabled by code generated from leaving this argument null) is not optimal for operation on RSX-IIM-PLUS, the driver will probably function properly without being changed to include the xxKRB and xxUCB entry

Argument instruction when the $GTPKT routine indicates that there is no I/O packet to process. If you leave this additionally generates the BCS instruction that returns control to the calling routine when there is no work. If you specify an address as

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

instruction is false, execution continues inline and the driver can process the I/O packet that the Executive queued to it. The $GTPKT routine leaves information in the driver registers to enable the driver to process the request. Refer to the description of the $GTPKT

routine in Chapter 7.

4.3.3 Interrupt Save Macro Call - INTSV$

You should specify the INTSV$ macro call at each interrupt entry point in the driver. The macro conditionally generates a call to the Executive $INTSV routine based on whether the driver is loadable. The format of the INTSV$ macro call is as follows:

INTSV$ dev,pri,nctrlr,pswsv,ucbsv

The arJuments of the call are described in Table 4-4. If the symbol LD$xx (where xx is the device mnemonic) is not defined, the macro generates the call to $INTSV and defines the priority at which the interrupt service routine will run. Not defining LD$xx indicates that the driver is resident. (For loadable drivers, the interrupt service routine in the Executive dispatches the interrupt.) For both loadable and resident drivers, however, the macro generates the code to load R5 upon ^a~ interrupt.

Argument

pri

nctrlr

ucbsv

Table 4-4

INTSVS Macro Call Arguments Meaning is the 2-character device mnemonic.

is the processor priority (PR4, PR5 or PR6) at which the device runs and at which the $INTSV coroutine will run.

is the number of controllers that the driver services (counting from 1).

is for compatibility with RSX-I1M drivers. If you are writing an RSX-1IM-PLUS driver, leave this argument nUll. If your driver is an RSX-I1M driver, this argument has no effect.

is for compatibility with RSX-1IM drivers. If you are writing a driver for RSX-IIM-PLUS, you should leave this argument nUll. The macro generates code which uses the controller index returned in R4 by $INTSV, calculates the KRB of the interrupting controller, and loads the UCB address of the interrupting unit into R5. For guidelines on specifying this argument, refer to Section 4.3.4.

4.3.4 Usage of UCBSV Argument in Macro Calls

The DD~$, GTPKT$, and INTSV$ macro calls allow you to specify an argument (ucbsv) that maintains compatibility with RSX-IIM drivers.

RSX-llH-PLUS does not need to utilize the ucbsv argument. The argument ucbsv in the DDT$ macro allocates nctrlr words of storage (one word for each controller that the driver supports) and labels the

4-8

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

first word ucbsv:. This storage is the CNTBL area used by RSX-IIM drivers to contain the address of the unit control block of the interrupting devices for each controller. Both the GTPKT$ and INTSV$

macro calls may use this same area. For more information concerning CNTBL, consult the RSX-IIM Guide to Writing an I/O Driver.

If you specify the argument ucbsv in the GTPKT$ macro call, i t must be the same label that you supplied for the ucbsv argument in the DDT$

and INTSV$ macro calls. The macro generates code to move the UCB address returned by $GTPKT to the correct location in the table starting at the label ucbsv.

If you specify the argument ucbsv in the INTSV$ macro call, it should be thE~ same label you supplied for the ucbsv argument in the DDT$ and GTPKT$ macro calls. The macro uses ucbsv to locate the UCB address of the interrupting unit, and then generates code to load the address into RS.

4.3.5 Specifying a Loadable Driver

To spec=ify that a driver is loadable and to enable generation of conditional code, you must define the symbol LD$xx. The definition can appear in either the driver source code or the assembly prefix file RSXMC.MAC. It is usually more convenient to define the symbol in the driver source code because you probably will not have cause to edit RSXMC.MAC. When the symbol is defined, the INTSV$ macro does not generate the call to $INTSV.

4.3.6 Loadable Driver Entry Points for LOAD and UNLOAD

A loadable driver that requires additional initialization and completion functions can define two entry points by labels of the form

$xxLOA and $xxUNL (where xx is the 2-character device mnemonic).

BeCaUSE! these two labels do not appear in the DDT itself, their format is fixed; you must use the exact format in your driver code. When you load the driver, the LOAD routines check for the $xxLOA entry point.

NOTE

The LOAD routines can perform this function only from MCR. If you attempt to load a driver that has the $xxLOA entry point from VMR, the load operation is terminated with the error message DRIVER REQUIRES RUNNING SYSTEM FOR LOAD/UNLOAD.

The driver is entered, once per UCB, at the $xxLOA entry point at priority zero. At this stage, the driver data base has been loaded and pointers have been relocated. The driver is mapped through APR 5, and the following registers are set up:

R3 Controller index (undefined if S.KRB 0) R4 - Address of the status control block

R5 - Address of the unit control block

The driver may use all the registers. When you unload the driver, the UNLOAD routine calls i t at the $xxUNL entry point with the same conditions.

PROGRAMMING SPECIFICS FOR WRITING AN I/O DRIVER

These wo entry points in the loadable driver are independent of the contro ler and unit status change entry points used by Executive reconf guration software. That is, the two entry points $xxLOA and

$xxUNL are used for initialization and completion at LOAD and UNLOAD time and not at on-line and off-line status change time.