From 321b29458db1fd7fd7e63e652d3c93622750155b Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Fri, 10 Jun 2011 22:43:24 +0200
Subject: dde/guide: add intro

---
 hurd/dde/guide.mdwn | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index 56f7683c..ffff601d 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,6 +8,18 @@ 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]]."]]"""]]
 
+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.
+
+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.
+
 If you haven't: install hurd to partition
 get grub image
 boot hurd in single user (change grub entry accordingly to the installed partition)
-- 
cgit v1.2.3


From 05ae27c5a7a0ec2131444d5d295f7f5c1c2c7a1f Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Fri, 10 Jun 2011 22:47:12 +0200
Subject: dde/guide: Drop section about installing Hurd

It's really out of place here.

Add a note in the intro.
---
 hurd/dde/guide.mdwn | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index ffff601d..76515dc7 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -19,16 +19,10 @@ 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.
 
-If you haven't: install hurd to partition
-get grub image
-boot hurd in single user (change grub entry accordingly to the installed partition)
-
-> $ export TERM=mach
-
-> $ ./native-install
-
-reboot to other debian
+Start by booting into Debian GNU/Linux for some preparations:
 
 suppose hurd partition is hdd1
 
-- 
cgit v1.2.3


From eb6338481fca495448aaa7f84d52961e864ab04e Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Fri, 10 Jun 2011 23:40:08 +0200
Subject: dde/guide: Drop section about resolv.conf

Again, not the right place for this.
---
 hurd/dde/guide.mdwn | 4 ----
 1 file changed, 4 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index 76515dc7..39390add 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -152,8 +152,4 @@ reboot to hurd with the new gnumach_dde
 
 replace the ip, gateway and mask with your own ones
 
-> $ nano /etc/resolv.conf
-
-add line: nameserver 192.168.1.254
-
 DONE
-- 
cgit v1.2.3


From 5e4d2daf11d94a68d37899f6a62ab10f83867f80 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Fri, 10 Jun 2011 23:49:23 +0200
Subject: dde/guide: Rewrite comments for clarity

---
 hurd/dde/guide.mdwn | 62 +++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 46 insertions(+), 16 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index 39390add..f67817fb 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -22,13 +22,12 @@ The whole process is much more cumbersome otherwise.
 It also assumes that apart from networking,
 your Hurd system is already installed and operational.
 
-Start by booting into Debian GNU/Linux for some preparations:
 
-suppose hurd partition is hdd1
+Start by booting into Debian GNU/Linux for some preparations:
 
-as root
+(as root)
 
-> $ mount /dev/hdd1 /mnt -t ext2
+> $ mount /dev/hdd1 /mnt -t ext2 # assuming your Hurd partition is hdd1 -- replace with whatever matches your setup
 
 > $ cd /mnt/etc/apt
 
@@ -61,12 +60,27 @@ as root
 > $ git clone git://git.sv.gnu.org/hurd/gnumach.git -b master-user_level_drivers gnumach_dde
 
 
-suppose you need forcedeth driver
+Now you need to get the actual driver from the Linux source tree.
+You have to find out which Linux driver
+is responsible for your network card,
+and which source file corresponds to this driver.
+In this guide we will use the forcedeth driver
+(for Nvidia nForce chipsets) as example.
+
+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
+and save under the file name forcedeth.c in /mnt/home
+
+(Note: the download from the Git URL above
+doesn't work with wget
+or other simple user agents without JavaScript.
+You will need to use Firefox or some such...
+Or figure out a better URL to get the file directly :-) )
 
-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
 
-reboot back to hurd (multiuser)
+Now everything should be in place,
+so we can boot into Hurd to do the actual work:
+
+(again as root)
 
 > $ apt-get update
 
@@ -79,6 +93,8 @@ reboot back to hurd (multiuser)
 > $ apt-get install build-essential libpciaccess-dev libpcap0.8-dev
 
 
+(this part can be done as normal user)
+
 > $ cd /home/gnumach_dde
 
 > $ autoreconf -i && ./configure --enable-kdb --enable-device-drivers=none --enable-lpr --enable-floppy --enable-ide
