[pok-devel] [26] Add documentation about gdb.

[subversion@xxxxxxxxxxxxx]

Revision: 26
Author:   coredumper
Date:     2012-02-08 17:19:40 +0100 (Wed, 08 Feb 2012)
Log Message:
-----------
Add documentation about gdb.

Modified Paths:
--------------
    trunk/doc/develguide/pok-devel.tex
    trunk/misc/mk/examples.mk

Modified: trunk/doc/develguide/pok-devel.tex
===================================================================
--- trunk/doc/develguide/pok-devel.tex	2011-12-05 20:09:13 UTC (rev 25)
+++ trunk/doc/develguide/pok-devel.tex	2012-02-08 16:19:40 UTC (rev 26)
@@ -331,6 +331,82 @@
 function: code must be understandable and documentation to be spread over users
 or developpers.
 
+\section{GDB'ing POK with QEMU}
+POK allows you to attach a remote GDB to monitor the kernel \textit{or} its
+partitions.
+
+To do so, go to your example directory and run the system in debug mode.
+
+\begin{verbatim}
+$ cd $POK_PATH/examples/partition-threads
+$ make run-gdb
+\end{verbatim}
+
+QEMU should be paused. Now run GDB using the kernel image.
+
+\begin{verbatim}
+$ gdb generated-code/kernel/kernel.elf
+...
+(gdb) target remote :1234
+Remote debugging using :1234
+0x0000fff0 in ?? ()
+(gdb) continue
+\end{verbatim}
+
+You're all set if you want to debug the kernel, but what if you want to
+instrumentate a partition?
+
+In GDB, we first have to let the kernel know about the symbols of the
+partition. But we also need to know where they are loaded in kernel space.
+Let's say we want to debug partition \#1. One way to know where it was
+relocated would be:
+
+\begin{verbatim}
+(gdb) p pok_partitions[0].base_addr
+$1 = 1175552
+\end{verbatim}
+
+Please note that \texttt{pok\_partition\_init} \textit{must} have completed
+or the array won't be initialized yet.
+
+Now we can load the symbol table with the correct offset.
+
+{
+\normalsize
+
+\begin{verbatim}
+(gdb) add-symbol-file generated-code/cpu/part1/part1.elf 1175552
+add symbol table from file "generated-code/cpu/part1/part1.elf" at
+        .text_addr = 0x11f000
+(y or n) y
+Reading symbols from /home/laurent/pok/examples/partitions-threads/generated-code/cpu/part1/part1.elf...done.
+(gdb) b user_hello_part1
+Breakpoint 1 at 0x11f17a: file ../../../hello1.c, line 21.
+(gdb) continue
+Continuing.
+
+Program received signal SIGTRAP, Trace/breakpoint trap.
+0x0000017a in ?? ()
+\end{verbatim}
+}
+
+You will notice debug symbols are missing, although we loaded them above.
+This is because the memory mapping is not the same in kernel end userland.
+We have to load the symbol file again in place of the kernel.
+
+{
+\normalsize
+
+\begin{verbatim}
+(gdb) symbol-file generated-code/cpu/part1/part1.elf
+Load new symbol table from "/home/laurent/pok/examples/partitions-threads/generated-code/cpu/part1/part1.elf"? (y or n) y
+Reading symbols from /home/laurent/pok/examples/partitions-threads/generated-code/cpu/part1/part1.elf...done.
+(gdb) bt
+#0  user_hello_part1 () at ../../../hello1.c:21
+#1  0xc4830845 in ?? ()
+\end{verbatim}
+}
+
 \section{Commit on the SVN}
 You \textbf{MUST} commit by ussing \texttt{make commit} at the root of the
 sources. This make target will build all examples on all architectures/platforms

Modified: trunk/misc/mk/examples.mk
===================================================================
--- trunk/misc/mk/examples.mk	2011-12-05 20:09:13 UTC (rev 25)
+++ trunk/misc/mk/examples.mk	2012-02-08 16:19:40 UTC (rev 26)
@@ -13,8 +13,11 @@
 	$(RM) generated-code
 
 run:
-	cd generated-code && make run
+	$(MAKE) $@ -C generated-code
 
+run-gdb:
+	$(MAKE) run QEMU_MISC="$(QEMU_MISC) -S -s " -C generated-code
+
 test: $(TESTS)
 
 spoq: