To add IP as a component-level IP (CLIP) item in a LabVIEW project, the IP must have an accompanying declaration XML file to define the I/O for the FPGA Module. The declaration XML file describes the elements of the IP. The FPGA Module uses this file to add the IP to a LabVIEW project.

Refer to www.w3.org/XML for information about using XML.

Creating a Declaration File

Note NI strongly recommends that you use the Configure Component-Level IP wizard to create this declaration file so that you can avoid common errors. The following table contains reference information about the XML tags that the Configure Component-Level IP wizard generates.

The first line of the declaration file includes the XML version. All tags inside the file must be enclosed in <CLIPDeclaration> tags as shown below:

<?xml version="1.0"?> <CLIPDeclaration Name="My VHDL IP"> <!-- Insert tags here --> </CLIPDeclaration>

The following table defines the XML tags you can use in the declaration file.
Tag Required? Parent Tag Number of Tags with Parent Tag Description
CLIPDeclaration Yes — — All CLIP definitions must be contained within this tag. Name is a required attribute that defines the name of the CLIP that LabVIEW displays.
FormatVersion Yes CLIPDeclaration 1 Defines the version of the CLIP tags to use in this declaration XML file. Set FormatVersion to 4.3.
Description No CLIPDeclaration 1 Describes this CLIP and displays this description on the General page of the Component-Level IP Properties dialog box.
SupportedDeviceFamilies No CLIPDeclaration 1

Defines the supported device families using a comma-delimited list. LabVIEW recognizes the following devices: Spartan-3, Spartan-3E, Spartan-6, Virtex-II, Virtex-II Pro, Virtex-5, Virtex-6, Virtex-7, Zynq, Kintex-7.

You also can specify Unlimited to support all families.

CompatibleCLIPSocketList No CLIPDeclaration 1 For socketed CLIP, specifies which sockets the CLIP supports.
Socket Yes CompatibleCLIPSocketList 1 or more For socketed CLIP, specifies the compatible socket names.
TopLevelEntityAndArchitecture Yes CLIPDeclaration 1 Specifies the entity and architecture for the top-level synthesis and simulation VHDL files.
SynthesisModel Yes TopLevelEntityAndArchitecture 1 Specifies the entity and architecture name for the top-level synthesis VHDL file.
Entity Yes SynthesisModel 1 Specifies the entity name for the top-level synthesis VHDL file.
Architecture No SynthesisModel 1 Specifies the architecture name for the top-level synthesis VHDL file.
SimulationModel No TopLevelEntityAndArchitecture 1 Specifies the entity and architecture name for the top-level simulation VHDL file.
Entity Yes SimulationModel 1 Specifies the entity name for the top-level simulation VHDL file.
Architecture No SimulationModel 1 Specifies the architecture name for the top-level simulation VHDL file.
InterfaceList Yes CLIPDeclaration 1 Contains one or more interface definitions. You cannot nest interface lists. You can define only one interface list.
Interface Yes InterfaceList 1 or more Defines all the I/O, clocks, and other signals available to or from the CLIP. You cannot nest interfaces. Name is a required attribute.
InterfaceType Yes Interface 1

Defines where the interface is connected in the FPGA. You can enter one of the following values:

  • LabVIEW: Interface connects to the FPGA Module. All I/O and clocks are available as resources in the FPGA Module.
  • Socket: Interface connects directly to a target-defined socket. The I/O and clocks are not available as resources in the FPGA Module.
  • Fabric: Interface connects directly to the FPGA. The I/O and clocks are not available as resources in the FPGA.
SignalList Yes Interface 1 Contains one or more signal definitions. You cannot nest SignalList tags.
Signal Yes SignalList 1 or more

Defines a signal that will be available to or from the CLIP. Must contain the Name attribute, which the FPGA Module uses for display purposes. The Name attribute must begin with a letter and must only contain English letters and numbers, periods, dashes, and underscores. The default is the HDLName you declare in the Signal tag.

