EPICURE Software Release Note 137.2

VMS System Services for TVI Support

David M. Kline

This document shows the calling sequences for the TVI routines on the 80386 DAE processors with C as well as for use on the VAX under VMS. In addition, several VME Common Memory structures are outlined. See Epicure Design Note #6 for more information on Common Memory data structures and formats. Many similarities exist between the TURBOchannel and the QBus interfaces . Therefore, the release note was based on Epicure Design Note #3. Where applicable, text and data structure formats have been modified to accommodate the TURBOchannel interface. However, most of the document's content and structure remain similar to the design note. The reader is encouraged to review Epicure design note #126 for a complete description of the design and intention of the TURBOchannel interface and implementation.

Introduction

• Data transfers through the TVI are 32-bit longwords aligned on longword boundaries. This requirement permits the TVI to correct for the byte ordering differences between the 680X0 Motorola and the VAX architectures. With the change of the DAE processors to Intel 80386s, this becomes less important since the VAX and the 80386 use the same byte-order memory address model. However, still does not correctly handle longword or word accesses on unaligned byte addresses (the data is scrambled) so a set of VAX services is still required to isolate the TVI users from this deficiency. Since the Common Memory is directly accessible (as VMEbus memory) to the DAE processors, special data transfer routines are not needed there .
• Bus interlocks must be generated for Test and Set instructions to interlock access to the queues. Since the VAX test and set instructions do not generate interlocked TURBOchannel cycles, hardware on the TURBOchannel DWTVX is preset to turn a back-to-back pair of read/write TURBOchannel cycles into a single VMEbus cycle. To insure correct timing, these actions must be taken as an atomic operation and done at IPL 31 in the VAX to prevent any intervening interrupts from stealing CPU cycles. The assembly routines needed for the interlocking instructions on the DAE processors are embedded in the CM services and invisible to the DAE programmers.
• The TVI control registers in TURBOchannel I/O space and interrupt control registers in VME address space must be manipulated.
• The details of manipulating the queues in Common Memory used for interprocessor communications are hidden from the users of the services. In addition, the queue manipulations are done with a software lock on the queue and with the CPU interrupts disabled to insure timely completion of the queue operation. On the VAX this requires kernel mode services.
• The VMEbus Interrupt (VBI) module general purpose FIFO interrupt queues and signature ROM must be accessed .
• Provide transparency between QVI and TVI system services, requiring minimal modification to existing diagnostic applications and VAX-based server processes. In addition, transparency must be maintained between CM routine implementations between front end types.

The TVI services provide a means of encapsulating these needs and presenting a simpler interface to the Data Acquisition Server (DAS), the primary user of the TVI services. Transparency between QVI and TVI system services is maintained by related services residing at the same transfer address within the shareable image. The CM routines for the DAE processors provide a simple interface to the programmers and implement the same queue handling protocol as the TVI services. Similarly, 80386 DAE processors residing on QBus or TURBOchannel front ends maintain transparency by using indicators (flags) in the VAX return queue headers which select the means by which interrupts are generated.

The TURBOchannel Allocator (TCA) device driver was developed to manage TURBOchannel interface resources. A set of system services is available to hide the complexities associated with manipulating resources.

A special device driver on the VAX, the , is needed for handling the fielding of interrupts from the TURBOchannel interface. This driver was derived from the Digital Connect-to-Interrupt driver and the Epicure and is specifically designed to handle the TURBOchannel the DWTVX interface.

Descriptions of the TVI and CM Services

TVI_US

These user services are meant for most users.

TVI_CS

The TVI Core Services are meant for special and diagnostic applications.

TVI_ES

These are Extended Services which are only available for the TURBOchannel interface.

TCA_CS

These are the Core Services used by the TVI_CS to allocate, load, and release TURBOchannel interface resources .

TCI_US

These User Services are used by other TVI services to establish connectivity between the VAX return queue device and a VAX process.

Service routines for the DAE processors are based on a simple subset of the TVI_US routines called the CM (for Common Memory) routines. The CM routines return VMS status codes to indicate success or failure; input arguments are passed by value and output arguments have a pointer passed by value (standard C calling sequences). Furthermore, these routines are implemented to work for both QVI and TVI front ends.

Common Memory queues and blocks are referenced by ``handles'' which are either offsets relative to the start of the Common Memory or addresses within the Common Memory as mapped into the local process's virtual address space (VAS). In particular, the actual interpretation of the ``handles'' returned by the TVI_US routines is unimportant to the users of the TVI_US routines. This does not hold true for the TVI_CS routines where the documentation specifies whether a particular ``handle'' is an actual address or an offset. The CM routines use 32-bit VMEbus addresses for Common Memory structures (normal startup of the 80386 DAE processors must setup for a 4 Gigabyte linear address space).

Common Memory Block Format

This structure is called a CMB for Common Memory Block. The CMB consists of two concatenated structures: the UMB contains the fields of importance to users, the CMH is the Common Memory Header containing information used only by the TVI services and the DAE modules. The fields of the UMB and CMH which are common to all types of CMBs are: list [cmb_r_cmh] This structure contains the header fields of the CMB: list [cmh_l_link] This longword is the queue link. It contains a pointer to the next entry in the queue or a 0 if this is the tail entry. Normally this field is only of concern to the TVI and CM routines. [cmh_l_rtnqid] This longword is set to the queue handle (qhdl) for the VAX return queue associated with the user process. The return qhdl is used to return the CMB to the originator upon completion of the actions requested by the CMB contents. [cmh_l_orgid] This longword contains the same value as the rtnqid longword for normal return queues. Such queues are normally associated with an interrupt attached to the destination process on the VAX or are polled by that process. If the return queue used is the multiplexed return queue, then the value in this longword is used by the process to locate the true destination process and its return queue (see the information on the Queue Demultiplexing Block below). [cmh_l_diqhdl] This longword contains the handle of the DAE input queue. The TVI_US_GET routine uses this field to route the CM block to its destination queue if it is to be recycled. The queue handle is taken from the QIB which specifies the default DAE input queue. Applications can override the default queue by specifying the altdiq parameter of the TVI_US_PUT routine.

