Merge branch 'master' into external_pager_mechanism

Conflicts:
	microkernel/mach/external_pager_mechanism.mdwn

9 files changed, 229 insertions, 84 deletions

diff --git a/hurd/debugging/gdb.mdwn b/hurd/debugging/gdb.mdwn
index 75474128..1fede74f 100644
--- a/hurd/debugging/gdb.mdwn
+++ b/hurd/debugging/gdb.mdwn
@@ -1,26 +1,15 @@
-[[license text="""
-Copyright © 2007 Free Software Foundation, Inc.
+[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
 
-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.txt]].
+[[!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]]."]]"""]]
 
-By contributing to this page, you agree to assign copyright for your
-contribution to the Free Software Foundation.  The Free Software Foundation
-promises to always use either a verbatim copying license or a free
-documentation license when publishing your contribution.  We grant you back all
-your rights under copyright, including the rights to copy, modify, and
-redistribute your contributions.
-"""]]
-
-The [GNU debugger *GDB*](http://www.gnu.org/software/gdb/) works on GNU/Hurd
+The [[GNU_debugger_*GDB*|/gdb]] works on GNU/Hurd
 systems as it does on other system, but has some additional [hurd-specific
 features](http://sourceware.org/gdb/current/onlinedocs/gdb_19.html#Hurd%20Native)
 to offer, such as [[noninvasive_debugging]] (for avoiding [[deadlock]]s), for
 example.
-
-* [Manual](http://sourceware.org/gdb/documentation/)
-
-* [When disassemble doesn't work](http://lists.gnu.org/archive/html/bug-hurd/2007-02/msg00039.html)
diff --git a/hurd/debugging/gdb/noninvasive_debugging.mdwn b/hurd/debugging/gdb/noninvasive_debugging.mdwn
index fc6653e7..fa7a3c5b 100644
--- a/hurd/debugging/gdb/noninvasive_debugging.mdwn
+++ b/hurd/debugging/gdb/noninvasive_debugging.mdwn
@@ -1,23 +1,16 @@
-[[license text="""
-Copyright © 2007 Free Software Foundation, Inc.
+[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
 
-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.txt]].
+[[!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]]."]]"""]]
 
-By contributing to this page, you agree to assign copyright for your
-contribution to the Free Software Foundation.  The Free Software Foundation
-promises to always use either a verbatim copying license or a free
-documentation license when publishing your contribution.  We grant you back all
-your rights under copyright, including the rights to copy, modify, and
-redistribute your contributions.
-"""]]
-
-Sometimes using [[GDB]] on a system server can result in a [[deadlock]].  You
+Sometimes using [[GDB]] on a [[system_server|translator]] can result in a [[deadlock]].  You
 can however still use GDB by using the [`set
 noninvasive`](http://sourceware.org/gdb/current/onlinedocs/gdb_19.html#Hurd%20Native)
 option.  This indicates to GDB to not stop the program but allows you to
-nevertheless examine its state.  Thus, you can get back traces and value of
+nevertheless examine its state.  Thus, you can get [[/gdb/backtrace]]s and values of
 variables (and watch them change underneath you).
diff --git a/hurd/debugging/glibc.mdwn b/hurd/debugging/glibc.mdwn
index a0890fe8..e9817132 100644
--- a/hurd/debugging/glibc.mdwn
+++ b/hurd/debugging/glibc.mdwn
@@ -1,13 +1,24 @@
+[[!meta copyright="Copyright © 2007, 2008, 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]]."]]"""]]
+
 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_testsuite]].
 
 ---
 
-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 c2aabc42..de46c08d 100644
--- a/hurd/debugging/rpctrace.mdwn
+++ b/hurd/debugging/rpctrace.mdwn
@@ -1,19 +1,13 @@
-[[license text="""
-Copyright © 2007 Free Software Foundation, Inc.
-
-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.txt]].
-
-By contributing to this page, you agree to assign copyright for your
-contribution to the Free Software Foundation.  The Free Software Foundation
-promises to always use either a verbatim copying license or a free
-documentation license when publishing your contribution.  We grant you back all
-your rights under copyright, including the rights to copy, modify, and
-redistribute your contributions.
-"""]]
+[[!meta copyright="Copyright © 2007, 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]]."]]"""]]
 
 *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
@@ -24,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
@@ -31,12 +27,27 @@ 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... ;-)
 
-# TODO
+* 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) ...
+        <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...
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/translator/gdb.mdwn b/hurd/debugging/translator/gdb.mdwn
new file mode 100644
index 00000000..82a50736
--- /dev/null
+++ b/hurd/debugging/translator/gdb.mdwn
@@ -0,0 +1,53 @@
+[[!meta copyright="Copyright © 2007, 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]]."]]"""]]
+
+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 [[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
+
+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
+    GNU gdb 6.5-debian
+    [...]
+    Reading symbols from /lib/libdiskfs.so.0.3...Reading symbols from /lib/debug/lib/libdiskfs.so.0.3...done.
+    done.
+    Loaded symbols for /lib/libdiskfs.so.0.3
+    Reading symbols from /devel4/tschwinge/tmp/hurd/hurd.ogi/build/libpager/libpager.so.0.3...done.
+    Loaded symbols for /devel4/tschwinge/tmp/hurd/hurd.ogi/build/libpager/libpager.so.0.3
+    Reading symbols from /lib/libstore.so.0.3...Reading symbols from /lib/debug/lib/libstore.so.0.3...done.
+    done.
+    Loaded symbols for /lib/libstore.so.0.3
+    [...]
+    (gdb) break pager_demuxer
+    Breakpoint 1 at 0x105c98d: file ../../libpager/demuxer.c, line 27.
+    [...]
+    Breakpoint 1, pager_demuxer (inp=0x12bded0, outp=0x12bbec0) at ../../libpager/demuxer.c:27
+    27      {
+    (gdb) list
+    22      /* Demultiplex a single message directed at a pager port; INP is the
+    23         message received; fill OUTP with the reply.  */
+    24      int
+    25      pager_demuxer (mach_msg_header_t *inp,
+    [...]
+
+Voilà.
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 :)