doc: documented new build steps

doc/wrs-build.in

@@ -349,35 +349,47 @@ save @i{stdout} to a file, like this:
    /path/to/wr-switch-sw/build/wrs_build-all > logfile
 @end example
 
-The progress messages look like what is shown here below.  The log
-file will be rather big, as all the compilation steps are quite
-verbose.
-
 Please note that there are also a number of warning messages being
 printed to @i{stderr}. It's a few hundred lines over the few dozen
 minutes it takes to build @i{buildroot}, but you can safely ignore them,
 trusting the build process will complete successfully.
 
+@b{Warning:} there is especially one hairy message being returned
+by @i{wget} if you are using the @i{ohwr} repository: @code{ERROR 500:
+Internal Server Error}. Please ignore this message, as it is about
+a file that is not being used (nor explicitly looked for, actually).
+Arranging for the message to be removed would have unpleasant side
+effects, and you are not expected to lack a local copy in any case.
+
+The progress messages look like what is shown here below.  The log
+file will be rather big, as all the compilation steps are quite
+verbose.
+
 @smallexample
-2011-05-11 20:05:57: --- Buildroot compiler and filesystem
-2011-05-11 20:05:57: Looking for file buildroot-2009.11.tar.bz2
-2011-05-11 20:05:57: Skip download of buildroot-2009.11.tar.bz2
-2011-05-11 20:06:10: Copied packages from /opt/ohwr-svn/white-rabbit/trunk/pkg/buildroot-pkg
-2011-05-11 20:06:10: Hardlinked packages from downloads to build place
-2011-05-11 20:23:51: --- AT91Boot
-2011-05-11 20:23:51: Looking for file AT91Bootstrap1.11.zip
-2011-05-11 20:23:51: Skip download of AT91Bootstrap1.11.zip
-2011-05-11 20:23:51: Patching AT91Boot
-2011-05-11 20:23:51: Building AT91Boot
-2011-05-11 20:23:51: --- U-Boot
-2011-05-11 20:23:51: Looking for file u-boot-1.3.4.tar.bz2
-2011-05-11 20:23:52: Skip download of u-boot-1.3.4.tar.bz2
-2011-05-11 20:23:55: Patching U-Boot
-2011-05-11 20:23:58: Building U-Boot
-2011-05-11 20:24:17: --- Linux kernel for switch
-2011-05-11 20:24:17: Looking for file buildroot-pkg/linux-2.6.35.tar.bz2
-2011-05-11 20:24:19: Skip download of buildroot-pkg/linux-2.6.35.tar.bz2
-2011-05-11 20:26:42: Complete build succeeded, apparently
+2011-05-18 00:26:45: --- Buildroot compiler and filesystem
+2011-05-18 00:26:45: Looking for file buildroot-2009.11.tar.bz2
+2011-05-18 00:26:45: Skip download of buildroot-2009.11.tar.bz2
+2011-05-18 00:26:58: Copied packages from /opt/ohwr-svn/white-rabbit/trunk/pkg/buildroot-pkg
+2011-05-18 00:26:58: Hardlinked packages from downloads to build place
+2011-05-18 00:43:41: --- AT91Boot
+2011-05-18 00:43:41: Looking for file AT91Bootstrap1.11.zip
+2011-05-18 00:43:42: Skip download of AT91Bootstrap1.11.zip
+2011-05-18 00:43:42: Patching AT91Boot
+2011-05-18 00:43:42: Building AT91Boot
+2011-05-18 00:43:42: --- U-Boot
+2011-05-18 00:43:42: Looking for file u-boot-1.3.4.tar.bz2
+2011-05-18 00:43:43: Skip download of u-boot-1.3.4.tar.bz2
+2011-05-18 00:43:45: Patching U-Boot
+2011-05-18 00:43:49: Building U-Boot
+2011-05-18 00:44:05: --- Linux kernel for switch
+2011-05-18 00:44:05: Looking for file buildroot-pkg/linux-2.6.35.tar.bz2
+2011-05-18 00:44:07: Skip download of buildroot-pkg/linux-2.6.35.tar.bz2
+2011-05-18 00:46:38: --- Kernel modules from this package
+2011-05-18 00:46:43: --- PTP daemon (noposix repository)
+2011-05-18 00:46:43: Using local git repository
+2011-05-18 00:46:45: --- User space tools
+2011-05-18 00:46:46: --- Wrapping filesystem
+2011-05-18 00:46:47: Complete build succeeded, apparently
 @end smallexample
 
 You may prefer to save @i{stderr} with @i{stdout} to the log file