[cmb_r_umb] This structure is the portion of the CMB manipulated by the user of the TVI or CM services. The fields of the UMB are: list [umb_l_flags] This is a bit-vector of flags in a longword. The lowest bit (bit 0) is used as the CYCLE bit. If this bit is 1, when the CMB is removed from the VAX return queue it is placed back on the default processing queue rather than released to the free queue (cycled for another processing pass).

Bit 1 is used by the DAE processors as the first time flag ( 1ST_TIME). This flag is used by the DAE Timer processor on cyclic requests to flag the first cycle (or the first time that the Timer has seen this request).

Bits 2-4 are used by the DAE Timer processor to support fast time plot control and data buffer processing and expunges. [umb_w_type] This word contains an identification code describing the data contents of this UMB and is of direct concern to the users of the TVI and CM routines. [umb_w_reqsiz] This word contains the requested UMB size in bytes. This may not be the actual size of the UMB (or enclosing CMB); there may be unused bytes (internal fragmentation) between the end of the data and the actual end of the UMB. [umb_r_data] This is the start of the data field of the UMB. The format and contents of this portion of the UMB are specific to the block type defined by the Common Memory user. The cmh_l_rtnqid field is sometimes of concern to the DAE programmer. This field identifies the return queue of the ``originator'' of the message and is sometimes used if the request is fatally flawed and cannot be processed. In this case, the return queue identifier is used to route the request immediately back to the originator, usually with the CYCLE bit cleared and a error status someplace in the data fields.

CMB Structure Definitions

There C structure definitions reflect those in (see below). The definition of the UMB0 structure is given here as a prototype definition for the user block. Common Memory users should supply their own definitions, replacing the umb_r_data field with definitions specific to their applications.

struct CMH {
    unsigned long cmh_l_link;
    unsigned long cmh_l_rtnqid;
    unsigned long cmh_l_orgid;
    unsigned long cmh_l_diqhdl;
    };

struct UMB0 {        /* Prototypical definition */
    unsigned long umb_l_flags;
    unsigned short umb_w_type;
    unsigned short umb_w_reqsiz;
    unsigned long umb_r_data[2];
    };
  
#define  UMB_M_CYCLE     0X00000001
#define  UMB_M_1ST_TIME  0X00000002
#define  UMB_M_SUSPEND   0X00000004
#define  UMB_M_AVAILABLE 0X00000008
#define  UMB_M_EXPNDG    0X00000010

struct CMB {
    struct CMH cmb_r_cmh;
    struct UMB0 cmb_r_umb;
    };

Multicast Block Format

The multicast message is sent to the first DAE processor with a non-zero Queue Table entry. The Queue Table Index (QTI) for this entry is stored in the multicast message. Each destination picks up the current QTI from the multicast message and begins searching the Queue Table from that point forward (towards the end of the Queue Table) for the next non-zero entry which will be the next destination of the multicast message. When the end of the Queue Table is reached, the multicast message is returned via the return queue handle in the CMB header.

Locating the TVI Files and Linking With the TVI Services

The TVI routines in the shareable image can be linked to by adding to the command line:

    $ link  ...,tvi_inc:tvilink/options,...

!
! Linker options file to link the TVI system services and
! VAX C RTL shareable images. Include general VAX-support
! routines in FERMILIB.
!
RDCS$LIB:FERMILIB/LIBRARY, -
EPICURE_ROOT:[WORK.TVI.USS]TVIUSS.EXE/SHARE,-
SYS$SHARE:VAXCRTL.EXE/SHARE

The TVI procedure also defines the logical name which specifies the current location of the object code files for the 80386 (file types ). The available files are: list [CMQLOCK] Contains the queue lock routines with the Test and Set instructions. Must be linked with all DAE system software. [CMQ] Contains the basic CM routines for manipulating the Common Memory queues. Must be linked with all DAE system software. [CMQGET] Contains the optional CM routines used if the DAE system will be generating unsolicited requests and so needs access to the free list queues. [CMQPOOL] Contains the optional CM data pool services for locating a Common Memory DataPool and locking or unlocking a DataPool.

VAX TVI User Services

TVI_US_DAP$LOCATE

TVI_US_DAP$MULTICAST

TVI_US_GET

TVI_US_INIT

TVI_US_LOCATE

TVI_US_MODFLG

TVI_US_PUT

TVI_US_RESINM

TVI_US_TEST

TVI Core Services

TVI_CS_CM2VAX

TVI_CS_CREAA

TVI_CS_CREQH

TVI_CS_DAP$MULTICAST

TVI_CS_GET

TVI_CS_INIT

TVI_CS_INSQT

TVI_CS_INTERRUPT

TVI_CS_LOCATE

TVI_CS_LOCKCM

TVI_CS_LOCKPOOL

TVI_CS_MAKECM

TVI_CS_MAKEFQT

TVI_CS_MAPCM

TVI_CS_MODIFLAGS

TVI_CS_POOLPOINTER

TVI_CS_PUNCHVME

TVI_CS_PUT

TVI_CS_REMQH

TVI_CS_RESETVME

TVI_CS_SHUTDOWN

TVI_CS_STATUS

TVI_CS_TEST

TVI_CS_TOUCHVME

TVI_CS_UNLOCKPOOL

TVI_CS_VAX2CM

TVI_CS_VMEADRMOD

TVI_CS_VMEMAP

