NI-VXI™ User Manual July 1996 Edition Part Number 371702A-01 © Copyright 1996 National Instruments Corporation. All Rights Reserved.
Internet Support GPIB: gpib.support@natinst.com DAQ: daq.support@natinst.com VXI: vxi.support@natinst.com LabVIEW: lv.support@natinst.com LabWindows: lw.support@natinst.com HiQ: hiq.support@natinst.com VISA: visa.support@natinst.com Lookout: lookout.support@natinst.com E-mail: info@natinst.com FTP Site: ftp.natinst.com Web Address: http://www.natinst.
Important Information Warranty The media on which you receive National Instruments software are warranted not to fail to execute programming instructions, due to defects in materials and workmanship, for a period of 90 days from date of shipment, as evidenced by receipts or other documentation. National Instruments will, at its option, repair or replace software media that do not execute programming instructions if National Instruments receives notice of such defects during the warranty period.
Table of Contents About This Manual Organization of This Manual..................................................................................... xiii Conventions Used in This Manual ............................................................................ xiv Related Documentation ............................................................................................. xv Customer Communication.........................................................................................
Table of Contents Multiple Mainframe Support ..................................................................................... 2-5 Controllers................................................................................................... 2-5 The extender and controller Parameters...................................................... 2-7 Using NI-VXI............................................................................................................ 2-9 Header Files...........................
Table of Contents WSLcmd ..................................................................................................... 3-11 WSLresp...................................................................................................... 3-11 WSrd ........................................................................................................... 3-12 WSrdf .......................................................................................................... 3-12 WSresp .....................
Table of Contents VXIout......................................................................................................... 3-25 VXIoutReg .................................................................................................. 3-25 Low-Level VXI/VMEbus Access Functions ............................................................. 3-26 Programming Considerations ...................................................................... 3-27 Multiple-Pointer Access for a Window..................
Table of Contents VXI Interrupt Functions ............................................................................................ 3-43 Programming Considerations ...................................................................... 3-45 ROAK Versus RORA VXI/VME Interrupters ............................................ 3-46 AcknowledgeVXIint ................................................................................... 3-46 AssertVXIint ............................................................
Table of Contents DefaultSoftResetHandler............................................................................. 3-61 DefaultSysfailHandler ................................................................................. 3-61 DefaultSysresetHandler............................................................................... 3-62 DisableACfail.............................................................................................. 3-62 DisableSoftReset .........................................
Table of Contents Figures Figure 1-1. VXI Configuration Registers ................................................................ 1-2 Figure 1-2. VXI Software Protocols ........................................................................ 1-3 Figure 2-1. An Embedded Controller Connected to Other Frames via Mainframe Extenders Using MXI-2 ..................................................... 2-6 Figure 2-2. An External Controller Connected Using MXI-2 to a Number of Remote Controllers ..................
About This Manual This manual describes in detail the features of the NI-VXI software and the VXI/VME function calls in the C/C++ and BASIC languages. Organization of This Manual The NI-VXI User Manual for C/C++ and BASIC is organized as follows: • Chapter 1, Overview of NI-VXI, introduces you to the concepts of VXI (VME eXtensions for Instrumentation), VME, MXI (Multisystem eXtension Interface), and their relationship to the NI-VXI application programmer’s interface (API).
About This Manual • Appendix B, Customer Communication, contains forms you can use to request help from National Instruments or to comment on our manuals. • The Glossary contains an alphabetical list and description of terms used in this manual, including abbreviations, acronyms, and metric prefixes. • The Index contains an alphabetical list of key terms and topics used in this manual, including the page where each one can be found.
About This Manual Related Documentation The following documents contain information that you may find helpful as you read this manual: • IEEE Standard for a Versatile Backplane Bus: VMEbus, ANSI/IEEE Standard 1014-1987 • Multisystem Extension Interface Bus Specification, Version 2.0 • VXI-1, VXIbus System Specification, Revision 1.4, VXIbus Consortium • VXI-6, VXIbus Mainframe Extender Specification, Revision 1.
Chapter 1 Overview of NI-VXI This chapter introduces you to the concepts of VXI (VME eXtensions for Instrumentation), VME, MXI (Multisystem eXtension Interface), and their relationship to the NI-VXI application programmer’s interface (API). Comprehensive functions for programming the VXIbus/VMEbus are included with the NI-VXI software. They are available for a variety of controller platforms and operating systems.
Chapter 1 Overview of NI-VXI Offset 3F VXI Configuration Space • Upper 16 KB of A16 space reserved for VXI configuration space • 64 bytes per device • 8-bit logical address specifies base address for each device 20 IE 1C 1A 18 Reserved Reserved Reserved Reserved Reserved by VXIbus Specification 16 14 12 10 A32 Pointer Low A32 Pointer High A24 Pointer Low A32 Pointer High Shared Memory Protocol Registers 0E Data Low Data High Response/Data Extended 0C 0A • 256 devices per VXI system Device Depen
Chapter 1 Overview of NI-VXI Message-Based Devices In addition to register-based devices, the VXIbus specification also defines message-based devices, which are required to have communication registers in addition to configuration registers. All message-based VXIbus devices, regardless of the manufacturer, can communicate at a minimum level using the VXI-specified Word Serial Protocol.
Chapter 1 Overview of NI-VXI a fashion very similar to IEEE 488 instruments. In general, message-based devices typically contain some level of local intelligence that uses or requires a high level of communication. In addition, the Word Serial Protocol has messages for configuring message-based devices and system resources. All VXI message-based devices are required to use the Word Serial Protocol and communicate in a standard way.
Chapter 1 Overview of NI-VXI register. Devices that do not have bus master capability always transmit such information via interrupts, whereas devices that do have bus master capability can either use interrupts or send signals. Some devices can receive only signals, some only interrupts, while some others can receive both signals and interrupts.
Chapter 1 Overview of NI-VXI Because MXI-2 incorporates all of these new signals into a single connector, the triggers, interrupts, and utility signals can be extended not only to other mainframes but also to the local CPU in all MXI-2 products using a single cable. Thus, MXI-2 lets CPU interface boards such as the PCI-MXI-2 perform as though they were plugged directly into the VXI/VME backplane.
Chapter 2 Introduction to the NI-VXI Functions This chapter introduces you to the NI-VXI functions and their capabilities. Additional discussion is provided for each function’s parameters and includes descriptions of the application development environment. This chapter concludes with an overview on using the NI-VXI application programming interface. The NI-VXI functions are a set of C/C++ and BASIC language functions you can use to perform operations with a VXI/VME system.
Chapter 2 Introduction to the NI-VXI Functions Note: NI-VXI User Manual • Low-Level VXIbus Access Functions—Low-level VXI/VMEbus access functions are the fastest access method for directly reading from or writing to any of the VXI/VMEbus address spaces. You can use these functions to obtain a pointer that is directly mapped to a particular VXI/VMEbus address. Then you use the pointer with the low-level VXI/VMEbus access functions to read from or write to the VXI/VMEbus address space.
Chapter 2 Introduction to the NI-VXI Functions of the VXI/VME interrupt lines, VXI TTL triggers, VXI ECL triggers, and utility bus signals. The National Instruments Resource Manager configures the mainframe extenders with settings based on user-modifiable configuration files. VXI-Only Function Groups The following NI-VXI function groups do not apply to VME. • Commander Word Serial Protocol Functions—Word Serial is a form of communication between VXI message-based devices.
Chapter 2 Introduction to the NI-VXI Functions LabWindows/CVI You can use the functions described in this manual with LabWindows/CVI. LabWindows/CVI is an integrated development environment for building instrumentation applications using the ANSI C programming language. You can use LabWindows/CVI with Microsoft Windows on PC-compatible computers or with Solaris on Sun SPARCstations. The source code you develop is portable across either platform.
Chapter 2 Introduction to the NI-VXI Functions Because value is an output parameter, &value is used when calling the function instead of value. The input parameters are la and reg. Return Values and System Errors All NI-VXI functions return a status indicating success or failure. The return code of 0x8000 is reserved as a return status value for any function to signify that a system error occurred during the function call except for the commander word serial operations.
Chapter 2 Introduction to the NI-VXI Functions cable connected towards the root frame) in the frame acts as a remote controller. An embedded or external controller may use a remote controller to control the remote mainframe. • External controller—A desktop computer or workstation connected to the VXI/VME system via a MXI interface board. An example is a standard personal computer with a PCI-MXI-2 installed.
Chapter 2 Introduction to the NI-VXI Functions ® ONAL ENTS RUM NATI INST NAT INST IONA RUM L ENT S® bus bus NAT INST IONA RUM L ENT S® bus NAT INST IONA RUM L ENT S® bus External Controller Remote Controller and Extender Extender Only Remote Controller and Extender Figure 2-2. An External Controller Connected Using MXI-2 to a Number of Remote Controllers The extender and controller Parameters In NI-VXI, some functions require a parameter named extender or controller.
Chapter 2 Introduction to the NI-VXI Functions Most functions that take a controller parameter will allow you to pass (-1) as the logical address. This selects the default controller for the system. Notice that the default controller is determined by the following factors: • If the program is running on an embedded controller, the default controller is the embedded controller.
Chapter 2 Introduction to the NI-VXI Functions Using NI-VXI This section presents a general overview of the more commonly used class of functions available in NI-VXI. Additional information summarizes how you can use the functions to perform certain tasks and further describes the general structure of NI-VXI programming. Header Files Although nivxi.
Chapter 2 Introduction to the NI-VXI Functions The busacc.h File The busacc.h file defines constants and macros for use with the high/low-level and slave memory access functions (see the Master Memory Access and Slave Memory Access sections later in this chapter). To make the code more readable, busacc.h defines such elements as memory space, privilege mode, and byte order as constants, and it defines macros to combine these constants into the necessary access parameters.
Chapter 2 Introduction to the NI-VXI Functions An important note about these two functions is that the internal structure maintains a record of the number of calls to InitVXIlibrary() and CloseVXIlibrary(). Although InitVXIlibrary() needs to be called only once, the structure of your program may cause the function to be called multiple times. A successful call to InitVXIlibrary() returns either a zero or a one.
Chapter 2 Introduction to the NI-VXI Functions For example, all VXI devices have at least one logical address by which they can be accessed. However, it is simple to change the logical address of most devices. Therefore, any program that uses a constant as a logical address of a particular device can fail if that device is reassigned to a different logical address.
Chapter 2 Introduction to the NI-VXI Functions Word Serial Communication When communicating with a message-based devices (MBD) in VXI, the protocol for string passing is known as Word Serial. The term is derived from the fact that all commands are 16 bits in length (word length), and that strings are sent serially, or one byte at a time. VXI also accommodates Long Word Serial (32-bit commands), and Extended Long Word Serial (48-bit commands). However, the VXIbus specification revision 1.
Chapter 2 Introduction to the NI-VXI Functions Master Memory Access You can access VXIbus memory directly through the NI-VXI high-level and low-level VXIbus access functions, within the capabilities of the controller. The main difference between the high-level and low-level access functions is in the amount of encapsulation given by NI-VXI.
Chapter 2 Introduction to the NI-VXI Functions timeout = 2000L; /* 2 seconds */ /* Notice the use of the macros for defining the access */ /* parameters.
Chapter 2 Introduction to the NI-VXI Functions Note: On modern, 32-bit operating systems running on high-performance processors (such as Microsoft Windows NT on a Pentium or Solaris 2 on a SPARC), we have found no performance gained by using macros instead of functions. For this reason, we strongly recommend that you use functions on these platforms to allow your program to be more portable across future platforms.
Chapter 2 Introduction to the NI-VXI Functions /* At this point, the remote master can perform */ /* I/O on the shared, allocated space.
Chapter 2 Introduction to the NI-VXI Functions Alternatively, you can choose to handle either signals or interrupts with a callback handler. You can use RouteSignal() to specify that the events should be handled by the callback handlers rather than the signal queue. After you have enabled the callback handler through either the EnableSignalInt() or the EnableVXIint() call, the callback function will be invoked when the event occurs.
Chapter 2 Note: Introduction to the NI-VXI Functions Although NI-VXI simplifies the installation and use of callback handlers, it cannot affect how the system handles interrupts. The programmer must follow programming guidelines set by the chosen operating system. Some of these guidelines could include using only reentrant functions, adhering to timing restrictions, and on Macintosh computers, regaining access to global variables.
Chapter 3 Software Overview This chapter describes the C/C++ and BASIC usage of VXI and VME functions and briefly describes each function. Functions are listed alphabetically in each functional group. System Configuration Functions The VXI system configuration functions copy all of the Resource Manager (RM) table information into data structures at startup so that you can find device names or logical addresses by specifying certain attributes of the device for identification purposes.
Chapter 3 Software Overview CloseVXIlibrary () CloseVXIlibrary is the application termination routine, which must be included at the end (or abort) of any application. CloseVXIlibrary disables interrupts and frees dynamic memory allocated for the internal RM table and other structures. You must include a call to CloseVXIlibrary at the termination of your application (for whatever reason) to free all data structures allocated by InitVXIlibrary and disable interrupts.
Chapter 3 Software Overview GetDevInfo (la, field, fieldvalue) GetDevInfo returns information about the specified device from the NI-VXI RM table. The field parameter specifies the attribute of the information to retrieve. Possible fields include the device name, Commander’s logical address, mainframe number, slot, manufacturer ID number, model code, model name, device class, VXI address space/base/size allocated, VXI interrupt lines/handlers allocated, protocols supported, and so on.
Chapter 3 Software Overview InitVXIlibrary () InitVXIlibrary is the NI-VXI initialization routine. An application must call InitVXIlibrary at application startup. InitVXIlibrary performs all necessary installation and initialization procedures to make the NI-VXI interface functional. This includes copying all of the RM device information into the data structures in the NI-VXI library.
Chapter 3 Software Overview SetDevInfoShort (la, field, shortvalue) SetDevInfoShort changes information about the specified device in the NI-VXI RM table. The field parameter specifies the attribute of the information to change. SetDevInfoShort is a function layered on top of SetDevInfo for languages (such as BASIC) that cannot typecast the fieldvalues of SetDevInfo. SetDevInfoShort changes only the fields of SetDevInfo that are 16-bit integers.
Chapter 3 Software Overview • Buffer writes • Buffer reads The Word Serial Protocol is a 16-bit transfer protocol between a Commander and its Servants. The Commander polls specific bits in the Servant’s VXI Response register to determine when it can write a command, when it can read a response from the Data Low register, and when a Word Serial protocol error occurs.
Chapter 3 Software Overview In addition to the four basic types of Word Serial transfers, there are two special cases: the Word Serial Clear and Trigger commands. The Word Serial Clear command must ignore the ERR* bit. One of the functions of the Clear command is to clear a pending protocol error condition. If the ERR* bit was polled during the transfer, the Clear would not succeed.
Chapter 3 Software Overview The WSabort function is the only exception to this restriction. WSabort is used to abort various Word Serial transfers in progress and will usually be called from an interrupt service routine (although it is not limited to interrupt service routines). The most common example of calling this function from an interrupt service routine is with the handling of Unrecognized Command events from a device.
Chapter 3 Software Overview Figure 3-1 gives a precise description of this two-level mutual exclusion algorithm. Notice that this mutual exclusion is on a per logical address basis. Any number of logical addresses can have Word Serial transfers in progress without conflict. If the application is to be compatible with IEEE 488.2, the application must perform trigger and write calls in sequential order. WSwrt, WSwrtf WStrg WSrd, WSrdf Wrt and Trg Exclusion Write and trigger ordering for IEEE 488.
Chapter 3 Software Overview until the transfer is complete or a timeout occurs. This support also keeps a word serial device which is not responding from “hanging” on the local CPU. The following paragraphs describe the Commander Word Serial, Longword Serial, and Extended Longword Serial Protocol functions. The descriptions are grouped by functionality and are presented at a functional level describing the operation of each of the functions.
Chapter 3 Software Overview WSEcmd (la, cmdExt, cmd, respflag, response) WSEcmd sends an Extended Word Serial command or query to a message-based Servant. It polls the WR bit before sending the 48-bit command.
Chapter 3 Software Overview Normally, you would use the WSLcmd function to send Longword Serial queries with the response automatically read (specified with respflag). In cases when you need to inspect the Longword Serial transfer at a lower level, however, you can break up the query sending and query response retrieval by using the WSLcmd function to send the query as a command, and using the WSLresp function to retrieve the response.
Chapter 3 Software Overview Normally, you would use the WScmd function to send Word Serial queries with the response automatically read (specified with respflag). In cases when you need to inspect the Word Serial transfer at a lower level, however, you can break up the query sending and query response retrieval by using the WScmd function to send the query as a command and using the WSresp function to retrieve the response.
Chapter 3 Software Overview WSwrtf (la, filename, count, modevalue, retcount) WSwrtf is an extension of the WSwrt function. WSwrtf writes a specified number of bytes from the specified file to a message-based Servant using the VXIbus Byte Transfer Protocol. The process involves calling the WSwrt function (possibly many times) to write out a block of data read from the specified file. The modevalue parameter in the call specifies whether to send BAV only or BAV with END for the last byte of the transfer.
Chapter 3 Software Overview A buffer write is a series of Byte Available Word Serial commands sent to the Servant, with the additional constraint that the Data In Ready (DIR) bit as well as the WR bit must be asserted before sending the Byte Available command. The lower 8 bits (bits 0 to 7) of the 16-bit command contain a single byte of data (bit 8 is the END bit). Therefore, one Byte Available is sent for each data byte in the buffer written.
Chapter 3 Software Overview (DIR, DOR, WR, RR, and ERR*) are done automatically within the functions as required. Figure 3-2 provides a graphical overview of the Servant Word Serial functions.
Chapter 3 Software Overview DefaultWSScmdHandler (cmd) DefaultWSScmdHandler is the default handler for the WSSwrt interrupt, which InitVXIlibrary automatically installs when it initializes the NI-VXI software. The current WSScmdHandler is called whenever the local CPU Commander sends any Word Serial Protocol command or query (other than BAV or BREQ).
Chapter 3 Software Overview DefaultWSSLcmdHandler calls GenProtError with a protocol error code of UnSupCom for every Longword Serial command received. DefaultWSSrdHandler (status, count) DefaultWSSrdHandler is the default handler for the WSSrd interrupt, which InitVXIlibrary automatically installs when it initializes the NI-VXI software. When WSSrd reaches the specified count or an END bit, or an error occurs, it calls the WSSrd interrupt handler with the status of the call.
Chapter 3 Software Overview GetWSSEcmdHandler () GetWSSEcmdHandler returns the address of the current WSSEcmd interrupt handler function. While Word Serial operations are enabled, the WSSEcmd interrupt handler will be called every time an Extended Longword Serial command is received. GetWSSLcmdHandler () GetWSSLcmdHandler returns the address of the current WSSLcmd interrupt handler function.
Chapter 3 Software Overview default handler provides examples of how to parse commands, respond to queries, and generate protocol errors. SetWSSEcmdHandler (func) SetWSSEcmdHandler replaces the current WSSEcmd interrupt handler with an alternate handler. While Word Serial operations are enabled, the WSSEcmd interrupt handler is called whenever an Extended Longword Serial command is received.
Chapter 3 Software Overview WSSabort (abortop) WSSabort aborts the Servant Word Serial operation(s) in progress. It returns an error code of ForcedAbort to the WSSrd or WSSwrt interrupt handlers in response to the corresponding pending functions. This may be necessary if the application needs to abort for some application-specific reason, or if the Commander of this device sends a Word Serial Clear, End Normal Operation, or Abort command.
Chapter 3 Software Overview WSSnoResp () WSSnoResp sets the WR bit so that it is ready to accept any further Word Serial commands. The WSScmd interrupt handler should call WSSnoResp after processing a Word Serial command (it calls WSSsendResp for a Word Serial query, which requires a response). WSSrd (buf, count, modevalue) WSSrd is the buffer read function.
Chapter 3 Software Overview High-Level VXI/VMEbus Access Functions You can use both low-level and high-level VXI/VMEbus access functions to read or write to VXI/VMEbus addresses.
Chapter 3 Software Overview VXI/VMEbus access functions. You can use both high-level and low-level VXI/VMEbus access functions at the same time. The following paragraphs describe the high-level VXI/VMEbus access functions. VXIin (accessparms, address, width, value) VXIin reads a single byte, word, or longword from a particular VXI/VME address in one of the VXI address spaces.
Chapter 3 Software Overview address space for the source and destination, respectively. The width parameter selects either byte, word, or longword transfers. If one of the addresses selected has no device residing at the address and a bus error occurs, VXImove traps the bus error condition and indicates the error through the return status. VXIout (accessparms, address, width, value) VXIout writes a single byte, word, or longword to a particular VXI/VME address in one of the VXI/VME address spaces.
Chapter 3 Software Overview Low-Level VXI/VMEbus Access Functions This section describes the use of the low-level VXI/VMEbus access functions. You can use both low-level and high-level VXI/VMEbus access functions to directly read or write to VXI/VMEbus addresses.
Chapter 3 Software Overview Programming Considerations All accesses to the VXI/VMEbus address spaces are performed by reads and writes to particular offsets within the local CPU address space, which are made to correspond to addresses on the VXI/VMEbus (using a hardware interface). The areas where the address space of the local CPU is mapped onto the VXI/VMEbus are referred to as windows. The sizes and numbers of windows present vary depending on the hardware being used.
Chapter 3 Software Overview Multiple-Pointer Access for a Window Application programmers can encounter a potential problem when the application requires different privilege states, byte orders, and/or base addresses within the same window. If the hardware context changes due to a subsequent call to MapVXIAddress or other calls such as SetPrivilege or SetByteOrder, previously mapped pointers would not have their intended access parameters.
Chapter 3 Software Overview can have multiple pointers in the same process or over multiple processes to access a particular window simultaneously, while still guaranteeing that the hardware context does not change between accesses. The call succeeds under either of the following conditions: • No processes are mapped for the window (first caller for Access-Only Privilege for this window). The hardware context is set as requested in the call.
Chapter 3 Software Overview GetByteOrder (window, ordermode) GetByteOrder retrieves the byte/word order of data transferred into or out of the specified window. The two possible settings are Motorola (most significant byte/word first) or Intel (least significant byte/word first). The application can have either Owner-Access Privilege or Access-Only Privilege to the applicable window for this function to execute successfully.
Chapter 3 Software Overview GetVXIbusStatusInd (controller, field, status) GetVXIbusStatusInd retrieves information about the current state of the VXI/VMEbus. The information that can be returned includes the state of the Sysfail, ACfail, VXI interrupt, TTL trigger, or ECL trigger lines as well as the number of VXI signals on the global signal queue. The specified information returns in a single integer value. The field parameter specifies the particular VXI/VMEbus information to be returned.
Chapter 3 Software Overview MapVXIAddressSize (size) MapVXIAddressSize sets the size for mapping user windows. The subsequent calls to MapVXIAddress will attempt to map a window of the size passed to MapVXIAddressSize. MapVXIAddressSize only provides a preferred size to the MapVXIAddress. If it is not possible to map a window to the given size, MapVXIAddress can use a different size. To determine the exact size of window mapped, use the GetWindowRange function.
Chapter 3 Software Overview SetPrivilege (window, priv) SetPrivilege sets the VXI/VMEbus windowing hardware to access the specified window with the specified VXI/VMEbus access privilege. The possible privileges include Nonprivileged Data, Supervisory Data, Nonprivileged Program, Supervisory Program, Nonprivileged Block, and Supervisory Block access. The application must have Owner-Access Privilege to the applicable window for this function to execute successfully.
Chapter 3 Software Overview Local Resource Access Functions Local resources are hardware and/or software capabilities that are reserved for the local CPU (the CPU on which the NI-VXI interface resides). You can use these functions to gain access to miscellaneous local resources such as the local CPU register set and the local CPU Shared RAM. These functions are useful for shared memory type communication, non-Resource Manager operation, and debugging purposes.
Chapter 3 Software Overview VXIinLR (reg, width, value) VXIinLR reads a single byte, word, or longword from the local CPU VXI/VME registers. On many CPUs, the local CPU VXI/VME registers cannot be accessed from the local CPU in the A16 address space window (due to hardware limitations). Another area in the local CPU address space is reserved for accessing the local CPU VXI registers. VXIinLR is designed to read these local registers.
Chapter 3 Software Overview VXIoutLR (reg, width, value) VXIoutLR writes a single byte, word, or longword to the local CPU VXI/VME registers. On many CPUs, the local CPU VXI/VME registers cannot be accessed from the local CPU in the A16 address space window (due to hardware limitations). Another area in the local CPU address space is reserved for accessing the local CPU VXI registers. VXIoutLR is designed to write to these local VXI/VME registers.
Chapter 3 Software Overview VXI signals from message-based devices can be one of two types: Response signals and Event signals (bit 15 distinguishes between the two). Response signals are used to report changes in Word Serial communication status between a Servant and its Commander. Event signals are used to inform another device of other asynchronous changes.
Chapter 3 Software Overview Programming Considerations The global signal queue used to hold signal values is of a finite length. If the application is not handling signals fast enough, it is theoretically possible to fill the global signal queue. If the global signal queue becomes full, DisableSignalInt is called to inhibit more signals from being received.
Chapter 3 Software Overview Figure 3-3 provides a graphical overview of the NI-VXI interrupt and signal functions.
Chapter 3 Software Overview returned immediately to the caller and the process/function is not suspended. The following paragraphs describe the VXI signal functions and default handler. The descriptions are presented at a functional level describing the operation of each of the functions. The functions are grouped by area of functionality.
Chapter 3 Software Overview GetSignalHandler (la) GetSignalHandler returns the address of the current signal handler for the specified VXI logical address. If signal interrupts are enabled (via EnableSignalInt), the signal handler for a specific logical address is called if the RouteSignal function has been set up to route signals to the handler (as opposed to the global signal queue).
Chapter 3 Software Overview SignalDeq (la, signalmask, signal) SignalDeq retrieves signals from the global signal queue. Two methods are available to handle VXI signals. You can handle the signals either by handlers or by queueing on a global signal queue. The RouteSignal function specifies which types of signals should be handled by which of the two methods for each VXI logical address. You can use SignalDeq to selectively dequeue a signal off of the global signal queue.
Chapter 3 Software Overview VXI Interrupt Functions VXI/VME interrupts are a basic form of asynchronous communication used by devices with interrupter support. In VME, a device asserts a VME interrupt line and the VME interrupt handler device acknowledges the interrupt. During the VME interrupt acknowledge cycle, an 8-bit status/ID value is returned. Most 680x0-based VME CPUs use this 8-bit value as a local interrupt vector value routed directly to the 680x0 processor.
Chapter 3 Software Overview specifies which types of signals are handled by signal handlers, and which are queued onto the global signal queue for each VXI logical address. A separate handler can be installed for each VXI logical address present (refer to the description for SetSignalHandler). A default handler, DefaultSignalHandler, is automatically installed when InitVXIlibrary is called from the application for every VXI logical address.
Chapter 3 Software Overview DeAssertVXIint and AcknowledgeVXIint are intended only for debugging purposes. Programming Considerations Figure 3-4 is a graphical overview of the NI-VXI interrupt and signal model.
Chapter 3 Software Overview ROAK Versus RORA VXI/VME Interrupters There are two types of VXI/VME interrupters. The Release On Acknowledge (ROAK) interrupter is the more common. A ROAK interrupter automatically unasserts the VXI/VME interrupt line it is asserting when an interrupt acknowledge cycle on the backplane occurs on the corresponding level. The VXIbus specification requires that all message-based devices be ROAK interrupters.
Chapter 3 Software Overview Normally, VXI/VME interrupts are automatically acknowledged when enabled via the function EnableVXIint. However, if the interrupts are not enabled and the assertion of an interrupt is detected through some method (such as GetVXIbusStatus), you can use AcknowledgeVXIint to acknowledge an interrupt and return the status/ID value.
Chapter 3 Software Overview DefaultVXIintHandler sets the global variables VXIintController, VXIintLevel, and VXIintStatusId. You can leave this default handler installed or install a completely new handler using SetVXIintHandler. DisableVXIint (controller, levels) DisableVXIint desensitizes the application to specified VXI interrupt levels being processed as VXI/VME interrupts (not as VXI signals). EnableVXIint enables VXI/VME interrupts to be handled as VXI/VME interrupts (not as VXI signals).
Chapter 3 Software Overview frame (for an embedded CPU) or the first extended controller (in an external CPU situation). EnableVXItoSignalInt (controller, levels) EnableVXItoSignalInt is used to sensitize the application to specified interrupt levels being processed as VXI signals. After calling InitVXIlibrary, the application can sensitize itself to interrupt levels for which it is configured to handle.
Chapter 3 Software Overview queue. The RouteSignal function specifies which types of signals should be handled by signal handlers, and which should be queued on the global signal queue for each VXI logical address. If the VXI/VME interrupt status/IDs are specified to be handled by a VXI/VME interrupt handler, the level and status/ID value is sent to the appropriate callback handler when an interrupt occurs. An individual handler can be installed for each of the seven VXI/VME interrupt levels.
Chapter 3 Software Overview VXI Trigger Functions VXI triggers are a backplane feature that VXI added to the VME standard. Tight timing and signaling is important between many types of controllers and/or instruments. In the past, clumsy cables of specified length had to be connected between controllers and/or instruments to get the required timing. For many systems, phase shifting and propagation delays had to be calculated precisely, based on the instrument connection scheme.
Chapter 3 Software Overview maximum time from source assertion edge). The accepting device(s) can later unassert the trigger line (no maximum time is specified) to complete the handshake. • START/STOP—START/STOP is a one-line, multiple-device protocol. START/STOP can be sourced only by the VXI Slot 0 device and sensed by any other devices on the VXI backplane. The START/STOP protocol is synchronized with the backplane clock (CLK10 for TTL, CLK100 and SYNC100 for ECL) onto any one of the trigger lines.
Chapter 3 Software Overview general, however, National Instruments hardware has two current configurations that provide triggering functionality: • Note: Trigger control used on a VXI-MXI-1 frame extender when used as an extending controller (under direct control of a root-level MXI-1 controller interface, such as an AT-MXI-1). These configurations do not have the National Instruments Trigger Interface Chip (TIC) on them.
Chapter 3 Software Overview Embedded, External MXI-2, and Remote Controller Trigger Capabilities National Instruments has developed a highly functional ASIC specifically designed for use within the VXIbus triggering environment called the Trigger Interface Chip (TIC). Note: In MXI-2 and the latest embedded systems, the TIC has been incorporated into the MANTIS ASIC.
Chapter 3 Software Overview AcknowledgeTrig (controller, line) AcknowledgeTrig performs the required trigger acknowledgments for the ASYNC or SEMI-SYNC VXI-defined protocol, as configured via the EnableTrigSense function. DefaultTrigHandler (controller, line, type) DefaultTrigHandler is the sample handler for the receiving acknowledges and sensing triggers, and is automatically installed after a call to InitVXIlibrary.
Chapter 3 Software Overview GetTrigHandler (line) GetTrigHandler returns the address of the current trigger handler for the specified VXI trigger line. SetTrigHandler (lines, func) SetTrigHandler replaces the current trigger handler for the specified VXI trigger lines with an alternate handler. WaitForTrig (controller, line, timeout) You can use the WaitForTrig function to suspend operation until it receives a trigger configured by the EnableTrigSense function.
Chapter 3 Software Overview crosspoint switch configurator (depending on the hardware capabilities of the applicable device). UnMapTrigToTrig (controller, srcTrig, destTrig) UnMapTrigToTrig unconfigures triggering hardware that was configured by the MapTrigToTrig function to route specified source trigger locations to destination trigger locations.
Chapter 3 Software Overview Trigger Configuration Functions You can use the NI-VXI trigger configuration functions to configure not only the general settings of the trigger inputs and outputs, but also the TIC counter and tick timers. TrigAssertConfig (controller, trigline, mode) TrigAssertConfig configures the local triggering generation method for the TTL/ECL triggers. You can decide on an individual basis whether to synchronize the triggers to CLK10.
Chapter 3 Software Overview panel. GPIO 3 is fed back in as the EXTCLK signal used for signal conditioning modes with MapTrigToTrig. The six remaining GPIOs are dependent upon the hardware platform. Regardless of the sources connected to the GPIOs, TrigExtConfig configures several aspects of the connection. You can disconnect and feed back the connection for use as a crosspoint switch. You can also choose whether to invert the external input.
Chapter 3 Software Overview The following paragraphs describe the system interrupt handler functions and default handlers. The descriptions are presented at a functional level describing the operation of each of the functions. The functions are grouped by area of functionality. AssertSysreset (controller, mode) AssertSysreset asserts the SYSRESET* signal on the specified controller. You can use this function to reset the local CPU, individual mainframes, all mainframes, or the entire system.
Chapter 3 Software Overview low-level VXI/VMEbus access functions will be reported to this handler. See also the descriptions of SetBusErrorHandler and GetBusErrorHandler. DefaultSoftResetHandler () DefaultSoftResetHandler is the sample handler for the Soft Reset interrupt, and is installed as a default handler when InitVXIlibrary initializes the NI-VXI software. It increments the global variable SoftResetRecv.
Chapter 3 Software Overview DefaultSysresetHandler (controller) DefaultSysresetHandler is the sample handler for the Sysreset interrupt, and is installed as a default handler when InitVXIlibrary initializes the NI-VXI software. It increments the global variable SysresetRecv. DisableACfail (controller) DisableACfail desensitizes the application to ACfail interrupts from embedded controller or extended controller(s) ACfail conditions (dependent on the hardware platform).
Chapter 3 Software Overview state, the failed device clears its PASS bit (in its Status register) and asserts the SYSFAIL* signal on the VXIbus backplane. DisableSysreset (controller) DisableSysreset desensitizes the application to Sysreset interrupts from embedded or extended controller(s) (dependent on the hardware platform).
Chapter 3 Software Overview specification requires that all VXI Commanders monitor the PASSed or FAILed state of their VXI Servants. When a VXIbus device is in the FAILed state, the failed device clears its PASS bit (in its Status register) and asserts the SYSFAIL* signal on the VXIbus backplane. When a Sysfail condition is detected on the local CPU, an interrupt is generated, and the current Sysfail interrupt handler is called.
Chapter 3 Software Overview GetSoftResetHandler () GetSoftResetHandler returns the address of the current Soft Reset interrupt handler. A default handler, DefaultSoftResetHandler, is automatically installed when InitVXIlibrary initializes the NI-VXI software. Note: The Soft Reset interrupt does not apply to VME. GetSysfailHandler () GetSysfailHandler returns the address of the current Sysfail interrupt handler.
Chapter 3 Software Overview errors at times and valid results at other times. The InitVXIlibrary function automatically installs a default handler, DefaultBusErrorHandler, when it initializes the NI-VXI software. Because bus errors can occur at any time, a corresponding enable and disable function is not possible. SetSoftResetHandler (func) SetSoftResetHandler replaces the current Soft Reset interrupt handler with an alternate handler.
Chapter 3 Software Overview VXI/VMEbus Extender Functions The NI-VXI software interface fully supports the standard VXIbus extension method presented in the VXIbus Mainframe Extender Specification. When the National Instruments Resource Manager (RM) completes its configuration, all default transparent extensions are complete. The transparent extensions include extensions of VXI/VME interrupt, TTL trigger, ECL trigger, Sysfail, ACfail, and Sysreset signals.
Chapter 3 Software Overview you can use MapTTLtrig to configure the mainframe-to-mainframe mapping. The NI-VXI Resource Manager automatically configures a default mapping based on the user-modifiable configuration files. The MapTTLtrig function can dynamically reconfigure the TTL trigger mapping. Only special circumstances should require any changes to the default configuration.
Appendix A Function Classification Reference This appendix contains two tables you can use as a quick reference. Table A-1, Function Listing by Group, lists the NI-VXI functions by their group association. This arrangement can help you determine easily which functions are available within each group. Table A-2, Function Listing by Name, lists each function alphabetically. You can refer to this table if you don’t remember the group association of a particular function.
Appendix A Function Classification Reference Table A-1.
Appendix A Function Classification Reference Table A-1.
Appendix A Function Classification Reference Table A-1.
Appendix A Function Classification Reference Table A-1.
Appendix A Function Classification Reference Table A-1.
Appendix A Function Classification Reference Table A-2.
Appendix A Function Classification Reference Table A-2.
Appendix A Function Classification Reference Table A-2.
Appendix A Function Classification Reference Table A-2.
Appendix A Function Classification Reference Table A-2.
Appendix A Function Classification Reference Table A-2.
Appendix A Function Classification Reference Table A-2.
Appendix Customer Communication B For your convenience, this appendix contains forms to help you gather the information necessary to help us solve technical problems you might have as well as a form you can use to comment on the product documentation. Filling out a copy of the Technical Support Form before contacting National Instruments helps us help you better and faster. National Instruments provides comprehensive technical assistance around the world. In the U.S.
FaxBack Support FaxBack is a 24-hour information retrieval system containing a library of documents on a wide range of technical information. You can access FaxBack from a touch-tone telephone at (512) 418-1111. E-Mail Support (currently U.S. only) You can submit technical support questions to the appropriate applications engineering team through e-mail at the Internet addresses listed below. Remember to include your name, address, and phone number so we can contact you with solutions and suggestions.
Technical Support Form Photocopy this form and update it each time you make changes to your software or hardware, and use the completed copy of this form as a reference for your current configuration. Completing this form accurately before contacting National Instruments for technical support helps our applications engineers answer your questions more efficiently.
Documentation Comment Form National Instruments encourages you to comment on the documentation supplied with our products. This information helps us provide quality products to meet your needs. Title: NI-VXI™ User Manual Edition Date: July 1996 Part Number: 371702A-01 Please comment on the completeness, clarity, and organization of the manual.
Glossary Prefix Meaning Value n- nano- 10-9 m- milli- 10-3 K- kilo- 103 M- mega- 106 G- giga- 109 A A16 space One of the VXIbus address spaces. Equivalent to the VME 64 KB short address space. In VXI, the upper 16 KB of A16 space is allocated for use by VXI devices configuration registers. This 16 KB region is referred to as VXI configuration space. A24 space One of the VXIbus address spaces. Equivalent to the VME 16 MB standard address space.
Glossary address modifier One of six signals in the VMEbus specification used by VMEbus masters to indicate the address space and mode (supervisory/nonprivileged, data/program/block) in which a data transfer is to take place. address space A set of 2n memory locations differentiated from other such sets in VXI/VMEbus systems by six signal lines known as address modifiers. n is the number of address lines required to uniquely specify a byte location in a given space.
Glossary BAV Word Serial Byte Available command. Used to transfer 8 bits of data from a Commander to its Servant under the Word Serial Protocol. BERR* Bus error signal. This signal is asserted by either a slave device or the bus time out (BTO) unit when an incorrect transfer is made on the Data Transfer Bus (DTB). The BERR* signal is also used in VXI for certain protocol implementations such as writes to a full Signal register and synchronization under the Fast Handshake Word Serial Protocol.
Glossary C clearing Replacing the information in a register, storage location, or storage unit with zeros or blanks. CLK10 A 10 MHz, ± 100 ppm, individually buffered (to each module slot), differential ECL system clock that is sourced from Slot 0 and distributed to Slots 1 through 12 on P2. It is distributed to each slot as a single-source, single-destination signal with a matched delay of under 8 ns. command A directive to a device.
Glossary D Data Transfer Bus One of four buses on the VMEbus backplane. The DTB is used by a bus master to transfer binary data between itself and a slave device. decimal Numbering system based upon the 10 digits 0 to 9. Also known as base 10. de-referencing Accessing the contents of the address location pointed to by a pointer. default handler Automatically installed at startup to handle associated interrupt conditions; the software can then replace it with a specified handler. DIR Data In Ready.
Glossary EOS End Of String; a character sent to designate the last byte of a data message. ERR Protocol error Event signal A 16-bit value written to a message-based device’s Signal register in which the most significant bit (bit 15) is a 1, designating an Event (as opposed to a Response signal). The VXI specification reserves half of the Event values for definition by the VXI Consortium. The other half are user defined.
Glossary GPIO General-Purpose Input Output, a module within the National Instruments TIC chip which is used for two purposes. First, GPIOs are used for connecting external signals to the TIC chip for routing/conditioning to the VXIbus trigger lines. Second, GPIOs are used as part of a crosspoint switch matrix. H handshaking A type of protocol that makes it possible for two devices to synchronize operations. hardware context The hardware setting for address space, access privilege, and byte ordering.
Glossary IEEE 488.2 A supplemental standard for GPIB. Its full title is Codes, Formats, Protocols and Common Commands. INT16 A 16-bit signed integer; may also be called a short integer or word. INT32 A 32-bit signed integer; may also be called a long or longword. INT8 An 8-bit signed integer; may also be called a char. interrupt A means for a device to notify another device that an event occurred.
Glossary M 20 MB 1,048,576 or 2 mapping Establishing a range of address space for a one-to-one correspondence between each address in the window and an address in VXIbus memory. master A functional part of a MXI/VME/VXIbus device that initiates data transfers on the backplane. A transfer can be either a read or a write. megabyte A million bytes.
Glossary N NI-VXI The National Instruments bus interface software for VME/VXIbus systems. nonprivileged access One of the defined types of VMEbus data transfers; indicated by certain address modifier codes. Each of the defined VMEbus address spaces has a defined nonprivileged access mode. NULL A special value to denote that the contents (usually of a pointer) are invalid or zero. O octal Numbering system with base 8, using numerals 0 to 7.
Glossary queue A group of items waiting to be acted upon by the computer. The arrangement of the items determines their processing priority. Queues are usually accessed in a FIFO fashion. R read To get information from any input device or file storage media. register A high-speed device used in a CPU for temporary storage of small amounts of data or intermediate results during processing. register-based device A Servant-only device that supports only the four basic VXIbus configuration registers.
Glossary ROAK Release On Acknowledge; a type of VXI interrupter which always deasserts its interrupt line in response to an IACK cycle on the VXIbus. All message-based VXI interrupters must be ROAK interrupters. ROR Release On Request; a type of VME bus arbitration where the current VMEbus master relinquishes control of the bus only when another bus master requests the VMEbus.
Glossary signal Any communication between message-based devices consisting of a write to a Signal register. Sending a signal requires that the sending device have VMEbus master capability. signed integer n bit pattern, interpreted such that the range is from -2(n-1) to +2(n-1) -1. slave A functional part of a MXI/VME/VXIbus device that detects data transfer cycles initiated by a VMEbus master and responds to the transfers when the address specifies one of the device’s registers.
Glossary System Controller A functional module that has arbiter, daisy-chain driver, and MXIbus cycle timeout responsibility. Always the first device in the MXIbus daisy-chain. system hierarchy The tree structure of the Commander/Servant relationships of all devices in the system at a given time. In the VXIbus structure, each Servant has a Commander. A Commander can in turn be a Servant to another Commander.
Glossary V VIC VXI Interactive Control program, a part of the NI-VXI bus interface software package. Used to program VXI devices, and develop and debug VXI application programs. Called VICtext when used on textbased platforms. VME Versa Module Eurocard or IEEE 1014 VMEbus Class device Also called non-VXIbus or foreign devices when found in VXIbus systems. They lack the configuration registers required to make them VXIbus devices.
Glossary WRviol Write Ready protocol violation; a type of Word Serial Protocol error. If a Commander attempts to write a command or query to a Servant that is not Write Ready (already has a command or query pending), a Write Ready protocol violation may be generated.
Index A C acceptor trigger functions AcknowledgeTrig, 3-55 DefaultTrigHandler, 3-55 DefaultTrigHandler2, 3-55 DisableTrigSense, 3-55 EnableTrigSense, 3-55 GetTrigHandler, 3-56 overview, 3-54 SetTrigHandler, 3-56 WaitForTrig, 3-56 access functions. See high-level VXI/VMEbus access functions; local resource access functions; low-level VXI/VMEbus access functions.
Index WScmd, 3-10 WSEcmd, 3-11 WSgetTmo, 3-11 WSLcmd, 3-11 WSLresp, 3-11 to 3-12 WSrd, 3-12 WSrdf, 3-12 WSresp, 3-12 to 3-13 WSsetTmo, 3-13 WStrg, 3-13 WSwrt, 3-13 WSwrtf, 3-14 configuration functions. See system configuration functions; trigger configuration functions.
Index external controllers, 2-6 to 2-7 definition, 2-6 embeddded controller connected to other frames (figure), 2-6 embeddded controller connected using MXI-2 (figure), 2-7 GetWSSrdHandler function, 3-19 GetWSSwrtHandler function, 3-19 global signal queue, 3-38 H hardware context high-level VXI/VMEbus access functions, 3-23 low-level VXI/VMEbus access functions, 3-27 header files, 2-9 to 2-10 busacc.h file, 2-10 datasize.h file, 2-9 devinfo.
Index interrupts interrupt service routine support, Commander Word Serial Protocol functions, 3-7 to 3-8 interrupts and asynchronous events, 1-4 to 1-5 Owner Privilege, 3-28 overview, 2-2, 3-26 to 3-27 programming considerations, 3-27 SetByteOrder, 3-32 SetContext, 3-32 SetPrivilege, 3-33 UnMapVXIAddress, 3-33 VXIpeek, 3-28, 3-33 VXIpoke, 3-28, 3-33 L LabWindows/CVI software, 2-4 to 2-5 C/C++ example, 2-4 input versus output parameters, 2-4 to 2-5 return values and system errors, 2-4 to 2-5 type definiti
Index multiple-pointer access for window, 3-28 to 3-29 Access-Only Privilege, 3-28 to 3-29 Owner Privilege, 3-28 multitasking support, Commander Word Serial Protocol functions cooperative, 3-7 to 3-8 preemptive operating system, 3-8 to 3-10 MXI-2 overview, 1-5 to 1-6 MXIbus overview, 1-5 extender and controller parameters, 2-7 to 2-8 using NI-VXI, 2-9 to 2-19 beginning and end of programs, 2-10 to 2-11 header files, 2-9 to 2-10 interrupts and signals, 2-17 to 2-19 master memory access, 2-14 to 2-16 slave
Index Request for Service False (REQF) event, 3-37 Request for Service False (REQF) status/ID, 3-37 Request for Service True (REQT) event, 3-37 Request for Service True (REQT) status/ID, 3-37 Response signals, 3-37 Response status/IDs, 3-43 RespProtError function, 3-19 return values and system errors, 2-5 ROAK (Release On Acknowledge) interrupter, 3-46 RORA (Release On Register Access) interrupter, 3-46 round-robin effect of Commander Word Serial function calls, 3-9 RouteSignal function description, 3-41 V
Index SetWSSEcmdHandler function, 3-20 SetWSSLcmdHandler function, 3-20 SetWSSrdHandler function, 3-20 SetWSSwrtHandler function, 3-20 Shared Memory events, 3-37, 3-43 signal handling C/C++ example, 2-18 overview, 2-17 to 2-18 signal queuing considerations, 3-38 to 3-39 SignalDeq function, 3-42 SignalEnq function, 3-42 SignalJam function, 3-42 single-tasking operating system support, Commander Word Serial Protocol functions, 3-7 to 3-8 slave memory access C/C++ example, 2-16 to 2-17 overview, 2-16 source t
Index START/STOP, 3-52 SYNC, 3-51 triggering hardware capabilities, 3-52 to 3-54 embedded, external MXI-2, and remote controller, 3-54 external controller/VXI-MXI-1, 3-53 triggers definition, 3-51 overview, 2-19 VXIintAcknowledgeMode, 3-46, 3-50 VXI-only function groups, 2-3 VXI signal functions alphabetical list (table), A-4 DefaultSignalHandler, 3-40 DisableSignalInt, 3-38, 3-40 EnableSignalInt, 3-40 GetSignalHandler, 3-41 overview, 2-2, 3-36 to 3-37 programming considerations, 3-38 to 3-39 RouteSignal,
Index map trigger functions MapTrigToTrig, 3-56 to 3-57 overview, 3-56 UnMapTrigToTrig, 3-57 overview, 2-3, 3-51 to 3-52 source trigger functions overview, 3-57 ScrTrig, 3-57 trigger configuration functions overview, 3-58 TrigAssertConfig, 3-58 TrigCntrConfig, 3-58 TrigExtConfig, 3-58 to 3-59 TrigTickConfig, 3-59 VXI/VME function groups, 2-1 to 2-3 VXI/VMEbus extender functions alphabetical list (table), A-7 MapECLtrig, 3-67 MapTTLtrig, 3-67 to 3-68 MapUtilBus, 3-68 MapVXIint, 3-68 overview, 2-2 to 2-3, 3-
Index WSSLnoResp function, 3-21, 3-22 WSSLsendResp function, 3-21 WSSrd function, 3-22 WSSsendResp function, 3-22 WSSwrt function, 3-22 WStrg function, 3-13 WSwrt function, 3-13 WSwrtf, 3-14 NI-VXI User Manual I-10 © National Instruments Corporation
