8.1.1. Execution Control

  c                           continue executing
  cont
  continue

  s     [count]               execute count instructions, default is 1
  step  [count]

  s     [cpu] [count]         for SMP simulation, execute count instructions on cpu, default is 1
  step  [cpu] [count]

  s     all [count]           for SMP simulation, execute count instructions on all cpus
  step  all [count]

  Ctrl-C                      stop execution, and return to command line prompt
  Ctrl-D                      if at empty line on command line, exit

  q                           quit debugger and execution
  quit
  exit

8.1.2. BreakPoints

  NOTE: The format of 'seg', 'off', and 'addr' in these descriptions,
        are as follows.  I don't have any way to set the current radix.

        hexidecimal:    0xcdef0123
        decimal:        123456789
        octal:          01234567

  vbreak seg:off              Set a virtual address instruction breakpoint
  vb     seg:off

  vbreak seg:off if "expr"    Set a conditional virtual address instruction breakpoint
  vb     seg:off if "expr"

  lbreak addr                 Set a linear address instruction breakpoint
  lb     addr

  lbreak addr if "expr"       Set a conditional linear address instruction breakpoint
  lb     addr if "expr"

  pbreak [*] addr             Set a physical address instruction breakpoint
  pb     [*] addr             (the '*' is optional for GDB compatibility)
  break  [*] addr
  b      [*] addr

  pbreak [*] addr if "expr"   Set a conditional physical address instruction breakpoint
  pb     [*] addr if "expr"   (the '*' is optional for GDB compatibility)
  break  [*] addr if "expr"
  b      [*] addr if "expr"

  info break                  Display state of all current breakpoints
  bpe    n                    Enable a breakpoint
  bpd    n                    Disable a breakpoint
  delete n                    Delete a breakpoint
  del    n
  d      n

8.1.3. Memory WatchPoints

  watch read  addr            Insert a read watch point at physical address addr
  watch r     addr            Insert a read watch point at physical address addr

  watch write addr            Insert a write watch point at physical address addr
  watch w     addr            Insert a write watch point at physical address addr

  watch                       Display state of current memory watchpoints

  watch stop                  Stop simulation when a watchpoint is encountered (default)
  watch continue              Do not stop simulation when a watchpoint is encountered

  unwatch addr                Remove watchpoint to specific physical address
  unwatch                     Remove all watch points

8.1.4. Manipulating Memory

  x  /nuf addr      Examine memory at linear address addr
  xp /nuf addr      Examine memory at physical address addr
     n              Count of how many units to display
     u              Unit size; one of
                      b Individual bytes
                      h Halfwords (2 bytes)
                      w Words (4 bytes)
                      g Giant words (8 bytes)
                      NOTE: these are *not* typical Intel nomenclature sizes,
                            but they are consistent with GDB convention.
     f              Printing format.  one of
                      x Print in hexadecimal
                      d Print in decimal
                      u Print in unsigned decimal
                      o Print in octal
                      t Print in binary

    n, f, and u are optional parameters.  u and f default to the last values
    you used, or to w(words) and x(hex) if none have been supplied.
    n currently defaults to 1.  If none of these optional parameters are
    used, no slash should be typed.  addr is also optional.  If you don't
    specify it, it will be the value the next address (as if you had
    specified n+1 in the last x command).

  setpmem addr datasize val    Set physical memory location of size
                               datasize to value val.

  writemem filename addr len   dump a number of bytes of virtual memory starting from
                               the specified linear address into a file

  loadmem filename addr        initialize virtual memory starting from the specified linear
                               address from a file

  deref addr deep              pointer dereference. For example: get value of [[[rax]]] or ***rax: deref rax 3

  crc  addr1  addr2            Show CRC32 for physical memory range addr1..addr2

8.1.5. Info commands

  r|reg|regs|registers         List of CPU integer registers and their contents
  fp|fpu                       List of all FPU registers and their contents
  mmx                          List of all MMX registers and their contents
  sse|xmm                      List of all SSE registers and their contents
  ymm|zmm                      List of all AVX registers and their contents
  sreg                         Show segment registers and their contents
  dreg                         Show debug registers and their contents
  creg                         Show control registers and their contents

  info cpu                     List of all CPU registers and their contents
  info eflags                  Show decoded EFLAGS register
  info break                   Information about current breakpoint status
  info tab                     Show paging address translation
  info idt                     Show contents of the IDT
  info gdt                     Show contents of the GDT
  info ldt                     Show contents of the LDT
  info device                  Show state of the specified device

