Skip to content
Projects
Groups
Snippets
Help
Loading...
Sign in
Toggle navigation
W
White Rabbit Switch - Software
Project
Project
Details
Activity
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
83
Issues
83
List
Board
Labels
Milestones
Merge Requests
4
Merge Requests
4
CI / CD
CI / CD
Pipelines
Schedules
Wiki
Wiki
image/svg+xml
Discourse
Discourse
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Commits
Issue Boards
Open sidebar
Projects
White Rabbit Switch - Software
Commits
827d0360
Commit
827d0360
authored
Mar 13, 2012
by
Manohar Vanga
Committed by
Alessandro Rubini
Mar 30, 2012
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
docs: review the first half or so of the build pdf
Signed-off-by:
Manohar Vanga
<
manohar.vanga@cern.ch
>
parent
0758ffc7
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
62 additions
and
56 deletions
+62
-56
wrs-build.in
doc/wrs-build.in
+62
-56
No files found.
doc/wrs-build.in
View file @
827d0360
...
...
@@ -18,7 +18,7 @@
% 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
)
% - leading blanks are allowed (this is something I can
no
t live without)
% - braces are automatically escaped when they appear in example blocks
%
...
...
@@ -67,7 +67,7 @@ of the repository at
(or @code{git@@ohwr.org:white-rabbit/wr-switch-sw.git} if you are
granted write access).
If
you
do
n
't need to make
your hands dirty, just skip to @ref{Quick
If you do
not want to get
your hands dirty, just skip to @ref{Quick
Build}.
@menu
...
...
@@ -95,11 +95,11 @@ Build}.
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
'
m
really
amazed
by
his
achievements
.
serious efforts, I
a
m really amazed by his achievements.
The rewriting described in this document (and embodied in the @code{build/}
subdirectory of the @code{wr-switch-sw} package) is meant to make the stuff
more
maintainable
over
time
.
I
'
m an old-fashioned follower of the rule
more maintainable over time. I
a
m an old-fashioned follower of the rule
``first make it work then make it work well'', and this step is expected
to make it work well for everybody.
...
...
@@ -125,9 +125,9 @@ The purpose of the build-script rewrite is achieving the following targets:
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
w
on'
t
need
re
re
-
get
everything
from
the
network
.
In
a
similar
w
ill not need
re-get everything from the network. In a similar
mood, people who already have a local copy of the big packages
(
kernel
,
u
-
boot
,
white
-
rabbit
svn
)
w
on
'
t need to re-download not
(kernel, u-boot, white-rabbit svn) w
ill no
t need to re-download not
even the first time they build the WRS software.
@end itemize
...
...
@@ -150,7 +150,7 @@ rebuilding it all from scratch.
@section Portability
The scripts in their current status are not expected to be very
portable. I
'
m
sure
a
number
of
@
i
{
bashisms
}
exist
,
and
I
did
no
effort
portable. I
a
m 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};
...
...
@@ -158,7 +158,7 @@ actually the scripts have been tested in one system where the
default @i{sh} is @i{dash}.
Similarly, the scripts are likely to fail if you use spaces in directory
names
;
that
'
s because not all
names; that
i
s 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.
...
...
@@ -175,7 +175,7 @@ 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
'
ll
need
to
set
the
variable; but when rebuilding a sub-package you
wi
ll need to set the
variables beforehand. Each sub-package complains if it needs variables
that are not set in your environment.
...
...
@@ -194,10 +194,10 @@ have a similar prefix for the same reason).
The 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
can
'
t
name of the main script. Note that the script can
no
t
be run from the same directory (i.e.: @code{./wrs_build-all}
is not allowed), you must call it from your output directory
using a pathname to invoke it. This variable can
'
t
be
using a pathname to invoke it. This variable can
no
t 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.
...
...
@@ -231,10 +231,10 @@ 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
'll notice we don'
t
have
If you compiled for version 2 you
will notice we do no
t 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
n
'
t add the new archives in there because of their size.
did
no
t add the new archives in there because of their size.
@c ==========================================================================
@node Downloading Files
...
...
@@ -304,15 +304,15 @@ Then run this (but please read more for a better command):
@end example
Note that progress messages are sent to @i{stderr}, so you may want to
save @i{stdout} to a file, like this (
but please read more for a better
command):
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
'
s
a
few
hundred
lines
over
the
many
printed to @i{stderr}. It
i
s 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.
...
...
@@ -353,11 +353,11 @@ to generate the terse output shown above:
| grep '
^
20.
.-..-..
..:
'
@end example
If
you
are
lucky
,
everything
completes
by
itself
in
quite
some
minutes
,
depend
ing
on
you
CPU
,
disk
and
network
speed
.
At
the
end
you
'
ll find your final files in the @code{images}
If you are lucky, everything completes by itself
. The time taken
depend
s
on you CPU, disk and network speed.
At the end you
wi
ll find your final files in the @code{images}
subdirectory. If you are not too lucky, the build stops because
you
'
ve
found
a
bug
in
the
build
scripts
;
most
likely
because
your
you
ha
ve found a bug in the build scripts; most likely because your
setup differs from the ones we have been testing on.
In order to re-run the build from the beginning, please remove (or
...
...
@@ -376,7 +376,7 @@ 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
).
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
...
...
@@ -387,7 +387,7 @@ the complete package.
@chapter 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
.
Such
a
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.
...
...
@@ -396,6 +396,9 @@ The configuration for @i{buildroot} comes from
is then changed only if you pre-set your own @code{CROSS_COMPILE}
variable.
@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}. After making your choices, copy back
...
...
@@ -415,7 +418,7 @@ ignored with a simple warning -- rather than stopping the build procedure.
The version of @i{at91bootstrap} being used in the switch as
@i{Initial Program Loader} is found at @code{http://repository.timesys.com/}
The patches we applied are in the directory @i{patches/at91boot/v3.3},
and
currently
it
is
on
e
patch
only
(
we
are
piggy
-
backing
on
the
Atmel
and currently it is on
ly a single patch
(we are piggy-backing on the Atmel
evaluation board without even changing the board name):
@example
...
...
@@ -427,19 +430,20 @@ The script uncompresses, patches and builds, leaving
the one to be loaded in the hardware.
For simplicity, a known-working binary is part of the @i{binaries}
@c The '
sane
' name?? do you mean '
same
'?
directory of this package as @code{at91bootstrap.bin}, the sane name used
later in the installation instructions.
@
b
{
Warning
}:
with
some
distribution
,
this
compilation
step
will
print
a
scar
ing
message
about
memory
corruption
.
The
message
is
reporting
a
bug
in
@b{Warning}: with some distribution
s
, this compilation step will print
a scar
y
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
'
ll switch to another version in the future.
Maybe we
wi
ll switch to another version in the future.
@c ##########################################################################
@node The Boot Loader
@chapter The Boot Loader
The switch use
r
@i{barebox} as a boot loader. We are running version
The switch use
s
@i{barebox} as a boot loader. We are running version
2011-09, with one simple local patch and the chosen configuration
file. More patches will be needed to customize board names (we are
piggy-backing on the Ronetix PM9G45 board).
...
...
@@ -456,7 +460,7 @@ are currently the following ones:
@end example
The build scripts compile with the following commands, where the
cross-compiler is the one buil
d
by @i{buildroot}. If you run these
cross-compiler is the one buil
t
by @i{buildroot}. If you run these
by hand you can use a different compiler (as shown):
@example
...
...
@@ -470,8 +474,8 @@ by hand you can use a different compiler (as shown):
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 be
useful
-- or may not
.
@code{images/barebox}; this file includes the symbol table and may
(or may not)
be
useful.
@c ##########################################################################
@node The Linux Kernel
...
...
@@ -497,6 +501,7 @@ and are currently the following ones:
The configuration being used is copied from this package, so it
is easier to change it if needed.
@c again, maybe simplify this to a set of commands?
If you want to change the configuration, you can do so after the first
build iteration: change directory to @code{build/kernel}
and run @code{make menuconfig}. After making your choices, copy back
...
...
@@ -524,18 +529,18 @@ package. The step depends on the kernel being available in the
build directory. The modules are then copied into the @code{images}
subdirectory of the main build directory.
Please note that modules (and later user-space) are compiled in-place
,
not in the output directory. The disadvantage is that your repository
becomes dirty with output and intermediate files
; t
he advantage is that
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
. T
he advantage is that
any modification you make to the code is already in the repository
for your to commit.
Currently, the modules build built are @i{wr_vic.ko} (the interrupt
controller) and @i{wr-nic.ko} (the network ``card'' driver). The
@i{wr_rtu.ko} driver is compiled too, but it is not currently used nor
tested.
has it been
tested.
@b{Warning}: I plan to soon rename all modules to have a
n
hyphen
@b{Warning}: I plan to soon rename all modules to have a hyphen
instead of an underscore in the name.
@c ##########################################################################
...
...
@@ -560,7 +565,7 @@ further, the directory @i{tools} includes the following programs:
detects the limit is reached.
@item load-lm32
Loads a program to the internal LM32 soft-cre.
Loads a program to the internal LM32 soft-c
o
re.
@item spi-pll
Uses the @i{opencores_spi} device part of the FPGA bitstream to
...
...
@@ -572,7 +577,7 @@ further, the directory @i{tools} includes the following programs:
The list above used to include @i{devmem2}, but now @i{devmem} is part
of the installed @i{busybox} and has the same command-line interface.
The functions to load the
fpga and the lm
32 have been turned into a
The functions to load the
FPGA and the LM
32 have been turned into a
library, so external programs can link @code{libtools.a}.
Please note that to compiler you need to specify both the kernel
...
...
@@ -590,7 +595,7 @@ integrated in the build scripts.
follows is the old text, kept here for reference.
The Precision Time Protocol Daemon being used is host in a different
repository. It
'
s
the
code
base
that
has
been
ported
to
compile
in
a
repository. It
i
s the code base that has been ported to compile in a
freestanding environment, downloaded from
@code{git://gnudd.com/ptp-noposix.git} .
...
...
@@ -605,6 +610,7 @@ fail for this @i{arm-linux} hosted build.
Additionally, the script installs the header and library for
@i{wr_ipc}, which are needed for later steps and are now part of the
@c hal or HAL?
@i{ptp} repository. Similarly, the script installs headers for the hal
and @i{libptpnetif}.
...
...
@@ -645,7 +651,7 @@ The build of user space is concerned about the following steps:
@chapter VHDL and LM32 Binaries
The binaries are currently missing from the filesystem-making procedures.
You
'
ll need to get the most recent binaries and copy them in the filesystem
You
wi
ll need to get the most recent binaries and copy them in the filesystem
by yourself. This part will be filled last in this document, when the
switches are distributed for production.
...
...
@@ -659,8 +665,8 @@ switches are distributed for production.
The final step in compiling the filesystem is making the CPIO archive
with the overall filesystem contents. This archive can be used as an
@i{initramfs} or uncompressed to some directory. The build procedure
does
n'
t
leave
a
directory
tree
on
disk
because
that
would
require
administrator
privileges
.
I
think
it
'
s best not to call @i{sudo} from
does
no
t leave a directory tree on disk because that would require
administrator privileges. I think it
i
s best not to call @i{sudo} from
within build scripts, to respect our users'
security
concerns
.
The
output
file
is
called
@
i
{
images
/
wrs
-
image
.
cpio
.
gz
}
in
the
build
...
...
@@ -709,10 +715,10 @@ MCH/P2}. The backplane hosts a CP2102 USB adapter and a mini-USB
socket
.
Note
that
you
may
connect
all
6
pins
,
but
only
TX
and
RX
signals
are
needed
.
You
can
work
without
a
serial
port
,
but
it
'
s strongly suggested to
You
can
work
without
a
serial
port
,
but
it
i
s
strongly
suggested
to
connect
it
.
With
a
UART
you
are
able
to
see
diagnostics
and
interact
with
the
boot
loader
or
the
operating
system
even
if
it
fails
to
configure the network. The port uses 3.3V signals, so you
'
ll
most
configure
the
network
.
The
port
uses
3.3
V
signals
,
so
you
wi
ll
most
likely
need
a
level
converter
;
the
figure
below
shows
the
connection
(
black
is
GND
,
orange
is
RX
and
white
is
TX
).
@
sp
1
...
...
@@ -731,13 +737,13 @@ likely need a level converter; the figure below shows the connection
You
can
boot
and
install
the
system
using
a
JTAG
debugger
,
although
the
@
i
{
USB
Flasher
}
is
currently
the
preferred
technique
.
Each
debugger
has
its
own
command
language
,
so
you
'
ll need to adapt to yours. What is
has
its
own
command
language
,
so
you
wi
ll
need
to
adapt
to
yours
.
What
is
shown
here
refers
to
the
@
i
{
peedi
}
tool
.
As a first step, you
'
ll
need
to
ensure
the
JTAG
clock
is
slow
enough
.
As
a
first
step
,
you
wi
ll
need
to
ensure
the
JTAG
clock
is
slow
enough
.
The
clock
can
be
no
faster
than
1
/
6
th
of
the
CPU
clock
,
so
you
need
3
kHz
at
most
(
the
G45
starts
up
with
an
internal
oscillator
,
which
has
an
unpredictable
value
between
20
kHz
and
40
kHz
).
Then
,
I
'
d verify
an
unpredictable
value
between
20
kHz
and
40
kHz
).
Then
,
I
woul
d
verify
that
the
internal
SRAM
is
working
;
I
do
that
with
cool
food
and
bad
coffee
instead
of
the
usual
smelly
dead
beef
.
...
...
@@ -767,7 +773,7 @@ it would take several dozen minutes.
go
@
end
example
On the serial port you
'
ll
see
the
following
messages
at
115200
,
8
N1
.
On
the
serial
port
you
wi
ll
see
the
following
messages
at
115200
,
8
N1
.
The
first
4
lines
are
printed
by
@
i
{
at91bootstrap
},
the
rest
by
@
i
{
barebox
}.
@
c
FIXME
:
the
messages
and
prompts
...
...
@@ -796,7 +802,7 @@ The first 4 lines are printed by @i{at91bootstrap}, the rest by @i{barebox}.
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
'
ll
According
to
the
partition
table
you
have
in
your
kernel
sources
,
you
wi
ll
see
a
different
set
of
@
i
{
mtd
}
files
,
but
you
can
identify
them
by
looking
at
@
code
{/
proc
/
mtd
}:
...
...
@@ -842,7 +848,7 @@ USB cable (on the right).
After shorting the pins you can press reset (the button near the USB
connector). If things go well, the device is enumerated as shown;
you
must
un
-
short
the
wires
at
this
point
or
you
w
on
'
t be able
you must un-short the wires at this point or you w
ill no
t be able
to write the new information to @i{dataflash}
@smallexample
...
...
@@ -888,7 +894,7 @@ The script performs the following steps:
@item It uses the @i{sam-ba} protocol to write to @i{dataflash}.
@end itemize
If all goes well, at the next reset you
'
ll
find
@
i
{
barebox
}
accessing
If all goes well, at the next reset you
wi
ll find @i{barebox} accessing
the network with your preferred MAC address.
The output you must expect from the flasher is like the following, and
...
...
@@ -905,7 +911,7 @@ the process takes half a minute more or less:
Programming done!
@end example
If
you
look
at
the
serial
port
,
during
programming
,
you
'
ll see
If you look at the serial port, during programming, you
wi
ll see
messages like these:
@example
...
...
@@ -925,9 +931,9 @@ After initial installation, the DataFlash only includes up to @i{barebox},
while the rest must still be loaded.
Assuming you have a known-working NFS-Root installation and a TFTP
server, but you do
n'
t
want
to
use
DHCP
because
you
already
have
one
server, but you do
no
t want to use DHCP because you already have one
in your network, the following commands will load a kernel and
boot
it
as
NFS
-
Root
.
You
'
ll need to change IP addresses and names
boot it as NFS-Root. You
wi
ll need to change IP addresses and names
to match your personal situation.
@c FIXME: kernel boot procedure
...
...
@@ -953,7 +959,7 @@ provided patches runs the following three commands:
This means that if you have both DHCP and TFTP, you can just write
your @i{barebox} commands in a file called @i{wrboot} in your TFTP
public location, and the commands will automatically executed at boot.
Actually, I
'
m
currently
using
the
stanza
shown
above
to
boot
my
Actually, I
a
m currently using the stanza shown above to boot my
switch over the network with no interaction at all, while being able
to change the boot procedure on the server while the switch is off.
...
...
@@ -1005,7 +1011,7 @@ With this setup, the @i{dataflash} can be made read-only when accessed
by Linux, for better safety. Normal use cases will be able to change
either the kernel or the filesystem (or both) without touching
@i{dataflash}. On the other hand, @i{at91boot} is unable to deal with
bad
blocks
in
NAND
,
or
with
correction
of
single
-
bit
errors
;
that
'
s
bad blocks in NAND, or with correction of single-bit errors; that
i
s
why it will load its @i{barebox} from @i{dataflash}.
The internal CPU ROM will boot from NAND if it finds the magic
...
...
@@ -1176,7 +1182,7 @@ the PLL, and then runs the test.
The
source
is
distributed
as
a
patch
-
set
over
@
i
{
at91boot
}
(
the
same
version
we
use
to
boot
the
switch
),
in
@
code
{
patches
/
g45memtest
}.
To
compile
,
untar
the
source
,
apply
the
patches
and
compile
.
The
following
commands
are
what
I
used
to
compile
it
(
you
'
ll need to set
following
commands
are
what
I
used
to
compile
it
(
you
wi
ll
need
to
set
@
code
{
CROSS_COMPILE
}
first
,
though
).
@
example
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment