Intel® Simics® Simulator for Intel® FPGAs: User Guide

Download PDF
ID 784383
Date 7/08/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
Document Table of Contents x
1. About This Document 2. Intel® Simics® Simulator and Virtual Platforms 3. Intel® Simics® Simulator for Intel® FPGAs Device Portfolio 4. Installing the Intel® Simics® Simulator for Intel® FPGAs 5. Getting Started with Intel® Simics® Simulator 6. Debugging Target Software 7. Networking with the Simulated Target System 8. Intel® Simics® Scripting 9. Software Debug Examples with Intel® Simics® Simulator 10. Document Revision History for Intel® Simics® Simulator for Intel FPGAs User Guide A. Intel® Simics® Simulator Command Reference
1. About This Document x
1.1. Documentation Conventions for Examples 1.2. Terminology 1.3. List of Acronyms
2. Intel® Simics® Simulator and Virtual Platforms x
2.1. Device Model and Virtual Platforms 2.2. Intel® Simics® Simulator 2.3. Intel® Simics® Simulator Architecture
2.2. Intel® Simics® Simulator x
2.2.1. Intel® Simics® Simulator for Intel FPGAs Capabilities
4. Installing the Intel® Simics® Simulator for Intel® FPGAs x
4.1. Installing the Intel® Simics® Simulator for Intel® FPGAs on Linux* Systems 4.2. Installing the Intel® Simics® Simulator for Intel® FPGAs on Microsoft Windows* Systems 4.3. Installing Ashling* RiscFree* IDE for Intel® FPGAs 4.4. Intel® Simics® Simulator for Intel® FPGAs Support
5. Getting Started with Intel® Simics® Simulator x
5.1. Simulation Set Up 5.2. Starting the Simulation 5.3. Intel® Simics® Simulator Command-Line Interface (CLI) 5.4. Hardware Inspection 5.5. Intel® Simics® Simulator Timing
5.1. Simulation Set Up x
5.1.1. Initializing an Intel® Simics® Project and Deploying a Virtual Platform 5.1.2. Understanding Target Scripts
5.2. Starting the Simulation x
5.2.1. Starting a Simulation from a Command Prompt 5.2.2. Starting a Simulation with Ashling* RiscFree* IDE
5.3. Intel® Simics® Simulator Command-Line Interface (CLI) x
5.3.1. Version of the Intel® Simics® Simulator for Intel FPGAs Software 5.3.2. Simulation Run Control from CLI 5.3.3. Intel® Simics® Simulator Command Scope 5.3.4. Intel® Simics® Simulator CLI Variables and Operations 5.3.5. Intel® Simics® Simulator CLI Command Completion and Command History 5.3.6. Intel® Simics® Command-Line Interface Help 5.3.7. Capture of CLI Session to a File 5.3.8. Intel® Simics® Simulator File Location and Intel® Simics® Search Path
5.4. Hardware Inspection x
5.4.1. Listing Objects in the Target System 5.4.2. Processor (CPU) Inspection 5.4.3. Device Inspection 5.4.4. Memory Mapping and Memory Inspection 5.4.5. Logging
5.4.2. Processor (CPU) Inspection x
5.4.2.1. Listing Processors 5.4.2.2. Inspect Processor Registers
5.4.3. Device Inspection x
5.4.3.1. Retrieve List of Devices 5.4.3.2. Inspecting Device Registers
5.4.4. Memory Mapping and Memory Inspection x
5.4.4.1. Memory Mapping Inspection 5.4.4.2. Memory Inspection
5.4.5. Logging x
5.4.5.1. Breakpoints on CLI Log Messages
5.5. Intel® Simics® Simulator Timing x
5.5.1. CPU Frequency 5.5.2. CPU Cycles and Steps 5.5.3. Events 5.5.4. Enable Real Time
6. Debugging Target Software x
6.1. Intel® Simics® Debugger and Debug Context 6.2. Capturing Serial Console Output 6.3. Breakpoints 6.4. Debugging Target Software with Symbol Files 6.5. Debugging Target Software with Ashling* RiscFree* Debugger 6.6. Capturing CPU Instruction Execution Trace
6.3. Breakpoints x
6.3.1. Memory Breakpoints 6.3.2. Temporal Breakpoints 6.3.3. CPU Control Register Breakpoints 6.3.4. Hardware Access Breakpoints 6.3.5. CPU Register Breakpoints 6.3.6. Tracing Breakpoints 6.3.7. Text Console Activity Breakpoints
6.4. Debugging Target Software with Symbol Files x
6.4.1. Loading Symbol Files in a Simulation
6.5. Debugging Target Software with Ashling* RiscFree* Debugger x
6.5.1. Remote Debugging with RiscFree* IDE
6.5.1. Remote Debugging with RiscFree* IDE x
6.5.1.1. Remote Debugging With Intel® Simics® Simulation and RiscFree* IDE on the Same System 6.5.1.2. Remote Debugging With Intel® Simics® Simulation and RiscFree* IDE on Different Systems 6.5.1.3. Remote Access to the Target System Serial Console
7. Networking with the Simulated Target System x
7.1. Network Simulation and Service Node 7.2. Connectivity Between Host PC and Target System
7.2. Connectivity Between Host PC and Target System x
7.2.1. Port Forwarding 7.2.2. Transferring Files Between Host PC and Target System 7.2.3. Accessing Target System from Host PC Through HTTP 7.2.4. Networking Commands Reference Table
7.2.1. Port Forwarding x
7.2.1.1. Incoming Port Forwarding 7.2.1.2. Outgoing Port Forwarding
7.2.1.1. Incoming Port Forwarding x
7.2.1.1.1. Example of an SSH Connection with Incoming Port Forwarding
7.2.1.2. Outgoing Port Forwarding x
7.2.1.2.1. Example of SSH Connection With Outgoing Port Forwarding 7.2.1.2.2. Example of SSH Connection via NAPT
7.2.2. Transferring Files Between Host PC and Target System x
7.2.2.1. Transferring Files with SCP service 7.2.2.2. Transferring Files with TFTP service
7.2.2.1. Transferring Files with SCP service x
7.2.2.1.1. Transferring Files With SCP Service via Forwarding Ports 7.2.2.1.2. Transferring Files with SCP from Target System to Host PC via NAPT
7.2.2.2. Transferring Files with TFTP service x
7.2.2.2.1. TFTP Using Forwarding Port 7.2.2.2.2. TFTP via NAPT 7.2.2.2.3. TFTP Using TFTP Server in Intel® Simics® Service Node
8. Intel® Simics® Scripting x
8.1. Scripts in CLI
8.1. Scripts in CLI x
8.1.1. Variables 8.1.2. Command Return Values 8.1.3. Control Flow Commands 8.1.4. Local Variables 8.1.5. Integer Conversion 8.1.6. Accessing Configuration Parameters 8.1.7. Error Handling in Scripts 8.1.8. Script Branches
8.1.8. Script Branches x
8.1.8.1. Script Branches Commands 8.1.8.2. Variables in Script Branches 8.1.8.3. Branch Synchronization 8.1.8.4. Canceling Script Branches 8.1.8.5. Script Branches Restrictions
9. Software Debug Examples with Intel® Simics® Simulator x
9.1. Debugging Linux* User-Mode Application
9.1. Debugging Linux* User-Mode Application x
9.1.1. Debugging a Linux Application with GDB 9.1.2. Debugging a Linux Application with RiscFree* IDE
9.1.1. Debugging a Linux Application with GDB x
9.1.1.1. Debugging with GDB Debug from Host PC Using Forwarding Ports 9.1.1.2. Debugging with GDB from Host PC with Intel® Simics® Simulator GDB Server
1. About This Document
2. Intel® Simics® Simulator and Virtual Platforms
3. Intel® Simics® Simulator for Intel® FPGAs Device Portfolio
4. Installing the Intel® Simics® Simulator for Intel® FPGAs
5. Getting Started with Intel® Simics® Simulator
6. Debugging Target Software
7. Networking with the Simulated Target System
8. Intel® Simics® Scripting
9. Software Debug Examples with Intel® Simics® Simulator
10. Document Revision History for Intel® Simics® Simulator for Intel FPGAs User Guide
A. Intel® Simics® Simulator Command Reference

