Annotation of wikisrc/kernel_debugging_with_qemu.mdwn, revision 1.11

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

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