doc: adding SDBFS format & configuration sections

3f4d81f8 · Benoit Rat · 81717e4a · 3f4d81f8
Commit 3f4d81f8 authored Nov 04, 2019 by Benoit Rat
Hide whitespace changes
Inline Side-by-side

Showing with 123 additions and 0 deletions

wr-starting-kit.md doc/wr-starting-kit.md +123 -0

No files found.
--- a/doc/wr-starting-kit.md
+++ b/doc/wr-starting-kit.md
@@ -622,6 +622,128 @@ For the tutorial we will use the following names:
 * `wrc2#` for `wrc#` console of the main board (wri1/busID=0x0100) on the PC02


+Initial Configuration using SDBFS partition
+------------------------------------
+
+Since version 3.0 of WR PTP Core ([wrpc-sw]), the on-board flash memory chip on the carrier
+is used as a default place for storing calibration parameters and an init script.
+
+The storage format of this information is organized in an SDBFS filesystem that **MUST BE** pre-formatted and
+should be properly configured at least once (in case it has not been done during the manufacturing tests).
+
+### Checking if SDBFS is properly formatted
+
+The first thing to do is to verify that the SDBFS has been properly formatted and configured.
+To do so you should check the trace messages while [connecting to the UART](#connect-to-the-uarts).
+
+In case you see an error while WR Core is initializing such as:
+
+~~~~~{.sh}
+WR Core: starting up...
+...
+No SDB filesystem in i2c eeprom
+~~~~~~~~~~
+
+Or
+
+~~~~~{.sh}
+WR Core: starting up...
+...
+get_persistent_mac: SDB error
+get_persistent_mac: SDB file is empty
+get_persistent_mac: Using W1 serial number
+~~~~~~~~~~
+
+This means that SDBFS as not been founded or that SDBFS is not properly formatted (corrupted).
+In this case you should format SDBFS as detailed in the [next section](#formatting-sdbfs).
+
+In case SDBFS is found but an error message about an "empty SDB file" appears when retrieving
+the MAC address of the device: you should jump to
+[configuring the MAC address](#configuring-mac-address) section.
+
+~~~~~{.sh}
+WR Core: starting up...
+sdbfs: found at 3014656 in Flash
+...
+get_persistent_mac: SDB file is empty
+get_persistent_mac: Using W1 serial number
+~~~~~~~~~~
+
+If none of these warnings arise during initialization this mean that you can skip the next
+steps and go directly to [configuring slave & master mode](#configure-in-slave-master-mode) section.
+
+
+### Formatting SDBFS
+
+> **Warning**: You should skip the following step if you have verified that
+> the SDBFS is [properly formatted](#checking-if-sdbfs-is-properly-formatted).
+
+Therefore, starting from v3.0 you have to write the empty
+SDBFS filesystem image to the flash before running the WRPC. The simplest way of
+doing this is by calling a WR PTP Core shell command:
+
+~~~~~{.sh}
+wrc# sdb fs 0
+~~~~~
+
+You should see the output similar to:
+
+~~~~~{.sh}
+filename: .                 ; first: 2e0000; last: 32007f
+filename: wr-init           ; first: 2f0000; last: 2f00ff
+filename: calibration       ; first: 300000; last: 30007f
+filename: mac-address       ; first: 310000; last: 310005
+filename: sfp-database      ; first: 320000; last: 32007f
+Formatting SDBFS in Flash(0x2e0000)...
+~~~~~
+
+After formatting the SDBFS, you should reconfigure the
+[MAC address](#configuring-mac-address) and the
+[calibration](#calibration).
+
+
+> **Note:** Other methods exists to format SDBFS with a pre-existing binary files:
+> through the PCIe bus ([wrpc-sw].pdf > Appendix C), or using a Xilinx JTAG cable when
+> [running in standalone](#run-in-standalone).
+
+### Configuring MAC address
+
+> **Note:** Configuring properly the MAC address is recommanded but not mandatory.
+
+In case you get the messages at the initialization of WR PTP Core:
+
+~~~~~{.sh}
+WR Core: starting up...
+...
+get_persistent_mac: SDB file is empty
+get_persistent_mac: Using W1 serial number
+~~~~~
+
+Your [SPEC] board will use a "auto-generated" MAC address using the
+thermometer serial number (W1) as is unique among SPEC devices.
+And if even if this MAC should be uniq on this network it has not been
+officially assigned following the [IEEE OUI].
+
+You should get the MAC for your board from its manufacturer. To configure the
+address and store it into the Flash/EEPROM (so that it's automatically loaded
+every time the WRPC starts) you should type two commands in the shell:
+
+~~~~~{.sh}
+wrc# mac set xx:xx:xx:xx:xx:xx
+wrc# mac setp xx:xx:xx:xx:xx:xx
+~~~~~
+
+where `xx:xx:xx:xx:xx:xx` is the MAC address of your board.
+
+To verify it back, you should run
+
+~~~~~{.sh}
+wrc# mac get
+~~~~~
+
+After rebooting the machine.
+
+
 Configure in slave & master mode
 --------------------------------

@@ -1712,6 +1834,7 @@ References
 [FMC fine-delay]: https://sevensols.com/index.php/fmc-del/
 [OHWR]: http://www.ohwr.org/projects/white-rabbit
 [Seven Solutions]: http://www.sevensols.com
+[IEEE OUI]: https://standards.ieee.org/products-services/regauth/index.html

 [wr-switch-guide.pdf]: https://sevensols.com/index.php/products/white-rabbit-switch/
 [wr-nic]: http://www.ohwr.org/projects/wr-nic/