13 files changed, 397 insertions, 82 deletions
diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index 56f7683c..31671308 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -1,4 +1,4 @@
-[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 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
@@ -8,146 +8,206 @@ 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]]."]]"""]]
 
-If you haven't: install hurd to partition
-get grub image
-boot hurd in single user (change grub entry accordingly to the installed partition)
+This guide explains how to build and set up
+a DDE-based network card driver
+with Debian GNU/Hurd,
+if your (wired) network card
+is not supported by the old in-kernel drivers shipped with gnumach.
 
-> $ export TERM=mach
+This guide assumes that you have
+an installation of Debian GNU/Linux on the same machine,
+which helps in fetching the required packages
+in absence of working networking in the Hurd.
+The whole process is much more cumbersome otherwise.
+It also assumes that apart from networking,
+your Hurd system is already installed and operational.
 
-> $ ./native-install
 
-reboot to other debian
+We start by booting into Debian GNU/Linux,
+so we can downloading everything we will need for building DDE.
 
-suppose hurd partition is hdd1
+Once there, first mount the Hurd partition (as root):
 
-as root
+	$ mount /dev/hdd1 /mnt -t ext2 # assuming your Hurd partition is hdd1 -- replace with whatever matches your setup
 
-> $ mount /dev/hdd1 /mnt -t ext2
+Prepare apt offline configuration so we can get necessary packages:
 
-> $ cd /mnt/etc/apt
+	$ cd /mnt/etc/apt
 
-> $ echo "deb http://ftp.debian-ports.org/debian unreleased main" >> sources.list
+	$ echo "deb http://ftp.debian-ports.org/debian unreleased main" >> sources.list # if you don't have sources.list set up yet on the Hurd system
 
-> $ echo "deb-src http://ftp.debian-ports.org/debian unreleased main" >> sources.list
+	$ echo "deb-src http://ftp.debian-ports.org/debian unreleased main" >> sources.list
 
-> $ echo "deb http://ftp.uk.debian.org/debian unstable main" >> sources.list
+	$ echo "deb http://ftp.uk.debian.org/debian unstable main" >> sources.list
 
-> $ echo "deb-src http://ftp.uk.debian.org/debian unstable main" >> sources.list
+	$ echo "deb-src http://ftp.uk.debian.org/debian unstable main" >> sources.list
 
-> $ wget http://www.gnu.org/software/hurd/hurd/running/debian/DebianAptOffline/apt.conf.offline
+	$ wget http://www.gnu.org/software/hurd/hurd/running/debian/DebianAptOffline/apt.conf.offline
 
-> $ cd /mnt
+Download the packages for offline installation:
 
-> $ apt-get -c etc/apt/apt.conf.offline update
+	$ cd /mnt
 
-> $ apt-get -c etc/apt/apt.conf.offline upgrade
+	$ apt-get -c etc/apt/apt.conf.offline update
 
-> $ apt-get -c etc/apt/apt.conf.offline install git-core
+	$ apt-get -c etc/apt/apt.conf.offline build-dep hurd gnumach
 
-> $ apt-get -c etc/apt/apt.conf.offline build-dep hurd gnumach
+	$ apt-get -c etc/apt/apt.conf.offline install git-core build-essential libpciaccess-dev libpcap0.8-dev
 
-> $ apt-get -c etc/apt/apt.conf.offline install build-essential libpciaccess-dev libpcap0.8-dev
+Get DDE code:
 
-> $ cd /mnt/home
+	$ cd /mnt/home/me # assuming your user name on the Hurd system is "me"
 
-> $ git clone git://git.sv.gnu.org/hurd/incubator.git -b dde hurd_dde
+	$ mkdir dde && cd dde
 
-> $ git clone git://git.sv.gnu.org/hurd/gnumach.git -b master-user_level_drivers gnumach_dde
+	$ git clone git://git.sv.gnu.org/hurd/incubator.git -b dde hurd
 
