An Introduction to Instrument Design Libraries for NI Software-Designed Instruments

Instrument Design Libraries

    National Instruments provides a multitude of Instrument Design Libraries for NI software-designed instruments. These Instrument Design Libraries exist at the interface between user and vendor code on both the host and FPGA, and implement functionality commonly found in instruments. Table 2 presents a list of top-level Instrument Design Libraries and their functionality.

DSP–Onboard signal processing
RF In–RF input hardware configuration and calibration
RF Out–RF output hardware configuration and calibration
Basecard–ADC and DAC configuration
Multirecord Acquisition–Multiple waveform acquisition DRAM abstraction
Waveform Sequencer–Multiple waveform DRAM abstraction for waveform sequencing
Trigger Synchronization–Multimodule sample clock synchronization, “T-Clk-like”
Embedded Configuration–FPGA dynamic reconfiguration through register sequences, LabVIEW FPGA “list mode”

Table 1. Top-level Instrument Design Libraries for NI VSTs.

These Instrument Design Libraries are installed with the software listed at, and subsequently exist on disk in c:\Program Files\National Instruments\LabVIEW [version]\\. Visually, they can be distinguished from other VIs in that they have a thicker, color-matched border.

Figure 1. Instrument Design Libraries feature unique iconography to distinguish them from other VIs, with thicker, color-matched borders.

Furthermore, by default they are locked, presenting a dialog box to unlock the VI before users may modify the contents. Provided below are details on taking ownership of these Instrument Design Libraries, which should happen before any modifications occur.

     To exchange data between the host and FPGA of a given Instrument Design Library, there are numerous possible mechanisms. The NI-RIO driver, used by all National Instruments products that use the LabVIEW RIO architecture and LabVIEW FPGA, provides both single-point, memory-mapped, register-based host to FPGA and FPGA to host communication, as well as multipoint, continuous DMA FIFOs from host to FPGA, and FPGA to host. These are both powerful mechanisms for data exchange, requiring little-to-no knowledge of the underlying bus architecture to effectively communicate between host and FPGA.

     A common requirement for Instrument Design Libraries is that the host code may need to download a large number of settings to the device, for instance to program the registers of chips connected to the FPGA, or to update groups of settings such as filter taps on the FPGA. Because several Instrument Design Libraries require this policy, and there are a limited number of DMA channels on the device, it may be necessary for these libraries share a common FIFO, with additional logic for arbitration on both the host and FPGA side of the FIFO. Additionally, this type of communication is typically unidirectional for the large data set, but it may also require some kind of single-point confirmation from the FPGA to the host, for instance confirming that all of the settings were successfully applied. All of these concepts are grouped into a distinct concept called the register bus, which is employed by several of the Instrument Design Libraries.

     The register bus uses a single Host-to-FPGA DMA FIFO for downloading settings, as well as a few registers/NI-RIO controls and indicators for handshaking, returning single-point data to the host, and optionally signaling confirmation that the instructions in the downloaded settings have been carried out.

Figure 2. The register bus is a lightweight protocol built on top of NI-RIO DMA, controls, and indicators, which implements the ability to efficiently download large groups of settings to the FPGA, a common requirement between the host and FPGA side of a given Instrument Design Library.

To manage arbitration, each Instrument Design Library has a unique subsystem ID that allows multiple libraries to share a single register bus. To better summarize the communication policies of the VST Instrument Design Libraries, table 2 shows which policy is used by each library.

  Controls and Indicators DMA FIFOs Register Bus
RF Out X
Basecard X
Multirecord Acquisition X X
Waveform Sequencer X X
Trigger Synchronization X
Embedded Configuration X

Table 2.  Host and FPGA Data Exchange Mechanisms of the NI PXIe-5644R Instrument Design Libraries.

Furthermore, when combined with the embedded configuration Instrument Design Library, the register bus can be used for FPGA-initiated reconfiguration with no host involvement.

     Because the Instrument Design Libraries represent a defined interface between vendor and user code, they are presented in palettes on both the host and FPGA. Under the host context on a LabVIEW VI block diagram, the host-side interface of the Instrument Design Libraries can be found under Functions>>FPGA Interface>>NI PXIe-5644R or Functions>>FPGA Interface>>NI PXIe-5645R. On the FPGA side, they are located under Functions>>NI PXIe-5644R or Functions>>NI PXIe-5645R.

