hdlverifier.FPGADataReader

Capture data from live FPGA into MATLAB workspace

Description

The hdlverifier.FPGADataReader System object™ communicates with a generated HDL IP core running on an FPGA board to capture signals from the FPGA into MATLAB^®.

The hdlverifier.FPGADataReader System object cannot be created directly. To use it, run FPGA Data Capture Component Generator and generate your own customized FPGADataReader System object. You can use the generated object directly or use the wrapper tool, FPGA Data Capture, to set data types and trigger conditions and capture data.

Before you create the System object, you must have previously generated the customized data capture components. You must also have integrated the generated IP code into your project and deployed it to the FPGA. The object communicates with the FPGA over a JTAG cable. Make sure that the JTAG cable is connected between the board and the host computer.

For a workflow overview, see Data Capture Workflow.

Note

Alternatively, instead of using the step method to perform the operation defined by the System object, you can call the object with arguments, as if it were a function. For example, y = step(obj,x) and y = obj(x) perform equivalent operations.

Creation

DC = mydc creates a customized object, DC, that captures data from a design running on an FPGA. mydc is the component name you specified in the FPGA Data Capture Component Generator tool.

Properties

TimeOut — Number of seconds until aborting data capture

10 (default) | positive integer

If a trigger condition is enabled, but the HDL IP core does not detect the condition, the data capture request times out after the specified number of seconds. If the data capture is aborted, no data is returned to MATLAB.

When you use the tool for data capture, this property is ignored. Use the Stop button on the pop-up window to abort a capture using the tool.

NumCaptureWindows — Number of data capture recurrences

1 (default) | integer power of two

Specify the number of recurrences to capture. This value must be a power of two, and cannot be greater than Sample depth. When specifying the sample depth, consider the number of windows you plan to configure when reading the data, because together they impact the window depth of each capture window. The window depth is the Sample depth divided by the Number of capture windows. Specify Sample depth in the FPGA Data Capture Component Generator tool.

For example: If Sample depth is 4096 and Number of capture windows is 4, then each capture window has a window depth of 1024.

NumTriggerStages — Number of trigger stages for providing trigger conditions

M (default) | integer from 1 to M

Specify the number of trigger stages. This value must be an integer from 1 to M, where M is set by the Max trigger stages parameter of the FPGA Data Capture Component Generator tool. When you specify the Max trigger stages parameter, consider the maximum number of trigger stages in which you plan to configure the trigger conditions to capture data.

For example, if Max trigger stages is 4, then NumTriggerStages can be 1, 2, 3, or 4.

TriggerPosition — Position of the trigger detection cycle within the capture buffer

0 (default) | integer up to window depth-1

By default, the clock cycle when the trigger is detected is the first sample of the capture buffer. You can change the relative position of the trigger detection cycle within the capture buffer. A nondefault trigger position means that some samples are captured before the trigger occurs. You can set this parameter to an integer from 0 to window depth–1, inclusive. When the trigger position is equal to window depth–1, the last sample corresponds to the cycle when the trigger occurs. For more information, see Triggers.

If your development board has multiple FPGAs or multiple JTAG connections, the data capture software cannot detect the location of your FPGA in the JTAG chain. Specify these advanced parameters to locate the FPGA that contains the data capture IP core.

Advanced Board Setup

JTAGCableType — Type of JTAG cable used for communication with FPGA board

'auto' (default) | 'FTDI'

Specify this property if more than one JTAG cable is connected to the host computer. When not specified, the object will auto-detect the JTAG cable type, in this order:

• The FPGADataReader object first searches for a Digilent^® cable.

• If it does not find a Digilent JTAG cable, it searches for an FTDI cable.

• If it finds two cables of the same type, the object returns an error. Specify JTAGCableName to resolve it.

• If it finds two cables of different types, it will prioritize the Digilent cable. To use an FTDI cable, set this property to 'FTDI'.

JTAGCableName — Name of JTAG cable used for data capture

'auto' (default) | character vector

Name of the JTAG cable used for data capture, specified as a character vector. Use this argument when the board is connected to two JTAG cables of the same type

JTAGChainPosition — Position of FPGA in JTAG scan chain

0 (default) | positive integer

Position of the FPGA in the JTAG scan chain, specified as a positive integer.

IRLengthBefore — Instruction register lengths before the FPGA

0 (default) | nonnegative integer

Number of instruction register lengths before the FPGA, specified as a nonnegative integer.

IRLengthAfter — Instruction register lengths after the FPGA

0 (default) | nonnegative integer

Number of instruction register lengths after the FPGA, specified as a nonnegative integer.

TckFrequency — JTAG clock frequency

15 (default) | integer

Specify the JTAG clock frequency, in MHz. For Xilinx^® FPGAs, the JTAG clock frequency is 33 or 66 MHz. The JTAG frequency depends on the type of cable and the maximum clock frequency supported by the FPGA board.

Object Functions