+	$ git clone git://git.sv.gnu.org/hurd/gnumach.git -b master-user_level_drivers
 
-suppose you need forcedeth driver
+Now comes the tricky part:
+you need to find out
+whether there is already a driver for your card
+in the DDE source tree,
+and otherwise get the driver code
+from the official Linux source tree.
 
-Download http://git.kernel.org/?p=linux/kernel/git/stable/linux-2.6.29.y.git;a=blob_plain;f=drivers/net/forcedeth.c;hb=HEAD from mozilla like
-browser to /mnt/home as forcedeth.c
+For this, you have to find out which Linux driver
+is responsible for your network card.
+In this guide we will use the forcedeth driver
+(for Nvidia nForce chipsets) as example.
+We check whether there is already a `dde_forcedeth` directory
+in the newly cloned `hurd_dde` tree.
+If there isn't, we have to find and download
+the right source file from Linux:
 
-reboot back to hurd (multiuser)
+Point a (JavaScript-capable) web browser at
 
-> $ apt-get update
+	http://git.kernel.org/?p=linux/kernel/git/stable/linux-2.6.29.y.git;a=tree;f=drivers/net;hb=HEAD
 
-> $ apt-get upgrade
+(Note: you **have** to use 2.6.29,
+as this is the version DDE is currently based on.)
 
-> $ apt-get install git-core
+Find the right file to download
+(forcedeth.c in this example);
+then hit the "raw" link,
+and save the resulting file (page) to /mnt/home/me/dde
 
