XML Generation Reference Utility for LabVIEW FPGA CLIP Nodes

To import Component-Level IP (CLIP) into a LabVIEW FPGA project, an XML file must be created to describe the CLIP's I/O signals and file hierarchy. A free utility is provided here that generates this XML file automatically, given a top-level VHDL file and signal information from its user interface. The source code for this utility is also provided. The utility can thus be modified to meet the needs of any LabVIEW FPGA developer. Modular portions of the code, such as the VHDL Parsing module and the XML Generation module, may also be useful to developers in other projects.

Purpose

Component-level IP is the preferred method of integrating HDL code into a LabVIEW FPGA design, but it requires a few more steps than simply dropping an HDL node onto the block diagram. One step in adding CLIP to a LabVIEW project is to create an XML file that both defines the interface between LabVIEW VIs and the CLIP and provides a listing of the files needed to compile the CLIP onto the target. Creating and editing this XML by hand can be cumbersome. The CLIP XML Generator (CXG) is a free utility that automates most of this process by scanning a VHDL file to find a signal interface, then gathering data about those signals and generating an XML file for the user.

In addition to the CXG application, its source code is provided for download. This allows any developer or development team to customize the CXG's functionality to suit their needs. There are also portions of the code that were designed for reference and reuse in other projects. This document provides both a user manual for the CXG as-is and a code reference for those seeking to customize it or make use of its functional modules.

How to Use the CXG

The CXG is a wizard-style application with three steps.

Step 1: Select Your CLIP and Define Its Properties

[+] Enlarge ImageFigure 1: First CXG step

Use the Top-Level VHDL File control to browse to the file that contains your CLIP's top-level entity declaration. This is the VHDL statement that declares the top-level entity that will interface to LabVIEW VIs and the CLIP Socket. Once a file is selected, all the entity declaration names in that file will be listed in in the left-side column. Click on an entity's name to Select the Top-Level Entity.

By default, the VHDL file name is used as the CLIP Declaration name. To create a custom declaration name for your CLIP, uncheck the Use VHDL File Name box and type in a custom name.

The file has also been added to the Implementation Files and Folders list. You can edit this list using the Add Path and Remove Path buttons. If you select a folder, all VHDL files in that folder will be linked at compile time. You can check the Recurse box next to a folder to force the utility to add all subfolders of that folder to the compilation. 

Note: This list uses syntax defined in the CLIP XML Schema. Refer to the LabVIEW 8.6 FPGA Module Help for more information about this syntax.

Note: It is strongly recommended that all implementation files be kept in the same folder as the top-level file or in subfolders. This greatly increases the portability of your CLIP between projects and systems, as it allows paths to these files to be defined using relative addressing instead of absolute addressing.

When you click Next, the CXG scans the port list for the chosen top-level entity and retrieves the names of all the signals in that list.

Step 2: Configure the Port Signals

[+] Enlarge ImageFigure 2: Second CXG step

The signals in the port list appear in the Unassigned Signals list on the left. The three lists on the right represent the interfaces available to the CLIP. You can learn more about types of CLIP in the LabVIEW 8.6 FPGA Module Help.

Drag unassigned signals into one of the interface lists. If a signal is placed in the Asynchronous Reset or Socket Interface list, it must conform to the strict definitions of this interface. See the LabVIEW Help link above and your target hardware documentation for more information about these restrictions.

After dropping a signal onto the LabVIEW Interface or Socket Interface lists, you must define that signal's properties by filling out each field for that signal. Click on a cell to enter information in that field. Each field will either require you to enter a string value or will provide a pop-up menu (shown above for the Data Type field) that allows you to select the appropriate value. The fields, which are descriptors for each signal in the signal list, are defined in the LabVIEW 8.6 FPGA Module Help.

When you click Next, the CXG gathers information from these lists and generates a CLIP XML document.

Step 3: Verify and Save the XML

[+] Enlarge ImageFigure 3: Third CXG step

The CLIP XML is shown for verification. If the XML was not built as you expected, you can click Back to change the values of any fields in the previous two steps.When you click Finish, a file will be created at the path shown in the XML File Path indicator. This path is always in the "working directory" and shares the top-level VHDL file's name.

Source Code Overview

The CXG was designed using the User Interface Event Handler VI template. It uses a simple While-loop/Event-structure design to respond to events generated on the user interface. All actions taken are driven by the user's interaction with the UI, and the application sits idle when the user takes no action. Control and indicator values are initialized at startup. When a shutdown is commanded, all resources are de-allocated prior to ending execution.

Figure. 4: The CXG project

The source project is shown in Figure 4. The top-level VI is called CLIP XML Generator.vi. SubVIs are organized into folders under the top-level VI. The Utilities folder contains simple functionalities needed to operate the user interface, such as populating listboxes and enabling/disabling controls and indicators. The other folders contain functional modules. Each functional module is a group of subVIs that work together to perform a closed task that is needed by the application, but that could also be used in other applications with minimal changes. The project also contains a "dummy" FPGA target, which is useful for testing the XML files generated by the application.

VHDL Parser