@@ -398,7 +410,10 @@ you've found a bug in the build scripts; most likely because your
 setup differs from the ones we have been testing on.
 
 In order to re-run the build from the beginning, please remove (or
-rename) the output directory and re-run.
+rename) the output directory and reissue the command.  To only
+redo one step, you can remove the marker in @code{build/_done}
+(the markers are empty files with name like @code{00-buildroot}
+and @code{03-kernel}).
 
 @c ##########################################################################
 @node The Compiler
@@ -518,17 +533,89 @@ package.  The step depends on the kernel being available in the
 build directory. The modules are then copied into the @code{images}
 subdirectory of the main build directory.
 
+Please note that modules (and later user-space) are compiled in-place,
+not in the output directory.  The disadvantage is that your repository
+becomes dirty with output and intermediate files; the advantage is that
+any modification you make to the code is already in the repository
+for your to commit.
+
+@c ##########################################################################
+@node PTPd
+@chapter PTPd
+
+The Precision Time Protocol Daemon being used is host in a different
+repository. It's the code base that has been ported to compile in a
+freestanding environment, downloaded from
+@code{git://gnudd.com/ptp-noposix.git} .
+
+A plain @i{make} in the directory will fail, because after building
+@i{ptpd} other steps are tried, but they are only needed for
+the freestanding environment (i.e., LM32 with supporting code) and will
+fail for this @i{arm-linux} hosted build.
+
+Additionally, the script installs the header and library for
+@i{wr_ipc}, which are needed for later steps and are now part of the
+@i{ptp} repository. Similarly, the script installs headers for the hal
+and @i{libptpnetif}.
+
+The script is known to work with version @code{fea09f7} of the @i{git}
+repository, but the script checks out the @i{master} branch, being
+confident newer versions will be at least as good as the current one
+(for example, the current version as I write this has some concerning
+warning messages).
+
 @c ##########################################################################
-@node User Space Tools
-@chapter User Space Tools
+@node User Space Applications
+@chapter User Space Applications
 
-Not compiled by this package, yet.
+The build of user space is concerned about the following steps:
+
+@table @i
+@item 3rdparty
+	The directory includes the @i{lua} tool, used in the switch
+        to parse the configuration file.
+
+@item libswitchhw 
+	This is a library of functions needed by the next
+        step. @code{libswitchhw.a} is thus installed in @code{images/wr/lib}.
+
+@item wrsw_hal
+	This is the main application program for the White Rabbit Switch
+        operation. The script installs the executable in @code{images/wr/bin}.
+
+@item wrsw_rtud
+	This is the daemon for the routing table unit, installed in
+        @code{images/wr/bin}.
+
+@end table
+
+@c ##########################################################################
+@node VHDL Binaries
+@chapter VHDL Binaries
+
+The binaries are currently missing from the filesystem-making procedures.
 
 @c ##########################################################################
 @node The Complete Filesystem
 @chapter The Complete Filesystem
 
-Not compiled by this package, yet.
+The final step in compiling the filesystem is making the CPIO archive
+to be used as @i{ramdisk} in the switch.  The name of the file
+@code{images/ramdisk.ext2} within the @code{WRS_BUILD_DIR}, even if
+it has nothing to do with an @i{ext2} filesystem.  The name, however,
+is the predefined one in @i{u-boot} configuration; so until we
+change @i{u-boot}, it's easier for the image to keep this older name.
+
+The filesystem is built by copying the @i{buildroot} file tree and
+overlaying it with @code{userspace/rootfs_override/}; device files
+are extracted from @code{userspace/devices.tar.gz}.
+
+The @i{root} user has an empty password (set forth in
+@code{userspace/rootfs_override/}) and authorizes a few @i{ssh} keys,
+to allow @i{ssh} login (and @i{scp}) without the need to provide a
+password -- though empty.  The script authorizes the key of the user
+running the script and all keys listed in the file @code{authorized_keys}
+in the main directory of this package, if present.
 
 @c ##########################################################################
 @iftex
@@ -542,4 +629,5 @@ Not compiled by this package, yet.
 @c  LocalWords:  LocalWords ietf timestamp misc timestamps ttstamp onestamp
 @c  LocalWords:  Tomasz Wlostowski buildroot distclean defconfig wrswitch REPO
 @c  LocalWords:  menuconfig config dataflash whiterabbit stdout stderr svnsync
-@c  LocalWords:  filesystem diff ohwr http mkdir linux rubini itemize
+@c  LocalWords:  filesystem diff ohwr http mkdir linux rubini itemize PTPd VHDL
+@c  LocalWords:  noposix ptpd userspace libswitchhw