To organize signals into a CLIP IO hierarchy, use periods as delimiters in the name. For example, signals named A.Input and A.Output create a folder called A that contains signals Input and Output in the project.

Description No Signal 1 Specifies a description for the signal.
HDLName No Signal 0 or 1 Defines the name of the I/O entity in the VHDL file. The HDLName for the port must be the same as the name in the top-level synthesis file.
RequiredClockDomain No Signal 0 or 1 If you do not specify a required clock domain, you can use the I/O in any clock domain. The value of RequiredClockDomain must match a clock signal name defined in another location of the CLIP XML file. If you require a clock domain, any I/O Node on the block diagram that uses this CLIP I/O must be in the clock domain you specify. If the I/O Node is in the wrong clock domain, LabVIEW returns an error during compilation of the FPGA VI.
LeaveUndrivenIfNotUsedInLabVIEW No Signal 0 or 1 Specifies to not drive a signal in the top-level file when the VHDL has a default value. Otherwise, LabVIEW drives the signal with all zeros during code generation.
HDLType Yes Signal 1 Specifies the VHDL port type of a signal. Only std_logic and std_logic_vector are supported. Reset and clock signals can only be std_logic.
UseInLabVIEWSingleCycleTimedLoop No Signal 0 or 1 Valid values are: NotAllowed, Allowed, Required. The default value is Allowed. This tag specifies how you can use CLIP I/O in a single-cycle Timed Loop. In a single-cycle Timed Loop, you can ensure that data latches on every clock edge. If the IP in the CLIP expects to receive values on every clock edge, then setting this tag to Required makes LabVIEW enforce this requirement.
SpecificTargetClock No Signal 0 or 1 Specifies one of the available FPGA target base clocks as the required clock connection for the CLIP clock. The value of this tag is the name of the specific FPGA target base clock. The FPGA target base clock must exist in the project and must meet the required frequency range specified in the declaration XML file.
DataType Yes Signal 1

Defines the data type of the signal. If the signal is for a LabVIEW interface, the data type also defines how LabVIEW represents this signal. If the signal is for a socket interface, the data type must match the data type of the signal in the socket. Use one of the following child tags to define the data type:

  • <Boolean />
  • <U8 />
  • <U16 />
  • <U32 />
  • <U64 />
  • <I8 />
  • <I16 />
  • <I32 />
  • <I64 />
  • <FXP>...</FXP>
  • <Array>...</Array>
Boolean No DataType or Array See parent tag Specifies that the VHDL code uses std_logic. *
U8 No DataType See parent tag Specifies that the VHDL code uses std_logic_vector(7 downto 0). *
U16 No DataType See parent tag Specifies that the VHDL code uses std_logic_vector(15 downto 0). *
U32 No DataType See parent tag Specifies that the VHDL code uses std_logic_vector(31 downto 0). *
U64 No DataType See parent tag Specifies that the VHDL code uses std_logic_vector(63 downto 0). *
I8 No DataType See parent tag Specifies that the VHDL code uses std_logic_vector(7 downto 0). *
I16 No DataType See parent tag Specifies that the VHDL code uses std_logic_vector(15 downto 0). *
I32 No DataType See parent tag Specifies that the VHDL code uses std_logic_vector(31 downto 0). *
I64 No DataType See parent tag Specifies that the VHDL code uses std_logic_vector(63 downto 0). *
FXP No DataType See parent tag Specifies that the VHDL code uses std_logic_vector(x downto 0), where x is in range [0,63]. *
WordLength No FXP 0 or 1 Specifies the word length of the FXP signal. The supported range is [1, 64].
IntegerWordLength No FXP 0 or 1 Specifies the integer word length of the FXP signal. The supported range is [-2048, 2047].
Unsigned No FXP 0 or 1 Add this tag if the FXP signal is unsigned. Do not add this tag if the FXP signal is signed.
Array No DataType See parent tag Creates an array of the Boolean data type. You must include the Boolean tag within the Array tag. You can use only the Array tag with socketed CLIP.
Size Yes Array 1 Specifies the size of the array.
Direction No Signal 0 or 1

