EPICURE Design Note 3.9

VMS System Services for QVI Support

David M. Kline

This document shows the calling sequences for the QVI 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.

Introduction

• Data transfers through the QVI are 32-bit longwords aligned on longword boundaries. This requirement permits the QVI to correct for the byte ordering differences between the 68020 Motorola and the VAX architectures. With the change of the DAE processors to Intel 80386s, this becomes less important since the MicroVAX and the 80386 use the same byte-order memory address model. However, the QVI still does not correctly handle longword or word accesses on byte addresses (the data is scrambled) so a set of VAX services is still required to isolate the QVI 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 MicroVAX test and set instructions do not generate interlocked QBus cycles, hardware on the QVI is preset to turn a back-to-back pair of read/write QBus 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 MicroVAX 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 QVI control registers in QBus I/O space and interrupt control registers in VME address space must be manipulated.
• The details of the 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 MicroVAX this requires kernel mode services.

A special device driver on the MicroVAX, the UICDRIVER, is needed to handling the fielding of interrupts from the QVI. This driver was derived from the Digital Connect-to-Interrupt driver and is designed to handle the Advanced Micro Devices 9519A Universal Interrupt Controller.

Descriptions of the QVI and CM Services

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 QVI_US routines is unimportant to the users of the QVI_US routines. This does not hold true for the QVI_CS routines where the documentation spells out whether a particular ``handle'' is an actual address or just 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 QVI 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 QVI 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 QVI_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 QVI_US_PUT routine.

[cmb_r_umb] This structure is the portion of the CMB manipulated by the user of the QVI 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 QVI 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 QVI Files and Linking With the QVI Services

    $ link  ...,qvi_inc:qvivaxc/options,...

The QVI 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 QVI User Services

QVI_US_DAP$LOCATE

QVI_US_DAP$MULTICAST

QVI_US_GET

QVI_US_INIT

QVI_US_LOCATE

QVI_US_MODFLG

QVI_US_PUT

QVI_US_RESINM

QVI_US_TEST

QVI Core Services

QVI_CS_CM2VAX

QVI_CS_CREAA

QVI_CS_CREQH

QVI_CS_DAP$MULTICAST

QVI_CS_GET

QVI_CS_INIT

QVI_CS_INSQT

QVI_CS_INTERRUPT

QVI_CS_LOCATE

QVI_CS_LOCKCM

QVI_CS_MAKECM

QVI_CS_MAKEFQT

QVI_CS_MAPCM

QVI_CS_MODIFLAGS

QVI_CS_POOLPOINTER

QVI_CS_PUNCHVME

QVI_CS_PUT

QVI_CS_REMQH

QVI_CS_RESETVME

QVI_CS_SHUTDOWN

QVI_CS_STATUS

QVI_CS_TEST

QVI_CS_TOUCHVME

QVI_CS_VAX2CM

QVI_CS_VMEADRMOD

QVI_CS_VMEMAP

QVI_CS_VMEPOINTER

QVI_CS_VMEWINDOW

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 MicroVAX to restore the exhausted block to its free list.

cm_get_block

cm_get_init

Other optional CM services deal with Common Memory DataPools. A DataPool is a section of Common Memory set aside for the use of a group of cooperating processes (usually on multiple processors) as a data storage area. The usual setup is for one process to collect data, reformat it and deposit in the DataPool. Another process will then pick data out of the DataPool in response to user data acquisition requests.

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 QBus addresses used for the main CM window. In either case, map the global section into current process VAS P0 region.
3. Initialize the QVI control registers to map the QBus addresses of the CM to the actual VME addresses of the CM memory board. Also create a permanent global section named to map the QVI control registers (access limited to kernel mode).
4. Zero all of the VME memory module locations (including the entire Common Memory region).
5. Initialize the CM global area locations and build the CM queue headers, allocation area descriptors and other fixed structures.
6. 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...]