The VHDL parsing module consists of two parsing functions: VHDL_Get Entities.vi and VHDL_Get Port List.vi. They are similar in design, using a state machine template built around the Scan String for Tokens primitive. This primitive locates and extracts token strings from an input string. In the context of a state machine, it allows the designer to look for a specific sequence of substrings, branching to each action based on whether or not the expected substring is found.

Figure 5: The core function in the VHDL parsing VIs

The state machine diagram for the port list parser is provided as an example. This VI is designed to locate the "port" string in an entity declaration, then extract signal names from the list that follows this string. The list is encased in parentheses and terminated by a semicolon, so the tokens "(" and ");" are used to locate the beginning and end of the list.  Once inside the list, signal names are extracted and non-name tokens are skipped. The machine parses text one line at a time, so that when a comment string is found, it can break to the next line (not shown in Figure 6).

Figure 6: Simplified state machine diagram for VHDL_Get Port List.vi

NOTE: This diagram does not show error-handling transitions that are common to every state. It also omits the "Get Text" state that is conditionally called from every state in the diagram.

Pop-up Menus

The Signal Type, Direction, and Data Type fields have a limited set of string values that are allowed.  Any other value violates the CLIP XML schema and must not be permitted by the application.  To limit the user's selections, a pop-up menu is used to effect a text ring control for the user's selection.  These menus are subVIs that the top-level application calls dynamically when the appropriate cell is clicked by the user.  The "Data Type" menu is shown in Figure 7 as an example.

Figure 7: A menu subVI's front panel

When the menu VI is called, it waits for the user to select a value from its front-panel control.  When a selection is made, the corresponding legal string value is passed back to the top-level VI, and the menu subVI closes itself.

To optimize memory and disk performance, the menu subVIs are loaded into memory by reference using VI Server. They are called repeatedly during the application's execution and then unloaded when no longer needed.

XML Generator

The XML Generation module uses the Simple XML Library to generate an XML string and to parse it into a human-readable format.

Generating the XML String

The generation function is broken into two subfunctions: extract data from the UI controls (xml_Extract Inputs from UI.vi) and build the XML document tree (xml_Create CLIPDeclaration.vi).  The document tree conforms to the CLIP XML Schema v1.0.  Each branch of the tree is an subVI that encapsulates all its references.  For example, the "InterfaceList" branch of the CLIP XML is shown in Figure 8.

Figure 8: A snippet of CLIP XML including the "InterfaceList" branch

Figure 9 shows the code used to build the "InterfaceList" tree:

1. An element called "InterfaceList" is obtained and added to the document as a child of the "CLIPDeclaration" element.
2. A number of elements called "Interface" (one, in this example) are obtained and appended to the "InterfaceList" element.
3. The reference to the "InterfaceList" element is closed.

[+] Enlarge Image

Figure 9: "xml_Create InterfaceList.vi" block diagram

Digging deeper, Figure 10 shows the how the "Interface" tree, which is part of the "InterfaceList" tree, is built in code:

1. An element called "Interface" is obtained and assigned an attribute called "Name".  It is added to the document as a child of the "InterfaceList" element.
2. An element called "InterfaceType" is obtained and assigned a string value. It is added as a child of "Interface". Because it has no children, its reference is immediately closed.
3. An element called "SignalList" is obtained and added as a child of "Interface".
4. The reference to the "Interface" element is closed.

[+] Enlarge Image

Figure 10: "xml_Create Interface.vi" block diagram.  This VI is called by "xml_Create InterfaceList.vi", shown in Fig. 9.

In this way, the XML generation code is built in direct correlation to the structure of the XML document tree it is designed to generate. For every branch of the tree, there is a subVI. If that branch has branches of its own, it has subVIs as well. The leaves of the tree (elements without branches of their own) are created using the Simple XML Library.

Making the XML String Human-Readable

The XML document string that is generated is not separated by whitespace characters like newline and tab.  Because the XML tree should be verified by the user before creating a file, a VI was created to parse the string and add newline and tab characters to it.  This VI (Simple XML.lvlib:Convert to Pretty Print.vi) is a state machine centered around the Scan String for Tokens primitive, similar in design to the VHDL Parsing VIs.

Support and Discussion

This utility was created by the NI Systems Engineering group. 

The CXG is free and its source code is provided.  Minimal error handling logic is provided, and in the event of an error the utility is designed to report and halt execution.

Community support and extension of this utility is encouraged!  If you have feedback (questions, comments, etc.) or would like to share your customizations of the CXG, please post in the CLIP XML Generator thread in the NI Discussion Forums.

Related Links

On-Demand Tutorial: Importing External Codes to LabVIEW FPGA Using CLIP (SSP Required)

Requirements

Filename: cxg_1_1_0_source.zip

Software Requirements

Application Software: LabVIEW Full Development System 8.6
Language(s): LabVIEW

Filename: cxg_1_1_0.zip

Software Requirements

Application Software: LabVIEW Full Development System 8.6
Language(s): LabVIEW

Reader Comments | Submit a comment »

Comment on the CLIP XML Generator thread as well
Make sure you comment on the the CLIP XML Generator thread http://forums.ni.com/ni/board/message?board.id=Components&thread.id=62 as well. Comments posted there will be read and responded to.
- Systems Engineering, National Instruments. - Oct 17, 2008