8.9 Using Breakpoints

Besides the source code or address breakpoints demonstrated in the debugging section, the Intel Simics simulator provides several other types of breakpoints:

8.9.1 Overview of Breakpoints

These are some examples of breakpoints:

• Hardware events
  • memory access - break when an address range is accessed
  • register access - break when a device, bank, or special purpose register is accessed
  • target serial console - break when a string is output
  • target graphics console - break when a bitmap is shown
  • exceptions/interrupt - break when there is an exception or interrupt
• Simulation
  • time - break after a specified number of seconds, cycles, or steps
  • logs - break on a specific log message
• Target software
  • processes/threads - break when a process or thread becomes active or inactive
  • magic instruction - break when a magic instruction is executed

8.9.2 Finding Breakpoint Commands

To list breakpoint related commands, use the help command the Breakpoints category:

simics> help category:Breakpoints
...
<bp-manager.time>.break           set time breakpoint
<bp-manager.time>.run-until       run until specified time
<bp-manager.time>.trace           enable tracing of time points
<bp-manager.time>.wait-for        wait for specified time
...

In the shortened list of break commands above, note that there are different command types:

• break - create a breakpoint
• run-until - set a temporary breakpoint and run until this (or some other reason to stop) triggers
• trace - trace when the break condition is true
• wait-for - command specific to script-branches not described in this manual (see Simics User's Guide)

8.9.3 The Breakpoint Manager

Most breakpoint commands are implemented by the breakpoint manager, which is an object named bp. To list the different breakpoint types that the breakpoint manager implements, use bp.list-types:

simics> bp.list-types
┌───────────────────┬────────────────────────────────────────┐
│     Provider      │            Breakpoint type             │
├───────────────────┼────────────────────────────────────────┤
│bp.bank            │device access                           │
│bp.console_string  │target console string output breakpoints│
│bp.control_register│control register access breakpoints     │
│bp.cycle           │cycle queue breakpoints                 │
│bp.cycle_event     │cycle event breakpoints                 │
│bp.exception       │exception breakpoints                   │
│bp.gfx             │graphics console output breakpoints     │
│bp.hap             │hap occurrence breakpoints              │
│bp.log             │log message breakpoints                 │
│bp.magic           │magic breakpoints                       │
│bp.memory          │memory access breakpoints               │
│bp.notifier        │notifier trigger breakpoints            │
│bp.os_awareness    │OS Awareness breakpoints                │
│bp.source_line     │source code line breakpoints            │
│bp.source_location │source code location breakpoints        │
│bp.step            │step queue breakpoints                  │
│bp.step_event      │step event breakpoints                  │
│bp.time            │virtual time breakpoints                │
└───────────────────┴────────────────────────────────────────┘

A breakpoint created with bp.<type>.break is assigned a breakpoint identity, and this identity can be used to inspect or manipulate that specific breakpoint. These are some common commands:

• bp.delete
  delete a specific or all breakpoints
• bp.disable / bp.enable
  disable or enable a specific or all breakpoints
• bp.ignore-count
  ignore first x number of breakpoint triggers
• bp.show
  show all information about a breakpoint
• bp.list
  show brief information about all breakpoints
• bp.test-trigger
  manually trigger a breakpoint

8.9.4 Breakpoint Examples

Here follows a few examples of how to use breakpoints.

8.9.4.1 Execution Breakpoint

In this example, we set an execution breakpoint on a memory address.

• Launch of the qsp-x86/firststeps target:

  ./simics qsp-x86/firststeps
  simics> 
  

• Disassemble a couple of addresses:

  simics> disassemble count = 2
  cs:0x000000000000fff0 p:0x0fffffff0  nop
  cs:0x000000000000fff1 p:0x0fffffff1  nop
  

  Apparently, we will reach the address p:0xfffffff1. Let's set an execution breakpoint of this address.

• Set an execution breakpoint:

  simics> bp.memory.break -x address = p:0xfffffff1
  Breakpoint 3: break on 'x' access to 0xfffffff1 in board.mb.cpu0.mem[0][0]
  

  The breakpoint got the breakpoint identifier 3, probably since the target itself has created breakpoints.

• Check the status of the breakpoint:

  simics> bp.show 3
  Breakpoint 3 (board.mb.cpu0.mem[0][0] break matching (addr=0xfffffff1, len=1, access=x))
  ========================================================================================
  
           Enabled : True
      Ignore Count : 0
            Object : board.mb.cpu0.mem[0][0]
           Planted : True
          Region-0 : phys-x   0x00000000fffffff1 0x00000000fffffff1
           Oneshot : False
  

  From this, we can see that the breakpoint is planted on the memory object board.mb.cpu0.mem[0][0], has a length of 1, is enabled and has been planted.

• Run the simulation and observe that the breakpoint triggers.

  simics> run
  [board.mb.cpu0.mem[0][0]] Breakpoint 3: board.mb.cpu0.mem[0][0] 'x' access to p:0xfffffff1
  simics> disassemble
  cs:0x000000000000fff1 p:0x0fffffff1  nop
  

  The breakpoint text and disassemble reveals that we have reached the 0xfffffff1 address.

• We can also list information about all breakpoints, and can see that the breakpoint has triggered once (Hit count):

  simics> bp.list
  ┌──┬─────────────────────────────────────┬───────┬───────┬────────────┬─────────┐
  │ID│            Description              │Enabled│Oneshot│Ignore count│Hit count│
  ├──┼─────────────────────────────────────┼───────┼───────┼────────────┼─────────┤
  │ 1│Clock board.mb.cpu0.core[0][0] break │ true  │ false │           0│        0│
  │  │at time 5.0                          │       │       │            │         │
  ├──┼─────────────────────────────────────┼───────┼───────┼────────────┼─────────┤
  │ 2│Console 'board.serconsole.con' break │ true  │ false │           0│        0│
  │  │on "root.*@grml.*#.* " (regexp)      │       │       │            │         │
  ├──┼─────────────────────────────────────┼───────┼───────┼────────────┼─────────┤
  │ 3│board.mb.cpu0.mem[0][0] break        │ true  │ false │           0│        1│
  │  │matching (addr=0xfffffff1, len=1,    │       │       │            │         │
  │  │access=x)                            │       │       │            │         │
  └──┴─────────────────────────────────────┴───────┴───────┴────────────┴─────────┘
  

• Delete the breakpoint:

  simics> bp.delete id = 3
  

8.9.4.2 Exception Breakpoint

In this example, we will write an illegal instruction, and break on the exception that is raised when executing the illegal instruction.

• Launch of the qsp-x86/firststeps target:

  ./simics qsp-x86/firststeps
  simics> 
  

  From the earlier example, we know that the address p:0x0fffffff1 will be executed.

• Write an illegal instruction UD2 (0F 0B) to the physical address 0xfffffff1.

  simics> set address=0xfffffff1 value=0x0b0f size=2 -l
  

  We can now check the written instruction:

  simics> da address = p:0xfffffff1
  p:0x0fffffff1  ud2
  

• Plant an exception breakpoint:

  We will now use bp.exception.break to add an exception breakpoint on all (-all) exceptions.

  simics> bp.exception.break -all
  [board.mb.cpu0.core[0][0] info] VMP not engaged. Reason: hap installed on software interrupt.
  Breakpoint 3: Break on any exception for the following objects:
  board.mb.cpu0.core[0][0]
  

  We got breakpoint identity 3 and the breakpoint was planted on board.mb.cpu0.core[0][0]

• Run the simulation until the breakpoint triggers.

  simics> run
  [board.mb.cpu0.core[0][0]] Breakpoint 3: board.mb.cpu0.core[0][0] Invalid_Opcode_Exception(6) exception triggered
  

  The exception that triggered the breakpoint was Invalid_Opcode_Exception(6).

• Verify that the breakpoint has triggered by observing the Hit count value:

  simics> bp.show 3
  Breakpoint 3 (Break on any exception on the following objects:
  board.mb.cpu0.core[0][0])
  ==============================================================
  
           Enabled : True
      Ignore Count : 0
            Object : board.mb.cpu0.core[0][0]
           Planted : True
           Oneshot : False
  
  Hit Counts:
      hits : 1
  

8.9.4.3 Log Breakpoint

In this example, we will plant a temporary (-once) log breakpoint that triggers when the object board.mb.sb, or one of its child objects, logs an info log that contains the string lower. The selection of child objects is achieved with the -recursive flag.

• Launch of the qsp-x86/firststeps target:

  ./simics qsp-x86/firststeps
  simics> 
  

• Plant the breakpoint:

  simics> bp.log.break type = info object = board.mb.sb -recursive substr = "lower" -once
  Breakpoint 3: Break on 'info' log messages matching 'lower' from board.mb.sb hierarchy
  

• Observe the breakpoint properties:

  simics> bp.show 3
  Breakpoint 3 (Break on info log messages matching 'lower' from board.mb.sb hierarchy)
  =====================================================================================
  
           Enabled : True
      Ignore Count : 0
            Object : board.mb.sb
           Planted : True
           Oneshot : True
  
  Hit Counts:
      hits : 0
  

• To make sure that the info log is produced (so that our breakpoint is triggered), raise the log level to 3 on our board.mb.sb object and all of its child objects:

  simics> log-level object = board.mb.sb -r level = 3
  [board.mb.sb] Changing log level recursively: 1 -> 3
  

• Run the simulation until the breakpoint triggers:

  simics> run
  [board.mb.sb.lpc info] pin smi_pin lowered
  [board.mb.sb.lpc] Breakpoint 3: board.mb.sb.lpc log message of type info matching 'lower'
  @assert conf.board.mb.sb.lpc.log_buffer[-1][-1][-1][0] == "pin smi_pin lowered:"
  

  The breakpoint was triggered by the object board.mb.sb.lpc with the log message
  [board.mb.sb.lpc info] pin smi_pin lowered.

• Since the breakpoint was temporary (--once), the breakpoint should now have been automatically deleted:

  simics> bp.list
  ┌──┬────────────────────────────────┬───────┬───────┬────────────┬─────────┐
  │ID│          Description           │Enabled│Oneshot│Ignore count│Hit count│
  ├──┼────────────────────────────────┼───────┼───────┼────────────┼─────────┤
  │ 1│Clock board.mb.cpu0.core[0][0]  │ true  │ false │           0│        0│
  │  │break at time 5.0               │       │       │            │         │
  ├──┼────────────────────────────────┼───────┼───────┼────────────┼─────────┤
  │ 2│Console 'board.serconsole.con'  │ true  │ false │           0│        0│
  │  │break on "root.*@grml.*#.* "    │       │       │            │         │
  │  │(regexp)                        │       │       │            │         │
  └──┴────────────────────────────────┴───────┴───────┴────────────┴─────────┘