doc: describe upgrading from 3.x and 4.0

Signed-off-by: Alessandro Rubini <rubini@gnudd.com>

doc: describe upgrading from 3.x and 4.0
Signed-off-by: Alessandro Rubini <rubini@gnudd.com>
ec79a7bd · Alessandro Rubini · 6f7fa86a · ec79a7bd · ec79a7bd
Commit ec79a7bd authored Oct 01, 2014 by Alessandro Rubini
Hide whitespace changes
Inline Side-by-side

Showing with 197 additions and 18 deletions

wrs-developer-manual.in doc/wrs-developer-manual.in +67 -16

wrs-user-manual.in doc/wrs-user-manual.in +130 -2

No files found.
--- a/doc/wrs-developer-manual.in
+++ b/doc/wrs-developer-manual.in
@@ -35,7 +35,7 @@

 @setchapternewpage off

-@set update-month September 2014
+@set update-month October 2014
 @c the release name below is substituted at build time
 @set release __RELEASE_GIT_ID__

@@ -1036,15 +1036,22 @@ the switch. In the shipped binaries no user is authorized, but the
 root password is still the empty string.

 @c ##########################################################################
-@node Flashing of WRS-3
-@chapter Flashing of WRS-3
+@node Flashing the Switch
+@chapter Flashing the Switch

-This chapter describes the steps to install the WRS-3 with the 
+This chapter describes the steps to install the @sc{wrs} with the 
 current firmware images. As far as hardware is concerned, this
-procedure describes the installation of the switch with a @i{SCB v3.3}
-and a @i{Mini-Backplane v3.3}. Older versions are not documented here
+procedure describes the installation of the switch with a @sc{scb}
+version 3.3 or 3.4, and a @sc{Mini-Backplane} version 3.3.
+Older versions are not documented here
 any more (please get an older manual, if needed).

+@b{Note:} Most likely you won't need to reflash your @sc{wrs}.
+Even if you rebuilt software from scratch, the ``update'' procedure
+that is available since August 2014 (release 4.0 of @t{wr-switch-sw})
+allows complete replacement of the firmware image without physical
+access to the device.
+
 @c ==========================================================================
 @node USB connections
 @section USB connections
@@ -1102,6 +1109,10 @@ and enter @emph{"Flashing mode"} is not working. You should contact support.
 @node Flashing Procedure
 @section Flashing Procedure