clone	Create hdlverifier.FPGADataReader System object with same property values
displayDataTypes	Display data types for all captured signals
displayTriggerSettings	Display overall trigger condition
isLocked	Locked status
launchApp	Open FPGA Data Capture app
release	Release control of JTAG interface
setDataType	Configure data type for the data captured from a signal
setNumberofTriggerStages	Configure number of trigger stages for capturing data
setTriggerCombinationOperator	Configure operator that combines individual signal value comparisons into overall trigger condition
setTriggerComparisonOperator	Configure operator that compares individual signal values within trigger condition
setTriggerCondition	Configure each signal value comparison
setTriggerTimeOut	Configure maximum number of FDC IP core clock cycles within which trigger condition must occur in a trigger stage
step	Capture one buffer of data from HDL IP core running on FPGA

Examples

Open the App

Before you open the FPGA Data Capture app, you must have previously generated the customized data capture components, using the FPGA Data Capture Component Generator tool. You must also have integrated the generated IP code into your project and deployed it to the FPGA. The tool communicates with the FPGA over a JTAG cable. Make sure that the JTAG cable is connected between the board and the host computer.

Create a data capture object using your generated System object. Then open the FPGA Data Capture app.

captureData = mydc;
launchApp(captureData)

About These Examples

These examples use a generated object, mydc, that defines two signals for data capture. Signal A is one bit and signal B is 8 bits. Both signals are also available for use in trigger conditions. The sample depth is 4096 samples. The generated HDL IP core is integrated into an existing FPGA design and running on the FPGA.

Capture Data Immediately

Create a data capture object and display the default trigger condition. The default configuration of the generated object does not enable any signals as part of the overall trigger condition.

captureData = mydc
displayTriggerCondition(captureData)

Trigger Immediately

Display the data types of the captured signals. The default data type for the 8-bit signal is uint8.

displayDataTypes(captureData)

Signal Name : Data Type
A : boolean
B : uint8

Call the object. The data is captured immediately from the FPGA.

dataOut = captureData();

The dataOut structure contains a field A, a vector of 4096 logical values, and a field B, a vector of 4096 uint8 values.

Capture Data on Trigger Event

To debug signal values near a specific event, set up a trigger condition. The trigger condition can be composed of value comparisons of one or more signals. You can combine these value comparisons with only one type of logical operator, either AND or OR operators.

Define a trigger condition to capture data when the FPGA detects a high value on A at the same time as signal B is greater than 7.

captureData = mydc
setTriggerCondition(captureData,'A',true,'High')
setTriggerCondition(captureData,'B',true,7)
setTriggerComparisonOperator(captureData,'B','>')
displayTriggerCondition(captureData)

The trigger condition is:
A==High and B>7

dataOut = captureData();

Define a trigger condition to capture data when the FPGA detects a high value on A at the same time as signal B value is 0xAX. In signal B, the trigger condition checks the left-most 4 bits provided as A and ignores the right-most 4 bits provided as X (don't care value).

captureData = mydc
setTriggerCondition(captureData,'A',true,'High')
setTriggerCondition(captureData,'B',true,'0xAX')
displayTriggerCondition(captureData)

The trigger condition is:
A==High and B==0xAX

dataOut = captureData();

dataOut is returned after the HDL IP core detects the trigger condition from the signals on the FPGA. dataOut contains samples starting from the cycle when the trigger condition is detected.

Capture Data on Multiple Trigger Events

Define trigger conditions to capture data when the FPGA detects two trigger conditions in sequence.

• Trigger condition 1: high value on A at the same time as signal B is equal to 7.

• Trigger condition 2: high value on A at the same time as signal B is greater than 15.

captureData = mydc
setNumberofTriggerStages(captureData,2)
setTriggerCondition(captureData,'A',true,'High')
setTriggerCondition(captureData,'B',true,7)
setTriggerCondition(captureData,'A',true,'High',2)
setTriggerCondition(captureData,'B',true,15,2)
setTriggerComparisonOperator(captureData,'B','>',2)

displayTriggerCondition(captureData)

The trigger condition is:
A==High and B==7

displayTriggerCondition(captureData,2)

The trigger condition is:
A==High and B>15

dataOut = captureData();

dataOut returns when the HDL IP core detects the trigger condition set in trigger stage 2 after detecting the trigger condition set in trigger stage 1, satisfying the set sequence.

Capture Fixed-Point Data

The default data type for an 8-bit signal is uint8, but in your HDL design, it can represent a fixed-point number. Set the data type of the captured data to cast it to the fixed-point representation.

captureData = mydc
setDataType(captureData,'B',numerictype(1,8,6))
displayDataTypes(captureData)

Signal Name : Data Type
A : boolean
B : numerictype(1,8,6)

dataOut = captureData();

In the dataOut structure, field A is a vector of 4096 logical values, field B is a vector of 4096 signed 8-bit fixed-point values, with 6 fractional bits.