Indicates if the CLIP receives or sends data on the signal. You can select from the following values:

  • ToCLIP: Use for the CLIP to receive data on the signal. ToCLIP is the default value.
  • FromCLIP: Use for the CLIP to send data on the signal.
  • Bidirectional: Use for bidirectional lines. Support for Bidirectional is available only with socketed CLIP.
SignalType No Signal 0 or 1

Indicates the type of signal. You can select from the following values:

  • data: Use if the signal is a standard I/O data signal. If you do not specify a value for the SignalType tag, the default is data.
  • clock: Use if the signal is a clock. If you use clock, you must use the <Boolean/> tag within the DataType tag.
  • reset: Use if the signal is a reset signal that connects to the global asynchronous reset signal of the FPGA VI; refer to the Resetting VHDL Code section in the Creating or Acquiring IP topic. The global asynchronous reset signal for FPGA VIs is active-high. You can use reset only if the InterfaceType tag is set to Fabric. A reset signal must be a ToCLIP signal.
  • clock status: There are two types of clock status signals: SourceClockReady and DerivedClocksValid. Both signals are required for each FromCLIP clock with the SupportDerivedClocks tag. These signals together implement the handshaking interface with the LabVIEW FPGA clocking circuitry that produces derived clocks.
FreqInHertz No Signal 1 Defines the frequency range of the signal. The FreqInHertz tag is required if the SignalType is set to clock.
Max Yes FreqInHertz 1 Defines the maximum supported frequency in SI notation. The Max tag is required if you include a FreqInHertz tag. **
Min No FreqInHertz 0 or 1 Defines the minimum supported frequency in SI notation. If you do not specify a value for Min, the Min value equals the Max value. **
ImplementationList Yes CLIPDeclaration 1 Defines the CLIP files to include. The CLIP files do not need to be in the same directory. You can include only one ImplementationList tag.
Path Yes ImplementationList 1 or more

Defines the path or directory that contains the implementation file(s) that are required for the IP to compile. The path to a directory does not include subdirectories, so you must define subdirectories in separate tags. The Path tag assumes either a path relative to the XML file or an absolute path.

When defining a relative path to a subdirectory, use two periods in a row (..) to indicate the parent directory of the current working directory, a period (.) to indicate the current working directory, and a slash (/ or \) to get to the next subdirectory. For example, use ../folderA/fileB.vhd to point to the fileB.vhd file that is inside of the folderA directory, which is at the same hierarchical level as the folder containing the XML file on disk. Use /folderA/fileB.vhd to point to the fileB.vhd file that is inside of the folderA directory, which is at the same hierarchical level as the XML file on disk. LabVIEW returns an error for invalid paths. LabVIEW does not return an error for a path to an empty directory unless no other file or directory tags exist in the XML file.Name is a required attribute of this tag and must be the same as the synthesis filename.
MD5 No Path 1 Detects whether a synthesis file has been modified.
TopLevel No Path 0 or 1 Indicates whether the current synthesis file is the top-level file. One and only one VHDL file can be a the top-level synthesis file.
SimulationFileList No Path 1 Defines the simulation file(s) for a specific synthesis file. You can include only one <SimulationFileList> tag for one synthesis file. This tag is required when <SimulationModel> is present.
Path No SimulationFileList 1 or more

Defines the path or directory that contains the simulation file(s) that are required for the IP to compile. The path to a directory does not include subdirectories, so you must define subdirectories in separate tags. The Path tag assumes either a path relative to the XML file or an absolute path.

When defining a relative path to a subdirectory, use two periods in a row (..) to indicate the parent directory of the current working directory, a period (.) to indicate the current working directory, and a slash (/ or \) to get to the next subdirectory. For example, use ../folderA/fileB.vhd to point to the fileB.vhd file that is inside of the folderA directory, which is at the same hierarchical level as the folder containing the XML file on disk. Use /folderA/fileB.vhd to point to the fileB.vhd file that is inside of the folderA directory, which is at the same hierarchical level as the XML file on disk. LabVIEW returns an error for invalid paths. LabVIEW does not return an error for a path to an empty directory unless no other file or directory tags exist in the XML file. This tag is required under <SimulationModelType> when the <SimulationModelType> is User-defined. The simulation file name should be specified as the name attribute of this tag. Name is a required attribute.

SimulationModelType Yes SimulationFileList 1 Defines the simulation model type for a specific synthesis file. The options are: Same as synthesis, User-defined, and Exclude from simulation model. For non-netlist files, the default option is Same as synthesis. For netlist files, the default option is Exclude from simulation model, and Same as synthesis is not supported.
NumberOfDCMsNeeded No CLIPDeclaration 0 or 1 Reserves a certain number of digital clock managers (DCM) on the FPGA. LabVIEW uses this number when compiling to determine if the code instantiates too many DCMs.
NumberOfMMCMsNeeded No CLIPDeclaration 0 or 1 Reserves a certain number of mixed mode clock managers (MMCM) on the FPGA. LabVIEW uses this number when compiling to determine if the code instantiates too many MMCMs.
NumberOfBufGsNeeded No CLIPDeclaration 0 or 1 Reserves a certain number of BUFGs on the FPGA. LabVIEW uses this number when compiling to determine if the code instantiates too many global clock nets.
DutyCycleRange No Signal 0 or 1 Defines the maximum and minimum duty cycles that the clock supports. The default value is 50 percent. Include the % symbol after the value.
PercentInHighMax No DutyCycleRange 0 or 1 Defines the maximum time in percentage that the clock is held high. The default value is 50 percent. Include the % symbol after the value. **
PercentInHighMin No DutyCycleRange 0 or 1 Defines the minimum time in percentage that the clock is held high. The default value is 50 percent. Include the % symbol after the value. **
AccuracyInPPM

In ToCLIP: No

In FromCLIP: Yes

 Signal 0 or 1 Specifies the accuracy of the CLIP clock in parts per million. **
JitterInPicoSeconds

In ToCLIP: No

In FromCLIP: Yes

 Signal 0 or 1 Specifies the jitter of the CLIP clock in picoseconds. **
GenericList No CLIPDeclaration 1 Specifies information about the VHDL generic.
Generic Yes GenericList 1 or more Specifies the generic name as an attribute of this tag.
Description No Generic 1 Specifies a description for the generic. The description appears in the message box of the Generics and Syntax Check page of the Component-Level IP Properties dialog box.
GenericType Yes Generic 1 Specifies the generic type from the top-level synthesis file.
DefaultValue Yes Generic 1 Specifies the default value for the generic. This value is from the top-level synthesis file. You can specify another value to override the DefaultValue on the Generics and Syntax Check page of the Component-Level IP Properties dialog box or in the CLIP wizard.
SupportDerivedClocks No Signal 1 This tag is required for each FromCLIP clock that supports derived clocks. If this tag is present, the SourceClockReadyHDLName and DerivedClocksValidHDLName tags are also required. This tag is only valid for FromCLIP clock signals.
SourceClockReadyHDLName No Signal 1 This tag is required for each FromCLIP clock that has the SupportDerivedClocks tag. This is the HDL name of the clock status type signal in the FromCLIP direction. The presence of this HDL name indicates that the FromCLIP clock is valid and free-running. Once asserted, this signal should remain asserted until the DerivedClocksValid signal is asserted. De-asserting this signal indicates that the FromCLIP clock is about to be turned off. After de-asserting this signal, the FromCLIP clock should not be turned off until the DerivedClocksValidHDLName signal is de-asserted.
DerivedClocksValidHDLName Yes Signal 1