@@ -103,9 +119,7 @@ reboot back to hurd (multiuser)
 
 > $ sed -i 's:-I/include:-I..:' Makefile
 
-> $ nano forcedeth.c
-
-add this line after the last #include
+> $ 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>
 
@@ -131,6 +145,8 @@ add this line after the last #include
 
 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*)
 
+(as root)
+
 > $ cp /home/gnumach_dde/gnumach /boot/gnumach_dde
 
 > $ mkdir /hurd/dde
@@ -141,15 +157,29 @@ If the make fails it might be necassary to replace some of the -l options (or al
 
 > $ cp /home/hurd_dde/dde_forcedeth/dde_forcedeth /hurd/dde/forcedeth
 
-reboot to hurd with the new gnumach_dde
+
+Now everything should be built.
+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.)
+Once there, set up the translators for the driver:
+
+(as root)
 
 > $ settrans -c /dev/forcedeth /hurd/dde/forcedeth
 
 > $ settrans -c /dev/eth0 /hurd/dde/devnode -M /dev/forcedeth eth0
 
-> $ 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 
-
+Finally, we can set up the actual network translator,
+using something like:
 
-replace the ip, gateway and mask with your own ones
+> $ 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.
-- 
cgit v1.2.3


From ec7b41aca85ba0e3d326ce8796f321e5a169086f Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Sat, 11 Jun 2011 10:47:49 +0200
Subject: dde/guide: Better way to download driver file

---
 hurd/dde/guide.mdwn | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index f67817fb..e3fcf2e5 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -67,15 +67,13 @@ and which source file corresponds to this driver.
 In this guide we will use the forcedeth driver
 (for Nvidia nForce chipsets) as example.
 
-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
-and save under the file name forcedeth.c in /mnt/home
+Point a (JavaScript-capable) web browser at
 
-(Note: the download from the Git URL above
-doesn't work with wget
-or other simple user agents without JavaScript.
-You will need to use Firefox or some such...
-Or figure out a better URL to get the file directly :-) )
+> http://git.kernel.org/?p=linux/kernel/git/stable/linux-2.6.29.y.git;a=tree;f=drivers/net;hb=HEAD
 
+Find the right file to download (e.g. forcedeth.c),
+hit the "raw" link,
+and save the resulting file (page) to /mnt/home
 
 Now everything should be in place,
 so we can boot into Hurd to do the actual work:
-- 
cgit v1.2.3


From 4db957304bb6d882933617ec70b38d80758df1e3 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Wed, 6 Jul 2011 08:38:24 +0200
Subject: dde/guide: Drop "apt-get upgrade"

This has nothing to do with DDE; and I don't see why it would be
necessary here -- the DDE stuff doesn't need any recent packages to
build AFAIK.
---
 hurd/dde/guide.mdwn | 4 ----
 1 file changed, 4 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index e3fcf2e5..f275c9d7 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -45,8 +45,6 @@ Start by booting into Debian GNU/Linux for some preparations:
 
 > $ apt-get -c etc/apt/apt.conf.offline update
 
-> $ apt-get -c etc/apt/apt.conf.offline upgrade
-
 > $ apt-get -c etc/apt/apt.conf.offline install git-core
 
 > $ apt-get -c etc/apt/apt.conf.offline build-dep hurd gnumach
@@ -82,8 +80,6 @@ so we can boot into Hurd to do the actual work:
 
 > $ apt-get update
 
-> $ apt-get upgrade
-
 > $ apt-get install git-core
 
 > $ apt-get build-dep hurd gnumach
-- 
cgit v1.2.3


From b4495b7195d2d794b89c6150194a09eea32fc559 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Wed, 6 Jul 2011 08:50:16 +0200
Subject: dde/guide: Drop "apt-get update" in Hurd

I'm pretty sure it is neither possible nor necessary with the apt
offline setup.
---
 hurd/dde/guide.mdwn | 2 --
 1 file changed, 2 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index f275c9d7..74962222 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -78,8 +78,6 @@ so we can boot into Hurd to do the actual work:
 
 (again as root)
 
