1: # Introduction
2:
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.
5:
6: ## Prerequisites
7:
8: You need a computer running an OS capable of cross-building NetBSD
9: (the "host system").
10: This can be NetBSD itself, Linux, or some other Unix-like OS.
11: These instructions have been tested with NetBSD/amd64 6.1.4 and
12: Debian 7 hosts. There should be at least 20 gigabytes of available
13: disk space.
14:
15: If your host system is running NetBSD, install the following packages
16: from pkgsrc:
17:
18: * emulators/qemu >= 2.0.0nb4
19: * misc/py-anita
20:
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/>.
26:
27: ## Building the target system
28:
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.
31: 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 50128|http://gnats.NetBSD.org/50128]], and sparc by
34: [[qemu bug 1399943|https://bugs.launchpad.net/qemu/+bug/1399943]].
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:
39:
40: [[!template id=programlisting text="""
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
44: """]]
45:
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
50:
51: Install the system in a virtual machine, including the debug symbols and source code:
52:
53: [[!template id=programlisting text="""
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: """]]
59:
60: ## Booting the VMs
61:
62: Next, start two qemu virtual machines, one to run the kernel being
63: debugged (the "target VM") and another to run gdb (the "gdb VM").
64:
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.
70:
71: First start the target VM, enabling qemu's built-in GDB target stub
72: on TCP port 1234:
73:
74: [[!template id=programlisting text="""
75: $ qemu-system-i386 -nographic -snapshot -hda work/wd0.img -gdb tcp::1234
76: """]]
77:
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.
81:
82: In a second terminal window, start the gdb VM:
83:
84: [[!template id=programlisting text="""
85: $ qemu-system-i386 -nographic -snapshot -hda work/wd0.img
86: """]]
87:
88: Log in to the gdb VM as root and set up the network:
89:
90: [[!template id=programlisting text="""
91: login: root
92: # dhcpcd
93: """]]
94:
95: Start gdb on the gdb VM and connect to the target:
96:
97: [[!template id=programlisting text="""
98: # gdb /netbsd
99: (gdb) target remote my.host.name:1234
100: """]]
101:
102: where my.host.name is the domain name or IP address of the
103: host system.
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:
107:
108: [[!template id=programlisting text="""
109: (gdb) where
110: (gdb) list
111: """]]
112:
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.
118:
119: ## Qemu tips
120:
121: Here is a couple of useful qemu commands to know:
122:
123: * Ctrl-a b will send a break which will make the NetBSD VM enter the ddb kernel debugger.
124:
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