Skip to content

S
Software for White Rabbit PTP Core
Commit 9b878a6f authored by Grzegorz Daniluk's avatar Grzegorz Daniluk
Browse files
Options

doc added (writing in progress)

parent 7c55565b
Hide whitespace changes
Inline Side-by-side
Showing with 563 additions and 0 deletions
doc/.gitignore 0 → 100644
View file @ 9b878a6f
*~
*.aux
*.cp
*.cps
*.fn
*.html
*.info
*.ky
*.log
fine-delay.pdf
*.pg
*.texi
*.toc
*.tp
/*.txt
*.vr
doc/Makefile 0 → 100644
View file @ 9b878a6f
#
# Makefile for the documentation directory
#
# Copyright 1994,2000,2010,2011 Alessandro Rubini <rubini@linux.it>
#
#################
# There is not basenames here, all *.in are considered input
INPUT = $(wildcard *.in)
TEXI = $(INPUT:.in=.texi)
INFO = $(INPUT:.in=.info)
HTML = $(INPUT:.in=.html)
TXT = $(INPUT:.in=.txt)
PDF = $(INPUT:.in=.pdf)
ALL = $(INFO) $(HTML) $(TXT) $(PDF)
MAKEINFO ?= makeinfo
%.texi: %.in
@rm -f $@
sed -f ./infofilter $< > $@
emacs -batch --no-site-file -l fixinfo $@
chmod -w $@
%.pdf: %.texi
texi2pdf --batch $<
%.info: %.texi
$(MAKEINFO) $< -o $@
%.html: %.texi
$(MAKEINFO) --html --no-split -o $@ $<
%.txt: %.texi
$(MAKEINFO) --no-headers $< > $@
##############################################
.PHONY: all images check terse clean install
.INTERMEDIATE: $(TEXI)
all: images $(ALL)
$(MAKE) terse
images::
if [ -d images ]; then $(MAKE) -C images || exit 1; fi
check: _err.ps
gs -sDEVICE=linux -r320x200x16 $<
terse:
for n in cp fn ky pg toc tp vr aux log; do rm -f *.$$n; done
rm -f *~
clean: terse
rm -f $(ALL) $(TEXI)
install:
doc/fixinfo 0 → 100644
View file @ 9b878a6f
;; use:
;; emacs -batch -l ./fixinfo.el <file>
;; or, better:
;; emacs -batch --no-site-file -l ./fixinfo.el <file>
(defun fixinfo (file)
(find-file-other-window file)
(message (concat "Maxing texinfo tree in " file))
(texinfo-all-menus-update)
(texinfo-every-node-update)
(save-buffer)
(kill-buffer (current-buffer))
)
;; loop over command line arguments
(mapcar 'fixinfo command-line-args-left)
(kill-emacs)
doc/infofilter 0 → 100644
View file @ 9b878a6f
#! /usr/bin/sed -f
# allow "%" as a comment char, but only at the beginning of the line
s/^%/@c /
#s/[^\\]%.*$//
s/^\\%/%/
#preserve blanks and braces in @example blocks
/^@example/,/^@end example/ s/{/@{/g
/^@example/,/^@end example/ s/}/@}/g
/^@example/,/^@end example/ p
/^@example/,/^@end example/ d
/^@smallexample/,/^@end smallexample/ s/{/@{/g
/^@smallexample/,/^@end smallexample/ s/}/@}/g
/^@smallexample/,/^@end smallexample/ p
/^@smallexample/,/^@end smallexample/ d
# remove leading blanks
s/^[ ]*//
doc/wrpc.in 0 → 100644
View file @ 9b878a6f
\input texinfo @c -*-texinfo-*-
%
% wrpc.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 fine-delay.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 wrpc.info
@settitle White Rabbit PTP Core
@iftex
@afourpaper
@end iftex
@paragraphindent none
@comment %**end of header
@setchapternewpage off
@set update-month August 2012
@set release 2.0
@set tagname wrpc-v2.0
@c WARNING: in @example I Can't use @value{tagname}, so please look for this
@c string when updating the document.
@finalout
@titlepage
@title White Rabbit PTP Core User's Manual
@subtitle @value{update-month} -- Release @value{release}
@subtitle Building and Running
@author Grzegorz Daniluk (CERN BE-CO-HT)
@end titlepage
@headings single
@c ##########################################################################
@iftex
@contents
@end iftex
@c ##########################################################################
@node Top
@top Introduction
This is the user manual for the White Rabbit PTP Core developed on
@code{ohwr.org}. It describes the building and running process. If you don't
want to get your hands dirty and prefer to use the binaries available at
@code{http://www.ohwr.org/projects/wr-cores/files} you can skip
@ref{Building the Core} and move forward directly to
@ref{Running and Configuring}.
@menu
* Repositories and Releases::
* Building the Core::
* Running and Configuring
* Known bugs and missing features::
* Troubleshooting::
@end menu
@c ##########################################################################
@node Repositories and Releases
@chapter Repositories and Releases
This version of the White Rabbit PTP Core is release @value{release}.
The code and documentation is distributed in the following places:
@table @code
@item http://www.ohwr.org/projects/wr-cores/documents
This place hosts the pdf documentation for every official
release.
@item http://www.ohwr.org/projects/wr-cores/files
Here we place the @i{.tar.gz} file for every release,
including the @i{git} tree and synthesized/compiled binaries
@item git://ohwr.org/hdl-core-lib/wr-cores.git
Read-only repository with the complete HDL design of WRPC
@item git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git
Read-only repository with the WRPC LM32 software (incl. WR PTP daemon)
@end table
Other tools useful in building and running WRPC can be fetched from the
following locations:
@table @code
@item git://ohwr.org/misc/hdl-make.git
@i{hdlmake} is used in the HDL synthesis process to build the Makefile based
on the set of Manifest files.
@item http://www.ohwr.org/attachments/download/1133/lm32.tar.xz
LM32 toolchain used to compile the WRPC firmware (software).
@end table
The repositories containing the WRPC gateware and software (@i{wr-cores},
@i{wrpc-sw}) are tagged with @code{@value{tagname}} tag. Other tools
used to build the core and load it into SPEC board should be used in their
newest available versions stored in master branch of an appropriate git
repository (unless specified otherwise in this document).
Any official hot fixes, if any, for this
release will live in the branch called
@code{@value{tagname}-fixes}, in each repository.
@c ##########################################################################
@node Building the Core
@chapter Building the Core
Building the White Rabbit PTP Core is a two step process. First you have to
synthesize the FPGA firmware (gateware). This describes the hardware inside
FPGA that is later used by LM32 software to perform WR synchronization.
To perform the steps below you would need a computer running Linux.
@menu
* HDL synthesis
* LM32 software compilation
@end menu
@c ##########################################################################
@node HDL synthesis
@section HDL synthesis
Before running the synthesis process you have to make sure that your
environment is set correctly. You need the Xilinx ISE Software with free
WebPack license installed on a PC. It contains the script @i{settings32.sh}
and @i{settings32.csh} (depending on the shell you use) that sets up all the
system variables required by Xilinx software. For default installation path the
script is located in:
@example
/opt/Xilinx/<version>/ISE_DS/settings32.sh
@end example
and has to be executed before other tools are used. The easiest way to ensure
that @i{ISE}-related variables are set in the shell is to check if @i{$XILINX}
variable contains the path to your @i{ISE} installation directory.
@b{Note:} current version of @i{hdlmake} tool developed at CERN requires
modification of @i{$XILINX} variable after @i{settings32} script execution.
This, provided that the installation path for @i{ISE} is /opt/Xilinx/<version>)
should look like this:
@example
$ export XILINX=/opt/Xilinx/<version>/ISE_DS
@end example
HDL sources for WR PTP Core can be synthesized with nothing more but Xilinx
ISE software, but using @i{hdlmake} tool developed at CERN is much more
convenient. It creates a synthesis Makefile and ISE project file based on the
set of Manifest.py files deployed among directories inside @i{wr-cores}
repository.
First, please clone the @i{hdlmake} repository from its location given in
@ref{Repositories and Releases}:
@example
$ git clone git://ohwr.org/misc/hdl-make.git <your_hdlmake_location>
@end example
and add the @i{hdlmake} binary to your @i{$PATH} to be able to call it from
any directory:
@example
$ export PATH=<your_hdlmake_location>:$PATH
@end example
@b{Note:} the @i{hdlmake} usage instructions here are based on version 493ce82.
When there will be newer commits, they can be used but please be aware that its
execution parameters may change. In that case please refer to @i{hdlmake}
documentation.
@sp 1
Having Xilinx ISE software and @i{hdlmake} you can clone the main WR PTP Core
git repository and start building the FPGA bitstream. First, please create a
local copy of the @i{wr-cores} in the preferred location on your system. This
release is marked with @value{tagname} tag.
@example
$ git clone git://ohwr.org/hdl-core-lib/wr-cores.git <your_wrpc_location>
$ cd <your_wrpc_location>
$ git checkout wrpc-v2.0
@end example
@b{Note:} alternatively you can get the release sources from the tarball
available in @i{http://www.ohwr.org/projects/wr-cores/files}
@sp 1
The subdirectory which contains the main synthesis Manifest.py for SPEC board
and in which you should perform the whole process is:
@example
$ cd <your_wrpc_location>/syn/spec_1_1/wr_core_demo/
@end example
Executing @i{hdlmake} without any parameters will fetch other git repositories
containing submodules essential for WRPC, and store their local copies to:
@example
<your_wrpc_location>/ip_cores
@end example
After that, the actual synthesis is just the matter of executing the command:
@example
$ make
@end example
just as in a regular software compilation process. This takes (depending on
your computer speed) about 15 minutes and if you are lucky (i.e. there were no
errors) it should create FPGA firmware in two files: @i{spec_top.bit} and
@i{spec_top.bin}. The former can be downloaded to FPGA using Xilinx software
(@i{Impact} or @i{Chipscope Pro}) and Xilinx Platform Cable. The latter can be
used to program the Spartan 6 chip on SPEC using the kernel driver from
@i{spec-sw} repository (usage example in @ref{Running and Configuring}).
@sp 1
If, on the other hand, you would like to clean-up the repository and rebuild
everything from scratch you can use the following commands:
@itemize
@item @i{$ make clean} - removes all synthesis reports and log files;
@item @i{$ make mrproper} - removes spec_top.bin and spec_top.bit files;
@item @i{$ hdlmake clean} - removes all fetched repositories (modules) from
@i{ip_cores} subdirectory.
@end itemize
@c ##########################################################################
@node LM32 software compilation
@section LM32 software compilation
To compile the LM32 software for White Rabbit PTP Core you will need to
download and unpack the LM32 toolchain from the location mentioned already in
@ref{Repositories and Releases}:
@example
$ wget http://www.ohwr.org/attachments/download/1133/lm32.tar.xz
$ tar xJf lm32.tar.xz -C <your_lm32_location>
@end example
Similar as with @i{hdlmake} in @ref{Building the Core}, you will need to add
the LM32 toolchain binaries to you @i{$PATH} to be able to call them from any
directory:
@example
$ export PATH=<your_lm32_location>/lm32/bin:$PATH
@end example
To get the release sources of WRPC software please clone the @i{wrpc-sw} git
repository tagged with @value{tagname} tag:
@example
$ git clone git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git <your_wrpcsw_location>
$ cd <your_wrpcsw_location>
$ git checkout wrpc-v2.0
@end example
@b{Note:} alternatively you can get the release sources from the tarball
available in @i{http://www.ohwr.org/projects/wr-cores/files}
@sp 1
The WRPC software repository contains a ptp-nosposix (that contains the WR PTP
software daemon) in the form of a git submodule. Your fresh local copy cloned
from @i{ohwr.org} has therefore the @i{ptp-noposix} directory empty. To fetch
the ptp-noposix you have to execute the following git commands:
@example
$ git submodule init
$ git submodule update
@end example
Now you have everything that is needed to build the software for WRPC. Before
compilation the decision can be made whether to turn on or not the software
support for Etherbone core that is integrated inside WRPC gateware for SPEC
board. But default it is disabled but can be turned on by setting the value of
@i{WITH_ETHERBONE} variable inside the Makefile. The compilation is made by
a simple command without any additional parameters:
@example
$ make
@end example
The resulting binary @i{wrc.bin} can be then used with the loader from
@i{spec-sw} software package to program the LM32 inside White Rabbit PTP Core
(@ref{Running and Configuring}).
@c ##########################################################################
@node Running and Configuring
@chapter Running and Configuring
@menu
* Downloading firmware to SPEC
* Writing EEPROM and calibration
* Running the Core
@end menu
@c ##########################################################################
@node Downloading firmware to SPEC
@section Downloading firmware to SPEC
There is a Software support for the SPEC board project in @i{ohwr.org}. It
contains a set of Linux kernel drivers and userspace tools written by
Alessandro Rubini and Tomasz Wlostowski that are used to communicate with the
SPEC board plugged into the PCI-Express port of the PC.
The instructions in this section are based on commit 27b4ad9 of @i{spec-sw}
repository and are limited to absolutely minimum required to load WRPC FPGA
and LM32 firmware. The full manual for @i{spec-sw} can be found on:
@i{http://www.ohwr.org/attachments/download/1506/spec-sw-2012-08-08.pdf}.
There will be a newer version of SPEC software support that you would like to
use, the up-to-date documentation can always be found in @i{doc/} subdirectory
of @i{spec-sw} git repository.
@sp 1
First, please clone the git repository of SPEC software support package and
build the kernel driver and userspace tools:
@example
$ git clone git://ohwr.org/fmc-projects/spec/spec-sw.git <your_specsw_location>
$ cd <your_specsw_location>
$ git checkout 27b4ad9
$ make
@end example
Then you have to copy the @i{spec_top.bin} to /lib/firmware/fmc/. changing its
name:
@example
$ cp <your_wrpc_location>/syn/spec_1_1/wr_core_demo/spec_top.bin \
/lib/firmware/fmc/spec-demo.bin
@end example
and after that you are ready to load the @i{spec.ko} driver that configures the
Spartan 6 FPGA on SPEC with a given bitstream (make sure you are in
<your_spacsw_location>:
@example
$ insmod kernel/spec.ko name=demo
@end example
To check if the FPGA firmware file was found by the driver and correctly loaded
to FPGA the @i{dmesg} Linux command can be called. Among plenty of messages
you should be able to find something very similar to:
@example
@noindent
[99883.768214] spec_probe (device 0003:0000)
[99883.768220] spec_probe: current 8639 (insmod)
[99883.768248] spec 0000:03:00.0: PCI INT A -> GSI 16 (level, low) -> IRQ 16
[99883.768302] spec 0000:03:00.0: irq 49 for MSI/MSI-X
[99883.768971] spec_load_files
[99883.774842] spec_load_fpga: got binary file "fmc/spec-demo.bin",
1485512 (0x16aac8) bytes
[99883.966491] spec_load_submodule: load "fmc/spec-demo": 256
@end example
If everything went right up to this moment you can write the LM32 binwry
(@i{wrc.bin}) to the SPEC board. For this purpose, there is a @i{spec-cl} tool
in the @i{spec-sw}. The programming is done with the simple command below:
@example
$ tools/spec-cl <your_wrpcsw_location>/wrc.bin
@end example
@sp 1
Now you should be able to start the Virtual-UART software (also a part of
@i{spec-sw} package) that you will use to interact with the White Rabbit PTP
Core Shell:
@example
$ tools/spec-vuart
@end example
If you are able to see the WRPC Shell prompt @i{wrc#} that means the Core is up
and running on your SPEC. Congratulations !
@c ##########################################################################
@node Writing EEPROM and calibration
@section Writing EEPROM and calibration
@c ##########################################################################
@node Running the Core
@section Running the Core
@c ##########################################################################
@node Known Bugs and missing features
@chapter Known Bugs and missing features
@c ##########################################################################
@node Troubleshooting
@chapter Troubleshooting
@c ##########################################################################
@node WRPC Shell commands
@appendix WRPC Shell Commands
@multitable @columnfractions .5 .5
@item @code{pll init <mode> <ref_channel> <align_pps>} @tab manually run spll_init()
function to initialize SoftPll
@item @code{pll cl <channel>} @tab check if SoftPLL is locked for the channel
@item @code{calibration} @tab
@end multitable
@c ##########################################################################
@bye
@c LocalWords: gnudd titlepage iftex texinfo CERN documentlanguage settitle
@c LocalWords: documentencoding setfilename afourpaper paragraphindent FPGA
@c LocalWords: setchapternewpage finalout gateware ohwr modprobe insmod cset
@c LocalWords: smallexample ctrl timestamp fdelay struct spusa
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment