Skip to content

W
White Rabbit Starting Kit
Source
Select Git revision
...
Target
Select Git revision
 
Commits (35)
Hide whitespace changes
Inline Side-by-side
Showing with 949 additions and 1159 deletions
.gitignore
View file @ 4364d91e
# .gitignore file
xcompiler/*
# OS generated files #
######################
*.bak
......
.gitmodules
View file @ 4364d91e
[submodule "spec-sw"]
path = spec-sw
url = git://ohwr.org/fmc-projects/spec/spec-sw.git
[submodule "etherbone"]
path = etherbone
url = git://ohwr.org/hdl-core-lib/etherbone-core.git
url = https://ohwr.org/project/spec-sw.git
[submodule "wr-nic"]
path = wr-nic
url = https://ohwr.org/project/wr-nic.git
[submodule "fmc-dio"]
path = fmc-dio
url = https://ohwr.org/project/fmc-dio-5chttla.git
[submodule "wrpc-sw"]
path = wrpc-sw
url = https://ohwr.org/project/wrpc-sw.git
[submodule "coht-vic"]
path = coht-vic
url = https://gitlab.cern.ch/cohtdrivers/coht-vic.git
Makefile
View file @ 4364d91e
......@@ -14,30 +14,40 @@
## will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
########################################################################
SUBMOD_DIRS=spec-sw etherbone
MAKE_DIRS = spec-sw etherbone/api #tools
SUBMOD_DIRS=spec-sw wr-nic fmc-dio coht-vic
MAKE_DIRS = spec-sw wr-nic fmc-dio coht-vic #tools
#RUNME := $(shell test -d $(FMC_DRV) || git submodule update --init)
LM32_XCOMPILER_URL="https://www.ohwr.org/project/wrpc-sw/uploads/2776ce0ba43503d1486ae205b48fb450"
LM32_XCOMPILER_NAME="lm32_host_64bit.tar.xz"
XCOMPILER_DIR="xcompiler"
LM32_XCOMPILER_NAME_DIR="lm32-gcc-4.5.3"
#RUNME := $(shell test -d $(FMC_DRV) || git submodule update --init)
## Call the sub folder Makefiles
all clean install: init
@for d in $(MAKE_DIRS); do $(MAKE) -C $$d $@ || exit 1; done
@if [ "x$@" = "xinstall" ]; then ./scripts/wr-ssk-get -i; fi
@if [ "x$@" = "xinstall" ]; then ./scripts/wr-ssk-get -i; cp wrpc-sw/tools/wrpc-vuart /usr/local/sbin; fi
## Init repo and create the .INIT file to not do it again
init: .INIT
.INIT:
git submodule init
.INIT:
git submodule init
@ $(MAKE) update
@ $(MAKE) patch
@touch .INIT; \
patch:
./scripts/wr-git-patch
## Force updating the submodules and fetch new gateware
update:
./scripts/wr-ssk-get -f
git submodule update
cd spec-sw
git submodule update
@rm -rf $(XCOMPILER_DIR)
mkdir -p $(XCOMPILER_DIR)
cd $(XCOMPILER_DIR) && wget $(LM32_XCOMPILER_URL)/$(LM32_XCOMPILER_NAME) \
&& tar xvf $(LM32_XCOMPILER_NAME)
cd wrpc-sw && make spec_defconfig && \
CROSS_COMPILE="$(shell pwd)/$(XCOMPILER_DIR)/$(LM32_XCOMPILER_NAME_DIR)/bin/lm32-elf-" make
coht-vic @ 44bb1e7b
Subproject commit 44bb1e7bafdcb82eaf3ce0c89157ba359b08d18c
doc/README.md 0 → 100644
View file @ 4364d91e
Intro
==========
The document has been written in markdown format and can be directly
read from github, gitlab or bitbucket
PDF Generation
===============
You might need to install `pandoc` software to generate `.pdf` from `.md`.
sudo apt-get install pandoc
To generate a specific document you should enter its own directory and execute
make
If you have some Latex compilation error please install the following packages
sudo apt-get install texlive texlive-latex-extra
### pandoc.latex
The file pandoc.latex is a latex template in order to add all special latex customization
to the markdown file. In case some of latex package are not working properly, the user
should try to modify this file.
Syntax
===========
> ***NOTES:*** The syntax used in this document is Markdown. We recommand to follow the strict
markdown syntax explained on [bitbucket](https://bitbucket.org/tutorials/markdowndemo).
doc/img/ssk_ txpps.png
View replaced file @ 8269bb7c View file @ 4364d91e
doc/img/ssk_ txpps.png

61.2 KB | W: | H:

doc/img/ssk_ txpps.png

90.5 KB | W: | H:

doc/img/ssk_ txpps.png
doc/img/ssk_ txpps.png
doc/img/ssk_ txpps.png
doc/img/ssk_ txpps.png
  • 2-up
  • Swipe
  • Onion skin
doc/img/ssk_100Hz.png
View replaced file @ 8269bb7c View file @ 4364d91e
doc/img/ssk_100Hz.png

191 KB | W: | H:

doc/img/ssk_100Hz.png

140 KB | W: | H:

doc/img/ssk_100Hz.png
doc/img/ssk_100Hz.png
doc/img/ssk_100Hz.png
doc/img/ssk_100Hz.png
  • 2-up
  • Swipe
  • Onion skin
doc/img/ssk_components.jpg 100755 → 100644
View file @ 4364d91e
File mode changed from 100755 to 100644
doc/img/ssk_configs.png
View replaced file @ 8269bb7c View file @ 4364d91e
doc/img/ssk_configs.png

72.8 KB | W: | H:

doc/img/ssk_configs.png

40.4 KB | W: | H:

doc/img/ssk_configs.png
doc/img/ssk_configs.png
doc/img/ssk_configs.png
doc/img/ssk_configs.png
  • 2-up
  • Swipe
  • Onion skin
doc/img/ssk_inside.jpg 100755 → 100644
View replaced file @ 8269bb7c View file @ 4364d91e
doc/img/ssk_inside.jpg

460 KB | W: | H:

doc/img/ssk_inside.jpg

384 KB | W: | H:

doc/img/ssk_inside.jpg
doc/img/ssk_inside.jpg
doc/img/ssk_inside.jpg
doc/img/ssk_inside.jpg
  • 2-up
  • Swipe
  • Onion skin
doc/img/ssk_lemo.jpg 100755 → 100644
View file @ 4364d91e
File mode changed from 100755 to 100644
doc/img/ssk_playdio.png
View replaced file @ 8269bb7c View file @ 4364d91e
doc/img/ssk_playdio.png

15.9 KB | W: | H:

doc/img/ssk_playdio.png

41.4 KB | W: | H:

doc/img/ssk_playdio.png
doc/img/ssk_playdio.png
doc/img/ssk_playdio.png
doc/img/ssk_playdio.png
  • 2-up
  • Swipe
  • Onion skin
doc/img/ssk_pps-setup.png
View replaced file @ 8269bb7c View file @ 4364d91e
doc/img/ssk_pps-setup.png

34.8 KB | W: | H:

doc/img/ssk_pps-setup.png

67 KB | W: | H:

doc/img/ssk_pps-setup.png
doc/img/ssk_pps-setup.png
doc/img/ssk_pps-setup.png
doc/img/ssk_pps-setup.png
  • 2-up
  • Swipe
  • Onion skin
doc/img/ssk_sfp.jpg 100755 → 100644
View replaced file @ 8269bb7c View file @ 4364d91e
doc/img/ssk_sfp.jpg

351 KB | W: | H:

doc/img/ssk_sfp.jpg

285 KB | W: | H:

doc/img/ssk_sfp.jpg
doc/img/ssk_sfp.jpg
doc/img/ssk_sfp.jpg
doc/img/ssk_sfp.jpg
  • 2-up
  • Swipe
  • Onion skin
doc/img/ssk_usb.jpg 100755 → 100644
View file @ 4364d91e
File mode changed from 100755 to 100644
doc/pandoc.latex
View file @ 4364d91e
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Pandoc Template used by Seven Solution to generate pdf from markdown
%% files.
%%
%% Authors:
%% - Benoit Rat (Seven Solutions, www.sevensols.com)
%%
%% GNU Lesser General Public License Usage
%% This file may be used under the terms of the GNU Lesser
%% General Public License version 2.1 as published by the Free Software
%% Foundation and appearing in the file LICENSE.LGPL included in the
%% packaging of this file. Please review the following information to
%% ensure the GNU Lesser General Public License version 2.1 requirements
%% will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[a4paper,oneside,$if(fontsize)$$fontsize$,$endif$$if(lang)$$lang$,$endif$]{$documentclass$}
\usepackage{amssymb,amsmath}
\usepackage[left=2.2cm,right=2.2cm,top=3cm,bottom=3cm]{geometry}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Xetex.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{ifxetex,ifluatex}
\ifxetex
\usepackage{fontspec,xltxtra,xunicode}
\defaultfontfeatures{Mapping=tex-text,Scale=MatchLowercase}
\else
\ifluatex
\usepackage{fontspec}
\defaultfontfeatures{Mapping=tex-text,Scale=MatchLowercase}
\else
\usepackage[utf8]{inputenc}
\fi
\fi
\ifxetex
\usepackage[setpagesize=false, % page size defined by xetex
unicode=false, % unicode breaks when used with xetex
xetex,
colorlinks=true,
urlcolor=blue,
anchorcolor=blue,
linkcolor=blue]{hyperref}
\else
\usepackage[unicode=true,
colorlinks=true,
linkcolor=blue]{hyperref}
\fi
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Generic
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
$if(url)$
\usepackage{url}
$endif$
\usepackage{calc}
\hypersetup{breaklinks=true, pdfborder={0 0 0}}
\usepackage{pbox}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Environment for code formatting
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Define the background (shade) color
\usepackage{color}
\definecolor{shadecolor}{RGB}{$bg-color$}
\definecolor{darkgreen}{RGB}{0,125,0}
\definecolor{darkred}{RGB}{170,0,0}
\definecolor{turquoise}{RGB}{20,100,100}
$if(listings)$
\usepackage{fancyvrb, listings, color}
\lstset{%
basicstyle=\small\ttfamily,
breaklines=true,
fancyvrb=true,
tabsize=2,
columns=fullflexible,
keywordstyle=\color{blue}\textbf,
identifierstyle=,
commentstyle=\color{darkgreen}\textit,
stringstyle=\color{red},
backgroundcolor=\color{shadecolor},
}
\lstdefinelanguage{sh}
{
sensitive=true,
keywords={sudo},
alsoletter={\#,:,>},%
emph={>:\# ,>:$$},
moreemph={wrc\# ,wrc1\# ,wrc2\# , >spusa:\# ,>tornado:\# },
emphstyle=\color{darkred},
comment=[l]{\#\#},%
morestring=[s]{\{}{\}},
keywordstyle=\color{blue}\textbf,
commentstyle=\color{darkgreen}\textit,
stringstyle=\color{turquoise},
backgroundcolor=\color{shadecolor},
}
$endif$
$if(lhs)$
\lstnewenvironment{code}
{}
{}
$endif$
$if(bg-color)$
% redefine env verbatim to be used to hold the code of any language.
\usepackage{framed}
\let\oldverbatim=\verbatim
\renewenvironment{verbatim}
{
\begin{snugshade}
\begin{oldverbatim}
}
{
\end{oldverbatim}
\end{snugshade}
}
% Redefined \textttt to add it background color
\usepackage{soul, color, url}
\sethlcolor{shadecolor}
\let\OldTexttt\texttt
\renewcommand{\texttt}[1]{\OldTexttt{\hl{#1}}}
% Add highlighting environment (when background color)
$if(highlighting-macros)$
$highlighting-macros$
\renewenvironment{Shaded}{
\begingroup
\fontsize{10pt}{12pt}\selectfont
\begin{snugshade}
}
{
\end{snugshade}
\endgroup
}
$endif$
$else$
$if(highlighting-macros)$
% Add highlighting environment (without background color)
$highlighting-macros$
$endif$
$endif$
\usepackage{alltt}
\let\oldquote=\quote
\renewenvironment{quote}
{
\begingroup
\sffamily %sans-serif font
\slshape %slated (almost italic)
\fontsize{10pt}{12pt}\selectfont
}
{
\endgroup
}
$if(verbatim-in-note)$
%\usepackage{fancyvrb}
$endif$
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Graphics & Tables
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{float} % provides the H option for float placement
%% Tables
$if(tables)$
\usepackage{ctable}
$endif$
%% Images
\usepackage{graphicx}
% We will generate all images so they have a width \maxwidth. This means
% that they will get their normal width if they fit onto the page, but
% are scaled down if they would overflow the margins.
\makeatletter
\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth
\else\Gin@nat@width\fi}
\makeatother
\makeatletter
\def\maxheight{\ifdim\Gin@nat@height>10cm10cm
\else\Gin@nat@height\fi}
\makeatother
\let\Oldincludegraphics\includegraphics
\renewcommand{\includegraphics}[1]{\Oldincludegraphics[width=\maxwidth, height=\maxheight, keepaspectratio]{#1}}
$if(subscript)$
\newcommand{\textsubscr}[1]{\ensuremath{_{\scriptsize\textrm{#1}}}}
$endif$
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Lang (TODO: clean this, without breaking)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
$if(lang)$
\ifxetex
\usepackage{polyglossia}
\newcommand{\euro}{€}
\setmainlanguage{$lang$}
\else
\usepackage{babel}
\usepackage{eurosym}
\fi
$endif$
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% List
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\usepackage{enumitem}
$if(fancy-enums)$
% Redefine labelwidth for lists; otherwise, the enumerate package will
% cause markers to extend beyond the left margin.
\makeatletter\AtBeginDocument{%
\renewcommand{\@listi}
{
\setlength{\labelwidth}{4em}
\leftmargin=25pt
\rightmargin=0pt
\labelsep=7pt
\labelwidth=20pt
\itemindent=0pt
\listparindent=0pt
\topsep=2pt plus 2pt minus 2pt
\partopsep=0pt plus 1pt minus 10pt
\parsep=2pt plus 1pt
\itemsep=\parsep
}
}\makeatother
\usepackage{enumerate}
$endif$
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}
\setlength{\emergencystretch}{3em} % prevent overfull lines
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Chapters & Section
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% chapters
\usepackage{titlesec}
\titleformat{\chapter}[block]
{\normalfont\HUGE\bfseries}{\LARGE\thechapter.}{1ex}{}
\titlespacing*{\chapter}{0pt}{-19pt}{0pt}
% Sections
$if(numbersections)$
\setcounter{secnumdepth}{2}
$else$
\setcounter{secnumdepth}{0}
$endif$
\let\oldsection\section
\renewcommand{\section}{\clearpage\oldsection}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Footer & Header
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
$if(verbatim-in-note)$
% allows verbatim text in footnotes
$endif$
\usepackage{fancyhdr}
\fancyhf{}
\fancyhead[R]{\nouppercase{\leftmark}}
\fancyfoot[L]{ www.sevensols.com/whiterabbitsolution}% empty left
\fancyfoot[L]{\raisebox{-25pt}{\includegraphics{logo.png}}}
\fancyfoot[C]{\raisebox{-15pt}{\small \url{www.sevensols.com/whiterabbitsolution}}}
\fancyfoot[R]{\raisebox{-15pt}{\thepage}}
\pagestyle{fancy} % Sets fancy header and footer
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Bibliography
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
$if(natbib)$
\usepackage{natbib}
\bibliographystyle{plainnat}
$endif$
$if(biblatex)$
\usepackage{biblatex}
$if(biblio-files)$
\bibliography{$biblio-files$}
$endif$
$endif$
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Title page (like texinfo)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
$if(title)$
\title{$title$}
$endif$
$if(author)$
\author{$for(author)$$author$$sep$ \and $endfor$}
$endif$
$if(date)$
\date{$date$}
$endif$
\makeatletter
\def\thickhrulefill{\leavevmode \leaders \hrule height 1pt\hfill \kern \z@}
\renewcommand{\maketitle}{\begin{titlepage}%
\let\footnotesize\small
\let\footnoterule\relax
\parindent \z@
\reset@font
\null\vfil
\begin{flushleft}
\Huge \textbf{\@title}
\end{flushleft}
\par
\hrule height 4pt
\par
\begin{flushright}
\large \@date \par
\end{flushright}
\vskip 500\p@
\vfil\null
\begin{flushleft}
\Large \textbf{\@author}
\end{flushleft}
\hrule height 2pt
\end{titlepage}%
\setcounter{footnote}{0}%
}
\makeatother
%======================================================================%
%======================================================================%
\begin{document}
$if(title)$
\maketitle
$endif$
$for(include-before)$
$include-before$
$endfor$
$if(toc)$
\setcounter{tocdepth}{2}
\tableofcontents
\clearpage
$endif$
$body$
$if(natbib)$
$if(biblio-files)$
$if(biblio-title)$
$if(book-class)$
\renewcommand\bibname{$biblio-title$}
$else$
\renewcommand\refname{$biblio-title$}
$endif$
$endif$
\bibliography{$biblio-files$}
$endif$
$endif$
$if(biblatex)$
\printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$
$endif$
$for(include-after)$
$include-after$
$endfor$
\end{document}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Pandoc Template used by Seven Solution to generate pdf from markdown
%% files.
%%
%% Authors:
%% - Benoit Rat (Seven Solutions, www.sevensols.com)
%%
%% GNU Lesser General Public License Usage
%% This file may be used under the terms of the GNU Lesser
%% General Public License version 2.1 as published by the Free Software
%% Foundation and appearing in the file LICENSE.LGPL included in the
%% packaging of this file. Please review the following information to
%% ensure the GNU Lesser General Public License version 2.1 requirements
%% will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[a4paper,oneside,table,$if(fontsize)$$fontsize$,$endif$$if(lang)$$lang$,$endif$]{$documentclass$}
\usepackage{amssymb,amsmath}
\usepackage[left=2.2cm,right=2.2cm,top=2cm,bottom=2cm]{geometry}
\providecommand{\tightlist}{%
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Xetex.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{ifxetex,ifluatex}
\ifxetex
\usepackage{fontspec,xltxtra,xunicode}
\defaultfontfeatures{Mapping=tex-text,Scale=MatchLowercase}
\else
\ifluatex
\usepackage{fontspec}
\defaultfontfeatures{Mapping=tex-text,Scale=MatchLowercase}
\else
\usepackage[utf8]{inputenc}
\fi
\fi
\ifxetex
\usepackage[setpagesize=false, % page size defined by xetex
unicode=false, % unicode breaks when used with xetex
xetex,
colorlinks=true,
urlcolor=darksevenblue,
anchorcolor=darksevenblue,
linkcolor=darksevenblue]{hyperref}
\else
\usepackage[unicode=true,
colorlinks=true,
linkcolor=darksevenblue]{hyperref}
\fi
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Generic
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
$if(url)$
\usepackage{url}
$endif$
\usepackage{calc}
\hypersetup{breaklinks=true, pdfborder={0 0 0}}
\usepackage{pbox}
\usepackage{wallpaper}
%% Define common color
\usepackage{color}
\definecolor{darksevenblue}{RGB}{10,100,130}
\definecolor{sevensolsblue}{RGB}{15,130,175}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Environment for code formatting
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Define the background (shade) color
\usepackage{color}
\definecolor{darkblue}{RGB}{8,40,80}
\definecolor{shadecolor}{RGB}{$bg-color$}
\definecolor{darkgreen}{RGB}{0,125,0}
\definecolor{darkred}{RGB}{170,0,0}
\definecolor{turquoise}{RGB}{20,100,100}
$if(listings)$
\usepackage{fancyvrb, listings, color}
\lstset{%
basicstyle=\small\ttfamily,
breaklines=true,
fancyvrb=true,
tabsize=2,
columns=fullflexible,
keywordstyle=\color{blue}\textbf,
identifierstyle=,
commentstyle=\color{darkgreen}\textit,
stringstyle=\color{red},
backgroundcolor=\color{shadecolor},
}
\lstdefinelanguage{sh}
{
sensitive=true,
keywords={sudo},
alsoletter={\#,:,>},%
emph={>:\# ,>:$$},
moreemph={wrc\# ,wrc1\# ,wrc2\# ,root@wrztp,\/\#},
emphstyle=\color{darkred},
comment=[l]{\#\#},%
morestring=[s]{\{}{\}},
keywordstyle=\color{blue}\textbf,
commentstyle=\color{darkgreen}\textit,
stringstyle=\color{turquoise},
backgroundcolor=\color{shadecolor},
}
$endif$
$if(lhs)$
\lstnewenvironment{code}
{}
{}
$endif$
$if(bg-color)$
% redefine env verbatim to be used to hold the code of any language.
\usepackage{framed}
\let\oldverbatim=\verbatim
\renewenvironment{verbatim}
{
\begin{snugshade}
\begin{oldverbatim}
}
{
\end{oldverbatim}
\end{snugshade}
}
% Redefined \textttt to add it background color
\usepackage{soul, color, url}
\sethlcolor{shadecolor}
\let\OldTexttt\texttt
\renewcommand{\texttt}[1]{\OldTexttt{\hl{#1}}}
% Add highlighting environment (when background color)
$if(highlighting-macros)$
$highlighting-macros$
\renewenvironment{Shaded}{
\begingroup
\fontsize{10pt}{12pt}\selectfont
\begin{snugshade}
}
{
\end{snugshade}
\endgroup
}
$endif$
$else$
$if(highlighting-macros)$
% Add highlighting environment (without background color)
$highlighting-macros$
$endif$
$endif$
\usepackage{alltt}
\let\oldquote=\quote
\renewenvironment{quote}
{
\begingroup
\sffamily %sans-serif font
\slshape %slated (almost italic)
\fontsize{10pt}{12pt}\selectfont
}
{
\endgroup
}
$if(verbatim-in-note)$
%\usepackage{fancyvrb}
$endif$
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Graphics & Tables
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{float} % provides the H option for float placement
\floatplacement{figure}{H}
%% Tables
$if(tables)$
\usepackage{ctable}
\usepackage{longtable}
% alternate rowcolors for all long-tables
\let\oldlongtable\longtable
\let\endoldlongtable\endlongtable
\renewenvironment{longtable}{\rowcolors{2}{white}{shadecolor}\small\oldlongtable}{\endoldlongtable\normalsize}
% Change style for first row
\let\oldtoprule\toprule
\renewcommand{\toprule}{\oldtoprule\rowcolor{white}}
$endif$
%% Images
\usepackage{caption,subcaption}
% Redefine \includegraphics so that, unless explicit options are
% given, the image width will not exceed the width or the height of the page.
% Images get their normal width if they fit onto the page, but
% are scaled down if they would overflow the margins.
\makeatletter
\def\ScaleWidthIfNeeded{%
\ifdim\Gin@nat@width>\linewidth
0.8\linewidth
\else
\Gin@nat@width
\fi
}
\def\ScaleHeightIfNeeded{%
\ifdim\Gin@nat@height>0.9\textheight
0.7\textheight
\else
\Gin@nat@width
\fi
}
\makeatother
\setkeys{Gin}{width=\ScaleWidthIfNeeded,height=\ScaleHeightIfNeeded,keepaspectratio}
$if(subscript)$
\newcommand{\textsubscr}[1]{\ensuremath{_{\scriptsize\textrm{#1}}}}
$endif$
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Lang (TODO: clean this, without breaking)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
$if(lang)$
\ifxetex
\usepackage{polyglossia}
\newcommand{\euro}{€}
\setmainlanguage{$lang$}
\else
\usepackage{babel}
\usepackage{eurosym}
\fi
$endif$
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% List
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\usepackage{enumitem}
$if(fancy-enums)$
% Redefine labelwidth for lists; otherwise, the enumerate package will
% cause markers to extend beyond the left margin.
\makeatletter\AtBeginDocument{%
\renewcommand{\@listi}
{
\setlength{\labelwidth}{4em}
\leftmargin=25pt
\rightmargin=0pt
\labelsep=7pt
\labelwidth=20pt
\itemindent=0pt
\listparindent=0pt
\topsep=2pt plus 2pt minus 2pt
\partopsep=0pt plus 1pt minus 10pt
\parsep=1pt plus 1pt
\itemsep=\parsep
}
}\makeatother
\usepackage{enumerate}
$endif$
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}
\setlength{\emergencystretch}{3em} % prevent overfull lines
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Chapters & Section
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%Use by with \autoref
\AtBeginDocument{%
\renewcommand{\chapterautorefname}{Chapter\negthinspace}
\renewcommand{\sectionautorefname}{\S\negthinspace}
\renewcommand{\subsectionautorefname}{\S\negthinspace}
\renewcommand{\subsubsectionautorefname}{\S\negthinspace}
\renewcommand{\figureautorefname}{Fig.\negthinspace}
\renewcommand{\subfigureautorefname}{Fig.\negthinspace}
\renewcommand{\tableautorefname}{Tab.\negthinspace}
}
% chapters
\usepackage{titlesec}
\titleformat{\chapter}[block]
{\normalfont\HUGE\bfseries}{\LARGE\thechapter.}{1ex}{}
\titlespacing*{\chapter}{0pt}{-19pt}{0pt}
% Sections
$if(numbersections)$
$else$
\newpage
\setcounter{secnumdepth}{0}
$endif$
\usepackage{titlesec}
\newcommand{\sectionbreak}{\clearpage}
\let\oldthesection=\thesection
%% Paragraph (adding new line)
\titleformat{\paragraph}[hang]{\normalfont\normalsize\bfseries}{\theparagraph}{1em}{}
\titlespacing*{\paragraph}{0pt}{3.25ex plus 1ex minus .2ex}{0.5em}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Footer & Header
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
$if(verbatim-in-note)$
% allows verbatim text in footnotes
$endif$
$if(weburl)$
\newcommand{\weburl}{\url{$weburl$}}
$else$
\newcommand{\weburl}{\url{www.sevensols.com}}
$endif$
\usepackage{fancyhdr}
\fancyhf{}
%% Header
\fancyhead[L]{\raisebox{0pt}{\includegraphics[height=7mm]{logo.png}}}
\fancyhead[R]{\small \nouppercase{\leftmark}}
\renewcommand{\headrulewidth}{1pt}
%% Footer
\renewcommand{\footrulewidth}{1pt}
\fancyfoot[L]{{\scriptsize \bfseries $title$ - $title-prefix$} \\ \raisebox{5pt}{\tiny $date$}}
\fancyfoot[C]{\raisebox{0pt}{\small \weburl }}
\fancyfoot[R]{\raisebox{0pt}{\scriptsize \thepage}}
\usepackage{etoolbox}
\makeatletter
%\patchcmd{\@fancyhead}{\rlap}{\color{sevensolsblue}\rlap}{}{} %%text
%\patchcmd{\@fancyfoot}{\rlap}{\color{sevensolsblue}\rlap}{}{} %%text
\patchcmd{\headrule}{\hrule}{\color{sevensolsblue}\hrule}{}{} %%line
\patchcmd{\footrule}{\hrule}{\color{sevensolsblue}\hrule}{}{} %%line
\makeatother
\pagestyle{fancy} % Sets fancy header and footer
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Bibliography
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
$if(natbib)$
\usepackage{natbib}
\bibliographystyle{plainnat}
$endif$
$if(biblatex)$
\usepackage{biblatex}
$if(biblio-files)$
\bibliography{$biblio-files$}
$endif$
$endif$
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Title page (like texinfo)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\DeclareFixedFont{\bigsf}{T1}{phv}{b}{n}{1.5cm}
$if(title)$
\title{$if(title-prefix)$\huge{$title-prefix$}\\\vspace{5mm}$endif${\bigsf $title$}}
$endif$
$if(author)$
\author{$for(author)$$author$$sep$, $endfor$}
$endif$
$if(date)$
$if(version)$
\date{v$version$: $date$}
$else$
\date{$date$}
$endif$
$endif$
\makeatletter
\def\thickhrulefill{\leavevmode \leaders \hrule height 1pt\hfill \kern \z@}
\renewcommand{\maketitle}{\begin{titlepage}%
$if(imgcover)$
\ThisLRCornerWallPaper{1}{$imgcover$}
$endif$
\vspace{5mm}
\begin{minipage}{\textwidth}
\vspace{4.5cm}
\begin{flushright}
\fontsize{10pt}{8pt}\selectfont
{\@date}
\end{flushright}
\end{minipage}
\begin{minipage}{\textwidth}
\vspace{5.8cm}
\noindent
\begin{center}
\textsc{\textbf{\@title}}
\end{center}
\vspace{7cm}
\begin{flushleft}
{\Large \textbf{\@author}}\\
\vspace{2cm}
{\large \OldTexttt{Seven Solutions S.L}}\\
{\url{www.sevensols.com}}
\end{flushleft}
\end{minipage}
\end{titlepage}%
\setcounter{footnote}{0}%
}
\makeatother
%======================================================================%
%======================================================================%
\begin{document}
\renewcommand{\familydefault}{\sfdefault}
$if(title)$
\maketitle
$endif$
$for(include-before)$
$include-before$
$endfor$
$if(toc)$
\setcounter{tocdepth}{2}
\tableofcontents
\clearpage
$endif$
$body$
$if(natbib)$
$if(biblio-files)$
$if(biblio-title)$
$if(book-class)$
\renewcommand\bibname{$biblio-title$}
$else$
\renewcommand\refname{$biblio-title$}
$endif$
$endif$
\bibliography{$biblio-files$}
$endif$
$endif$
$if(biblatex)$
\printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$
$endif$
$for(include-after)$
$include-after$
$endfor$
\end{document}
\ No newline at end of file
doc/wr-starting-kit.md
View file @ 4364d91e
% WR SPEC Starting Kit
% WR SPEC Starting Kit
% Benoit RAT, Javier Diaz (Seven Solutions) & Miguel Jimenez (UGR)
......@@ -15,7 +15,7 @@ written permission by Seven Solutions.
~~~~~~~
The "WR SPEC Starting Kit" (as defined above) is provided under the terms of GPL v2.0
Copyright (C) 2013 - Seven Solutions
Copyright (C) 2019 - Seven Solutions
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
......@@ -65,7 +65,11 @@ conditions
[Seven Solutions]
2.0 15/05/2014 Benoit Rat\ Updating for v2.0 release
[Seven Solutions]
3.0 10/10/2019 Francesco Colella\ Updating for 3.0 reléase
[Seven Solutions]
------------------------------------------------------------------------
You can also check the [Changelog section](#changelog) for more information.
......@@ -102,7 +106,7 @@ and how to integrate it on your own project.
You can find more information on other components and use cases on:
* Our webpage <http://www.sevensols.com/whiterabbitsolution/>
* Our webpage <http://www.sevensols.com/>
* The official wiki page <http://www.ohwr.org/projects/white-rabbit/wiki>
......@@ -112,7 +116,7 @@ About the Starting Kit
This starting kit uses two nodes, each one composed of a [SPEC] and one
[FMC-DIO] card.
A node makes basic operations such as input timestamping or programmable output pulse generation.
A node makes basic operations such as input time-stamping or programmable output pulse generation.
Additionally, specific software and gateware layers allow to use it as a standard network
interface card implementing the White Rabbit technology functionalities.
Network packages with accurate time-stamping information are generated/timestamped at
......@@ -120,13 +124,14 @@ the hardware level to achieve the highest accuracy.
It is based on different projects:
* [spec-sw]: driver to communicate to the [SPEC] card through PCIe. It
* [spec-sw], driver to communicate to the [SPEC] card through PCIe. It
also includes a set of tools to experiments.
* [wr-nic]: gateware that includes the NIC & DIO capabilities.
* [wrpc-sw]: white rabbit PTP firmware for the synchronization.
* [wr-nic], gateware/software that includes the NIC capabilities.
* [fmc-dio-5chttla], gateware/software that includes the support for FMC-DIO 5ch TTL
* [wrpc-sw], white rabbit PTP firmware for the synchronization.
About this document:
About this document
--------------------
This document is intended to be a step by step user friendly tutorial
......@@ -134,11 +139,7 @@ to start with the White Rabbit technology. It includes the description
of some simple experiments to illustrate [WR] capabilities. Some
concepts are deliberately avoided to ease the comprehension of this document.
If you want to know more about these concepts, please access to the
related documents in the [Reference section](#references)
and especially to the following ones:
* [spec-sw.pdf]
* [wrpc.pdf]
related documents in the [Reference section](#references).
The rest of the document provides an explanation about the system setup, software driver, FPGA configuration and
some application examples.
......@@ -153,19 +154,42 @@ the different source projects and how to compile them.
Changelog
-----------------
-----------
In this section, we resume the main changes that happens at each release of the starting-kit
### wr-starting-kit-v3.0
This new release has been focused to update all different modules used by the starting kit but does not provide
specific update for the starting kit.
* Update spec-sw with new VIC core to support kernels (v4.15-v4.18)
* Use new wr-core v4.2 with their update tools (see changelog of wrc-v4.2)
* Separate NIC, FMC-DIO, SPEC-SW into different modules
* Update submodules to work with new ohwr gitlab URL
* Remove etherbone support to avoid conflict in epfilters
A detailed changelog can be found on the wiki page of each submodules:
* [wr-nic-v2.0.1-1](https://www.ohwr.org/project/wr-nic/tags)
* [fmc-bus-v2017-06](https://www.ohwr.org/project/fmc-bus/tags)
* [spec-sw-v2017-10-19](http://www.ohwr.org/projects/spec-sw/tags)
* [coht-vic-v1.2.2-3](https://www.ohwr.org/project/coht-vic/tags)
* [fmc-dio-5chttla-v3.0](https://www.ohwr.org/project/fmc-dio-5chttla/tags)
* [wrpc-v4.2](https://www.ohwr.org/project/wr-cores/wikis/Documents/WR-PTP-Core-v4.2-Files)
* [ppsi-v2016.12-91](https://www.ohwr.org/project/ppsi/tags)
### wr-starting-kit-v2.0
* The driver now support kernel from 2.8.x to 3.5.x
* A valid EEPROM data is now **mandatory** in order to start the kernel
* The gateware is now accesible remotely/standalone through ethernet using etherbone core.
* First DIO channel output is now reserved for outputing PPS
* The gateware is now accessible remotely/standalone through ethernet using etherbone core.
* First DIO channel output is now reserved for outputting PPS
* PPSi has been introduced to improve compatibility with other PTP devices.
* GrandMaster locking has been improved
* FMC bus has been updated to the stable version which is officialy included in linux kernel (>3.5)
* FMC bus has been updated to the stable version which is officially included in linux kernel (>3.5)
* Calibration has been improved using t42p procedure
......@@ -192,23 +216,17 @@ What do you need?
In order to use the white rabbit starting kit and setup the different
experiments you will need:
* An oscillocope with at least 150Mhz bandwitdh (500Mhz is recommanded).
* A PC with at least two `PCIe x4` ports (`x8` & `x16` are also compatible)
* The Operative System **Ubuntu LTS 32bit (Long Term Support)** installed.
* An oscilloscope with at least 150Mhz bandwidth (500Mhz is recommended).
* Two PCs with at least two `PCIe x4` ports (`x8` & `x16` are also compatible)
* The Operative System **Ubuntu LTS 64bit (Long Term Support)** installed.
* Two mini-USB (B) cables (not provided with the kit).
This tutorial has been tested and verified with Ubuntu LTS 12.04 and Ubuntu LTS 14.04,
this mean that standard support will only be given for these releases.
However, the `spec-sw` driver should work with other releases, distributions and architectures
that run kernel `2.8.x` to `3.13.x`.
Finally, [Seven Solutions] also provides a fully setup PC or USB-live images to skip
the instalation process and ease the introduction to the *"White Rabbit World"*.
> ***Note:*** This tutorial follow a configuration with two [SPEC+FMCDIO] boards connected in the two **PCIe x16** interfaces of the same computer. However, you can also use two different computers (if you do not have two **PCIe x4**) and follow this tutorial; you just need to replace all the commands with `wr1` or `0x0300` by the `wr0` and its corresponding bus_id on the second PC. The configuration with two separated PCs is more *"natural"* to understand how to communicate two different nodes using the starting kit,
but it requires more physical space to implement it.
However, the `spec-sw` driver should work with other releases, distributions and architectu
that run kernel `2.8.x` to `3.5.x`.
![Configuration with one or two PCs](img/ssk_configs.png)
![Configuration with one two PCs](img/ssk_configs.png)
Starting kit components
-----------------
......@@ -225,7 +243,6 @@ in the package[^standardssk] :
* 1x LC-LC cable (2m)
* 3x LEMO cable (2m)
* 3x LEMO-BNC Adaptor
* 1x Pre-installed live-USB (Ubuntu 14.04)
![The components of the starting kit](img/ssk_components.jpg)
......@@ -241,51 +258,28 @@ Physical setup
(A Virtual UART is also available, but it is safer to use the physical
one).
* Connect the two [SPEC+FMCDIO] boards using the SFPs and the optical fiber cable (LC-LC)
* In the demo we have put the violet SFP on the top SPEC board (wr0)
* ... and the blue SFP below (wr1)
* In the demo we have put the violet SFP on the PC01 SPEC board (wri1)
* ... and the blue SFP on the PC02 (wri1)
* Start Ubuntu LTS.
* Prepare an oscilloscope with at least two input channels to access
the [FMCDIO] outputs.
![Mounting two SPECs in the same PC](img/ssk_inside.jpg)
![Mounting two SPECs in two PC](img/ssk_inside.jpg)
![Connecting SFPs and fiber](img/ssk_sfp.jpg)
![The UART use a mini-USB cable to communicate](img/ssk_usb.jpg)
Pre-Installed Live-USB
========================
In our latest WR package we also provide a Live-USB (Ubuntu 14.04) pendrive with
the drivers & tools pre-installed.
In order to run the Live-USB from the pendrive you need to modify the
BIOS of your PC to enable booting from USB.
In the most recent BIOS you will find a `Boot options menu` by pressing
tipically `F10`, `F11` or `F12` during the startup of the PC.
Otherwise you might need to modify the Boot priority in the BIOS Configuration. To do so restart your computer, and watch for a message telling you which key to press to enter the BIOS setup. It will usually be one of F1, F2, DEL, ESC or F10. Press this key while your computer is booting to edit your BIOS settings. Once you are in the BIOS configuration, look for something similar as `Boot` > `Boot Order`. You should see an entry for `removable drive` or `USB media`. Move this to the top of the list to make the computer attempt to boot from the USB device before booting from the hard disk. If you still having trouble do perform this step please search on the web how to `Boot from USB` using your BIOS manufacturer as keyword in the research.
Once Ubuntu has started you should select your own language, and click
the `Try Ubuntu Live` options, then you can go directly to the
[Setting Master & Slave using White Rabbit Core Section](#setting-master-slave-using-white-rabbit-core)
If you prefer to use the WR Starting Kit with your own PC you need to
follow the installation steps in the [next section](#installation).
Installation
=======================
> Notes: If you are running the Live-USB pendrive you should skip this
section.
Once you have your system running with the boards plugged, you need to:
* Check that the boards has been detected
* Install the tools to build drivers, etc...
* The drivers : `spec-sw`
* The HDL bitstream of [SPEC+FMCDIO]: `wr-nic`
SPEC detection
......@@ -300,13 +294,12 @@ First you should check that the boards has been correctly detected on your PCIe
You should obtain something similar as:
~~~~~{.sh}
05:00.0 Non-VGA unclassified device: CERN/ECP/EDU Device 018d (rev 03)
0b:00.0 Non-VGA unclassified device: CERN/ECP/EDU Device 018d (rev 03)
01:00.0 Non-VGA unclassified device: CERN/ECP/EDU Device 018d (rev 03)
~~~~~~~~~~
Where `05` and `0b` represent the ID of the PCIe slot given by your motherboard.
Where `01` represent the ID of the PCIe slot given by your motherboard.
> **Note**: The PCIe slot numbering are normally ordered from top to bottom on the motherboard,
this mean that the board with ID `05` will be above the one with index `0b`.
this mean that the board with ID `01` will be above.
Tools
......@@ -319,12 +312,13 @@ Then you need to install all the tools that you will need:
* **linux-source**: Might be useful to compile drivers & kernel modules
* **minicom**: Hyperterminal for linux
* **texinfo, texlive, emacs**: Tools to build documentation
* **lib**: libreadline-dev
You can also run this command[^debian] for minimal setup:
~~~~{.sh}
sudo apt-get install git build-essential linux-headers-$(uname -r) minicom
sudo apt-get install git build-essential libreadline-dev linux-headers-$(uname -r) minicom
~~~~~~~~~
and this one if you also want to generate documentation (not mandatory):
......@@ -337,7 +331,7 @@ sudo apt-get install texinfo emacs texlive pandoc
[^debian]: This sample command is for debian's like distributions.
However similar packages exist for other distributions.
Install the project
Compile & Install the project
-------------------
The first step is to install the driver to communicate with the card using
......@@ -350,25 +344,23 @@ includes the [spec-sw] project.
>:$ cd ~/wr/
## Clone the repository
>:$ git clone git://ohwr.org/white-rabbit/wr-starting-kit.git
>:$ git clone https://ohwr.org/project/wr-starting-kit.git
>:$ cd wr-starting-kit
## Checkout the stable release
>:$ git checkout -b wr-starting-kit-v2.0 wr-starting-kit-v2.0
>:$ git checkout -b wr-starting-kit-v3.0 wr-starting-kit-v3.0
~~~~~~~~~~~~
Then you can get the project submodule by running
Configure your Git username/email
~~~~{.sh}
## Obtain the spec-sw project using submodules
>:$ git submodule init
>:$ git submodule update
## Update submodule of spec-sw
>:$ cd spec-sw
>:$ git submodule init
>:$ git submodule update
>:$ cd -
To set your global username/email configuration:
Open the command line.
Set your username:
git config --global user.name "FIRST_NAME LAST_NAME"
Set your email address:
git config --global user.email "MY_NAME@example.com"
~~~~~~~~~~~~
Or you can try our new Makefile that should perform everything!
......@@ -382,132 +374,6 @@ Or you can try our new Makefile that should perform everything!
The **master** branch might have the latest source but support is only offered for tagged release. The other branches are normally used for development and are not stable.
Structure of the spec-sw project
---------------------------------
Most of the information on how the project is structured can be found in the [spec-sw.pdf] in the `/doc` folder,
however in the following paragraphs we briefly summarize it:
### Folders layout
Each of the following folders contain:
* **doc**: documentation of the project
* **gateware**: downloaded HDL binaries also called gateware.\
(This folder is created while downloading gateware)
* **kernel**: Kernel modules (drivers) to connect the [SPEC] to the PC through PCIe.
* **tools**: Set of tools used for the experiments in the Starting Kit
### Structure of the driver and HDL
The Starting Kit contains 3 different drivers:
* **fmc.ko**: Define a generic FMC-bus[^fmc-bus] used to identify and connect to FMC boards independently
of the carrier being used (e.g. [SPEC], SVEC, ...)
* **spec.ko**: It is the device driver that connects to the [SPEC] through PCI. It also loads the spec-init.bin “golden” gateware file.
* **wr-nic.ko**: The wr-nic driver is basically an Ethernet driver with
support for hardware time stamping. It also loads the following:
* `fmc/wr_nic_dio.bin` gateware for the NIC and DIO properties.
* `fmc/wr_nic_dio-wrc.bin` software for the LM32[^lm32inc].
[^fmc-bus]: More information about the [FMC]-bus can be found within [fmc-bus.pdf] in the `doc/` folder.
[^lm32inc]: In future version, the program file for the LM32 will be included into the gateware.
Compile & install
------------------------
A Makefile in the [spec-sw] project has been written to compile and install easily the drivers and the tools used below.
~~~~{.sh}
## Go to spec-sw project
>:$ cd spec-sw
## In the root folder (spec-sw), run
>:$ make
## then, install the driver in your system so that they load automatically
>:$ sudo make install
~~~~~~~~~~~
If everything works well you should see the driver in
~~~~{.sh}
>:$ ls -l /lib/modules/$(uname -r)/extra
~~~~~~~~~~~
> ***Notes:*** The procedure below is specific to ubuntu distribution so you
might want to find a similar way to perform it if you use another
distribution.
You should add the `extra` folder to the search of module so that at
next reboot the kenel modules are easily founded.
~~~~{.sh}
## Open the configuration file
>:$ sudo nano /etc/depmod.d/ubuntu.conf
~~~~~~~~~~~
Check if you already have the extra folder or otherwise add the `extra` keyword
before built-in.
The first line of this file should now be similar as:
search updates ubuntu extra built-in
Finally, you must regenerate the map of dependencies with this new path
by calling:
~~~~{.sh}
>:$ sudo depmod -a
~~~~~~~~~~~
Download, install & load the gateware
--------------------------------------
You need to install the gateware[^version] to `/lib/firmware/fmc`
### Automatic procedure
You can also use the script `wr-ssk-get` in `wr-starting-kit/scripts` folder
to ease the installation. `sudo` is required
~~~~{.sh}
## Fetch and install the firmware
>:$ sudo scripts/wr-ssk-get --all
~~~~~~~~~~~~~~
### Manual procedure
First you need to download the gateware/firmware files from our website:
<http://www.sevensols.com/dl/wr-starting-kit/bin/latest_stable.tar.gz>
~~~~{.sh}
## Create the gateware folder
>:$ mkdir firmware
## Extract to the gateware folder
>:$ tar -xzf wr-starting-kit-v2.0_gw.tar.gz -C ./firmware
~~~~~~~~~~~
Once you have the file you need to install them to your system in order to make them load automatically
~~~~{.sh}
## Install the HDL binaries in /lib/firmware/fmc (require sudo)
>:$ sudo cp -v firmware/*.bin /lib/firmware/fmc
~~~~~~~~~~~~~
[^version]: The HDL binaries (gateware) came from other project, you can find in
the [Developers Section](#quick-start-guide-for-developers) where to obtain them and
how to compile them.
Loading the driver
------------------------
......@@ -515,7 +381,9 @@ To enable the wr-nic you should execute the modprobe[^errmodprobe] command to lo
~~~~{.sh}
>:$ sudo modprobe spec
>:$ sudo modprobe htvic
>:$ sudo modprobe wr-nic
>:$ sudo modprobe wr-dio
~~~~~~~~
[^errmodprobe]: We have found a problem in some distribution with `modprobe` command.
......@@ -526,7 +394,7 @@ You should expect to obtain two (or one) new interface(s):
~~~~{.sh}
>:$ ifconfig -a | grep wr
wr0 Link encap:Ethernet HWaddr XX:XX:XX:XX:XX:XX
wri1 Link encap:Ethernet HWaddr XX:XX:XX:XX:XX:XX
~~~~~~~~~~~~
If it is not the case you might have an empty EEPROM that need to be
......@@ -555,40 +423,15 @@ you might obtain the following warning on `dmesg`:
~~~~~{.sh}
>:$ dmesg
...
spec 0000:05:00.0: FPGA programming successful
spec 0000:05:00.0: mezzanine 0
EEPROM has no FRU information
11.949966] spec 0000:01:00.0: mezzanine 0
[ 11.949967] Manufacturer: CERN
[ 11.949967] Product name: FmcDio5cha
...
~~~~~~~~~~
This information, called the FRU, contains the type of FMC board, its serial number, etc.
You can generate in two different way:
### Automatic
A small script has been created for this procedure and thus you just need to call it as below:
scripts/wr-ssk-get -w
Then the script will detect if you have one or more [FMC-DIO] with empty
eeprom. If it is the case it will ask to enter a S/N.
> ***Tip***: The S/N is labeled on the back side of the
[FMC-DIO] board and the index of PCIe slots on the bus "normally" respect
the physical plug order from top to bottom on the motherboard.
If for instance you have one with the label `7S-FMCDIO5ch-v1.0-S3-058` and
you can't read the label on the second one, we suggest you to fill the input as below:
Found 2 FMC board(s) with empty EEPROM
Enter S/N for board fmc-0500 in the format xx-XXX (or 0) : 03-058
...
Enter S/N for board fmc-0b00 in the format xx-XXX (or 0) : 0
### Manual
If you prefer to perform these steps manually you can try the
following procedure:
In order to write it in case you have an old FMC board without any EEPROM written,
you should execute the following commands
~~~~~{.sh}
##First you need to go in the fru-generator folder
......@@ -599,29 +442,29 @@ following procedure:
## Then, find out on which bus id you have the boards
>:$ ls /sys/bus/fmc/devices/
fmc-0500 fmc-0b00
FmcDio5cha-0100
### Enter root mode in the terminal
>:$ sudo bash
## Write the eeprom for fmc-0500: the first/the top one fmc board.
## Write the eeprom for fmc-0100: the first/the top one fmc board.
>:# FRU_VENDOR="CERN" FRU_NAME="FmcDio5cha" FRU_PART="EDA-02408-V2-0" \
./fru-generator -s 7S-DIO-v2-S03-058 > /sys/bus/fmc/devices/fmc-0500/eeprom
## Write the eeprom for fmc-0b00: the 2nd/the bottom one fmc board.
>:# FRU_VENDOR="CERN" FRU_NAME="FmcDio5cha" FRU_PART="EDA-02408-V2-0" \
./fru-generator -s 7S-DIO-v2-S00-000 > /sys/bus/fmc/devices/fmc-0b00/eeprom
./fru-generator -s 7S-DIO-v2-S03-058 > /sys/bus/fmc/devices/FmcDio5cha-0100/eeprom
## Finally, Go back to user and starting-kit root directory
>:# exit
>:$ cd -
~~~~~~~~~~
Don't forget to modify the bus id: `fmc-XXXX` and the S/N
Don't forget to modify the bus id: `FmcDio5cha-XXXX` and the S/N
`7S-DIO-v2-Sxx-XXX` with your specific devices setup.
### Reload the kernel driver
> ***Notes:*** Removing the kernel is actually proving a kernel panic (core-dump) and
your PC will be freezed. This is a known bug that you be corrected in a release fix.
Once you have correctly written (Auto or Manual) the EEPROM of the [FMC-DIO], you need
to reload the kernel driver by doing this
......@@ -634,13 +477,9 @@ you should now obtain something like this on `dmesg`:
~~~~~{.sh}
...
[269290.520027] spec 0000:05:00.0: mezzanine 0
[269290.520035] Manufacturer: CERN
[269290.520038] Product name: FmcDio5cha
...
[269291.086221] spec 0000:0b:00.0: mezzanine 0
[269291.086228] Manufacturer: CERN
[269291.086230] Product name: FmcDio5cha
[ 10.901519] spec 0000:01:00.0: mezzanine 0
[ 10.901521] Manufacturer: CERN
[ 10.901521] Product name: FmcDio5cha
...
~~~~~~~~
......@@ -679,7 +518,7 @@ This depends on how you have plugged the USB cable to your USB of your machine.
### Virtual UART
An easier way to perform this operation is to access to the virtual
UART of the [SPEC] board by using the spec-vuart tool.
UART of the [SPEC] board by using the wrpc-vuart tool.
You first need to know the `bus_id` of your board
> ***Notes:*** The VUART can not work if the USB is already connected as the Physical UART
......@@ -687,26 +526,24 @@ has the priority.
~~~~~{.sh}
>:$ lspci | grep CERN
05:00.0 Non-VGA unclassified device: CERN/ECP/EDU Device 018d (rev 03)
0b:00.0 Non-VGA unclassified device: CERN/ECP/EDU Device 018d (rev 03)
01:00.0 Non-VGA unclassified device: CERN/ECP/EDU Device 018d (rev 03)
~~~~~~~~~~
This means that your first board (wr0) is at **05**:00.0 and the second one (wr1) is at **0b**:00.0
This means that your first board (wri1) is at **01**:00.0
Thus, for each board you can open a terminal and run the following command:
~~~~~{.sh}
>:$ sudo ./tools/spec-vuart -b 0x05 #For the first SPEC board