\input texinfo    @c -*-texinfo-*-
%
% wrs-software.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-software.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 can't live without)
%   - braces are automatically escaped when they appear in example blocks
%

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

@setchapternewpage off

@set update-month June 2011

@finalout

@titlepage
@title White Rabbit Switch: software repository
@subtitle @value{update-month}

@author Alessandro Rubini (@code{rubini@@gnudd.com})
@end titlepage
@headings single

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

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

This package is meant to include all white-rabbit software.
At this point, it includes part of it but it is being worked on.
@c FIXME

Please note that the documentation itself is split in three different
documents, this includes only part of the story.

@menu
* The Software Package::        
* Compiling the Kernel::        
* Compiling Kernel Modules::    
* The NIC Driver::              
@end menu

@c ##########################################################################
@node The Software Package
@chapter The Software Package

The package hosts the minic and nic drivers for the WR switch, the
user space code, build scripts and testing procedures.  The build
scripts and test procedures are documented in separate files (pdf and
all the other formats are available).

To compile the documentation you are expected to have @i{emacs},
@i{texinfo} and @i{pdftex} installed.  @i{emacs} is used to recreate
the ``prev'', ``next'', ``up'' links used by @i{texinfo}.

While the documentation is mainly my work, most of the code here is not
mine. Tomasz Wlostowski and Maciej Lipinski wrote most of the vhdl and
user-space code; Emilio Cota, with Tomasz, wrote the initial kernel
space implementation; Miguel Baizan and Juan Luis Manas wrote the RTU code.

There are many more people involved in White Rabbit and I'm clearly
misrepresenting most of them here.  If you are involved and you are
editing this file, please add your name in all the proper places.

@menu
* Directory Layout::            
* Role of this document::       
@end menu

@c ==========================================================================
@node Directory Layout
@section Directory Layout


@table @code
@item COPYING
	GNU GPL Version 2. This package is copyrighted by CERN and others,
        and is released as free software.

@item doc/wrs-software.in
	Source for this documentation.

@item doc/wrs-build.in
	Documentation for the build scripts.

@item doc/wrs-test.in
	Documentation for the testing code.

@item build/
	Build scripts used to recompile all the software, documented
        in doc/wrs-build* .

@item kernel/
	Device drivers and support files. Remember to set the @code{LINUX}
        environment variable and your @code{CROSS_COMPILE} prefix in    
        order to compile successfully. If you compile with the
        build scripts this is done automatically for you.

@item userspace/
	Applications used in the switch itself. Again, you need
        @code{CROSS_COMPILE} to be set unless you follow the build
        scripts.

@item on-switch-tests/
	Tests that are meant to be run on the switch itself.
        As of March 2012 only a few tests remain, as older ones
        only applied to V2, and the switch testing is not a
        different project.

@item robustness/
	The robustness demo program, copied from @i{svn} and
        only cleaned up for end-of-line issues (dos newlines and
        trailing spaces).

@item watchdog/
	The code for the ARM7 watchdog processor, copied from @i{svn}
        and only cleaned of for end-of-line problems.

@item test/
	Test procedures, for the switch as a network equipment.
        Documented in doc/wrs-test* .

@item patches/
	The directory hosts patches for both the kernel and
        other packages (as needed by the build scripts).
        Some of the patches here have been spit out by "git format-patch".

@end table

@c ==========================================================================
@node Role of this document
@section Role of this document

While the overall software compilation is described in a separate
document, developers usually need to compile just the sub-parts they
are working with, or get some insight about what the software is doing.

This document, thus, collects notes about compilation of individual parts
separately from the build scripts, as well as some information about
the NIC driver and possibly (over time) other software components.


@c ##########################################################################
@node Compiling the Kernel
@chapter Compiling the Kernel

To compile the kernel, you need to retrieve the pristine sources for
2.6.35 and apply the patches for the switch. You can do that using git
or with old-style tar+patch. See the section about how to get
the sources with @i{git} or @i{tar} and @i{patch}.

Once you have the wrswitch kernel, you should cd to its main directory
and compile in this way. Note that the CROSS_COMPILE prefix may be the
one you built using buildroot or any other @code{arm-linux-gcc}. The
CROSS_COMPILE variable must end with the hyphen that appears before "gcc"
in the name of the actual compiler.

@example
   export ARCH=arm
   export CROSS_COMPILE=/path/to/cross/arm-linux-
   make wrswitchv2_defconfig
   make uImage
@end example

Finally, copy the uImage to your tftp server directory, as the
boot-loader in the switch is preconfigured to get a file called
"uImage" from your tftp server.

@example
   cp arch/arm/boot/uImage /tftpboot
@end example

@menu
* Using Git::                   
@end menu

@c ==========================================================================
@node Using Git
@section Using Git

If you use @i{git}, you are expected to already have some copy of Linus'
official tree. Let's say it's in /usr/src/linux-vanilla.git .  In that
case, you should first check out 2.6.35 and then fetch the wrswitch
branch. The git tree where I have the stuff is

@example
	git://gnudd.com/linux-wrswitchv2/
@end example

What follows is one possible way, adding branches to the vanilla
tree. (I use different names for the various items to help the
non-expert git user in differentiating them, a cleaner approach would
be using "wrswtichv2" for all items in the different contexts).

@example
   cd /usr/src/linux-vanilla.git
   git remote add gnudd git://gnudd.com/linux-wrswitchv2/
   git fetch gnudd
   git checkout -b wr-kernel gnudd/wrswitch2-dev
@end example

