Skip to main content

Let's manipulate System Console commands with the Toolkit API GUI!

Let's manipulate System Console commands with the Toolkit API GUI!

  • Updated

Hello, my name is Intel F. Hanako. 
My name is Intel F. Hanako and I am the technical support for Intel® FPGA products at Macnica. 
I am Intel F. Hanako, a technical support engineer for Intel® FPGA products.

In the previous article, we entered the System Console commands to be executed on the System Console in the Tcl Console pane each time, but by utilizing the Toolkit API service, we can create custom tools to visualize and manipulate the debugging data of our design. The Toolkit API provides visual widgets in the form of buttons and text fields that leverage user input to communicate with debug logic.

In this article, we will show you how to use the Toolkit API in the System Console.


System Console

 

Target Environment

Quartus® Prime

Standard Edition / Lite Edition

Target Device

All devices supported by the above editions of Quartus Prime

Download Cable

 ・Intel FPGA Download Cable II (formerly USB-Blaster II)
・On-board Intel FPGA Download Cable II
・Intel FPGA Download Cable (formerly USB-Blaster)
・On-board Intel FPGA Download Cable
Requirements
 The 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 component

Note: The Toolkit API is also available in the Pro Edition, however, please use the new framework from Pro Edition 19.1 onwards.


Sample Designs

The sample design used here consists of the following 
We will use the Toolkit API on the System Console to visualize and manipulate the PIO of DIP switches, PIO of LEDs, and access to on-chip RAM through widgets.

Sample Design Configuration

 

Widget Types

There are several widget types that can be created. 
For example, buttons, checkboxes, combo boxes, text boxes, LEDs, bar graphs, and pie charts can be configured. 
These widgets can be combined to enhance usability.

For more information about widget types and properties, please refer to the following documentation

  • Toolkit API
    (from Intel Quartus Prime Standard Edition User Guide: Debug Tools > Analyzing and Debugging Designs with System Console)

 

For example, the Toolkit API can be used to control the sample design with a GUI like this

[Sample A]

  • Clicking a button widget to turn an LED on or off
  • Read the ON/OFF status of a DIP switch and display it on an LED widget

Button widget, LED widget

 

Another widget can be used to configure a GUI with different operability, as shown below.

 

[Sample B].

  • Specifying the LED PIO address and the value to be written to a text widget to control the turning on/off of the LED
  • Read the value of a DIP switch PIO address and display it in a text widget

Text widget

 

Workflow

The following files are required for a Toolkit created using the Toolkit API.

  • Script file (.tcl) that implements the Toolkit GUI
  • Toolkit description file (.toolkit)

The workflow to launch the Toolkit API GUI is as follows

In this section, [Sample A] is used as the subject. 
(In this sample, the address of PIO for LED is 0x90.)


1. Create a Toolkit API script file (.tcl)

To use the Toolkit API service, create a script to build the GUI. 
Here is an example of a Toolkit API script.

 

Visualizing the Toolkit

To make the Toolkit visible on the System Console, use the toolkit_set_property command and the visible property. 
The following is an example.

 toolkit_set_property self visible true

Setting the visible property to true makes the widget visible in the GUI. 
If the property is provided for the entire toolkit, use self. 
Otherwise, use all to refer to the root toolkit.

Note that the syntax of the toolkit_set_property command used here is

  • toolkit_set_property <id> <propertyName> <value>
    • Arguments
      • <id> Unique ID of the widget being edited
      • <propertyName> The name of the widget property being set
      • <value> The new value of the widget property

 

Adding and configuring widgets

To add a widget, use the toolkit_add command. 
The syntax of the toolkit_add command is

  • toolkit_add <id> <type> <groupid>
    • Arguments
      • <id> Unique ID of the widget being added
      • <type> The type of the widget being added
      • <groupid> ID of the parent group containing the new widget

The details of the created widget can be set by using the toolkit_set_property command. 
For example, for a textbox widget, you can set the initial display and the width of the textbox, and for a group widget, you can set the number of widgets to be placed in a row within a group widget. 
(For the syntax of the toolkit_set_property command, see the section "Making the Toolkit Visible.") 
The following is an example of building SW0 (see red box in the lower right corner of the figure below) with an LED widget.

 toolkit_add SW0 led leds # add LED widget SW0
toolkit_set_property SW0 text "SW0" # SW0 is displayed as SW0 text
toolkit_set_property SW0 color green_off # SW0 is green (lights off)

To create LEDs and buttons like LED3 (see the red frame in the upper left of the above figure), write as follows

 toolkit_add LED3_led led buttons # Add LED widget LED3_led
toolkit_set_property LED3_led text " " # LED3_led is text, no display 
toolkit_set_property LED3_led color red_off # LED3_led is red (lights off) 

toolkit_add LED3 button buttons # add button widget LED3
toolkit_set_property LED3 text "LED3" # LED3 is displayed as text LED3
toolkit_set_property LED3 onClick {toggle_led 3} # LED3 executes {} each time it is clicked


Add events

Some widgets perform user-specified actions called callbacks. 
For example, the onChange property of a text field widget is called when the text content changes. 
A button widget's onClick is called when the button is clicked.

Callbacks update widgets or communicate with services based on the contents of text fields or the state of other widgets. 
To register an event that triggers a callback, define a procedure (proc command). 
The syntax of the proc command is as follows

  • proc <name> {args} {body}
    • Arguments
      • <name> procedure name
      • {args} variable list
      • {body} Tcl script

For example, to turn on LED3 on the board (write the value to address 0x90) and simultaneously turn on the LED widget by clicking on the button widget labeled LED3, write the following

 # 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] 

# (code omitted for LED0 to 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] 

# (code omitted for LED0 to 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 Toolkit description file (.toolkit)

Create a Toolkit description file to which the Toolkit API script file you created is applied. 
Toolkit description file (.toolkit) is an XML file that provides Toolkit registration data. 
The following 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>

Please see the following documentation for the required attributes and child elements of the .toolkit file.

 

3. Register the Toolkit

To use the Toolkit, execute the toolkit_register command on the System Console according to the following procedure.

1) Start System Console.

2) (If you have already downloaded the .sof file from the Programmer before starting the System Console, go to 4). 
　 Click the File menu > Load Design button and select the .sof file to be downloaded. 
　Download the .sof file.

3) Right-click on FPGA under the devices folder in the System Explorer pane, and click "Program device" > "sof file".


4) Specify the path to the .toolkit file with the toolkit_register command.

 % toolkit_register . /tcl/toolkit_script.toolkit

 

4. Start Toolkit

1) Click Tools menu > Toolkits in System Console. 

The created Toolkit appears.

2) The Toolkit with the created name is added to the Toolkits tab.　Click the "Launch" button.

3) The Toolkit you created is launched as a new window (tab) and the GUI is displayed.

4) Use the widgets for debugging.

 

Sample Scripts

Sample A and B script files are attached. Please refer to them.

 

Summary

By utilizing the Toolkit API, widgets can be used on the System Console, which is useful for isolating FPGA problems on the actual device, and debugging can be done with ease.

 

Recommended articles/documents are here

Related articles