TVI_CS_VMEPOINTER

TVI_CS_VMEWINDOW

TVI_ES_ALOVMEWIN

TVI_ES_GENINT

TVI_ES_MAKSEC

TVI_ES_RELVMEWIN

TVI_ES_RESETVME

TCA Core Services

The TCA Core Services are intended for VAX based applications that want to map VME address space into P0 or P1 process space. The services are primarily used by other TVI system services, or initialization & diagnostic applications that want map portions of VME address space.

TCA_CS_ALOVME_DMA_PMR

TCA_CS_ALOVME_PIO_PMR

TCA_CS_COPY_DDB

TCA_CS_DISINT

TCA_CS_ENAINT

TCA_CS_EXIT

TCA_CS_INIT

TCA_CS_READ_AIB

TCA_CS_READ_DDI

TCA_CS_READ_PIO_PMR_STATUS

TCA_CS_RELVME_PERM

TCA_CS_RELVME_PMR

TCI User Services

The TCI User Services are primarily used by the TVI initialization services to establish connectivity between a VME interrupt vector and VAX process.

TCI_US_CONNECT

TCI_US_EXIT

TCI_US_INIT

TCI_US_READ_ALL_VEC

TCI_US_READ_VEC

TCI_US_RESINM

Basic Services for 80386 Code

cm_dapmcast

cm_dapqloc

cm_insqt

cm_locate

cm_remqh

cm_tstq

Additional 80386 Services

These CM services are an optional addition to those listed above. Normally, the DAE processors receive requests from the VAX and pass responses back to the VAX in the same CMB as the request arrived in. In order to allow the DAE processors to generate unsolicited messages, these additional routines interface the DAE processors to the free block lists in the Common Memory. These routines assume that the VAX will be the sink for these messages and depend on the VAX to restore the exhausted block to its free list.

cm_get_block

cm_get_init

cm_lockpool

cm_poolpointer

cm_unlockpool

CM Initialization

1. Read a text file of parameters using the logical name . The format of this file is described below.
2. Create a permanent global section named if not already present. The global section is created using PFN (Page Frame Number) mapping of the TURBOchannel addresses used for the main CM window. In either case, map the global section into current process VAS P0 region.
3. Create a permanent global section named if not already present. The global section is created using the PFN extract from the base hardware address of the TURBOchannel adapter. Furthermore, the TURBOchannel adapter registers are initialized to the VMEbus configurations: to and arbitration.
4. Create a permanent global section named if not already present. The global section is created by using the PFN returned by the identifying the VAX window into the VMEbus address space of the VBI. The VBI FIFO interrupt queues are flushed and the QFULL registers are initialized.
5. Zero all of the VME memory module locations (including the entire Common Memory region).
6. Initialize the CM global area locations and build the CM queue headers, allocation area descriptors and other fixed structures.
7. Initialize CM free queues and place all the CM blocks on their respective free queues.

Format of Parameter Descriptions

     SYS_STARTUP:CM_PARAMETERS.INI

 
    parameter-name[/qualifier(s)]  value[,value...]

TCCMInitializer Parameters

Note, and are mutually exclusive and only one can be used on a given BLOCKS command. Similarly, only a single BLOCKS command in a parameters file can use the qualifier. [CLEARMEMORY size] Specifies the amount of memory in the VME memory module to be cleared to zeroes. Size is given in Kbytes. [DATAPOOL n size] Specifies that DataPool number n is to be initialized with a size of size bytes. [EXIT] Terminates parameters command file. [LDD name] Specifies the node name whose Listener Data Descriptor (LDD) is to be setup. The ``DEFS'' string is passed as the name parameter to specify defaults values. The defaults are used if a particular qualifier isn't specified for a given name, or if the current node doesn't match any of the names defined by the LDD command. Furthermore, ``DEFS'' be specified before any other LDD command definitions. list [/ID=number] Specifies the Listener ARCnet node number (0-255). [/DAE=number] Specifies the number (0-255) of seconds that must elapse before the DAE data is considered stale. [/FTP=number] Specifies the number (0-255) of seconds that must elapse before the FTP data is considered stale.

[MUXQUEUE name] Specifies the name of the multiplexed return queue (if any). [QUEUE name] Defines a named queue whose header is to be setup. Queue names are alphanumeric symbol names (``$'' and ``_'' permitted). The case of the queue name is unimportant as all the queue names are kept in uppercase. list [/EXTERNAL=number] Specifies the bit number of a TVI external interrupt associated with this queue. This interrupt is generated by writing a 1 to the selected bit number in a register. [/DEMUX] Specifies that this is a VAX return queue fed via the multiplexed return queue and the process. [/NONE] No interrupt is associated with the queue (normally used only for free list queues or input queues watched by a polling algorithm). [/DEVICE=device] Specifies the name of a VAX device with the TCI driver for handling interrupts for this queue. Used for input queues for VAX processes only. [/DAP_INDEX=number] Specifies that this queue is to be entered in the DAP queue table at the specified index number. [/IRQ=number] Specifies the VMEbus Interrupt Request Number (IRQ) number for this particular VAX return queue. If not specified, IRQ defaults to value as defined by the symbol TVI$B_RIQ_INIT. [/VECTOR=vector] Specifies the interrupt (IRQ) vector that activates the VAX return queue. Value is specified in hexadecimal. Normally, this is determined by reading the vector directly from the device. Specifying this value overrides the one read from the device. Valid vector range is . Only one of the qualifiers , and , , or may be present ( is taken by default if no qualifier is present). The and qualifiers are not allowed with (either an explicit or one implied by default) or . The qualifiers , , , or are not allowed with . In addition, and are not allowed together.