-> $ apt-get update
-
 > $ apt-get install git-core
 
 > $ apt-get build-dep hurd gnumach
-- 
cgit v1.2.3


From ff99222cc9af6b4f52e5af909f9b3bd8b598d7c2 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Wed, 6 Jul 2011 08:53:49 +0200
Subject: dde/guide: Merge install command for git-core with other packages

---
 hurd/dde/guide.mdwn | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index 74962222..d6dffb85 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -45,11 +45,9 @@ Start by booting into Debian GNU/Linux for some preparations:
 
 > $ 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 install build-essential libpciaccess-dev libpcap0.8-dev
+> $ apt-get -c etc/apt/apt.conf.offline install git-core build-essential libpciaccess-dev libpcap0.8-dev
 
 > $ cd /mnt/home
 
@@ -78,11 +76,9 @@ so we can boot into Hurd to do the actual work:
 
 (again as root)
 
-> $ apt-get install git-core
-
 > $ apt-get build-dep hurd gnumach
 
-> $ apt-get install build-essential libpciaccess-dev libpcap0.8-dev
+> $ apt-get install git-core build-essential libpciaccess-dev libpcap0.8-dev
 
 
 (this part can be done as normal user)
-- 
cgit v1.2.3


From 8874ec5fa546ccd5132a30d64dd5364ab6b0b529 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Wed, 6 Jul 2011 09:58:03 +0200
Subject: dde/guide: Add many more explanations

---
 hurd/dde/guide.mdwn | 60 +++++++++++++++++++++++++++++++++--------------------
 1 file changed, 37 insertions(+), 23 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index d6dffb85..1418638c 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -23,15 +23,18 @@ It also assumes that apart from networking,
 your Hurd system is already installed and operational.
 
 
-Start by booting into Debian GNU/Linux for some preparations:
+We start by booting into Debian GNU/Linux,
+so we can downloading everything we will need for building DDE.
 
-(as root)
+Once there, first mount the Hurd partition (as root):
 
 > $ mount /dev/hdd1 /mnt -t ext2 # assuming your Hurd partition is hdd1 -- replace with whatever matches your setup
 
+Prepare apt offline configuration so we can get necessary packages:
+
 > $ 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
 
@@ -41,6 +44,8 @@ Start by booting into Debian GNU/Linux for some preparations:
 
 > $ wget http://www.gnu.org/software/hurd/hurd/running/debian/DebianAptOffline/apt.conf.offline
 
+Download the packages for offline installation:
+
 > $ cd /mnt
 
 > $ apt-get -c etc/apt/apt.conf.offline update
@@ -49,13 +54,14 @@ Start by booting into Debian GNU/Linux for some preparations:
 
 > $ apt-get -c etc/apt/apt.conf.offline install git-core build-essential libpciaccess-dev libpcap0.8-dev
 
+Get DDE code:
+
 > $ cd /mnt/home
 
 > $ git clone git://git.sv.gnu.org/hurd/incubator.git -b dde hurd_dde
 
 > $ git clone git://git.sv.gnu.org/hurd/gnumach.git -b master-user_level_drivers gnumach_dde
 
-
 Now you need to get the actual driver from the Linux source tree.
 You have to find out which Linux driver
 is responsible for your network card,
@@ -71,17 +77,17 @@ Find the right file to download (e.g. forcedeth.c),
 hit the "raw" link,
 and save the resulting file (page) to /mnt/home
 
+
 Now everything should be in place,
-so we can boot into Hurd to do the actual work:
+so we can boot into Hurd to do the actual work.
 
-(again as root)
+Once there, install the packages previously downloaded (again as root):
 
 > $ apt-get build-dep hurd gnumach
 
 > $ apt-get install git-core build-essential libpciaccess-dev libpcap0.8-dev
 
-
-(this part can be done as normal user)
+Build a DDE-enabled Mach (this and following parts can be done as normal user):
 
 > $ cd /home/gnumach_dde
 