Host Palette for the VST Instrument Design Libraries

FPGA Palette for the VST Instrument Design Libraries

Figure 3. Host and FPGA palettes for the Instrument Design Libraries of the NI VSTs. The FPGA palette includes additional Instrument Design Libraries for common, lower-level functionality.


LabVIEW Sample Projects

     The NI VST Instrument Design Libraries provide significant capabilities, but alone they do not completely address the requirement of a software-designed instrument to deliver default functionality, nor do they provide a simple host interface that is familiar to the majority of VSA and VSG instrument programmers.

     LabVIEW 2012 provides a new feature that serves as a convenient mechanism to not only distribute additional code that provides default, precompiled functionality and a convenient host interface, but also allow users to easily take ownership of that code. This mechanism is the LabVIEW sample project, which copies a LabVIEW project, specific VIs, and associated files to a user-specified location on disk. It also offers the ability to rename files and update VI banners.

Figure 4. With LabVIEW 2012 sample projects, users of software-designed instruments can take ownership of the appropriate portions of code.

More details on creating sample projects for NI VSTs can be found at

      The software installer for the NI PXIe-5644R adds the capability to create multiple sample projects, each with different features. The project that is most similar to the default functionality of a VSA and VSG is the Simple VSA/VSG sample project. This sample project provides a host interface that is similar to other VSA and VSG APIs. The high level architecture and data flow of the Simple VSA/VSG sample project is shown in Figure 5.

Figure 5. The Simple VSA/VSG sample project aggregates Instrument Design Libraries on the host and the FPGA to present a starting point familiar to users of VSAs and VSGs.

     Starting with the FPGA VI of the Simple VSA/VSG sample project, there are four main loops, and some additional functionality located in the process subVIs. For configuring all of the programmable components of NI VSTs, as well as some of the Instrument Design Libraries on the FPGA, the configuration loop receives registers and settings from the host, and then distributes them to various FPGA subsystems and external circuitry. To increase performance as well as provide independent access from multiple processes on the host, there are two register buses. One is designated for acquisition, one for generation, and each must be able to configure shared resources such as clocking.

Figure 6.  The configuration loop is responsible for receiving data from the host and programming the instrument.

     The RF input loop takes data from the analog-to-digital converters (ADCs); applies a complex vector calibration; and provides for frequency shifts, phase alignment, impairments, and variable, factional, alias-protected decimation. It also implements synchronization as well as digital and power-level triggering before writing data to a FIFO and eventually DRAM.

Figure 7. The RF input loop produces calibrated data at a configurable I/Q rate and writes it to DRAM.

     The RF output loop is similar to the RF input loop, though the order of operations is reversed. Data from DRAM is interpolated, scaled, frequency-shifted, phase-aligned, interpolated, calibrated, and then generated out of the digital-to-analog converters (DACs). There are also signals for triggering and synchronization.

Figure 8.  The RF output loop retrieves data from DRAM then generates it.

     The process subVIs contain loops and state machines that implement multirecord acquisition and waveform sequencing DRAM controllers. They contain a considerable amount of code, which is necessary to meet the high-bandwidth and low-latency performance necessary to guarantee that they can consume full rate ADC data without overflowing, and produce full-rate DAC data without underflowing, while still transferring waveform data to and from the host.

     The fetch loop implements functionality that could exist in the mutirecord acquisition process, but is exposed for convenience. It provides one final opportunity to process acquired data as it leaves DRAM and before it is sent to the host. This path is in its own loop so that IP, which may not meet the timing requirements of the 120 MHz RF input and output loops, may still be employed. To accommodate such IP, reducing this loop rate by a small amount does not adversely affect fetch performance, and though reducing it by a considerable amount may, this will only increase the time it takes for the data to reach the host. It will not drop samples or otherwise corrupt data, though acquisition memory may completely fill.

Figure 9. The fetch loop provides an opportunity to process acquired data before it is returned to the host. By default, it returns the data unaltered.

     Although the top-level FPGA VI aggregates the functionality of 13 Instrument Design Libraries, it would be inconvenient to program each of these libraries independently on the host, and this application-level host code would look nothing like that of a traditional VSA or VSG API. To address this, the Simple VSA/VSG sample project includes an additional host layer that aggregates these Instrument Design Libraries into an interface that presents functions more similar to those of a vendor-defined VSA/VSG API. LabVIEW classes provide a convenient mechanism to do this, offering a strictly typed session wire, public and private methods, and a convenient mechanism for maintaining subVI icon headers. Note that the object-oriented concept of inheritance, while available in LabVIEW classes, is not used for this host interface.

