MTS HW driverThe HW package - MTS (Marvin Test Solutions) Hardware Access Driver, is used by all MTS instrument drivers and ATEasy to access the PC resources (memory, IO ports, DMA etc), to set/query the PCI/PXI configuration and more.
The HW package includes libraries used to program and create instrument drivers for PCI/cPCI/PXI based instruments, including the PCI Express (PCIe) derivatives. PXI/PCI Explorer , a utility to configure and display PXI/PC based systems, is also included. This utility includes a VISA configuration manager for PXI and PXI express instruments (similar to NI-MAX), and supports MTS and other vendors PXI chassis, controllers and bus expanders.
The MTS HW driver is used by, and installed with all MTS software packages, including ATEasy and all MTS instrument drivers. It is also available as a stand alone package, to download the current HW software click here.
Once installed the HW driver includes the following files: | |
- HwSetup.exe - A command line utility to install, uninstall and check the status of the HW driver
- HwTest.exe - A program to test the HW driver and to read/write to I/O ports, memory and to display PCI resources
- HwPciExplorer.exe - HW PXI/PCI Explorer Applet, a PXI/PCI based VISA compatible resource manager control panel applet. Used to display the current PXI/PCI devices and to assign slot numbers to device resources. Slots numbers are required to identify a PCI/PXI board when using MTS board driver
- HwPciExplorer.cpl and HwPciExplorer64.cpl - 32 and 64 bit PXI/PCI Explorer - Windows Control Applet Panel support
- Hw.sys and Hw64.sys - Windows kernel mode device drivers, provides access to I/O ports, memory and PCI resources, installed to the Windows System Drivers directory.
- HwDevice.sys and HwDevice64.sys - 32 and 64 bit Windows kernel mode device driver for HW.INF boards, installed to the Windows System Drivers directory
- HwPxiExpress.dll and HwPxiExpress64.dll - 32 and 64 bit driver to provide information to MTS Chassis, Controller and Peripheral PXIe devices, installed to the Windows System directory
- HwCIns32.dll and HwClins64.dll - Windows Class Installer for HwDevice.sys and HwDevice64.sys
- Hw.dll and Hw64.dll - Library with API defined in hw.h, installed in Windows System folder
- Hw.h - Include file, to include in your C/C++ project provides functions prototypes to Hw.dll and Hw64.dll files
- Hw.lib and Hw64.lib - Import library for C/C++ applications
- HwCIns32.dll and HwCIns32.dll - 32 and 64 bit Windows Class Installer for HW
- Hw.inf - Driver information files for MTS's PXI/PCI boards. Installed to the Windows System INF directory
- Hw.cat - Windows digitally signed catalog file
- HW-NI-PAL-PCI.reg - HW-NI-PAL Registration entries file
- GX7XXXX.ini - Configuration files used to support Marvin Test Solutions chassis and controllers
- Hw.vxd - Windows 9x/Me virtual device driver provides access for memory and PCI resources, installed to the Windows System directory
- HwCIns16.dll - Windows 9x/Me Class Installer for HW
- HwVdd.dll - VDD for 16 bit application running on 2000-Vista, installed to the Windows System directory
- ReadMe.txt - Contains the latest release information about the HW package
HW Library FunctionsThere are many functions within the HW library that are useful for determining the system configuration. This article discusses the most important procedures, the structHWPCIDEVICE data structure, and provides an examples using the objects listed below for querying the PXI system resources:
HwOpen:
Initializes the HW library this must be called prior to any HW driver functions. This is automatically performed in the ATEasy HW driver (HW.drv), but needs to be explicitly called from other programming languages.
PciGetSlotNumbers([Val] Word wVendorId, [Val] Word wDeviceId, Var Short panSlotNumbers[], Var Word pwDevicesFound):
Returns an array of slot number(s) for the devices with the specified Vendor ID and specified Device ID.
PciGetSlotDevice(Val Long lSlot, Var structHWPCIDEVICE pstPciDev):
Returns the device information for the instrument in the specified slot.
Struct structHWPCIDEVICE:
A data type structure that contains information about devices (instruments) installed in a PXI system. While the procedures above are used to obtain information about a PXI device, it is the structHWPCIDEVICE data structure where that information is stored. Knowing the structure of the data type is key to fully utilizing the HW driver. The full structure provided in the HW driver is provided below for review:
structHWPCIDEVICE: Struct Public
{
dwVendorId: DWord
dwDeviceId: DWord
dwBus: DWord
stPciSn: structPciSlotNumber
stPciCfg: strictPciCommonConfig
aResDesc: structCmPartialResourceDescriptor[8]
aMemDesc: structHwMemoryDesc[8]
szId: Char[256]
}
! stPciSn - PCI/PXI slot number (5 low bit: device #, 3 bits: function #, 8 bits: Legacy slot, 16 chassis/slot : 0x203
structPciSlotNumber: Struct Public
{
dwAsUlong: DWord
}
strictPciCommonConfig: Struct Public
{
wVendorId: Word
wDeviceId: Word
wCommand: Word
wStatus: Word
ucRevisionId: Byte
ucProgIf: Byte
ucSubClass: Byte
ucBaseClass: Byte
ucCacheLineSize: Byte
ucLatencyTimer: Byte
ucHeaderType: Byte
ucBIST: Byte
stType0: structPciHeaderType0
dwDeviceSpecific: Byte[192]
}
structPciHeaderType0: Struct Public
{
adwBaseAddresses: DWord[6]
dwSubSystem: DWord
dwSubVendorID: DWord
dwROMBaseAddress: DWord
adwReserved2: DWord[2]
ucInterruptLine: Byte
ucInterruptPin: Byte
ucMinimumGrant: Byte
ucMaxinumLatency: Byte
}
structPxiChassisInfo: Struct Public
{
dwSize: Long ! Fill with sizeof (PXIChassisInfo)
apcidevBridges: structHWPCIDEVICE[4] ! Bridges in the chassis
wChassisModel: Word ! Chassis model # : i.e. 7010
wChassisRevision: Word
dwChassisSerial: DWord
acUserDefinedData: Char[64]
wNumberOfSlots: Word ! Total number of slots in the chassis
}
structCmPartialResourceDescriptor: Struct Public
{
ucType: Byte
ucShareDisposition: Byte
wFlags: Word
Address1: DWord
Address2: DWord
Address3: DWord
}
structHwMemoryDesc: Struct Public
{
dwPhAddrLow: DWord
lPhAddrHigh: Long
dwLength: DWord
pvVirtualAddress: DWord
}
structHwMemoryDma: Struct Public
{
ucSize: Byte ! Struct Size for Version
ucBus: Byte ! PCI Bus #
dwLength: DWord ! Allocation Size
memdesc: structHwMemoryDesc ! Returned by HW
dwDmaAdapter: DWord ! Returned by HW
}
Using a Device AliasTo demonstrate the utility of the HW driver, let's review a common task confronting anyone writing a program to control PXI test instruments. When writing a test program, the programmer is always faced with having to identify what instruments are installed in the PXI chassis. This information is essential to the test program so it knows how to establish a communication link between the host computer (i.e., the test program) and the instruments. Instrument identification can take one of several forms. PXI slot numbers can identify instruments. Instruments could also be identified by a resource descriptor (VISA) or a board index number.
One traditional method to initialize an instrument would be to use a VISA Resource Descriptor string, for example "PCI4::13::INSTR". ATEasy achieves similar functionality using the nSlot value. This parameter contains both the Chassis number and the Slot number. For example, for the nSlot value of 0x108, the hex 0x100 identifies the instrument Chassis as 1 and hex 0x8 identifies the Slot number as 8.
The HW driver also provides a method to create an Alias to an instrument. An alias is a text name that can be assigned to any instrument in a PXI chassis using PXI/PCI Explorer, a PXI resource utility that is installed with the HW package. Using an Alias name for an instrument allows using the instrument without having to identify its specific location in the system. This is useful if an instrument is moved or the system configuration is changed. Since the Alias name identifies the instrument it is no longer location dependent and can simply be remapped using PCI/PXI Explorer to match the existing test programs, and thus avoiding coding changes that might force recertification of a test program. For example to use Alias names to initialize two GX5295s in an ATEasy program the user would simply define the alias using PXI/PCI Explorer (below), and then use initialization code similar to the example that follows:
 Figure 1: Using PXI/PCI Explorer to assign an instrument Alias
lSlot: Long
nStimulusHandle: Short
nResponseHandle: Short
!Using PXI-PCI Explorer Alias to Initalize two GX5295 masters
!Use "Skip On Init" to disable automatic initialization of the GX5295 instruments
!The following procedure uses the HW and GX5295 driver functions,
!Void HwOpen() Automatically called by ATEasy
!Long HwPciGetAliasChassisSlot(sAlias) Returns nSlot used by GXXXInitialize
!Void InitializeMaster(nMasterNumber,nSlot,sVisaResource) Master board Init
!Void GetMasterHandle(pnHandle) Returns the current master handle
!Open the HW driver automatically called by ATEasy
!Hw Initialize()
!Initialization for GX5295 Master 1
lSlot = HW Pci Get AliasChassisSlot("Stimulus") !Gets nSlot value
Dio Initialize Master(1,lSlot,"")
Dio Get MasterHandle(nStimulusHandle)
!Initialization for GX5295 Master 2
lSlot = HW Pci Get AliasChassisSlot("Response") !Gets nSlot value
Dio Initialize Master(2,lSlot,"")
Dio Get MasterHandle(nResponseHandle)
For additional information about using PXI/PCI Explorer, refer to Knowledge Base article Using HW PXI/PCI Explorer Applet. Further details of how to create and use an Alias name is discussed in Knowledge Base article Using an Alias to address PXI instruments.
Instrument Initialization The process for establishing communication with an instrument is to “Initialize” the instrument. This is done by passing the appropriate identification parameter into an initialization procedure, typically contained in the instrument drivers, and having the procedure return a “handle” that is used as a reference for future communication with that instrument. MTS initialization is performed using the GxXXXInitialize function, where XXX is the mnemonic of the instrument, such as DIO, CNT, DMM, etc. This function can use the device's nSlot parameter, Legacy Slot, VISA Resource Descriptor string or an Alias to Initialize an instrument. This information can be obtained in the PCI/PXI Explorer, or can be obtained programmatically from the structHWPCIDEVICE listed above.
For example, to initialize the GX5295 located in nSlot 0x108 as referenced above, the user can initialize the instrument using Dio Initialize Master(1, 0x108). The device handle can be queried using the ATEasy command Dio Get Master Handle(pnHandle).
The instrument initialization process is very similar to that of opening a file, and using the returned “file handle” for subsequent reading or writing to a file. | |
Identification of instruments can be done at program design time by hard-coding the instrument identification into the test program, or at run time by querying the system resources and dynamically initializing instruments using the information returned by the system query. To use procedures contained in HW.DLL to query the system resources and identify installed instruments at run time, the HW HwOpen() procedure must be called prior to calling any of the other procedures in the HW driver. In the ATEasy HW driver, this initialization is automatically performed when the ATEasy application runs.
Once the HW driver has been initialized, the PciGetSlotNumbers() procedure returns an array of PXI slot numbers that contain instruments matching the search criteria – often the Vendor ID and/or the Device ID. The device information is contained in the structure structHWPCIDEVICE (listed above). If, for example, you wanted to know how many GX5295 dynamic digital instruments were installed in a PXI chassis, what are their slot numbers, and the firmware revision of each of those instruments, you could use the following code:
Word wVendorId : Word =0x16E2 ! Marvin Tests Solutions Vendor ID
wDeviceId=0x5295 : Word ! GX5295 Device ID
panSlotNumbers : Short[32] ! Array of slot numbers found
Word pwDevicesFound: Word ! Number of slots matching the Vendor and Device ID’s
pstPciDev: structHWPCIDEVICE
sDeviceInfo : String
i : Long
!HwOpen() Is performed automatically using ATEasy
!Open the HW driver automatically called by ATEasy
!Hw Initialize()
PciGetSlotNumbers(wVendorId, wDeviceId, panSlotNumbers, pwDevicesFound)
If pwDevicesFound<>0
For i=0 to pwDevicesFound-1
PciGetSlotDevice(panSlotNumbers[i], pstPciDev)
sDeviceInfo= pstPciDev.szId
Print "Slot "+Format(panSlotNumbers[i],"00")+" Firmware: "+Mid(sDeviceInfo,Pos("SUBSYS_",sDeviceInfo)+7,4)
Next
EndIf
After the slot number for an instrument is obtained, it would be a simple matter to initialize the instrument by calling the instrument's Initialize() procedures and passing the slot number obtained by scanning the PXI system using the example above. Another method of identifying a PXI system's configuration is using the PciGetSlotDevice(). This procedure returns the device information for the instrument in the specified slot. PciGetSlotDevice() can be used in a polling scheme to identify what, if any, instruments are installed in each slot of a PXI chassis, or in all slots in a multi-chassis configuration.
Device SettingsThe Device Settings are as shown in PCI/PXI Explorer,
 Figure 2: Device Settings
To view the Device Settings, expand the folder under the desired instrument. This folder displays the Bus, Device, Function, Device ID, Vendor ID and the memory allocated for the module. These parameters can help determine if the module has had the correct resources allocated during the boot process. For example, if neither of the Memory parameters is showing that memory has been allocated for the instrument, then the module was not allocated memory resources on system boot-up, which could indicate that the instrument drivers need to be installed. Typically, this is done prior to installing the hardware and allows these resources to be allocated when the computer/Windows boots. The Device Settings are informational only and are not editable by the user.
The Device Settings information can be obtained programmatically using HW driver functions such as PciGetSlotDevice. The PciGetSlotDevice function can be used to obtain information on all devices in a system and allow the user to write driver functions using the information contained in the HWPCIDEVICE structure. The following is an ATEasy procedure that displays the Device Settings of all devices found in the chassis.
Slot: Long
nCntr: Short
stPciDevice: structHWPCIDEVICE
!DisplayDeviceInfo
!This example demonstrates using the HW driver library function HwPciGetSlotDevice
!to obtain PCI/PXI device configuration of each slot of a system. The variable
!stPciDevice is defined as a HWPCIDEVICE structure. The for-next loop prints
!the information found in each populated slot
Log.PlainText=True
ClearLog()
HW Initialize() ! Must be called before any HW call
HW Pci AssignDeviceSlot() ! Assign slots to all devices
for lSlot=0 to HW_MAX_SLOTS-1
HW Pci Get SlotDevice(lSlot, stPciDevice) ! Get the device in the specified slot
if stPciDevice.dwVendorId<>0 ! if populated slot, print the device info
append " Slot ";lSlot;" - Bus ";stPciDevice.dwBus;", Device ";\
stPciDevice.stPciSn.dwAsUlong and 0x1F;\
", Function ";(stPciDevice.stPciSn.dwAsUlong shr 5) and 0x7
append " - VendorID 0x";ucase(str(stPciDevice.stPciCfg.wVendorId, 16));\
", SubVendorID 0x";ucase(Str(stPciDevice.stPciCfg.stType0.dwSubVendorID, 16))
append " - DeviceID 0x";ucase(str(stPciDevice.stPciCfg.wDeviceId, 16));\
", SubSystem 0x";ucase(Str(stPciDevice.stPciCfg.stType0.dwSubSystem, 16))
for nCntr=0 to 7
select stPciDevice.aResDesc[nCntr].ucType
case 1
append " - Port: 0x";\
ucase(Str(stPciDevice.aResDesc[nCntr].Address1, 16));\
" Length 0x";ucase(str(stPciDevice.aResDesc[nCntr].Address3, 16))
case 2
append " - Interrupt: 0x";\
ucase(Str(stPciDevice.aResDesc[nCntr].Address1, 16))
case 3
append " - Memory: 0x";\
ucase(Str(stPciDevice.aResDesc[nCntr].Address1, 16));\
" Length 0x";ucase(str(stPciDevice.aResDesc[nCntr].Address3, 16))
endselect
next
endif
next
ConclusionThe HW driver, coupled with the PCI/PXI Explorer Applet, provides the user a powerful toolset to not only obtain system information, but can be used to automate identification and initialization of the instrumentation contained in the test system. For additional information about how to use the HW driver and the PCI/PXI Explorer Applet, review the HW programming example installed with ATEasy (Hw.prj) located in the ATEasy driver directory and the files installed the Program Files\Marvin Test Solutions\HW. In addition refer to the following knowledge base articles: Using HW PXI/PCI Explorer Applet, Scanning a PXI system to learn about system resources and Using an Alias to address PXI instruments.
|