[RESET] Generate a VME bus reset. [SET keyword] Select an option: list [CHECK_ONLY] Read and validate the parameters, but do not actually initialize the CM. [VERIFY] List the commands as they are read. [TEST_MODE] Used for testing CMI.

[SHOW keyword] Select an output option: list [BUILD] Show details during the initialization of the Common Memory. [PARAMETERS] Show a table of the initialization parameters after the commands are read and before the CM is initialized. [SUMMARY] Show a summary of the initialization operations. [SIZE Kbytes] Specifies the size of the CM in Kbytes.

The following is an example of a command procedure used to initialize the Common Memory. The first part of the procedure defines the logical names which TCCMI will cross-check against its input parameters.

$ DEFINE := DEFINE /NOLOG
$!
$! Define logical names to identify default queue to send packets to
$! Data Acquisition Engine and to hold packets incase of INSQ failures.
$!
$ DEFINE /SYSTEM	RDCS$QVI_DAE_QUEUE	TIMER
$ DEFINE /SYSTEM	RDCS$QVI_WASTE_QUEUE	$TOXIC$
$!
$! Define logical names for VAX devices associated with CM queues used
$! as "input" to VAX processes; devices are used with Connect-to-Interrupt.
$!
$ DEFINE /SYSTEM	RDCS$QVI_VAXQ_DASRET	VAXQA0:
$ DEFINE /SYSTEM	RDCS$QVI_VAXQ_TSRET	VAXQB0:
$ DEFINE /SYSTEM	RDCS$QVI_VAXQ_HERMES	VAXQC0:
$ DEFINE /SYSTEM	RDCS$QVI_VAXQ_FEEDER	VAXQF0:
$ DEFINE /SYSTEM	RDCS$QVI_VAXQ_ECHOBACK	VAXQG0:
$!
$! Initialize the common memory with parameters in the specified file.
$!
$ SET PROCE/PRIV=("CMKRNL,DIAGNOSE,PSWAPM,PRMGBL,SYSGBL,PFNMAP,SYSLCK")
$ DEFINE /USER_MODE  CM_PARAMETERS   SYS$INPUT
$ RUN TCCMI
reset
address %XE0000000 /cm                 !CM VME card address
address	%XD0000000 /vbi /vax=0 /vme=1  !VMEbus Interrupter Module address
size    3072                           !Use 3 MB of memory
clear   4096                           !Clear all 4 MB of memory
!
! Queues for free lists:
!
queue	$256 /none
queue	$1K /none
queue	$4k /none
queue	$8k /none
queue	$16k /none
queue	$tiny /none
blocks	$16k /size=16384 /count=50
blocks	$8k /size=8192 /count=80
blocks	$4k /size=4096 /count=150
blocks	$1k /size=1048 /count=300
blocks	$256 /size=280 /count=500
blocks	$tiny /size=128 /available
!
! Listener parameters:
! The defaults MUST be defined first!
!
ldd     defs    /id=1 /dae=120 /ftp=120 !Setup listener defaults
ldd     huey    /id=1                   !For HUEY
ldd     dewey   /id=2                   !For DEWEY
ldd     louie   /id=3                   !For LOUIE
ldd     webby   /id=4                   !For WEBBY
!
! Action queues:
!
queue   $toxic$  /none
queue   dasret   /device=vaxqa0:                !DAS return queue
queue   tsret    /device=vaxqb0:                !TS return queue
queue   camac    /external=1 /dap_index=2       !CAMAC module's queue
queue   timer    /external=0 /dap_index=1       !Timer module's queue
queue   Hermes   /device=vaxqc0: /irq=5 /vector=%XFC !Message handler queue
exit
$ EXIT

Internals

Logical Names

Another set of logical names of the form are used to specify special-purpose devices and associate them with registers. The variant encapsulated in the logical identifies the specific QFULL register.

TCADRIVER

VMEbus resources are managed by the device driver. The TVI system services assign to the main TCA device to request allocation, initialization, and releasing Programmed I/O (PIO) & Direct Memory Access (DMA) page map registers (PMRs). The internal formats and complexities of the requests are hidden from the user by the TCA system services. The TCA device is initialized and established by a startup command procedure:

$ RUN SYS$SYSTEM:SYSGEN
!
! NOTE: The below driver is implemented as a 'cloned'
!       device driver and requires NO /VECTOR qualifier
!
CONN TCAA0/ADAP=2/DRIV=RDCS_TVI:TCADRIVER
!
!
EXIT
$ EXIT

Loading the device initializes the TURBOchannel adapter data structures and prepares the device for requests. When users assign the device, a ``clone'' device is created. Each request for a set of PIO or DMA PMRs creates a new TCA device. When the user's image exits, the ``cloned'' device is deleted and all VMEbus resources allocated are then released .

TCIDRIVER and VAX Interrupt Devices

$ RUN SYS$SYSTEM:SYSGEN
!
! NOTE: The /VEC establishes connectivity between
!       TVI message queues and VMS processes
!
CONN VAXQA0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%X10
CONN VAXQB0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%X20
CONN VAXQC0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%X30
CONN VAXQD0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%X40
CONN VAXQE0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%X50
CONN VAXQF0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%X60
CONN VAXQG0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%X70
CONN VAXQH0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%X80
!
! NOTE: The below devices are viewed as the VBI Q full
!       notification queues. The VQMonitor process assigns
!       to them and waits for the interrupt from the VBI.
!
CONN VAXQW0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%XF0
CONN VAXQX0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%XF4
CONN VAXQY0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%XF8
CONN VAXQZ0/ADAP=2/DRIV=RDCS_TVI:TCIDRIVER/VEC=%XFC
EXIT
$ EXIT

A process that assigns to a device is eligible for interrupts initiated from VMEbus given the corresponding vector as specified in the command. The TCI system services use the I/O function code (same function code as used by the VMS Connect-to-Interrupt Driver supplied by Digital) to initialize the connectivity.