+If the update procedure, described in the @i{User's Manual}
+is not suitable for you (because, for example, you are the manufacturer),
+you need physical access to your @sc{wrs} to flash it.
+
 Unlike what happened with previous releases (up to the end of 2013),
 the filesystem of the switch can't fit in RAM memory during installation
 any more: the image is now downloaded through the network.  Thus
@@ -1121,8 +1132,8 @@ DHCP as IP address for the TFTP transfer.
 Also, since release 4.1, you should not provide MAC addresses
 while flashing any more. The two MAC addresses are expected to be stored
 in @i{dataflash} by the manufacturer and not changed any more. If you
-upgraded your switch from a previous software version, please refer
-to 
+upgrade your switch from a previous software version, please refer
+to the @i{User's Manual} for details.

 The tool used to flash the firmware into the switch is the @i{USB-loader}
 we inherited from Atmel. The @file{flash-wrs} script is what
@@ -1616,16 +1627,49 @@ Currently this only applies to the serial number (@t{-n})
 @node Storing Hwinfo in a White Rabbit Switch
 @section Storing Hwinfo in a White Rabbit Switch

-Linux partitioning accesses the hardware information as a read-only
-partition, to prevent accidental erasure. The boot loader, on the
-other hand, has full access to the @i{dataflash} device.
+You can store your @i{hwinfo} using either the @sc{wrs} shell
+or the boot loader. The former technique can be performed remotely,
+the latter requires access to the serial
+console, on the backplane. 
+
+@c --------------------------------------------------------------------------
+@node From the Linux Shell
+@section From the Linux Shell
+
+The information lives in partion @t{mtd5}, as shown in @t{/proc/mtd}
+(Memory Technology Device). To avoid accidental erasure, our
+filesystem doesn't include the device file @t{/dev/mtd5}, but only
+the read-only counterpart, @t{/dev/mtd5ro}.

-To write the hardware information in a switch that misses it, or
-replace an existing set of values, you may use the following
-@i{barebox} commands (erasing is not needed if the device is blank).
+If you built your own @i{hwinfo}, with your MAC addresses, and you
+copied it to @i{/update} (a good staging place for files copied
+over the network), the following commands will place the information
+in place:
+
+@smallexample
+   test -c /dev/mtd5 || mknod /dev/mtd5 c 90 10
+   flash_erase /dev/mtd5 0 0
+   cat /update/hwinfo > /dev/mtd5
+   rm /dev/mtd5
+@end smallexample
+
+The commands create the device file if missing (to prevent an ugly
+error message if you already created it), erase and overwrite the
+data area, and finally remove the device file.
+
+You new MAC addresses will be effective at the next boot.
+
+@c --------------------------------------------------------------------------
+@node From the Barebox Shell
+@section From the Barebox Shell
+
+If you prefer creating or replacing @i{hwinfo} from the boot loader,
+this is the procedure. You can't run it with software version 4.0 or
+earlier, because our boot loader was unable to access
+@i{dataflash}. V4.1 fixed this problem and introduced the @t{sdb}
+command in the booloader to access your @i{hwinfo} structure.

 @smallexample
-   addpart /dev/dataflash0 0x840@@0x94800(hwinfo)
   erase /dev/dataflash0.hwinfo
   dhcp 5
   tftp hwinfo /dev/dataflash0.hwinfo
@@ -1635,7 +1679,14 @@ The code above assumes that the @i{hwinfo} file is available from your
 @sc{dhcp/tftp} server. According to your configuration one or more
 commands may be redundant.

-You can verify successful writing by running @i{sdbinfo}, as shown
+The commands rely on a partition being there, and the default
+script already created it using the following command:
+
+@smallexample
+   addpart /dev/dataflash0 0x840@@0x94800(hwinfo)
+@end smallexample
+
+You can verify successful writing by running @i{sdb ls}, as shown
 below.

 @c ==========================================================================

--- a/doc/wrs-user-manual.in
+++ b/doc/wrs-user-manual.in
@@ -35,7 +35,7 @@

 @setchapternewpage off

-@set update-month September 2014
+@set update-month October 2014
 @c the release name below is substituted at build time
 @set release __RELEASE_GIT_ID__

@@ -132,6 +132,126 @@ versions. As usual, it is in the @i{files} tab of @t{ohwr.org}.
 V1 and V2 were development items, never shipped.


+@c ##########################################################################
+@node Upgrading WRS Software
+@chapter Upgrading WRS Software
+
+The @sc{wrs} is shipped with a current version of its software image,
+which is sometiems called @i{firmware}.
+If your devices are running a previous version of the software you may
+want to upgrade, or you may want to replace the firmware images after
+rebuilding your own, as explained in the @i{Developer's Manual}.
+
+If you run version 4.1 or later, you can ignore this chapter, that
+explains a transition between the initial way we passed MAC addresses
+and the safer approach we introduced in v4.1
+
+@c ==========================================================================
+@node hwinfo
+@section hwinfo
+
+Version 4.1 (October 2014) and later ones use a new way to pass
+hardware information to all levels of software, such information
+includes the MAC addresses for the management Ethernet and the
+@sc{sfp} ports.  Information is now stored in a Flash partition called
+@i{hwinfo}, using the @sc{sdb} file format. @sc{sdb} is defined in the
+@t{fpga-configuration-space} within @t{ohwr.org}.  Before using
+@sc{sdb} we used to edit the boot loader's configuration at flash
+time, a bad practice developed in a hurry.
+
+The @i{hwinfo} structure is now written to @i{dataflash} by the
+manufacturer, and never changed even when perforiming a complete re-flash
+of the device, because the flashing scripts preserve the @i{hwinfo}
+memory area.
+
+When upgrading from a pre-4.1 switch software, you need to create this
+@i{hwinfo} data structure. This procedure is mostly automatic, but you
+need to be aware of the steps involved, in case something goes wrong.
+
+@c ==========================================================================
+@node Upgrading from v4.0
+@section Upgrading from v4.0
+
+Version 4.0 and later of @t{wr-switch-sw} are able to upgrade
+themselves if you place the profer files in the @i{/update} directory
+of the @sc{wrs}.  However, in version 4.0 we forgot to provide for
+an upgrade of the boot loader.
+
+To upgrade from version 4.0, therefore, the procedure is the following
+one:
+
+@itemize @bullet
+
+   @item Copy your own @t{wrs-firmware.tar} for v4.1 into the @i{/update}
+   partition. This can be the official firwmare or one you built yourself.
+   Then reboot and wait for everything to settle (the system will reboot
+   once more by itself).
+
+   @item Copy @t{wrs-firmware.tar} again. And reboot again. The system
+   will reboot once more by itself.
+
+   @item Now you have a running v4.1 with your @i{hwinfo} in place
+   and the old MAC addresses preserved.
+
+@end itemize
+
+What follows is a details description of what is happening during
+the update, so you can follow the steps without being too
+scared (I usually am...):
+
+@itemize @bullet
+
+   @item The first time you reboot, the on-switch v4.0 boot scripts
+   will replace the complete filesystem, the kernel and the @i{initramfs}
+   -- but not the boot loader.  Having replaced the kernel, it
+   reboots to make it active.
+
+   @item At this point in time, we are running the 4.0 boot loader,
+   that knows its own MAC addresses in the old ugly way, with a 4.1
+   kernel and filesystem.
+
+   @item The v4.1 boot procedure includes a script to create @i{hwinfo}
+   and save it to flash using the current MAC addresses, if no
+   valid @i{hwinfo} exists.  Thus, after
+   the system is booted, @i{hwinfo} is in place, even if the boot loader
+   is not using it.
+
+   @item Now you place @t{wrs-firmware.tar} into @i{/update}
+   a second time, to replace the boot loader using the v4.1
+   upgrade scripts.  (As an alternative, you can just place
+   @t{barebox.bin} into @i{/update}, as v4.1 looks for such file name).
+
+   @item When booting, the contents of @i{/update} are
+   processed by the v4.1 boot scripts, which install everything
+   included in @t{wrs-firmware.tar}, including the boot
+   loader.
+
+   @item When the system automatically reboots to finalize the second
+   upgrade, you are running the new boot loader, that retrieves your MAC
+   addresses from the @i{hwinfo} partition.
+
+@end itemize
+
+@c ==========================================================================
+@node Upgrading from v3.x
+@section Upgrading from v3.x
+
+Upgrading from versions older than 4.0 (August 2014) requires physical
+access to the device and, unfortunately, requires some extra steps
+especially if you want to preserve your MAC addresses.
+
+One possible path is flashing version 4.0 (please refer to v4.0
+manuals) and then proceed as described in @ref{Upgrading from v4.0}.
+When flashing version 4.0 you'll need to pass your MAC addresses on
+the command line of the flasher, so please take not of what they are.
+
+Another option is flashing the latest firwmare version and then build
+your own @i{hwinfo} structure by specifying your MAC addresses.
+@t{wr-switch-sw} includes specific tools for both steps. They are
+described in the @i{Developer's Manual}, because they are expected to
+only be performed by the manufacturer, not the final user.
+
+
 @c ##########################################################################
 @node Kconfig Support
 @chapter Kconfig Support
@@ -150,6 +270,10 @@ menuconfig}'' (or @i{gconfig} or @i{kconfig} or the old text-mode
 silently enact the default configuration, run ``@t{make defconfig}''
 (this is done by the normal build if no configuration is present).

+The released firmware image uses the default configuration, but we'll
+soon offer the option to change most of these values at boot-time
+(by downloading configuration from a network server) or run-time.
+
 The following configuration options are available

 @table @code
@@ -328,7 +452,7 @@ from, as shown in the log excerpt above. So you'll have your
 leading @t{#!/bin/sh}. Examples in @i{wr-switch-sw} did not include the
 line until April 2014 included.

-The @file{binaries} subdirectory of this package includes two known-working
+The @file{binaries} subdirectory of @t{wr-switch-sw} includes two known-working
 wrboot scripts as examples; one if for use with static IP addresses and
 the other relies on DHCP. If you want to override the default NFS-Root
 directory mounted from the server (which is @code{/tftpboot/<ip-address>})
@@ -338,6 +462,10 @@ you can add something like the following line to your @file{wrboot} script:
    bootargs="$bootargs nfsroot=/opt/root/wrs-3"
 @end example

+@c ==========================================================================
+@node Creating an NFS-Root Environment for WRS
+@section Creating an NFS-Root Environment for WRS
+
 In order to create an NFS root directory, you should uncompress
 @t{wrs-image.tar.gz} that is created at build time.  If you use
 a released @t{wrs-firmware.tar}, however, you'll have no overall