Af this point, you checkout is a new branch that corresponds to the
"wrswitch2-dev" branch on my gnudd server.

Another option is creating a different checkout that uses data from
the Linus tree you already have on your system. (Strictly speaking,
you can avoid creating the "linus" remote to fetch it, but I feel this
is clearer).

@example
   export GIT_ALTERNATE_OBJECT_DIRECTORIES=/usr/src/linux-vanilla.git/objects
   mkdir /usr/src/linux-wr
   cd /usr/src/linux-wr
   git init
   git remote add linus /usr/src/linux-vanilla.git/objects
   git remote add gnudd git://gnudd.com/linux-wrswitchv2/
   git fetch linus
   git fetch gnudd
   git checkout -b wr-kernel gnudd/wrswitch2-dev
@end example

Please note that if you don't have a local "Linus" tree first, your
fetch from gnudd will take several hours. You should first fetch from
a mainstream server the official kernel to make this operation fast.

To make the "GIT_ALTERNATE_OBJECT_DIRECTORIES" setting persistent, you
can save it to local repository:

  echo /usr/src/linux-vanilla/objects > .git/objects/info/alternates

@c ==========================================================================
@node Using Tar and Patch
@section Using Tar and Patch

If you are not a git user, you might apply the patches, with this
procedure, using your national mirror instead of ch.kernel.org.
Let's assume your starting current directory is the @code{wr-switch-sw}
main directory

@example
   DOCDIR=$(/bin/pwd)
   mkdir /usr/src/linux-wr
   cd /usr/src/linux-wr
   wget ftp://ftp.ch.kernel.org/pub/linux/kernel/v2.6/linux-2.6.35.tar.bz2
   tar xjf linux-2.6.35.tar.bz2
   mv linux-2.6.35/* linux-2.6.35/.??* .
   rmdir linux-2.6.35
   for n in in $DOCDIR/patches/kernel/v2.6.35/*patch; do
       cat $n | patch -p1
   done
@end example


@c ##########################################################################
@node Compiling Kernel Modules
@chapter Compiling Kernel Modules

To compile the kernel drivers you need to run "make" in the @code{kernel/}
subdirectory of the package, after setting up
the proper environment variables:

@table @code
@item LINUX
         should point to the kernel directory. For example,
         export LINUX=/usr/src/linux-wr
@item CROSS_COMPILE
         should be the same prefix you used to cross-compile the
         kernel. If CROSS_COMPILE_ARM is set, it is used as a
         default (the name CROSS_COMPILE_ARM is used in wrdev2 scripts)
@item ARCH
         should be "arm", but the Makefile sets it if not predefined.
@end table

With the variables in place, after "make" you'll have a few kernel
modules, with extension ".ko", that should be copied to the target
system and loaded. Let's assume the target is T=192.168.1.23

@example
    scp $(find . -name '*.ko') root@@$T:/wr/lib/modules
@end example

The previous command assumes you either know the root password of your
private key is authorised in the target system. The latter happens if
you build the filesystem using wrdev2 or the build scripts
part of this package.


@c ##########################################################################
@node The NIC Driver
@chapter The NIC Driver

The @code{kernel/nic/} directory includes the NIC driver for white rabbit.

The has been laid out to be as understandable as possible, since I'm
not the one who's going to debug it.

These notes are for the ones who will debug my crap. The published one
will be different, hopefully.

@menu
* The Makefile::                
* The Naming Conventions::      
* The NIC Files::               
@end menu

@c ==========================================================================
@node The Makefile
@section The Makefile

You can "export WRN_DEBUG=y" to force all pr_debug and netdev_dbg
into real printks (with KERN_DEBUG priority: you get them in dmesg
or you need to raise the console priority to see them on the console).

@c ==========================================================================
@node The Naming Conventions
@section The Naming Conventions

@table @code
@item wrn_

      as a prefix is used for all functions and macros, so you
      immediately know if sth is ours or comes from elsewhere
      (as an exception, names of our own bits and registers are kept
      as I got them, the context should say sth about what they arr)

@item wrn

      is always a pointer to the wr-nic overall structure

@item ep

      is the pointer to the endpoint structure
@item dev

      is the pointer to the network device (device.c is an
      exception, is uses "netdev" instead, sorry for the confusion)
@end table

@c ==========================================================================
@node The NIC Files
@section The NIC Files

The module is called wr-nic.ko which comes from several object files.
This is the layout. Files which need to be fixed have FIXME inside and
in this list as well.

@table @i
@item ../wbgen-regs/

        The directory includes the register lists. See the README
	in there about how to recreate them.

@item nic-hardware.h

        This includes only #defines for magic project-wide constants.
	It then includes the wbgen-generated headers for indivitual
	register blocks.

@item wr-nic.h

        the header is used for sharing stuff between sources. Unlike
        the previous one, which it includes, it define kernel-level
	abstractions.

@item module.c

        registering and unregistering the module

@item device.c

        the actual probe and remove functions, and the driver structure

@item endpoint.c

        Talking with the actual endpoints, including the probe part.
	Mii/phy stuff is here, as well as the polling timer for link status.

@item nic-core.c

        standard networking stuff: interrupts and so on

@item ethtool.c

        ethtool operations

@item pps.c

        the pulse-per-second mechanism. This might want to be registered
        in Linux using drivers/pps, but it must be looked at. This
        file is currently registering itself as a timesource.

@item timestamp.c

        all the stuff related to timestamping

@item dmtd.c

        calibration and readout

@end table
@c ##########################################################################
@bye


@c  LocalWords:  texinfo pdftex wrswitch linux