8.1.6. Manipulating CPU Registers

  set reg = expr    Change a CPU register to value of expression.
                    Currently only general purpose registers and instruction pointer
                    are supported. You may not change eflags, segment registers,
                    floating point or SIMD registers.

    Examples: set eax = 2+2/2
              set esi = 2*eax+ebx

  registers         List of CPU registers and their contents
  regs
  reg
  r

  calc|? expr       Evaluate an expression and display the result.
                    'expr' can reference any general-purpose, opmask and segment
                    registers, use any arithmetic and logic operations, and also
                    special ':' operator which computes the linear address of a
                    segment:offset (in real and v86 mode) or of a selector:offset
                    (in protected mode) pair. Use $ operator for dereference,
                    for example, get value of [[[rax]]] or ***rax: rax$3.

8.1.7. Disassembly commands

  disassemble start end       Disassemble instructions in given linear address
                              range, inclusive of start, exclusive of end.
                              Use "set $disassemble_size =" to tell
                              debugger desired segment size.  Use a value for
                              end of less than start (or zero) if you only
                              want the first instruction disassembled.

  disassemble switch-mode     Switch between Intel and AT&T disassembly styles
                              for debugger disassembler.

  disassemble size = n        Tell debugger what segment size to use when
                              the "disassemble" command is used.  Use values
                              of 0, 16 or 32 for n.  Value of 0 means
                              "use segment size specified by current CS
                              segment". Default is 0.

  set $auto_disassemble = n   Cause debugger to disassemble current instruction
                              every time execution stops if n=1.  Default is 0.
                              Segment size of current CPU context is used for
                              disassembly, so the "disassemble size" variable is
                              ignored.

  set disassemble on          The same as 'set $auto_disassemble = 1'
  set disassemble off         The same as 'set $auto_disassemble = 0'

8.1.8. Instruction tracing

  trace on                    Disassemble every executed instruction. Note
                              that instructions which caused exceptions are
                              not really executed, and therefore not traced.

  trace off                   Disable instruction tracing.

  trace-mem on/off            Enable/Disable memory access tracing.

8.1.9. Instrumentation

To use instrumentation features in Bochs, you must compile in support for it. You should build a custom instrumentation library in a separate directory in the "instrument/" directory. To tell configure which instrumentation library you want to use, use the --enable-instrumentation option. The default library consists of a set of stubs, and the following are equivalent:

  ./configure [...] --enable-instrumentation
  ./configure [...] --enable-instrumentation="instrument/stubs"

  ./configure [...] --enable-instrumentation="instrument/myinstrument"

8.1.10. Instrumentation commands

  instrument [command]          calls BX_INSTR_DEBUG_CMD instrumentation callback with [command]
  instrument "[command string]" calls BX_INSTR_DEBUG_CMD instrumentation callback with [command string]

8.1.11. Other Commands

ptime

sb delta

sba time

print-stack [num words]

print-string addr

bt [num_entries]

source file

addlyt file

Example of use:

Create a script file (script.txt) with the following content

    regs
    print-stack 7
    u /10
    (*EMPTY NEW LINE)

Execute addlyt

addlyt "script.txt"

Then, when you execute a step/DebugBreak... you will see: registers, stack and disasm.

remlyt

lyt

modebp

ldsym [global] filename [offset]

The symbol file consists of zero or more lines of the format

"%x %s"

setmagicbps "cx dx bx sp bp si di"

  setmagicbps "di sp"

clrmagicbps "cx dx bx sp bp si di"

  clrmagicbps "di sp"

show [string]

  Toggles show symbolic info (calls to begin with).
  show - shows current show mode
  show mode     - show, when processor switch mode
  show int      - show, when interrupt is happens
  show call     - show, when call is happens
  show ret      - show, when iret is happens
  show off      - toggles off symbolic info
  show dbg-all  - turn on all show flags
  show dbg-none - turn off all show flags

8.1.12. Related links

For information on advanced debugger usage see the developer documentation (under construction).