Skip to content

S
Software for White Rabbit PTP Core
Commit 4ea462ec authored by Dimitris Lampridis's avatar Dimitris Lampridis Committed by Grzegorz Daniluk
Browse files
Options

doc: updated HDL documentation for upcoming WRPC v4.0 release

parent 5865f4c6
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1891 additions and 641 deletions
doc/HDLdoc/Makefile
View file @ 4ea462ec
all : wrpc_hdl.pdf
FILE=wrpc_hdl
all : $(FILE).pdf
.PHONY : all clean
wrpc_hdl.pdf : wrpc_hdl.tex
pdflatex $^
pdflatex $^
$(FILE).pdf : $(FILE).tex *.tex references.bib
pdflatex $(FILE)
pdflatex $(FILE)
bibtex $(FILE)
pdflatex $(FILE)
pdflatex $(FILE)
clean :
rm -f *.eps *.pdf *.dat *.log *.out *.aux *.dvi *.ps *.nav *.snm *.toc
rm -f *.eps *.pdf *.dat *.log *.out *.aux *.dvi *.ps *.nav *.snm *.toc *.blg *.bbl
doc/HDLdoc/app.tex deleted 100644 → 0
View file @ 5865f4c6
\appendix
\section{Appendices}
\subsection{Simple top design with WRPC}
\label{app:top_design}
\begin{center}
\includegraphics[width=.9\textheight, angle=90]{fig/basic_top.pdf}
\end{center}
%\newpage
%\subsection{WR Fabric testbench example}
%\label{app:fabric_tb}
%
%\begin{lstlisting}
%/* A small testbench demonstrating how to send Ethernet packets
% * over WRPC's Fabric interface.*/
%
%`include "if_wb_master.svh"
%`include "if_wb_slave.svh"
%`include "wb_packet_sink.svh"
%`include "wb_packet_source.svh"
%
%`timescale 1ns/1ns
%
%module main;
%
% reg clk = 0;
% reg rst = 0;
%
% /* Clock / reset generation */
% initial #100 rst = 1;
% always #10 clk <= ~clk;
%
% /* Packet Sink Wishbone interface (slave) - inputs packets,
% * simulating a MAC TX input.*/
% IWishboneSlave
% #(
% .g_data_width(16),
% .g_addr_width(2))
% U_WB_Slave
% (
% .clk_i(clk),
% .rst_n_i(rst)
% );
%
% /* Packet Sink Wishbone interface (slave) - inputs packets,
% * simulating a MAC TX input.*/
% IWishboneMaster
% #(
% .g_data_width(16),
% .g_addr_width(2))
% U_WB_Master
% (
% .clk_i(clk),
% .rst_n_i(rst)
% );
%
% assign U_WB_Slave.adr = U_WB_Master.adr;
% assign U_WB_Slave.dat_i = U_WB_Master.dat_o;
% assign U_WB_Slave.cyc = U_WB_Master.cyc;
% assign U_WB_Slave.stb = U_WB_Master.stb;
% assign U_WB_Slave.sel = U_WB_Master.sel;
% assign U_WB_Slave.we = U_WB_Master.we;
%
% assign U_WB_Master.ack = U_WB_Slave.ack;
% assign U_WB_Master.stall = U_WB_Slave.stall;
% assign U_WB_Master.rty = U_WB_Slave.rty;
% assign U_WB_Master.err = U_WB_Slave.err;
%
% /* Packet Transmission process */
% initial begin
%
% /* Create a Packet Source object: WBPacketSource class
% * takes Ethernet packets and converts them to
% * Wishbone transactions .*/
% WBPacketSource src = new(U_WB_Master.get_accessor());
% EthPacket pkt, template = new;
% EthPacketGenerator gen = new;
%
% int i;
%
% /* Force the WB Master to make some mess on the bus by
% * throttling transfer rate (random empty slots).*/
% U_WB_Master.settings.gen_random_throttling = 1;
% U_WB_Master.settings.throttle_prob = 0.05;
%
% /* Size range: 64 to 128 bytes */
% gen.set_size(64, 128);
%
% /* Payload = sequence of increasing bytes */
% gen.set_randomization(EthPacketGenerator::SEQ_PAYLOAD);
%
% template.src = '{ 'hca, 'hfe, 'hba, 'hbe, 'h00, 'h01 };
% template.dst = '{ 'hff, 'hff, 'hff, 'hff, 'hff, 'hff };
% template.ethertype = 'h1234;
%
% /* Set template header for all generated packets
% * (i.e. MAC, Ethertype). */
% gen.set_template(template);
%
% /* Wait until reset goes low */
% #200;
%
% for (i = 0; i < 10; i++) begin
% pkt = gen.gen();
% $display("Send %d\n", i);
% src.send(pkt);
% end
% end
%
% initial begin
% /* Create a Packet Sink object: WBPacketSink class
% * decodes Wishbone transactions into Ethernet packets.*/
% WBPacketSink snk = new (U_WB_Slave.get_accessor());
% EthPacket pkt;
%
% int i;
%
% /* Make the WB Slave sometimes stall the Wishbone link,
% * to demonstrate various conditions on the bus.*/
% U_WB_Slave.settings.gen_random_stalls = 1;
% U_WB_Slave.settings.stall_prob = 0.05;
% U_WB_Slave.settings.stall_min_duration = 1;
% U_WB_Slave.settings.stall_max_duration = 5;
%
% /* Wait until reset goes low */
% #200;
%
% /* Print all received packets */
% forever begin
% snk.recv(pkt);
% pkt.dump();
% end
% end
%
%endmodule // main
%\end{lstlisting}
doc/HDLdoc/clk_rst_adv.tex → doc/HDLdoc/aux_clocks.tex
View file @ 4ea462ec
......@@ -12,22 +12,5 @@ is done with a similar PLL that is used to discipline the local reference clock
(section \ref{basic:clk_rst}). WRPC provides tuning values for the VCXO producing
clock signal which is connected to \emph{clk\_aux\_i}.
\begin{center}
\begin{tabular}{|l|l|p{9cm}|}
\hline
\multicolumn{3}{|l|}{\bf Signals description:}\\
{\bf name} & {\bf size} & {\bf description} \\
\hline \hline
\texttt{clk\_aux\_i} & g\_aux\_clks & [optional] vector of auxiliary
clocks that will be disciplined to WR timebase\\
\hline
\texttt{tm\_dac\_value\_o} & 24 & DAC value for tuning auxiliary clock
(\emph{clk\_aux\_i})\\
\texttt{tm\_dac\_wr\_o} & 1 & validates auxiliary DAC value\\
\texttt{tm\_clk\_aux\_lock\_en\_i} & 1 & enable locking auxiliary clock to
internal WR clock\\
\texttt{tm\_clk\_aux\_locked\_o} & 1 & auxiliary clock locked to internal WR
clock\\
\hline
\end{tabular}
\end{center}
\begin{hdlporttable}
\end{hdlporttable}
doc/HDLdoc/clk_rst.tex deleted 100644 → 0
View file @ 5865f4c6
\subsection{Clocks and reset}
\label{basic:clk_rst}
\begin{figure}[ht]
\begin{center}
\includegraphics[width=.8\textwidth]{fig/basic_wrpc_clk.pdf}
\caption{Mandatory clock signals and main reset of WRPC}
\end{center}
\end{figure}
\begin{center}
\begin{tabular}{|l|l|p{9cm}|}
\hline
%\multicolumn{3}{|l|}{\bf Signals description:}\\
{\bf Signal name} & {\bf size} & {\bf description} \\
\hline \hline
\texttt{clk\_sys\_i} & 1 & main system clock, can be any frequency $\leq
f_{clk\_ref\_i}$ e.g. 62.5 MHz\\
\texttt{clk\_dmtd\_i} & 1 & DMTD offset clock (close to 62.5 MHz, e.g. 62.49 MHz)\\
\texttt{clk\_ref\_i} & 1 & 125 MHz reference clock\\
\hline
\texttt{dac\_hpll\_load\_p1\_o} & 1 & validates DAC value on data port \\
\texttt{dac\_hpll\_data\_o} & 16 & DAC value for tuning helper (DMTD) VCXO\\
\texttt{dac\_dpll\_load\_p1\_o} & 1 & validates DAC value on data port \\
\texttt{dac\_dpll\_data\_o} & 16 & DAC value for tuning main (ref) VCXO\\
\hline
\texttt{clk\_ext\_i} & 1 & [optional] external 10 MHz reference clock
input for GrandMaster mode\\
\texttt{rst\_n\_i} & 1 & main reset input, active-low (hold for at least 5
\emph{clk\_sys} cycles)\\
\hline
\end{tabular}
\end{center}
doc/HDLdoc/fabric.tex
View file @ 4ea462ec
\newpage
\subsection{Fabric interface}
\label{sec:wrpc_fabric}
\begin{figure}[ht]
\begin{center}
\includegraphics[width=\textwidth]{fig/wrpc_fabric.pdf}
\caption{WR Fabric interface}
\end{center}
\end{figure}
%\begin{figure}[ht]
% \begin{center}
% \includegraphics[width=\textwidth]{fig/wrpc_fabric.pdf}
% \caption{WR Fabric interface}
% \end{center}
%\end{figure}
The Fabric interface is used for sending and receiving Ethernet frames. It consists
of two pipelined Wishbone interfaces operating independently:
\begin{itemize}
\item \emph{WRF Source}: pipelined Wishbone Master, passes all the Ethernet frames
received from a physical link to WRF Sink interface implemented in a
......@@ -18,32 +19,9 @@ of two pipelined Wishbone interfaces operating independently:
the WRF Source implemented in the user-defined module, and sends them to a
physical link.
\end{itemize}
Each of the Pipelined Wishbone buses being part of WR Fabric interface consist
of the following signals:
\begin{center}
\begin{tabular}{|l|l|l|p{10cm}|}
\hline
{\bf Signal name} & {\bf size} & {\bf direction} & {\bf description} \\
\hline
\hline \texttt{adr} & 2 & Source $\rightarrow$ Sink & defines what kind of data is actually available on data bus\\
\hline \texttt{dat} & 16 & Source $\rightarrow$ Sink & data bus \\
\hline \texttt{sel} & 2 & Source $\rightarrow$ Sink & byte/word select (single
byte can be transmitted only as the last data word of the frame)\\
\hline \texttt{cyc} & 1 & Source $\rightarrow$ Sink & indicates a valid bus cycle\\
\hline \texttt{stb} & 1 & Source $\rightarrow$ Sink & indicates a valid data
transfer cycle\\
\hline \texttt{we} & 1 & Source $\rightarrow$ Sink & write enable (always high)\\
\hline \texttt{ack} & 1 & Sink $\rightarrow$ Source & data acknowledge\\
\hline \texttt{err} & 1 & Sink $\rightarrow$ Source & Sink error indicator\\
\hline \texttt{stall} & 1 & Sink $\rightarrow$ Source & used by Sink for flow control\\
\hline
\end{tabular}
\end{center}
For a more precise description of the Pipelined Wishbone signals please check the
Wishbone B4 Specification \cite{wb_spec}.\\
{\bf Address bus} can have one of the following values:
\begin{center}
\begin{tabular}{|c|l|}
\hline {\bf decimal value} & {\bf meaning of data word on data bus}\\
......@@ -51,24 +29,80 @@ Wishbone B4 Specification \cite{wb_spec}.\\
\emph{0} & regular data (packet header and payload)\\
\emph{1} & OOB (Out-of-band) data\\
\emph{2} & status word\\
\emph{3} & currently not used\\
\hline
\end{tabular}
\end{center}
{\bf Status word} (sent when the value of the address bus is \emph{2}) contains
the information about Ethernet frame's structure and type:
\begin{figure}[ht]
{\bf Status word} (sent when the value of address bus is \emph{2}) contains
various information about Ethernet frame's structure and type:
%\begin{figure}[ht]
\begin{center}
\includegraphics[width=.6\textwidth]{fig/basic_wrf_status.pdf}
\caption{Simplified status word format}
\includegraphics[width=.6\textwidth]{fig/status.pdf}
%\caption{Status word format}
\end{center}
\end{figure}
%\end{figure}
\begin{itemize}
\item[] \emph{isHP} - if \emph{1}, the frame is high priority
\item[] \emph{err} - if \emph{1}, the frame contains an error
\item[] \emph{vSMAC} - the frame contains a source MAC address (otherwise
it will be assigned from WRPC configuration)
\item[] \emph{vCRC} - the frame contains a valid CRC checksum
\item[] \emph{packet class} - the packet class assigned by the classifier
inside WRPC MAC module
\end{itemize}
OOB data is used for passing the timestamp-related information for the incoming and
outgoing Ethernet frames. Each frame received from a physical link is
timestamped inside the WRPC and this value is passed as Rx OOB
data. On the other hand, for each transmitted frame the Tx timestamp can be read
from the Tx Timestamping Interface (section \ref{sec:txts}) together with a unique
frame number assigned in Tx OOB. Therefore, the format of OOB differs between Rx
and Tx frames.\\
{\bf Tx OOB format}:
%\begin{figure}[ht]
\begin{center}
\includegraphics[width=.7\textwidth]{fig/oob_tx.pdf}
%\caption{Tx OOB data format}
%\label{fig:fabric_adv:tx_oob}
\end{center}
%\end{figure}
\begin{itemize}
\item[] \emph{OOB type}: "0001" means Tx OOB
\item[] \emph{frame ID}: ID of the frame being sent. It is later output
through the \emph{Tx Timestamping interface} to associate Tx timestamp with
appropriate frame. Frame ID = 0 is reserved for PTP packets inside WRPC
and cannot be used by user-defined modules.
\end{itemize}
{\bf Rx OOB format}:
%\begin{figure}[ht]
\begin{center}
\includegraphics[width=.7\textwidth]{fig/oob_rx.pdf}
%\caption{Rx OOB data format}
%\label{fig:fabric_adv:rx_oob}
\end{center}
%\end{figure}
\begin{itemize}
\item[] \emph{err} - if \emph{1}, the frame contains an error. It may occur when
the size of Ethernet frame is too small or it contains invalid CRC checksum.
\item[] \emph{OOB type}: "0000" means Rx OOB
\item[] \emph{Tiv}: timestamp invalid. When this bit is set to '1', the PPS
generator inside WRPC is being adjusted which means the Rx timestamp is not
reliable.
\item[] \emph{port ID}: the ID of a physical port on which the packet was
received. In case of WRPC, this field is always 0, because there is only one
physical port available.
\item[] \emph{CNTR\_f}: least significant bits of the Rx timestamp generated on
the falling edge of the reference clock.
\item[] \emph{CNTR\_r}: Rx timestamp generated on the rising edge of the reference
clock.
\end{itemize}
\begin{figure}[hbt]
\begin{figure}
\begin{center}
\includegraphics[width=.6\textwidth]{fig/basic_wrf_data.pdf}
\caption{Data words that make the Ethernet frame}
......@@ -88,7 +122,7 @@ Figure \ref{fig:fabric:simple_tx} shows a very simple WR Fabric cycle. The WRF
Source of user-defined module sends there an Ethernet frame containing even
number of bytes.
\begin{figure}[ht]
\begin{figure}
\begin{center}
\includegraphics[width=\textwidth]{fig/basic_wrf_cycle_simple.pdf}
\caption{Simple WR Fabric cycle - user-defined module sending packet}
......@@ -112,7 +146,7 @@ user-defined WRF Source sends an Ethernet frame to the WRPC. This time though,
the frame contains odd number of bytes, therefore the \emph{sel} line is used to
signal this fact to WRF Sink inside the WRPC (1).
\begin{figure}[ht]
\begin{figure}
\begin{center}
\includegraphics[width=\textwidth]{fig/basic_wrf_cycle_sel.pdf}
\caption{Simple WR Fabric cycle - user-defined module sending packet(odd
......@@ -124,7 +158,8 @@ signal this fact to WRF Sink inside the WRPC (1).
Figure \ref{fig:fabric:cyc} presents more complicated Fabric cycle where an
Ethernet frame is received from WRF Source in the WRPC (output signals in the
diagram are driven by WRF Source on the WRPC side):
\begin{figure}[ht]
\begin{figure}
\begin{center}
\includegraphics[width=\textwidth]{fig/basic_wrf_cycle.pdf}
\caption{WR Fabric cycle}
......@@ -157,13 +192,15 @@ process the flow of data coming from WRF Source. However, if some more serious
problem appears on the receiving side, the \emph{err} line can be used to
immediately break the cycle. This situation is presented in figure
\ref{fig:fabric:cycerr}:
\begin{figure}[ht]
\begin{figure}
\begin{center}
\includegraphics[width=\textwidth]{fig/basic_wrf_cycle_err.pdf}
\caption{WR Fabric cycle interrupted with an error line}
\label{fig:fabric:cycerr}
\end{center}
\end{figure}
\begin{enumerate}
\item WRF Sink wants to break a bus cycle, so it drives \emph{err\_i} high.
\item WRF Source breaks the cycle immediately after receiving an error indicator
......@@ -183,3 +220,4 @@ WRF Sink) can be found in the \emph{wr-cores} git repository
The testbench example using the simulation model of WR Fabric interface can
be found in the zip archive attached to this documentation.
doc/HDLdoc/fabric_adv.tex deleted 100644 → 0
View file @ 5865f4c6
\subsection{Fabric interface}
Address bus can have one of the following values:
\begin{center}
\begin{tabular}{|c|l|}
\hline {\bf decimal value} & {\bf meaning of data word on data bus}\\
\hline
\emph{0} & regular data (packet header and payload)\\
\emph{1} & OOB (Out-of-band) data\\
\emph{2} & status word\\
\emph{3} & currently not used\\
\hline
\end{tabular}
\end{center}
{\bf Status word} (sent when the value of address bus is \emph{2}) contains
various information about Ethernet frame's structure and type:
\begin{figure}[ht]
\begin{center}
\includegraphics[width=.6\textwidth]{fig/status.pdf}
\caption{Status word format}
\end{center}
\end{figure}
\begin{itemize}
\item[] \emph{isHP} - if \emph{1}, the frame is high priority
\item[] \emph{err} - if \emph{1}, the frame contains an error
\item[] \emph{vSMAC} - the frame contains a source MAC address (otherwise
it will be assigned from WRPC configuration)
\item[] \emph{vCRC} - the frame contains a valid CRC checksum
\item[] \emph{packet class} - the packet class assigned by the classifier
inside WRPC MAC module
\end{itemize}
OOB data is used for passing the timestamp-related information for the incoming and
outgoing Ethernet frames. Each frame received from a physical link is
timestamped inside the WRPC and this value is passed as Rx OOB
data. On the other hand, for each transmitted frame the Tx timestamp can be read
from the Tx Timestamping Interface (section \ref{sec:txts}) together with a unique
frame number assigned in Tx OOB. Therefore, the format of OOB differs between Rx
and Tx frames.\\
{\bf Tx OOB format} (figure \ref{fig:fabric_adv:tx_oob}):
\begin{figure}[ht]
\begin{center}
\includegraphics[width=.7\textwidth]{fig/oob_tx.pdf}
\caption{Tx OOB data format}
\label{fig:fabric_adv:tx_oob}
\end{center}
\end{figure}
\begin{itemize}
\item[] \emph{OOB type}: "0001" means Tx OOB
\item[] \emph{frame ID}: ID of the frame being sent. It is later output
through the \emph{Tx Timestamping interface} to associate Tx timestamp with
appropriate frame. Frame ID = 0 is reserved for PTP packets inside WRPC
and cannot be used by user-defined modules.
\end{itemize}
{\bf Rx OOB format} (figure \ref{fig:fabric_adv:rx_oob}):
\begin{figure}[ht]
\begin{center}
\includegraphics[width=.7\textwidth]{fig/oob_rx.pdf}
\caption{Rx OOB data format}
\label{fig:fabric_adv:rx_oob}
\end{center}
\end{figure}
\begin{itemize}
\item[] \emph{OOB type}: "0000" means Rx OOB
\item[] \emph{Tiv}: timestamp invalid. When this bit is set to '1', the PPS
generator inside WRPC is being adjusted which means the Rx timestamp is not
reliable.
\item[] \emph{port ID}: the ID of a physical port on which the packet was
received. In case of WRPC, this field is always 0, because there is only one
physical port available.
\item[] \emph{CNTR\_f}: least significant bits of the Rx timestamp generated on
the falling edge of the reference clock.
\item[] \emph{CNTR\_r}: Rx timestamp generated on the rising edge of the reference
clock.
\end{itemize}
doc/HDLdoc/fig/wrpc_board.svg 0 → 100644
View file @ 4ea462ec
This diff is collapsed.
doc/HDLdoc/generics.tex deleted 100644 → 0
View file @ 5865f4c6
\subsection{Generic parameters}
\label{sec:generics}
\begin{center}
\begin{tabular}{|p{4cm}|p{2cm}|p{1.5cm}|p{6.5cm}|}
\hline {\bf name} & {\bf type} & {\bf default value} & {\bf description} \\
\hline
\hline
\texttt{g\_simulation} & integer & \texttt{0} & setting to '1' speeds up the simulation,
must be set to '0' for synthesis\\
\hline
\texttt{g\_with\_external\_ \linebreak clock\_input} & boolean & \texttt{false} &
enable external clock and 1-PPS inputs. The PLL inside WRPC will lock to
external 10 MHz and 1-PPS signal when operating in GrandMaster mode\\
\hline
\end{tabular}
\end{center}
doc/HDLdoc/generics_adv.tex deleted 100644 → 0
View file @ 5865f4c6
\subsection{Generic parameters}
\label{sec:adv:generics}
\begin{center}
\begin{tabular}{|p{3.7cm}|p{3.3cm}|p{2.2cm}|p{5cm}|}
\hline {\bf name} & {\bf type} & {\bf default value} & {\bf description} \\
\hline
\hline
\texttt{g\_phys\_uart} & boolean & \texttt{true} & enable physical UART interface\\
\hline
\texttt{g\_virtual\_uart} & boolean & \texttt{false} & enable virtual UART interface\\
\hline
\texttt{g\_aux\_clks} & integer & \texttt{1} & number of aux clocks syntonized by WRPC to WR
timebase\\
\hline
\texttt{g\_rx\_buffer\_size} & integer & \texttt{1024} & size of Rx buffer in WRPC MAC module,
default value is 1024 and should not be changed\\
\hline
\texttt{g\_dpram\_initf} & string & \texttt{""} & filename of compiled WRPC software, to be
stored in WRPC memory during the synthesis (default is \emph{wrc.ram}
created by compiling WRPC software from \emph{wrpc-sw} git repository)\\
\hline
\texttt{g\_dpram\_initv} & t\_xwb\_dpram\_init &
\texttt{c\_xwb\_ \linebreak dpram\_init \linebreak \_nothing} & VHDL array to initialize WRPC
internal memory\\
\hline
\texttt{g\_dpram\_size} & integer & \texttt{22528} & size of RAM used by WRPC software (in 32-bit
words), default value is 22528 and should not be changed\\
\hline
\texttt{g\_interface\_ \linebreak mode} & t\_wishbone\_ \linebreak interface\_mode &
\texttt{PIPELINED} & external Wishbone Slave interface mode
[PIPELINED/CLASSIC]\\
\hline
\texttt{g\_address\_ \linebreak granularity} & t\_wishbone\_ \linebreak
address\_granularity & \texttt{WORD} & granularity of address bus in
external Wishbone Slave interface [BYTE/WORD]\\
\hline
\texttt{g\_aux\_sdb} & t\_sdb\_device & \texttt{c\_wrc\_ \linebreak
periph3\_ \linebreak sdb} & structure providing SDB Wishbone description of
WRPC, when connected to SDB Wishbone Crossbar, this parameter is optional
and can be unassigned\\
\hline
\end{tabular}
\end{center}
doc/HDLdoc/intro.tex
View file @ 4ea462ec
\section{Introduction}
The White Rabbit PTP Core is an Ethernet MAC implementation capable of providing
precise timing. It can be used for sending and receiving regular Ethernet
frames between user-defined HDL modules and a physical medium. It also
implements the White Rabbit protocol to provide sub-nanosecond time
synchronization.
This section describes the various options available to the users for instantiating and
parametrising the WRPC in their designs.
The White Rabbit PTP Core can operate in one of the following modes:
\begin{itemize}
\item GrandMaster: WR Master synchronized to an external 1-PPS and 10 MHz clock
signal, propagates precise timing to other WR-compliant devices
\item Master: WR Master with free-running oscillator, propagates precise
timing to other WR-compliant devices
\item Slave: synchronizes its internal oscillator to another WR Master device
\end{itemize}
By default it starts as \emph{Slave} but its mode can be changed in anytime
using the \emph{mode} command of WRPC Shell (please check the \emph{White
Rabbit PTP Core User's Manual - Building and Running} \cite{wrpc_man} for full
description of the WRPC Shell).\\
\begin{figure}
\begin{center}
\includegraphics[width=.6\textwidth]{fig/wrpc_board.pdf}
\label{fig:wrpc_board}
\caption{WRPC HDL abstraction hierarchy}
\end{center}
\end{figure}
The WRPC provides several levels of abstractions and VHDL modules, depending on the target
system. These are presented in Figure~\ref{fig:wrpc_board}. At the highest level of abstraction, the
WRPC provides Board Support Packages (BSPs), available for all officially supported boards. All BSP
modules share a common part (the ``board-common'' module) which encapsulates the WRPC core itself,
together with a selection of interfaces for connecting the core the the user FPGA
logic. Furthermore, each BSP also makes use of a Platform Support Package (PSP), which groups
together and instantiates all the FPGA-specific parts (typically hard IP provided by the FPGA
vendor), such as PHY, PLLs and clock buffers.
This documentation describes the input and output ports of the WRPC IP-core and
VHDL generic parameters that can be used to personalize the core. The manual is
divided into two parts:
\begin{itemize}
\item {\bf Part I: Standard configuration}: describes only generics and ports
that have to be connected to use WRPC as the precise time source and be able
to send and receive Ethernet frames through it.
\item {\bf Part II: Advanced options}: all the generics and input/output ports
that are beyond WRPC's basic usage. They can be used by people with expert
knowledge of the White Rabbit and {\bf on their own responsibility} (the WRPC
instantiated with those parameters modified won't be supported).
\end{itemize}
Thus, depending on the users' systems and needs, several scenarios might be available for
instantiating the WRPC into their designs.
Figure \ref{intro:fig:wrpc_top} is an example on how to instantiate the WRPC
component inside the VHDL project. It contains few additional modules besides
the WRPC:
\begin{itemize}
\item \emph{wr\_gtp\_phy\_spartan6}: module wrapping Xilinx GTP SerDes to
improve its determinism
\item \emph{PLL\_BASE}: Xilinx Spartan6 PLL primitive \cite{pll_base}, used to
produce 62.5 MHz system clock from 125 MHz local reference clock and to
produce the DMTD offset clock from a local 20 MHz oscillator
\item \emph{spec\_serial\_dac\_arb}: converts DACs tuning values to serial
interface and arbitrates access to two DACs used for reference and DMTD
clock tuning.
\end{itemize}
\begin{description}
\item[Option 1: Supported board.] In this simplest of scenarios, it will be enough to just
instantiate the provided BSP into the users' designs and configure it via the provided generics.
\item[Option 2: Supported FPGA platform.] The users could draw inspiration from an existing BSP
based on the same platform, reusing the board-common module and PSP, while adapting the parts
that are unique to their designs.
\item[Option 3: Unsupported FPGA platform.] There is significant work involved in this
scenario. In addition to providing the details for their board (just like for option 2), users
also have to write their own PSP. It should be possible though to reuse the board-common
module. Furthermore, if the unsupported platform is related to a supported one, it could be that
the PHY and/or PLLs will also be reused, perhaps with minor adjustments.
\end{description}
%Very similar example can be found in the WRPC
%reference design for PCI-Express SPEC board:
%\emph{top/spec\_1\_1/wr\_core\_demo/spec\_top.vhd} inside \emph{wr-cores} git
%repository.
When writing a new BSP or PSP, it's worth discussing it first in the
\href{http://www.ohwr.org/mailing_list/show?project_id=white-rabbit}{white-rabbit-dev} mailing
list. Perhaps there is already some preliminary support underway. It's also worth considering
sharing your work so that it can be merged with the project and added to the list of supported
platforms/boards.
\begin{figure}[hbp]
\begin{center}
\includegraphics[width=.9\textheight, angle=270]{fig/basic_top.pdf}
\label{intro:fig:wrpc_top}
\caption{Simple top design with WRPC}
\end{center}
\end{figure}
The rest of this section describes the various modules in more detail. The WRPC module is presented
in Section~\ref{sec:hdl_wrpc}. The platform support modules are presented in
Section~\ref{sec:hdl_platform}, while the board support modules are presented in
Section~\ref{sec:hdl_board}.
doc/HDLdoc/periph.tex
View file @ 4ea462ec
\newpage
\subsection{GPIO/UART/I2C/1-Wire interfaces}
\label{sec:wrpc_periph}
\begin{figure}[ht]
\begin{center}
\includegraphics[width=.9\textwidth]{fig/basic_wrpc_gpio.pdf}
\caption{Other interfaces of WRPC}
\end{center}
\end{figure}
%\begin{figure}[ht]
% \begin{center}
% \includegraphics[width=.9\textwidth]{fig/basic_wrpc_gpio.pdf}
% \caption{Other interfaces of WRPC}
% \end{center}
%\end{figure}
Other hardware peripherals can be connected to the White Rabbit PTP
Core. It has a UART, 1-Wire and two $I^2C$ interfaces implemented
inside. The $I^2C$ connection to the SFP module
is used to read its Part ID, while the external EEPROM stores calibration
values for each supported SFP together with an initialization script. That script
is executed every time the WRPC is powered on and can contain instructions to
automatically match the SFP's Part ID with the EEPROM content and load appropriate
calibration values. The SFP presence indicator is mandatory and has to be connected.
Otherwise, the WRPC won't be able to operate properly (without knowing whether
the SFP transceiver is actually inserted).
Several hardware peripherals can be connected to the White Rabbit PTP Core. It has a UART, 1-Wire
and two $I^2C$ interfaces implemented inside. The $I^2C$ connection to the SFP module is used to
read its Part ID, while the external EEPROM stores calibration values for each supported SFP
together with an initialization script. That script is executed every time the WRPC is powered on
and can contain instructions to automatically match the SFP's Part ID with the EEPROM content and
load appropriate calibration values. The SFP presence indicator is mandatory and has to be
connected. Otherwise, the WRPC won't be able to operate properly (without knowing whether the SFP
transceiver is actually inserted).
Furthermore, a 1-Wire digital thermometer provides
on-board temperature, but also its unique ID is used to calculate default MAC
address of the physical Ethernet interface. The UART interface provides a user shell
that can be used to interact with the White Rabbit PTP Core. More detailed
description of the WRPC shell can be found in the \emph{White Rabbit PTP Core User's
Manual - Building and Running} \cite{wrpc_man}.
\begin{center}
\begin{tabular}{|p{3cm}|l|p{11cm}|}
\hline
{\bf Signal name} & {\bf size} & {\bf description} \\
\hline \hline
\texttt{pps\_ext\_i} & 1 & [optional] external 1-PPS input used in
GrandMaster mode\\
\hline
\texttt{scl\_i} \linebreak \texttt{scl\_o} \linebreak \texttt{sda\_i} \linebreak
\texttt{sda\_o} & 4 & I2C interface for EEPROM memory storing calibration
parameters and WRPC init script\\
\hline
\texttt{sfp\_scl\_i} \linebreak \texttt{sfp\_scl\_o} \linebreak
\texttt{sfp\_sda\_i} \linebreak \texttt{sfp\_sda\_o} & 4 & I2C interface for
EEPROM inside SFP module\\
\hline
\texttt{sfp\_det\_i} & 1 & SFP presence indicator\\
\hline
\texttt{uart\_rxd\_i} \linebreak \texttt{uart\_txd\_o} & 2 & [optional] serial
UART interface for interaction with WRPC software\\
\hline
\texttt{owr\_pwren\_o} \linebreak \texttt{owr\_en\_o} \linebreak \texttt{owr\_i} &
3 & [optional] 1-Wire interface used to read the temperature of hardware board from
digital thermometer (e.g. Dallas DS18B20)\\
\hline
\texttt{pps\_led\_o} & 1 & 1-PPS signal with extended pulse width to drive a
LED\\
\hline
\texttt{btn1\_i} \linebreak \texttt{btn2\_i} & 2 & two microswitch inputs,
active low, currently not used in official WRPC software\\
\hline
\texttt{led\_link\_o} & 1 & signal for driving Ethernet Link LED\\
\hline
\texttt{led\_act\_o} & 1 & signal for driving Ethernet Act LED\\
\hline
\end{tabular}
\end{center}
Furthermore, a 1-Wire digital thermometer provides on-board temperature, but also its unique ID is
used to calculate default MAC address of the physical Ethernet interface. The UART interface
provides a user shell that can be used to interact with the White Rabbit PTP Core. More detailed
description of the WRPC shell can be found in the \emph{White Rabbit PTP Core User's Manual -
Building and Running} \cite{wrpc_man}.
doc/HDLdoc/phyif.tex
View file @ 4ea462ec
\subsection{PHY interface}
\begin{figure}[ht]
\begin{center}
\includegraphics[width=.7\textwidth]{fig/wrpc_phyif.pdf}
\caption{PHY interface of WRPC}
\end{center}
\end{figure}
%\begin{figure}[ht]
% \begin{center}
% \includegraphics[width=.7\textwidth]{fig/wrpc_phyif.pdf}
% \caption{PHY interface of WRPC}
% \end{center}
%\end{figure}
The interface connects WRPC with the Ethernet PHY layer IP-core. The interface is
generic, but currently two Gigabit Ethernet PHYs are tested and supported: Xilinx
8-bit GTP and 16-bit GTX SerDes. The signals' naming convention is the same as
in the GTP/GTX component definition.\\
The interface connects WRPC with the Ethernet PHY layer IP-core. The interface is generic, but
currently three Gigabit Ethernet PHYs are tested and supported:
{\bf Important !} If a WRPC user wants to use one of the supported PHYs (GTP,
GTX), they have to be taken from the White Rabbit HDL package instead of generating
them with the Xilinx Coregen tool. That is because WR developers have attached
additional logic to Xilinx GTP/GTX to improve its determinism.\\
\begin{enumerate}
\item Xilinx Spartan6 8-bit GTP SerDes
\item Xilinx Virtex6 16-bit GTX SerDes
\item Altera ``Deterministic Latency'' Transceiver PHY (tested on Arria V)
\end{enumerate}
Depending on the value of the \tts{g\_records\_for\_phy} and \tts{g\_pcs\_16bit} generic parameters,
WRPC expects to find the PHY signals in one of the following ports:
\begin{center}
\begin{tabular}{|c|c|l|}
\hline {\bf \tts{g\_records\_for\_phy}} & {\bf \tts{g\_pcs\_16bit}} & {\bf PHY ports}\\
\hline
\tts{false} & \tts{false} & \multirow{2}{*}{individual standard logic ports}\\
\tts{false} & \tts{true} & \\
\tts{true} & \tts{false} & \tts{phy8} record-based ports\\
\tts{true} & \tts{true} & \tts{phy16} record-based ports\\
\hline
\end{tabular}
\end{center}
\begin{center}
\fcolorbox{red}{white}{
\parbox{.99\textwidth}{\textcolor{red}{\textbf{Important:}} If a WRPC user wants to use one of
the supported PHYs, they have to be taken from the WRPC repository instead of manually
generating them with the Xilinx/Altera tools. That is because WR developers have attached
additional logic to them to improve their determinism. The easiest way of doing so is to make
use of the provided Platform/Board Support Packages (see Sections~\ref{sec:hdl_platform}
and~\ref{sec:hdl_board}).}}
\end{center}
doc/HDLdoc/timecode.tex
View file @ 4ea462ec
\subsection{Timecode interface}
\label{sec:wrpc_timecode}
\begin{figure}[ht]
\begin{center}
\includegraphics[width=.5\textwidth]{fig/basic_wrpc_tm.pdf}
\caption{Timecode output interface of WRPC}
\end{center}
\end{figure}
%\begin{figure}[ht]
% \begin{center}
% \includegraphics[width=.5\textwidth]{fig/basic_wrpc_tm.pdf}
% \caption{Timecode output interface of WRPC}
% \end{center}
%\end{figure}
Timecode interface provides current time to the other HDL modules in a form that
can be easily used. It consists of: a 1-PPS and a UTC timecode
aligned to the time of WR Master.
\begin{center}
\begin{tabular}{|l|l|p{10cm}|}
\hline
{\bf Signal name} & {\bf size} & {\bf description} \\
\hline \hline
\texttt{tm\_link\_up\_o} & 1 & state of Ethernet link (up/down), \emph{1}
means Ethernet link is up\\
\texttt{tm\_time\_valid\_o} & 1 & if \emph{1}, the timecode generated by the
WRPC is valid\\
\texttt{tm\_tai\_o} & 40 & TAI part of the timecode (full seconds)\\
\texttt{tm\_cycles\_o} & 28 & fractional part of each second represented by
the state of counter clocked with the frequency 125 MHz (values from 0 to
124999999, each count is 8 ns)\\
\texttt{pps\_p\_o} & 1 & 1-PPS signal generated in \emph{clk\_ref\_i} clock
domain and aligned to WR time, pulse
generated when the cycle counter is 0 (beginning of each full TAI second)\\
\hline
\end{tabular}
\end{center}
doc/HDLdoc/txts.tex
View file @ 4ea462ec
\subsection{Tx Timestamping interface}
\label{sec:txts}
\begin{figure}[ht]
\begin{center}
\includegraphics[width=.4\textwidth]{fig/wrpc_txts.pdf}
\caption{Tx timestamping interface of WRPC}
\end{center}
\end{figure}
%\begin{figure}[ht]
% \begin{center}
% \includegraphics[width=.4\textwidth]{fig/wrpc_txts.pdf}
% \caption{Tx timestamping interface of WRPC}
% \end{center}
%\end{figure}
The Tx Timestamping interface provides the timestamps generated inside WRPC for each
Ethernet frame transmitted from user-defined module through the WRF Sink interface.\\
\begin{center}
\begin{tabular}{|l|l|p{9cm}|}
\hline
{\bf Signal name} & {\bf size} & {\bf description} \\
\hline \hline
\texttt{txtsu\_port\_id\_o} & 5 & physical port ID from which the timestamp
was originated. WRPC has only one physical port, so this value is always
\emph{0}.\\
\texttt{txtsu\_frame\_id\_o} & 16 & frame ID for which the timestamp is
available\\
\texttt{txtsu\_ts\_value\_o} & 32 & Tx timestamp value\\
\texttt{txtsu\_ts\_incorrect\_o} & 1 & Tx timestamp is not reliable since it
was generated while PPS generator inside WRPC was being adjusted\\
\texttt{txtsu\_stb\_o} & 1 & strobe signal that validates the rest of signals
described above\\
\texttt{txtsu\_ack\_i} & 1 & acknowledge, indicating that user-defined module
has received the timestamp\\
\hline
\end{tabular}
\end{center}
doc/HDLdoc/wb.tex
View file @ 4ea462ec
\subsection{External Wishbone Slave/Master interface}
\label{sec:wrpc_wb}
\begin{figure}[ht]
\begin{center}
\includegraphics[width=.7\textwidth]{fig/wrpc_wb.pdf}
\caption{External Wishbone interfaces of WRPC}
\end{center}
\end{figure}
%\begin{figure}[ht]
% \begin{center}
% \includegraphics[width=.7\textwidth]{fig/wrpc_wb.pdf}
% \caption{External Wishbone interfaces of WRPC}
% \end{center}
%\end{figure}
{\bf Aux WB Master} is a Pipelined Wishbone Master interface. It is connected
through the Wishbone Crossbar inside the White Rabbit PTP Core to the LM32 soft-core
processor (instantiated inside the WRPC). It can optionally be used to control
any user-defined module having a Pipelined Wishbone Slave interface. In that case, the WRPC software
has to be modified to control additional modules connected to the \emph{Aux WB
Master} interface.\\
{\bf Ext WB Slave} is a Wishbone slave interface (see the Wishbone bus specification~\cite{wb_spec}
for more details). It controls the primary Wishbone Crossbar insisde the WRPC and thus provides
access to all the WRPC internals.
{\bf Ext WB Slave} is a Wishbone Slave interface that operates in Pipelined or
Classic mode (selected with \emph{g\_interface\_mode} generic), with the address bus
granularity set with \linebreak \emph{g\_address\_granularity} generic. It gives the access
to control all the WRPC internals. In the WRPC reference design it is connected to
the Gennum GN4124 IP-core and used to upload WRPC software to its internal memory.\\
In most designs, this slave interface should be connected to the host (if any), via an aprropriate
bridge. As an example, in the SPEC WRPC reference design it is connected to a Gennum GN4124 IP core,
and in the SVEC/VFC-HD reference designs it is connected to the VME64x IP core. In all three
reference designs, this interface is used to upload WRPC software to its internal memory and to
access the WRPC VUART.
HDL modules accessible through \emph{Ext WB Slave} interface:
HDL modules accessible through \emph{Ext WB Slave} interface include:
\begin{center}
\begin{tabular}{|l|l|}
\hline {\bf module name} & {\bf offset (bytes)}\\
......@@ -37,3 +35,11 @@ HDL modules accessible through \emph{Ext WB Slave} interface:
\hline
\end{tabular}
\end{center}
{\bf Aux WB Master} is a Pipelined Wishbone Master interface. It is connected through the Wishbone
Crossbar inside the White Rabbit PTP Core to the LM32 soft-core processor (instantiated inside the
WRPC). It can optionally be used to control any user-defined module having a Pipelined Wishbone
Slave interface. In that case, the WRPC software has to be modified to control additional modules
connected to the \emph{Aux WB Master} interface. An alternative is to access the Aux WB master
interface from the host (via the external Wishbone slave interface).
doc/HDLdoc/wrc_board.tex 0 → 100644
View file @ 4ea462ec
This diff is collapsed.
doc/HDLdoc/wrc_core.tex 0 → 100644
View file @ 4ea462ec
\section{WR Core}
\label{sec:hdl_wrpc}
This section describes the input and output ports of the WRPC IP-core and VHDL generic parameters
that can be used to personalize the core.
The top-level VHDL module is located under:\\\hrefwrpc{modules/wrc\_core/wr\_core.vhd}
A wrapper for the top-level VHDL module which makes use of VHDL records to reduce the number of
ports can be found under:\\\hrefwrpc{modules/wrc\_core/xwr\_core.vhd}
\begin{figure}
\begin{center}
\includegraphics[width=.9\textheight, angle=270]{fig/basic_top.pdf}
\label{intro:fig:wrpc_top}
\caption{Simple top design with WRPC}
\end{center}
\end{figure}
Figure \ref{intro:fig:wrpc_top} is an example on how to instantiate the WRPC component inside a
Xilinx Spartan6-based project. It contains few additional modules besides the WRPC:
\begin{itemize}
\item \emph{wr\_gtp\_phy\_spartan6}: module wrapping Xilinx GTP SerDes to improve its determinism
\item \emph{PLL\_BASE}: Xilinx Spartan6 PLL primitive \cite{pll_base}, used to produce 62.5 MHz
system clock from 125 MHz local reference clock and to produce the DMTD offset clock from a
local 20 MHz oscillator
\item \emph{spec\_serial\_dac\_arb}: converts DACs tuning values to serial interface and
arbitrates access to two DACs used for reference and DMTD clock tuning.
\end{itemize}
A very similar example can be found in the WRPC reference design for PCI-Express SPEC board (see
Section~\ref{sec:hdl_board_spec}).
\input{wrc_generics.tex}
\input{wrc_ports.tex}
\input{phyif.tex}
\input{periph.tex}
\input{wb.tex}
\input{fabric.tex}
\input{txts.tex}
\input{timecode.tex}
doc/HDLdoc/wrc_generics.tex 0 → 100644
View file @ 4ea462ec
\subsection{Generic parameters}
\label{sec:wrc_generics}
\begin{hdlparamtable}
g\_simulation & integer & 0 & setting to '1' speeds up the simulation,
must be set to '0' for synthesis\\
\hline
g\_with\_external\_clock\_input & boolean & false &
enable external clock and 1-PPS inputs. The PLL inside WRPC will lock to
external 10 MHz and 1-PPS signal when operating in GrandMaster mode\\
g\_phys\_uart & boolean & true & enable physical UART interface\\
\hline
g\_virtual\_uart & boolean & false & enable virtual UART interface\\
\hline
g\_aux\_clks & integer & 0 & number of aux clocks syntonized by WRPC to WR timebase\\
\hline
g\_rx\_buffer\_size & integer & 1024 & size of Rx buffer in WRPC MAC module,
default value is 1024 and should not be changed\\
\hline
g\_tx\_runt\_padding & boolean & true & \\
\hline
g\_dpram\_initf & string & "" & filename of compiled WRPC software, to be
stored in WRPC memory during the synthesis (default is \emph{wrc.ram}
created by compiling WRPC software from \emph{wrpc-sw} git repository)\\
\hline
g\_dpram\_size & integer & 32768 & size of RAM used by WRPC software (in 32-bit
words), default value is 22528 and should not be changed\\
\hline
g\_interface\_mode & enum& PIPELINED & external Wishbone Slave interface mode
\tts{[PIPELINED/CLASSIC]}\\
\hline
g\_address\_granularity & enum & BYTE & granularity of address bus in external
Wishbone Slave interface \tts{[BYTE/WORD]}\\
\hline
g\_aux\_sdb & rec & c\_wrc\_periph3\_sdb & structure providing an SDB descriptor
for the peripheral attached to the WRPC auxiliary WB interface. This parameter is optional
and can be left unassigned. The default value corresponds to an undocumented device with an
address space of 256 bytes\\
\hline
g\_softpll\_enable\_debugger & boolean & false & \\
\hline
g\_vuart\_fifo\_size & integer & 1024 & size (in bytes) for the virtual UART FIFO\\
\hline
g\_pcs\_16bit & boolean & false & when set to \tts{true}, make use of 16-bit PCS, otherwise use 8-bit PCS\\
\hline
g\_records\_for\_phy & boolean & false & when set to \tts{true}, all the PHY-related
signals will be grouped in the \tts{phy8/phy16} VHDL records, otherwise the individual standard
logic signals will be used\\
\hline
g\_diag\_id & integer & 0 & \\
\hline
g\_diag\_ver & integer & 0 & \\
\hline
g\_diag\_ro\_size & integer & 0 & \\
\hline
g\_diag\_rw\_size & integer & 0 & \\
\end{hdlparamtable}
doc/HDLdoc/wrc_platform.tex 0 → 100644
View file @ 4ea462ec
\section{Platform Support Packages}
\label{sec:hdl_platform}
The White Rabbit (WR) PTP core project provides platform support packages (PSPs) for Altera and
Xilinx FPGAs.
By using these modules, users gain the benefit of instantiating all the platform-specific support
components for the WR PTP core (PHY, PLLs, etc.) in one go, without having to delve into the
implementation details, using a setup that has been tested and is known to work well on the
supported FPGAs.
\subsection{Common}
\label{sec:hdl_platform_common}
This section describes the generic parameters and ports which are common to all provided PSPs.
\subsubsection{Generic parameters}
\begin{hdlparamtable}
g\_with\_external\_clock\_input & boolean & false & Select whether to
include the external 10MHz reference clock input (used in WR Grandmaster mode)\\
\hline
g\_use\_default\_plls & boolean & true & Set to FALSE if you want to
instantiate your own PLLs\\
\end{hdlparamtable}
Each PSP provides two generic parameters of boolean type , which allow the users to configure the
PLLs in their designs. As such, four different PLL setups can be achieved by changing the values of
these parameters.
\begin{description}
\item[PLL setup 1:] Use default PLLs, no external reference clock. In this setup, the PSP expects
one 20MHz and one 125MHz clock, and it will instantiate all the required PLLs internally. This is
the default mode.
\item[PLL setup 2:] Use default PLLs, with external reference clock. This is the same as PLL setup
1, with the addition of the external 10MHz reference clock input, which will be multiplied
internally by the PSP to 125MHz.
\item[PLL setup 3:] Use custom PLLs, no external reference clock. In this setup, the PSP will not
instantiate any PLLs internally. It is up to the user to provide the 62.5MHz system clock, the
125MHz reference clock and the 62.5MHz DMTD clock.
\item[PLL setup 4:] Use custom PLLs, with external reference clock. This is the same as PLL setup 3,
with the addition of the external reference clock input, which should be provided as is (10MHz)
and also multiplied to 125MHz.
\end{description}
\subsubsection{Ports}
\begin{hdlporttable}
areset\_n\_i & in & 1 & asynchronous reset (active low)\\
\hline
clk\_10m\_ext\_i & in & 1 & 10MHz external reference clock input
(used when \tts{g\_with\_external\_clock\_input = true})\\
\hline
\hdltablesection{Clock inputs for default PLLs (used when
\tts{g\_use\_default\_plls = true})}\\
\hline
clk\_20m\_vcxo\_i & in & 1 & 20MHz VCXO clock\\
\hline
clk\_125m\_pllref\_i & in & 1 & 125MHz PLL reference\\
\hline
\hdltablesection{Interface with custom PLLs (used when
\tts{g\_use\_default\_plls = false})}\\
\hline
clk\_62m5\_dmtd\_i & in & 1 & \multirowpar{2}{62.5MHz DMTD offset
clock and lock status}\\
\cline{1-3}
clk\_dmtd\_locked\_i & in & 1 & \\
\hline
clk\_62m5\_sys\_i & in & 1 & \multirowpar{2}{62.5MHz Main system
clock and lock status}\\
\cline{1-3}
clk\_sys\_locked\_i & in & 1 & \\
\hline
clk\_125m\_ref\_i & in & 1 & 125MHz Reference clock\\
\hline
clk\_125m\_ext\_i & in & 1 & \multirowpar{4}{125MHz derived
from 10MHz external reference, locked/stopped status inputs and reset output (used when
\tts{g\_with\_external\_clock\_input = true})}\\
\cline{1-3}
clk\_ext\_locked\_i & in & 1 & \\
\cline{1-3}
clk\_ext\_stopped\_i & in & 1 & \\
\cline{1-3}
clk\_ext\_rst\_o & out & 1 &\\
\hline
\hdltablesection{Interface with SFP}\\
\hline
sfp\_tx\_fault\_i & in & 1 & TX fault indicator\\
\hline
sfp\_los\_i & in & 1 & Loss Of Signal indicator\\
\hline
sfp\_tx\_disable\_o & out & 1 & TX disable control\\
\hline
\hdltablesection{Interface with WRPC}\\
\hline
clk\_62m5\_sys\_o & out & 1 & 62.5MHz system clock output\\
\hline
clk\_125m\_ref\_o & out & 1 & 125MHz reference clock output\\
\hline
clk\_62m5\_dmtd\_o & out & 1 & 62.5MHz DMTD clock output\\
\hline
pll\_locked\_o & out & 1 & logic AND of system and DMTD PLL lock\\
\hline
clk\_10m\_ext\_o & out & 1 & 10MHz external reference clock output\\
\hline
phy8\_o & out & rec & \multirowpar{2}{input/output records for PHY signals
when \tts{g\_pcs\_16bit = false}}\\
\cline{1-3}
phy8\_i & in & rec & \\
\hline
phy16\_o & out & rec & \multirowpar{2}{input/output records for PHY signals
when \tts{g\_pcs\_16bit = true}}\\
\cline{1-3}
phy16\_i & in & rec & \\
\hline
ext\_ref\_mul\_o & out & 1 & \multirowpar{4}{125MHz derived from
10MHz external reference, locked/stopped status outputs and reset input}\\
\cline{1-3}
ext\_ref\_mul\_locked\_o & out & 1 & \\
\cline{1-3}
ext\_ref\_mul\_stopped\_o & out & 1 & \\
\cline{1-3}
ext\_ref\_rst\_i & in & 1 & \\
\end{hdlporttable}
\subsection{Altera}
\label{sec:hdl_platform_altera}
The Altera PSP currently supports the Arria V family of FPGAs.
The top-level VHDL module is located under:\\\hrefwrpc{platform/altera/xwrc\_platform\_altera.vhd}
A VHDL package with the definition of the module can be found
under:\\\hrefwrpc{platform/wr\_altera\_pkg.vhd}
An example (VHDL) instantiation of this module can be found in the VFC-HD board support package (see
also Section~\ref{sec:hdl_board_vfchd}):\\\hrefwrpc{board/vfchd/xwrc\_board\_vfchd.vhd}
This section describes the generic parameters and ports which are specific to the Altera
PSP. Parameters and ports common to all PSPs are described in Section~\ref{sec:hdl_platform_common}.
\subsubsection{Generic parameters}
\begin{hdlparamtable}
g\_fpga\_family & string & arria5 & Defines the family/model of Altera
FPGA. Recognized values are "arria5" (more will be added)\\
\hline
g\_pcs16\_bit & boolean & false & Some FPGA families provide the possibility
to configure the PCS of the PHY as either 8bit or 16bit. The default is to use the 8bit PCS,
but this generic can be used to override it\\
\end{hdlparamtable}
\subsubsection{Ports}
\begin{hdlporttable}
\hdltablesection{Interface with SFP}\\
\hline
\linebreak sfp\_tx\_o\linebreak & out & 1 & \multirowpar{2}{PHY TX and RX. These
are single ended and should be mapped to the positive half of each differential signal.
Altera tools will infer both the negative half and the differential receiver}\\
\cline{1-3}
\linebreak sfp\_rx\_i\linebreak & in & 1 &\\
\end{hdlporttable}
\subsection{Xilinx}
\label{sec:hdl_platform_xilinx}
The Xilinx PSP currently supports the Spartan 6 family of FPGAs.
The top-level VHDL module is located under:\\ \hrefwrpc{platform/xilinx/xwrc\_platform\_xilinx.vhd}
A VHDL package with the definition of the module can be found
under:\\ \hrefwrpc{platform/wr\_xilinx\_pkg.vhd}
Examples of (VHDL) instantiation of this module can be found in the SPEC and SVEC board support
packages (see also Sections~\ref{sec:hdl_board_spec}
and~\ref{sec:hdl_board_svec}):\\
\hrefwrpc{board/spec/xwrc\_board\_spec.vhd}\\
\hrefwrpc{board/svec/xwrc\_board\_svec.vhd}
This section describes the generic parameters and ports which are
specific to the Xilinx PSP. Parameters and ports common to all PSPs
are described in Section~\ref{sec:hdl_platform_common}.
\subsubsection{Generic parameters}
\begin{hdlparamtable}
g\_fpga\_family & string & spartan6 & Defines the family/model of Xilinx
FPGA. Recognized values are "spartan6" (more will be added)\\
\hline
g\_simulation & integer & 0 & setting to '1' speeds up the simulation, must
be set to '0' for synthesis\\
\end{hdlparamtable}
\subsubsection{Ports}
\begin{hdlporttable}
clk\_125m\_gtp\_p\_i & in & 1 & \multirowpar{2}{125MHz GTP
reference differential clock input}\\
\cline{1-3}
clk\_125m\_gtp\_n\_i & in & 1 & \\
\hline
\hdltablesection{Interface with SFP}\\
\hline
sfp\_txn\_o & out & 1 & \multirowpar{2}{differential pair for PHY TX}\\
\cline{1-3}
sfp\_txp\_o & out & 1 & \\
\hline
sfp\_rxn\_i & in & 1 & \multirowpar{2}{differential pair for PHY RX}\\
\cline{1-3}
sfp\_rxp\_i & in & 1 & \\
\end{hdlporttable}
doc/HDLdoc/wrc_ports.tex 0 → 100644
View file @ 4ea462ec
This diff is collapsed.
doc/HDLdoc/wrpc_hdl.tex
View file @ 4ea462ec
......@@ -3,36 +3,21 @@
%
% White Rabbit PTP Core HDL.
%
\def\us{\char`\_}
\documentclass[a4paper, 12pt]{article}
%\documentclass{article}
\documentclass[a4paper]{article}
\usepackage{fullpage}
\usepackage{pgf}
\usepackage{tikz}
\usetikzlibrary{arrows,automata,shapes}
\usepackage{graphicx}
\usepackage{multirow}
\usepackage{color}
\usepackage{colortbl}
\usepackage{array}
\usepackage{longtable}
\usepackage[latin1]{inputenc}
\usepackage{verbatim}
\usepackage{amsmath}
\usepackage{times,mathptmx}
\usepackage{chngcntr}
\usepackage{hyperref}
\usepackage[none]{hyphenat}
%\usepackage{draftwatermark}
%%%%%5% used in Tomeks %%%%%%%
\usepackage{listings}
\definecolor{light-gray}{gray}{0.95}
\usepackage{cancel}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% fig/tomeksDrawings
%\usepackage{morefloats}
%\usepackage{amsfonts}
%\usepackage{amssymb}
%\usepackage{graphicx}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% creating subsubsubsection notation
......@@ -50,21 +35,77 @@
{-3.25ex\@plus -1ex \@minus -.2ex}%
{0.0001pt \@plus .2ex}%
{\normalfont\normalsize\bfseries}}
%\renewcommand{\thefootnote}{\fnsymbol{footnote}}
%\renewcommand{\thefootnote}{\alph{footnote}}
\counterwithin{paragraph}{subsubsection}
\counterwithin{subparagraph}{paragraph}
\makeatother
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\eqoffset}[1]{%
{\ensuremath{%
{\text{offset}}_{#1}}%
}%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\definecolor{wrlblue}{RGB}{165,195,210}
\definecolor{wrlgray}{RGB}{209,211,212}
\newcommand{\multirowpar}[2]{
\multirow{#1}{\hsize}{\parbox{\hsize}{\strut\raggedright#2\strut}}
}
\newcommand{\hdltablesection}[1]{
\multicolumn{4}{|c|}{\bf\small#1}
}
\newcolumntype{L}[1]{>{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
\newcolumntype{M}[1]{>{\raggedright\let\newline\\\arraybackslash\hspace{0pt}\ttsmall}m{#1}}
\newcolumntype{C}[1]{>{\centering\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
\newcolumntype{D}[1]{>{\centering\let\newline\\\arraybackslash\hspace{0pt}\ttsmall}m{#1}}
\newenvironment{hdlparamtable}{
\let\underscore\_
\renewcommand{\_}{\underscore\allowbreak}
\setlength{\extrarowheight}{1pt}
\begin{center}
\begin{longtable}{|M{.2\textwidth}|C{.09\textwidth}|D{.11\textwidth}|L{.5\textwidth}|}
\firsthline
\rowcolor{wrlblue}
\bf{name} & \bf{type} & \bf{default} & \bf{description}\\
\hline
\endhead
}{
\lasthline
\end{longtable}
\end{center}
}
\newcommand{\eqdelay}[1]{{\text{delay}}_{#1}}
\newcommand{\eqasymm}{{\text{asymmetry}}}
\newenvironment{hdlporttable}{
\let\underscore\_
\renewcommand{\_}{\underscore\allowbreak}
\setlength{\extrarowheight}{1pt}
\begin{center}
\begin{longtable}{|M{.25\textwidth}|C{.05\textwidth}|D{.05\textwidth}|L{.55\textwidth}|}
\firsthline
\rowcolor{wrlblue}
\bf{name} & \bf{dir} & \bf{size} & \bf{description}\\
\hline
\endhead
}{
\lasthline
\end{longtable}
\end{center}
}
\def \wrpcrelease {for-tests}
%\def \wrpcrelease {wrpc-v4.0}
\newcommand{\tts}[1]{
\texttt{\small{#1}}}
% same as \tts{}, without argument
\newcommand{\ttsmall}{\ttfamily\small}
\newcommand{\hrefwrpc}[1]{
\tts{\href{http://www.ohwr.org/projects/wr-cores/repository/entry/#1?rev=\wrpcrelease}{#1}}}
\begin{document}
......@@ -72,71 +113,23 @@
{version 1.0}\\\small{(01-03-2013)}}
\author{Grzegorz Daniluk\\ CERN BE-CO-HT}
\date{March 2013}
\date{March 2017}
\maketitle
\thispagestyle{empty}
\begin{figure}[ht!]
\centering
\vspace{1.3cm}
%\includegraphics[width=0.50\textwidth]{fig/wr_logo.png}
\label{fig:wr_logo}
\end{figure}
\newpage
%\setcounter{page}{1}
%\begin{center}
%\large Revision History Table
%\end{center}
%
%\begin{table}[ht!]
%%\begin{table}[tbp]
%%\caption{White Rabbit Specification Revision History Table }
%\centering
%\begin{tabular}{| c | c | c | p{8cm} |} \hline
%\textbf{Version} & \textbf{Date} & \textbf{Authors} & \textbf{Description} \\
% & & &\\ \hline
%0.01 & 06/11/2012 & G.D. & First draft for comments. \\ \hline
%\end{tabular}
%\label{tab:revHist}
%\end{table}
\newpage
\newpage
\tableofcontents
\newpage
\input{intro.tex}
\newpage
\section{Standard configuration}
\input{generics.tex}
\input{clk_rst.tex}
\input{phyif.tex}
\input{fabric.tex}
\input{timecode.tex}
\input{periph.tex}
\include{intro}
\include{wrc_core}
\include{wrc_platform}
\include{wrc_board}
\newpage
\appendix
\section{Appendix: Advanced options}
{\color{red} {\bf Information presented in this part should be used only
by users with expert knowledge of the White Rabbit Protocol and on their own
responsibility}}
\input{generics_adv.tex}
\input{clk_rst_adv.tex}
\input{fabric_adv.tex}
\input{wb.tex}
\input{txts.tex}
\newpage
\bibliographystyle{unsrt}
\bibliography{references}
%\newpage
%\input{app.tex}
\end{document}
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