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 trigger condition, capture condition, and data types, 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 or Ethernet cable. Make sure that the required 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.

EnableCaptureCtrl — Argument to enable capture condition logic

false (default) | true

Set this property to true to enable capture condition logic in the HDL IP core. Enable capture condition logic to use a capture condition to control which data to capture from the FPGA. The HDL IP core evaluates the capture condition at each clock cycle and captures only the data that satisfies the capture condition. For more information on capture conditions, see Capture Conditions.

Dependencies

To enable this parameter, in the FPGA Data Capture Component Generator tool, select Include capture condition logic.

CaptureMode — Capture mode

'blocking' (default) | 'nonblocking'

Specify the capture mode as one of these options:

• 'blocking' — The data capture object blocks MATLAB while retrieving captured data. In this capture mode, the JTAG resource is allocated to either FPGA data capture or AXI manager at a time.

• 'nonblocking' — The data capture object does not block MATLAB while retrieving captured data. In this capture mode, you can use FPGA data capture and AXI manager simultaneously.

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'.

Dependencies

To enable this property, in the FPGA Data Capture Component Generator tool, set the Connection type parameter to JTAG.

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

Dependencies

To enable this property, in the FPGA Data Capture Component Generator tool, set the Connection type parameter to JTAG.

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.

Dependencies

To enable this property, in the FPGA Data Capture Component Generator tool, set the Connection type parameter to JTAG.

IRLengthBefore — Instruction register lengths before the FPGA

0 (default) | nonnegative integer

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

Dependencies

To enable this property, in the FPGA Data Capture Component Generator tool, set the Connection type parameter to JTAG.

IRLengthAfter — Instruction register lengths after the FPGA

0 (default) | nonnegative integer

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

Dependencies

To enable this property, in the FPGA Data Capture Component Generator tool, set the Connection type parameter to JTAG.

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.

Dependencies

To enable this property, in the FPGA Data Capture Component Generator tool, set the Connection type parameter to JTAG.

DeviceAddress — IP address of Ethernet port on FPGA board

192.168.0.2 (default) | dotted-quad value

Specify the internet protocol (IP) address of the Ethernet port on the FPGA board as a dotted-quad value. The device IP address must be a set of four numbers consisting of integers in the range from 0 to 255 that are separated by three dots.

Dependencies

To enable this property, in the FPGA Data Capture Component Generator tool, set the Connection type parameter to Ethernet.

Port — UDP port number of FPGA board

50101 (default) | integer from 255 to 65,535

Specify the user datagram protocol (UDP) port number of the FPGA board as an integer from 255 to 65,535.

Dependencies

To enable this property, in the FPGA Data Capture Component Generator tool, set the Connection type parameter to Ethernet.

Object Functions

checkStatus	Check current status of FPGA data capture in nonblocking mode
clone	Create hdlverifier.FPGADataReader System object with same property values
collectData	Collect captured data from FPGA to host in nonblocking mode
displayCaptureCondition	Display overall capture condition
displayDataTypes	Display data types for all captured signals
displayTriggerCondition	Display overall trigger condition
isLocked	Locked status
launchApp	Open FPGA Data Capture app
release	Release control of JTAG interface
setCaptureCondition	Configure comparison for each signal value
setCaptureConditionCombinationOperator	Configure operator that combines individual signal value comparisons into overall capture condition
setCaptureConditionComparisonOperator	Configure operator that compares individual signal values within capture condition
setDataType	Configure data type for the data captured from a signal
setNumberofTriggerStages	Configure number of trigger stages for capturing data
setRunImmediateFlag	Configure data capture to run immediately without any trigger condition
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
stop	Stop FPGA data capture execution based on current status in nonblocking mode

Examples

Capture Data from FPGA over JTAG Connection

This example shows how to use the hdlverifier.FPGADataReader System object™ to capture data from a design running on an FPGA over a JTAG connection. The hdlverifier.FPGADataReader System object provides a programmatic way to configure and capture data. Generate an FPGA data reader System object by using the FPGA Data Capture Component Generator tool. Then use the generated System object directly to set data types and trigger conditions and capture data.

Generate hdlverifier.FPGADataReader System Object

To generate a customized hdlverifier.FPGADataReader System object, open the FPGA Data Capture Component Generator tool by entering following command at the MATLAB® command prompt. To use this tool, you must have an existing HDL design and FPGA project.

generateFPGADataCaptureIP;

This example uses a generated object, mydc, that defines two signals for data capture. Signal A is 1 bit and signal B is 8 bits. Both signals are also available for use in trigger conditions. The sample depth is 4096 samples. To configure the hdlverifier.FPGADataReader System object to operate on these two signals, follow these steps.

1. Add one row to the Ports table by clicking the Add button once.

2. Name the first signal A and the second signal B.

3. Set Bit Width of the two signals to 1 and 8, respectively.

4. Specify Generated IP name as mydc.

5. Set FPGA vendor to Xilinx.

6. Set Sample depth to 4096.

7. Set Max trigger stages to 2.

This figure shows these tool settings.

To generate the hdlverifier.FPGADataReader System object, click Generate. A report shows the results of the generation. Integrate the generated IP code into your existing FPGA project and deploy it to the FPGA. The System object communicates with the FPGA over a JTAG cable. Make sure that the JTAG cable connects the board and the host computer.

Go to the directory where the hdlverifier.FPGADataReader System object is generated.

cd hdlsrc;

Create a data capture object using your generated System object.

captureData = mydc

captureData =

   mydc with properties:

              Connection: 'JTAG'
    IsConditionalCapture: 0
         TriggerPosition: 0
       NumCaptureWindows: 1
        NumTriggerStages: 2
                 TimeOut: 10
       EnableCaptureCtrl: 0
             CaptureMode: 'blocking'
           JTAGCableName: 'auto'
           JTAGCableType: 'auto'
       JTAGChainPosition: 0
          IRLengthBefore: 0
           IRLengthAfter: 0
            TckFrequency: 15
     MaxNumTriggerStages: 2

Capture Data Immediately

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

captureData = mydc;

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

displayDataTypes(captureData);

Signal Name : Data Type
Capture_Window : uint32
Trigger_Position : boolean
A : boolean
B : uint8

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

[Capture_Window,Trigger_Position,dataOut] = captureData();

The captured data is returned as a structure containing a field for the Capture_Window signal, a field for the Trigger_Position signal, and a field for each signal captured by the data capture object. The dataOut structure contains field A, which is a vector of 4096 logical values, and field B, which is 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 an AND or OR operator.

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','>');

Display the overall trigger condition.

displayTriggerCondition(captureData);

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

Call the object to capture data on the specified trigger event.

[~,~,dataOut] = captureData();

Define a trigger condition to capture data when the FPGA detects a high value on A at the same time as the value of signal B is 0xAX. In signal B, the trigger condition checks the leftmost 4 bits provided as A and ignores the rightmost 4 bits provided as X (X indicates bits for the function to ignore).

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

Display the overall trigger condition.

displayTriggerCondition(captureData);

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

Call the object to capture data on the specified trigger event.

[~,~,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);

Display the trigger condition. By default, the function displays the trigger condition in trigger stage 1.

displayTriggerCondition(captureData);

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

Display the trigger condition in trigger stage 2.

displayTriggerCondition(captureData,2);

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

Call the object to capture data on the specified trigger events.

[~,~,dataOut] = captureData();

dataOut is returned 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, you can represent the signal using 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));

Display the data types of the captured signals.

displayDataTypes(captureData);

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

Call the object to capture data on the specified trigger event.

[~,~,dataOut] = captureData();

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

Version History

Introduced in R2017a