Getting Started with NI-HSDIO

This document intends to give the beginner a general idea of how to get started with NI-HSDIO. It begins with a brief introduction to the structure of instrument drivers generally, and continues into more detail on the National Instruments NI-HSDIO instrument driver for NI digital instruments. The Instrument Driver Programming Basics section covers basic waveform acquisition and some basic measurement options. For a more thorough explanation of the NI-HSDIO instrument driver and more information on programming with NI-HSDIO, refer to the NI Digital Waveform Generator/Analyzer Help.

Instrument Driver Programming Basics

What is an instrument driver?

An instrument driver is a set of software routines that control a programmable instrument. Each routine corresponds to a programmatic operation such as configuring, reading from, writing to, and triggering the instrument. Instrument drivers simplify instrument control and reduce test program development time by eliminating the need to learn the programming protocol for each instrument.

The Structure of an Instrument Driver

All instrument drivers have the same basic hierarchy. Instrument drivers are written from low-level components that are used to program the instrument. These low-level calls are combined to form application functions that simplify programming the instrument. These application functions present only the common instrument features and capabilities, whereas low-level functions are organized into a modular assortment containing all the instrument configuration and measurement capabilities. The component functions fit into six categories – Initialize, Configuration, Action/Status, Data, Utility, and Close. Below is a model structure of a program written with an instrument driver.

This model represents the basic programming structure of a program written with an instrument driver.

Initialize
All instrument drivers have an Initialize function. It is the first instrument driver function called and establishes communication with the instrument. Optionally, it can also perform instrument identification query and reset operations. Initialization also places the instrument in a specific state, usually its default power on state.

Configuration
Configuration functions are collections of software routines that configure the instrument to perform a desired operation. The number of Configuration functions depends on the complexity of the instrument. After the Configuration functions are called, the instrument is ready to take measurements.

Action/Status
The Action/Status category contains two types of functions. Action functions cause the instrument to initiate or terminate test and measurement operations such as arming the triggering system or generating a stimulus. Action functions differ from Configuration functions in that they do not change instrument settings; instead, they order the instrument to carry out an action based on its current configuration settings.

Status functions return the current status of the instrument or of pending operations. Specific routines in this category and the actual operations they perform are at the discretion of the instrument driver developer, and are usually created as required by other functions.

Data
Data functions include calls to transfer data to or from the instrument. Examples of Data function operations include reading a measured value or waveform from a measurement instrument, and downloading waveforms or digital patterns to a source instrument. Specific routines in this category depend on the instrument.

Utility
Utility functions perform a variety of operations auxiliary to the most-used instrument driver calls. These functions include the majority of the template instrument driver calls (described below) such as reset, self-test, revision, and error query, and may include other custom routines such as calibration or storing/recalling instrument configurations.

Close
All instrument drivers include a Close function. The Close function terminates the software connection to the instrument and deallocates system resources used during that instrument session.

Getting Started with NI-HSDIO

The NI-HSDIO instrument driver is the application programming interface (API) that allows programming of your National Instruments high-speed digital I/O board in LabVIEW, LabWindows/CVI, ANSI C or Microsoft Visual C++.  NI-HSDIO provides the same functionality and example programs in all supported programming environments.  For simplicity, LabVIEW examples are referred to in this document, but similar examples using other programming environments also ship with the NI-HSDIO driver.

Step 1:  Initialize (for Acquisition, Generation or Calibration)

The initialize function can be used for acquisition or generation.  This function establishes communication with the instrument by using one of the following VIs or functions.

Acquisition
The Initiate Acquisition Session function creates a new acquisition session. You can perform static and dynamic acquisition operations with this session.

Figure 1 niHSDIO Init Acquisition Session VI

C Function: niHSDIO_InitAcquisitionSession

Creating a new session does not automatically tristate your front panel terminals, or channels, possibly driving voltages from previous sessions. Refer to the niHSDIO Close VI for more information about leaving lines driving after closing a session.

Set reset instrument to TRUE to place your device in a known start-up state when creating a new session. This action is equivalent to using the niHSDIO Reset VI, and it tristates the front panel terminals and channels.

Generation
The Initiate Generation Session function creates a new generation session. You can perform static and dynamic generation operations with this session.

Figure 2 niHSDIO Init Generation Session VI

C Function: niHSDIO_InitGenerationSession

 

Calibration
The Initiate External Calibration function creates and initializes a special NI-HSDIO external calibration session. instrument handle out is an NI-HSDIO session that can be used during the calibration session.

Figure 3 niHSDIO Init Ext Cal VI

C Function: niHSDIO_InitExtCal

Multiple calls to this function return the same session ID. Calibration sessions are mutually exclusive with acquisition and generation sessions.

Step 2:  Select Channels

Your digital device contains multiple channels.  You can use the following VIs and functions to specify which channels you want to use in your data operations. You can configure a channel for more than one simultaneous data operation. A channel can be simultaneously configured for the following operations:

• Dynamic generation and any (static and/or dynamic) acquisition
• Static generation and any (static and/or dynamic) acquisition
• Both static and dynamic acquisition

