Annotation of wikisrc/kernel_debugging_with_qemu.mdwn, revision 1.9

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.5       gson       29: Check out the NetBSD-current sources from CVS and build a full
                     30: NetBSD-current/i386 release with debug symbols using the build.sh
                     31: script.  The i386 port is the preferred test platform because the two
                     32: other ports supported by anita are affected by known bugs: amd64 by
                     33: [[PR 49276|http://gnats.NetBSD.org/49276]], and sparc by
                     34: [[qemu bug 1335444|https://bugs.launchpad.net/qemu/+bug/1335444]].
1.2       wiki       35: 
1.5       gson       36: If you do the build in a directory other than /usr/src, 
                     37: use the -fdebug-prefix-map option to ensure that the source file names embedded
                     38: in the debug symbols point to /usr/src, which is where the sources will be
                     39: installed on the target system.  For example:
1.2       wiki       40: 
1.3       wiki       41: [[!template  id=programlisting text="""
1.5       gson       42:  $ CVSROOT=anoncvs@anoncvs.NetBSD.org:/cvsroot cvs checkout -A -P src
                     43:  $ cd src
                     44:  $ ./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       45: """]]
                     46: 
1.5       gson       47: For best performance, change the number after "-j" to the number of CPU cores
                     48: you have, or slightly more.
                     49: 
                     50: ## Installing the target system
1.3       wiki       51: 
1.5       gson       52: Install the system in a virtual machine, including the debug symbols and source code:
1.3       wiki       53: 
                     54: [[!template  id=programlisting text="""
1.5       gson       55:  $ cd ..
                     56:  $ anita --workdir work --disk-size 4G --memory-size 256M \
                     57:      --sets kern-GENERIC,modules,base,etc,comp,debug,games,man,misc,tests,text,syssrc,src,sharesrc,gnusrc \
                     58:      install $(pwd)/obj/releasedir/i386/
                     59: """]]
1.3       wiki       60: 
1.5       gson       61: ## Booting the VMs
1.3       wiki       62: 
1.5       gson       63: Next, start two qemu virtual machines, one to run the kernel being
1.9     ! gson       64: debugged (the "target VM") and another to run gdb (the "gdb VM").
1.3       wiki       65: 
1.8       gson       66: The two VMs could be run on separate physical machines, but in this
1.5       gson       67: example, they are run on the same physical machine and share the same
                     68: hard disk image.  This sharing is made possible by the "-snapshot"
                     69: option to qemu, which ensures that the disk image is not written to by
                     70: either VM.
1.3       wiki       71: 
1.9     ! gson       72: First start the target VM, enabling qemu's built-in GDB target stub
1.5       gson       73: on TCP port 1234:
1.3       wiki       74: 
                     75: [[!template  id=programlisting text="""
1.5       gson       76:  $ qemu-system-i386 -nographic -snapshot -hda work/wd0.img -gdb tcp::1234
1.3       wiki       77: """]]
                     78: 
1.5       gson       79: If you don't want everyone on the Internet to be able to debug your
                     80: target, make sure incoming connections on port 1234 are blocked in
                     81: your firewall.
1.3       wiki       82: 
1.9     ! gson       83: In a second terminal window, start the gdb VM:
1.3       wiki       84: 
                     85: [[!template  id=programlisting text="""
1.5       gson       86:  $ qemu-system-i386 -nographic -snapshot -hda work/wd0.img
1.3       wiki       87: """]]
                     88: 
1.9     ! gson       89: Log in to the gdb VM as root and set up the network:
1.3       wiki       90: 
                     91: [[!template  id=programlisting text="""
1.5       gson       92:  login: root
                     93:  # dhcpcd
1.3       wiki       94: """]]
                     95: 
1.9     ! gson       96: Start gdb on the gdb VM and connect to the target:
1.3       wiki       97: 
                     98: [[!template  id=programlisting text="""
1.5       gson       99:  # gdb /netbsd
                    100:  (gdb) target remote my.host.name:1234
1.3       wiki      101: """]]
1.2       wiki      102: 
1.5       gson      103: where my.host.name is the domain name or IP address of the
1.9     ! gson      104: host system.
1.5       gson      105: 
                    106: Now you should be able to get a stack trace and start debugging
                    107: with full debug symbols and access to the source code:
1.2       wiki      108: 
1.5       gson      109: [[!template  id=programlisting text="""
                    110:  (gdb) where
                    111:  (gdb) list
                    112: """]]
1.2       wiki      113: 
1.5       gson      114: If the stack trace prints very slowly (like 30 seconds per stack
                    115: frame), it's likely because you are using a version of qemu where
                    116: the user-mode networking code fails to disable the Nagle algorithm.
                    117: This is fixed in the qemu in pkgsrc, but you may run into it if your
                    118: qemu is not installed via pkgsrc.
1.2       wiki      119: 
1.5       gson      120: ## Qemu tips
1.2       wiki      121: 
1.5       gson      122: Here is a couple of useful qemu commands to know:
1.1       wiki      123: 
1.5       gson      124: * Ctrl-a b will send a break which will make the NetBSD VM enter the ddb kernel debugger.
1.3       wiki      125: 
1.5       gson      126: * Ctrl-a c will switch to the qemu monitor where you can enter commands like "quit" to exit qemu,
                    127: or do things like saving/restoring the VM to/from a file.

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