HDL Debugging

Learn how to use HDL debugging tools inside Active-HDL

www.aldec.com

Debugging • Active-HDL provides several mechanisms for efficient HDL code

debugging and viewing design interconnects: Syntax Checking - performed with every Compile command

On the fly error detection and code navigation – Using Code Browser

Code Tracing - HDL code is executed either statement-by-statement or traced by processes, subprograms, and procedures

Value Verification - variable values are displayed in additional watch, List, and Memory View windows

Activity Status – active processes are displayed in the Processes window

Off-line Simulation – the Post Simulation Debug mode allows observing simulation results saved to a file after the simulation has been finished

Design Interconnects - statements, port maps, connections, instances are displayed in the Advanced Dataflow window

XTrace – helps to find the unknown values throughout the design

2

www.aldec.com

Debug Setup • Before you start debugging a

source code, you have to perform some initial procedures: Set up a design and add all required

files.

Generate an HDL description for any block diagram and state machine.

Compile source files into a working library to perform syntax check

Start debugging the source code

3

www.aldec.com

Debugging Restriction • Active-HDL allows you to debug the source code of your design

that has been compiled into a working library.

• However, the components stored in some standard libraries provided with Active-HDL software do not contain the original source code. Instead, they contain the headers for the pre-compiled code that you will not be able to debug.

4

www.aldec.com

Code Browser – Navigation • You can open Code Browser

using button from toolbar or by clicking Code Browser option from View menu. The Code Browser represents the

structure of source code being currently open in the HDL Editor window and allows conveniently navigating through source code.

Double-clicking an item in the Code Browser scrolls the HDL Editor window and places the insertion point in the corresponding line of code.

5

www.aldec.com

Code Browser – Error detection • While editing source file

when you save it, Code Brower analyzes the code on-the-fly and displays the error messages before compilation of the file

• Code analysis performed by the Code Browser identifies the following issues: syntax errors

Missing object declaration

expression type mismatch

6

Currently Code Browser is VHDL only

www.aldec.com

Syntax Checking • After you execute the Compile command and errors occur, a list of

errors is displayed in the Console window.

• Each error is displayed with additional information: name of the source file

internal error number

line & column number location of the error in the code

a short description of the error

7

www.aldec.com

Searching for Errors • The Console window is tightly

integrated with the HDL Editor. Double-clicking any error message will

take you directly to the HDL Editor window with the source of an error.

The line is also underscored with a red wavy line and a red marker is placed to the left of the line.

Resting the pointer over the underscored line for a second, pulls up a tooltip with error descriptions.

We can review the history of issued commands in the Console window by using the navigation keys (the up or down arrow key). They can be recalled very quickly and then re-executed by pressing Enter.

8

www.aldec.com

Preferences • The Preferences window

allows you to customize the way the debugger works:

• Select one of the two options for tracing state machine code: trace the original state machine

trace HDL code generated from a state machine

• Separate component instances view

• Set the display options for vectors and numbers

9

www.aldec.com

Code Tracing • You can trace the HDL source code statement-by-statement. There

are four functions that allow you to trace the code: Trace into - executes a single HDL statement. If a subprogram call is

encountered, the execution descends into the subprogram body.

Trace over - executes a single HDL command. If a subprogram call is encountered, the statements contained within the subprogram body are executed in a single step.

Trace out - executes as many HDL statements as are required to complete the execution of a subprogram. If subprograms are nested, the command completes the execution of the innermost subprogram only.

Trace over transition - executes as many HDL statements as are required to perform a transition between states.

10

www.aldec.com

Code Tracing • To trace the code, click the trace buttons. The currently executed

line is highlighted in yellow.

To improve source debugging, you can also set multiple: code breakpoints

signal breakpoints

11

Note: Breakpoints stop the

debugging process.

www.aldec.com

Simulation Breakpoints • Breakpoints allow you to stop the verification process when some

desired condition(s) occurred. All processes are suspended and signal values are displayed in the Watch window.

12

To set a breakpoint, hit the F9 key or choose the Toggle Breakpoint option from the pop-up menu.

NOTE: The HDL Editor allows inserting breakpoints only in these lines that contain appropriate constructs, e.g. statements containing assignments, expressions, etc.

www.aldec.com

Breakpoint Editor • The Breakpoint Editor allows manual toggling of the breakpoints.

Moreover, you can add signal breakpoints on signals that you want to trace.

13

• You can select which breakpoints should be active when debugging the design.

