3.5.1.8.1 Introduction

(Ask a Question)

SmartHLS™ introduces the Automatic On-Chip Instrumentation feature, which streamlines the instrumentation process, enhancing visibility into HLS-generated modules for effective debugging and verification. This feature also offers valuable insights into the design's operation.

On-Chip debugging serves as a vital complement to simulation debugging, enabling the detection of errors that occur with real data inputs, which may not be anticipated when using simulation test vectors. This is particularly useful when dealing with extensive datasets, such as prolonged video sequences. Additionally, it accounts for physical variables that only impact a design when executed on an actual board, such as temperature fluctuations, voltage changes, and interactions with other board components (e.g., DDR chips, Ethernet, HDMI cables, power regulators) or with other modules during system-level integration.

On-Chip debugging is an established method typically involving the deployment of probes or on-chip logic analyzers connected to specific design signals for waveform analysis. SmartHLS's Automatic On-Chip Instrumentation simplifies this process by providing a high-level instrumentation abstraction that integrates with existing tools like Synopsys Identify. (For more information, see Microchip Products page.)

SmartHLS now offers automatic instrumentation capabilities for:

The input and output ports of modules generated by SmartHLS.
The input and output ports, as well as the occupancy levels, of all FIFOs within the SmartHLS design.

This feature enables users to monitor the data exchange within SmartHLS modules and observe the information flow through function pipelines and dataflow designs that communicate via FIFOs. The following diagram illustrates the potential instrumentation points within the HLS-generated design, including AXI Stream, AXI Memory Mapped and Simple ports, as well as internal FIFO signals.

Figure 3-29. Potential Instrumentation Points in HLS-generated Design

Tip: A full example showing how to use the SmartHLS Automatic On-Chip Instrumentation feature is available on Github at https://github.com/MicrochipTech/fpga-hls-examples/tree/main/auto-instrument.

Configuration File

To simplify the instrumentation process, SmartHLS takes inspiration from the software debugging technique that allow users to pass command-line options, such as -v, -vv, -vvv for "verbose", "very verbose" or "very very verbose". In software, increasing the verbosity will print an increasing number of debug messages. Similarly, SmartHLS uses log levels to determine how much instrumentation is required. This provides an easy and convenient way to adjust the trade-off between resources and visibility because the more instrumentation is requested the more resources on the FPGA will be required for instrumentation. This log level is specified in a configuration file called instrument_init.jsonthat must be placed under the SmartHLS project directory.

Instrumentation can be enabled by running the shls instrument_init command, which will automatically generate the instrumentation configuration file with some default values that can be adjusted manually by the user as required. Here is an example of the file assuming there are two SmartHLS top-level modules called "my_top_level_module_1" and "my_top_level_module_2":

{
    "modules": {
        "my_top_level_module_1": {
            "log_level": "1",
            "fifo_log_level": "0"
        },
        "my_top_level_module_2": {
            "log_level": "2",
            "fifo_log_level": "1"
        }
    },
    "dashboard": {
        "max_iterations": -1,
        "show_markers": 1,
        "monitoring_mode": 0,
        "waveform_period": "5"
    },
    "iice_options": {
        "sample_buffer_depth": 1024,
        "iice_name": "my_dbg_hls_IICE"
    }
}

The following table describes the parameters of the instrument_init.json file.

Table 3-2. Parameters of `instrument_init.json` file
Option	Description
modules	Group all the settings for each top-level module
log_level	Specifies what in/out ports of the module get instrumented: 0: No instrumentation. 1: The tool instruments all simple ports and only AXI handshaking signals (i.e. valid/ready). Tries to reduce resource overhead when using AXI interfaces. 2: (Default) the tool instruments all the ports from log level 1, plus the AXI data and address ports. Meant to provide a balanced approach. 3: In log level 3, the tool instruments all the ports of the module. Will require the most resources but provides maximum visibility on all ports. See Table 3-3for a list of AXI signals that will be instrumented at each log level. By default, this is set to 2 for all modules.
fifo_log_level	Specifies what visibility is desired for all FIFOs in the SmartHLS modules. 0: (Default) No instrumentation. 1: Only FIFO full, empty and occupancy (number of words in the FIFO) are instrumented. 2: Signals included in FIFO_LOG_LEVEL=1 plus FIFO write_enable, read_enable, write_data and read_data. 3: All FIFO signals. This include almost_full, almost_empty, among others. By default, this is set to 0 for all modules.
dashboard	Group all monitoring mode related settings. For more information on the monitoring mode, see Modes.
max_iterations	Specifies how many times the debugger should be run. If set to -1, the debugger will run infinitely. Only applicable when using the monitoring mode. The default value is -1.
show_markers	Toggles whether markers should be drawn in the waveform when a captured sample dump ends. Only applicable when using the monitoring mode. The default value is 1.
monitoring_mode	1: Monitoring mode 0: (Default) Debugging mode See the Monitoring/Debugging modes section for more information.
waveform_period	The waveform period in nanoseconds that Identify will use when writing captured samples to a VCD file. By default, this is set to the period of the HLS module.
iice_options	Group all settings related to the automatically generated IICE
sample_buffer_depth	The depth (number of samples) of the IICE generated for the HLS project. There is one IICE per SmartHLS project. The default value is 1024.
iice_name	The name of the IICE generated for the SmartHLS project. If this is an empty string, the name of the IICE will be IICE_[HLS project folder name]. This is left empty by default.

For the AXI standard interfaces used in the SmartHLS-generated Verilog module, the following table shows the list of AXI signals that will be instrumented at each log level.

Table 3-3. Log Levels and AXI Signals Instrumented
Log Level	AXI Memory-Map and AXI Stream Signals that will be Instrumented
1	valid, ready
2	addr, data, len, burst, size, strb
3	All the signals

v2024.2

3.5.1.8.1 Introduction

Configuration File