Dynamic
The Assign Dynamic Channels function configures channels for dynamic acquisition (if instrument handle is an acquisition session) or dynamic generation (if instrument handle is a generation session).

 

Figure 4 niHSDIO Assign Dynamic Channels VI

C Function: niHSDIO_AssignDynamicChannels

Static

The Assign Static Channels function configures channels for static acquisition (if instrument handle is an acquisition session) or for static generation (if instrument handle is a generation session).  A channel cannot be simultaneously assigned to a static generation and dynamic generation.

Figure 5 niHSDIO Assign Static Channels VI

C Function: niHSDIO_AssignStaticChannels

Step 3:  Configure the Hardware

After you have opened a session to the digital instrument, you need to configure the hardware settings for channels, clocking, triggering, voltage levels etc.  This section discusses some of the main VIs for configuring your instrument.  For a complete list of functions please see the NI Digital Waveform Generator/Analyzer Help.

Sample Clock
The Configure Sample Clock function allows you to specify the sample clock source and rate for your session. 

Figure 6 niHSDIO Configure Sample Clock VI

If clock source is set to On Board Clock, NI-HSDIO coerces the rate to a value that is supported by the hardware.  Refer to the specifications page of your device for the onboard clock rates available.  Select Timing»Sample Clock»Rate from the niHSDIO Property Node to get the coerced value of the Sample clock rate.  The clock source can be set to Strobe only for acquisition sessions, or NI-HSDIO returns an error.

Voltage
The Configure Voltage function specifies the voltage levels for the data, trigger, and event channels. You can use either predefined logic families or custom voltage levels.

Figure 7 niHSDIO Configure Voltage VI

C Function: niHSDIO_ConfigureDataVoltageLogicFamily
                 niHSDIO_ConfigureDataVoltageCustomLevels
                 niHSDIO_ConfigureTriggerVoltageLogicFamily
                 niHSDIO_ConfigureTriggerVoltageCustomLevels
                 niHSDIO_ConfigureEventVoltageLogicFamily
                 niHSDIO_ConfigureEventVoltageCustomLevels

The niHSDIO Configure Voltage VI is a polymorphic VI, so refer to the NI Digital Waveform Generator/Analyzer Help for a complete description of the different options for voltages.  Also, refer to your specific device specifications for available logic families and custom voltage levels.

Triggers
There are several kinds of triggering available for use with NI-HSDIO and NI digital waveform generators/analyzers.  The niHSDIO Configure Trigger VI is a polymorphic VI with different options for triggering.

Figure 8 niHSDIO Configure Trigger VI

C Function: niHSDIO_ConfigureDigitalEdgeStartTrigger

For complete descriptions of the different triggering options, refer to the Triggering section of the NI Digital Waveform Generator/Analyzer Help.

Step 4:  Acquire

After the HSDIO device is configured for your application, you may start the acquisition, or generation.  Acquiring/generating data can be separated into two parts, initiating the acquisition, or generation, and retrieving/generating the data from/to the HSDIO’s onboard memory.

Initiate
The Initiate function arms the board to begin the task after the trigger has occurred. If immediate triggering has been configured, then the board starts acquiring/generating data immediately.

Figure 9 niHSDIO Initiate VI

C Function: niHSDIO_Initiate

Dynamic Read
The Read Waveform function initiates a waveform acquisition on channels enabled for dynamic acquisition, waits to acquire the number of samples specified in samples to read, and returns the acquired data.

Figure 10 niHSDIO Read Waveform VI

C Function: niHSDIO_ReadWaveformU8(16/32)

The niHSDIO Read Waveform VI is a polymorphic VI, and can be configured for different data sizes.  Refer to the NI Digital Waveform Generator/Analyzer Help for the various options associated with this VI.

Initiate and Fetch

The fetch VI is mainly used to perform other functions while the device is acquiring data.  This VI has to be used for functions such as streaming that require other activities to take place while the HSDIO device is acquiring data.  Initiate begins the acquisition operation and returns control to your program.  Fetch transfers the acquired data from acquisition onboard memory to the application.

Figure 11 niHSDIO Fetch Waveform U32

C Function: niHSDIO_FetchWaveformU8(16/32)

niHSDIO_FetchWaveformU32 ( ViSession vi, ViInt32 samplesToRead, ViInt32 maxTimeMilliseconds, ViInt32* numberOfSamplesRead, ViUInt32 data[]);

[+] Enlarge Image

Figure 12 LabVIEW Example showing dynamic acquisition w/ hardware start trigger VI

Step 5:  Generate

Generating Waveforms

You can use the HSDIO device to generate one waveform at a time or you can use scripts to generate complex sequences of waveforms.

The Write Named Waveform function Transfers waveform data from PC memory to onboard memory.

Figure 13 niHSDIO Write Named Waveform VI

C Function: niHSDIO_WriteNamedWaveformU8(16/32)

The niHSDIO Write Named Waveform VI is a polymorphic VI, and can be configured for different data sizes.  Refer to the NI Digital Waveform Generator/Analyzer Help for the various options associated with this VI.

The example below shows a code snippet for an example of writing a 1 MS waveform to onboard memory.

[+] Enlarge Image