@@ -89,23 +95,25 @@ so we can boot into Hurd to do the actual work:
 
 > $ make
 
+Prepare the driver for your network card:
+
 > $ cd ../hurd_dde
 
-> $ cp -r dde_pcnet32 dde_forcedeth
+> $ cp -r dde_pcnet32 dde_forcedeth # using pcnet32 as template
 
 > $ cd dde_forcedeth
 
-> $ rm pcnet32.c
+> $ rm pcnet32.c # don't want the actual pcnet32 code here...
 
-> $ cp /home/forcedeth.c ./
+> $ cp /home/forcedeth.c ./ # ...but rather the forcedeth code
 
-> $ sed -i 's/pcnet32/forcedeth/g' Makefile
+> $ 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
+> $ 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
+> $ 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:
 
@@ -113,27 +121,34 @@ so we can boot into Hurd to do the actual work:
 
 > $ cd ..
 
+Commit the 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 commit -a -m 'Add forcedeth driver'
 
+Build the necessary Hurd and DDE bits:
+
 > $ autoreconf -i && ./configure
 
-> $ mkdir -p hurd/include/ddekit
+> $ mkdir -p hurd/include/ddekit # workaround for a buildsystem bug... XXX I'm pretty sure this is not necessary anymore
 
-> $ make libddekit libmachdev devnode pfinet
+> $ make libddekit libmachdev devnode pfinet # Hurd components
 
-> $ cd libdde_linux26
+> $ cd libdde_linux26 # common DDE driver code -- uses a different Makefile system than the Hurd components!
 
 > $ make
 
-> $ cd ../dde_forcedeth
+> $ cd ../dde_forcedeth # actual driver
 
 > $ 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*)
+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*) XXX
 
-(as root)
+Install the various built components to their final destinations (as root):
 
 > $ cp /home/gnumach_dde/gnumach /boot/gnumach_dde
 
@@ -146,16 +161,15 @@ If the make fails it might be necassary to replace some of the -l options (or al
 > $ cp /home/hurd_dde/dde_forcedeth/dde_forcedeth /hurd/dde/forcedeth
 
 
-Now everything should be built.
+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.)
-Once there, set up the translators for the driver:
 
-(as root)
+Once there, set up the translators for the driver (as root):
 
 > $ settrans -c /dev/forcedeth /hurd/dde/forcedeth
 
-- 
cgit v1.2.3


From 425b9fc977ff09b9fd8a10eaaa5406f6bc329c67 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Wed, 6 Jul 2011 11:03:02 +0200
Subject: dde/guide: Be clearer about requirement for creating new driver

Explain that it is only necessary to create a new driver if an
appropriate one isn't in DDE already; and mention which steps are
necessary only in this case.

Also be explicit about the fact that this guide only deals with
single-file drivers.
---
 hurd/dde/guide.mdwn | 37 ++++++++++++++++++++++++++++---------
 1 file changed, 28 insertions(+), 9 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index 1418638c..c4ff1772 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -62,21 +62,36 @@ Get DDE code:
 
 > $ git clone git://git.sv.gnu.org/hurd/gnumach.git -b master-user_level_drivers gnumach_dde
 
-Now you need to get the actual driver from the Linux source tree.
-You have to find out which Linux driver
-is responsible for your network card,
-and which source file corresponds to this 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.
+
+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:
 
 Point a (JavaScript-capable) web browser at
 
 > http://git.kernel.org/?p=linux/kernel/git/stable/linux-2.6.29.y.git;a=tree;f=drivers/net;hb=HEAD
 
-Find the right file to download (e.g. forcedeth.c),
-hit the "raw" link,
+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
 
+(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...)
+
 
 Now everything should be in place,
 so we can boot into Hurd to do the actual work.
@@ -95,7 +110,9 @@ Build a DDE-enabled Mach (this and following parts can be done as normal user):
 
 > $ make
 
-Prepare the driver for your network card:
+
+If not already present in DDE,
+we need to prepare the driver for the network card:
 
 > $ cd ../hurd_dde
 
@@ -121,7 +138,7 @@ Prepare the driver for your network card:
 
 > $ cd ..
 
-Commit the driver with git.
+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:
@@ -130,7 +147,9 @@ and/or upstream submission:
 
 > $ git commit -a -m 'Add forcedeth driver'
 
-Build the necessary Hurd and DDE bits:
+
+Having prepared the driver,
+we can now build the necessary Hurd and DDE bits:
 
 > $ autoreconf -i && ./configure
 
-- 
cgit v1.2.3


From 94fab8bd64b2f1821b5f15b137086d51c42bac8d Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Thu, 7 Jul 2011 09:10:05 +0200
Subject: dde/guide: Don't abuse /home/

Put stuff in an actual user home directory, rather than stuffing it
directly in /home/
---
 hurd/dde/guide.mdwn | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index c4ff1772..4f455790 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -56,11 +56,13 @@ Download the packages for offline installation:
 
 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
 
 Now comes the tricky part:
 you need to find out
@@ -85,7 +87,7 @@ Point a (JavaScript-capable) web browser at
 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
+and save the resulting file (page) to /mnt/home/me/dde
 
 (If you happen to need one of the few drivers
 that consist of more than one source file,
@@ -104,7 +106,7 @@ Once there, install the packages previously downloaded (again as root):
 
 Build a DDE-enabled Mach (this and following parts can be done as normal user):
 
-> $ cd /home/gnumach_dde
+> $ cd ~me/dde/gnumach
 
 > $ autoreconf -i && ./configure --enable-kdb --enable-device-drivers=none --enable-lpr --enable-floppy --enable-ide
 
@@ -114,7 +116,7 @@ Build a DDE-enabled Mach (this and following parts can be done as normal user):
 If not already present in DDE,
 we need to prepare the driver for the network card:
 
-> $ cd ../hurd_dde
+> $ cd ~me/dde/hurd
 
 > $ cp -r dde_pcnet32 dde_forcedeth # using pcnet32 as template
 
@@ -122,7 +124,7 @@ we need to prepare the driver for the network card:
 
 > $ rm pcnet32.c # don't want the actual pcnet32 code here...
 
-> $ cp /home/forcedeth.c ./ # ...but rather the forcedeth code
+> $ cp ~me/dde/forcedeth.c ./ # ...but rather the forcedeth code
 
 > $ sed -i 's/pcnet32/forcedeth/g' Makefile # adapt Makefile accordingly
 
@@ -169,15 +171,17 @@ If the make fails it might be necassary to replace some of the -l options (or al
 
 Install the various built components to their final destinations (as root):
 
-> $ cp /home/gnumach_dde/gnumach /boot/gnumach_dde
+> $ cd ~me/dde/
+
+> $ cp gnumach/gnumach /boot/gnumach_dde
 
 > $ mkdir /hurd/dde
 
-> $ cp /home/hurd_dde/devnode/devnode /hurd/dde
+> $ cp hurd/devnode/devnode /hurd/dde
 
-> $ cp /home/hurd_dde/pfinet/pfinet /hurd/dde
+> $ cp hurd/pfinet/pfinet /hurd/dde
 
-> $ cp /home/hurd_dde/dde_forcedeth/dde_forcedeth /hurd/dde/forcedeth
+> $ cp hurd/dde_forcedeth/dde_forcedeth /hurd/dde/forcedeth
 
 
 Now everything should be ready.
-- 
cgit v1.2.3


From 88537e912dff92178e0b1da744f2f63fc7925e12 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Thu, 7 Jul 2011 09:34:26 +0200
Subject: dde/guide: Be more explicit about building as user

Instead of just vaguely stating that things can be done as user,
explicitely suggest logging in as user.

More importantly, include the chown command necessary for this actually
to work...
---
 hurd/dde/guide.mdwn | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index 4f455790..16c248ae 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -104,7 +104,13 @@ Once there, install the packages previously downloaded (again as root):
 
 > $ apt-get install git-core build-essential libpciaccess-dev libpcap0.8-dev
 
-Build a DDE-enabled Mach (this and following parts can be done as normal user):
+Make sure we can build stuff as normal user:
+
+> $ chown -R me ~me/dde
+
+Now you can log in with the normal user account to build stuff.
+
+Build a DDE-enabled Mach:
 
 > $ cd ~me/dde/gnumach
 
-- 
cgit v1.2.3


From 81cd1343c95216ddc3086656f87b29707c18af86 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Thu, 7 Jul 2011 09:37:31 +0200
Subject: dde/guide: Drop unnecessary trailing slash

Explicitely using "./" instead of just "." is necessary only in some
very special situations... This in not one of them. So use the simpler
and more familiar form.
---
 hurd/dde/guide.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index 16c248ae..4264f7ad 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -130,7 +130,7 @@ we need to prepare the driver for the network card:
 
 > $ rm pcnet32.c # don't want the actual pcnet32 code here...
 
-> $ cp ~me/dde/forcedeth.c ./ # ...but rather the forcedeth code
+> $ cp ~me/dde/forcedeth.c . # ...but rather the forcedeth code
 
 > $ sed -i 's/pcnet32/forcedeth/g' Makefile # adapt Makefile accordingly
 
-- 
cgit v1.2.3


From 699f4c1a555bed70f8890ce7461e7422ca116db4 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Thu, 7 Jul 2011 10:18:31 +0200
Subject: dde/guide: Don't rename driver binary upon install

I don't see any use in that; it only creates potential confusion and
other problems.
---
 hurd/dde/guide.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index 4264f7ad..10a2b727 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -187,7 +187,7 @@ Install the various built components to their final destinations (as root):
 
 > $ cp hurd/pfinet/pfinet /hurd/dde
 
-> $ cp hurd/dde_forcedeth/dde_forcedeth /hurd/dde/forcedeth
+> $ cp hurd/dde_forcedeth/dde_forcedeth /hurd/dde
 
 
 Now everything should be ready.
-- 
cgit v1.2.3


From 00f52298039e1db2f469834fb9f8c31d6e022faa Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Thu, 7 Jul 2011 10:20:49 +0200
Subject: dde/guide: Install all Hurd bits in one "cp" command

---
 hurd/dde/guide.mdwn | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index 10a2b727..89422625 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -183,11 +183,7 @@ Install the various built components to their final destinations (as root):
 
 > $ mkdir /hurd/dde
 
-> $ cp hurd/devnode/devnode /hurd/dde
-
-> $ cp hurd/pfinet/pfinet /hurd/dde
-
-> $ cp hurd/dde_forcedeth/dde_forcedeth /hurd/dde
+> $ cp hurd/devnode/devnode hurd/pfinet/pfinet hurd/dde_forcedeth/dde_forcedeth /hurd/dde
 
 
 Now everything should be ready.
-- 
cgit v1.2.3


From 04a7d787d0372ee1406ff626826ffc7f8a336cd3 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Thu, 7 Jul 2011 10:38:57 +0200
Subject: dde/guide: Add note about Linux version

---
 hurd/dde/guide.mdwn | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index 89422625..eeb25ae1 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -84,6 +84,9 @@ Point a (JavaScript-capable) web browser at
 
 > http://git.kernel.org/?p=linux/kernel/git/stable/linux-2.6.29.y.git;a=tree;f=drivers/net;hb=HEAD
 
+(Note: you **have** to use 2.6.29,
+as this is the version DDE is currently based on.)
+
 Find the right file to download
 (forcedeth.c in this example);
 then hit the "raw" link,
-- 
cgit v1.2.3


From 22fd6914758fe7f049fe39b71297a0874b8d6150 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Thu, 7 Jul 2011 10:45:13 +0200
Subject: dde/guide: Drop extra note about possibly necessary Makefile changes

Even if it should turn out this is not completely obsolete (which I'm
pretty sure it is), the specific cases are already covered in the
instructions; and if any new should pop up, the guide needs to be
updated accordingly. Making the user guess just doesn't fit with such a
step-by-step guide.
---
 hurd/dde/guide.mdwn | 2 --
 1 file changed, 2 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index eeb25ae1..e3588335 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -176,8 +176,6 @@ we can now build the necessary Hurd and DDE bits:
 
 > $ 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*) XXX
-
 Install the various built components to their final destinations (as root):
 
 > $ cd ~me/dde/
-- 
cgit v1.2.3


From a8e3de8d7b9237e69346fcf44010a41d5da08c8e Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Sat, 9 Jul 2011 12:41:54 +0200
Subject: dde/guide: Use tabs instead of quote marks

This way we lose the indentation -- but special characters are escaped
automatically. Also, the commands appear in monospace font (as <pre>
blocks) this way, which I think is better.

There might be some prettier option -- but I'm too lazy to check :-) The
formatting of the whole thing is not exactly good anyways...
---
 hurd/dde/guide.mdwn | 98 ++++++++++++++++++++++++++---------------------------
 1 file changed, 49 insertions(+), 49 deletions(-)

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn
index e3588335..31671308 100644
--- a/hurd/dde/guide.mdwn
+++ b/hurd/dde/guide.mdwn
@@ -28,41 +28,41 @@ so we can downloading everything we will need for building DDE.
 
 Once there, first mount the Hurd partition (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 # assuming your Hurd partition is hdd1 -- replace with whatever matches your setup
 
 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 # if you don't have sources.list set up yet on the Hurd system
+	$ 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
 
 Download the packages for offline installation:
 
-> $ cd /mnt
+	$ cd /mnt
 
-> $ apt-get -c etc/apt/apt.conf.offline update
+	$ apt-get -c etc/apt/apt.conf.offline update
 
-> $ 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 git-core build-essential libpciaccess-dev libpcap0.8-dev
 
 Get DDE code:
 
-> $ cd /mnt/home/me # assuming your user name on the Hurd system is "me"
+	$ cd /mnt/home/me # assuming your user name on the Hurd system is "me"
 
-> $ mkdir dde && cd dde
+	$ mkdir dde && cd dde
 
-> $ git clone git://git.sv.gnu.org/hurd/incubator.git -b dde hurd
+	$ 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
+	$ git clone git://git.sv.gnu.org/hurd/gnumach.git -b master-user_level_drivers
 
 Now comes the tricky part:
 you need to find out
@@ -82,7 +82,7 @@ the right source file from Linux:
 
 Point a (JavaScript-capable) web browser at
 
-> http://git.kernel.org/?p=linux/kernel/git/stable/linux-2.6.29.y.git;a=tree;f=drivers/net;hb=HEAD
+	http://git.kernel.org/?p=linux/kernel/git/stable/linux-2.6.29.y.git;a=tree;f=drivers/net;hb=HEAD
 
 (Note: you **have** to use 2.6.29,
 as this is the version DDE is currently based on.)
@@ -103,88 +103,88 @@ so we can boot into Hurd to do the actual work.
 
 Once there, install the packages previously downloaded (again as root):
 
-> $ apt-get build-dep hurd gnumach
+	$ apt-get build-dep hurd gnumach
 
-> $ apt-get install git-core build-essential libpciaccess-dev libpcap0.8-dev
+	$ apt-get install git-core build-essential libpciaccess-dev libpcap0.8-dev
 
 Make sure we can build stuff as normal user:
 
-> $ chown -R me ~me/dde
+	$ chown -R me ~me/dde
 
 Now you can log in with the normal user account to build stuff.
 
 Build a DDE-enabled Mach:
 
-> $ cd ~me/dde/gnumach
+	$ cd ~me/dde/gnumach
 
-> $ autoreconf -i && ./configure --enable-kdb --enable-device-drivers=none --enable-lpr --enable-floppy --enable-ide
+	$ autoreconf -i && ./configure --enable-kdb --enable-device-drivers=none --enable-lpr --enable-floppy --enable-ide
 
-> $ make
+	$ make
 
 
 If not already present in DDE,
 we need to prepare the driver for the network card:
 
-> $ cd ~me/dde/hurd
+	$ cd ~me/dde/hurd
 
-> $ cp -r dde_pcnet32 dde_forcedeth # using pcnet32 as template
+	$ cp -r dde_pcnet32 dde_forcedeth # using pcnet32 as template
 
-> $ cd dde_forcedeth
+	$ cd dde_forcedeth
 
-> $ rm pcnet32.c # don't want the actual pcnet32 code here...
+	$ rm pcnet32.c # don't want the actual pcnet32 code here...
 
-> $ cp ~me/dde/forcedeth.c . # ...but rather the forcedeth code
+	$ 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' Makefile # adapt Makefile accordingly
 
-> $ sed -i 's/pcnet32/forcedeth/g' .gitignore
+	$ 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:-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
+	$ 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:
+	$ 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'
 
 
 Having prepared the driver,
 we can now build the necessary Hurd and DDE bits:
 
-> $ autoreconf -i && ./configure
+	$ autoreconf -i && ./configure
 
-> $ mkdir -p hurd/include/ddekit # workaround for a buildsystem bug... XXX I'm pretty sure this is not necessary anymore
+	$ mkdir -p hurd/include/ddekit # workaround for a buildsystem bug... XXX I'm pretty sure this is not necessary anymore
 
-> $ make libddekit libmachdev devnode pfinet # Hurd components
+	$ make libddekit libmachdev devnode pfinet # Hurd components
 
-> $ cd libdde_linux26 # common DDE driver code -- uses a different Makefile system than the Hurd components!
+	$ cd libdde_linux26 # common DDE driver code -- uses a different Makefile system than the Hurd components!
 
-> $ make
+	$ make
 
-> $ cd ../dde_forcedeth # actual driver
+	$ cd ../dde_forcedeth # actual driver
 
-> $ make
+	$ make
 
 Install the various built components to their final destinations (as root):
 
-> $ cd ~me/dde/
+	$ cd ~me/dde/
 
-> $ cp gnumach/gnumach /boot/gnumach_dde
+	$ cp gnumach/gnumach /boot/gnumach_dde
 
-> $ mkdir /hurd/dde
+	$ mkdir /hurd/dde
 
-> $ cp hurd/devnode/devnode hurd/pfinet/pfinet hurd/dde_forcedeth/dde_forcedeth /hurd/dde
+	$ cp hurd/devnode/devnode hurd/pfinet/pfinet hurd/dde_forcedeth/dde_forcedeth /hurd/dde
 
 
 Now everything should be ready.
@@ -197,14 +197,14 @@ in the boottime grub menu while testing.)
 
 Once there, set up the translators for the driver (as root):
 
-> $ settrans -c /dev/forcedeth /hurd/dde/forcedeth
+	$ settrans -c /dev/forcedeth /hurd/dde/forcedeth
 
-> $ settrans -c /dev/eth0 /hurd/dde/devnode -M /dev/forcedeth eth0
+	$ settrans -c /dev/eth0 /hurd/dde/devnode -M /dev/forcedeth eth0
 
 Finally, we can set up the actual network translator,
 using something like:
 
-> $ 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 
+	$ 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 
 
 For the exact syntax,
 see the normal network setup documentation.
-- 
cgit v1.2.3


From ee740619cc27f30c5c0a7710e740b42144804702 Mon Sep 17 00:00:00 2001
From: antrik <antrik@users.sf.net>
Date: Sun, 10 Jul 2011 03:17:02 +0200
Subject: dde/guide [discussion]: Add ToDo

---
 hurd/dde/guide/discussion.mdwn | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 hurd/dde/guide/discussion.mdwn

(limited to 'hurd/dde')

diff --git a/hurd/dde/guide/discussion.mdwn b/hurd/dde/guide/discussion.mdwn
new file mode 100644
index 00000000..b24b69e7
--- /dev/null
+++ b/hurd/dde/guide/discussion.mdwn
@@ -0,0 +1,15 @@
+[[!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:
+
+* 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
-- 
cgit v1.2.3