\input texinfo    @c -*-texinfo-*-
%
% wrs-build.in - main file for the documentation
%
%%%%

%------------------------------------------------------------------------------
%
%                         NOTE FOR THE UNAWARE USER
%                         =========================
%
%    This file is a texinfo source. It isn't the binary file of some strange
%    editor of mine. If you want ASCII, you should "make wrs-build.txt".
%
%------------------------------------------------------------------------------

%
% This is not a conventional info file...
% I use three extra features:
%   - The '%' as a comment marker, if at beginning of line ("\%" -> "%")
%   - leading blanks are allowed (this is something I cannot live without)
%   - braces are automatically escaped when they appear in example blocks
%

@comment %**start of header
@documentlanguage en
@documentencoding ISO-8859-1
@setfilename wrs-build.info
@settitle wrs-build
@iftex
@afourpaper
@end iftex
@paragraphindent none
@comment %**end of header

@setchapternewpage off

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

@finalout

@titlepage
@title White Rabbit Switch: software build scripts
@subtitle @value{update-month} (@value{release})
@subtitle How to rebuild the whole software package from sources
@author Alessandro Rubini, Benoit Rat, Federico Vaga et al.
@end titlepage
@headings single

@c ##########################################################################
@iftex
@contents
@end iftex

@c ##########################################################################
@node Top
@top Introduction

