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