The following is a short description of calling the . Serious users are directed to the description of the VMS Connect-to-Interrupt driver in the VAX/VMS Device Driver manual.

status = SYS$QIO( [efn], chan, func, [iosb], [astadr], [astprm], [p1], [p2], [p3], [p4], [p5], [p6])

The standard VMS $QIO system service when used with the takes the following arguments. Note that there is a distinction between the completion of the I/O operation and device interrupts. The $QIO call can be setup to receive a single interrupt and then have the I/O request complete. A more normal mode of operation, as used by the TVI_US routines, is to have multiple device interrupts reported without the I/O request completing. efn number of event flag set on completion of the I/O request. Passed by value. chan channel number assigned to one of the devices using the $ASSIGN system service. Passed by value. func I/O function code of IO$_CONINTREAD. Passed by value. iosb I/O status block set on completion of the I/O request. Passed by reference. astadr AST routine called upon completion of the I/O request. Passed by reference. astprm parameter for the I/O completion AST. Passed by value. p1 this parameter is ignored by the . Passed by value. p2 optionally specifies the interrupt level number if the flag in the p3 argument. Passed by value. p3 longword containing flags and an optional event flag number. This event flag is set on each device interrupt (as distinct from the efn parameter above). Passed by value. p4 AST routine called on each device interrupt (address of routine's entry mask). Passed by reference. p5 AST parameter to be passed to the device interrupt AST specified in p4. Passed by value. p6 number of AST control blocks to preallocate in anticipation of fast, recurrent interrupts from the device. Passed by value. status returns a VMS condition code: SS$_NORMAL success. SS$_BADPARAM number of preallocated AST control blocks in the p6 argument exceeds 65535. SS$_DISCONNECT a connection is already outstanding for the device or the driver cannot reallocate AST control blocks quickly enough. SS$_EXQUOTA process has exceeded its direct I/O limit quota or its AST limit quota. SS$_ILLEFC an illegal event flag number was specified. SS$_INSFMEM insufficient system dynamic memory is available to complete the system service. SS$_UNASEFC the process is not associated with the cluster containing the specified event flag.

list [CIN$M_EFN] set event flag on interrupt. [CIN$M_USECAL] p2 parameter contains the interrupt level number. [CIN$M_REPEAT] leave process connected to the interrupt vector until the connection is canceled and repeatedly report interrupts for this single I/O operation. [CIN$M_AST] queue p4 AST routine on interrupt. [CIN$M_EFNUM] high-order word specifies the number of the event flag to be set when an interrupt occurs.

KerrMcGee Process

This detached VMS process is planned to monitor the integrity of the Common Memory and the ``toxic waste'' queue in particular. Currently, only updates the time-of-year clink value in the Common Memory global area approximately every 21 minutes to keep the value in synchrony with the VAX system time.

DeMuxer Process

This detached VMS process has the multiplexed queue as its input queue. When an entry is made on this queue, is awakened by an interrupt and proceeds to empty the queue. As each entry is removed, the originator identifier in the CM block is used to locate the Queue Demultiplexing Block (QDB, see below) which contains a pointer to the true destination queue for the CM block. The QDB also identifies the VMS process associated with this return queue; simulates an interrupt to this process by using the Declare External Process AST routine in the Epicure System Services (ESS).

DAE Event Monitor (DEM) Process

This detached VMS process monitors activity on the VAX return queue. Messages which appear on the queue indicate that an exception occurred on one of the processors. When a message appears on the queue, is awakened by an interrupt and proceeds to empty the queue. The data within the message is translated, logged to a file, and sent to the VMS process. In addition, it's intended that these messages be integrated into the Epicure alarm system .

VBI Q Monitor (VQMonitor) Process

This detached VMS process responds to interrupts from the module when the FIFO interrupt queues reach the half full point. For each FIFO interrupt queue, a device exists that is used to signal when the queue has reached it's half full mark. When this occurs, the process is notified and logs a message to a file. In addition, it is intended that these messages be integrated into the Epicure Alarm System.

Queue Organization, Queue Headers and Queue Operations

The fields of the CM queue header are: list [cqh_b_lock] Lock byte. The LCK bit is used to lock the queue during manipulations (by a on the VAX, a the 68020 and a on the 80386). list [CQH_V_LOCK] Offset to the lock bit in the lock byte.

[cqh_b_flags] Byte of bit flags: list [CQH_V_INT] Offset to the INT bit. This bit is set if an interrupt is associated with the queue (thus the cqh_l_intid field contains valid information). [CQH_V_EXT] Offset to the EXT bit. This bit indicates whether the interrupt is an external interrupt (EXT=1) or an interrupt triggered by touching a VME address (EXT=0). The EXT bit thus describes the contents of the cqh_l_intid field. Used only by QVI front ends. [CQH_V_MUX] Offset to the MUX bit. This bit indicates that the VAX return queue is fed via the multiplexed return queue and the process. [CQH_V_TC] Offset to the TC bit. This bit indicates whether the VAX return queue is configured for the VBI module. Used only by TURBOchannel front ends. [CQH_V_WRD] If set, a word instruction to the specified VME address is used to generate the associated interrupt. [CQH_V_DAS] Obsolete.

[cqh_l_headp] Offset to entry at head of queue. [cqh_l_tailp] Offset to entry at tail of queue. [cqh_w_curcnt] Count of current queue entries. [cqh_w_maxcnt] Count of maximum number of entries on queue since initialization (or last reset). [cqh_l_intid] Interrupt descriptor that identifies the external or vectored interrupt(s) to generate. If the bit is set, this value is written to the VBI module. [cqh_q_name] Queue name given as uppercase characters, padded with blanks. [cqh_l_putcnt] Unsigned count of the insert operations performed to the queue since the counter was zeroed (initially zeroed at CM initialization).

/*
 As seen by the VAX and the 80386:
*/
struct CQH {
    unsigned char cqh_b_lock;
    unsigned char cqh_b_flags;
    unsigned : 16;
    unsigned long cqh_l_headp;
    unsigned long cqh_l_tailp;
    unsigned short cqh_w_curcnt;
    unsigned short cqh_w_maxcnt;
    unsigned long cqh_l_intid;
    unsigned long cqh_q_name[2];
    unsigned long cqh_l_putcnt;
    };

/*
 As seen by the 68020:
*/
struct CQH {
    unsigned : 16;
    unsigned char cqh_b_flags;
    unsigned char cqh_b_lock;
    unsigned long cqh_l_headp;
    unsigned long cqh_l_tailp;
    unsigned short cqh_w_maxcnt;
    unsigned short cqh_w_curcnt;
    unsigned long cqh_l_intid;
    unsigned long cqh_q_name[2];
    unsigned long cqh_l_putcnt;
    };

/*
 Common to all processors:
*/
#define CQH_V_LOCK  7
#define CQH_M_LOCK  0X80
#define CQH_V_INT   0
#define CQH_M_INT   0X01
#define CQH_V_EXT   1
#define CQH_M_EXT   0X02
#define CQH_V_MUX   2
#define CQH_M_MUX   4
#define CQH_V_TC    3
#define CQH_M_TC    8
#define CQH_V_WRD   6
#define CQH_M_WRD   0X40
#define CQH_V_DAS   7
#define CQH_M_DAS   0X80

1. The queue reserve lock is set. This is done with a instruction on the 68020 against the lock byte of the queue header at offset CQH_B_LOCK. The 80386 uses a byte instruction with the prefix on that same byte with the register loaded with (this may change in the future to a instruction). The VAX sets the reserve lock with the instruction (Interlocked Branch on Bit Set and Set bit) on the bit at offset in the lock byte at offset . The offsets will be defined so that the , and instructions are manipulating the same bit in the Common Memory.

   Before the VAX issues the instruction, the TVI is preset to stretch the VMEbus cycle since the results in separate read and write TURBOchannel bus cycles. The TVI preset will keep the VMEbus busy until the next write operation (the write cycle from the in this case).

2. The requested queue operation (insert entry at tail or remove entry from head) is performed by updating all the affected pointers.
3. The counters (current and maximum number of entries, count of queue inserts) are updated.
4. The queue reserve lock is cleared by clearing the lock byte with a Clear Byte instruction.

VAX Structures

VMEbus Interrupter (VBI) Structures

The module is mapped to the global section and allows processes to access them through the TVI system services. This section describes the data structures that represent the module registers:

The structure displays the format of all general purpose queues and provides the necessary fields in order to generate external or VMEbus interrupts.

struct TVI_VBI_QENTRY
    {
    variant_union
        {
        unsigned int data;
        variant_struct
            {
            unsigned char vector;
            unsigned level : 3;
            unsigned : 5;
            unsigned short trigger;
            } $qentry_members;
        } $qentry_overlay;
    };

The structure fields can be described as follows:

list [vector] This field is the VMEbus vector that gets placed on the VMEbus during an interrupt acknowledge cycle. Interrupts must be enabled in order for the DWTVX interface to service the interrupt. This is performed by the application. Valid TURBOchannel interrupt vectors are . [level] This field works in conjunction with the field and specifies the level to generate the interrupt. Valid interrupt levels are . [trigger] This field specifies which external interrupt to trigger given the bit position. Multiple bits can be specified generating simultaneous external interrupts.

The structure displays the format of the registers used to generate VMEbus interrupts when the corresponding queue reaches its half full mark. Only vectored interrupts can be generated. Below describes the registers format.

struct TVI_VBI_QFULL
    {
    variant_union
        {
        unsigned int data;
        variant_struct
            {
            unsigned char vector;
            unsigned level : 3;
            unsigned : 1;
            unsigned q : 1;
            unsigned : 1;
            } $qentry_members;
        } $qentry_overlay;
    };

The structure fields can be described as follow:

list [vector] This field is the VMEbus vector that gets placed on the VMEbus during an interrupt acknowledge sequence. Interrupts must be enabled in order for the DWTVX interface to service the interrupt. This is performed by the application. Valid TURBOchannel interrupt vectors are . [level] This field works in conjunction with the field and specified the level to generate the interrupt. Valid interrupt ranges are . [q] This field specifies which FIFO queue will perform the interrupt. Valid queue numbers are .

Both structures and describe the formats used by the FIFO queues used to generate external and VMEbus interrupts for general purpose and specific use. The module registers are viewed by the VAX as linear addresses and not all registers are part of the current implementation. Below describes the format of the module as viewed by the system services given the current implementation:

struct TVI_VBI_IO {
    struct TVI_VBI_QENTRY q0_entry;
    struct TVI_VBI_QENTRY q1_entry;
    unsigned int q0_flush;
    unsigned int q1_flush;
    struct TVI_VBI_QFULL q0_full;
    struct TVI_VBI_QFULL q1_full;
    };

The fields which are relevant to the implementation are described below: list [q0_entry] This fields represents the general purpose FIFO interrupt queue zero that is used for interrupts from the VAX. [q1_entry] This fields represents the general purpose FIFO interrupt queue one that is used for interrupts from VMEbus. [q0_flush] Writing to this location clears the contents of . This action is performed only at CM initialization. [q1_flush] Writing to this location clears the contents of . This action is performed only at CM initialization. [q0_full] An interrupt descriptor is written to this location to generate an interrupt when has reached its half full mark. The VAX-based process will be notified by this interrupt. [q1_full] An interrupt descriptor is written to this location to generate an interrupt when has reached its half full mark. The VAX-based process will be notified by this interrupt.

TURBOchannel DWTVX Registers

The registers supported by the TURBOchannel DWCTX interface are mapped to the global section and allow TVI system services to access them. Although many registers exist, this section will describe only the registers that are used by the TVI system services.

The structure represents the contents of the global section. Only the registers that are used by the TVI system services are provided:

struct TVI_MVME_IO
    {
    unsigned char PROM[0X40000];
    struct TVI_MVI_CSR MVI_CSR;
                :
                :
    struct TVI_VIC_VICR VIC_VICR1;
    struct TVI_VIC_VICR VIC_VICR2;
    struct TVI_VIC_VICR VIC_VICR3;
    struct TVI_VIC_VICR VIC_VICR4;
    struct TVI_VIC_VICR VIC_VICR5;
    struct TVI_VIC_VICR VIC_VICR6;
    struct TVI_VIC_VICR VIC_VICR7;
                :
                :
    unsigned int VIC_ICR1;
    unsigned int VIC_ARCR;
                :
                :
    unsigned int VIC_RCR;
                :
                :
    unsigned int VIC_SRR;
    };

The fields which are relevant to the implementation are described as follows:

list [PROM] This area provides the TURBOchannel ROM header that contains information to determine if the option module exists. The information contained is probed by the TVI system services. The data contained is pattern fields, firmware version, vendor name, firmware type, and a flag field. [MVI_CSR] The DWTVXB interface command/status register. Consult the ``TURBOchannel-to-VME IO Subsystem Technical User's Guide'' for a complete description of this register. [VIC_VICR1..VIC_VICR7] Provides enabling as VMEbus interrupt handler for the corresponding interrupt level. [VIC_ICR1] VMEbus interface configuration register. A general purpose read/write register defining how operations are performed. [VIC_ARCR] This register provides configuration of the arbitration mode. When set, priority arbitration is used. When clear, round-robin arbitration is used. This register is configured for priority arbitration. [VIC_RCR] This register configures the VMEbus release mode. This register is configured for mode. [VIC_SRR] The system reset register provides the means to generate a VMEbus . Writing the value of causes this function to occur.

The structure represents the corresponding to the VMEbus interrupt levels. Assigning appropriate values to the individual members enables or disables the TURBOchannel DWTVB module as a VMEbus interrupt handler. Below indicates the format of the registers and describes the fields which compose the structure:

struct TVI_VIC_VICR
    {
    variant_union
        {
        unsigned int data;
        variant_struct
            {
            unsigned IPL: 3;
            unsigned : 4;
            unsigned interrupt_enable: 1;
            unsigned : 24;
            } bit_defs;
        } data_overlay;
    };

list [IPL] Is an encoded IRQ level and used for systems with 680X0 processors. [interrupt_enable] VMEbus interrupt mask. When clear, the DWCTX acts as interrupt handler for the corresponding interrupt level.

Common Memory Descriptor

A CM descriptor occupies 16 longwords (64 bytes). The CM descriptor basically describes the TVI and CM global sections as mapped into a process (each process has its own CM descriptor). The format of a CM descriptor is:

The fields of the CM descriptor are: list [cmd_l_check] Longword with validation check value. Used to validate CM descriptor as initialized. [cmd_a_base] Pointer to base of the CM global section as mapped into the process's virtual address space (VAS). This pointer, like all non-system space virtual addresses, is valid only for a the current process. This field also holds the pointer to the base of the ``roving'' VME window section created by the TVI_CS_VMEWINDOW service (see below). [cmd_a_mvi] Pointer to global section as mapped by this process. [cmd_a_top] Address of the top of the CM global section. [cmd_a_cqhbot] Pointer to the CM queue header array in the CM global section. Used to validate queue handles. [cmd_a_cqhtop] Pointer to end of the CM queue header array in the CM global section. Used to validate queue handles. [cmd_a_baabot] Pointer to the base of the CM block allocation areas in the CM global section. Used to validate block handles. [cmd_a_baatop] Pointer to the top of the CM block allocation areas in the CM global section. Used to validate block handles. [cmd_a_itwmr] Pointer to the TVI map register used for the ``transient'' window by the TVI services. A primary use of this window will be to trigger interrupts which require the touching of specific VME addresses. This window will be moved (at elevated IPL) to map the VME address to be touched. This field is unused by TURBOchannel front ends. [cmd_a_itw] Pointer to the ``transient'' window address range as mapped into the virtual address space of the VAX process. See the above explanation for cmd_a_itwmr. This field is unused by TURBOchannel front ends. [cmd_a_viq] Virtual address of the VBI FIFO interrupt queue used by VAX processes to generate interrupts. [cmd_a_csr] Virtual address of the TURBOchannel CSR used by VAX processes to preset for operations. [cmd_a_vbi] Virtual address of the VBI module. [cmd_l_exitsts] This field overlays cmd_a_top in the variant Common Memory descriptor procedure by the TVI_CS_VMEWINDOW routine. This field stores the exit status for the internally-declared exit handler used to release the lock on the ``roving'' VME window. [cmd_l_vwba] This field overlays cmd_a_cqhtop in the variant Common Memory descriptor produced by the TVI_CS_VMEWINDOW routine. This field stores the VME base address of the TVI window. It is setup by the TVI_CS_VMEMAP routine and used in the TVI_CS_VMEPOINTER routine. [cmd_r_ehblk] This is the exit handler block passed to the $DCLEXH system service by the VME_CS_VMEWINDOW routine to setup the internal exit handler.

struct CMDescriptor {  /* Normal format */
    unsigned long cmd_l_check;
    address cmd_a_base;
    struct TVI_MVME_IO *cmd_a_mvi;
    address cmd_a_top;
    struct CQH *cmd_a_cqhbot;
    struct CQH *cmd_a_cqhtop;
    address cmd_a_baabot;
    address cmd_a_baatop;
    unsigned short *cmd_a_itwmr;
    address cmd_a_itw;
    address cmd_a_viq;
    address cmd_a_csr;
    address cmd_a_vbi;
    };

struct CMDescriptor {  /* VMEWINDOW variant */
    unsigned long cmd_l_check;
    address cmd_a_base;
    struct TVI_MVME_IO *cmd_a_qvi;
    unsigned long cmd_l_exitsts;
    unsigned short *cmd_a_mapreg;
    unsigned long cmd_l_vwba;
    address cmd_a_baabot;
    address cmd_a_baatop;
    unsigned short *cmd_a_itwmr;
    address cmd_a_itw;
    struct {
      address ehb_a_link;
      unsigned long (*exit_handler)();
      unsigned long ehb_l_argcnt;
      unsigned long *ehb_a_exitsts;
      unsigned long ehb_l_lockid;
      } cmd_r_ehblk;
    };

Queues Information Block

The Queues Information Block (QIB) contains process-specific information on Common Memory queues. An internal copy is maintained by the TVI_US routines and passed in the calling sequences of the TVI_CS_GET and TVI_CS_PUT routines. The fields of the Queues Information Block are:

list [myqh] Pointer to the CM queue header for the VAX return queue for this process. Used as the default return queue by TVI_CS_GET. Used by TVI_CS_PUT to set the return queue handle in CMBs put onto DAE queues. If the multiplexed queue is used, then this points to the real return queue for this specific process (queue without interrupts). [retqh] Pointer to actual CM return queue. If the multiplexed return queue is not used, then this has the same value as myqh, otherwise it points to the input queue of the process. [myid] Longword containing this process's originator identifier to be placed in CMBs put on DAE queues. If the multiplexed return queue is being used, then this is a pointer to the Queue Demux Block (QDB) in the CM for this process. If a normal return queue is used, then this has the same value as myqh. [daeqh] Pointer to the CM queue header defined as the default DAE queue. Used by TVI_CS_GET for reCYCLEd CMBs. [twqh] Pointer to the CM queue header defined as the ``toxic waste'' queue. Used by TVI_CS_GET and TVI_CS_PUT to avoid dropping CM blocks on the floor and losing them as available resources. This queue is periodically examined and emptied by a separate VAX process (). [fqtable] Free list queue table of quadword descriptors of the free queues. Each quadword contains the free block size and a pointer to the free list queue for blocks of that size (see the structure, below). Sorted by block size for efficient searching. [dapqtbl] DAP queue table copied from CM with queue header offsets converted to handles. Used by the TVI_US_DAP$LOCATE routine.

struct QIB {
    struct CQH *myqh;
    unsigned long myid;
    struct CQH *daeqh;
    struct CQH *twqh;
    struct FQL fqtable[QIB_C_MAXFQS];
    struct CQH *dapqtbl[QIB_C_MAXDQS];
    };

struct FQL {
    unsigned long fql_l_size;
    struct CQH *fql_a_qhdr;
    };

Queue Demultiplexing Block

The Queue Demux Block (QDB) is stored in the Common Memory, but only used by the VAX. It is used by the process to redirect CMBs from the input queue (the multiplexed return queue) to the return queues of the real destination processes. The format of the QDB is:

list [qdb_l_pid] Owning process identification. [qdb_l_astadr] Notification AST address in the destination process. [qdb_l_rtnqoff] Offset to header of the destination process return queue in Common Memory. [qdb_b_flags] Flag bits. Currently only the bit is defined. If the flag is set, the process will empty the destination process return queue (to the free lists) if the destination process does not exist.

struct QDB {
    unsigned long qdb_l_pid;
    unsigned long qdb_l_astadr;
    unsigned long qdb_l_rtnqoff;
    unsigned char qdb_b_flags;
    };

#define  QDB_V_EINXP    0
#define  QDB_M_EINXP    1

Differences with QVI and TVI Implementations

This section is meant for system and application programmers who have written and are planning on writing applications that have ran or will run on either Qbus or TURBOchannel front end machines. A few implementation peculiarities exist between the bus architectures and therefore effect applications that have used QVI system services. This section outlines these differences and suggests some solutions:

• In previous usage of the QVI_CS_VMEMAP and the QVI_CS_VMEPOINTER system services, subsequent calls to QVI_CS_VMEMAP didn't require another QVI_CS_VMEPOINTER call to reestablish the VMEbus virtual address space pointer. This however, isn't true with TURBOchannel implementations. The application call the TVI_CS_VMEPOINTER system service after every call to TVI_CS_VMEMAP and reestablish the address pointer. This imposes difficulties with applications that remain within the 128Kbytes window limitation on QVI front ends. However, applications that are migrating to TURBOchannel front ends need to incorporate this change if they are accesses multiple 128Kbytes windows. To avoid this limitation, it's suggested that applications either incorporate the QVI_CS_VMEPOINTER after every call to QVI_CS_VMEMAP or use the TVI extended system services to map VMEbus address space.

• Another system service needed to be implemented that would generate a VMEbus reset without the Common Memory initialized. A characteristic of the TURBOchannel DWTVB causes all VIC-068A registers to reset when a VMEbus occurs. This imposed a problem with the application and required the implementation of the TVI_ES_VMERESET system service. The system service maps the DWTVB VIC-068A registers locally into virtual address space and generates a on the VMEbus by writing the appropriate value to the System Reset Register . The virtual pages are deleted from the process before the system service returns.

Keywords: EPICURE, VME, TVI, Common_Memory.

Distribution:

Normal