Research Division EED/Controls Software<P> Design Note 126.3<P> TURBOchannel-to-VME Interface (TVI)<P> Design Specification

Research Division EED/Controls Software

Design Note 126.3

TURBOchannel-to-VME Interface (TVI)

Design Specification

David M. Kline

This document represents the final design specification for the TURBOchannel-to-VME interface (TVI). It consists of theoretical discussions and implementation descriptions based on research and empirical studies. Further discussions about the internal components consisting of the TURBOchannel software device drivers, user written system services, and other elements which would perhaps be beneficial to future front end enhancements are mentioned. The reader is encouraged to review Epicure design notes ``VMS System Services for QVI Support'' & ``Use of the QVI and Common VME Memory'' to acquire an understanding of the preceding front end implementation. The TURBOchannel interface intends to replace the Qbus-to-VME Interface (QVI) based on Q22-bus VAX processors and act as an intermediary solution for the next fixed target run. The Research Division/EED Controls group is presently investigating the possibility of using the PCI bus architecture as the bus medium for future front end processors. Because of the preliminary nature of PCI, this document will focus on the TURBOchannel-to-VME interface and defer the PCI design specification to a later date.

Introduction

The TURBOchannel-to-VME I/O adapter subsystem is implemented as part of Digital Equipment Corporation's workstation providing a high performance I/O interconnect. TURBOchannel is defined as a synchronous, asymmetrical I/O channel for connecting optional devices, both Digital and non-Digital based.

In particular, the Digital supported TURBOchannel subsystem adapters have been chosen as the medium for processing data acquisition transactions between VAX and VMEbus based processors. The TURBOchannel VMEbus device support option offered for the VAXstation 4000/60 will be used to implement the Epicure Data Acquisition front end. The TURBOchannel adapter (DWCTX) provides hardware connectivity between the VAXstation processor system bus and the TURBOchannel option module slot. Furthermore, the VAXstation 4000 Models 60 & 90 support only one TURBOchannel slot.

The hardware components consist of the TURBOchannel adapter (DWCTX) and the MVME subsystem. The MVME subsystem consists of the TURBOchannel option module (DWTVXA), YAbus interconnect cable, and the VMEbus interface MVIB (DWTVXB) module. The 3VIA option module interfaces the TURBOchannel bus and the YAbus interconnect cable . The MVIB resides on the VMEbus connecting the YAbus and the VMEbus. The MVIB is responsible for the VMEbus interface and mapping address space between VAX and VMEbus. It contains a Cypress VIC-068A VMEbus interface chip that may be accessed from the VAX. The YAbus interconnect cable serves as a high-speed point-to-point medium that links two dissimilar bus architectures, in this case the TURBOchannel and VME busses. In order to facilitate the migration from Q22-bus to TURBOchannel, a VMEbased interrupter module was designed by the Research Division/EED Controls group to emulate the functionality of the QVI external and address mapped interrupts. The VMEbus Interrupter Module (VBIM) was designed to serve that purpose by supporting general purpose FIFO interrupt queues. Interrupts are generated by writing an interrupt descriptor to a queue specifying the IRQ level and interrupt vector; and up to 12 trigger bits to generate VMEbus or external interrupts, respectively. Digital supports interrupts from VMEbus but doesn't from VAX. Benchmarks have proven them to work in both directions however, that doesn't guarantee that ones from VAX will work in future releases of VMS or on Alpha platforms. The VBIM supports other features such as a read/write diagnostic register, signature ROM, and scratch RAM that can be used at the discretion of the TVI .

The VMS operating system provides a set of executive service routines that allow Programmed I/O (PIO) and Direct Memory Access (DMA) page map registers to be allocated, initialized, and released. These routines are briefly described below :

IOC$ALOVMEMAP_PIO()
- Allocates a set of contiguous VMEbus PIO map registers and records the allocation in the VMEbus adapter ADP and CRB.
IOC$LOADVMEMAP_PIO()
- Loads the previously allocated set of PIO map registers with VMEbus page frame numbers given the information from the IOC$ALOVMEMAP_PIO() routine.
IOC$RELVMEMAP_PIO()
- Obtains the location and number of allocated map registers from CRB and releases them to the free list in the ADP.
IOC$ALOVMEMAP_DMAN()
- Allocate a contiguous set of VMEbus DMA map registers and records the allocation in a map descriptor.
IOC$LOADVMEMAP_DMAN()
- Loads the previously allocated set of DMA map registers with VMS page frame numbers.
IOC$RELVMEMAP_DMAN()
- Obtains the location and number of previously allocated map register from the descriptor as constructed by the IOC$ALOVMEMAP_DMAN() routine. The registers are then released to the free list in the VMEbus adapter ADP.

A VMS device driver was written using the above executive routines to manage and synchronize the allocation, loading, and releasing of both PIO and DMA page map registers and other MVIB resources. Additionally, a set of user written system services provides a consistent interface for applications to map VMEbus address space into process space P0 to accomplish both PIO & DMA transactions with VMEbus memory. A later section describes the driver further.

Revision History

This section provides a listing of the modifications that were made to the document at each release. Readers that have read the entire document can use the below list to identify the sections that have been modified and review only those. Otherwise, the reader is encouraged to read the entire document:

V126.0
- Initial release of the document.
V126.1
- Modifications where made to the sections ``Software Drivers'' and ``ARCnet Support''. The design for both the TURBOchannel PIO/DMA mapping register allocator and ARCnet drivers have been augmented from research and by empirical studies. The ``Revision History'' section was added to aid the reader.
V126.2
- Minor prose changes to sections ``Introduction'' and ``QVI-to-TVI Migration''.
V126.3
- Document is considered to be the final design specification. It reflects modifications made due to software benchmarks and hardware considerations. Inclusion of PCI definition and available system services.

Front End Migration

Because of the present front end limitations and Digital's future migration of processors for both VAX and AXP platforms, a solution is needed to upgrade the Epicure front end subsystem from the Q22-bus architecture into one that provides a higher bandwidth, faster data acquisition, and allows for future development. Although Digital has recently announced that it will drop TURBOchannel support and focus on PCI, the TURBOchannel option boards and related components are appropriate for an intermediary step between the present Q22-bus and future PCI front ends.

The TVI implementation includes user written system services that are implemented as a protected shareable image similarly to the QVI system services. Where applicable, TVI system services reside at the same transfer address as the QVI system services and therefore don't require Epicure products to reestablish them at the link phase. This works quite nicely since this requires no modifications to applications and server processes using QVI system services. The shareable image can be installed without any effect and therefore remains independent of the underlying bus architecture. Because of this transparency, synchronization and consistency when processing common memory queues can be maintained. Applications that want to access services which are beyond the scope of the QVI will be required to use TVI extended system services. To describe further, consider that QVI is limited to only one roaming VMEbus window; TVI extended system services can map the entire common memory and datapool memory into an application . Consequently, these extended services are only available on TURBOchannel front ends. Additional diagnostic features are available. The counter module can be mapped directly to VAX memory without aborting other VAX processes. Another extended service is that TURBOchannel has the means to transfer data over VMEbus to VAX using DMA transactions, providing the fastest method of returning data to a user application. Recent observations have proven a fault exists in the VMS supplied executive system routine that manages releasing DMA page map registers and occurs intermittently . Furthermore, DMA processing doesn't integrate neatly with the present front end protocol using message queues. Therefore, because of the executive routine fault, Digital's announcement of TURBOchannel's future, and integration issues, DMA processing was determined not cost effective at this time.

The QVI system services may be viewed as a subset of the TVI system services. The TVI initialization sequence will be composed of an algorithm that probes the TURBOchannel option module (DWTVXA) signature ROM . If the algorithm determines that the TURBOchannel adapter is present, TVI extended services are enabled. In general however, the QVI and TVI services may be viewed as a layered set of services in which the under lying bus architecture is transparent. Below is a pictorial representation of the layering:

Viewed from above, one can observe that all types of services are accessible. Below lists the layers and provides a brief discussion of them:

TURBOchannel adapter/MVME subsystem
- This is the physical layer that interfaces the VAX with the VMEbus. It consists of the TURBOchannel adapter (DWCTX) and the MVME subsystem .
TVI Device Drivers
- This layer manages and synchronizes access to TURBOchannel resources.
Extended TVI Services
- These services provide extended diagnostic and DMA support. See later sections for additional information.
TVI/QVI Services
- This layer provides transparency between the QVI and TVI system services and between the Q22-bus and TURBOchannel bus architectures. Both services are used to support basic VMEbus address space accesses, manipulate common memory queues, and generate interrupts.

Software Drivers

The TVI implementation is composed of two software drivers. The TURBOchannel Allocator (TCA) and the TURBOchannel Interrupter (TCI). The TCA driver is responsible for managing and synchronizing the MVIB PIO & DMA mapping registers. The TCI driver is responsible for notifying applications of VMEbus events by queuing ASTs to a process or setting an event flag. Both drivers provide user written system services for a consistent entry point to driver services.