-> $ apt-get build-dep hurd gnumach
+(If you happen to need one of the few drivers
+that consist of more than one source file,
+the process will be more complicated,
+and can't be covered in this guide...)
 
-> $ apt-get install build-essential libpciaccess-dev libpcap0.8-dev
 
+Now everything should be in place,
+so we can boot into Hurd to do the actual work.
 
-> $ cd /home/gnumach_dde
+Once there, install the packages previously downloaded (again as root):
 
-> $ autoreconf -i && ./configure --enable-kdb --enable-device-drivers=none --enable-lpr --enable-floppy --enable-ide
+	$ apt-get build-dep hurd gnumach
 
-> $ make
+	$ apt-get install git-core build-essential libpciaccess-dev libpcap0.8-dev
 
-> $ cd ../hurd_dde
+Make sure we can build stuff as normal user:
 
-> $ cp -r dde_pcnet32 dde_forcedeth
+	$ chown -R me ~me/dde
 
-> $ cd dde_forcedeth
+Now you can log in with the normal user account to build stuff.
 
-> $ rm pcnet32.c
+Build a DDE-enabled Mach:
 
-> $ cp /home/forcedeth.c ./
+	$ cd ~me/dde/gnumach
 
-> $ sed -i 's/pcnet32/forcedeth/g' Makefile
+	$ autoreconf -i && ./configure --enable-kdb --enable-device-drivers=none --enable-lpr --enable-floppy --enable-ide
 
-> $ sed -i 's/pcnet32/forcedeth/g' .gitignore
+	$ make
 
-> $ sed -i 's:-lhurd-slab:../libhurd-slab/libhurd-slab.a:' Makefile
 
-> $ sed -i 's:-I/include:-I..:' Makefile
+If not already present in DDE,
+we need to prepare the driver for the network card:
 
-> $ nano forcedeth.c
+	$ cd ~me/dde/hurd
 
-add this line after the last #include
+	$ cp -r dde_pcnet32 dde_forcedeth # using pcnet32 as template
+
+	$ cd dde_forcedeth
+
+	$ rm pcnet32.c # don't want the actual pcnet32 code here...
+
+	$ cp ~me/dde/forcedeth.c . # ...but rather the forcedeth code
+
+	$ sed -i 's/pcnet32/forcedeth/g' Makefile # adapt Makefile accordingly
+
+	$ sed -i 's/pcnet32/forcedeth/g' .gitignore
+
+	$ sed -i 's:-lhurd-slab:../libhurd-slab/libhurd-slab.a:' Makefile # fix up build system... XXX I guess this part is obsolete
+
+	$ sed -i 's:-I/include:-I..:' Makefile # same
+
+	$ nano forcedeth.c # Near the top of the file, there will be many #include lines. After the last one, add this:
 
     #include <ddekit/timer.h>
 
-> $ cd ..
+	$ cd ..
+
+Commit the new driver with git.
+This will be helpful if we update the DDE code later;
+as well as for creating a patch for later reuse
+and/or upstream submission:
 
-> $ git add dde_forcedeth
+	$ git add dde_forcedeth
 
-> $ git commit -a -m 'Add forcedeth driver'
+	$ git commit -a -m 'Add forcedeth driver'
 
-> $ autoreconf -i && ./configure
 
-> $ mkdir -p hurd/include/ddekit
+Having prepared the driver,
+we can now build the necessary Hurd and DDE bits:
 
-> $ make libddekit libmachdev devnode pfinet
+	$ autoreconf -i && ./configure
 
-> $ cd libdde_linux26
+	$ mkdir -p hurd/include/ddekit # workaround for a buildsystem bug... XXX I'm pretty sure this is not necessary anymore
 
-> $ make
+	$ make libddekit libmachdev devnode pfinet # Hurd components
 
-> $ cd ../dde_forcedeth
+	$ cd libdde_linux26 # common DDE driver code -- uses a different Makefile system than the Hurd components!
 
-> $ make
+	$ make
 
-If the make fails it might be necassary to replace some of the -l options (or all) in Makefile with the real path to the library objects (example: change *-lhurd-slab* to *../libhurd-slab/libhurd-slab.a*)
+	$ cd ../dde_forcedeth # actual driver
 
-> $ cp /home/gnumach_dde/gnumach /boot/gnumach_dde
+	$ make
 
-> $ mkdir /hurd/dde
+Install the various built components to their final destinations (as root):
 
-> $ cp /home/hurd_dde/devnode/devnode /hurd/dde
+	$ cd ~me/dde/
 
-> $ cp /home/hurd_dde/pfinet/pfinet /hurd/dde
+	$ cp gnumach/gnumach /boot/gnumach_dde
 
-> $ cp /home/hurd_dde/dde_forcedeth/dde_forcedeth /hurd/dde/forcedeth
+	$ mkdir /hurd/dde
 
-reboot to hurd with the new gnumach_dde
+	$ cp hurd/devnode/devnode hurd/pfinet/pfinet hurd/dde_forcedeth/dde_forcedeth /hurd/dde
 
-> $ settrans -c /dev/forcedeth /hurd/dde/forcedeth
 
-> $ settrans -c /dev/eth0 /hurd/dde/devnode -M /dev/forcedeth eth0
+Now everything should be ready.
+Before we can use the driver,
+we have to boot with the newly built gnumach_dde
+instead of the standard kernel.
+(Adapt your grub configuration;
+or manually edit the entry
+in the boottime grub menu while testing.)
 
-> $ settrans -c /servers/socket/2 /hurd/dde/pfinet -i /dev/eth0 -a 192.168.1.194 -g 192.168.1.254 -m 255.255.255.0 
+Once there, set up the translators for the driver (as root):
 
+	$ settrans -c /dev/forcedeth /hurd/dde/forcedeth
 
-replace the ip, gateway and mask with your own ones
+	$ settrans -c /dev/eth0 /hurd/dde/devnode -M /dev/forcedeth eth0
 
-> $ nano /etc/resolv.conf
+Finally, we can set up the actual network translator,
+using something like:
 
-add line: nameserver 192.168.1.254
+	$ settrans -c /servers/socket/2 /hurd/dde/pfinet -i /dev/eth0 -a 192.168.1.194 -g 192.168.1.254 -m 255.255.255.0 
 
-DONE
+For the exact syntax,
+see the normal network setup documentation.
+The only differences here
+are the different location of the pfinet binary,
+and the different syntax for the -i option.
diff --git a/hurd/dde/guide/discussion.mdwn b/hurd/dde/guide/discussion.mdwn
new file mode 100644
index 00000000..a1cccad4
--- /dev/null
+++ b/hurd/dde/guide/discussion.mdwn
@@ -0,0 +1,17 @@
+[[!meta copyright="Copyright © 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]]."]]"""]]
+
+ToDo:
+
+[[!tag open_issue_documentation]]
+
+* This guide is probably out of date in some points: the build system got reworked in the meantime I believe...
+* The formatting here needs serious cleanup
+* Might be nice to explain how to find out the right Linux driver, and in which source file it resides
diff --git a/hurd/debugging/rpctrace.mdwn b/hurd/debugging/rpctrace.mdwn
index de46c08d..f7136056 100644
--- a/hurd/debugging/rpctrace.mdwn
+++ b/hurd/debugging/rpctrace.mdwn
@@ -1,13 +1,13 @@
-[[!meta copyright="Copyright © 2007, 2008, 2009, 2010 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
 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
@@ -51,3 +51,8 @@ See `rpctrace --help` about how to use it.
         <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...
+
+
+# See Also
+
+See also [[open_issues/librpci]].
diff --git a/hurd/documentation.mdwn b/hurd/documentation.mdwn
index 874ce847..48fd017c 100644
--- a/hurd/documentation.mdwn
+++ b/hurd/documentation.mdwn
@@ -1,5 +1,5 @@
 [[!meta copyright="Copyright © 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
-2009 Free Software Foundation, Inc."]]
+2009, 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
@@ -24,6 +24,8 @@ is included in the section entitled
 
   * [[*The_Hurd*|/hurd-talk]], a presentation by Marcus Brinkmann.
 
+  * The *[[translator_primer]]*.
+
   * A document about *[[translators]]* by Marcus Brinkmann.
 
   * [[*A_Critique_of_the_GNU_Hurd_Multi-server_Operating_System*|critique]], an
diff --git a/hurd/documentation/translator_primer.mdwn b/hurd/documentation/translator_primer.mdwn
new file mode 100644
index 00000000..d8d89148
--- /dev/null
+++ b/hurd/documentation/translator_primer.mdwn
@@ -0,0 +1,70 @@
+[[!meta copyright="Copyright © 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]]."]]"""]]
+
+# Small Examples on Using Translators
+
+The [[concept|concepts]] of user-space servers, [[translator]]s, is a very
+powerful one.  Here is an introductionary text.
+
+
+## Intro
+
+The Hurd has some unique capabilities, and we created this simple image 
+to enable you to easily try two of them: 
+
+* The simplest of translators: Hello World!
+* Transparent FTP
+
+### Hello World
+
+To try out the simplest of translators, you can go the following simple steps: 
+
+	$ cat hello  
+	$ setrans hello /hurd/hello  
+	$ cat hello  
+	"Hello World!"  
+	$ settrans -g hello  
+	$ cat hello  
+
+What you do with these steps is first verifying that the file "hello" is empty. 
+
+Then you setup the translator /hurd/hello in the file/node hello. 
+
+After that you check the contents of the file, and the translator returns "Hello World!". 
+
+To finish it, you tell the translator to go away from the file "hello" via "settrans -g hello" and verify that now the file is empty again. 
+
+### Transparent FTP
+
+We already setup a a transparent FTP translator for you at /ftp: 
+
+With it you can easily access public FTP via the file system, for example the one from the GNU project: 
+
+	$ ls /ftp://ftp.gnu.org/
+
+But you can also do this very easily yourself: 
+
+	$ # Setup the translator on the node ftp:  
+	$ settrans -c ftp: /hurd/hostmux /hurd/ftpfs /
+
+and you can access FTP sites via the pseudo-directory ftp:, for example with 
+
+	$ ls ftp://ftp.gnu.org/
+
+What you do here is setting up the translator /hurd/hostmux on ftp: and passing it the translator /hurd/ftpfs to use for resolving accesses as well as / as additional path component. 
+
+
+These were only two basic usages of translators on the Hurd. We're sure you'll quickly see many other ways to use this. 
+
+As a last comment: You can setup a translator on any node you have access to, so you can for example mount any filesystems as normal user. 
+
+You might currently be logged in as root, but you could just as well do the same as normal user. 
+
+Why don't you try it out? 
diff --git a/hurd/running.mdwn b/hurd/running.mdwn
index a51b40cf..b9b50fc0 100644
--- a/hurd/running.mdwn
+++ b/hurd/running.mdwn
@@ -17,7 +17,6 @@ There are several different ways to run a GNU/Hurd system:
 * [[QEMU]] - In QEMU
 * [[VirtualBox]] - In VirtualBox
 * [[vmware]] (**non-free!**)
