Annotation of wikisrc/kernel_debugging_with_qemu.mdwn, revision 1.13

1.1       wiki        1: # Introduction
                      2: 
1.5       gson        3: This HOWTO explains how to set up a test environment for symbolic
                      4: debugging of the NetBSD kernel using a pair of QEMU virtual machines.
1.1       wiki        5: 
1.5       gson        6: ## Prerequisites
1.3       wiki        7: 
1.5       gson        8: You need a computer running an OS capable of cross-building NetBSD
                      9: (the "host system").
1.6       gson       10: This can be NetBSD itself, Linux, or some other Unix-like OS.
1.5       gson       11: These instructions have been tested with NetBSD/amd64 6.1.4 and
1.7       gson       12: Debian 7 hosts.   There should be at least 20 gigabytes of available
                     13: disk space.
1.1       wiki       14: 
1.5       gson       15: If your host system is running NetBSD, install the following packages
                     16: from pkgsrc:
1.1       wiki       17: 
1.5       gson       18: * emulators/qemu >= 2.0.0nb4
                     19: * misc/py-anita
1.2       wiki       20: 
1.5       gson       21: If your host system uses a package system other than pkgsrc,
                     22: use that to install cvs, make, gcc, qemu, the Python pexpect
                     23: library, and genisoimage or mkisofs.  Also download and 
                     24: install the most recent anita package from
                     25: <http://www.gson.org/netbsd/anita/download/>.
1.1       wiki       26: 
1.5       gson       27: ## Building the target system
1.1       wiki       28: 
1.12      gson       29: Check out the NetBSD-current sources from CVS and build a full release
                     30: of NetBSD-current/i386 with debug symbols using the build.sh script.
1.13    ! gson       31: The i386 port is preferred because these instructions have been 
        !            32: successfully tested with it.
        !            33: The amd64 port won't work because of [[PR 50128|http://gnats.NetBSD.org/50128]],
        !            34: and sparc has not been tested since [[qemu bug
        !            35: 1399943|https://bugs.launchpad.net/qemu/+bug/1399943]] was fixed.
        !            36: 
1.5       gson       37: If you do the build in a directory other than /usr/src, 
                     38: use the -fdebug-prefix-map option to ensure that the source file names embedded
                     39: in the debug symbols point to /usr/src, which is where the sources will be
                     40: installed on the target system.  For example:
1.2       wiki       41: 
1.3       wiki       42: [[!template  id=programlisting text="""
1.5       gson       43:  $ CVSROOT=anoncvs@anoncvs.NetBSD.org:/cvsroot cvs checkout -A -P src
                     44:  $ cd src
                     45:  $ ./build.sh -j 4 -V MKDEBUG=YES -V COPTS="-g -fdebug-prefix-map=$(pwd)=/usr/src" -O ../obj -m i386 -U release sourcesets
1.3       wiki       46: """]]
                     47: 
1.5       gson       48: For best performance, change the number after "-j" to the number of CPU cores
                     49: you have, or slightly more.
                     50: 
                     51: ## Installing the target system
1.3       wiki       52: 
1.5       gson       53: Install the system in a virtual machine, including the debug symbols and source code:
1.3       wiki       54: 
                     55: [[!template  id=programlisting text="""
1.5       gson       56:  $ cd ..
                     57:  $ anita --workdir work --disk-size 4G --memory-size 256M \
                     58:      --sets kern-GENERIC,modules,base,etc,comp,debug,games,man,misc,tests,text,syssrc,src,sharesrc,gnusrc \
                     59:      install $(pwd)/obj/releasedir/i386/
                     60: """]]
1.3       wiki       61: 
1.5       gson       62: ## Booting the VMs
1.3       wiki       63: 
1.5       gson       64: Next, start two qemu virtual machines, one to run the kernel being
1.9       gson       65: debugged (the "target VM") and another to run gdb (the "gdb VM").
1.3       wiki       66: 
1.8       gson       67: The two VMs could be run on separate physical machines, but in this
1.5       gson       68: example, they are run on the same physical machine and share the same
                     69: hard disk image.  This sharing is made possible by the "-snapshot"
                     70: option to qemu, which ensures that the disk image is not written to by
                     71: either VM.
1.3       wiki       72: 
1.9       gson       73: First start the target VM, enabling qemu's built-in GDB target stub
1.5       gson       74: on TCP port 1234:
1.3       wiki       75: 
                     76: [[!template  id=programlisting text="""
1.5       gson       77:  $ qemu-system-i386 -nographic -snapshot -hda work/wd0.img -gdb tcp::1234
1.3       wiki       78: """]]
                     79: 
1.5       gson       80: If you don't want everyone on the Internet to be able to debug your
                     81: target, make sure incoming connections on port 1234 are blocked in
                     82: your firewall.
1.3       wiki       83: 
1.9       gson       84: In a second terminal window, start the gdb VM:
1.3       wiki       85: 
                     86: [[!template  id=programlisting text="""
1.5       gson       87:  $ qemu-system-i386 -nographic -snapshot -hda work/wd0.img
1.3       wiki       88: """]]
                     89: 
1.9       gson       90: Log in to the gdb VM as root and set up the network:
1.3       wiki       91: 
                     92: [[!template  id=programlisting text="""
1.5       gson       93:  login: root
                     94:  # dhcpcd
1.3       wiki       95: """]]
                     96: 
1.9       gson       97: Start gdb on the gdb VM and connect to the target:
1.3       wiki       98: 
                     99: [[!template  id=programlisting text="""
1.5       gson      100:  # gdb /netbsd
                    101:  (gdb) target remote my.host.name:1234
1.3       wiki      102: """]]
1.2       wiki      103: 
1.5       gson      104: where my.host.name is the domain name or IP address of the
1.9       gson      105: host system.
1.5       gson      106: 
                    107: Now you should be able to get a stack trace and start debugging
                    108: with full debug symbols and access to the source code:
1.2       wiki      109: 
1.5       gson      110: [[!template  id=programlisting text="""
                    111:  (gdb) where
                    112:  (gdb) list
                    113: """]]
1.2       wiki      114: 
1.5       gson      115: If the stack trace prints very slowly (like 30 seconds per stack
                    116: frame), it's likely because you are using a version of qemu where
                    117: the user-mode networking code fails to disable the Nagle algorithm.
                    118: This is fixed in the qemu in pkgsrc, but you may run into it if your
                    119: qemu is not installed via pkgsrc.
1.2       wiki      120: 
1.5       gson      121: ## Qemu tips
1.2       wiki      122: 
1.5       gson      123: Here is a couple of useful qemu commands to know:
1.1       wiki      124: 
1.5       gson      125: * Ctrl-a b will send a break which will make the NetBSD VM enter the ddb kernel debugger.
1.3       wiki      126: 
1.5       gson      127: * Ctrl-a c will switch to the qemu monitor where you can enter commands like "quit" to exit qemu,
                    128: or do things like saving/restoring the VM to/from a file.

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb