9 files changed, 173 insertions, 51 deletions
diff --git a/hurd/debugging/gdb.mdwn b/hurd/debugging/gdb.mdwn
index 98c31435..1fede74f 100644
--- a/hurd/debugging/gdb.mdwn
+++ b/hurd/debugging/gdb.mdwn
@@ -1,12 +1,12 @@
-[[meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
 
-[[meta license="""[[toggle id="license" text="GFDL 1.2+"]][[toggleable
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
 document under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no Invariant
 Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
-[[GNU_Free_Documentation_License|/fdl]]."]]"""]]
+[[GNU Free Documentation License|/fdl]]."]]"""]]
 
 The [[GNU_debugger_*GDB*|/gdb]] works on GNU/Hurd
 systems as it does on other system, but has some additional [hurd-specific
diff --git a/hurd/debugging/gdb/noninvasive_debugging.mdwn b/hurd/debugging/gdb/noninvasive_debugging.mdwn
index 62179f7d..fa7a3c5b 100644
--- a/hurd/debugging/gdb/noninvasive_debugging.mdwn
+++ b/hurd/debugging/gdb/noninvasive_debugging.mdwn
@@ -1,12 +1,12 @@
-[[meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
 
-[[meta license="""[[toggle id="license" text="GFDL 1.2+"]][[toggleable
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
 document under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no Invariant
 Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
-[[GNU_Free_Documentation_License|/fdl]]."]]"""]]
+[[GNU Free Documentation License|/fdl]]."]]"""]]
 
 Sometimes using [[GDB]] on a [[system_server|translator]] can result in a [[deadlock]].  You
 can however still use GDB by using the [`set
diff --git a/hurd/debugging/glibc.mdwn b/hurd/debugging/glibc.mdwn
index a0890fe8..028d4fe4 100644
--- a/hurd/debugging/glibc.mdwn
+++ b/hurd/debugging/glibc.mdwn
@@ -1,13 +1,24 @@
+[[!meta copyright="Copyright © 2007, 2008, 2010, 2011 Free Software Foundation,
+Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
 Here are some hints about how to approach testing after nontrivial changes to
 glibc have been done.
 
 ---
 
-First step is having the build a glibc complete.  This is actually more
-difficult than one might expect, as it involves (towards the end of the build
-process; unless you are cross-building, of course), that the newly created
-libraries and loader actually work: they're used to run the `rpcgen`
-program.  If that step doesn't succeed, it'll look similar to this:
+First step is having the build of glibc succeed.  This is actually more
+difficult than one might expect as it involves (towards the end of the build
+process -- unless you are cross-compiling, of course -- that the
+newly created libraries and loader actually work: they'll be used to run the
+`rpcgen` program.  If that step doesn't succeed, it'll look similar to this:
 
     [...]
     CPP='gcc -E -x c-header' [...]/build/elf/ld.so.1 --library-path [...] [...]/build/sunrpc/rpcgen [...]
@@ -15,19 +26,35 @@ program.  If that step doesn't succeed, it'll look similar to this:
 
 ---
 
-If building glibc succeeds, the next thing to try is running the test suite, or
-parts of it.
+Unless cross-compiling, the next thing you'll probably want to do
+is running the test suite, or parts of it.
 
-Here is a list of known failures:
-
-[TODO].
+There is a list of [[known failures|open_issues/glibc]].
 
 ---
 
-Make sure static linking is working OK at all.  The `elf/sln` program (a
-stripped-down `ln` that is statically linked) in the glibc build ought to test
-that.  Also, static linking under various conditions will already have been
-tested when running the test suite, especially in `elf/` and `dlfcn/`.
+If you've been doing simple changes to glibc functions that end up in
+`libc.so`, you may test them like this (like for a `strerror_l` implementation
+in this case):
+
+    $ LD_PRELOAD=./libc.so ./ld.so ./a.out 10 1073741928 de_DE.utf8
+    1073741928 (0x40000068): Computer bought the farm
+    1073741928 (0x40000068): Der Computer hat den Bauernhof erworben
+
+You usually will only have luck using the new `libc.so` (from
+`[glibc-build]/libc.so`) in combination together with the new `ld.so` (from
+`[glibc-build]/elf/ld.so`):
+
+    $ LD_PRELOAD=./libc.so ./a.out 10 1073741928 de_DE.utf8
+    Killed
+    $ LD_PRELOAD=./libc.so /lib/ld.so ./a.out 10 1073741928 de_DE.utf8
+    Killed
+
+Make sure static linking is working OK at all.  Running the
+`[glibc-build]/elf/sln` program (a stripped-down `ln` that is statically
+linked) ought to test that.  Also, static linking under various conditions will
+already have been tested when running the test suite, especially in `elf/` and
+`dlfcn/`.
 
 Make sure static linking with cthreads is working.  If you can get an
 `ext2fs.static` compiled and linked against the new glibc, that is good.
@@ -41,8 +68,8 @@ Then debug its startup as a normal program on your working hurd.
 
 Then try its full server startup.
 
-    $ settrans -ca node [...]/ext2fs.static <BACKEND>
-    $ cd node/
+    $ settrans -ca node [...]/ext2fs.static BACKING_STORE
+    $ ls -l node/
     [...]
 
 Make sure dynamic linking for servers is working.  If you haven't broken the
@@ -51,7 +78,7 @@ glibc's `testrun.sh` does it.
 
 [TODO]: Is this the correct way to do that?
 
-    $ settrans -ca node [glibc]/build/testrun.sh /hurd/ext2fs <BACKEND>
+    $ settrans -ca node [glibc]/build/testrun.sh /hurd/ext2fs BACKING_STORE
     $ cd node/
     [...]
 
@@ -62,10 +89,3 @@ Test it in a [[subhurd]].
 ---
 
 Test it on a real system.
-
----
-
-Sources:
-
-* <http://lists.gnu.org/archive/html/bug-hurd/2007-02/msg00038.html>
-* [[Thomas_Schwinge|tschwinge]]'s mind
diff --git a/hurd/debugging/rpctrace.mdwn b/hurd/debugging/rpctrace.mdwn
index 68edca2f..f7136056 100644
--- a/hurd/debugging/rpctrace.mdwn
+++ b/hurd/debugging/rpctrace.mdwn
@@ -1,12 +1,13 @@
-[[meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008, 2009, 2010, 2011 Free Software
+Foundation, Inc."]]
 
-[[meta license="""[[toggle id="license" text="GFDL 1.2+"]][[toggleable
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
 document under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no Invariant
 Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
-is included in the section entitled
-[[GNU_Free_Documentation_License|/fdl]]."]]"""]]
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
 
 *rpctrace* is -- roughly -- an equivavlent to Linux's *strace* or Solaris' or
 BSD's *truss*.  It is used to trace [[remote_procedure_call|rpc]]s a process is
@@ -17,6 +18,8 @@ See `rpctrace --help` about how to use it.
 
 # Issues and Patches
 
+[[!tag open_issue_hurd]]
+
 * <http://savannah.gnu.org/patch/?2104> -- don't assert that local port names
   are valid
 * <http://savannah.gnu.org/bugs/?3939> -- `rpctrace`d program hangs when signal
@@ -24,12 +27,32 @@ See `rpctrace --help` about how to use it.
   * <http://savannah.gnu.org/patch/?1633> -- terminated with `C-c` `rpctrace`d
     programs hang
 * <http://savannah.gnu.org/patch/?5580> -- more readable output
-* <http://savannah.gnu.org/bugs/?20612> -- heisenbug
+
+* IRC, unknown channel, unknown date
+
+        <youpi> how to rpctrace a translator ?
+        <youpi> ah, just settrans /usr/bin/rpctrace...
+        <youpi> hum, it hung, and killing it got a Mach panic (thread in unexpected
+          state) ...
+
+* IRC, unknown channel, unknown date
+
+        <antrik> hm... for a funny effect, try running rpctrace on
+          /servers/socket/1, and then use dpkg... ;-)
+
+* IRC, unknown channel, unknown date.
+
+        <youpi> the problem of rpctrace is that it's a man in the middle :)
+        <youpi> so in principle, by design authentication stuff shouldn't work
+        <antrik> I don't think the Hurd auth mechanism in any way prevents or tries to prevent man-in-the-middle...
+        <youpi> maybe, but just try, you'll see all kinds of issue as soon as you have authentication stuff
+        <youpi> and the basic reason is that being a man in the middle needs special care
+        <youpi> which rpctrace doesn't completely do
+        <antrik> it's a while since I have dived into rpctrace; but AIUI, it should work just fine if the proxying is done properly
+        <antrik> note that there is a number of known bugs in rpctrace, for which zhengda has sent patches... though I haven't reviewed all of them I think
+        <antrik> there are some nasty Mach operations that are really hard to proxy -- but I don't think the auth mechanism needs any of these...
 
 
-# TODO
+# See Also
 
-    <youpi> how to rpctrace a translator ?
-    <youpi> ah, just settrans /usr/bin/rpctrace...
-    <youpi> hum, it hung, and killing it got a Mach panic (thread in unexpected
-      state) ...
+See also [[open_issues/librpci]].
diff --git a/hurd/debugging/subhurd.mdwn b/hurd/debugging/subhurd.mdwn
index caad950b..7b5b07b1 100644
--- a/hurd/debugging/subhurd.mdwn
+++ b/hurd/debugging/subhurd.mdwn
@@ -85,6 +85,6 @@ W3
 
 Sources:
 
-* <http://www.gnu.org/software/hurd/howto/subhurd.html>
+* [[subhurd/running_a_subhurd]]
 * <http://lists.gnu.org/archive/html/bug-hurd/2007-02/msg00030.html>
 * [[Thomas_Schwinge|tschwinge]]'s mind
diff --git a/hurd/debugging/translator.mdwn b/hurd/debugging/translator.mdwn
new file mode 100644
index 00000000..d439e17b
--- /dev/null
+++ b/hurd/debugging/translator.mdwn
@@ -0,0 +1,15 @@
+[[!meta copyright="Copyright © 2008 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled
+[[GNU Free Documentation License|/fdl]]."]]"""]]
+
+[[!inline
+pages="hurd/debugging/translator/* and !*/discussion"
+show=0
+feeds=no
+actions=yes]]
diff --git a/hurd/debugging/translator/capturing_stdout_and_stderr.mdwn b/hurd/debugging/translator/capturing_stdout_and_stderr.mdwn
new file mode 100644
index 00000000..b7cfc3c9
--- /dev/null
+++ b/hurd/debugging/translator/capturing_stdout_and_stderr.mdwn
@@ -0,0 +1,37 @@
+[[!meta copyright="Copyright © 2008, 2009, 2010 Free Software Foundation,
+Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled
+[[GNU Free Documentation License|/fdl]]."]]"""]]
+
+Sometimes it may already be helpful to capture a translator's `stdout` and
+`stderr`, for example in this situation where [[translator/pfinet]] was
+silently dying all the time, without any console output:
+
+    $ sudo settrans -fgap ↩
+      /servers/socket/2 ↩
+      /bin/sh -c '/hurd/pfinet -i eth0 -a [...] > /tmp/stdout 2> /tmp/stderr'
+    $ [...]
+    $ cat /tmp/stdout
+    NET4: Linux TCP/IP 1.0 for NET4.0
+    IP Protocols: ICMP, UDP, TCP
+    TCP: Hash tables configured (ehash 65536 bhash 65536)
+    $ cat /tmp/stderr
+    pfinet: ../../hurd.work/pfinet/ethernet.c:196: ethernet_xmit: Unexpected error: (os/device) invalid IO size.
+
+(Trying to run [[GDB]] in this case was of no help -- due to a bug in GDB
+(supposedly) it wouldn't catch the fault.)
+
+Be made aware that both `stdout` and `stderr` will be block bufferend and no
+longer line buffered when doing such a redirection, so you'll have to arrange
+for appropriate `fflush`es on these, or force them to be line buffered again
+using the appropriate glibc magic (`setvbuf`).  Otherwise you'll see text in
+the output files only if either glibc herself decides to flush (after some KiB
+of text) the after translator exits.
+
+There is also a [[related open issue|open_issues/translator_stdout_stderr]].
diff --git a/hurd/debugging/hurd.mdwn b/hurd/debugging/translator/gdb.mdwn
index 043da3e0..82a50736 100644
--- a/hurd/debugging/hurd.mdwn
+++ b/hurd/debugging/translator/gdb.mdwn
@@ -1,32 +1,32 @@
-[[meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
 
-[[meta license="""[[toggle id="license" text="GFDL 1.2+"]][[toggleable
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
 document under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no Invariant
 Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
-[[GNU_Free_Documentation_License|/fdl]]."]]"""]]
+[[GNU Free Documentation License|/fdl]]."]]"""]]
 
-Say you want to try running file system server (*[[translator/ext2fs]]*<!--`[[translator/ext2fs]]`-->,
-*[[translator/jfs]]*<!--`[[translator/jfs]]`-->, ...)  against a modified version of *[[libpager]]*<!--`[[libpager]]`--> and
-debug the latter one using [[GDB]].
+Say you want to try running file system server ([[`ext2fs`|translator/ext2fs]],
+[[`jfs`|translator/jfs]], ...) against a modified version of
+[[`libpager`|libpager]] and debug the latter one using [[debugging/GDB]].
 
-Set the [[translator]] like this:
+Set the [[hurd/translator]] like this:
 
     $ settrans -fgap ↩
       jfs.img.i ↩
       /usr/bin/env ↩
         LD_LIBRARY_PATH=~tschwinge/tmp/hurd/hurd.ogi/build/libpager ↩
-      "`pwd`"/jfs.obj/jfs ↩
-      "`pwd`"/jfs.img
+      "$PWD"/jfs.obj/jfs ↩
+        "$PWD"/jfs.img
 
 Then, when starting GDB, start it like this (or use an equivalent method, of
 course):
 
     $ LD_LIBRARY_PATH=~tschwinge/tmp/hurd/hurd.ogi/build/libpager ↩
       gdb ↩
-      ~tschwinge/tmp/jfs/jfs.obj/jfs 15436
+        ~tschwinge/tmp/jfs/jfs.obj/jfs 15436
     GNU gdb 6.5-debian
     [...]
     Reading symbols from /lib/libdiskfs.so.0.3...Reading symbols from /lib/debug/lib/libdiskfs.so.0.3...done.
diff --git a/hurd/debugging/trap_in_the_kernel.mdwn b/hurd/debugging/trap_in_the_kernel.mdwn
new file mode 100644
index 00000000..11f989e3
--- /dev/null
+++ b/hurd/debugging/trap_in_the_kernel.mdwn
@@ -0,0 +1,27 @@
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+[[!tag open_issue_gnumach open_issue_documentation]]
+
+IRC, #hurd, September 2010
+
+    <diegonc> when an application executes an out instruction in user mode, how is
+      kernel mode entered? general protection trap?
+    <youpi> some sort of trap, yes
+    <youpi> I'd rather think about illegal instruction, but yes
+    <diegonc> hm.. so to debug what happens inside that instruction I'll have to
+      break at the trap handler. Can I instruct kdb to stop only when a given task
+      caused the trap?
+    <youpi> applications usually don't trap, so what I usually do is to uncomment
+      the test at the end of user_trap() before the call to kdb_trap()
+    <diegonc> "if (debug_all_traps_with_kdb && .. " <- that test?
+    <youpi> yes
+    <youpi> so comment the test to make kdb_trap() called all the time
+    <diegonc> oh, I understand now :)