Figure 14 – LabVIEW code showing how to read data from a file and write it to the onboard memory of an HSDIO device.

#define BLOCK_SIZE         8192

ViUInt32 data[BLOCK_SIZE];
.
.
.
niHWS_OpenFile("mydata.hws", niHWS_Val_ReadOnly, &fileHandle);
niHWS_GetWfmReference (fileHandle, VI_NULL, VI_NULL, &wfmRef);

/* reserve onboard memory, name the waveform "myWfm" */
niHWS_GetWfmI32Attribute (wfmRef, niHWS_Attr_WaveformSize, &wfmSize);
niHSDIO_AllocateNamedWaveform (instrHdl, "myWfm", wfmSize);

/* write waveform 1 block at a time */
numSamplesWritten = 0;
while (numSamplesWritten <= wfmSize)
{
/* Read BLOCK_SIZE samples from .hws file, put in data */
niHWS_ReadDigitalU32(wfmRef, BLOCK_SIZE, data, &actualSamplesRead);
niHSDIO_WriteNamedWaveformU32 (instrHdl, "myWfm", actualSamplesRead, data);
numSamplesRead = numSamplesRead + actualSamplesRead;
}


[+] Enlarge Image

Figure 15 Example showing dynamic generation of data using an onboard clock

 

Generating Multiple Waveforms / Linking and Looping

Scripting allows you to link and loop multiple waveforms in complex combinations.  Use the niHSDIO Configure Generation Mode VI to switch to scripted mode.

Figure 16 niHSDIO Configure Generation Mode VI

C Function: niHSDIO_ConfigureGenerationMode

The script contains the general instructions to be executed.  Multiple scripts can exist on your device simultaneously. Internally, the script stores physical device memory locations to refer to named waveforms. Thus, write all waveforms to the device before writing the script, or the device will be unable to locate the waveform. The initiate function produces an error if this rule is violated. If you delete waveforms and rewrite them, rewrite the script to update it with the new locations, even if the script text has not changed.

A simple script example is shown below

script myFirstScript
  wait until scriptTrigger0
  repeat 3
   generate waveform A marker0 (16)
  end repeat
  repeat 2
   generate waveform B
   generate waveform C
   generate waveform D
  end repeat
end script

Generate Waveforms using Streaming

Streaming is a method of generating waveforms that are too large to fit in the onboard memory of the device. Streaming can be used in dynamic generation sessions.

To stream waveform data, you allocate and identify all or a portion of the device onboard memory to act as an onboard waveform for streaming. Before initiating generation, you fill that onboard memory with the first part of your waveform. As the waveform is generated, space in the onboard memory becomes free and you fill that space with new waveform data. You repeat the process of filling the freed onboard memory in blocks of new waveform data until the waveform is complete.

Step 6:  Stimulus and Response or Hardware Compare Functionality

Hardware comparison allows a device to verify in real-time at the full data rate of the device that a DUT generates the correct response data under different use cases and stimulus data. Traditionally, the comparison was done by acquiring data into the PC memory and then performing software analysis.

Figure 17 niHSDIO Hardware Comparison Flowchart

There are two primary methods for comparing acquired response data with expected data. With the first method, the device captures the actual response data into PC memory and uses software to post-process the results. The software uses only the two basic logic states, 0 and 1, to configure the tester’s stimulus data. With the second method, you can preload the device with both stimulus and expected response data and make real-time comparisons as data is acquired. Whenever a waveform contains a comparison logic state (H or L), then the acquired response data is compared to the expected response. You can choose whether this real-time hardware comparison operation drives and compares data (0, 1, Z, H, L, and X) or whether it only acquires and compares (H, L, and X).

Digital Logic States

Test engineers can choose from a number of different digital I/O instruments with a range of features for communication and test applications. Beyond the basic capabilities of driving a digital pattern of 1's and 0's, digital instruments often support waveforms that can include some or all of the logic states shown in the following table.

Table 1 – Logic States Supported by NI-HSDIO

 

NOTE: Only the NI 655x/6547/48 devices support hardware compare and the extended logic states shown in the table above.

Errors that occur using the above hardware compare feature can be returned using the following function.

Figure 18 niHSDIO HWC Fetch Sample Errors (U32)

 

Step 7:  Using Attributes with NI-HSDIO

The Error Handler function translates error codes into explanations to help you debug your application.

Figure 19 niHSDIO Error Message VI

C Function: niHSDIO_error_message

Step 8:  Close

The last step is to call the Close function, which closes the session and de allocates any resources the session used.

Figure 20 niHSDIO Close VI

C Function: niHSDIO_Close

It is important to close the session because it releases any temporary buffers created to transfer data between the HSDIO and the host computer memory.

Summary

Once you understand all the VI’s necessary to perform an acquisition or generation, it’s time to bring them together to make a complete application.  The following diagram depicts the typical programming flow for a generation or acquisition session.  For more detailed information about all of the functions and available features please refer to the NI Digital Waveform Generator-Analyzer Help and your HSDIO user manual.

Figure 21 NI-HSDIO Basic Acquisition/Generation Flowchart

Reader Comments | Submit a comment »