Quartus® Prime Pro Edition User Guide: Design Compilation

ID 683236
Date 9/30/2024
Public
Document Table of Contents

1.3.2.2. Preserving Signals for Monitoring and Debugging

The Compiler optimizes the RTL signals during synthesis and place-and-route. Unless preserved, the signal names in your RTL might not exist in the post-fit netlist after signal optimizations. For example, the compilation process can merge duplicate registers, or add tildes (~) to net names that fan-out from a node.

Preserving a signal so that it is available for debugging after synthesis and place-and-route involves the following steps:
  • Marking the signal for preservation.

    You can mark the signal directly in your RTL code or through a QSF assignment command.

  • Enabling signal preservation either for the entire project or for the instance that contains the marked signal.

    You can enable project-wide signal preservation through the Quartus® Prime GUI or a QSF assignment command. To preserve signals in an instance, use a QSF assignment command.

By separating marking signals for preservation and enabling signal preservation, you can tag signals of interest as you write your code with no effect on optimization until you enable signal preservation.

When signal preservation is enabled, the nodes marked preserve_for_debug inherit the following attributes:
Table 5.  Attributes Inherited by Nodes Marked preserve_for_debug
Attribute Result
preserve Prevents Quartus® Prime from optimizing away or retiming a register
keep Prevents Quartus® Prime from minimizing or removing a signal net during combinational logic optimization
noprune Prevents Quartus® Prime from removing or optimizing a fanout free register
dont_merge Prevents Quartus® Prime from merging a register with a duplicate register
dont_replicate Prevents Quartus® Prime from duplicating a register
Important: Instance-level signal preservation settings always override project-wide level settings. Also, signal preservation settings in your RTL always override QSF settings.
After you synthesize your design, you can locate and review your preserved signals:
  • The Preserve for Debug Assignments report shows the preservation status and name of all nodes that are marked for preservation.
  • The preserved for debug filters in Node Finder helps you quickly find preserved nodes.

The overall flow to follow to preserve signals for monitoring and debugging is as follows:

  1. Mark the signals that you want to preserve in one of the following ways:
    • Mark the signals directly in your RTL code with the preserve_for_debug attribute:
      Table 6.  Examples of Marking Signals with the preserve_for_debug Attribute in RTL
      Verilog Example VHDL Example
      (* preserve_for_debug *) wire [3:0] counter_wire;
      (* preserve_for_debug *) reg [3:0] counter_reg;
      
      (* preserve_for_debug *) wire [15:0] decode_out_top;
      (* preserve_for_debug *) reg [15:0] decode_out_reg_top;
      attribute preserve_for_debug : boolean;
      attribute preserve_for_debug of counter_wire : signal is true;
      attribute preserve_for_debug of counter_reg : signal is true;
      attribute preserve_for_debug of decode_out : signal is true;
      attribute preserve_for_debug of decode_out_reg : signal is true;
      In the Quartus® Prime GUI, you can also use the Insert Template (Edit > Insert Template) dialog box to add the preserve_for_debug attribute.
    • Mark the signals with the PRESERVE_FOR_DEBUG assignment in one of the following ways:
      • Specify the PRESERVE_FOR_DEBUG assignment for specific nodes from a command line or in your QSF file:
        set_instance_assignment -name PRESERVE_FOR_DEBUG ON -to <node hpath>
      • Specify the Preserve signal for debug assignment To any node of interest in the Assignment Editor. Select On as the assignment value.
      Important: In some rare cases, logic might be optimized away before the signal can be preserved when you use the PRESERVE_FOR_DEBUG assignment. If you encounter this issue, use the preserve_for_debug attribute in your HDL code instead.
    • Mark a system module, interface, or port for preservation in Platform Designer.

      For details, refer to "Preserving a System Module, Interface, or Port for Debugging" in Quartus® Prime Pro Edition User Guide: Platform Designer.

  2. Enable preserve for debug either project-wide or for specific instances.
    • To enable preservation and reporting project-wide, do one of the following steps:
      • Enable project-wide signal preservation from the Signal Tap Logic Analyzer settings:

        Select Assignments > Settings > Signal Tap Logic Analyzer > Enable preserve for debug assignments.

      • Specify the global PRESERVE_FOR_DEBUG_ENABLE assignment from a command line or in your QSF file:
        set_global_assignment -name PRESERVE_FOR_DEBUG_ENABLE ON
      • Specify a global Enable preserve for debug assignments assignment in the Assignment Editor. Select On as the assignment value.
      Tip: When project-wide signal preservation and reporting is enabled, use the instance-level setting to exclude instances from project-wide signal preservation and reporting.
    • To enable (or disable) preservation and reporting for only specific instances:
      • Specify the instance PRESERVE_FOR_DEBUG_ENABLE assignment as ON (or OFF) from a command line or in your QSF file:
        set_instance_assignment -name PRESERVE_FOR_DEBUG_ENABLE ON -to <instance hpath>
      • Specify the Enable preserve for debug assignments assignment To any instance of interest in the Assignment Editor. Select On (or Off) as the assignment value.
      • Specify the PRESERVE_FOR_DEBUG_ENABLE attribute with a value of ON (or OFF) on the instance in your RTL.
        Table 7.  Examples of Setting the PRESERVE_FOR_DEBUG_ENABLE Attribute in RTL
        Verilog Example VHDL Example
        ...
        (* altera_attribute = "-name PRESERVE_FOR_DEBUG_ENABLE ON" *)
        decoder decoder_inst(
        ...
        ...
        attribute altera_attribute : string;   
        attribute altera_attribute of my_decoder_inst : LABEL is "-name PRESERVE_FOR_DEBUG_ENABLE ON";
        
        ...
        begin
        ...
        
        my_decoder_inst :  decoder
  3. Synthesize your design.

    On the Compilation Dashboard, click Analysis & Synthesis. The Compilation Report generates when synthesis is complete. You can also now use preserved for debug filters in Node Finder to help you quickly find preserved nodes.

  4. View the results of signal preservation.
    Open the Preserve for Debug Assignments report located in the Synthesis > Partition <name> > Preserve for Debug report folder.
    Figure 36. Preserve for Debug Assignments Report
  5. Run a full compilation to perform place and route of the design and Signal Tap instance by selecting Processing > Start Compilation.
    The debug signals that you preserve persist through the Fitter into the finalized compilation database.

After running a full compilation, you can debug your design with any of the Quartus® Prime debug tools.

Remember: After you have debugged your design, you might want to disable signal preservation (both globally and at the instance level) and run a full compilation to optimize signals that were preserved.
Table 8.  Debug Signal Preservation Assignments
Assignment Description Example
preserve_for_debug

(Preserve signal for debug in Assignments Editor)

Marks a signal to be preserved during compilation for post-synthesis or post-fit debugging when preserve-for-debug is enabled. set_instance_assignment -name PRESERVE_FOR_DEBUG ON -to <node hpath>
preserve_for_debug_enable

(Enable preserve for debug assignments in Assignments Editor)

Enables preserve-for-debug at either the project or instance level.

When enabled, the Compiler reports the results of signal preservation in the Preserve for Debug Assignments report after compilation.

The Compiler reports these nodes in the Preserve for Debug Assignments report following compilation.
set_global_assignment -name PRESERVE_FOR_DEBUG_ENABLE ON

set_instance_assignment -name PRESERVE_FOR_DEBUG_ENABLE ON -to <instance hpath>