-* [[FlashHurd]] - From a flash stick
 
 * [[FAQ]]
 
diff --git a/hurd/running/qemu.mdwn b/hurd/running/qemu.mdwn
index 4766b2be..9f085d24 100644
--- a/hurd/running/qemu.mdwn
+++ b/hurd/running/qemu.mdwn
@@ -60,6 +60,9 @@ Check if your CPU supports kvm:
 
 Do not enable kernel-kqemu, as that assumes some particular behavior from the guest kernel, which we are reluctant to artificially add to gnumach.
 
+If QEMU with KVM is not available, [[Virtualbox]] reportedly has better
+performance.
+
 #### If you have hardware support (recommended):
     $ apt-get install qemu-kvm
     $ modprobe kvm
diff --git a/hurd/running/qemu/discussion.mdwn b/hurd/running/qemu/discussion.mdwn
index fd0df4c5..1ce14b01 100644
--- a/hurd/running/qemu/discussion.mdwn
+++ b/hurd/running/qemu/discussion.mdwn
@@ -50,3 +50,95 @@ The problem is actually that the linux block cache doesn't make any consistency
 between /dev/hda and /dev/hda6, so if you give /dev/hda to qemu, qemu writings
 won't be consistent with mounting /dev/hda6 in linux. You can give /dev/hda6
 directly to qemu and it will be fine.
