Subject: Converted kgdb.list to kgdb.xml and some questions
To: None <netbsd-docs@netbsd.org>
From: None <dsieger@techfak.uni-bielefeld.de>
List: netbsd-docs
Date: 04/03/2007 19:57:50
--lrZ03NoBR/3+SXJZ
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Hi all.
I converted htdocs/Documentation/kernel/kgdb.list to DocBook/XML
today. The resulting .xml file as well as a small patch to actually
build it is attached.
[1] notes there is a list2xml script that can be used for converting
.list files to XML. Unfortunately, the htutils repository seems not to
accessible for the average user. So, would it be possible to include
this script in htdocs rather than htutils? htutils/templates seems to
be another reasonable candidate for being accessible for everyone.
Furthermore, do we have some scripts/tools do indent newly
created/converted XML files properly?
Regards,
Daniel
[1]: http://www.netbsd.org/developers/htdocs.html#convert-to-xml
--
Daniel Sieger
Faculty of Technology
Bielefeld University
wwwhomes.uni-bielefeld.de/dsieger
--lrZ03NoBR/3+SXJZ
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="kgdb.xml"
<?xml version="1.0"?>
<!DOCTYPE webpage
PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
"http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
<webpage id="Documentation-kernel-kgdb">
<config param="desc" value="NetBSD Documentation: Debugging the NetBSD kernel with GDB HOWTO"/>
<config param="cvstag" value="$NetBSD: $"/>
<config param="rcsdate" value="$Date: $"/>
<head>
<!-- Copyright (c) 1994-2007
The NetBSD Foundation, Inc. ALL RIGHTS RESERVED. -->
<title>NetBSD Documentation: Debugging the NetBSD kernel with GDB HOWTO</title>
</head>
<sect1 role="toc">
<sect2 id="using_kgdb">
<title>Using KGDB</title>
<sect3 id="introduction">
<title>Introduction</title>
<para>
Although the DDB debugger that can be included with the NetBSD
kernel is useful for gathering crash tracebacks, examining the
values of variables, and other minor debugging tasks, if
you're doing serious kernel hacking you'll want to setup to
work with the remote debugger, KGDB, instead.</para>
<para>
The advantage of KGDB over DDB is that you can step through
the <emphasis>source code</emphasis> of the kernel, rather
than through disassembled machine code. As a matter of fact,
nearly all GDB facilities work, including any of the various
graphical frontends for gdb (eg -
<filename>devel/ddd</filename>).</para>
</sect3>
<sect3 id="prerequisites">
<title>Prerequisites</title>
<itemizedlist>
<listitem>
<para>Two machines of the same architecture (including
object code format)both running NetBSD:</para>
<itemizedlist>
<listitem>
<para>TARGET - the machine that will be running the
debug kernel</para>
</listitem>
<listitem>
<para>REMOTE - the machine that will run/display
gdb</para>
</listitem>
</itemizedlist>
<para>It is possible to build gdb hosted on one
architecture and targeted for another, but that is
currently beyond the scope of this document.
</para>
</listitem>
<listitem>
<para>A free serial port on each machine.</para>
</listitem>
<listitem>
<para>A null modem cable (see the <ulink
href="../../Documentation/Hardware/Misc/serial.html">NetBSD
Serial Port Primer</ulink> for more information).</para>
</listitem>
<listitem>
<para>Knowledge of how to build and install a kernel, and
how to use gdb.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="instructions">
<title>Instructions</title>
<para>In the following, we will assume that you'll be using
<filename>/dev/tty01</filename> on the REMOTE machine (the
one running gdb) and <filename>/dev/tty00</filename> on the
TARGET (the one being debugged). You may need to substitute
the correct devices for the serial ports for your hardware,
eg. <filename>/dev/dty00</filename>.</para>
<orderedlist>
<listitem>
<para>Build a kernel with KGDB enabled</para>
<para>(NOTE: It may be best to build the kernels on the
REMOTE machine. That way all the proper source and
symbol files are already there when it comes time to
debug.)</para>
<itemizedlist>
<listitem>
<para>Comment out the following lines in the kernel
config file for the TARGET machine:</para>
<programlisting>
#options DDB # in-kernel debugger
#options DDB_HISTORY_SIZE=100 # enable history editing</programlisting>
<para>and uncomment (or add) the following three
lines:</para>
<programlisting>
options KGDB # remote debugger
options "KGDB_DEVNAME=\"com\"",KGDB_DEVADDR=0x3f8,KGDB_DEVRATE=9600
makeoptions DEBUG="-g" # compile full symbol table</programlisting>
<para>Change KGDB_DEVADDR to match the IO address of
the serial port you will use on the TARGET (0x3f8 is
tty00, 0x2f8 is tty01), and KGDB_DEVRATE to match
the serial bitrate you want to use.</para>
</listitem>
<listitem>
<para>Configure and <ulink
href="./#how_to_build_a_kernel">build the
kernel</ulink> for the TARGET.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Prepare the TARGET machine</para>
<para>Copy the file <filename>netbsd</filename> from the
kernel build directory to the root directory of the
TARGET machine. <emphasis role="bold">DO NOT INSTALL
THIS KERNEL ON THE REMOTE MACHINE</emphasis> (especially
if you're using the same tty on both machines!).</para>
</listitem>
<listitem>
<para>Prepare the REMOTE machine</para>
<itemizedlist>
<listitem>
<para>If you built the kernel on the TARGET machine,
make a copy of all of
<filename>/usr/src/sys</filename> from there to the
REMOTE machine. (Note: you can't just NFS-mount the
directory from the TARGET! When gdb hits a
breakpoint, <emphasis>everything</emphasis> on the
TARGET will stop, including
<application>nfsd</application>!)</para>
</listitem>
<listitem>
<para>Change the line in
<filename>/etc/ttys</filename> for the tty you plan
to use on the REMOTE machine (and
<emphasis>only</emphasis> the REMOTE) to something
like:</para>
<programlisting>
tty01 "/usr/libexec/getty std.9600" unknown off local</programlisting>
<para>The important parts here are <quote>off</quote>
(so that init won't run getty on the port) and
<quote>local</quote>. This is because
<application>ttyflags</application> sets up the
defaults for the port according to
<filename>/etc/ttys</filename> at boottime, and gdb
requires <quote>local</quote> to be set so that it
doesn't wait for DTR.</para>
<para>You may also want to change the
<quote>std.9600</quote> to a different bitrate - it
should match the rate you set in the kernel options
for the TARGET as well as the remotebaudrate you set
in gdb (below). Make sure there is actually an entry
in <filename>/etc/gettytab</filename> to match the
name you give here.</para>
</listitem>
<listitem>
<para>Reboot the REMOTE machine, or otherwise have
<application>ttyflags</application> run and reread
<filename>/etc/ttys</filename>. (<command>kill -1
1</command> may be sufficient, although init can get
confused by a change in the ordering of items in
<filename>/etc/ttys</filename>).</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Connect the serial ports with the null modem
cable.</para>
</listitem>
<listitem>
<para>Reboot the TARGET, and hit the space bar as soon
as the boot loader message comes up. Enter the following
command:</para>
<programlisting>
boot -d</programlisting>
<para>This will cause the kernel to load, after which
the message <quote>waiting for kgdb</quote> will be
printed, and the TARGET will stop.</para>
</listitem>
<listitem>
<para>On the REMOTE machine, cd to the directory where
you built the kernel (usually
<filename>/usr/src/sys/arch/<something>/compile/<config-name></filename>)
and run <command>gdb</command>:</para>
<screen>&rprompt; <userinput>gdb netbsd.gdb</userinput></screen>
<para>After a couple seconds of churning, you will get
the (gdb) prompt.</para>
</listitem>
<listitem>
<para>setup a couple gdb flags:</para>
<programlisting>
# this one lets you stop the TARGET any time with Ctrl-C
(gdb) set remotebreak 1
# this sets the baudrate gdb will use (default 9600,
# MUST match the setting in the kernel installed on the TARGET)
(gdb) set remotebaud 9600
# this one speeds up retransmissions of debugger
# commands when there is a line error on the serial
(gdb) set remotetimeout 3</programlisting>
</listitem>
<listitem>
<para>Connect to the TARGET machine (assuming you're using
tty01 on the REMOTE):</para>
<programlisting>
target remote /dev/tty01</programlisting>
<para>You should be greeted with something like the
following:</para>
<programlisting>
Remote debugging using /dev/tty01
kgdb_connect (verbose=1) at ../../../../arch/i386/i386/kgdb_machdep.c:244
244 if (verbose)
(gdb)</programlisting>
<para>If GDB instead appears to <quote>hang</quote>, you
may have something wrong with your serial hardware,
cable, or settings. See the troubleshooting section
below.</para>
</listitem>
<listitem>
<para>If you did get a prompt back, then you're ready to
hack - you can set breakpoints, examine data, single
step, etc, just like gdb'ing a userlevel application
running on the local machine! To continue with the
kernel boot process, use <command>cont</command>, and
to pop back into the debugger at a later time, hit
Ctrl-C.</para>
</listitem>
<listitem>
<para>To automate steps 5 - 7, create a file called
<filename>.gdbinit</filename> in the kernel build
directory containing the following lines:</para>
<programlisting>
file netbsd.gdb
set remotebreak 1
set remotebaud 9600
target remote /dev/tty01</programlisting>
<para>Now you can start debugging by just typing
<command>gdb</command>.</para>
</listitem>
</orderedlist>
</sect3>
<sect3 id="troubleshooting">
<title>Troubleshooting</title>
<para>If things don't work, try some of these:</para>
<itemizedlist>
<listitem>
<para>Reboot the TARGET without specifying
<option>-d</option>. You should see a message similar to
the following one displayed in the device probes. If you
don't see the second line, either you didn't get KGDB
enabled in the kernel you built, or you're running the
wrong kernel:</para>
<programlisting>
com0 at isa0 port 0x3f8-0x3ff irq4: ns16550a, working fifo
com0: kgdb</programlisting>
</listitem>
<listitem>
<para>Make sure the serial ports and cable work with a
<quote>normal</quote> application: boot the TARGET with a
non-KGDB kernel and try running
<application>tip</application> between the two
machines. If you don't know about
<application>tip</application>, here's a quick rundown on
what to do:</para>
<itemizedlist>
<listitem>
<para>put the following lines in
<filename>/etc/remote</filename> on both the TARGET
and the REMOTE machines:</para>
<programlisting>
tty00-9600:dv=/dev/tty00:br#9600:pa=none:dc:
tty01-9600:dv=/dev/tty01:br#9600:pa=none:dc:</programlisting>
</listitem>
<listitem>
<para>on the TARGET, give the command <command>tip
tty00-9600</command>, and on the REMOTE do
<command>tip tty01-9600</command></para>
</listitem>
<listitem>
<para>type characters at the keyboard of each machine
- the characters should echo to <emphasis>the
other</emphasis> machine's display.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Double check the line for your tty in
<filename>/etc/ttys</filename>, and reboot to make sure
it has taken effect.</para>
</listitem>
<listitem>
<para>In all the above discussion, I've assumed you were
running as root. tip and gdb may not work if you're
running as a normal user (depending on the permissions of
<filename>/dev/tty0*</filename>). Of course, running as
root is not an advisable <quote>normal</quote>
strategy. Instead, you should do this:</para>
<orderedlist>
<listitem>
<para>put <filename>/dev/tty0*</filename> in group
<literal>wheel</literal> (if it isn't already)</para>
</listitem>
<listitem>
<para>add your username to the <literal>wheel</literal>
line in <filename>/etc/group</filename></para>
</listitem>
<listitem>
<para>add your username to the <literal>dialer</literal>
line in <filename>/etc/group</filename></para>
</listitem>
</orderedlist>
<para>(2) will allow your gdb process (and other processes
run by you) to open the tty, (3) will allow you to run
tip.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="general_caveats">
<title>General Caveats</title>
<orderedlist>
<listitem>
<para>You may sometimes notice a long pause after you've
entered a command until you get a response back - this
seems to be due to bad data on the serial connection;
after a short pause and a retransmit, everything is back
on track. setting remotetimeout to a value lower than
the default 20 seconds helps immensely. (This was
reported by one person to be caused (in his case) by
having a kernel <function>printf()</function> executed
between commands; this apparently somehow corrupted the
gdb data).</para>
</listitem>
<listitem>
<para>Ctrl-C may not work if the kernel has lock some high
priority interrupts (depending on the port), ie you
can't break an endless loop in
<function>splimp()</function> on the i386, but if you
place a breakpoint before the loop you can single-step
through it.</para>
</listitem>
</orderedlist>
</sect3>
</sect2>
</sect1>
<parentsec url="./" text="NetBSD Documentation: Kernel"/>
</webpage>
--lrZ03NoBR/3+SXJZ
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="kgdb.diff"
Index: Makefile
===================================================================
RCS file: /cvsroot/htdocs/Documentation/kernel/Makefile,v
retrieving revision 1.18
diff -u -r1.18 Makefile
--- Makefile 16 Feb 2007 08:08:18 -0000 1.18
+++ Makefile 3 Apr 2007 17:52:28 -0000
@@ -3,10 +3,9 @@
SUBDIR+= profiling
SUBDIR+= pseudo
-LISTDOCS= kgdb.list
-LISTDOCS+= scsidma.list
+LISTDOCS= scsidma.list
XMLDOCS+= index non-exec ddwg porting_netbsd_arm_soc programming
-XMLDOCS+= lazyfpu uvm
+XMLDOCS+= lazyfpu uvm kgdb
.include "../../share/mk/web.site.mk"
Index: layout.xml
===================================================================
RCS file: /cvsroot/htdocs/layout.xml,v
retrieving revision 1.228
diff -u -r1.228 layout.xml
--- layout.xml 15 Mar 2007 11:23:25 -0000 1.228
+++ layout.xml 3 Apr 2007 17:52:51 -0000
@@ -72,6 +72,7 @@
<tocentry page="Documentation/kernel/lazyfpu.xml" filename="lazyfpu.html"/>
<tocentry page="Documentation/kernel/non-exec.xml" filename="non-exec.html"/>
<tocentry page="Documentation/kernel/ddwg.xml" filename="ddwg.html"/>
+ <tocentry page="Documentation/kernel/kgdb.xml" filename="kgdb.html"/>
<tocentry page="Documentation/kernel/porting_netbsd_arm_soc.xml" filename="porting_netbsd_arm_soc.html"/>
<tocentry page="Documentation/kernel/profiling/index.xml" dir="profiling" filename="."/>
<tocentry page="Documentation/kernel/programming.xml" filename="programming.html"/>
--lrZ03NoBR/3+SXJZ--