6.1. Intel® Simics® Debugger and Debug Context

Intel® Simics® tool is a full-system simulator that can run target software at any different level going from bootloaders to OS applications. When you want to debug a OS application, it is possible that there are some other pieces of software running in the background such as other software threads, other applications or kernel tasks. To limit the scope of your debugging to just one process (or task, or kernel thread, and so on), you use an appropriate debug context. Each debug context corresponds to some part of the target system. It can be a processor or the memory space of a processor, or a software abstraction like a process or thread. There are also debug contexts that group other contexts.

Currently, the debug context supported must be associated to the specific processor that is running the software to debug. In this case, you must be cautious as the debugger does not track when the operating system on the target switches between different processes or tasks.

To perform source-level debugging, you need to request the debugger about the binaries (executable files and shared libraries) that the component of the system you want to debug is using. The debugger presents the target system as a set of debug contexts. Each debug context represents one interesting part of the system. It can be a software concept (like a process, a thread or a task), or a processor core or the physical memory space of a processor. To provide context, there are also debug contexts that provide grouping like a machine or a group of all user-space programs on a Linux system.

When you interact with debug contexts directly, you usually interact with a context running code, such as a thread or a processor core. The debug context allows you to step through the code and to inspect variables scoped to the current location in the code.

By default, Intel® Simics® simulator does not activate the debugger; global stepping and other commands act directly over the current processor selected, and not to a specific debug context. There are two ways to activate the debugger and get access to debug contexts.

  1. To enable the debugger with the enable-debugger command. This makes Intel® Simics® debugger to track debug contexts and automatically select an initial debug context if possible (current core selected).
  2. To explicitly select a debug context with the debug-context command. This sets a current debug context and also activates the debugger.

You can disable the debugger with the disable-debugger command and Intel® Simics® simulator returns to the default behavior of the global stepping commands.