+
+
+# Host-side Writeback Caching
+
+IRC, freenode, #hurd, 2011-06-07
+
+    <braunr> hm, i guess i should have used cache=writeback with kvm before
+      starting the debian installer :/
+    <braunr> ah yes, much better
+    <braunr> this shows how poor the state of our I/O drivers and subsystem is
+      :/
+    <antrik> indeed... still no clustered pageout :-(
+    <braunr> and no I/O scheduler either
+    <braunr> although an I/O scheduler has limited value without clustered
+      pageouts
+    <braunr> since one of its goals is to pack related I/O requests together eh
+    <braunr> i wonder if the wiki mentions using cache=writeback to speed up
+      qemu performances
+    <braunr> it would help those unable to use kvm a lot
+    <braunr> and even those running kvm too
+    <braunr> kvm -m $RAM \ -monitor stdio \ -drive
+      cache=writeback,index=0,media=disk,file=hd0.img \
+    <braunr> etc..
+    <braunr> the idea is that qemu doesn't open its disk file synchronously
+    <braunr> changes are queued in the host page cache before being flushed to
+      the disk image
+    <braunr> but if you brutally close your qemu instance, you're likely to
+      loose file system consistency
+    <braunr> ext2fs will think it has committed its metadata to the disk, but
+      the disk image won't be updated synchronously
+    <braunr> on my machine (which is quite fast), my kvm has installed debian
+      like 10 times faster than without the option
+    <antrik> braunr: I don't think killing qemu should hurt in this
+      case... probably only matters when the host machine dies
+    <braunr> antrik: ah yes, right
+    <braunr> it really makes everything faster, even downloading, since I/O
+      requests aren't interleaved between networking RPCs
+    <antrik> regarding I/O sheduler... this discussion came up before, but I
+      don't remember the outcome -- doesn't the glued Linux driver actually
+      come with one?
+    <braunr> i don't remember either
+    <antrik> braunr: err... I don't think interleaving has anything to do with
+      it... I guess it's simply the fact that downloading writes the result to
+      disk, which suffers from lacking clustered pageout like everything else
+    <antrik> (my internet connection is too slow though to notice :-) )
+    <braunr> well, if there is no I/O during downloading, downloading is faster
+      :)
+
+IRC, freenode, #hurd, 2011-06-08
+
+    <braunr> youpi: does xen provide disk caching options ?
+    <youpi> through a blktap, probably
+    <braunr> ok
+
+([[microkernel/mach/gnumach/ports/Xen]], *Host-side Writeback Caching*.)
+
+    <braunr> we should find the pages mentioning qemu on the wiki and add the
+      options to enable disk image caching
+    <braunr> it really makes the hurd run a lot faster
+    <braunr> as a workaround for emulators until I/O is reworked, ofc
+
+IRC, freenode, #hurd, 2011-06-09
+
+    <gnu_srs> braunr recommends to use writeback caching with kvm. Is this
+      really recommended with the frequent crashes I experience?
+    <youpi> provided that you terminate your kvm normaly (i.e. quitting it, not
+      killing it), there should be no difference
+    <jkoenig> I think the host's stability is what matters
+    <jkoenig> the data presumably sits in linux's cache even if qemu dies
+      violently
+    <gnu_srs> But the freezes I see force me to kill kvm :-(
+    <youpi> maybe kvm doesn't even do caching indeed, I don't know
+    <youpi> gnu_srs: you can quit even when frozen
+    <youpi> use the console
+    <youpi> (the kvm console)
+    <jkoenig> gnu_srs, "Writeback caching will report data writes as completed
+      as soon as the data is present in the host page cache.  This is safe as
+      long as you trust your host.  If your host crashes or loses power, then
+      the guest may experience data corruption." (from the qemu manpage)
+
+IRC, freenode, #hurd, 2011-06-11
+
+    <gnu_srs> braunr: If you are online. For me setting the parameters -drive
+      cache=writeback,index=0,media=disk,file=hd0.img does not show any speed
+      improvement at all compared to the default.
+    <braunr> gnu_srs: what's your complete qemu command line ?
+    <gnu_srs> kvm -m 1024 -net nic,model=rtl8139 -net
+      user,hostfwd=tcp::5556-:22 -drive
+      cache=writeback,index=0,media=disk,file=hd0.img -cdrom netinst.iso
+    <braunr> what qemu version ?
+    <gnu_srs>  qemu-kvm  0.14.1+dfsg-1: Sorry, I cannot be online until
+      tomorrow again.
diff --git a/hurd/running/virtualbox.mdwn b/hurd/running/virtualbox.mdwn
index 02ab88e7..0731b8d6 100644
--- a/hurd/running/virtualbox.mdwn
+++ b/hurd/running/virtualbox.mdwn
@@ -20,3 +20,9 @@ supported.
 
 The network controller should be configured as PCnet-PCI II or PCNet-FAST III
 for instance. INTEL PRO or Paravirtualized Network do not work.
+
+
+# Performance
+
+If [[QEMU with KVM|qemu]] is not available, VirtualBox reportedly has better
+performance.
diff --git a/hurd/settrans/discussion.mdwn b/hurd/settrans/discussion.mdwn
new file mode 100644
index 00000000..c9ec4d34
--- /dev/null
+++ b/hurd/settrans/discussion.mdwn
@@ -0,0 +1,18 @@
+[[!meta copyright="Copyright © 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]]."]]"""]]
+
+[[!tag open_issue_documentation open_issue_hurd]]
+
+
+# IRC, freenode, #hurd, 2011-06-01
+
+    <antrik> ugh... I just realized why settrans -a without -f doesn't
+      generally work on filesystem translators
+    <antrik> obviously, it needs -R too!
diff --git a/hurd/translator.mdwn b/hurd/translator.mdwn
index 6f385b50..aa8b966a 100644
--- a/hurd/translator.mdwn
+++ b/hurd/translator.mdwn
@@ -63,6 +63,8 @@ Also there is an [[writing/example]] about how to write a simple translator.
 
 See some [[examples]] about how to use translators.
 
+There is a [[documentation/translator_primer]].
+
 Marcus Brinkmann has written a document about [[documentation/translators]].
 
 Here are some [[hints_about_debugging_translators|debugging/translator]]
diff --git a/hurd/translator/ext2fs.mdwn b/hurd/translator/ext2fs.mdwn
index 305576b8..fff2e74b 100644
--- a/hurd/translator/ext2fs.mdwn
+++ b/hurd/translator/ext2fs.mdwn
@@ -1,4 +1,4 @@
-[[!meta copyright="Copyright © 2007, 2008, 2010 Free Software Foundation,
+[[!meta copyright="Copyright © 2007, 2008, 2010, 2011 Free Software Foundation,
 Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
@@ -9,14 +9,20 @@ 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]]."]]"""]]
 