CMInitializer 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 [/VME=address] Specifies the address of a VME location used to generate the interrupt associated with this queue. The interrupt is triggered when an entry is made on the queue to signal the destination that a request is available on its input queue. [/EXTERNAL=number] Specifies the number (0-7) of a QVI mapped 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 UIC 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. [/NOBYTE_OPERATION] Specifies that the hardware generating the interrupt will only respond to word operations (otherwise a byte access will be used). Only one of the qualifiers , , 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 . Similarly, can only be used with the qualifier (if is used, the default is ). [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 CMInitializer will cross-check against its input parameters.

$ DEFINE := DEFINE /NOLOG
$ SET PROCESS /PRIVILEGE=SYSNAM
$!
$! 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 PROCESS /PRIVILEGE=(CMKRNL,DIAGNOSE,PSWAPM,PRMGBL,SYSGBL,PFNMAP,SYSLCK)
$ DEFINE /USER_MODE	CM_PARAMETERS	SYS$INPUT:
$ RUN CMI
address %XE0000000 /cm				!CM VME card address
address	%XFF00E010 /external_interrupt		!Mapped External Interrupts
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	$tiny /none
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 /vme=%XFF00E000 /device=vaxqa0: /nobyte	!DAS return queue
queue	tsret /vme=%XFF00E002 /device=vaxqb0: /nobyte	!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 /vme=%XFF00E004 /device=vaxqc0: /nobyte	!Message handler queue
exit
$ EXIT

Internals

Logical Names

UICDRIVER and VAX Interrupt Devices

$ RUN SYS$SYSTEM:SYSGEN
!
! NOTE: The CSR addresses here are of the Command Register of the
!	AMD9519 Interrupt Controller, NOT of the 1st QVI register.
!
CONNECT VAXQA0 /ADAPTER=UB0 /DRIVERNAME=UICDRIVER /CSR=%O777102 /VECTOR=%O700
CONNECT VAXQB0 /ADAPTER=UB0 /DRIVERNAME=UICDRIVER /CSR=%O777102 /VECTOR=%O704
CONNECT VAXQC0 /ADAPTER=UB0 /DRIVERNAME=UICDRIVER /CSR=%O777102 /VECTOR=%O710
CONNECT VAXQD0 /ADAPTER=UB0 /DRIVERNAME=UICDRIVER /CSR=%O777102 /VECTOR=%O714
CONNECT VAXQE0 /ADAPTER=UB0 /DRIVERNAME=UICDRIVER /CSR=%O777102 /VECTOR=%O720
CONNECT VAXQF0 /ADAPTER=UB0 /DRIVERNAME=UICDRIVER /CSR=%O777102 /VECTOR=%O724
CONNECT VAXQG0 /ADAPTER=UB0 /DRIVERNAME=UICDRIVER /CSR=%O777102 /VECTOR=%O730
CONNECT VAXQH0 /ADAPTER=UB0 /DRIVERNAME=UICDRIVER /CSR=%O777102 /VECTOR=%O734
EXIT
$ EXIT

At system startup, the arms the chip but does not enable any of the interrupt levels. A level is enabled and its vector is loaded into the chip once an I/O operation is started with the I/O function code (same function code as used by the VMS Connect-to-Interrupt Driver supplied by Digital). Similarly once the I/O operation is completed or cancelled, the interrupt level is disabled on the chip.

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 QVI_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).

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. [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 address on VME bus or a bit number for the external interrupt register (on the QVI board). This interrupt is associated with this queue to inform the destination processor of an entry on the queue. [cqh_q_name] Queue name given as 1-8 uppercase ASCII 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_WRD   6
#define CQH_M_WRD   0X40

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 QVI is preset to stretch the VMEBus cycle since the results in separate read and write QBus cycles. The QVI 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

Common Memory Descriptor

A CM descriptor occupies 16 longwords (64 bytes). The CM descriptor basically describes the QVI 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 QVI_CS_VMEWINDOW service (see below). [cmd_a_qvi] Pointer to QVI registers 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 QVI map register used for the ``transient'' window by the QVI 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. [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. [cmd_a_mapreg] This field overlays cmd_a_cqhbot in the variant Common Memory descriptor produced by the QVI_CS_VMEWINDOW routine; a more detailed explanation is given below. This field stores the pointer to the QVI map register used by the ``roving'' VME window and is used by the QVI_CS_VMEMAP routine. [cmd_l_vwba] This field overlays cmd_a_cqhbot in the variant Common Memory descriptor produced by the QVI_CS_VMEWINDOW routine. This field stores the VME base address of the QVI window. It is setup by the QVI_CS_VMEMAP routine and used in the QVI_CS_VMEPOINTER routine. [cmd_l_exitsts] This field overlays cmd_a_top in the variant Common Memory descriptor procedure by the QVI_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_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 qvi_r_csrs *cmd_a_qvi;
    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;
    };

struct CMDescriptor {  /* VMEWINDOW variant */
    unsigned long cmd_l_check;
    address cmd_a_base;
    struct qvi_r_csrs *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 QVI_US routines and passed in the calling sequences of the QVI_CS_GET and QVI_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 QVI_CS_GET. Used by QVI_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 QVI_CS_GET for reCYCLEd CMBs. [twqh] Pointer to the CM queue header defined as the ``toxic waste'' queue. Used by QVI_CS_GET and QVI_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 QVI_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 MicroVAX. 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 DeMuxer 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

Keywords: EPICURE, VME, QVI, Common_Memory.

Distribution:

Normal