The TCA driver is primarily responsible for managing the allocation, loading, and release of PIO & DMA page map registers (PMR). The TCA system services access the driver on behalf of the application and allocate a set of contiguous PIO or DMA PMRs for either data acquisition or diagnostic support. The driver is implemented as a template driver and functions as the focal point for all requests for VMEbus address space mapping. Consequently, synchronization between cooperating VAX-based processes and applications can be maintained. User written system services provide a common interface and access method for clients. The required access protocols will be constructed in the system services and sent to the driver for channel maintenance and PMR resource assignment and release. Mapping registers can be defined as permanent or temporary. Permanent PMRs are allocated for system wide global sections and allow clients of different group codes access to VMEbus resources. In particular, the VMEbus common memory is defined as a set of contiguous PMRs mapped to a global section. TVI system services allow clients to access the common memory and manipulate queues for data acquisition requests and other types of communication. The release of permanent PMRs is performed either by an explicit request, such as the restart of Epicure; or rebooting the VAX. Temporary PMRs are used by clients to map portions of VMEbus space for front end management or diagnostic purposes. For example, there are many applications which are used by hardware personnel to view blocks of common memory for diagnostic purposes. Some of these are: QSHOW, DMPCM, VMEPEEK, and VCMPEEK. The release of temporary PMRs can be performed by an explicit request or the termination of a VAX process or application . The termination of an image automatically causes the cancel I/O routine to be invoked at the driver level. All mapping registers for that device which are defined as temporary will be released. This ensures efficient resource management and avoids unpredictable VMEbus accesses. The TVI system service TCA_CS_ALOVME_PIO_PMR() is used specifically by applications to allocate PIO PMRs. It returns the necessary parameters that are used by the SYS$CRMPSC() system service to create and map a PFN section. Thus, providing the application with the mechanism to access VMEbus address space. The TVI system service TCA_CS_ALOVME_DMA_PMR() is used specifically to allocate PMRs for applications that want DMA transactions. DMA processing is accomplished by the driver making the association between VMEbus and VMS by allocating a buffer from nonpaged pool. When DMA transactions occur, the buffer is filled. After DMA completes, the application is responsible for retrieving the buffer contents. The buffer can be retrieved in two ways. The TCA_CS_COPY_DDB() system service is used to copy the buffer into process local memory, or the TCA_CS_ALOVME_DMA_PMR() system service provides an optional parameter that returns the virtual address to where the nonpaged pool buffer resides. In addition, the destination VMEbus address is returned to one of the parameters and must be communicated to the DMA controller residing on VMEbus. This can be accomplished by the application mapping the controller VMEbus address and communicate using PIO transfers. Refer to later sections for specific details about these services.

The TCI driver is derived from Digital's connect to interrupt facility and the Epicure UICDRIVER. It is primarily responsible for servicing VAX-bound interrupts from VMEbus devices. The VMEbus interrupt vector activates a specific VAX device, as determined by the SYSGEN CONNECT command, and notifies the process by queuing an AST to it or setting an event flag. User written system services provide, a consistent interface and access method to attach the process to a specific VAX device, and notify the process of the interrupt by means of an event flag or user AST routine for specific processing. For example, to remove a message from a common memory queue. The interrupt processing can be described as the VMEbus device placing an interrupt vector on the VMEbus and is received by the TURBOchannel MVIB. The MVIB sends the vector to the VMS operating system which looks up the vector in the System Control Block (SCB). The SCB has the ISR routine vector associated with the particular VMEbus vector. The ISR in the appropriate device is executed as defined by the driver prologue table. The ISR notifies the attached process by queuing as AST to it, sets an event flag (if specified), and resets the driver to notify the process of any further interrupts. The TCI system service then executes the specified AST routine and sets the event flag. The ISR is furthermore responsible for toggling the TURBOchannel CSR interrupt enable bit. This was recommended by Digital for third party vendors using the DWCTX. Interrupt freezes were observed on the VAXstation 4000 Model 90 due to certain assumptions made by Digital's engineering staff. The Model 90 is edge triggered whereas the Model 60 is level sensitive. The TCI driver initialization routine maps the TURBOchannel CSR located at 0X36800000 into system virtual address space. The ISR then acquires a lock on the registers, toggles bit 12 of the CSR, releases the lock, and completes the processing by queuing an AST to the process or setting an event flag.

PFN Sections

VAX-based processes and applications that want to gain access to the VMEbus address space must map those pages into its Virtual Address Space (VAS). When pages are mapped in this way, the VMS operating system bypasses system memory management and creates its own window into the page. The page is known to be PFN mapped and protection functions which are normally performed are not. Therefore the PFNMAP privilege is required or system services need to access these pages on behalf of the application. The TVI services will access VMEbus memory and devices as PFN mapped and create permanent global sections which may be accessed by processes with authorized privileges and access modes.

The TVI services will map and initialize a minimum of three permanent global sections. Access to these sections will be allowed by TVI system services operating at an elevated access mode and processes which have the required authorization. Below lists these sections and their use:

MVI_REGISTERS
- This section maps the 3VIA (DWTVXA), MVIB (DWTVXB), and the VIC-068A registers. These registers are used to control the data transfer types and setup the interrupt levels and vectors.
VBI_REGISTERS
- The VMEbus Interrupter Module (VBIM) interrupt queues and registers are mapped to this section. TVI system services use this section to generate external and VMEbus interrupts and facilitate front end diagnostics.
VME_COMMON_MEMORY
- The VME_COMMON_MEMORY section is the VMEbus common memory used by VAX-based processes and VMEbus processors to communicate between one another.
OTHERs
- Other global sections may be created on-the-fly for diagnostic purposes. To illustrate, the VMEbus counter module may be mapped in to read the counters, the control/status register, and bus error diagnostic registers. Additionally, the entire common memory or datapool memory may be mapped for diagnostic purposes too. Typically, these windows are created by the roving VMEbus window provided by the TVI system services.

Interrupt Generation

Interrupts are generated by accessing the VBI module FIFO interrupt queues from either TVI system services or front end processor CM services. Each FIFO interrupt queue is considered general purpose since both external and vectored interrupts can be generated for all IRQ levels. Generating an external interrupt requires setting the appropriate trigger bit in the interrupt descriptor and writing it to one of the interrupt queues. A VMEbus interrupt is generated by specifying the vector and the IRQ level and writing it to one of the interrupt queues. Both external and VMEbus interrupts can be generated by assigning the appropriate trigger bits, vector, and IRQ level. Furthermore, multiple trigger bits can be set and generate simultaneous external interrupts .

Interrupts are defined by the TURBOchannel Common Memory Initializer application. The application was based on the CMInitializer used by Q22-bus front ends. Unfortunately, the bus architecture is dissimilar enough to require an individual initialization application. The Epicure front end startup command procedures are responsible for determining which front end adapter exists and invoke the appropriate initialization application.

The TURBOchannel Common Memory Initializer (TCCMI) uses the Digital Command Language Interpreter (CLI) to define the descriptor used to generate an interrupt. External interrupts are defined by specifying the trigger bit position of the VBIM FIFO interrupt queue. Interrupts which are used by the return data queues, are specified by a vector . The VMEbus CM services will use that vector to activate the correct VAX return queue device.

System Services

The following sections describe the system services provided to applications and front end processors allowing them to perform data acquisition and diagnostics when a TURBOchannel adapter is present.

TVI User Services

Several ``combined'' service routines are defined to provide a simple interface to the DAE for the Data Acquisition Server (DAS) and other similar processes. The details of the Core Services are hidden within the US calls. In addition, the initialization routine provides for connecting to a interrupt-driven queue and receiving the interrupt notifications by means of event flags or ASTs.

TVI_US_DAP$LOCATE

status = TVI_US_DAP$LOCATE( qti, qhdl ) Locate a queue by its DAP queue index and return the queue handle. This routine is usually called once and the queue handle saved for later use in TVI_US_DAP$MULTICAST. qti DAP Queue Table index (unsigned byte, 0..255). Passed by value. qhdl queue handle returned in a longword. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__NOQUE fatal, queue not found TVI__NOTINIT fatal, TVI_US services not initialized

TVI_US_DAP$MULTICAST

status = TVI_US_DAP$MULTICAST( blktyp, mcpars, [cmbhdl] ) Allocate a free CM block and build a multicast UMB into this block. The first longword of the multicast UMB (after the standard UMB header) contains the Queue Table Index of the current queue; this is followed by 4 longwords of multicast parameters specified by the caller. This routine initializes the QTI longword to the first non-zero QTI entry. The CM block is then placed on the CM queue specified by that QTI entry. As each destination processes the multicast message, it advances the QTI longword to the next non-zero entry in the QTI table and passes the block on to that destination until all the QTI entries have been visited; after which the block is returned to the VAX by the return queue identifier found in the CM block header. blktyp Block type for the multicast UMB. Passed by value. mcpars Parameters for the multicast message. A block of 4 longwords (16 bytes) passed by reference. cmbhdl optional longword in which to return a pointer to the CMB allocated from the free list and filled with the multicast UMB contents. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__QTIEMPTY success, no multicast as QTI empty TVI__NOFREE error, no free CM blocks of the needed size are available TVI__QLCKFAI error, failed to acquire queue lock TVI__IVQLINK fatal, invalid queue link, possible CM corruption TVI__NOTINIT fatal, TVI_US services not initialized

