Debugging the Virtual Target Simulation with Intel® Debug Extensions for WinDbg* - 2422 - ID:648476

Intel® System Debugger User Guide

ID 648476

Date 06/13/2024

Version

Confidential

Debugging the Virtual Target Simulation with Intel(R) Debug Extensions for WinDbg*

This chapter describes set-up and configuration of Intel(R) Debug Extensions for WinDbg* over Simics® so you can perform basic debugging operations.

Prerequisites

Simics(R) tool installation with the relevant platform packages installed (access Simics(R) Package Manager for a GUI app for installation)
- If you are using an Intel cloud infrastructure, you should have access to an installation with the appropriate packages.
WinDbg over Intel® DCI <.. _windbg_get_started:>’’ (included in the ISD release)
The following environment variables need to be configured:
- The Simics® host IP address and port number where the Target Communication Framework* (TCF) agent is listening should be set as an environment variable called TCF_PORT, e.g., 10.252.43.128:20006.
  To determine this port number in a GUI initiated target, see the section Environment setup for local debugging.

Environment setup for local debugging

After Simics(R) target instance has started up, type tcf.status in the console prompt. The output should be similar to the following:

simics> tcf.status
Status of tcf [class tcf-agent]

Backend Started : True

TCF Peer Properties:
   AgentID : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    Host : 127.0.0.1
    Name : Simics
    OSName : Windows 10.0
    Port : 53702
    ...
    ...
simics>

The localhost address and port number indicated here should be set as an environment variable called TCF_PORT, e.g. 127.0.0.1:53702.

Environment setup for remote debugging

Setup in the remote Simics(R) host

Note:

<SIMICS BASE PROJECT DIRECTORY> refers to the chosen base directory where the Simics projects are created. This example is written using ADL-S as an example. The directory structure is mirrored in other targets. <PLATFORM PACKAGE> refers to the package name of the target you are running, e.g. simics-adl-6.0.pre293.

Determine the network IP address of the host using ipconfig or ifconfig. This IP should be used as a parameter to start the TCF agent. For this example, let us suppose it is 10.252.43.128 and the chosen port is 20006. Please confirm the chosen port is not being used by any other application.

Create a new startup script (e.g., <SIMICS BASE PROJECT DIRECTORY>\<SIMICS PROJECT NAME>\adl-s.simics) as follows:

# **Target Startup Script**
start-eclipse-backend ``TCP:10.252.43.128:20006``
#$artifactory = FALSE
#$local_storage = TRUE
#read-configuration <NAME OF CHECKPOINT>
run-command-file ``<SIMICS INSTALLATION PATH>\\<PLATFORM PACKAGE>\\targets\\adl\\adl-s.simics``
$sim_fail_on_warnings = FALSE

Note:

If using a checkpoint to start your target, confirm the checkpoint’s directory is in the <SIMICS BASE PROJECT DIRECTORY><SIMICS PROJECT NAME> directory (or in the location indicated in the read-configuration command) and uncomment line 5 and comment out line 6 in the startup script.

Open a command prompt. Navigate to the directory where the target files are installed and start the target type:

cd <SIMICS BASE PROJECT DIRECTORY>\<SIMICS PROJECT NAME>
simics ``<SIMICS BASE PROJECT DIRECTORY>\\<SIMICS PROJECT NAME>\\targets\\adl\\adl-s.simics``

Note:

After an initial execution, when the images retrieved from Artifactory have already been downloaded, lines 3 and 4 can be uncommented.

Setup in the debugging host

The Simics(R) host IP address and TCF agent port number used above should be set as an environment variable called TCF_PORT, e.g., 10.252.43.128:20006.

Execution

Navigate to the installation root directory and run isd_shell.bat (for Windows* OS host)
In the opened command line, set TCF agent port number (considering local or remote debugging scenario): a) local debugging: set TCF_PORT=127.0.0.1:53702 b) remote debugging set TCF_PORT=10.252.43.128:20006
From the same command line, launch windbg over SIMICS by: windbg_simics

Reverse Execution

Warning: Debugging with reverse execution use is slower than with forward execution.

Target preparation

A Simics target with remote execution support is needed. For this, run the following command from the Simics CLI or, in case you are starting the target with a Simics script, insert the following line:

enable-reverse-execution

Set bookmarks at a point in time close to the period you wish to debug:

set-bookmark <name_of_bookmark>

Note:

The bookmark should be set before the beginning of the time period over which you wish to debug.

Reverse execution WinDbg commands

To enable reverse stepping:

!re

or:

.exdicmd target:<core number>:reverse on

Then, for each step execute:

For reverse execution (reverse go):

To turn off stepping in reverse:

!rd

or

.exdicmd target:<core number>:reverse off

Example console output

0: kd> u
fffff803`43b0ac43 48c1e220        shl     rdx,20h                          <-------- **present instruction**
fffff803`43b0ac47 480bc2          or      rax,rdx
fffff803`43b0ac4a c3              ret
fffff803`43b0ac4b cc              int     3
fffff803`43b0ac4c cc              int     3
fffff803`43b0ac4d cc              int     3
fffff803`43b0ac4e cc              int     3
fffff803`43b0ac4f cc              int     3
0: kd> p
fffff803`43b0ac47 480bc2          or      rax,rdx                          <-------- **one forward step**
0: kd> !re                                                                 <-------- **reverse stepping enabled**
Target command response: Revexe enabled
exdiCmd: The function: 'reverse on' was completed.
0: kd> p
fffff803`43b0ac43 48c1e220        shl     rdx,20h                          <-------- **one reverse step**
0: kd> u
fffff803`43b0ac43 48c1e220        shl     rdx,20h                          <-------- **we are back to initial instruction**
fffff803`43b0ac47 480bc2          or      rax,rdx
fffff803`43b0ac4a c3              ret
fffff803`43b0ac4b cc              int     3
fffff803`43b0ac4c cc              int     3
fffff803`43b0ac4d cc              int     3
fffff803`43b0ac4e cc              int     3
fffff803`43b0ac4f cc              int     3
0: kd> p
fffff803`43b0ac40 0f01f9          rdtscp                                   <-------- **now one instruction before the start of debugging**
0: kd> !rd                                                                 <-------- **reverse stepping disabled**
Target command response: Revexe disabled
exdiCmd: The function: 'reverse off' was completed

0: kd> u
fffff803`43b0ac40 0f01f9          rdtscp
fffff803`43b0ac43 48c1e220        shl     rdx,20h
fffff803`43b0ac47 480bc2          or      rax,rdx
fffff803`43b0ac4a c3              ret
fffff803`43b0ac4b cc              int     3
fffff803`43b0ac4c cc              int     3
fffff803`43b0ac4d cc              int     3
fffff803`43b0ac4e cc              int     3
0: kd> p
fffff803`43b0ac43 48c1e220        shl     rdx,20h                          <-------- **stepping forward**
0: kd> p
fffff803`43b0ac47 480bc2          or      rax,rdx                          <-------- **stepping forward**
0: kd> !re                                                                 <-------- **reverse stepping enabled**
Target command response: Revexe enabled
exdiCmd: The function: 'reverse on' was completed.

0: kd> p 3                                                                 <-------- **multiple steps in reverse**
fffff803`43b0ac43 48c1e220        shl     rdx,20h
fffff803`43b0ac40 0f01f9          rdtscp
fffff803`43ba6451 ffe0            jmp     rax                              <-------- **reverse through to calling function**

Note:

“Simics is a trademark of Intel Corporation or its subsidiaries.”