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, Ethernet, or USB 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.
Creation
creates a customized object,
DC
= mydcDC
, 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
.
Dependencies
To enable this property, in the FPGA Data Capture Component Generator tool, set Storage
type to Internal memory
.
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.
Dependencies
To enable this property, in the FPGA Data Capture Component Generator tool, set Storage
type to Internal memory
.
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 property, 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.
DataCaptureID
— Data capture System object identifier (AMD® only)
1
(default) | integer from 1 to 8
Specify the data capture System object identifier as an integer from 1 to 8. For each data capture System object, the value of this property must be unique and must match the data capture ID of the corresponding data capture HDL IP core.
Dependencies
To enable this property, in the FPGA Data Capture Component Generator tool, set FPGA
vendor to AMD
and Number of data
capture IPs to a value greater than 1.
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 SetupJTAGCableType
— Type of JTAG cable used for communication with FPGA board (AMD only)
'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 FPGA
vendor to AMD
and Connection
type 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
JTAGChainPosition
— Position of FPGA in JTAG scan chain (AMD only)
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 FPGA
vendor to AMD
and Connection
type to JTAG
.
IRLengthBefore
— Instruction register lengths before the FPGA (AMD only)
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 FPGA
vendor to AMD
and Connection
type to JTAG
.
IRLengthAfter
— Instruction register lengths after the FPGA (AMD only)
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 FPGA
vendor to AMD
and Connection
type to JTAG
.
TckFrequency
— JTAG clock frequency (AMD only)
15
(default) | integer
Specify the JTAG clock frequency, in MHz. For AMD 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 FPGA
vendor to AMD
and Connection
type to JTAG
.
MemoryBaseAddress
— Base address of external DDR memory (AMD only)
'80000000'
(default) | character vector | string scalar
Specify the base address of the external DDR memory as a character vector or string scalar. Use this value to indicate where you want to store the captured data in the DDR memory.
Dependencies
To enable this property, in the FPGA Data Capture Component Generator tool, set FPGA
vendor to AMD
, Connection
type to JTAG
, and Storage
type to External memory
.
DeviceAddress
— IP address of Ethernet port or USB Ethernet gadget on FPGA or SoC board (AMD only)
character vector | string scalar
Specify the internet protocol (IP) address of the Ethernet port or USB Ethernet
gadget on the FPGA or SoC board as a character vector or string scalar. 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. The default IP address for the PL Ethernet or PS
Ethernet interface is 192.168.0.2
. The default IP address for the USB
Ethernet interface is 192.168.1.2
.
Dependencies
To enable this property, in the FPGA Data Capture Component Generator tool, set FPGA
vendor to AMD
and Connection
type to PL Ethernet
, PS
Ethernet
, or USB Ethernet
.
Port
— UDP port number of FPGA board (AMD only)
'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 FPGA
vendor to AMD
and Connection
type to PL Ethernet
.
CaptureBaseAddress
— Base address of data capture HDL IP core (AMD only)
'40000000'
(default) | character vector | string scalar
Specify the base address of the data capture HDL IP core as a character vector or string scalar.
Dependencies
To enable this property, in the FPGA Data Capture Component Generator tool, set FPGA
vendor to AMD
and Connection
type to PS Ethernet
or USB
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 Intel FPGA Board 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.
Add one row to the Ports table by clicking the Add button once.
Name the first signal
A
and the second signalB
.Set Bit Width of the two signals to
1
and8
, respectively.Specify Generated IP name as
mydc
.Set FPGA vendor to
Altera
.Set Sample depth to
4096
.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' DataCaptureName: 'mydc' IsConditionalCapture: 0 TriggerPosition: 0 NumCaptureWindows: 1 NumTriggerStages: 2 TimeOut: 10 EnableCaptureCtrl: 0 JTAGCableName: 'auto' MaxNumTriggerStages: 2 CaptureMode: 'blocking'
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 signalB
is equal to 7Trigger condition 2 - High value on
A
at the same time as signalB
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.
Capture Data from AMD FPGA Board 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.
Add one row to the Ports table by clicking the Add button once.
Name the first signal
A
and the second signalB
.Set Bit Width of the two signals to
1
and8
, respectively.Specify Generated IP name as
mydc
.Set FPGA vendor to
AMD
.Set Sample depth to
4096
.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' DataCaptureName: 'mydc' IsConditionalCapture: 0 MemoryType: 'Internal memory' TriggerPosition: 0 NumCaptureWindows: 1 NumTriggerStages: 2 TimeOut: 10 EnableCaptureCtrl: 0 JTAGCableName: 'auto' JTAGCableType: 'auto' JTAGChainPosition: 0 IRLengthBefore: 0 IRLengthAfter: 0 TckFrequency: 15 MemoryBaseAddress: '80000000' MaxNumTriggerStages: 2 CaptureMode: 'blocking'
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 signalB
is equal to 7Trigger condition 2 - High value on
A
at the same time as signalB
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
See Also
Tools
Blocks
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)