TVI_US_GET

status = TVI_US_GET( maxsize, umbbuf, [,blkhdl] ) Remove the CM block from the head of the VAX return queue specified in the TVI_US_INIT call and return the UMB contents from the CM block in the provided buffer. The CM block is either released to the free list or recycled depending on the value of the CYCLE flag. maxsize maximum expected UMB size. Passed by value. umbbuf address of a buffer in VAX memory to be filled with the contents of the UMB in the dequeued CM block. Passed by reference. blkhdl optional longword in which the block handle used to identify the dequeued CM block is returned. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__EMPTY warning, return queue was empty TVI__TRU warning, return block truncated as UMB too small TVI__QLCKFAI error, failed to acquire queue lock TVI__IVQLINK fatal, invalid queue link, possible CM corruption TVI__NOTINIT fatal, TVI_US services not initialized others as returned by TVI_CS and VMS services

TVI_US_INIT

status = TVI_US_INIT( qname [,efn] [,ast] [,astprm] [,astcnt] ) Initialize the TVI_US services, including mapping all needed global sections which were created during the Common Memory initialization. The logical name RDCS$QVI_DAE_QUEUE is translated to provide the name of the CM queue to which messages are queued by TVI_US_PUT if no explicit target queue is given. This default queue is also used by TVI_US_GET for messages with the CYCLE flag set. The RDCS$QVI_WASTE_QUEUE logical name provides the name of the CM queue used as the ``toxic waste'' queue when inserts of ``defunct'' blocks onto the free lists fail. Also, the name of the CM return queue specified in the call is used to form the RDCS$QVI_VAXQ_name logical name which should translate to the VMS device to assign an I/O channel for the interrupt handling if either an event flag or an AST routine is specified in the call to this service. The RDCS$QVI_DEMUX_QUEUE logical name gives the name of the multiplexed CM queue to allow TVI user processes using that queue to specify it as the return queue. This is done automatically by TVI_US_INIT if the queue name specified in the call is marked as a multiplexed queue (MUX bit in the queue header). qname queue name to be used by this process as its VAX return queue. The queue name is a 1-8 character string passed by descriptor. efn Optional event flag number to be set when a block appears on the VAX return queue for processing. Passed by value. ast Optional address of an AST routine to be invoked when a block appears on the VAX return queue for processing. Passed by reference (address of the procedure's entry mask). astprm Optional parameter to be passed to the AST routine. Passed by value. astcnt Optional parameter specifying a count of AST blocks to be preallocated for handling rapid interrupts. Default value of 10 is used. Passed by value. status returns a VMS condition code: SS$_NORMAL success TVI__CMINIT fatal, CM not initialized TVI__MAPERR fatal, failed to map CM properly TVI__NOQUE fatal, queue named not found others as returned by TVI_CS and VMS services

TVI_US_LOCATE

status = TVI_US_LOCATE( qname, qhdl ) Locate a named queue and return its queue handle. This service is typically used once per queue and the resulting queue handle saved for later use with TVI_US_PUT. qname queue name to be located. The queue name is a 1-8 character string passed by descriptor. qhdl Queue handle returned in a longword. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__NOQUE fatal, queue named not found TVI__NOTINIT fatal, TVI_US services not initialized others as returned by TVI_CS and VMS services

TVI_US_MODFLG

status = TVI_US_MODFLG( blkhdl [,rmask] [,smask] ) Modify the flag bits of the specified CM block. This is normally used to clear the CYCLE flag before queuing a multicast EXPUNGE request for that CM block. The CM block handle must have been saved from a previous TVI_US_PUT call. blkhdl block handle used to identify the CM block whose flag bits are to be modified. Passed by value. rmask mask of those UMB_L_FLAGS bits to be reset (cleared to zero). Passed by value. smask mask of those UMB_L_FLAGS bits to be set (to one). Passed by value. status returns a VMS condition code: SS$_NORMAL success TVI__NOTORG error, not originator of CM block TVI__BADBHDL fatal, bad block handle TVI__NOTINIT fatal, TVI_US services not initialized others as returned by TVI_CS and VMS services

TVI_US_PUT

status = TVI_US_PUT( umbbuf [,toqhdl] [,blkhdl] [,altdiq] ) Allocate a block of CM and copy the UMB (User Memory Block) contents into the CM block from the VAX buffer. The CM block is then placed on the specified target CM queue. umbbuf address of a buffer in VAX memory to be copied into the UMB portion of the CM block. Passed by reference. The UMB size will be taken from the umb_w_reqsiz word in the VAX buffer. toqhdl optional queue handle of the target CM queue. Passed by value. If not specified (or specified as 0), then the block will be placed on the default DAE queue. This argument is the queue handle returned from a previous call to TVI_US_LOCATE. blkhdl optional longword in which the block handle used to identify the allocated CM block is returned. Passed by reference. altdiq optional queue handle of the CM queue which will receive the CM block if the CYCLE bit is set. Passed by value. If the parameter is not supplied or contains a value of zero, the CM block is directed towards the default DAE input queue as specified by the RDCS$QVI_DAE_QUEUE logical. This argument is the queue handle return from a previous call to TVI_US_LOCATE. status returns a VMS condition code: SS$_NORMAL success TVI__NOFREE error, no free CM blocks of the required size TVI__QLCKFAI error, failed to acquire queue lock TVI__BADQHDL fatal, bad queue handle TVI__IVQLINK fatal, invalid queue link, possible CM corruption TVI__NOTINIT fatal, TVI_US services not initialized TVI__TOOBIG fatal, requested size exceeds that of the largest CM block others as returned by TVI_CS and VMS services

TVI_US_RESINM

status = TVI_US_RESINM( [efn] [,ast, astprm] ) This routine is called to reestablish the mechanism used to notify processes that an interrupt from the TURBOchannel adapter has been received. efn integer value of the event flag number set when an interrupt is received. Passed by value. ast address of the function to execute when an interrupt occurs. Passed by reference. astprm integer value passed to the AST routine if the ``ast'' parameter is specified. Passed by value. status returns a VMS condition code: SS$_NORMAL success SS$_BADPARAM fatal, bad parameter value FALSE error, services not initialized others as returned by VMS and $QIO services

TVI_US_TEST

status = TVI_US_TEST( [size] ) Test the VAX return queue (specified in the TVI_US_INIT call) to see if any entries are currently queued. size optional longword in which the size of the UMB in the CM block at the head of the queue is returned. Passed by reference. If the queue is empty, then zero is returned. status returns a VMS condition code: SS$_NORMAL success TVI__EMPTY warning, return queue was empty TVI__QLCKFAI error, failed to acquire queue lock TVI__IVQLINK fatal, invalid queue link, possible CM corruption TVI__NOTINIT fatal, TVI_US services not initialized others as returned by TVI_CS and VMS services

TVI Core Services

The TVI Core Services (CS) are meant for direct use by the Common Memory initialization program and by diagnostics programs. In addition, several of the Core Services are used by the User-level Services (US routines) described above.

TVI_CS_CM2VAX

status = TVI_CS_CM2VAX( cmdescr, cmbptr, size, block ) Copy an array of longwords from a CM block into VAX memory. cmdescr CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAPCM service. Passed by reference. cmbptr pointer to the CM block to be copied. Consider the pointer as passed by value or that the CM block itself is passed by reference (address of the CM block appears in the argument list). size Size of the longword array in bytes. Passed by value. block address of target VAX buffer to receive the longwords from the CM block. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__IVCMDS fatal, invalid CM descriptor TVI__BADBHDL fatal, bad block handle

TVI_CS_CREAA

status = TVI_CS_CREAA( cmdescr, blksiz, blkcnt, qptr, curcmo, aadptr ) Create a Common Memory allocation area. This routine is meant for use by the CM initialization program or by stand-alone diagnostics. cmdescr address of a CM descriptor returned by the TVI_CS_MAKECM routine. Passed by reference. blksiz size, in bytes, of the blocks in the allocation area being defined. The size must be less than 65,535. Passed by value. blkcnt number of blocks requested for the area (less may be defined if the end of the CM is reached first). Passed by value. qptr pointer to header of free list queue for the new allocation area. The free list queue is populated with all the blocks in the new area. Passed by value. curcmo current Common Memory offset on input, modified to reflect new value after the new allocation area has been setup. Passed by reference. aadptr returns the address of the Allocation Area Descriptor for the new allocation area. Passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_NOPRIV fatal, no privilege for the requested operation TVI__BADQHDL fatal, bad CM queue handle TVI__CMALRINI fatal, CM already completed initialization TVI__IVCMDS fatal, invalid CM descriptor TVI__IVQLINK fatal, invalid queue link, possible CM corruption TVI__IVSIZE fatal, invalid CM block size TVI__OUTOFCM fatal, no free Allocation Area Descriptors remain This routine requires DIAGNOSE privilege to use.

TVI_CS_CREQH

status = TVI_CS_CREQH( cmdescr, qname, qptr ) Create and initialize a Common Memory queue header. This routine is meant for use by the Common Memory initialization program or by standalone diagnostics. cmdescr address of a CM descriptor returned by the TVI_CS_MAKECM routine. Passed by reference. qname queue name given as (up to 8) ASCII characters. Passed by fixed-length string descriptor. qptr pointer to the new queue header returned in a longword. Passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_NOPRIV fatal, no privilege for the requested operation TVI__CMALRINI fatal, CM already completed initialization TVI__IVCMDS fatal, invalid CM descriptor TVI__NOQUE fatal, no free queue headers left in CM This routine requires DIAGNOSE privilege to use.

TVI_CS_DAP$MULTICAST

status = TVI_CS_DAP$MULTICAST( cmdescr, qib, blktyp, mcpars, [cmbptr] ) Allocate a free CM block and build a multicast UMB into this block. The first longword of the multicast UMB (after the standard UMB header) contains the Queue Table Index of the current queue; this is followed by 4 longwords of multicast parameters specified by the caller. This routine initializes the QTI longword to the first non-zero QTI entry. The CM block is then placed on the CM queue specified by that QTI entry. As each destination processes the multicast message, it advances the QTI longword to the next non-zero entry in the QTI table and passes the block on to that destination until all the QTI entries have been visited; after which the block is returned to the VAX by the return queue identifier found in the CM block header. cmdescr CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAPCM service. Passed by reference. qib Queues Information Block containing default DAE queue header pointer, free queue table and the DAP Queues Table. Passed by reference. blktyp Block type for the multicast UMB. Passed by value. mcpars Parameters for the multicast message. A block of 4 longwords (16 bytes) passed by reference. cmbptr optional longword in which to return a pointer to the CMB allocated from the free list and filled with the multicast UMB contents. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__QTIEMPTY success, no multicast as the DAP Queue Table is empty TVI__IVCMDS fatal, invalid CM descriptor TVI__IVQLINK fatal, invalid queue link, possible CM corruption TVI__NOFREE error, no free CM blocks of the needed size are available TVI__QLCKFAI error, failed to acquire queue lock

TVI_CS_GET

status = TVI_CS_GET( cmdescr, qib, maxs, umbbuf, [qptr], [cmbptr] ) Remove the CM block from the head of the specified CM queue. If no explicit queue is specified, the VAX return queue specified in the Queues Information Block (QIB) is used. The contents of the UMB portion of the dequeued CM block (if any) are returned in the provided VAX UMB buffer. The CM block dequeued is either released to the CM free lists or recycled depending upon the UMB_M_CYCLE flag in the UMB header. A recycled CM block is placed on the DAE input queue as given in the CMH. cmdescr CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAPCM service. Passed by reference. qib Queues Information Block containing the default return queue header pointer and free queue table. Passed by reference. maxs size of user data return buffer (in bytes). Passed by value. umbbuf buffer for user data returned from the CMB removed from the head of the queue. Passed by reference. qptr optional pointer to queue header from which to remove the head entry, default is the return queue pointed to in the QIB. Passed by value. cmbptr optional longword in which to return a pointer to the CMB dequeued. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__EMPTY warning, return queue was empty TVI__TRU warning, return block truncated TVI__BADQHDL fatal, bad queue handle TVI__IVCMDS fatal, invalid CM descriptor TVI__IVQLINK fatal, invalid queue link, possible CM corruption TVI__IVSIZE fatal, invalid block size TVI__NOQUE fatal, no target or default queue given TVI__QLCKFAI error, failed to acquire queue lock

TVI_CS_INIT

status = TVI_CS_INIT( cmdescr ) Initializes the TVI control registers and creates the permanent global section which maps the TVI control registers. The pages of this global section are locked into the page tables to permit access at elevated IPLs. This service is meant for use by the Common Memory initialization program and by standalone diagnostics. cmdescr address of a 16 longword CM descriptor returned by this routine and used in other TVI_CS routines. Passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_NOPRIV fatal, no privilege for the requested operation TVI__MAPERR fatal, error mapping the TVI registers TVI__NOVMEPWR fatal, VME Bus is not powered others as returned by VMS services This routine requires SYSGBL, PRMGBL, PFNMAP and DIAGNOSE privileges to use.

TVI_CS_INSQT

status = TVI_CS_INSQT( cmdescr, cmbptr, qptr, genint ) Insert a Common Memory block onto the tail of a queue in the Common Memory. cmdescr CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAPCM service. Passed by reference. cmbptr pointer to the CM block within the mapped CM section. Passed by value. qptr pointer to CM queue header on which to insert the CM block. Passed by value. genint interrupt generation control flag. If 1 then the interrupt associated with the queue is triggered. If 0, then the interrupt (if any) is not triggered. status returns a VMS condition code: SS$_NORMAL success TVI__IVCMDS fatal, invalid CM descriptor TVI__IVQLINK fatal, invalid queue link, possible CM corruption TVI__BADBHDL fatal, bad block handle TVI__BADQHDL fatal, bad queue handle TVI__QLCKFAI fatal, failed to acquire queue lock

TVI_CS_INTERRUPT

status = TVI_CS_INTERRUPT( cmdescr, intno ) Generate an external mapped interrupt to a VME module using the VBI. The external mapped interrupts are generated by writing a mask of bits into a 32-bit control register in the VBI. cmdescr CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAPCM service. The variant form of the CM descriptor returned by the TVI_CS_VMEWINDOW routine is also acceptable. Passed by reference. intno external interrupt number (0-11). Passed by value. status returns a VMS condition code: SS$_NORMAL success SS$_BADPARAM fatal, bad interrupt number TVI__IVCMDS fatal, invalid CM descriptor

TVI_CS_LOCATE

status = TVI_CS_LOCATE( cmdescr, qname, qptr ) Locate a Common Memory queue header. cmdescr address of a CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAP routine. Passed by reference. qname queue name given as (up to 8) ASCII characters. Passed by fixed-length string descriptor. qptr pointer to the new queue header returned in a longword. This is the address of the queue header in the CM as mapped into the process's virtual address space. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__IVCMDS fatal, invalid CM descriptor TVI__NOQUE fatal, no queue found

TVI_CS_LOCKCM

status = TVI_CS_LOCKCM( cmdescr ) Lock the Common Memory global section into the paging tables to permit access at elevated IPLs. This service is meant for use by the CM initialization program and by stand-alone diagnostics. Requires that TVI_CS_MAKECM have already been called. cmdescr address of a 16 longword CM descriptor which was returned by TVI_CS_MAKECM. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__IVCMDS fatal, invalid CM descriptor TVI__MAPERR fatal, not all of CM locked others as returned by VMS services This routine requires PSWAPM privilege to use.

TVI_CS_LOCKPOOL

status = TVI_CS_LOCKPOOL( cmdescr, poolno ) Lock specified DataPool against access by other processes or processors. cmdescr address of a CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAP routine. Passed by reference. poolno Common Memory DataPool selector number. Passed by value. status returns a VMS condition code: SS$_NORMAL success TVI__LOCKED warning, DataPool is already locked TVI__IVCMDS fatal, invalid CM descriptor TVI__BADPOOLNO fatal, bad data pool selector number

TVI_CS_MAKECM

status = TVI_CS_MAKECM( cmavme, cmsize, cmdescr ) Create and map the permanent global sections for the VMEbus Common Memory and Interrupter (VBI) module into the process's virtual address space. This service is meant for use by the CM initialization program. Requires that TVI_CS_INIT have been called previously. cmavme VME address of the base of the Common Memory module. Must be aligned on a TVI boundary (multiple of 128 KBytes). Passed by value. cmsize number of bytes of the Common Memory module to be used. Must be an integral number of Kbytes (an even number of VAX pages). Passed by value. cmdescr address of a 16 longword CM descriptor which was returned by TVI_CS_INIT and will be modified here. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__CMBASE fatal, CM base address not on TVI mapping boundary TVI__CMSIZEXC fatal, CM size exceeds QBus address space TVI__CMSIZODD fatal, CM size not even number of VAX pages TVI__IVCMDS fatal, invalid CM descriptor TVI__MAPERR fatal, not all of CM mapped TVI__VBIMAP fatal, failed to map VBI module properly others as returned by VMS services This routine requires SYSGBL, PRMGBL and PFNMAP privileges to use.

TVI_CS_MAKEFQT

status = TVI_CS_MAKEFQT( cmdescr, maxfq, fqtable ) Build a free queue location table to provide fast access to the free lists. cmdescr address of a CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAP routine. Passed by reference. maxfq maximum number of free list queues provided for in the table. Passed by value. fqtable free list queue table giving block sizes and pointers to the associated free queue headers. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__CMNOTINI fatal, Common Memory not initialized TVI__IVCMDS fatal, invalid CM descriptor TVI__TOOMNYFQ fatal, too many free queues for table

TVI_CS_MAPCM

status = TVI_CS_MAPCM( cmdescr ) Map the Common Memory, transient VME window and TVI control registers global sections into the current process's virtual address space. These global sections must have already been setup by a previous program (such as the CM initialization program). This service is used instead of TVI_US_INIT by those programs which depend upon the CM being initialized by a special program (usually at system startup). cmdescr address of a 16 longword block in which a CM descriptor is returned. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__CMNOTINI fatal, Common Memory not initialized TVI__MAPERR fatal, not all of a global section mapped or locked into the page tables TVI__NOVMEPWR fatal, VME Bus is not powered TVI__VBIMAP fatal, failed to map VBI module properly others as returned by VMS services

TVI_CS_MODIFLAGS

status = TVI_CS_MODIFLAGS( bp, [rstmsk], [setmsk] ) Modify the flag bits of the specified CM block. This is normally used the clear the CYCLE bit before queuing a CANCEL or EXPUNGE multicast request for a particular CM block. This is an internal routine for the TVI_US_MODFLG routine to do the flag modifications at elevated IPL. bp pointer to Common Memory block. Passed by value. rstmsk mask of flag bits to be cleared. Passed by value. setmsk mask of flag bits to be set. Passed by value. status returns a VMS condition code: SS$_NORMAL success SS$_ACCVIO fatal, no access to CMB flags

TVI_CS_POOLPOINTER

status = TVI_CS_POOLPOINTER( cmdescr, poolno, poolptr, poolsize ) Return pointer to selected Common Memory DataPool. cmdescr address of a 16 longword block returned by the TVI_CS_MAPCM service. Passed by reference. poolno selector number of Common Memory DataPool. Passed by value. poolptr address of a longword to receive a pointer to the base of the DataPool as mapped in current process virtual address space. Pointer to pool is passed by reference. poolsize address of a longword to receive size of the DataPool. Size is passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__NOPOOL error, no space allocated for selected data pool TVI__IVCMDS fatal, invalid CM descriptor TVI__BADPOOLNO fatal, bad CM data pool number others as returned by VMS services

TVI_CS_PUNCHVME

status = TVI_CS_PUNCHVME( ) This routine is obsolete with the TURBOchannel implementation and will return the status code of SS$_UNSUPPORTED.

TVI_CS_PUT

status = TVI_CS_PUT( cmdescr, umbbuf, qib, [tqptr], [cmbptr], [altdiq] ) Allocate a free CM block and copy the UMB contents into this free block from the VAX UMB buffer. The CM block size is retrieved from the UMB UMB buffer size field. The CM block is then placed on the specified CM queue or the default DAE queue (given in the QIB) if no target queue handle is provided. The CM block is recycled to the queue handle as specified by the altdiq parameter if the CYCLE bit is set. cmdescr CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAPCM service. Passed by reference. umbbuf buffer of user data to be inserted into a CMB and placed on a queue for processing. Passed by reference. This data must have the structure of a UMB with the length of the UMB in the umb_w_reqsiz word. qib Queues Information Block containing default DAE queue header pointer and free queue table. Passed by reference. tqptr optional pointer to target queue header. If not given then the target is the default DAE queue from the QIB. Passed by value. cmbptr optional longword in which to return a pointer to the CMB allocated from the free list and queued to the target queue. Passed by reference. altdiq optional longword directing the CM block to be recycled on an alternate DAE input queue (DIQ). Passed by value. status returns a VMS condition code: SS$_NORMAL success TVI__NOFREE error, no free CM blocks of the needed size are available TVI__QLCKFAI error, failed to acquire queue lock TVI__BADQHDL fatal, bad queue handle TVI__IVCMDS fatal, invalid CM descriptor TVI__IVQLINK fatal, invalid queue link, possible CM corruption TVI__IVSIZE fatal, invalid block size TVI__NOQUE fatal, no target or default queue given TVI__TOOBIG fatal, requested UMB size exceeds that of the largest CM block

TVI_CS_REMQH

status = TVI_CS_REMQH( cmdescr, qptr, cmbptr ) Remove the entry from the head of a queue in the Common Memory. cmdescr CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAPCM service. Passed by reference. qptr pointer to queue header from which to remove the entry at the head of the queue. Passed by value. cmbptr returns a pointer to the CM block removed in a longword. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__EMPTY warning, queue is empty TVI__BADQHDL fatal, bad queue handle TVI__IVQLINK fatal, invalid queue link, possible CM corruption TVI__IVCMDS fatal, invalid CM descriptor TVI__QLCKFAI fatal, failed to acquire queue lock

TVI_CS_RESETVME

status = TVI_CS_RESETVME( cmdescr ) Use the TVI to generate a RESET on the VME bus. cmdescr address of a 16 longword block returned by the TVI_CS_INIT service. The variant form returned by the TVI_CS_VMEWINDOW routine is also acceptable. Passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_NOPRIV fatal, no privilege for requested operation TVI__IVCMDS fatal, invalid CM descriptor others as returned by VMS services The process must have DIAGNOSE privilege.

TVI_CS_SHUTDOWN

status = TVI_CS_SHUTDOWN( ) Shutdown the TVI services by deleting the permanent global sections used by these services. This service is meant for use by the CMShutdown program or stand-alone diagnostics. status returns a VMS condition code: SS$_NORMAL success SS$_NOPRIV fatal, no privilege for the requested operation others as returned by VMS services This routine requires SYSGBL, PRMGBL, PFNMAP and DIAGNOSE privileges to use.

TVI_CS_STATUS

status = TVI_CS_STATUS( cmdescr ) Return status from the TVI. cmdescr CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAPCM service. The variant form CM descriptor returned by TVI_CS_VMEWINDOW is also acceptable. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__VMEBUSBSY warning, a TVI operation is in progress on the VME bu TVI__IVCMDS fatal, invalid CM descriptor TVI__VMEBUSERR fatal, a VME bus error has occurred TVI__MVIICR fatal, MVI ICR1 setup incorrectly TVI__MVIRCR fatal, MVI RCR setup incorrectly TVI__MVICSR fatal, MVI CSR setup incorrectly TVI__MVIARCR fatal, MVI ARCR setup incorrectly

TVI_CS_TEST

status = TVI_CS_TEST( cmdescr, qptr, [size] ) Test the specified queue to see if any entries are on it. cmdescr CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAPCM service. Passed by reference. qptr pointer to CM queue header. Passed by value. size returns the size of the UMB of the entry at the head of the queue (or 0 if the queue is empty). Passed by reference. status returns a VMS condition code: SS$_NORMAL success TVI__EMPTY warning, queue was empty TVI__QLCKFAI error, failed to acquire queue lock TVI__BADQHDL fatal, bad queue handle TVI__IVQLINK fatal, invalid queue link possible CM corruption TVI__IVCMDS fatal, invalid CM descriptor

TVI_CS_TOUCHVME

status = TVI_CS_TOUCHVME( ) This routine is obsolete with the TURBOchannel implementation and will return the status code of SS$_UNSUPPORTED.

TVI_CS_UNLOCKPOOL

status = TVI_CS_UNLOCKPOOL( cmdescr, poolno ) Unlock specified DataPool to allow access by other processes or processors. cmdescr address of a CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAP routine. Passed by reference. poolno Common Memory DataPool selector number. Passed by value. status returns a VMS condition code: SS$_NORMAL success TVI__NOTLOCKED warning, DataPool was already unlocked TVI__IVCMDS fatal, invalid CM descriptor TVI__BADPOOLNO fatal, bad data pool selector number

TVI_CS_VAX2CM

status = TVI_CS_VAX2CM( cmdescr, block, size, cmbptr ) Copy an array of longwords from VAX memory into a CM block. cmdescr CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAPCM service. Passed by reference. block address of a buffer of one or more longwords in VAX memory. Passed by reference. size Size of the longword buffer in bytes. Passed by value. cmbptr pointer to the CM block to be filled (pointer refers to the CM block as mapped by the CM global section into the process' virtual address space). Consider the pointer as passed by value or that the CM block itself is passed by reference (address of the CM block appears in the argument list). status returns a VMS condition code: SS$_NORMAL success TVI__IVCMDS fatal, invalid CM descriptor TVI__BADBHDL fatal, bad block handle TVI__IVSIZE fatal, not integral number of longwords

TVI_CS_VMEADRMOD

status = TVI_CS_VMEADRMOD( cmdescr, amod ) Set the VME address modifier of the roving VME window defined by the call to TVI_CS_VMEWINDOW to the selected value (or revert to the default). cmdescr address of a 16 longword block returned by from the TVI_CS_VMEWINDOW routine. Passed by reference. amod unsigned longword giving the VME address modifier code (see definitions in QVIDEF.H file) for the roving VME window. If 0 is passed, the VME address modifier is reset to the initialization value for Extended Supervisory Data Access. Below lists the valid address modifier codes: 0X3E Standard supervisory program access 0X3D Standard supervisory data access 0X3A Standard non-privileged program access 0X39 Standard non-privileged data access 0X2D Short supervisory access 0X29 Short non-privileged access 0X0E Extended supervisory program access 0X0D Extended supervisory data access 0X0A Extended non-privileged program access 0X09 Extended non-privileged data access status returns a VMS condition code: SS$_NORMAL success TVI__NOVME fatal, VME window not initialized

TVI_CS_VMEMAP

status = TVI_CS_VMEMAP( cmdescr, vmeadr ) Set the VME base address of the roving VME window defined by the call to TVI_CS_VMEWINDOW. NOTE: unlike the QVI system service QVI_CS_VMEMAP, the TVI_CS_VMEPOINTER system service must be called after TVI_CS_VMEMAP to establish the virutal address pointer to the VMEbus address space. cmdescr address of a 16 longword block returned by from the TVI_CS_VMEWINDOW routine. Passed by reference. vmeadr unsigned longword giving the base VME address of the window into the VME address space. The low-order 17 bits of the VME address are ignored. Passed by value. status returns a VMS condition code: SS$_NORMAL success TVI__NOVME fatal, VME window not initialized TVI__VBIMAP fatal, failed to map VBI module properly

TVI_CS_VMEPOINTER

address = TVI_CS_VMEPOINTER( cmdescr, vmeadr ) Return the VAX virtual address (in the process' VAS) which corresponds to the VME address as mapped by the roving VME window. The VME window has to have been setup by a call to CS_VMEMAP to map a range of VME addresses (including the VME address specified to this routine). cmdescr address of CM descriptor block returned by from the CS_VMEWINDOW routine. Passed by reference. vmeadr unsigned longword giving the VME address to be located. Passed by value.

TVI_CS_VMEWINDOW

status = TVI_CS_VMEWINDOW( cmdescr ) Probe the MVI registers and verify that the TURBOchannel adapter is available. Initialize the TCA_ system services for TURBOchannel resource management. Declare a user mode exit handler that releases the VMEbus window on image exit or process termination. Setup the information block with passed parameter that is used by the CS_VMEMAP routine to request TURBOchannel PMR resources. cmdescr address of the CM descriptor block returned by this routine with the TVI addresses. This variant form of the CM descriptor must be used with the CS_VMEMAP routine and is acceptable to the CS_INTERRUPT, CS_STATUS, and CS_RESETVME routines. This block must be allocated in static storage due to existence of an exit handler block within the common memory descriptor. Passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_NOPRIV fatal, no privilege for the requested operation TVI__VMEINUSE fatal, VME window in use by another process others as returned by TVI_CS and VMS services This routine requires PFNMAP and DIAGNOSE privileges to use.

TVI_ES_ALOVMEWIN

status = TVI_ES_ALOVMEWIN( handle, vmeaddr, addrspc, va [,vmeflg] ) This routine is part of the TURBOchannel extended services. It provides for any number of windows that can be mapped to both VMEbus device memories and control registers. The window created by this routine can be defined as either permanent or temporary. Permanent windows are ones which will not release any TURBOchannel resources until a reset to the adapters or a restart of the VMS operating system. Temporary windows can be release by using the compliment routine TVI_ES_RELVMEWIN(). This routine will probe the MVI registers and verify the existence of the TURBOchannel adapter option module. handle address of an identifier to the TURBOchannel resources. Address pointer passed by reference. vmeaddr base VMEbus address. Passed by value. addrspc address range of the VMEbus to map. Values must be aligned on 4Kb boundaries. Passed by value. va return pointer to the mapped VMEbus address as specified in the 'addrspc' parameter. Passed by reference. vmeflg optionl longword identifying the VMEbus address modifier. If parameter is not passed, the default of ``Extended Non-Privileged Data Access'' is used. Passed by value. status returns a VMS condition code: SS$_NORMAL success SS$_BADPARAM fatal, bad parameter value SS$_INSFARG fatal, insufficient call arguments SS$_NOPRIV fatal, no privilege for the requested operation others as returned by TVI_CS, TCA_CS, & VMS services This routine requires PFNMAP and DIAGNOSE privileges to use.

TVI_ES_GENINT

status = TVI_ES_GENINT( cmdsc, intdsc ) Generate an interrupt by writing the VBI/VAX interrupt queue. The parameter ``intdsc'' specifies the IRQ level and the particualar VAX return queue that will be actived when the interrupt is processed. The routine succeeds the TOUCHVME & PUNCHVME routines since they are unsupported by TURBOchannel. cmdsc CM descriptor returned by the TVI_CS_MAKECM or TVI_CS_MAPCM service. A variant CM descriptor returned by TVI_CS_VMEWINDOW is also acceptable. Passed by reference. intdsc Interrupt descriptor which gets written to the VBI/VAX interrupt queue. Passed by value. The descriptor is organized as follows: VECTOR the lower byte of the first word specifies which VAX return queue to activate. LEVEL the upper byte of the first word specifies the IRQ level which is asserted when the interrupt is generated. If no level is supplied, the interrupt will not be generated. INTNO the upper word specifies which external interrupt(s) are to be asserted when the interrupt is generated. status returns a VMS condition code: SS$_NORMAL success SS$_BADPARAM fatal, bad interrupt number

TVI_ES_MAKSEC

status = TVI_ES_MAKSEC( cmddescr, cmavme, cmsize, vbivme ) Create and map the permanent global sections for the TURBOchannel interface. The VMEbus common memory and interrupter modules are represented and accessed as permanent global sections. The CMDescriptor will contain virtual addresses to these sections and provide accesses to them at elevated access modes. This service is meant for use by the CM initialization program and requires that TVI_CS_INIT have been called previously. cmdescr address of a 16 longword CM descriptor which was returned by TVI_CS_INIT and will be modified here. Passed by reference. cmavme VME address of the base of the Common Memory module. Must be aligned on a TVI boundary (multiple of 128 KBytes). Passed by value. cmsize number of bytes of the Common Memory module to be used. Must be an integral number of Kbytes (an even number of VAX pages). Passed by value. vbivme VME address of the base of the VMEbus Interrupter Module. Must be aligned on a VMEbus boundary (multiple of 4 KBytes). Passed by value. status returns a VMS condition code: SS$_NORMAL success TVI__CMBASE fatal, CM base address not on TVI mapping boundary TVI__CMSIZEXC fatal, CM size exceeds QBus address space TVI__CMSIZODD fatal, CM size not even number of VAX pages TVI__IVCMDS fatal, invalid CM descriptor TVI__MAPERR fatal, not all of CM mapped TVI__VBIMAP fatal, failed to map VBI module properly others as returned by VMS services This routine requires SYSGBL, PRMGBL and PFNMAP privileges to use.

TVI_ES_RELVMEWIN

status = TVI_ES_RELVMEWIN( handle ) This routine is the compliment of the _ES_ALOVMEWIN() routine. It releases any TURBOchannel resources that are associated with the handle parameter. handle address of an identifier to the TURBOchannel resources. Address pointer passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_NOPRIV fatal, no privilege for the requested operation others as returned by TVI_CS, TCA_CS, & VMS services This routine requires PFNMAP and DIAGNOSE privileges to use.

TVI_ES_RESETVME

status = TVI_ES_RESETVME() Use the MVI to generate a RESET on the VME bus without the Common Memory initialized. status returns a VMS condition code: SS$_NORMAL success SS$_NOPRIV fatal, no privilege for requested operation others as returned by VMS services The process must have DIAGNOSE privilege.

TCI User Services

The TCI User Services are used by other TVI system services to establish connectively between VAX return queues and applications.

TCI_US_CONNECT

status = TCI_US_CONNECT( dname [,efn] [,ast, astprm] [,astcnt] ) This routine connects a VMS application with a VMEbus interrupt vector. When the appropriate VMEbus device wants to interrupt the VAX, it asserts an interrupt vector on the bus. It is processed by the TURBOchannel MVIB module and sent to the VMS operating system. The OS uses the vector to lookup the interrupt service routine (ISR) in the system control block (SCB). The ISR queues an AST to the process that is associated with the vector. dname string name of the device to assign too. Passed by reference. efn integer value of the event flag number set when an interrupt is received. Passed by value. ast address of the function to execute when an interrupt occurs. Passed by reference. astprm integer value passed to the AST routine if the ``ast.fa.rp'' parameter is specified. Passed by value. astcnt integer value that preallocates a number of AST blocks. Passed by value. status returns a VMS condition code: SS$_NORMAL success SS$_BADPARAM fatal, bad parameter value FALSE error, services not initialized others as returned by VMS and $QIO services

TCI_US_EXIT

status = TCI_US_EXIT() This routine deassigns the channel and releases any resources associated with the device. The TCI_US_CONNECT routine declares this routine as a user-mode exit handler. Therefore, releasing TCI_ resources is an automatic feature of the system services. status returns a VMS condition code: SS$_NORMAL success others as returned by VMS system services

TCI_US_INIT

status = TCI_US_INIT() This routine prepares for use of the TCI_ system service routines. status returns a VMS condition code: SS$_NORMAL success, initialization complete others as returned by VMS and $LIB services

TCI_US_READ_ALL_VEC

status = TCI_US_READ_ALL_VEC( vectors, count ) This routine queries all devices for the vectors used to activate them. The ``vectors'' parameter is an address pointer to an array of structures that contain two integers. The first one indicates a VMS status code and the second the vector number. The parameter may be viewed as an array of I/O status blocks. The routine will allocate from the dynamic memory pool enough to hold the status and vector for every known device. A list of known devices is acquired by translating the logical RDCS$TVI_TCI_DEVICES. The address of the dynamic memory block is returned to the ``vectors'' parameter which the application may use to initialize the VBI module virtual DMA channels. Since the TCI_US_EXIT routine is responsible for releasing device resources, the application shouldn't attempt to release the memory block. vectors address pointer to array of two integer data packets. Passed by reference. count number of vectors returned. Passed by reference. status returns a VMS condition code: SS$_NORMAL success others as returned by VMS services

TCI_US_READ_VEC

status = TCI_US_READ_VEC( vector ) This routine requests the interrupt vector from the device assigned to after a call to the TCI_US_CONNECT routine. vector returned integer that contains the interrupt vector used to activate the device. Passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_BADPARAM fatal, bad parameter value FALSE error, services not initialized others as returned by VMS and $QIO services

TCI_US_RESINM

status = TCI_US_RESINM( [efn] [,ast, astprm] ) This routine is called to reestablish the mechanism used to notify processes that an interrupt from the TURBOchannel adapter has been received. efn integer value of the event flag number set when an interrupt is received. Passed by value. ast address of the function to execute when an interrupt occurs. Passed by reference. astprm integer value passed to the AST routine if the ``ast'' parameter is specified. Passed by value. status returns a VMS condition code: SS$_NORMAL success SS$_BADPARAM fatal, bad parameter value FALSE error, services not initialized others as returned by VMS and $QIO services

TCA Core services

The TCA Core Services are used by other TVI system services and applications that require access to the VMEbus.

TCA_CS_ALOVME_DMA_PMR

status = TCA_CS_ALOVME_DMA_PMR( handle, ddbreqsiz, ddbva, ddbretsiz, vmeaddr ) This routine allocates an AIB and requests a set of free map registers. The AIB is filled with DMA PMR information and linked in with the other ones located in the CAB. The ``ddbreqsiz'' parameter is used to determine the size of the DMA Data Buffer (DDB). The DDB is defined by the routine as a PFN mapped section and its virtual address is returned in the ``ddbva'' parameter. The VMEbus address that represents VMS memory is returned to the ``vmeaddr'' parameter. The value is written to the DMA controlling device which uses it to access VMS memory from the VMEbus. handle PMR handle returned. Passed by reference. ddbreqsiz integer requesting size of DDB in bytes. Passed by value. If parameter not provided, a size of 512 bytes is assumed. Size will be adjusted on integer boundaries. ddbva return integer providing the virtual address of the DDB. Address pointer passed by reference. ddbretsiz return integer of the actual size of the DDB. Passed by reference. vmeaddr return integer containing the VMEbus address of the DDB. This value represents the VMS virtual address to the DDB from the VMEbus. It is used by DMA controllers. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TCA__NOCAB no client allocation block found LIB$_INSVIRMEM insufficient virtual memory others as returned by VMS services

TCA_CS_ALOVME_PIO_PMR

status = TCA_CS_ALOVME_PIO_PMR( handle, perm, vmeaddr, addrspc, vbn, boff, vmeflg ) This routine allocates an AIB and requests a set of free map registers. The AIB is linked to other AIBs located in the CAB. The routine returns the virtual block number (VBN) that is used by client applications to map VMEbus address space as a PFN mapped section. handle PMR handle returned. Passed by reference. perm allocate the set of PMRs as permanent. Passed by value. The value of TRUE indicates that the set of PIO PMRs will be allocated as permanent, whereas FALSE indicates they will be temporary. vmeaddr start VMEbus address that is to be mapped. Passed by value. addrspc size of the VMEbus address space to map (in bytes). Passed by value. vbn return integer of the virtual block number of PIO PMR location in VMS dynamic memory. Passed by reference. boff return integer of the byte offset into the first VMS page that mapped to VMEbus space. Passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_BADPARAM bad parameter value others as returned by VMS services

TCA_CS_COPY_DDB

status = TCA_CS_COPY_DDB( handle, data, size ) This routine copies the contents of the DDB to the client data buffer. The address of the local buffer is return to the parameter ``data''. The user must call this routine to extract the data from the VME device immediately. If not, the data will get overwritten by the next DMA transaction. handle PMR handle. Passed by value. data address pointer of the data buffer. The routine returns a virtual address of the data buffer that the DDB was copied to. Passed by reference. size size if the copied data adjusted to integer boundaries. Passed by reference. status returns a VMS condition code: SS$_NORMAL success

TCA_CS_DISINT

status = TCA_CS_DISINT( mviio, intno ) Disable the IRQ level on the MVI as specified by the ``intno'' parameter. This routine assumes that the MVI control registers have already been mapped into virutal address space and is passed by the ``mviio'' parameter. mviio virtual address of the TURBOchannel MVI registers. In particular, the VIC-068A which contains the IRQ registers. Passed by reference. intno longword indicating which VMEbus IRQ level to disable. Passed by value. status returns a VMS condition code: SS$_NORMAL success TCA__NOADAP fatal, no MVI option module adapter found TCA__NOADDR fatal, MVI option module address not supplied TCA__IVIRQ error, invalid IRQ level specified. others as returned by VMS services

TCA_CS_ENAINT

status = TCA_CS_ENAINT( mviio, intno ) Enable the IRQ level on the MVI as specified by the ``intno'' parameter. This routine assumes that the MVI control registers have already been mapped into virutal address space and is passed by the ``mviio'' parameter. mviio virtual address of the TURBOchannel MVI registers. In particular, the VIC-068A which contains the IRQ registers. Passed by reference. intno longword indicating which VMEbus IRQ level to enable. Passed by value. status returns a VMS condition code: SS$_NORMAL success TCA__NOADAP fatal, no MVI option module adapter found TCA__NOADDR fatal, MVI option module address not supplied TCA__IVIRQ error, invalid IRQ level specified. others as returned by VMS services

TCA_CS_EXIT

status = TCA_CS_EXIT() This routine traverses the AIB list and releases PMR resources. PIO PMR resources are released to the set of free map registers. DMA PMR resources are released to the set of free map registers and the DDB private section virtual pages are unmapped. The TCA_CS_INIT routine establishes a user-mode exit handler with this routine. By default, the routine is executed as part of VMS image termination and guarantees that TURBOchannel resources will be relinquished. status returns a VMS condition code: SS$_NORMAL success TCA__NOCAB warning, no client allocation block found others as returned by VMS and LIB$ services

TCA_CS_INIT

status = TCA_CS_INIT( mviio, init ) Initializes TCA services by clearing the client allocation block (CAB). The CAB contains a linked list of allocation information blocks (AIB) that identify both PIO and DMA PMR allocation. Client resource usage can easily be tracked and identified by traversing the AIB list. mviio virtual address of the TURBOchannel MVI registers. In particular, the CSR data containing the board switch status. The switches are used to generate the VMEbus address. Passed by reference. init indicates whether to continue to initialize the MVI registers. Passed by value. status returns a VMS condition code: SS$_NORMAL success TCA__CABVAL warning, client allocation block already valid TCA__NOADAP fatal, no MVI option module adapter found TCA__NOADDR fatal, MVI option module address not supplied others as returned by VMS services

TCA_CS_READ_AIB

status = TCA_CS_READ_AIB( aibnum, aib, size ) This routine returns the number of allocation information blocks and the AIB descriptors located in client allocation block. The CAB AIB list is traversed and a block of dynamic memory is allocated. As AIBs are found, they are placed into dynamic memory. The address pointer to the array of AIBs is returned to the caller. aibnum return integer indicating the number of descriptors returned. Passed by reference. aib return address pointer of the array of AIB data structures describing the list of PIO & DMA PMR allocation. Passed by reference. The definition of the AIB is located in the header file ``epicure_sys_inc:tcadef.h''. size return size of the AIB array. Passed by reference. This value in used by clients to release dynamic memory to the free lists. status returns a VMS condition code: SS$_NORMAL success SS$_BADPARAM bad parameter value TCA__NOAIB no allocation information block found in CAB others as returned by VMS services

TCA_CS_READ_DDI

status = TCA_CS_READ_DDI( handle, data ) This routine retrieves the device-dependent information from the device UCB. The ``handle'' parameter identifies the device to read. handle PMR handle. Passed by value. data address of integer containing device-dependent information. Passed by reference. status returns a VMS condition code: SS$_NORMAL success LIB$_BADBLOADR bad block address others as returned by VMS services

TCA_CS_READ_PIO_PMR_STATUS

status = TCA_CS_READ_PIO_PMR_STATUS( numdsc, disreg, mapreg ) This routine returns the address to the list of free PIO PMRs. The structure format is defined in the ``epicure_sys_inc:tcadef.h'' header file. numdsc return integer indicating the number of descriptors returned. Passed by reference. disreg return integer indicating the number of disabled map registers. Passed by reference. mapreg return address pointer to the array describing the set of free map registers. Passed by reference. status returns a VMS condition code: SS$_NORMAL success TCA__NOAIB no allocation information block found in CAB others as returned by VMS services

TCA_CS_RELVME_PERM

status = TCA_CS_RELVME_PERM( num ) This routine releases all PIO PMRs that have been setup as permanent. The routine was intended for initialization routines only. num return unsigned integer containing the number of permanent PIO PMRs released. Passed by reference. status returns a VMS condition code: SS$_NORMAL success others as returned by VMS services

TCA_CS_RELVME_PMR

status = TCA_CS_RELVME_PMR( handle ) This routines scans the CAB AIB list for the AIB that matches the value as identified by the ``handle'' parameter. Resources that were allocated for DMA PMR, including the DDB PFN section, are released to the device adapter control block and dynamic memory pools. PIO PMR resources are released to the device adapter control block. handle address pointer of the PMR handle. Passed by reference. status returns a VMS condition code: SS$_NORMAL success LIB$_BADBLOADR bad block address LIB$_DABBLOSIZ bad block size others as returned by VMS services

CM Services

The CM routines are linked with the DAE code itself and provide services at the level of the VAX TVI_US routines. The CM routines locate Common Memory blocks and queues by their VMEbus address in the memory module used to support the Common Memory.

cm_dapmcast

status = cm_dapmcast( cmbptr ) Insert a Common Memory block with a DAP Multicast message the next destination queue of the message. The next destination queue is given by either the next non-empty entry in the DAP Queue Table (as specified by the QTI within the Multicast message) or is the originator's return queue. By convention, DAP Multicast messages originate in the host MicroVAX. cmbptr pointer to CM block with the Multicast message. Passed by value (or consider the CM block as passed by reference). status returns a VMS condition code: SS$_NORMAL success QVI__CMNOTINI fatal, Common Memory not initialized QVI__QLCKFAI fatal, failed to acquire queue lock

cm_dapqloc

status = cm_dapqloc( qti, qhdl ) Locate a Common Memory queue by its Queue Table Index (QTI) as used in the Data Access Protocol (DAP) packets. qti queue table index given as a byte. Passed by value. qhdl returns a pointer to the queue header. Passed by reference. status returns a VMS condition code: SS$_NORMAL success QVI__CMNOTINI fatal, Common Memory not initialized QVI__NOQUE fatal, could not find named queue

cm_insqt

status = cm_insqt( cmbptr, qptr, genint ) Insert a Common Memory block onto the tail of a queue in Common Memory. cmbptr pointer to the CM block. Passed by value (or consider the CM block as passed by reference). Note that the pointer is to the CMB, not the UMB which is contained within the CMB. qptr pointer to CM queue header on which to insert the CM block or the offset of the queue header relative to the base of the CM. Passed by value (or consider the CM queue header as passed by reference). genint interrupt generation control flag. If 1 then the interrupt associated with the queue is triggered. If 0, then the interrupt (if any) is not triggered. Passed by value. status returns a VMS condition code: SS$_NORMAL success QVI__BADBHDL fatal, bad pointer to CM block QVI__BADQHDL fatal, bad pointer to CM queue header QVI__CMNOTINI fatal, Common Memory not initialized QVI__QLCKFAI fatal, failed to acquire queue lock

cm_locate

status = cm_locate( qname, qhdl ) Locate a Common Memory queue header. qname queue name given as (up to 8) ASCII characters. Passed by reference (a C string terminated by a NUL character). qhdl pointer to the new queue header returned in a longword. This is the address of the queue header in the CM. Passed by reference. status returns as VMS condition code: SS$_NORMAL success QVI__NOQUE fatal, no queue found

cm_remqh

status = cm_remqh( qptr, cmbptr ) Remove entry from the head of a Common Memory queue. qptr pointer to CM queue header from which to remove the CM block. Passed by value (consider the CM queue header as passed by reference). cmbptr address of longword to return pointer to the block removed from the head of the queue. Passed by reference. Note that the pointer is to the CMB, not to the UMB which is contained within the CMB. status returns a VMS condition code: SS$_NORMAL success QVI__EMPTY warning, queue is empty QVI__BADQHDL fatal, bad pointer to CM queue header QVI__CMNOTINI fatal, Common Memory not initialized QVI__QLCKFAI fatal, failed to acquire queue lock

cm_tstq

status = cm_tstq( qptr ) Test the status of a Common Memory queue. qptr pointer to CM queue header. Passed by value (consider the CM queue header as passed by reference). status returns a VMS condition code: SS$_NORMAL success QVI__EMPTY warning, queue is empty QVI__BADQHDL fatal, bad pointer to CM queue header QVI__CMNOTINI fatal, Common Memory not initialized QVI__QLCKFAI fatal, failed to acquire queue lock

Additional CM 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

status = cm_get_block( size, qhdl, cmbptr ) Allocate a block from the Common Memory free lists. size requested size of the UMB to be allocated from the CM free lists. Passed by value. The size will be stored in the standard field in the UMB header of the allocated block. The caller must fill in the UMB block type. qhdl queue pointer, returned by cm_locate(), of a queue owned by a VAX process which is the ultimate destination of the message in the block being requested. cmbptr address of longword to return pointer to the block removed from a free list queue. Passed by reference. Note that the pointer returned is to the CMB, not the UMB which is contained within the CMB. status returns a VMS condition code: SS$_NORMAL success QVI__NOFREE error, no free CM blocks QVI__CMNOTINI fatal, Common Memory not initialized QVI__IVSIZE fatal, invalid UMB size request QVI__QLCKFAI fatal, failed to acquire queue lock QVI__TOOBIG fatal, size exceeds largest CM block size

cm_get_init

status = cm_get_init() Perform necessary one-time-only initializations for the cm_get_block() routine. This includes building a list of the free lists in static storage which is sorted by the size of the blocks on the free lists. status returns a VMS condition code: SS$_NORMAL success QVI__CMNOTINI fatal, Common Memory not initialized QVI__TOOMNYFQ fatal, too many free queues for table 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

status = cm_lockpool( pn ) Lock the selected data pool against updates by other processors. pn number of Common Memory DataPool. Passed by value. status returns a VMS condition code: SS$_NORMAL success, pool locked by this processor QVI__LOCKED warning, pool is already locked QVI__BADPOOLNO fatal, bad CM data pool number

cm_poolpointer

status = cm_poolpointer( pn, pp ) Return address of selected Common Memory DataPool area. pn number of Common Memory DataPool. Passed by value. pp address of a longword to return the pointer to the Common Memory DataPool. Passed by reference. status returns a VMS condition code: SS$_NORMAL success QVI__NOPOOL error, no space allocated for selected data pool QVI__CMNOTINI fatal, Common Memory not initialized QVI__BADPOOLNO fatal, bad CM data pool number

cm_unlockpool

status = cm_unlockpool( pn ) Release the lock on the selected data pool to allow updates by other processors. pn number of Common Memory DataPool. Passed by value. status returns a VMS condition code: SS$_NORMAL success, pool locked by this processor QVI__NOTLOCKED warning, pool was already unlocked QVI__BADPOOLNO fatal, bad CM data pool number

Command/Control Application

Presently, there are many individual applications written to diagnose the QVI when a problem exists. With the front end upgrade, these diagnostic applications will be combined into a single application. Selection of the screen interface is still under discussion; however, Motif is preferred. Whether the application is written depends on interface developments within the group and funding. If however, funding or routines are not available, ESM will be the interface the application is based on.

The application will provide screens that display the current status of the common memory queues, common memory blocks, DWCTX status and registers, and command & control features that allow technicians and programmers to diagnose problems. Additional information will be displayed consisting of statistics, peek loads, and usage patterns.

Performance Measurements

During the development phase, benchmarks were written to compare performance differences between the Q22-bus and TURBOchannel front ends. This section provides this information in a tabular format. The tests were run on a VS3200, VS4000/90, and VS4000/60. They measured the number of CM blocks, consisting of 128 bytes, which can be processed for both CAMAC and VMEbus transactions using PIO read & write accesses.

Below represents the number of transactions that can be processed per second for VMEbus accesses.

Below represents the number of transactions that can be processed per second for CAMAC operations.

The tables above indicate that there exist minimal performance differences between the VS4000/90 & VS4000/60 models. Since the model 90 is the more expensive of the two and DMA processing is not required, it therefore suggests that the model 60 would be appropriate as an intermediate front end processor.

Keywords: Epicure, TVI, QVI, CM

Distribution: normal

Security, Privacy, Legal

rwest@fsus04.fnal.gov