This tag is required for each FromCLIP clock that has the SupportDerivedClocks tag. This is the HDL name of the clock status type signal in the ToCLIP direction. The presence of this HDL name indicates that all derived clocks generated by the LabVIEW FPGA clock generation circuitry and sourced by this FromCLIP clock are valid and free-running. This signal serves two purposes:

  • The de-assertion of this signal indicates to the CLIP that it is safe to disable the FromCLIP clock.
  • This signal indicates to the CLIP when the generated derived clocks are valid.

This tag is required for each external clock that supports derived clocks.

SupportsGating

ToCLIP: Yes

In FromCLIP: No

 Signal 1 This tag is required for each ToCLIP gated clock in order to support removing implicit enable signals from single-cycle Timed Loops.
CyclesRequiredBeforeAsynchronousResetClears

ToCLIP: Yes

In FromCLIP: No

 Signal 1 Defines the number of clock edges of this clock that must occur while asynchronous reset is asserted. This value must be 0 for this CLIP to be used when the build specification is configured to allow the removal of implicit enable signals because the asynchronous reset will assert and deassert before the clock starts running. This value must also be 0 if this clock is used with external clocks that may stop during reset. If a CLIP requires a running clock during asynchronous reset, such as for CLIP that use built-in FIFOs, and the design requires the removal of implicit enable signals, consider creating a local asynchronous reset, and prevent diagram access to or from the CLIP while this local reset is asserted.
ReadBeforePlace No Path 1 This tag can be applied to one or more XDC files. An XDC file contains constraints that are read by the Xilinx Vivado toolchain. An XDC file with ReadBeforePlace tag will be read by the Xilinx Vivado toolchain just before invoking the Place process, while an XDC file without ReadBeforePlace tag will be read by the Xilinx Vivado toolchain just before invoking the Synthesis process. This tag is available in LabVIEW FPGA 2022 and later, with CLIP FormatVersion 4.3 and later. This tag will not be set by the wizard and should be set manually. This tag is not available in the UCF file which contains constraints that are read by the Xilinx ISE toolchain.

* This tag does not contain a value, so you can use a forward slash in the open tag or create empty open and close tags. For example, you can use <Boolean /> or <Boolean> </Boolean> to indicate a Boolean data type.

** You must use a period as the decimal separator when entering numeric values in CLIP parameters. If you use a comma as the decimal separator, LabVIEW returns an XML error.

Using a Schema to Reduce Errors

XML schema files are definition files that constrain an XML file to a certain format. You can add a schema file to most XML editing tools when writing an XML file. Use the CLIPDeclaration.xsd schema file in the labview\FPGA\CLIP\Schema directory to minimize syntax and formatting errors when you create a CLIP declaration file for user-defined CLIP.

Note The CLIPDeclaration.xsd schema file is available only for use with user-defined CLIP. For more information about schemas for socketed CLIP, refer to the FPGA target hardware documentation.
Note NI strongly recommends using the Configure Component-Level IP wizard to avoid errors in the declaration XML file.

Handling Multiple Implementation Files in Different Directories

You can specify multiple files to implement CLIP code. In the following example, the CLIP you want to implement has five files saved in the directory structure show below:

foo/myCLIPDeclaration.xml

foo/myTop.vhd

foo/mySide.vhd

foo/components/myLeftSubComponent.vhd

foo/components/myMiddleSubComponent.vhd

foo/components/myRightSubComponent.vhd

In the myCLIPDeclaration.xml you can indicate all five VHDL files are necessary for the CLIP by using relative paths. Include the following code in the XML file to specify that the two VHDL files in the foo directory and all the files in the components are necessary.

<ImplementationList>

<Path Name="./myTop.vhd">

<TopLevel/></Path>

<Path Name="./mySide.vhd"></Path>

<Path Name="./components"></Path>

(

<Path Name="./components/myLeftSubComponent.vhd"></Path>

<Path Name="./components/myMiddleSubComponent.vhd"></Path>

<Path Name="./components/myRightSubComponent.vhd"></Path>

)

</ImplementationList>

Refer to the CLIP Tutorial, Part 2: Defining the Interface for an example of defining the CLIP interface.