hello.
My name is Intel F. Hanako and I provide technical support for Intel® FPGA products at Macnica.
previously introduced
Let's use the FPGA system debugging tool "System Console"
In , you typed System Console commands into the Tcl Console pane for execution on the System Console, but with the help of the Toolkit API services, you can create custom tools to visualize and manipulate your design's debug data. The Toolkit API provides visual widgets in the form of buttons and text fields that can leverage user input to communicate with debug logic.
This time, I will introduce how to use the Toolkit API in the System Console.
Target environment
Quartus® Prime |
Standard Edition / Lite Edition |
Target device |
All devices supported by the above editions of Quartus Prime |
communication cable |
・Intel FPGA Download Cable II (formerly known as USB-Blaster II) ・On-Board Intel FPGA Download Cable II ・Intel FPGA download cable (formerly known as USB-Blaster) ・On-Board Intel FPGA download cable |
Design requirements |
Your project design must include one of the following peripherals: ・ JTAG to Avalon Master Bridge (JTAG Master) ・ Nios II Processor (with JTAG Debug module) ・USB Debug Master ・ Avalon-ST (Streaming) JTAG Interface ・JTAG UART ・Ethernet components |
Note:
You can still use the Toolkit API in Pro Edition, but please use the new framework from Pro Edition 19.1 onwards.
sample design
The configuration of the sample design used here is as follows.
This time, we will use the Toolkit API in the System Console to visualize and manipulate the DIP switch PIOs, LED PIOs, and access to on-chip RAM with widgets.
Widget type
There are multiple widgets you can create.
For example, you can configure buttons, Box, combo Box, text Box, LEDs, bar charts, pie charts, etc.
Combining these widgets improves operability.
For widget types and properties, see the documentation below.
(From Intel Quartus Prime Standard Edition User Guide: Debug Tools > Analyzing and Debugging Designs with System Console)
For example, using the Toolkit API for the example design, you can control it with such a GUI.
[Sample A]
・ Click the button widget to control the turning on/off of the LED
・ Read ON/OFF status of DIP switch and display on LED widget
In addition, different widgets allow you to configure GUIs with different operability, such as:
[Sample B]
・ Specify the address of the LED PIO and the value to be written in the text widget, and control the ON/OFF of the LED
・ Reads the value of the DIP switch PIO address and displays it in the text widget
work flow
Toolkits built using the Toolkit API require the following files:
- A script file (.tcl) that implements the Toolkit GUI
・Toolkit description file (.toolkit)
The work flow up to starting the Toolkit API GUI is as follows.
- Create a Toolkit API script file (.tcl)
- Create a Toolkit description file (.toolkit)
- Register Toolkit
- Launch Toolkit
Here, [Sample A] is used as the material for explanation.
(The address of PIO for LED in this sample is 0x90.)
1. Create a Toolkit API script file (.tcl)
Create a script to build the GUI to use the Toolkit API service.
Here is an example Toolkit API script.
● Visualize Toolkit
To make the Toolkit visible on the System Console, use the toolkit_set_property command and the visible property.
Below is an example.
toolkit_set_property self visible true
Setting the visible property to True makes the widget visible in the GUI.
Use self if the property is provided throughout the toolkit.
Otherwise, use all to refer to the root toolkit.
なお ここで使用している toolkit_set_property コマンドの構文は以下のとおりです。
toolkit_set_property <id> <propertyName> <value>
argument
<id> unique id of the widget being edited
<propertyName> Name of the widget property being set
<value> new value for the widget property
● Add and configure widgets
Use the toolkit_add command to add widgets.
The syntax for the toolkit_add command is:
toolkit_add <id> <type> <groupid>
argument
<id> Unique ID of the widget being added
<type> the type of widget being added
<groupid> ID of the parent group containing the new widget
Also, set the details of the created widget using the toolkit_set_property command.
For example, if it is a text Box widget, you can set the initial display and the width of the text Box,
For group widgets, you can set the number of widgets to be placed in one row within the group widget.
(For the syntax of the toolkit_set_property command, see the “Visualize the Toolkit” section.)
Below is an example of building SW0 (see the red box in the bottom right of the figure below) with an LED widget.
toolkit_add SW0 led leds # LED ウィジェット SW0 を追加 toolkit_set_property SW0 text "SW0" # SW0 はテキストで SW0 と表示 toolkit_set_property SW0 color green_off # SW0 は 緑色(消灯)
When constructing an LED and a button, like LED3 (see the red box in the top left of the figure above), you would write:
toolkit_add LED3_led led buttons # LED ウィジェット LED3_led を追加 toolkit_set_property LED3_led text " " # LED3_led はテキストで表示なし toolkit_set_property LED3_led color red_off # LED3_led は赤(消灯)
toolkit_add LED3 button buttons # ボタンウィジェット LED3 を追加 toolkit_set_property LED3 text "LED3" # LED3 はテキストで LED3 と表示 toolkit_set_property LED3 onClick {toggle_led 3} # LED3 はクリックするたびに {} を実行
● Add event
Some widgets perform user-specified actions called callbacks.
For example, the TextField widget's onChange property is called when the text content changes.
The button widget's onClick is called when the button is clicked.
Callbacks update widgets based on the contents of text fields or the state of other widgets, or communicate with services.
To register an event with a callback as a trigger, define a procedure (proc command).
The syntax of the proc command is as follows:
proc <name> {args} {body}
argument
<name> procedure name
{args} variable list
{body} Tcl スクリプト
For example, click the button widget labeled LED3 to turn on LED3 on the board (write value to address 0x90),
To light up the LED widgets at the same time, write:
# This Procedure toggles the LED when you push the button on the toolkit proc toggle_led {led } { global master_path set led_read [master_read_8 $master_path 0x90 1]
# (LED0~LED2 用のコード省略)
if {$led == 3 } { set led_set [expr 8 ^ $led_read] }
master_write_8 $master_path 0x90 $led_set
set led_read [master_read_8 $master_path 0x90 1]
# (LED0~LED2 用のコード省略)
if { [expr {$led_read & 8}] == 8 } { toolkit_set_property LED3_led color red }
if { [expr {$led_read & 8}] == 0 } { toolkit_set_property LED3_led color red_off } }
2. Create a Toolkit description file (.toolkit)
Create a Toolkit description file that applies the created Toolkit API script file.
A Toolkit description file (.toolkit) is an XML file that provides registration data for Toolkit.
Below is a sample.
<?xml version="1.0" encoding="UTF-8"?> <toolkit name="system console toolkit" displayName="System Console Toolkit" addMenuItem="false"> <file> toolkit_script.tcl </file> </toolkit>
See the documentation below for the attributes and child elements required for .toolkit files.
Creating a Toolkit Description File
(From Intel Quartus Prime Standard Edition User Guide: Debug Tools > Analyzing and Debugging Designs with System Console)
3. Register Toolkit
To use the Toolkit, execute the toolkit_register command on the System Console by following the steps below.
(1) Start System Console.
(2) (If .sof has already been downloaded with Programmer before starting System Console, proceed to (4).)
Click the File menu > Load Design button and select the .sof to download.
(3) Open the connection destination under the devices folder in the System Explorer pane.
Right click > Program device > "sof file" for FPGA
Click
④ Specify the path to the .toolkit file with the toolkit_register command.
% toolkit_register ./tcl/toolkit_script.toolkit
4. Launch Toolkit
(1) Click Tools menu > Toolkits in System Console.
* It may have already been displayed.
② Toolkits タブ内に、作成した名称の Toolkit が追加されています。
Click the Launch button.
(3) The Toolkit created as a new window (tab) will start and the GUI will be displayed.
④ Debug using widgets.
sample script
I am attaching the script files for sample A and sample B. please refer.
Summary
By using the Toolkit API, you can use widgets on the System Console to help isolate problems with the actual FPGA, and you can debug with better operability.