This document describes the software build procedures for the White
Rabbit Switch.  The procedure described is for version 3.3 of the
hardware project and post-v3.3 software package.
If you are running the official 3.3 release, please
refer to the associated manual (at
@url{http://www.ohwr.org/attachments/download/2264/wr-switch-sw-v3.3-20130725_build.pdf},
which includes some (though limited) documentation for v3.0, v3.1
& v3.2 in its Appendixes.

@b{Note:} the switch, as shipped, works perfectly with the provided
binaries (@url{http://www.ohwr.org/projects/wr-switch-sw/files}), and
most users will only need to run the flasher -- see @ref{Flashing of
WRS-3}.  This document as a whole is mainly aimed at developers who
want to customize their own switch, which is actually a GNU/Linux host.

If you do not need to modify/hack anything in the switch and just learn
how to use it, you should first refer at the @b{User Guide} that you can
find in the @url{http://www.ohwr.org/projects/wr-switch-sw/files}

@menu
* Overview::                    
* Building::                    
* Flashing of WRS-3::           
* Booting with Barebox::        
* The Individual Build Steps::  
* Code layout in a production switch::  
* Schematics are Available::    
* Older Hardware Releases::     
* Installing from Jtag::        
* Bugs and Troubleshooting::    
@end menu

@c ##########################################################################
@node Overview
@chapter Overview

The scripts build over previous work by Tomasz Wlostowski, who first
made the whole thing work and stick together -- a serious result from
serious efforts, I am really amazed by his achievements.

The purpose of the build-script rewrite is achieving the following targets:

@itemize @bullet
@item One-command build.
	The non-technical user should be able to rebuild the whole software
        package with a single command. This includes the IPL and boot-loader
        even though they are expected to be pre-installed in the switch with
        no real need for upgrading.
@item Sub-package separation.
	Users and developers should be able to rebuild each
        sub-package by itself. Sub-packages are the kernel,
	@i{buildroot}, libraries and so on. If you have a problem (or a
        customization you need on one sub-package), you should be able to work
        on the specific part ignoring the whole as much as possible.
@item Documentation.
	The steps are documented as much as possible, because mishaps
        do happen, and you should easily understand where the problem is.
@item Avoid redundant downloads.
	People with non-mainstream network connections would rather
	avoid downloading the same package over and over. Thus, a centralized
	download directory is defined where all external packages are
        retrieved. Even if you ``make distclean'' in the build scripts you
        will not need re-get everything from the network.  In a similar
        mood, people who already have a local copy of the big packages
        (kernel, barebox, white-rabbit svn) will not need to re-download not
        even the first time they build the WRS software.
@end itemize

After release 3.3, we decided to add @i{Kconfig} support. This means
that the first build step is expected to be ``@t{make menuconfig}'',
like it happens for the kernel.  The default configuration is selected
by default when one of the build scripts is run, so the procedure for
the final user is the same as for v3.3 and earlier.  A build with a
non-default configuration, however, is not considered as
``supported'', and @i{Kconfig} is there mainly to help developers try
new packages and setups without changing the repository or
introducing problems for other users.  For some more information about
@i{Kconfig} in this package, see @ref{Kconfig Support}.

The build system is set up as a mix of scripts and makefiles. Every
sub-package is built by its own script and/or Makefile, and configuration is
passed over through environment variables. The top-level build script
sets all environment variables, while keeping defaults from your
preexisting environment -- so you can override anything even when
rebuilding it all from scratch.

@menu
* Portability::                 
* Environment Variables::       
* Downloading Files::           
@end menu

@c ==========================================================================
@node Portability
@section Portability

The scripts in their current status are not expected to be very
portable. I am sure a number of @i{bashisms} exist, and I did no effort
to even identify them.  To relieve the user from possible pain,
internally the name @i{bash} is used instead of @i{sh}, so things
should work even if your default shell is @i{ash} or @i{dash}.
@c FIXME test this again
@c actually the scripts have been tested in one system where the
@c default @i{sh} is @i{dash}.

Similarly, the scripts are likely to fail if you use spaces in directory
names; that is because not all
uses of shell variables are properly quoted. I urge you to use directory names
with no spaces in them, or to submit a patch to fix the scripts.

It should go without saying that the build environment is expected to
be a native GNU/Linux system; success reports about other environments
(e.g. cygwin) are welcome, possibly with associated patches.

@c ==========================================================================
@node Environment Variables
@section Environment Variables

The scripts use a number of environment variables; you can pre-set
them as you wish. If they are not pre-set, defaults apply as
described below.

When rebuilding everything, the defaults are applied for each unset
variable; but when rebuilding a sub-package you will need to set the
variables beforehand.  Each sub-package complains if it needs variables
that are not set in your environment.

The following variables are used in one or more parts of the scripts;
let me restate, though, that sensible default values apply by default,
so this list is mainly for your curiosity unless you are a developer.

They are listed in an order that seems logical to me, but may sound
random to a different person, please forgive this.  Most of the
variables are prefixed with @code{WRS_} to make them easily identified
in the overall mess of variables and command names (all scripts used here
have a similar prefix for the same reason).

@table @code
@item WRS_BASE_DIR
	The absolute pathname of the build directory (i.e., the @code{build/}
        subdirectory of @code{wr-switch-sw}).
        The variable is internally set to the directory
        name of the main script. Note that the script cannot
        be run from the same directory or from the wr-switch-sw project
        directory (i.e.: @code{./wrs_build-all} @code{./build/wrs_build-all}
        are not allowed), you must call it from your output directory
        using a pathname to  invoke it.  This variable cannot be
        overridden in the main script, but must be pre-set if you run
        a sub-script to rebuild only part of the software suite.

@item WRS_OUTPUT_DIR
	The absolute pathname of the directory where output is placed. It 
	defaults
        to the current directory whence you invoke the script (i.e., you
        can invoke @code{/path/to/wrs_build-all} to have all output
        in the current directory).  Compilation
        happens in a @i{build} subdirectory of @code{WRS_OUTPUT_DIR},
        done-markers are placed in a @i{_done} subdirectory
        and final images are placed in a @i{images} subdirectory.

@item WRS_DOWNLOAD_DIR
	The absolute pathname of the directory where downloaded files 
	are placed. If unset
        it defaults to @code{$WRS_OUTPUT_DIR/downloads}, which is
        created if needed.  By pre-setting this variable you can
        simply recursively delete
        the output directory to force a full rebuild, without
        the overhead of re-downloading everything.

@item WRS_HW_DIR
	The absolute pathname of the directory where you build HDL, if any.
        If this variable is set, FPGA binaries will be copied from there
        instead of being extracted by the official archive on @code{owhr.org}.

@item CROSS_COMPILE
	The variable is the usual cross-compilation prefix. For example,
        @code{arm-linux-} if you have @i{arm-linux-gcc} in your path,
        or a full pathname without the trailing @code{gcc}. If unset,
        it defaults to the compiler that @i{buildroot} self-builds.
        See @ref{The Compiler} for some more details.

@end table

Other variables are used internally in the script; since they are only
useful to people working on the script itself, they are documented in
place.

If you compiled for version 2 you will notice we do not have
@code{WRS_WR_REPOSITORY} any more. We used to rely on upstream
archives to be part of the @i{White Rabbit} subversion tree, but I
did not add the new archives in there because of their size.

@c ==========================================================================
@node Downloading Files
@section Downloading Files

Every downloaded file is saved to the @code{download} directory 
(if set @code{WRS_DOWNLOAD_DIR} else the default
@code{$WRS_OUPUT_DIR/downloads}). You should
arrange not to remove that directory when you recompile over and over
during development. I chose to make the first
script download everything, because I think this eases development in a
way: you first wait a while but can tell download errors from other
issues, and then you can build it all even without a network connection.

For each upstream archive needed, the following steps are performed:

@itemize @bullet
@item If the file exists in the download directory, the @i{md5sum} is
      checked; on success, nothing else is done.
@item If the previous step fails, the file is retrieved from upstream.
@item If the previous step fails, the file is downloaded from the
      buildroot web site.
@end itemize

The policy just described is implemented in @i{wrs_download}, in the file
@code{scripts/wrs_functions}, based on @code{download-info} in the
main build directory.

The messages of a download run are like the following ones:

@smallexample
   2012-01-12 18:30:46: --- Downloading all files
   2012-01-12 18:30:53: Retrieved at91bootstrap-3-3.0.tar.gz from upstream
   2012-01-12 18:31:00: Retrieved buildroot-2011.11.tar.bz2 from upstream
   [...]
   2012-01-12 18:37:53: Retrieved uClibc-0.9.32.tar.bz2 from upstream
   2012-01-12 18:37:56: Retrieved zlib-1.2.5.tar.bz2 from upstream
@end smallexample

@c ##########################################################################
@node Building
@chapter Building

@menu
* Building Procedure::          
* Build Script Description::    
@end menu

@c ==========================================================================
@node Building Procedure
@section Building Procedure
If you just want to build stuff, with no concern about network
downloads and without even knowing what is happening, just create a
directory where you want the output to be generated and start
compilation. Note that it takes around 3GB of storage.

Then run this (but please read more for a better command):

@example
   /path/to/wr-switch-sw/build/wrs_build-all
@end example

Note that progress messages are sent to @i{stderr}, so you may want to
save @i{stdout} to a file, like this (again, it is recommended you read
further for a better command):

@example
   /path/to/wr-switch-sw/build/wrs_build-all > logfile
@end example

Please note that there are also a number of warning messages being
printed to @i{stderr}. It is a few hundred lines over the many
minutes it takes to build @i{buildroot}, but you can safely ignore them,
trusting the build process will complete successfully.

The progress messages look like what is shown here below.  The log
file will be rather big (6 or 7MB or so), as all the compilation steps are
quite verbose.

The following example shows a run on a quad core system (18k
bogoMips in total). If files had already been downloaded, the first
step takes only a pair of seconds to verify the checksums:

@smallexample
2012-07-06 17:23:57: --- Downloading all files
2012-07-06 17:24:02: --- Buildroot compiler and filesystem
2012-07-06 17:24:02: Uncompressing buildroot
2012-07-06 17:24:02: Patching buildroot
2012-07-06 17:24:02: Reconfiguring buildroot
2012-07-06 17:24:04: Compiling buildroot
2012-07-06 17:48:46: --- AT91Boot
2012-07-06 17:48:46: Patching AT91Boot
2012-07-06 17:48:46: Building AT91Boot
2012-07-06 17:48:50: --- Barebox
2012-07-06 17:48:50: Patching Barebox
2012-07-06 17:48:50: Building Barebox
2012-07-06 17:48:59: --- Linux kernel for switch
2012-07-06 17:50:32: --- Kernel modules from this package
2012-07-06 17:50:35: --- PTP daemon (noposix repository as a submodule)
2012-07-06 17:50:38: --- User space tools
2012-07-06 17:50:39: --- Deploying FPGA firmware
2012-07-06 17:50:39: --- Wrapping filesystem
2012-07-06 17:50:53: Complete build succeeded, apparently
@end smallexample

You may prefer to save @i{stderr} with @i{stdout} to the log file
but still see the time-stamped messages from the scripts. In this
case you can issue the following command -- which is what I used
to generate the terse output shown above:

@example
   /path/to/wr-switch-sw/build/wrs_build-all 2>&1 | tee logfile \
        | grep "^20..-..-.. ..:"
@end example

If you are lucky, everything completes by itself. The time taken
depends on you CPU, disk and network speed.
At the end you will find your final files in the @code{images}
subdirectory.  If you are not too lucky, the build stops because
you have 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 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{01-buildroot}
and @code{04-kernel}).

@c ==========================================================================
@node Build Script Description
@section Build Script Description

The @code{wrs_build-all} can be used to quickly build the White Rabbit 
Software as seen above. However it admits other functionalities detailed
in this chapter. You might also want to check its embedded documentation using:

@example
   /path/to/wr-switch-sw/build/wrs_build-all --help
@end example

@menu
* Release Package::             
* Rebuilding Parts::            
* Rebuilding From Scratch::     
@end menu

@c --------------------------------------------------------------------------
@node Release Package
@subsection Release Package

Once all the building steps have succeeded, you can easily create a
package in @code{WRS_OUTPUT_DIR} using the following command:

@example
   /path/to/wr-switch-sw/build/wrs_build-all --pack
@end example 

This will generate a @code{tar.gz} package. The name of the package is composed
by the prefix and the description of the current status of the git repository.
This is the same naming policy of the kernel and other packages.

The prefix is @code{wrs-firmware-}; the information about the current status are
retrieved by using the git command @code{git describe --always --dirty}.
For example, if you are building the tag @code{wr-switch-sw-v3.3}, your package
name will be @code{wrs-firmware-wr-switch-sw-v3.3.tar.gz}. If you are building
on some personal commit the name includes some extra information to describe
your commit: number of commits form the last tag (if any), SHA1 code of the
commit. If you have uncommited changed, the suffix @code{-dirty} is there too.

@c --------------------------------------------------------------------------
@node Rebuilding Parts
@subsection Rebuilding Parts

When the main script succeeds in building one part (sub-package),
it creates a file in the @code{build/_done} directory.

When you rebuild everything, steps for which the marker file exists
are not rebuilt. To force rebuilding of one specific part, just remove
the marker.  Markers are numbered, reflecting the order of compilation
steps, but they also have a name: names like @code{04-kernel} should be
self-explicative. 

To ease the rebuilding of a specific module a shortcut has been created 
in the @code{wrs_build-all} script. For example if you want to recompile
kernel you should execute.

@example
   /path/to/wr-switch-sw/build/wrs_build-all --step=04
@end example

You can list all compiled module by calling

@example
   /path/to/wr-switch-sw/build/wrs_build-all --list
@end example
 
If you want to rebuild various modules at the same time, you should run
something similar as:

@example
   /path/to/wr-switch-sw/build/wrs_build-all --step="5 7 9"
@end example


As an alternative, you can run the individual script from within
@i{scripts/}, after setting the proper environment variables.


@c --------------------------------------------------------------------------
@node Rebuilding From Scratch
@subsection Rebuilding From Scratch

If you have updated the repository with new modifications, you might want 
to check that you can rebuild from scratch. To clean your output 
directory by deleting all compiled modules (except downloaded files), just call:

@example
   /path/to/wr-switch-sw/build/wrs_build-all --clean
@end example


@c ##########################################################################
@node Kconfig Support
@chapter Kconfig Support

After release 3.3 of this software package, we added Kconfig support
to wr-switch-sw.  The user can ignore this step: building as usual
(by running @t{wrs_build-all} from an empty directory) silently selects
the default configuration.  Developers may use the feature to try
different choices of packages.

To change configuration, you are expected to run ``@t{make
menuconfig}'' (or @i{gconfig} or @i{kconfig} or the old text-mode
@i{config}) from the top-level directory of @i{wr-switch-sw}.  To
silently enact the default configuration, run ``@t{make defconfig}''
(this is done by the normal build if no configuration is present).

The following configuration options are available

@table @code

@item CONFIG_BR2_CONFIGFILE

	This string option lists a file to be used as Buildroot (BR2)
        configuration. A simple filename or relative pathname refers to the 
        @t{configs/buildroot} directory; an absolute pathname is used
        unchanged.

@item CONFIG_PTP_NOPOSIX
@itemx CONFIG_PPSI

	Users can select one of these options, to build with one or the other
        flavour of @sc{wr-ptp}.  PPSi is going to be the default, and later
        the only supported option.

@end table

@c ##########################################################################
@node Flashing of WRS-3
@chapter Flashing of WRS-3

This chapter describes the different steps to install the WRS-3 with the 
correct firmware. 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 any more (please get an older
manual, if needed).

@c ==========================================================================
@node USB connections
@section USB connections

In order to perform the flashing operation easily, you should connect
three @i{mini-USB} cables to the switches. 

The two back panel @i{mini-USB} sockets correspond to the serial 
port of the FPGA and the ARM. They are labeled @b{FPGA test} and 
@b{ARM test} and respectively correspond to the devices 
@code{/dev/ttyUSB0} and @code{/dev/ttyUSB1} on your host. 

You can connect to them using minicom 
@footnote{You can use other programs for accessing serial ports, for 
example @uref{http://brokestream.com/tinyserial.html, tinyserial}} 
like this:

@example
	minicom -D /dev/ttyUSB0 -b 115200
	minicom -D /dev/ttyUSB1 -b 115200
@end example

Unfortunately, this order depends on how the USB cables are plugged 
so you might have the @code{ttyUSB0} device that corresponds to the ARM 
and the @code{ttyUSB1} to the FPGA.

@sp 1

The front panel USB connection, labeled as @b{management} USB port, communicates 
with the internal ROM of the CPU. It is the one used to perform the 
flashing procedure.

You first need to set up the switch in @emph{"Flashing mode"} to 
continue with the flashing procedure. To do so, you should turn on 
the power while pressing the @b{flash button} on the rear panel.

If the operation succeed you should see the message @code{bootROM} 
appears on the ARM UART. You can also see the enumerated
device in your own host:

@smallexample
   $ lsusb | grep Atmel
   Bus 001 Device 025: ID 03eb:6124 Atmel Corp. at91sam SAMBA bootloader
@end smallexample

Finally, the kernel should also load the proper device driver, and you
are expected to see @code{/dev/ttyACM0} or equivalent in your system.

If it is not the case, this mean that the button used to disable the dataflash
and enter @emph{"Flashing mode"} is not working. You should contact support.

@c =============================================================================
@node Flashing Procedure
@section Flashing Procedure

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
you'll use to run the loader with appropriate parameters.

The script can be invoked in the following way to flash a
@i{package} into the switch. The package is the @code{.tar.gz}
file created by ``@code{wrs_build-all --pack}'' (see @ref{Release Package}).

The command to flash is this:

@example
    /path/to/wr-switch-sw/build/flash-wrs -e wrs-firmware-<revision>.tar.gz 
@end example

You can also flash the image you have build using @ref{Building} by
adding the tag @code{-b|--build}. To use this option you must call
the script from the build directory, or define the @t{WRS_OUTPUT_DIR}
environment variable.

@example
    /path/to/wr-switch-sw/build/flash-wrs -e -b
@end example

Please note that the ``@code{-e}'', which requires erasing the
whole data flash, is almost mandatory because otherwise bits of your previous
installation may leak into the newly-programmed one. Only on factory-new
devices you can avoid this ``@code{-e}'' argument. 

When you program
the NAND memory the script applies automatically @code{-e} option.

It is recommended to configure the MAC addresses during the flashing
procedure. With the option @code{-m1|--mac1} you can select the MAC address
to assign to the Ethernet port on board. With the option @code{-m2|--mac2}
you can select the base MAC address; the @code{wr_nic} driver will use this
MAC address to sequentially assign a MAC address for every switch ports.

@example
    /path/to/wr-switch-sw/build/flash-wrs -e -b -m1 02:34:56:77:65:43
    -m2 02:34:34:34:34:00
@end example

Please remember that bits 0 and 1 of the first byte are special: if
the first byte is odd, the MAC address is reserved for multicast
transmission (the script doesn't check, and the kernel will refuse to
enact such address).  Bit 1 is set for ``locally assigned'' numbers:
while official MAC addresses have bit 1 clear, if you choose your
unofficial addresses you should set the bit.

If you don't configure a MAC address, a warning will be displayed and
you can abort the procedure. If you don't abort the flashing
procedure, the script will use default MAC addresses. Default MAC addresses
are: 02:34:56:78:9A:BC for MAC1 (the Ethernet port of the ARM CPU)
and 02:34:56:78:9A:00 for MAC2 (the base address for the 18 SFP ports).

@smallexample
   tornado% ~/wip/wr-switch-sw/build/flash-wrs -e -b
   flash-wrs: Working in /tmp/flash-wrs-1vV9z6
   Warning: you did not set the MAC1 value; using "02:34:56:78:9A:BC"
   Warning: you did not set the MAC2 value; using "02:34:56:78:9A:00"
   flash-wrs: I'm talking with the switch;
      please remove the jumper and press Enter to start flashing:
@end smallexample

If the script cannot find the Atmel programming interface on your USB
bus, it prints a message and waits for the switch to be turned on
in the proper way (with the jumper plugged or the button pressed).

The process calls the flasher program twice (so you'll see the
initialization strings two times) and takes slightly less than 3
minutes.  the longest step is erasure of @i{DataFlash}: if run
without @t{-e} the script takes just 20 seconds.

This is the summary of the output you are expected to see,
trimmed to save pages:

@smallexample
Initializing SAM-BA: CPU ID: 0x819b05a2

[...]

Initializing DDR...
loading applet isp-extram-at91sam9g45 at 0x00300000
Initializing DDR > Done

Initializing DataFlash...
loading applet isp-dataflash-at91sam9g45 at 0x00300000
Initializing DataFlash > Done! 

Erasing DataFlash [... there is a long delay here ...] > DONE

Programming DataFlash...
	 @ 0x70000000 : at91bootstrap.bin ; size 0xf7c (3Kb)
DataFlash: Writing 3964 bytes at offset 0x0 buffer 70000000....ABCDEF OK
	 @ 0x70008400 : barebox.Fb09jx ; size 0x2f1bc (188Kb)
DataFlash: Writing 192956 bytes at offset 0x8400 buffer 70000000....ABCDEF OK
Programming DataFlash Done!!!
[...]

Initializing NandFlash...
loading applet isp-nandflash-at91sam9g45 at 0x00300000
Initializing NandFlash > Done! 

Erasing NandFlash > DONE

[...]

Initializing DDR...
loading applet isp-extram-at91sam9g45 at 0x00300000
Initializing DDR > Done

Erasing DDR > DONE

Loading DDR...
	 @ 0x70000000 : /tmp/barebox.Fb09jx ; size 0x2f1bc (188Kb)
	 @ 0x71000000 : /data/morgana/build-v3-fede/images/zImage ; size 0x16886c (1442Kb)
	 @ 0x71fffff8 : /tmp/wrsflash-cpio.jrPKMY.cpio.gz ; size 0x128c722 (18993Kb)
DDR: Writing 21119306 bytes at offset 0x0 buffer 70000000....ABCDEF

[...]
@end smallexample

It is suggested to look at the CPU's serial port during programming,
where you will see messages like these:

@smallexample
   -I- Statup: PMC_MCKR 1202 MCK = 100000000 command = 0
   -I- -- EXTRAM ISP Applet 2.9 --
   -I- -- AT91SAM9G45-EK
   [...]
   -I-     End of applet (command : 2 --- status : 0)

[...]

barebox 2012.05.0 (Oct 26 2012 - 20:51:43)

Board: CERN White Rabbit Switch V3

[...]

Uncompressing Linux... done, booting the kernel.

[...]

FLASHING: flashing kernel to /dev/mtd0 ...
Writing data to block 0 at offset 0x0
Writing data to block 1 at offset 0x20000

[...]

FLASHING: flashing file system to /dev/mtd1 ...
Writing data to block 0 at offset 0x0
Writing data to block 1 at offset 0x20000

[...]

@end smallexample

@menu
* Flash Script Description::    
@end menu

@c -------------------------------------------------------------------
@node Flash Script Description
@subsection Flash Script Description

The @code{flash-wrs} script can be used to quickly flash the White Rabbit switch
as seen above. However it admits other functionalities detailed in this chapter.
You might also want to check its embedded documentations using:

@smallexample
$ ./build/flash-wrs --help
Usage: ./build/flash-wrs [options] [<firmware>.tar.gz] [DEV]

MAC:	 MAC address in hexadecimal seperated by ':' (i.e, AB:CD:EF:01:23:45)
<firmware>.tar.gz: Use the file in the firmware to flash the device
DEV:	 The usb device (by default it is /dev/ttyACM0)
Options: 
  -h|--help	 Show this help message
  -m|--mode	 can be: default (df and nf), df (dataflash),
		 nf (nandflash), ddr (ddr memories).
  -g|--gateware	 Select the gateware: 18p (18 ports, default), 8p (8 ports), LX130T (small FPGA), LX240T (big FGPA)
  -e 		 Completely erase the memory (Can erase your configuration)
  -b|--build	 Use files that you have built in the WRS_OUTPUT_DIR
  -m1|--mac1	 Default MAC address for the Ethernet port on board
  -m2|--mac2	 Default base MAC address for the switch ports

@end smallexample

The @i{DEV} is optional and the default is @code{/dev/ttyACM0}.
If your system maps the Atmel ROM to a different device name, please
pass the name on the command line. The script wants a full pathname 
starting with @code{/}.

If you want to flash the @i{at91boot.bin}, @i{barebox.bin}, @i{kernel}
or @i{file-system} that you just built, you can just call the script
from the build directory and use the @code{-b} option.

The official binaries for installation of version 3.3 of this package
are available in the @i{files} tab of @t{ohwr.org}. The complete link
is:@*
@url{www.ohwr.org/attachments/download/2262/wr-switch-sw-v3.3-20130725_binaries.tar.gz}

You can select a mode using the @code{-m|--mode} flag to choose
to write in dataflash (df), nandflash (nf), both (default) or ddr memories
(ddr)@footnote{The ddr memory mode is only for developers}. The memory mode
is used to select the kind of memory to write. The flash script is used to
install different binaries on these memories: 
@itemize @bullet
@item dataflash: @emph{at91boot} and @emph{barebox} binaries
@item nandflash: @emph{kernel} zImage and the @emph{file-system}
@end itemize

You can select which type of gateware you want to flash on your 
switch. By default we only write on the nandflash the gateware 
for 18 ports for both its light (@code{LX130T}) and full 
(@code{LX240T}) FPGA size. If you know which type of FPGA you are 
using (i.e, @code{LX240T}) and you want to have the gateware for 8 
and 18 ports you can use the flag as below:

@smallexample
$ ./build/flash-wrs --gateware LX240T <...>
@end smallexample

You can also erase the dataflash memory before writing your binaries; to do this
add the option @code{-e}. Note that the script always erases nandflash before
writing to it.

The script performs the following steps:

@itemize @bullet
@item It compiles the loader (@i{usb-loader/} subdir).
@item It checks if the SAMBA bootloader is present.
@item It picks the correct binaries according to the options.
@item Optionally, it changes the default MAC addresses in @i{barebox}
      default environment, so you can use a different MAC for each switch.
@item Optionally, it erases the dataflash memory.
@item And finally, it writes the corresponding binaries to @i{dataflash}, 
      or @i{nand}.
@end itemize

@c ############################################################################
@node Booting with Barebox
@chapter Booting with Barebox

After the initial installation, the boot loader will offer you an
interactive  menu, where the first entry is selected by default.
The menu is a simple ASCII interface on the serial port, and looks
like the following:

@example
   Welcome on WRSv3 Boot Sequence
       1: boot from nand (default)
       2: boot from TFTP script
       3: edit config
       4: exit to shell
       5: reboot
@end example

If flashing of the whole system was successful, the first entry will
simply work, booting the switch without any network access.  Although
a DCHP client runs by default after boot, everything will work even if
you leave the Ethernet port unconnected or you have no DHCP server
when the switch is operational.

If booting from NAND memory fails (for example because you erased the
kernel partition) the menu is re-entered automatically.

The other entries are provided to help developers.

@menu
* The Compiler::                
@end menu

@c ==========================================================================
@node Description of the menus
@section Description of the menus

The individual menu items perform the following actions:
@table @code

@item 1: boot from nand (default)

	This entry is selected by default after 10 seconds of
        inactivity on the serial port. It boots the system from its
        own NAND memory. This ``just works''.

@item 2: boot from TFTP script

	This entry tries to download a @i{barebox} script from your TFTP
        server; if successful it then executes it. Developers are
        expected to customize the script to support any kind of environment,
        from customized kernel command-line to NFS-Root environments.
        See @ref{Using wrboot} for details.

@item 3: edit config

	This fires the editor on the configuration file, and
        saves it to flash when the user is done. This is useful to
        change the MAC address of the ARM network port. Please note
        that saving save the whole @file{/env} file tree, so you
        can also change the init scripts interactively and have them
        stored persistently on the flash.

@item 4: exit to shell

	By choosing this entry, the user can access the shell-like
        interface of @i{barebox}. The entry is aimed at developers
        who know what they are going to type.

@item 5: reboot

	This entry is useful to see and log the exact boot messages.
        Since the serial-USB converter is @i{switch-powered} and not
        @i{USB-powered}, you won't be able to hook at the serial port
        soon enough after power-on.  Actually, the menu timeout is
        left to 10 seconds and not less for the very same reason.

@end table

@c ==========================================================================
@node Using wrboot
@section Using wrboot

If you use the @i{wrboot} script option, you can for example run
an NFS-Root system or do whatever customization and testing you want.

The provided procedure tries to load the script from TFTP under three
different names, from most specific to most generic, and the first
match will be used.  The first name is MAC-address-based, the
second is IP-address-based and the third is just @file{wrboot}.

This is for example what I see in my logs when only providing @file{wrboot}:

@smallexample
   dhcpd: DHCPOFFER on 192.168.16.224 to 02:0b:ad:c0:ff:ee via eth0
   atftpd[5623]: Serving wrboot-02:0B:AD:C0:FF:EE to 192.168.16.224:1029
   atftpd[5623]: Serving 192.168.16.224/wrboot to 192.168.16.224:1030
   atftpd[5623]: Serving wrboot to 192.168.16.224:1031
   mountd[21014]: NFS mount of /tftpboot/192.168.16.9 attempted from 192.168.16.9
@end smallexample

We chose to place the IP-address-based name in a subdirectory because
this is the default place where the NFS-Root filesystem is mounted
from, as shown in the log excerpt above. So you'll have your
@file{wrboot} in the same place

The @file{binaries} subdirectory of this package 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>})
you can add something like the following line to your @file{wrboot} script:

@example
    bootargs="$bootargs nfsroot=/opt/root/wrs-3"
@end example

If you use static IP addresses, please note that you should fix
@file{/etc/init.d/S40network} in the filesystem for your switch,
so it doesn't run the DHCP client.

@c ##########################################################################
@node The Individual Build Steps
@chapter The Individual Build Steps

This chapter details the individual build steps, for the users that want
to customize their switch in any way. 

@menu
* The Compiler::                
* Buildroot::                   
* The IPL::                     
* The Boot Loader::             
* The Linux Kernel::            
* Kernel Modules::              
* PTPd::                        
* User Space Applications::     
* VHDL Binaries::               
* The Complete Filesystem::     
@end menu

@c ==========================================================================
@node The Compiler
@section The Compiler

The predefined compiler used here is the one built by @i{buildroot}.
The default configuration selects this choice.  If you pre-set a
different @code{CROSS_COMPILE} prefix in your environment, your own
choice will be used by modifying the @i{buildroot} configuration file.
Note, however, that not all cross-compilers will work (@i{buildroot}
wants one that has been configured with @code{--sysroot} and it is
quite unlikely yours has been).

In practice, you may want to set @code{CROSS_COMPILE} when you compile
the boot loader and kernel by themselves, and avoid it when compiling
the complete package.

@c ==========================================================================
@node Buildroot
@section Buildroot

The distribution being used here is @i{buildroot}. It is the first
step being built, because it creates the cross-compiler it will use. This
compiler is later used to compile all other software for the White
Rabbit Switch.

The configuration for @i{buildroot} comes from
@code{configs/buildroot/wrs_release_br2_config}. The configuration
is then changed only if you pre-set your own @code{CROSS_COMPILE}
variable.  A different configuration can be chosen in the Kconfig
interface, by running ``@t{make menuconfig}'' or equivalent, in the
top-level source directory.

@c The following can be shown in a set of commands instead of this hard
@c to read explanation.

If you want to change the configuration, you can do so after the first
build iteration: change directory to @code{build/buildroot-2011.11}
and run @code{make menuconfig} (this the Buildroot configuration,
not the one of wr-switch-sw). After making your choices, copy back
the file @code{.config} to @t{configs/buildroot} in this package,
so you can select it by running @t{make menuconfig} in wr-switch-sw.

Then, please run @t{configs/buildroot/RUNME} (without arguments)
in order to remove your local pathnames in the configuration file;
the file without local pathnames can be committed and published for
other people to use.

You can also set @code{WRS_BUILDROOT_CONFIG} to the full pathname of
your configuration file of choice (this used to be the only way
to pass a custom configuration file). The file must be a copy of the
@code{.config} after the @code{make menuconfig} step described above,
within buildroot.
Note that if the variable is not pointing to a regular file it is
ignored with a simple warning -- rather than stopping the build procedure.

@c ==========================================================================
@node The IPL
@section The IPL

The version of @i{at91bootstrap} being used in the switch as
@i{Initial Program Loader} is version 3.3, download from  @code{timesys.com/}
(the full URL is in @i{build/download-info}.
The patches we applied are in the directory @i{patches/at91boot/v3.3},
and we are piggy-backing on the Atmel
evaluation board without even changing the board name):

@example
   0001-printf-added-files-from-pptp-unchanged.patch
   0002-printf-fixes-and-addition-to-makefile.patch
   0003-build-Add-gitversion-to-binary-and-a-script-to-compi.patch
   0004-board-9g45ek-fix-ddr-config-for-WRS-V3.patch
   0005-boot-disable-watchdog-asap-added-flip_leds-count-run.patch
   0006-boot-Correct-crash-due-to-an-Atmel-bug-during-boot-w.patch
   0007-gpios-Correct-FPGA-LED-problems-and-add-CPU-LEDs-FAN.patch
@end example

The script @i{wrs_build_at91boot} uncompresses, patches and builds, leaving
@code{images/@-at91bootstrap.bin} after it is over.  This file is
the one to be loaded in the hardware.
For simplicity, a known-working binary is part of the @i{binaries}
directory of this package as @code{at91bootstrap.bin}, the same name used
later in the installation instructions.

If you build using a local @i{git} repository, we suggest to use
@code{git am --whitespace=nowarn} because we have a number of
white space errors, and we apologize for that.

@b{Warning}: with most distributions, this compilation step will print
a scary message about memory corruption. The message is reporting a bug in
the configuration program which has no actual effects and can be ignored.
Maybe we will switch to another version in the future that doesn't show
the bug, or to the newer @i{barebox} that obsoletes @i{at91boot}.

@c ==========================================================================
@node The Boot Loader
@section The Boot Loader

The switch uses @i{barebox} as a boot loader. We are running version
2012-05, with a few local patches and the chosen configuration
file. Note that we are piggy-backing on the Ronetix PM9G45 board, out
of laziness.

The patches are part of this package in @i{patches/barebox} and
the set is made up of the following ones:

@smallexample
   0001-sam945-include-mtd-nand.h-in-device-file.patch
   0002-arm-change-prompt-for-pm9263-wrs-piggy-backs-on-that.patch
   0003-nand-wrs-our-nand-is-16-bit-connected-fix-accordingl.patch
   0004-add-DHCP-retries-by-tom.patch
   0005-gpio-add-function-to-check-them.patch
   0006-startup-load-default-environment-when-loading-env-fa.patch
   0007-wrs-on-pm9g45-change-nand-setup.patch
@end smallexample

If you build using a local @i{git} repository, we suggest to use
@code{git am --whitespace=nowarn} because we have a number of
white space errors, and we apologize for that.

The @i{barebox} boot loader is organized as a small Unix-like
environment, and its own configuration and scripts live in a small
filesystem.  To ease modification of such configuration and boot steps
the build script copies over the configuration instead of patching it
in the sources.  You can thus edit the files you find in
@file{patches/barebox/env} and rebuild your customized bootloader.
The script that is executed at boot time is @file{env/bin/init} and as
you see it calls the other ones.  The menus included in the shipped
configuration are described in @ref{Booting with Barebox}.

Building @i{barebox} relies on a @i{Kconfig} setup, and the
configuration file we use is
@file{patches/barebox/@-wrs3_defconfig}. Again, this is copied over and
not patched in (see the simple @file{build/scripts/@-wrs_build_barebox}
for details).

@c FIXME: describe how to change the barebox configuration file

After patching and copying over the files, the following commands
build the boot loader using the
cross-compiler built by @i{buildroot}. If you run these
by hand you can use a different compiler (as shown):

@example
   export CROSS_COMPILE=/opt/arm-2010q1/bin/arm-none-eabi-
   export ARCH=arm
   make wrs3_defconfig
   make
   cp barebox.bin images/
@end example

To use the same compiler the scripts use, you need this setting (which is split
in two lines with a local variable to fit the page with in documentation):

@smallexample
   BR=${WRS_OUTPUT_DIR}/build/buildroot-2011.11
   export CROSS_COMPILE=${BR}/output/host/usr/bin/arm-linux-
@end smallexample

A pre-built binary is available as @code{binaries/barebox.bin}.
The ELF version is copied to @i{images} as well, as
@code{images/barebox}; this file includes the symbol table and may (or
may not) be useful.

@c ==========================================================================
@node The Linux Kernel
@section The Linux Kernel

The kernel is currently version 2.6.39, compiled from an uncompressed
tar file (so not within a @i{git} repository).  The upstream
vanilla kernel is downloaded, then
local patches are applied (they come from a @i{git}
repository, but they are currently applied with a simple @i{patch}
command).

The relevant patches are available in @i{patches/kernel/v2.6.39},
and are currently the following ones:

@example
   0001-wrs3-changes-to-g45ek.patch
   0002-initramfs-stop-after-one-cpio-archive.patch
   0003-at91-NR_IRQS-increase-by-64-to-fit-custom-muxes.patch
   0004-irq-export-symbols-for-external-irq-controller.patch
   0005-fix-nand-parition-layout-and-usb-vbus.patch
   0006-fiq-support.patch
@end example

The configuration we use to build the kernel is not a patch but a plain
@code{.config} file, in the same directory as the patches, so you
can change it easily, if needed. As an alternative,
you can also set @code{WRS_KERNEL_CONFIG} to the full pathname of
your configuration file of choice. The file must be a copy of the
@code{.config} found in the main kernel directory,
(for example the one left after the @code{make menuconfig} step).
Note that if the @code{WRS_KERNEL_CONFIG}
variable is not pointing to a regular file it is
ignored with a simple warning, without stopping the build procedure.

The build scripts copy both @i{zImage} and all compiled kernel
modules to the @i{images/} directory of the build place. This currently
includes modules 

@c ==========================================================================
@node Kernel Modules
@section Kernel Modules

In the next step the scripts compile modules that are part of this
package.  The step depends on the kernel being available in the
build directory. The modules are then copied into the
@file{images/wr/lib/modules/} subdirectory of the main build directory.

Please note that modules (and later user-space) are compiled in-place;
ie. 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.

Currently, the package includes the following modules:

@itemize @bullet
@item @i{wr_vic.ko}: the interrupt controller for in-FPGA devices.
@item @i{wr-nic.ko}: the network ``card'' driver for WR ports.
@item @i{at91_softpwm}: a tool that generates a PWM signal for the fan.
@item @i{wr_rtu.ko}: the routing-table interface between the
switching core and the associated user-space daemon.
@end itemize

@c ==========================================================================
@node PTPd
@section PTPd

Configuration supports two different PTP engines: either @t{ptp-noposix}
(default at this point in time) or PPSi. The latter will become
the default choice, and then the only choice, as we test it on a larger
use base.

Both implementations are hosted in their own respective different
repository; both are registered as  @i{git} submodules in this package.
The repositories are hosted  on @code{ohwr}, like others.

A plain @i{make} in either  @i{userspace/ptp-noposix} or
@t{userspace/ppsi} will likely fail, because of
missing environment variables. 

Additionally,  the script installs headers for the HAL
and @i{libptpnetif}.

@c ==========================================================================
@node User Space Applications
@section User Space Applications

The filesystem of the switch includes some user-space applications
and tools.  Some of the @i{tools} are actually used by the init
scripts and some are just utilities for the developer.

The subdirectories in @file{userspace} include the various applications
needed for the operation of the switch itself, as well as support libraries
used by the applications themselves.

The main components are:

@table @i

@item mini-rpc
	A remote procedure call library used by most other programs
        to exchange information among themselves or query the LM32
        that is running on the FPGA.

@item libswitchhw

	A series of utility functions to access the switch itself.

@item wrsw_hal
	The main application program for the White Rabbit Switch
        operation. The script installs the executable in @code{images/wr/bin}.

@item wrsw_rtud
	The daemon for the routing table unit, used for routing around
        data frames. It is installed in
        @code{images/wr/bin}.

@end table

The most important tools in @file{userspace/tools} are the following:

@table @file

@item load-virtex
@itemx load-lm32

	They load into the FPGA the gateware and the LM32 application.
        They are used by the init scripts of the Linux system.


@item mapper
@itemx wmapper
	The former reads from a file using @i{mmap}
        (usually you run it on @i{/dev/mem}) and writes to @i{stdout}.
        The latter read from @i{stdin} and writes using @i{mmap}.
        They are classic tools distributed in the @i{Linux Device Drivers}
        examples since 1998.

@item com
	The program is a simple program for talking with serial ports.

@item wr_phytool
	A tool to read and write PHY registers in the switch

@item wr_mon
	A simple monitor of White Rabbit status. It prints to @i{stdout}
        using the standard escape sequences for color output. The
        @t{-b} command line options removes color change (b/w).

@item wr_date

	The program can read or set the White Rabbit date. When setting,
        using ``@t{wr_date set} @i{value}'' assigns an arbitrary date,
        and ``@t{wr_date set host}'' passes the host time to White Rabbit.
        If the file @t{/etc/leap-seconds.list} exists, it is used to
        pass the TAI offset to the kernel, and to consider it in setting
        White Rabbit time to the current TAI value.  The program is
        meant to prime the White Rabbit counter at boot time, and is
        run by @t{/etc/init.d/S70wr_date} -- this script uses NTP
        to set host time as a first step, if @t{/wr/etc/wr_date.conf}
        exists and includes a line of the form @t{ntpserver 192.168.16.1}.

@item shw_ver
	Print informations about the SW & HW version of the WRS. 
	See also @ref{DIP Switch HW version}.
@end table

Please note that to compile the applications and tools outside of the build
scripts you need to specify both the kernel
directory (@code{LINUX=}) and the cross-compiler to use
(@code{CROSS_COMPILE=}).

@c ==========================================================================
@node VHDL Binaries
@section VHDL and LM32 Binaries

The gateware binaries that are needed to run the FPGA are added to the
target filesystem by the @file{wrs_build_gateware} script. If the
variable @code{WRS_HW_DIR} is set, the script uses it to retrieve the
binaries you just compiled (but the script is not compiling gateware).

If the variable is not set, the script extract a tar file downloaded
from @code{ohwr.org} as part of the initial download step. The tar is
currently called @code{wrs3-gw-v3.0-20120801.tar.gz} and has been
build from the @code{wr-switch-sw-v3.0} of the @code{wr-switch-hdl}
repository.  Please note that the repository uses @i{git} submodules,
so it depends on other @code{ohwr} repositories too, which in turn
have not been tagged because the submodule mechanism ensures you'll
get the exact version you need.

The LM32 program is provided as a pre-compiled binary in
@code{binaries/rt_cpu.bin}. The respective source code is the
@i{wrpc-sw} package, because all WR installations run the same
@sc{pll} software code and we chose to avoid duplication. Moreover,
@i{wr-switch-sw} builds to not require an LM32 development environment.

If you need to rebuild the @t{rt_cpu.bin} file from source, to make
your own modifications, you can run @t{make wr_switch_defconfig}
in @i{wrpc-sw} and then @t{make}.  The exact commit identifier
is stored in the binary itself, and you can get it back using
``@t{strings binaries/rt_cpu.bin | grep wrpc}''.

@c ==========================================================================
@node The Complete Filesystem
@section The Complete Filesystem

The final step in building the switch software is wrapping together
the filesystem for the switch, also making the archives and the
@i{jffs2} image file.

The step of setting up the complete filesystem is performed by
@file{build/scripts/@-wrs_build_wraprootfs}.  The script
does not leave a directory tree on disk because that would require
administrator privileges. We think it is best not to call @i{sudo} from
within build scripts, to respect our users' security concerns.

The script creates three output files, that can be used in different
situations, like @i{initramfs} or unpacking for NFS-Root.  All of them
are around 15MB of data, and the flashing script only uses the first
listed here:

@table @code

@item wrs-image.jffs2.img

	This is a raw image in JFFS2 format, which is ready to be
        written to NAND flash. This is used bt the USB flasher.

@item wrs-image.cpio.gz

	If you prefer to run an @i{initramfs} system, this is the file
        you should use. We used it a lot during development, to avoid
        wearing the flash device and wasting time waiting for the flasher
        to run.

@item wrs-image.tar.gz

	We added this out of laziness, because it's easier to create
        your NFS-Root directory from @i{tar} than from @i{cpio}.

@end table

You can uncompress either @i{cpio} or @i{tar}, for example to run NFS-root,
by running one of the following commands in a newly-created empty directory:

@example
   zcat $WRS_OUTPUT_DIR/images/wrs-image.cpio.gz | sudo cpio --extract

   tar xzf $WRS_OUTPUT_DIR/images/wrs-image.tar.gz
@end example

Each of the three archives include a number of device special files in
@i{dev}. The pre-created devices come from
@i{userspace/devices.tar.gz}. Note that the buildroot output
directory, @i{build/buildroot-2011.11/output/target} does not
include any device (and no white-rabbit specific files), so it
cannot be used as a root filesystem by itself.

The content of the final filesystem comes from several sources:

@itemize @bullet

@item The @i{buildroot} output (from its own @file{output/target/}).
@item The switch-specific overlay (@file{userspace/roofs_override}).
@item The @file{images/wr} and @file{images/lib} trees,
      filled but the build scripts.
@item The file @file{userspace/devices.tar.gz}
@item The file @file{$WRS_BASE_DIR/authorized_keys} if it exists.

@end itemize

The final step allows a predefined set of users to enter as system
administrator without the need to type a password (which, anyways is
empty by default).  It is useful if you @i{scp} files in and out of
the switch. In the shipped binaries no user is authorized, but the
root password is still the empty string.

@c ##########################################################################
@node Code layout in a production switch
@chapter Code layout in a production switch

This final chapter is a summary of how we used the two internal flash
memories in the switch, when programmed with the official firmware
binaries. It is meant for people who want to better understand the
boot procedure and possibly customize stuff using higher-level tools,
like erasing and rewriting flash-memory areas from Linux itself.

Unfortunately, the CPU is not able to boot from NAND memory directly,
so the first steps of booting are performed from the @i{dataflash}
device.  Such an SPI memory is used to host the IPL (@i{at91boot}) and
the executable code of @i{barebox}.  The user is not expected to
ever erase this memory; if it happens, the system won't boot and
you'll be forced to re-flash it entirely (or at least the @i{dataflash}
area.

NAND memory is used for user-data: tke boot loader configuration, the
kernel and the filesystem.

This is how the memory is used. While it definitely looks suboptimal,
it is the result of our own history of development and there are
no problems with this ``strange'' split up of space:

@example
   0x0000.0000 - 0x0004.0000    Empty (space for a barebox)
   0x0004.0000 - 0x0008.0000    Barebox environment
   0x0008.0000 - 0x0010.0000    Empty
   0x0010.0000 - 0x0090.0000    Kernel (plenty of space)
   0x0090.0000 - 0x0400.0000    Empty
   0x0400.0000 - 0x0c00.0000    Filesystem space, jffs2
   0x0c00.0000 - 0x2000.0000    Available
@end example

When you boot Linux, the three empty areas are not visible, while
the last area is accessible. This is the content of @file{/proc/mtd}
after boot:

@example
   dev:    size   erasesize  name
   mtd0: 00800000 00020000 "Kernel"
   mtd1: 08000000 00020000 "Filesystem"
   mtd2: 00040000 00020000 "Barebox Environment"
   mtd3: 14000000 00020000 "Available"
   mtd4: 00840000 00000420 "spi0.0-AT45DB642x"
@end example

If you are customizing the switch, you may use the
@file{flash_erase} and @file{cat} to replace individual parts of
the system, like the kernel, or erase the @i{barebox} configuration to
restore the factory defaults.  Note however that you shouldn't
modify the @i{dataflash} device (@code{/dev/mtd4}) unless you really
know what you are doing (for example, the following chapter changes
it by using magic offsets in the commands).

@c ##########################################################################
@node Schematics are Available
@appendix Schematics are Available

The switch schematics for all PCB versions (3.x of the
SCB as well as both 3.1, 3.2 and 3.3 of the backplane)
are available on the Open Hardware Repository, at
@uref{http://www.ohwr.org/documents/180}, which can also be reached
from the @i{Documents} tab of the @i{White Rabbit} project.

Please note that only version 3.2 and 3.3 of both the motherboard and 
the backplane has been shipped commercially; you are interested in 
previous versions only if you are an early developer and have one of 
those in your hands.

@menu
* DIP Switch HW version::
@end menu


@c ==========================================================================
@node DIP Switch HW version
@section DIP Switch HW version

Since v3.3, the backplane include a DIP switch configured by the 
manufacturer in order to define a specific SCB and backplane 
version. This setup is then read by the software in order to load 
the correct FPGA binaries and use the proper I/Os. Please be aware 
that if you upgrade your SCB from LX130T to LX240T but keep the same 
backplane you might need to change the DIP switch configuration. 
Check the code from @code{userspace/libswitchhw/i2c_io.c} code to 
know how to reconfigure the DIP switch for you upgraded device.

For example, the v3.3 backplane with v3.3 LX240T SCB must be configured as bellow:
@example
+--------------+---+---+---+---+
| DIP position | 1 | 2 | 3 | 4 |
+==============+===+===+===+===+
| DIP value    | 1 | 1 | 1 | 0 |
+--------------+---+---+---+---+
@end example





@c ##########################################################################
@node Installing from Jtag
@appendix Installing from Jtag

As an alternative to the serial flasher, you can take control of the
system with a JTAG debugger. Please note that 
the @i{USB Flasher} is @b{really} the preferred technique, but in case
it doesn't work for your, JTAG is the only way to
communicate with the switch.

Each debugger has its own command language, so you will need to adapt 
to yours. What is shown here refers to the @i{peedi} & @i{sam-ice} tools.
These notes are only aimed at low-level developers and leave a lot
unsaid.

@menu
* Using PEEDI::                 
* Using SAM-ICE::               
* Installation the Boot Loader from JTAG::  
@end menu

@c ==========================================================================
@node Using PEEDI
@section Using PEEDI

As a first step, you will need to ensure the JTAG clock is slow enough.
The clock can be no faster than 1/6th of the CPU clock, so you need
3kHz at most (the G45 starts up with an internal oscillator, which has
an unpredictable value between 20kHz and 40kHz).  Then, I would verify
that the internal SRAM is working; I do that with cool food and bad
coffee instead of the usual smelly dead beef.

@smallexample
   clock init
   mem write 0x300000 0xc001f00d
   mem write 0x300004 0xbadc0ffe
   mem read  0x300000 2
   ==> 0x300000: 0xC001F00D 0xBADC0FFE
@end smallexample

Now, you can load your @i{at91bootstrap} to the internal SRAM,
retrieving it from the network or your host filesystem.  Since no boot
loader is there, you should place a breakpoint after @i{at91bootstrap}
initialized SDRAM and the PLL. Finally you can load @i{barebox} and jump
to it. Such step is better performed with the full JTAG clock, or
it would take several dozen minutes.

@smallexample
  mem load at91bootstrap.bin 0x300000
  break add hard 0x300088
  go
  ## wait for the breakpoint to happen
  break del all
  clock normal
  mem load barebox.bin 0x73f00000
  go
@end smallexample

@c ==========================================================================
@node Using SAM-ICE
@section Using SAM-ICE

This section follows the same steps as in @ref{Using PEEDI}, but using
the syntax of the SAM-ICE tool recommended by Atmel

@example
./start
@end example

Checking SRAM

@smallexample
speed 2
w4 0x300000 0xc001f00d
w4 0x300004 0xcbadc0ffe
mem32 0x300000 2
@end smallexample

Uploading at91bootstrap & barebox to DDR

@smallexample
speed 2
r
wreg "R15 (PC)" 300000
loadbin /tftpboot/at91bootstrap.bin 0x300000
SetBP 0x300088 H #Check 0x300088
g
speed a
loadbin /tftpboot/barebox.bin 0x73f00000
ClrBP 1
g
@end smallexample


@c ==========================================================================
@node Installation the Boot Loader from JTAG
@section Installing the Boot Loader from JTAG

After tou managed to load and run @i{barebox.bin},
you will see the following messages on the serial port, at 115200,8N1.
The first 4 lines are printed by @i{at91bootstrap}, the rest by @i{barebox}.

@c FIXME: the messages and prompts
@smallexample
   Start AT91Bootstrap...
   DDR2 Config: 0x39 (NC=0xa, NR=0xd, CAS=0x3, ba_offset = 0x18)
   DDR2 Config: 0x39 (NC=0xa, NR=0xd, CAS=0x3, ba_offset = 0x18)
   Compiled by federico (Jul 31 2012 @ 16:14:34)
   git rev:

   Begin to load image...
   ++++++++
   Loading image done.


   barebox 2012.05.0 (Aug  7 2012 - 13:44:23)

   Board: CERN White Rabbit Switch V3
   Clocks: CPU 400 MHz, master 133 MHz, main 12.000 MHz
   registered netconsole as cs1
   NAND device: Manufacturer ID: 0x2c, Chip ID: 0xbc (Micron NAND 512MiB 1,8V 16-bi
   t)
   Scanning device for bad blocks
   GPIOs: PA4=1 (36), PC7=1 (103)
   Malloc space: 0x73b00000 -> 0x73efffff (size  4 MB)
   Stack space : 0x73af8000 -> 0x73b00000 (size 32 kB)
   envfs: wrong magic on /dev/env0
   no valid environment found on /dev/env0. Using default environment
   running /env/bin/init...
   Starting up barebox [wrs3] (MAC=02:0B:AD:C0:FF:EE)
   starting menu in 5 seconds
@end smallexample

When the boot loader is running, you can boot a kernel and use its
own @i{/dev/mtd} devices to write to the DataFlash and NAND memories.

According to the partition table you have in your kernel sources, you will
see a different set of @i{mtd} files, but you can identify them by looking
at @code{/proc/mtd}:

@c FIXME: mtd layout
@example
   # cat /proc/mtd
   dev:    size   erasesize  name
   mtd0: 00800000 00020000 "Kernel"
   mtd1: 08000000 00020000 "Filesystem"
   mtd2: 00040000 00020000 "Barebox Environment"
   mtd3: 14000000 00020000 "Available"
   mtd4: 00840000 00000420 "spi0.0-AT45DB642x"
@end example

Here above, the DataFlash is @i{/dev/mtd4}, whereas the former partitions
refer to NAND memory.  You should then write @i{at91boot} to offset 0
of the DataFlash and @i{barebox} to offset 0x8400 (33792):

@example
   cat at91bootstrap.bin > /dev/mtd4
   dd bs=33792 seek=1 if=barebox.bin of=/dev/mtd4
@end example

Now you can detach the debugger, press reset and see @i{barebox} starting
without the need for the JTAG any more. The following steps are the same
as already described.

@c ##########################################################################
@node Bugs and Troubleshooting
@appendix Bugs and Troubleshooting

Even if the package is already released and used in production,
some details can be
suboptimal, while some procedures may be tricky and need more explanation.

We are collecting all those issues in the @i{wiki} page of the
project, to avoid frequent updates to this manual to just collect
those details.  So please visit
@url{www.ohwr.org/projects/wr-switch-sw/wiki/Bugs} and
@url{www.ohwr.org/projects/wr-switch-sw/wiki/Troubleshooting}
if you have any problem with this package, but feel free to reach us
on the mailing list if you don't find help there.

@c ##########################################################################
@bye


@c  LocalWords:  gnudd titlepage iftex texinfo CERN timestamping smallexample
@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 PTPd VHDL
@c  LocalWords:  noposix ptpd userspace libswitchhw DataFlash NAND barebox FPGA
@c  LocalWords:  Atmel Kconfig minicom tinyserial ttyUSB bootloader logfile
@c  LocalWords:  nandflash gateware TFTP init wrboot wiki
