Annotation of wikisrc/kernel_debugging_with_qemu.mdwn, revision 1.6

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

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