Once Intel® Simics® debugger tracks debug contexts, it updates the current debug context to the currently running thread every time the simulation stops. The current debug context is the debug context that all global step and inspection commands interacts with. This means that when you have hit a breakpoint or complete a step, you can use the global commands to investigate the state of your software and to continue stepping through the code.

Once you have a debug context and symbols file loaded (described later in this document), you can use it to step through the code and inspect its state. When the debugger is enabled, and you have a current debug context, you can use the global versions of these commands. The commands are also implemented directly by the debug context, which means that you can use them on debug contexts different to the current debug context. You can do this even if the debugger is disabled.

There are some commands that can only operate if a context is defined. Some examples of these commands are the following:

Table 17.   Intel® Simics® Debugger and Debug Context Commands
Command Description
step-line Run forward until the debug context reaches another line in the program.
next-line Run forward until the debug context reaches another line but skip over calls made by the current function.
finish-function Run forward until the current function returns.
next-instruction Run forward until the debug context reaches another instruction but skip over calls made by the current function.
list List source code.

An active thread also has a stack of call frames or just frames. Intel® Simics® simulator provides commands to show the stack and to select which frame other commands must use to find local variables. The stack goes from the innermost frame up towards the outermost frame. The current stack frame is reset to the innermost frame every time Intel® Simics® simulator stops executing. Some of the commands that operate over call frames are the following. To use these commands, you must have a context defined.

Table 18.  Commands to Show the Stack and Select Frame
Command Description
stack-trace Shows the stack.
frame Selects the frame with the given number. The currently executing function has frame 0, its caller has frame 1, and so on.
up Selects the frame with the next higher number.
down Selects the frame with the next lower number.

The following capture shows an example of how you can set a debug context and use some of the instructions described above: 

# Intel Simics simulator CLI  

simics> list-debug-contexts 
Fully Qualified Name                        
-------------------------------------------------------------
/system                                                   
/system/board.fpga.soc_inst.hps_subsys.agilex_hps.core[0] 
/system/board.fpga.soc_inst.hps_subsys.agilex_hps.core[1] 
/system/board.fpga.soc_inst.hps_subsys.agilex_hps.core[2] 
/system/board.fpga.soc_inst.hps_subsys.agilex_hps.core[3] 
/system/board.fpga.soc_inst.hps_subsys.agilex_hps.cpu_mem[0]
/system/board.fpga.soc_inst.hps_subsys.agilex_hps.cpu_mem[1]
/system/board.fpga.soc_inst.hps_subsys.agilex_hps.cpu_mem[2]
/system/board.fpga.soc_inst.hps_subsys.agilex_hps.cpu_mem[3]

simics> enable-debugger
Debugger enabled.

simics> debug-context
dbg0 (the arm-cortex-a55 system.board.fpga.soc_inst.hps_subsys.agilex_hps.core[0])
Now debugging the arm-cortex-a55 system.board.fpga.soc_inst.hps_subsys.agilex_hps.core[0]
??()
                                                   str w0, [x18, #340]
simics> next-instruction
                                                   cmp x0, x19

simics> debug-context object = "system.board.fpga.soc_inst.hps_subsys.agilex_hps.core[1]"
dbg5 (the arm-cortex-a55 system.board.fpga.soc_inst.hps_subsys.agilex_hps.core[1])
Now debugging the arm-cortex-a55 system.board.fpga.soc_inst.hps_subsys.agilex_hps.core[1]
??()
                                                   b 0x28
simics> debug-context
dbg5 (the arm-cortex-a55 system.board.fpga.soc_inst.hps_subsys.agilex_hps.core[1])
simics> step-line
                                                  bl 0x80000108
simics> next-instruction
                                                  adr x0, 0x8000a800
simics> step-line
                                                  msr vbar_el3, x0
simics>  debug-context dbg0
dbg0 (the arm-cortex-a55 system.board.fpga.soc_inst.hps_subsys.agilex_hps.core[0])
Now debugging the arm-cortex-a55 system.board.fpga.soc_inst.hps_subsys.agilex_hps.core[0]
??()
                                                  msr cptr_el3, x19
simics> stack-trace 
#0 0x80008b30 in ??()
#1 0xffff800008026a34 in ??()
#2 0xffff800008d9d768 in ??()

In the previous example, the following operations are executed:

  • Initially, the debug-context command is called and when doing this, the command response indicates that there is not any debug context selected.
  • The list-debug-contexts command is called and shows possible debug contexts that you can select, including CPU cores and memories.
  • The debugger gets enabled using the enable-debugger command. When doing this, the default debug context is selected which corresponds to the current core selected, which is core[0]. This debug context is referred to as dbg0.
  • The next-instruction command is used to advance in the simulation using core[0] as debug target.
  • You switch to the core[1] context using debug-context command. The debug context is provided with the path of this core. This debug context is referred to as dbg5.
  • You advance in the simulation again using the next-instruction and step-line which act over the core[1] this time. These commands show the current assembler instruction.
  • Finally, you return to the core[0] context using the debug-context command. This time, this command is used providing the debug context name dbg0 instead of the core[0] path. You can also print the current stack using the stack-trace command.
Level Two Title