• You can also set the signal breakpoints by specifying the following conditions: Event

Transaction

Value

www.aldec.com

Edit Condition breakpoint • In the Edit Condition dialog box you can

specify that the scope of the code breakpoint should be limited only for the specified design region (Instance) or the breakpoint should pause the simulation only when it is hit for the nth time (Hit Count).

• The simulation can be paused when the specified line is executed or specified signal meets the specified conditions (break always); when the breakpoint hit count is less than (break when less), equal (break when equal), or greater than (break when greater), or when it is and integer multiple of (break when multiple of) the value specified in the Hit Count field.

14

NOTE: Instance can be specified only for code breakpoints.

www.aldec.com

“when” command • The when command allows you to specify commands that should

be executed when a certain condition is met.

• A condition expression can include VHDL signals, transactions on VHDL signals, Verilog registers, Verilog nets and the following operators: = (equivalent to ==), /=, and, and or.

• When the condition is met and the commands assigned to it are executed, the simulation stops. If you want the simulation to continue, terminate the command list with the run command.

• Please, open the fifo design. It contains a simple model of FIFO with ‘almost full’ and ‘almost empty’ signals.

15

www.aldec.com

“when” command • Execute the runme.do macro. This macro sets up three when

commands.

when {DATA_IN=16#00} {echo"'00' value is not allowed."}

• This command breaks simulation and prints information in the console when value “00” is asserted on the input data bus of the FIFO.

16

www.aldec.com

“when” command • Two remaining commands are used to force data on the DATA_IN

data bus.

when -label AF {AF=1 and CLK_FIFO=1} {echo "Fifo almost

full";

force WR 0;

force DATA_IN ZZZZZZZZ;

run -all}

• This command assigns “0” value to the WR port and “Z” value to the DATA_IN port when the FIFO is almost full (AF=1).The run -all command allows you to continue simulation.

17

www.aldec.com

“when” command when -label AE {AE=1 and CLK_FIFO=1} {

echo "Fifo almost empty";

force -freeze WR 0 0ns 1 4ns 0 8ns -r 16ns;

force -freeze DATA_IN -r 10ns -dist uniform -seed 0 -start 0

-end 255;

run -all }

• This command assigns stimulators to the WR and DATA_IN ports when the FIFO is almost empty (AE=1). The run -all command allows you to continue simulation.

18

www.aldec.com

FSM Debugging

• All the Trace commands are active during the debugging. Therefore, you can trace an execution of any statement in the HDL code and observe its influence on the model’s behavior.

• The Trace over Transition option executes the source code to the point where the next transition takes place.

19

• To trace state machines, you need to generate their corresponding HDL code. The State Machine Editor highlights the currently active state in yellow.

www.aldec.com

FSM Debugging

• To set a breakpoint select desired state and choose the Breakpoint option from the pop-up menu.

• To mark that a breakpoint is set on a state, the state symbol is distinguished by double-line border.

20

• You can also set breakpoint on the specified state of the state machine. It allows you to stop simulation when the specified state is reached.

www.aldec.com

Verifying Results • You can use additional tools while tracing HDL code that will help

you to verify the design’s overall responses.

Active-HDL comes with the following interactive windows: Watch – displays the current signal, variable, or generic value

List – displays results in a tabular format

Waveform – displays graphical results in a form of signal waves

Processes – displays the process status in the current simulation cycle

Call Stack – displays a list of sub-programs being currently executed and their parameters

Memory View – displays the memory contents

Advanced Dataflow – displays flat or hierarchical interconnects of a design

Note: You can open each window by choosing an appropriate option from the

View or File | New menu.

21

www.aldec.com

Watch Window • To find the last or current signal value, you may use the Watch

window. The Watch window displays values of selected signals (including ports) and variables.

The window is divided into several columns that show: Names

types of the selected objects

current value

last value

Event

last event time

Note: The red exclamation mark means that an event occurred on the marked signal in the current simulation cycle.

22

www.aldec.com

Adding signals to Watch Window • All signals viewed in the Watch window can be dragged and

dropped from the Design Browser window or the Waveform window. You can also drag a signal name from the HDL source code itself. To add the signal from the HDL code, highlight the signal name.

Drag the signal to the Watch window.

Note: You can change signal display options in the Preferences window by choosing the Display options from the pop-up menu.

23

www.aldec.com

List Window • The List window displays all results in a tabular form.

(This window is used only as a viewer of simulation results)

• Each signal is represented by a column with corresponding event times. The window can display signal values in two ways: For all simulation cycles executed for the specified time step.

Only for the last simulation cycle within the specified time step.

Note: You can toggle the delta display using the button.

24

www.aldec.com

Delta Cycle Handling • The Active-HDL simulator uses delta cycles to simulate the design.

• A delta time is an infinitesimally small amount of time that represents a time greater than zero, but it is zero when added to a discrete amount of time. Thus, if a signal assignment is made at time "100ns + 1delta time" and the model discrete delay is 10ns, the new signal value is assigned at 100ns + 10ns + 0 delta time = 110ns. This is because the 1 delta time * 1 = 0ns.

• The number of delta delays reflects the number of events that take place in particular simulation cycles.

25

www.aldec.com

Adding signals to List

• To add the signal from the Design Browser, select the entity in the Structure tab and drag it to the List window.

• To add signals using the Add Signals window, click the show signal browser button and select the signals. Close the window by clicking the Close button.

26

• All signals viewed in the List window can be dragged and dropped here, from the Design Browser window, Watch window and Waveform window. You can also use the Add signals window.

www.aldec.com

Memory View • The Memory View window is a debugging tool that has been

designed to display the contents of memories defined in a design (e.g. objects of the two-dimensional array type).

• The Memory View window allows you to view objects as if they were memory cells. The memory contents are presented in the window as a table of the defined number of columns and rows.

27

www.aldec.com

Adding signals Memory View

Select the desired object on the Structure tab of the Design Browser and use pop-up menu option Add to Memory View

You can also use drag-and-drop technique to add objects displayed in Waveform Editor, Watch etc.

28

• Open Memory View window using the button on the main toolbar or use Memory View option from the File | New menu after simulation has been initialized.

www.aldec.com

Memory View Properties

• If you want to watch only part of your memory you may specify the memory address range (in the Start and End fields) for cells displayed in the memory grid.

• Aliases option allows you to display memory cells using user-friendly mnemonics instead of hexadecimal or binary numbers.

29

• The Memory View window is fully customizable.

• You can change the display radix for the memory address and memory words using Radix options ( available from the Tool bar or the Memory View Properties window).

www.aldec.com

Searching Memory Contents

• Press the Forward or Backward button. Focus will be moved to the cell contains searching value.

• To go to specified address using the Memory View Go to window, click the button.

• Type in desired address in the Address edit box, select address radix and press the Go To button. Focus will be moved to specified address

30

• To search through the memory contents, click the button on the Toolbar. It opens the Memory View Find window.

• Type in value you want to find in the Value to Search edit box.

• Select the starting point for searching using the From option.

www.aldec.com

Editing Memory Variables • You can change variable values in the Memory View window for a

current simulation run. To change a variable value, select the cell in the Memory View window and

double click on it.

Now you can type the new cell value.

NOTE: To change the memory contents you can also use the change macro

command.

31

www.aldec.com

Saving Memory to File

• To save the contents of the selected memory: Choose Save or Save As option from

the File menu.

You can also use the save button or write mem macro command.

The Memory View file will be added to the design as a resource, if you leave the Automatically add new file to design option selected in the Save Memory View file window.

32

• The memory displayed in the Memory View window can be saved in the native Aldec Memory File format (*.mem), Intel HEX format file (*.hex), and Altera or Xilinx Memory Initialization File (*.mif) formats.

www.aldec.com

Aldec Memory File format

• In the Save options dialog you can specify: the range of memory cells that will

be saved to the output file.

notation of memory word values.

tabs or spaces to be used as column separators.

to skip addresses in the generated output file.

33

• When you choose to save the memory data to the Aldec Memory File(*.mem), you will be prompted to specify additional settings in the Save options dialog box.

www.aldec.com

Processes Window • The Processes window displays a list of processes in the elaborated

model along with their current status. This window is available only while the simulator is running.

Each concurrent statement that is modeling a sequential process is represented in the window. There are: process statements

concurrent signals assignment statements

concurrent assertion statements

concurrent procedure call statements

34

Note: For processes without explicit labels, the compiler generates default labels that show the line number of the source file in which a process is located (e.g., line__15).

www.aldec.com

Processes Window • A process listed in the Process window can have one of the

following statuses: Ready - indicates that the process is scheduled to be executed within the current

simulation cycle.

Wait - indicates that the process is suspended and is waiting to be resumed.

• The Processes window can show either: All processes in the selected region of the elaborated design, irrespective of their

status in the current simulation cycle.

Only active processes in the selected region of the elaborated design (those scheduled to be executed within the current simulation cycle).

Note: In addition, you can choose a region of the design whose processes you want to

trace.

35

www.aldec.com

Call Stack Window • The Call Stack window is a debugging tool that displays a list of

subprograms (procedures and functions) and variables being currently executed.

36

• For each subprogram, the window displays the following information: Formal parameters along with

their actual values.

Variables, constants and files declared locally in subprogram bodies along with their current values.

Note: The Call Stack window is available only while the simulator is running.

www.aldec.com

Variables • You can change variable values in the Call Stack window for a

current simulation run.

37

• To change a variable value, click within the Call Stack window.

• Now click the variable value and type the new value.

Note: You can also change the variable value in the lower part of Design

Browser following the same steps.

www.aldec.com

Advanced Dataflow • The Advanced Dataflow window (View | Advanced Dataflow) is

a tool that allows designers to explore the connectivity of a design and analyze dataflow among instances, statements, signals/nets, and registers during simulation.

• The hierarchical or flat dataflow diagram displayed by the Advanced Dataflow may be especially helpful while tracing events propagating through the entire project and identifying those that may be potential sources of unexpected output values.

• The Advanced Dataflow Viewer displays design interconnects in one of two modes: Hierarchical

Flat

38

www.aldec.com

Advanced Dataflow • In the Flat mode, statements, port maps, signals/nets from all units

on all hierarchy levels are flattened and displayed as a single-level diagram. Each object displayed in the window has a reference pointing to its full path within the design hierarchy. Placing the cursor over the symbol, brings up the tooltip that displays detailed information on the object (name, hierarchy path, value, and type of a signal or port, etc.).

39

www.aldec.com

Advanced Dataflow • The Hierarchical mode displays instances along with information

on the design hierarchies and library paths. Instances are displayed within frames that outline HDL statements and signals/nets forming design units that are connected to other symbols via port maps.

40

www.aldec.com

Advanced Dataflow • A primary purpose of Advanced Dataflow is to allow exploring the

connectivity of a design and enable tracing events propagating through the entire project, which may help identify sources of unexpected outputs.

• It allows expanding the view from one process to another and watch drivers and readers of a particular signal or net.

• The connectivity of the design can be expanded by using the commands from the pop-up menu: Expand Net

Expand Net to Readers

Expand Net to Drivers

X Way

41

www.aldec.com

Advanced Dataflow • Expand Net

Displays drivers and readers of the selected signal, net, or register

• Expand Net to Readers Displays readers of the selected signal, net, or register

• Expand Net to Drivers Display drivers of the selected signal, net, or register

• X Way Expands recursively the selected net through the design in order to find the source of

X or U value.

42

www.aldec.com

Advanced Dataflow • Regardless of the selected working mode, the Advanced Dataflow

window is always synchronized with Advanced Dataflow Trace.

43

• The Advanced Dataflow Trace option is designed for: Displaying detailed information

on design objects (signals/nets, their types, values, and hierarchy, instances, statements, port maps, etc.) selected in the Advanced Dataflow window

Finding signals/nets, instances, and HDL statements displayed within the current data flow

diagram

www.aldec.com

XTrace • The xtrace command creates a report with information on

unknown values in the simulated model. By default, XTrace generates a report for the X, U, and -(Don't care) values. It is, however, possible to XTrace other values of the std_logic type.

44

• XTrace monitors the specified signals and provides exact information on the time of unknown value occurrence, hierarchy path and if necessary drivers contributing to the affected signal.

• To enable the XTrace monitoring on all signals in the design switch to the Structure tab, select top level unit and use the Xtrace|Xtrace On... option from the Simulation menu. The Xtrace Options window will be open.

www.aldec.com

XTrace Option The XTrace Options dialog box (Image on next page) allows you to

specify the settings of

the XTrace session.

• The Reports option specifying the path and name of the report file and the format of the report file.

• The XTrace Conditions section defines the operating conditions for XTrace.

• The Console Messages allows you to specify how XTraced signals will be reported in the Console window.

• The XTrace Report Parameters determines whether to add to the report information about simulation time and drivers of the signals experiencing an X value.

45

www.aldec.com

XTrace Option 46

www.aldec.com

Adding Signals to the XTrace session 47

• To add signals to the current session: Select the desired object on the

Structure tab of the Design Browser

Use option Xtrace|Xtrace Add... from the pop-up menu or the Simulation menu.

In the XTrace Options window press OK button.

Note: All options specified at the beginning of the XTrace session apply to signals being added.

www.aldec.com

Disabling XTrace session • To disable the XTrace session press the button on the XTrace

toolbar or use the Xtrace|Xtrace Disable option from the Simulation menu.

• To enable the XTrace session once again press the button or use the Xtrace|Xtrace Disable option.

• You can also switch off XTrace using the button or the Xtrace|Xtrace Off option from the Simulation menu.

48

www.aldec.com

XTrace and Advanced Dataflow • The XTrace can be used in conjunction with the Advanced Dataflow

to effectively find the causes of unknown values. To enable the XTrace to Advanced Dataflow cross probing, initialize the simulation, select the top-level unit and use the Xtrace|Xtrace On option from the Simulation menu. In the XTrace Options window select the Stop Simulation when an X Occurs check box and the Advanced Dataflow check box (it turns on the cross probing).

• Run the simulation and once you observe in Console window XTrace message:

# XTRACE: 160ps UUT/I1/O x

• Double click on this line will add the signal with X value to the Advanced Dataflow view where you can explore the design connectivity to find the source of the unknown value.

49

www.aldec.com

XTrace and Advanced Dataflow • In the figure on the right it is clearly

visible that the cause of an X on the output O of the AND2 module is the X value on BUST signal connected to I0 input. To list all the driving processes in the console window you can use the List Drivers option from the context menu.

50

The XWay used on the BUST signal will recursively expand the net with unknown values to show the ‘real’ source of problem.

www.aldec.com

XTrace & source code cross probing • The XTrace also supports the message cross probing to the HDL

source of the unknown values. To enable it, use the Xtrace|Xtrace On option from the Simulation menu. In the XTrace Options window select the HDL Source check box (it turns on the cross probing).During the simulation run messages in the Console window will be sensitive to double click, and will take you to the source code which caused the unknown value on the signal.

51

www.aldec.com

Signal Agent • The Signal Agent allows monitoring and driving VHDL signals that

do not have to be routed via the interface or declared in global packages, which is particularly useful in testbench development and design verification. To use the signal_agent procedure, insert the following library and use clauses:

library aldec;

use aldec.signal_agent_pkg.all;

• The Signal Agent joins a source signal with a destination signal. The source drives the destinations as if the signals were connected directly in a simulated model. The signal_agent procedure (stored in the signal_agent_pkg package in the pre-installed aldec library) needs to be called only once. All changes on the source signal will then be transferred to the destination signal.

52

www.aldec.com

Signal Agent • In the signalagent sample design uses the signal_agent procedure

to monitor the 4 signals buried deep in the design hierarchy. The /uut/u2/fullsignal drives the full2 signal located at the top-level region of the design.

• Monitoring the /uut/u2/full signal without the signal_agent task requires routing the signal through the interface of each block or defining it in a global package.

architecture beh of testbench is signal full1, full2, full3 :STD_LOGIC;

begin

signal_agent ( "/uut/u2/full","full2",1 );

...

stimulus: process is

begin

--...

--...

end process stimulus;

end architecture beh;

53

www.aldec.com

Follow Object • The Follow Object option allows users to follow objects in the

simulated design. An object to be followed can be a signal/net or process/always modeled by statements in the simulated design.

54

• To follow the selected signal/net or process you should: Initialize the simulation and then

point to the signal/net name or process label (identifier).

Right-click on object's identifier or on the keyword representing an object (e.g. if a process has no label).

www.aldec.com

Follow Object • Choose the object that you want to follow from the Follow Object

list. After it has been selected, an appropriate document window is open with the line of HDL code distinguished by the sign or with the highlighted object, e.g. wire, bus, or terminal.

55

www.aldec.com

Post Simulation Debug • Post-Simulation Debug is a powerful feature that enables users to

trace the simulation results after simulation has been finished.

56

• In order to enable this feature we do the following: Check the Save full signal history box

and select the signals for post-simulation debugging.

Check Preserve file with signal history for Post Simulation Debug box on the Trace/Debug category of the Design Settings window and specify the file in the File with simulation results field. (this option is for standard waveform only, use

.asdb for Accelerated Waveform)

www.aldec.com

Post Simulation Debug 57

• Run the simulation for the desired time.

• To initialize simulation in the Post Simulation Debug mode, select the Simulation | Initialize Post Simulation Debug menu command

• The post-simulation data for the chosen signals will be saved in the *.psd file specified in the Design Settings window.

• Perform the post-simulation by running the simulation for the desired time.