Figure 10. LabVIEW classes provide a convenient mechanism for aggregating functionality and maintaining host interfaces.

The Simple VSA/VSG sample project additionally provides several host examples for common RF VSA and VSG operations, which demonstrate how to properly use the host interface. These cover frequency domain and I/Q acquisition; CW and sequence-based waveform generation; and multiple input, multiple output (MIMO) synchronization.

Figure 11. Several host examples demonstrate use of the class-based host interface for the Simple VSA/VSG sample project.

     The Simple VSA/VSG sample project incorporates a significant amount of functionality and presents a familiar host interface. This utility comes at a cost, however, and that cost is code complexity. Specifically, the waveform-based abstractions of the DRAM attached to the FPGA add a considerable amount of code, complexity, and resource utilization of the VST FPGA. Yet not all applications require a waveform-based or instrumentation data movement paradigm. Some applications are better suited with a real-time streaming data movement architecture. For these, the VST Streaming sample project offers a better starting point, with greater opportunity for customization.

Figure 12. The VST Streaming sample project aggregates Instrument Design Libraries on the host and the FPGA to present a starting point which is flexible for real-time, low-latency signal processing and embedded applications.

     The top-level FPGA VI of the VST Streaming sample project has a similar architecture to that of the Simple VSA/VSG sample project. Though, on closer inspection it is considerably simpler. Noticeably absent are the configuration processes, which represent a significant amount of code. The configuration loop is much simpler, with only a single register bus instead of two, and all subsystems are wrapped into a single subVI.

Figure 13. The configuration loop of the FPGA VI found in the VST Streaming sample project, with only a single register bus interface, is considerably simpler than that of the Simple VSA / VSG.

Rather than having separate acquisition and generation loops, the VST Streaming sample project uses a single loop for all analog I/O. This architecture provides deterministic synchronization of RF input and output for applications that require a known phase relationship between the two, and is only possible because both the ADCs and DACs use the same sample clock. The DSP and calibration of the VST Streaming sample project is similar to that of the Simple VSA / VSG.

     The main difference between the two sample project FPGA VIs is that the VST Streaming sample project uses a lightweight mechanism to send and receive data to and from the host. It features simple stream controllers that support basic triggering, continuous and intermittent streams, and overflow and underflow detection. These controllers operate by interrupting the 2-wire handshaking signals between their sources and destinations, effectively gating the data flow. They do not support the full 4-wire handshaking scheme, which has the capability to throttle upstream nodes or be throttled by downstream nodes, so the burden is on the programmer to characterize the system and ensure that all FIFOs controlled by these stream controllers can produce or consume data at the requisite rates. A key concept in the VST Streaming sample project is that the FIFOs, which by default send data to and from the host, may be easily changed to support streaming to other locations on the VST FPGA for additional processing, or over the PXI Express backplane to other modules through peer-to-peer data streaming.

Figure 14. FPGA stream controllers and FIFO encapsulations provide for basic flow control and the ability to easily reroute stream sources and destinations.

     Moving to the host side of the VST Streaming sample project, there is a similar aggregation of the host components of the Instrument Design Libraries, though the mechanism differs from the Simple VSA/VSG. The VST Streaming sample project does not use LabVIEW classes, instead it simply aggregates functionality in subVIs and passes a session to the register bus between them. This register bus session also contains a reference to the FPGA VI Reference, so each of these subVIs has access to not only the register bus communication policy, but also NI-RIO FIFOs and controls. Furthermore, there are no independent sessions for acquisition and generation; all VIs use the same session.

Figure 15. The VST Streaming sample project host interface features a register bus-based session wire for both acquisition and generation subVIs. This example logically groups acquisition and generation into separate rows for readability.

The VST Streaming sample project provides two host examples. The simpler one demonstrates continuous streaming of a waveform to the VST for generation, with either bursted or continuous streaming of acquired data from the VST. The more advanced example demonstrates MIMO synchronization of multiple VSTs.

Figure 16. Examples demonstrate use of the host interface for the VST Streaming sample project.