-# Large Stores
+# Implementation
+
+  * [[filetype]] option
+
+
+## Large Stores
 
 The `ext2fs` translator from the upstream Hurd code base can only handle file
 systems with sizes of less than roughly 2 GiB.
 
 [[!tag open_issue_hurd]]
 
-## Ognyan's Work
+
+### Ognyan's Work
 
   * Ognyan Kulev, [[*Supporting Large ext2 File Systems in the
     Hurd*|ogi-fosdem2005.mgp]], 2005, at FOSDEM
@@ -34,4 +40,6 @@ small backend stores, like floppy devices.
 
 # Documentation
 
-<http://www.nongnu.org/ext2-doc/>
+  * <http://e2fsprogs.sourceforge.net/ext2.html>
+
+  * <http://www.nongnu.org/ext2-doc/>
diff --git a/hurd/translator/ext2fs/filetype.mdwn b/hurd/translator/ext2fs/filetype.mdwn
new file mode 100644
index 00000000..5d85bac9
--- /dev/null
+++ b/hurd/translator/ext2fs/filetype.mdwn
@@ -0,0 +1,33 @@
+[[!meta copyright="Copyright © 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]]."]]"""]]
+
+The *ext2fs* translator doesn't support the ext2 format's *filetype* option.
+
+According to *mke2fs(8)*:
+
+> **filetype**: Store file type information in directory entries.
+
+By setting directory listings' informational `d_type` field (`readdir`, etc.),
+this may avoid the need for subsequent `stat` calls.
+
+Not all file systems can support this option.
+
+In `[hurd]/ext2fs/dir.c` the `EXT2_FEATURE_INCOMPAT_FILETYPE` is generally
+masked out (is not even considered) when adding a node to a directory in
+`diskfs_direnter_hard` and when reading in `diskfs_get_directs`.  The Hurd's
+ext2fs unconditionally sets this field to 0 (`EXT2_FT_UNKNOWN`).
+
+
+# `e2fsck`
+
+Running `e2fsck` on a file system with the *filetype* option, will correct the
+*filetype* for a lot of files (all `EXT2_FT_UNKNOWN`?) to either 1 (regular
+file, `EXT2_FT_REG_FILE`), or 2 (directory, `EXT2_FT_DIR`), and likely others.
+The Hurd's ext2fs will again ignore these fields, of course.