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
86
Issues
86
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
ec79a7bd
Commit
ec79a7bd
authored
Oct 01, 2014
by
Alessandro Rubini
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
doc: describe upgrading from 3.x and 4.0
Signed-off-by:
Alessandro Rubini
<
rubini@gnudd.com
>
parent
6f7fa86a
Show whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
197 additions
and
18 deletions
+197
-18
wrs-developer-manual.in
doc/wrs-developer-manual.in
+67
-16
wrs-user-manual.in
doc/wrs-user-manual.in
+130
-2
No files found.
doc/wrs-developer-manual.in
View file @
ec79a7bd
...
...
@@ -35,7 +35,7 @@
@setchapternewpage off
@set update-month
Septem
ber 2014
@set update-month
Octo
ber 2014
@c the release name below is substituted at build time
@set release __RELEASE_GIT_ID__
...
...
@@ -1036,15 +1036,22 @@ the switch. In the shipped binaries no user is authorized, but the
root password is still the empty string.
@c ##########################################################################
@node Flashing
of WRS-3
@chapter Flashing
of WRS-3
@node Flashing
the Switch
@chapter Flashing
the Switch
This chapter describes the steps to install the
WRS-3
with the
This chapter describes the steps to install the
@sc{wrs}
with the
current firmware images. As far as hardware is concerned, this
procedure describes the installation of the switch with a @i{SCB v3.3}
and a @i{Mini-Backplane v3.3}. Older versions are not documented here
procedure describes the installation of the switch with a @sc{scb}
version 3.3 or 3.4, and a @sc{Mini-Backplane} version 3.3.
Older versions are not documented here
any more (please get an older manual, if needed).
@b{Note:} Most likely you won'
t
need
to
reflash
your
@
sc
{
wrs
}.
Even
if
you
rebuilt
software
from
scratch
,
the
``
update
''
procedure
that
is
available
since
August
2014
(
release
4.0
of
@
t
{
wr
-
switch
-
sw
})
allows
complete
replacement
of
the
firmware
image
without
physical
access
to
the
device
.
@
c
==========================================================================
@
node
USB
connections
@
section
USB
connections
...
...
@@ -1102,6 +1109,10 @@ and enter @emph{"Flashing mode"} is not working. You should contact support.
@node Flashing Procedure
@section Flashing Procedure
If the update procedure, described in the @i{User'
s
Manual
}
is
not
suitable
for
you
(
because
,
for
example
,
you
are
the
manufacturer
),
you
need
physical
access
to
your
@
sc
{
wrs
}
to
flash
it
.
Unlike
what
happened
with
previous
releases
(
up
to
the
end
of
2013
),
the
filesystem
of
the
switch
can
't fit in RAM memory during installation
any more: the image is now downloaded through the network. Thus
...
...
@@ -1121,8 +1132,8 @@ DHCP as IP address for the TFTP transfer.
Also, since release 4.1, you should not provide MAC addresses
while flashing any more. The two MAC addresses are expected to be stored
in @i{dataflash} by the manufacturer and not changed any more. If you
upgrade
d
your switch from a previous software version, please refer
to
upgrade your switch from a previous software version, please refer
to
the @i{User'
s
Manual
}
for
details
.
The
tool
used
to
flash
the
firmware
into
the
switch
is
the
@
i
{
USB
-
loader
}
we
inherited
from
Atmel
.
The
@
file
{
flash
-
wrs
}
script
is
what
...
...
@@ -1616,16 +1627,49 @@ Currently this only applies to the serial number (@t{-n})
@node Storing Hwinfo in a White Rabbit Switch
@section Storing Hwinfo in a White Rabbit Switch
Linux
partitioning
accesses
the
hardware
information
as
a
read
-
only
partition
,
to
prevent
accidental
erasure
.
The
boot
loader
,
on
the
other
hand
,
has
full
access
to
the
@
i
{
dataflash
}
device
.
You can store your @i{hwinfo} using either the @sc{wrs} shell
or the boot loader. The former technique can be performed remotely,
the latter requires access to the serial
console, on the backplane.
@c --------------------------------------------------------------------------
@node From the Linux Shell
@section From the Linux Shell
The information lives in partion @t{mtd5}, as shown in @t{/proc/mtd}
(Memory Technology Device). To avoid accidental erasure, our
filesystem doesn'
t
include
the
device
file
@
t
{/
dev
/
mtd5
},
but
only
the
read
-
only
counterpart
,
@
t
{/
dev
/
mtd5ro
}.
To
write
the
hardware
information
in
a
switch
that
misses
it
,
or
replace
an
existing
set
of
values
,
you
may
use
the
following
@
i
{
barebox
}
commands
(
erasing
is
not
needed
if
the
device
is
blank
).
If
you
built
your
own
@
i
{
hwinfo
},
with
your
MAC
addresses
,
and
you
copied
it
to
@
i
{/
update
}
(
a
good
staging
place
for
files
copied
over
the
network
),
the
following
commands
will
place
the
information
in
place
:
@
smallexample
test
-
c
/
dev
/
mtd5
||
mknod
/
dev
/
mtd5
c
90
10
flash_erase
/
dev
/
mtd5
0
0
cat
/
update
/
hwinfo
>
/
dev
/
mtd5
rm
/
dev
/
mtd5
@
end
smallexample
The
commands
create
the
device
file
if
missing
(
to
prevent
an
ugly
error
message
if
you
already
created
it
),
erase
and
overwrite
the
data
area
,
and
finally
remove
the
device
file
.
You
new
MAC
addresses
will
be
effective
at
the
next
boot
.
@
c
--------------------------------------------------------------------------
@
node
From
the
Barebox
Shell
@
section
From
the
Barebox
Shell
If
you
prefer
creating
or
replacing
@
i
{
hwinfo
}
from
the
boot
loader
,
this
is
the
procedure
.
You
can
't run it with software version 4.0 or
earlier, because our boot loader was unable to access
@i{dataflash}. V4.1 fixed this problem and introduced the @t{sdb}
command in the booloader to access your @i{hwinfo} structure.
@smallexample
addpart
/
dev
/
dataflash0
0x840
@@
0x94800
(
hwinfo
)
erase /dev/dataflash0.hwinfo
dhcp 5
tftp hwinfo /dev/dataflash0.hwinfo
...
...
@@ -1635,7 +1679,14 @@ The code above assumes that the @i{hwinfo} file is available from your
@sc{dhcp/tftp} server. According to your configuration one or more
commands may be redundant.
You
can
verify
successful
writing
by
running
@
i
{
sdbinfo
},
as
shown
The commands rely on a partition being there, and the default
script already created it using the following command:
@smallexample
addpart /dev/dataflash0 0x840@@0x94800(hwinfo)
@end smallexample
You can verify successful writing by running @i{sdb ls}, as shown
below.
@c ==========================================================================
...
...
doc/wrs-user-manual.in
View file @
ec79a7bd
...
...
@@ -35,7 +35,7 @@
@setchapternewpage off
@set update-month
Septem
ber 2014
@set update-month
Octo
ber 2014
@c the release name below is substituted at build time
@set release
__
RELEASE
_
GIT
_
ID
__
...
...
@@ -132,6 +132,126 @@ versions. As usual, it is in the @i{files} tab of @t{ohwr.org}.
V1 and V2 were development items, never shipped.
@c ##########################################################################
@node Upgrading WRS Software
@chapter Upgrading WRS Software
The @sc
{
wrs
}
is shipped with a current version of its software image,
which is sometiems called @i
{
firmware
}
.
If your devices are running a previous version of the software you may
want to upgrade, or you may want to replace the firmware images after
rebuilding your own, as explained in the @i
{
Developer's Manual
}
.
If you run version 4.1 or later, you can ignore this chapter, that
explains a transition between the initial way we passed MAC addresses
and the safer approach we introduced in v4.1
@c ==========================================================================
@node hwinfo
@section hwinfo
Version 4.1 (October 2014) and later ones use a new way to pass
hardware information to all levels of software, such information
includes the MAC addresses for the management Ethernet and the
@sc
{
sfp
}
ports. Information is now stored in a Flash partition called
@i
{
hwinfo
}
, using the @sc
{
sdb
}
file format. @sc
{
sdb
}
is defined in the
@t
{
fpga-configuration-space
}
within @t
{
ohwr.org
}
. Before using
@sc
{
sdb
}
we used to edit the boot loader's configuration at flash
time, a bad practice developed in a hurry.
The @i
{
hwinfo
}
structure is now written to @i
{
dataflash
}
by the
manufacturer, and never changed even when perforiming a complete re-flash
of the device, because the flashing scripts preserve the @i
{
hwinfo
}
memory area.
When upgrading from a pre-4.1 switch software, you need to create this
@i
{
hwinfo
}
data structure. This procedure is mostly automatic, but you
need to be aware of the steps involved, in case something goes wrong.
@c ==========================================================================
@node Upgrading from v4.0
@section Upgrading from v4.0
Version 4.0 and later of @t
{
wr-switch-sw
}
are able to upgrade
themselves if you place the profer files in the @i
{
/update
}
directory
of the @sc
{
wrs
}
. However, in version 4.0 we forgot to provide for
an upgrade of the boot loader.
To upgrade from version 4.0, therefore, the procedure is the following
one:
@itemize @bullet
@item Copy your own @t
{
wrs-firmware.tar
}
for v4.1 into the @i
{
/update
}
partition. This can be the official firwmare or one you built yourself.
Then reboot and wait for everything to settle (the system will reboot
once more by itself).
@item Copy @t
{
wrs-firmware.tar
}
again. And reboot again. The system
will reboot once more by itself.
@item Now you have a running v4.1 with your @i
{
hwinfo
}
in place
and the old MAC addresses preserved.
@end itemize
What follows is a details description of what is happening during
the update, so you can follow the steps without being too
scared (I usually am...):
@itemize @bullet
@item The first time you reboot, the on-switch v4.0 boot scripts
will replace the complete filesystem, the kernel and the @i
{
initramfs
}
-- but not the boot loader. Having replaced the kernel, it
reboots to make it active.
@item At this point in time, we are running the 4.0 boot loader,
that knows its own MAC addresses in the old ugly way, with a 4.1
kernel and filesystem.
@item The v4.1 boot procedure includes a script to create @i
{
hwinfo
}
and save it to flash using the current MAC addresses, if no
valid @i
{
hwinfo
}
exists. Thus, after
the system is booted, @i
{
hwinfo
}
is in place, even if the boot loader
is not using it.
@item Now you place @t
{
wrs-firmware.tar
}
into @i
{
/update
}
a second time, to replace the boot loader using the v4.1
upgrade scripts. (As an alternative, you can just place
@t
{
barebox.bin
}
into @i
{
/update
}
, as v4.1 looks for such file name).
@item When booting, the contents of @i
{
/update
}
are
processed by the v4.1 boot scripts, which install everything
included in @t
{
wrs-firmware.tar
}
, including the boot
loader.
@item When the system automatically reboots to finalize the second
upgrade, you are running the new boot loader, that retrieves your MAC
addresses from the @i
{
hwinfo
}
partition.
@end itemize
@c ==========================================================================
@node Upgrading from v3.x
@section Upgrading from v3.x
Upgrading from versions older than 4.0 (August 2014) requires physical
access to the device and, unfortunately, requires some extra steps
especially if you want to preserve your MAC addresses.
One possible path is flashing version 4.0 (please refer to v4.0
manuals) and then proceed as described in @ref
{
Upgrading from v4.0
}
.
When flashing version 4.0 you'll need to pass your MAC addresses on
the command line of the flasher, so please take not of what they are.
Another option is flashing the latest firwmare version and then build
your own @i
{
hwinfo
}
structure by specifying your MAC addresses.
@t
{
wr-switch-sw
}
includes specific tools for both steps. They are
described in the @i
{
Developer's Manual
}
, because they are expected to
only be performed by the manufacturer, not the final user.
@c ##########################################################################
@node Kconfig Support
@chapter Kconfig Support
...
...
@@ -150,6 +270,10 @@ menuconfig}'' (or @i{gconfig} or @i{kconfig} or the old text-mode
silently enact the default configuration, run ``@t
{
make defconfig
}
''
(this is done by the normal build if no configuration is present).
The released firmware image uses the default configuration, but we'll
soon offer the option to change most of these values at boot-time
(by downloading configuration from a network server) or run-time.
The following configuration options are available
@table @code
...
...
@@ -328,7 +452,7 @@ from, as shown in the log excerpt above. So you'll have your
leading @t
{
#!/bin/sh
}
. Examples in @i
{
wr-switch-sw
}
did not include the
line until April 2014 included.
The @file
{
binaries
}
subdirectory of
this package
includes two known-working
The @file
{
binaries
}
subdirectory of
@t
{
wr-switch-sw
}
includes two known-working
wrboot scripts as examples; one if for use with static IP addresses and
the other relies on DHCP. If you want to override the default NFS-Root
directory mounted from the server (which is @code
{
/tftpboot/<ip-address>
}
)
...
...
@@ -338,6 +462,10 @@ you can add something like the following line to your @file{wrboot} script:
bootargs="
$
bootargs nfsroot
=/
opt
/
root
/
wrs
-
3
"
@end example
@c
==========================================================================
@node Creating an NFS
-
Root Environment for WRS
@section Creating an NFS
-
Root Environment for WRS
In order to create an NFS root directory, you should uncompress
@t
{
wrs
-
image.tar.gz
}
that is created at build time. If you use
a released @t
{
wrs
-
firmware.tar
}
, however, you'll have no overall
...
...
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