qemu/roms/seabios/docs/Debugging.md

   1 This page describes the process of obtaining diagnostic information
   2 from SeaBIOS and for reporting problems.
   3
   4 Diagnostic information
   5 ======================
   6
   7 SeaBIOS has the ability to output diagnostic messages. This is
   8 implemented in the code via calls to the "dprintf()" C function.
   9
  10 On QEMU these messages are written to a special debug port. One can
  11 view these messages by adding '-chardev stdio,id=seabios -device
  12 isa-debugcon,iobase=0x402,chardev=seabios' to the QEMU command line.
  13 Once this is done, one should see status messages on the console.
  14
  15 On coreboot these messages are generally written to the "cbmem"
  16 console (CONFIG_DEBUG_COREBOOT). If SeaBIOS launches a Linux operating
  17 system, one can obtain the cbmem tool from the coreboot repository and
  18 run "cbmem -c" to view the SeaBIOS diagnostic messages.
  19
  20 Additionally, if a serial port is available, one may compile SeaBIOS
  21 to send the diagnostic messages to the serial port. See the SeaBIOS
  22 CONFIG_DEBUG_SERIAL option.
  23
  24 Trouble reporting
  25 =================
  26
  27 If you are experiencing problems with SeaBIOS, it's useful to increase
  28 the debugging level. This is done by running "make menuconfig" and
  29 setting CONFIG_DEBUG_LEVEL to a higher value. A debug level of 8 will
  30 show a lot of diagnostic information without flooding the serial port
  31 (levels above 8 will frequently cause too much data).
  32
  33 To report an issue, please collect the serial boot log with SeaBIOS
  34 set to a debug level of 8 and forward the full log along with a
  35 description of the problem to the SeaBIOS [mailing list](Mailinglist).
  36
  37 Timing debug messages
  38 =====================
  39
  40 The SeaBIOS repository has a tool (**scripts/readserial.py**) that can
  41 timestamp each diagnostic message produced. The timestamps can provide
  42 some additional information on how long internal processes take. It
  43 also provides a simple profiling mechanism.
  44
  45 The tool can be used on coreboot builds that have diagnostic messages
  46 sent to a serial port. Make sure SeaBIOS is configured with
  47 CONFIG_DEBUG_SERIAL and run the following on the host receiving serial
  48 output:
  49
  50 `/path/to/seabios/scripts/readserial.py /dev/ttyS0 115200`
  51
  52 Update the above command with the appropriate serial device and baud
  53 rate.
  54
  55 The tool can also timestamp the messages from the QEMU debug port. To
  56 use with QEMU run the following:
  57
  58 ```
  59 mkfifo qemudebugpipe
  60 qemu -chardev pipe,path=qemudebugpipe,id=seabios -device isa-debugcon,iobase=0x402,chardev=seabios ...
  61 ```
  62
  63 and then in another session:
  64
  65 `/path/to/seabios/scripts/readserial.py -nf qemudebugpipe`
  66
  67 The mkfifo command only needs to be run once to create the pipe file.
  68
  69 When readserial.py is running, it shows a timestamp with millisecond
  70 precision of the amount of time since the start of the log. If one
  71 presses the "enter" key in the readserial.py session it will add a
  72 blank line to the screen and also reset the time back to zero. The
  73 readserial.py program also keeps a log of all output in files that
  74 look like "seriallog-YYYYMMDD_HHMMSS.log".
  75
  76 Debugging with gdb on QEMU
  77 ==========================
  78
  79 One can use gdb with QEMU to debug system images. To do this, add '-s
  80 -S' to the qemu command line. For example:
  81
  82 `qemu -bios out/bios.bin -fda myfdimage.img -s -S`
  83
  84 Then, in another session, run gdb with either out/rom16.o (to debug
  85 bios 16bit code) or out/rom.o (to debug bios 32bit code). For example:
  86
  87 `gdb out/rom16.o`
  88
  89 Once in gdb, use the command `target remote localhost:1234` to have
  90 gdb connect to QEMU. See the QEMU documentation for more information
  91 on using gdb and QEMU in this mode.
  92
  93 When debugging 16bit code it is necessary to load the 16bit symbols
  94 twice in order for gdb to properly handle break points.  To do this,
  95 run the following command `objcopy --adjust-vma 0xf0000 out/rom16.o
  96 rom16offset.o` and then run the following in gdb:
  97
  98 ```
  99 set architecture i8086
 100 add-symbol-file rom16offset.o 0
 101 ```
 102
 103 To debug a VGA BIOS image, run `gdb out/vgarom.o`, create a
 104 vgaromoffset.o file with offset 0xc0000, add use the gdb
 105 command `add-symbol-file out/vgaromoffset.o 0` to load the 16bit VGA
 106 BIOS symbols twice.
 107
 108 If debugging the 32bit SeaBIOS initialization code with gdb, note that
 109 SeaBIOS does self relocation by default. This relocation will alter
 110 the location of initialization code symbols. Disable
 111 CONFIG_RELOCATE_INIT to prevent SeaBIOS from doing this.