summaryrefslogtreecommitdiff
path: root/Mach/RemoteDebugOskitMach.mdwn
diff options
context:
space:
mode:
Diffstat (limited to 'Mach/RemoteDebugOskitMach.mdwn')
-rw-r--r--Mach/RemoteDebugOskitMach.mdwn84
1 files changed, 39 insertions, 45 deletions
diff --git a/Mach/RemoteDebugOskitMach.mdwn b/Mach/RemoteDebugOskitMach.mdwn
index 97b55159..b82b6912 100644
--- a/Mach/RemoteDebugOskitMach.mdwn
+++ b/Mach/RemoteDebugOskitMach.mdwn
@@ -4,44 +4,43 @@
# <a name="Booting_oskit_mach_with_a_serial"> Booting oskit-mach with a serial console </a>
-Author: Igor Khavkine Last Updated: Mon Jul 30 17:58:55 EDT 2001
+<dl>
+ <dt> Author</dt>
+ <dd> Igor Khavkine </dd>
+ <dt> Last Updated</dt>
+ <dd> Mon Jul 30 17:58:55 EDT 2001 </dd>
+</dl>
----
-Why? because it's covenient. If you have a second computer, but not a second monitor or keyboard, you can connet your second box to your main one using null-modem serial cables. Once that is done, you can configure the GRUB bootloader to use the serial port when starting up and boot oskit-mach without having to switch monitor cables or type blindly at a second keyboard. Also, oskit-mach supports the GDB remote debugging protocol over a serial line. This way it's now possible to debug the running kernel relatively unobtrusively because, the debugger will not be running on the same machine.
+## <a name="Why_"> Why? </a>
-## <a name="How_"> How? </a>
-
-First you need some equipment: two computers, each one should have at least one (two is preferable) free serial ports, as many null-modem serial cables. Then you need to follow the instructions given below.
-
-1. The first step is to get sourcefor oskit-mach and oskit. Currently (2001-07-30) you have to get the sources for oskit from [2] and compile them yourself. You need to get the snapshot oskit-20000202, newer versions either don't work or have not been tested. Hoefuly this situation will change in the future. Now is your chance (if you wish) to compile oskit with debugging symbols. (If you encounter errors while compiling, try removing anything that has to do with \`unix' or \`examples' from the file modules.x86.pc). Then you need to get the sources for oskit-mach. They are available from the GNU CVS repository[3], you need to check out the \`gnumach' module with the flag \`-roskit-branch'. Again now is your chance to compile oskit-mach with debugging symbols.
-
-1. Now you need to setup GRUB on your second box so it would accept input from a serial port while booting up. This is simple to do by adding the following lines to your \`menu.lst' file, before any of the menu entries:
+Because it's covenient. If you have a second computer, but not a second monitor or keyboard, you can connect your second box to your main one using null-modem serial cables. Once that is done, you can configure the GRUB bootloader to use the serial port when starting up and boot [oskit-mach](http://savannah.gnu.org/cgi-bin/viewcvs/hurd/gnumach/?only_with_tag=oskit-branch) without having to switch monitor cables or type blindly at a second keyboard.
-serial --unit=0 --speed=9600 terminal serial
+Also, oskit-mach supports the GDB remote debugging protocol over a serial line. This way it is now possible to debug the running kernel relatively unobtrusively, because the debugger will not be running on the same machine.
-Unit refers to the serial port you wish to use (0 is COM1), and speed is optional. For more information see the GRUB documentation.
+## <a name="How_"> How? </a>
-1. You need to make sure that your main box has the necessary utilities to communicate with your second box over a serial line. You can use a terminal emulator like minicom(1), or a simple serial communication program cu(1) which comes with the GNU uucp package. Or if you feel really lazy you can use this hack:
+First you need some equipment: two computers, each one should have at least one (two is preferable) free serial ports, as many null-modem serial cables. Then you need to follow the instructions given below.
- stty raw
+1. The first step is to the get source for oskit-mach and OSKit.
+ Currently the [St. Patrick's day release](ftp://flux.cs.utah.edu/flux/oskit/oskit-20020317.tar.gz), 2002-03-17, of the OSKit is the latest. Get the sources and compile them yourself, compile OSKit with debugging symbols if that is what you need. (If you encounter errors while compiling, try removing anything that has to do with \`unix' or \`examples' from the file modules.x86.pc).
+ Then you need to get the sources for oskit-mach. They are available from the GNU CVS repository[3], you need to check out the \`gnumach' module with the flag \`-roskit-branch'. Again now is your chance to compile oskit-mach with debugging symbols.
+2. Now you need to setup GRUB on your second box so it accepts input from a serial port while booting up. This is simple to do by adding the following lines to your \`menu.lst' file, before any of the menu entries:
+ serial --unit=0 --speed=9600
+ terminal serial
+ Unit refers to the serial port you wish to use (0 is COM1), and speed is optional. For more information see the GRUB documentation.
+3. You need to make sure that your main box has the necessary utilities to communicate with your second box over a serial line. You can use a terminal emulator like minicom(1), seyon(1), tip(1), or a simple serial communication program cu(1) which comes with the GNU uucp package. Or if you feel really lazy you can use this hack:
+ stty raw
cat > /dev/ttyS1 # in one terminal window
cat /dev/ttyS1 # in a second terminal window
-
-1. Now you have to make sure your computer has an at least partially setup Hurd partition. You can find instructions how to do that here [4,5]. Copy the oskit-mach kernel binary compressed with gzip to /boot/oskit-mach.gz and use the following command line[1] to boot it from GRUB:
-
+4. Now you have to make sure your computer has an at least partially setup Hurd partition. You can find instructions how to do that here [4,5]. Copy the oskit-mach kernel binary compressed with gzip to /boot/oskit-mach.gz and use the following command line[1] to boot it from GRUB:
/boot/gnumach.test.gz -h CONS_COM=1 -d GDB_COM=2 BAUD=9600 -- root=hd0s2
-
--h (use serial console) CONS\_COM=1 (COM1) CONS\_COM=2 (COM2) CONS\_COM=3 (COM3) CONS\_COM=4 (COM4)
-
--d (enable serial port debugging, optional) GDB\_COM=2 (use a different port other then CONS\_COM, default is to use the same as CONS\_COM) BAUD=9600 (use this baud rate, optional, default is 9600)
-
--- (delimits the arguments passed to the oskit from those to the kernel)
-
-root=hd0s2 (tell gnumach which is your root partition, in this case it's hd0s2)
-
-1. Now I suggest that you familiarize yourself with the GDB documentation on remote debugging. If you pass the -d boot flag to oskit-mach, then it will automatically insert a breakpoint at main() and wait for further instructions from GDB over the serial line. Here's a simple example of how to attach GDB to a remote target over a serial line:
-
+ -h (use serial console) CONS\_COM=1 (COM1) CONS\_COM=2 (COM2) CONS\_COM=3 (COM3) CONS\_COM=4 (COM4)
+ -d (enable serial port debugging, optional) GDB\_COM=2 (use a different port other then CONS\_COM, default is to use the same as CONS\_COM) BAUD=9600 (use this baud rate, optional, default is 9600)
+ -- (delimits the arguments passed to the oskit from those to the kernel)
+ root=hd0s2 (tell gnumach which is your root partition, in this case it's hd0s2)
+5. Now I suggest that you familiarize yourself with the GDB documentation on remote debugging. If you pass the -d boot flag to oskit-mach, then it will automatically insert a breakpoint at main() and wait for further instructions from GDB over the serial line. Here's a simple example of how to attach GDB to a remote target over a serial line:
$ script # record the debugging session
$ gdb # assume you're in the oskit-mach build dir.
(gdb) file kernel
@@ -52,17 +51,14 @@ root=hd0s2 (tell gnumach which is your root partition, in this case it's hd0s2)
[...]
(gdb) quit
$ ^D # finish recording the session
-
-This way you can catch any kernel panics (except for the really nasty ones and try to debug them).
-
-I've noticed that once oskit-mach is running under GDB, pressing C-c from GDB will not suspend it, this makes it hard to set additional breakpoints after the kernel is running. So optinally you can modify oskit-mach to add a dummy system call that will be used only for setting breakpoints, and make a small program that calls it, you can use it whenever you want to pause the kernel and examine something under GDB. An example of how to do this is attached in Appendix A.
+ This way you can catch any kernel panics (except for the really nasty ones and try to debug them).
+ I've noticed that once oskit-mach is running under GDB, pressing C-c from GDB will not suspend it, this makes it hard to set additional breakpoints after the kernel is running. So optinally you can modify oskit-mach to add a dummy system call that will be used only for setting breakpoints, and make a small program that calls it, you can use it whenever you want to pause the kernel and examine something under GDB. An example of how to do this is attached in Appendix A.
Now you're all set to do some serious kernel hacking. I hope more people will take advantage of this opportunity.
- Appendix A
- ----------
+## <a name="Appendix_A"> Appendix A </a>
- Apply this patch to oskit-mach to add a dummy system call:
+Apply this patch to oskit-mach to add a dummy system call:
--- gdb-stub.diff ---
Index: kern/syscall_sw.c
@@ -99,9 +95,7 @@ Now you're all set to do some serious kernel hacking. I hope more people will ta
int mach_trap_count = (sizeof(mach_trap_table) / sizeof(mach_trap_table[0]));
--- end ---
- When starting an oskit-mach debug session with GDB set a break poit at
- `gdb_break_stub'. Then use this program to invoke the system call when
- desired:
+When starting an oskit-mach debug session with GDB set a break poit at \`gdb\_break\_stub'. Then use this program to invoke the system call when desired:
--- gdb-break.c ---
/* Compile with: gcc -o gdb-break gdb-break.c gdb-break-stub.S */
@@ -113,7 +107,8 @@ Now you're all set to do some serious kernel hacking. I hope more people will ta
extern int gdb_break_stub (void *addr);
- int main () {
+ int main ()
+ {
kern_return_t err;
err = gdb_break_stub (&main);
@@ -128,14 +123,13 @@ Now you're all set to do some serious kernel hacking. I hope more people will ta
kernel_trap(gdb_break_stub,-129,1)
--- end ---
- References
- ----------
+## <a name="References"> References </a>
- [1] OSKit documentation, section 1.6.3.
- [2] http://www.cs.utah.edu/flux/oskit/
- [3] http://www.gnu.org/software/devel
- [4] http://www.walfield.org/papers/hurd-installation-guide/
- [5] http://www.pick.ucam.org/~mcv21/hurd.html
+* [1] OSKit documentation, section 1.6.3.
+* [2] <http://www.cs.utah.edu/flux/oskit/>
+* [3] <http://www.gnu.org/software/devel.html>
+* [4] <http://www.walfield.org/papers/hurd-installation-guide/>
+* [5] <http://www.pick.ucam.org/~mcv21/hurd.html>
vim:ts=8:tw=72:sw=8: