Changeset 3161

Timestamp:

07/06/07 21:40:00 (1 year ago)

Author:

n0-1

Message:

* /ignore for temporary files
* added kgdb documentation

Files:

• trunk/freewrt/Docs/handbook/devel (modified) (1 prop)
• trunk/freewrt/Docs/handbook/devel/handbook-dev.tex (modified) (12 diffs)

trunk/freewrt/Docs/handbook/devel/handbook-dev.tex

@@ -6 +6 @@
-\usepackage{amssymb}
-\usepackage{caption2}
-canadian
+english
-\usepackage{varioref}
-\usepackage{txfonts}
@@ -43 +43 @@
-\usepackage{cancel}
-%\usepackage[final, activate, verbose=true]{microtype}
-
+%
-%\usepackage{bookman}
-%\usepackage[a4paper,twoside,rmargin=2cm,lmargin=2cm,tmargin=2.5cm]{geometry}
@@ -88 +88 @@
-\newcommand{\entspr}{\stackrel{\wedge}{=}}
-
+% Create some new commands for designing the text
+% applications
+\newcommand{\app}[1]{%
+        \textsf{\textit{#1}}}
+% terminology, vendor or product names
+\newcommand{\term}[1]{%
+        \textsc{#1}}
+% filenames and directories
+\newcommand{\file}[1]{%
+        \textsf{#1}}
+% user input
+\newcommand{\command}[1]{%
+        \texttt{\textbf{#1}}}
+% example code, output of applications
+\newcommand{\code}[1]{%
+        \texttt{#1}}
+% emphasized text (nicer than \emph{})
+\newcommand{\strong}[1]{%
+        \textbf{#1}}
+
-\chapter{Introduction}
-
@@ -101 +121 @@
-feedback and will try to update or correct the issues mentioned by you.
-
- 
+
-% ADK Overview
-% SVN Grundlagen
@@ -137 +157 @@
-
-Examples starting with \$ indicate a command that should be invoked as a
-  
+
-
-\begin{Verbatim}
@@ -166 +186 @@
-\item Debian GNU/Linux
-\item Gentoo Linux
- 
+
-\item Ubuntu GNU/Linux
- 
+
-\item OpenBSD (partial support)\footnote{some addon packages does not compile}
-\item MirOS BSD (partial support)\footnote{some addon packages does not compile}
@@ -261 +281 @@
-\section{Getting the source}
-
- 
+
-To get the latest version of the FreeWRT ADK use one of these commands:
-\begin{Verbatim}
@@ -290 +310 @@
-% other projects (Gentoo, OpenWrt, OpenEmbedded, *BSD ports)
-% Upstream Bugtracking and Mailinglist archives
+
+\section{Debugging Userspace}
-
-% gdbserver
@@ -330 +352 @@
-(gdb) bt
-#0  0x0044efa0 in op_yank (oap=0x7fff7d18, deleting=7, mess=1) at ops.c:2388
- 
+
-    command_busy=0x7fff7c90, old_col=0, gui_yank=0, dont_adjust_op_end=646447176)
-    at normal.c:1789
@@ -339 +361 @@
-\end{verbatim}
-
+\section{Debugging Kernelspace}
+
+To debug problems with kernel or modules, basically some debugger has to be
+enabled inside the kernel itself. There is more than only one implementation
+for doing the job, but FreeWRT sticks to the subsystem already being included
+into the vanilla kernel, namely \app{KGDB}.
+
+To be able to control the debugger on headless machines, some sort of
+client/server approach like with \app{gdbserver} has to be used. Luckily, our
+cross compiled \app{gdb} serves fine for this task. But unlike \app{gdbserver},
+\app{KGDB} communicates via a serial port. As serial port access at the very
+early state \app{KGDB} starts using it (i.e. right after kernel execution
+starts) is very hardware--dependant, a few hardware--specific functions have to be
+provided for each supported device. At the time of this writing, only
+\code{rb-2.6} includes support for \app{KGDB}.
+
+First enable \code{FWRT\_DEBUG\_KGDB} in the ADK's config, then build the
+complete system. Besides enabling support for \app{KGDB} itself, this option
+causes the kernel and all modules to be built with debugging symbols included.
+
+\strong{BEWARE:} the generated kernel and modules are really huge in size, much
+too big to fit into any flash space (kernel around 20MB). So better build for
+use with nfsroot or compactflash disk.
+
+When booting the debug kernel, an attached serial terminal shows:
+\begin{Verbatim}[label=kernel with KGDB starting]
+GDB console initialized
++
+\end{Verbatim}
+first line is actually some hard--coded string inside debug console
+initialisation, so the only magic part is the \code{+} sign at the end. In
+\app{KGDB} protocol language this means "successful transfer", and is used here
+to start communication.
+
+Exit your terminal emulation and start the debugger:
+\begin{Verbatim}[label=gdb initialisation]
+$ cd build_mipsel/linux
+$ mipsel-linux-gdb vmlinux
+GNU gdb 6.3
+Copyright 2004 Free Software Foundation, Inc.
+GDB is free software, covered by the GNU General Public License, and you are
+welcome to change it and/or distribute copies of it under certain conditions.
+Type "show copying" to see the conditions.
+There is absolutely no warranty for GDB.  Type "show warranty" for details.
+This GDB was configured as "--host=i686-pc-linux-gnu
+--target=mipsel-linux-uclibc"...
+(gdb) set remotebaud 115200
+(gdb) target remote /dev/ttyUSB0
+0xffffffff8010dfcc in breakinst () at arch/mips/kernel/gdb-stub.c:1066
+1066            __asm__ __volatile__(
+warning: shared library handler failed to enable breakpoint
+(gdb)
+\end{Verbatim}
+Changing the directory into the kernel source's root is necessary as \app{gdb}
+automatically searches the current working directory for source files
+referenced by the debugging symbols inside the kernel.
+Alternatively/additionally you can specify search paths using the
+\code{directory} directive, e.g.:
+\begin{Verbatim}[label=specifying a search path in gdb]
+(gdb) directory ../../w-madwifi-0.9.3.1-4/madwifi-0.9.3.1/
+Source directories searched:
+/var/tmp/portage/build_mipsel/linux-2.6-rb/linux-2.6.19.1/../../w-madwifi-0.9.3.1-4
+/madwifi-0.9.3.1:$cdir:$cwd
+(gdb)
+\end{Verbatim}
+
+Specifying the correct tty with \code{target remote} triggers the start of
+communication with \app{KGDB}. To make life happy, right after communication
+has started, the kernel triggers a break itself, so you have time to specify
+other options before continuing.
+
+Finally hit \code{c} for \code{continue} and watch the kernel booting. (The gdb
+console registered inside the kernel is being enabled for use as a regular
+output device, and kernel log messages output is being redirected via the
+\code{console=gdb} kernel parameter.
+
+To be able to debug kernel modules, you need to specify a path to the object
+files being debugged:
+\begin{Verbatim}[label=setting solib-search-path]
+(gdb) set solib-search-path /tmp/t/lib/modules/2.6.19.1/
+(gdb)
+\end{Verbatim}
+\app{gdb} should recognise loading of a module on the test machine and load the
+corresponding object file itself.
+
+While \app{gdb} is running, the serial console is unusable for I/O. This means
+if kernel bugs somehow have to be triggered interactively, it is handy to have
+networking being configured so you can log in via \app{SSH} in parallel. Though
+after exiting from \app{gdb} (hit \code{ctrl-c} twice), you can reattach your
+terminal emulator to the serial port and continue using the serial console as
+usual.
+
+From now on, you can use \app{gdb} like when debugging any other application.
+
-\chapter{Appliance Development Kit (ADK) Reference}
-
-\section{Filesystem structure}
-
- 
+
-working directory:
-\begin{verbatim}
@@ -358 +474 @@
-
-You will see some more files there, containing license information, portability
- 
+
-builds. We will concentrate on the above list for now.
-
-The docs/ directory contains a package template and the FreeWRT handbook's
- 
+
-
-\section{NFO system}
@@ -400 +516 @@
-\section{Filesystems}
-
- 
+
-% squashfs, lzma, jffs2, yaffs2, ext2, nfs
-