Skip to content

S
Software for White Rabbit PTP Core
Commit f24ed697 authored by Tristan Gingold's avatar Tristan Gingold
Browse files
Options

Update doc

parent cd8978bb
Hide whitespace changes
Inline Side-by-side
Showing with 21 additions and 86 deletions
doc/Makefile
View file @ f24ed697
......@@ -7,7 +7,9 @@ all : wrpc.pdf
.PHONY : all clean
wrpc.pdf : wrpc.tex HDLdoc/*.tex
# Generate version
bash -c "echo '\\newcommand{\\gitrevinfo}{'$(subst _,\\\\_,$(RELEASE))'}' > version.tex"
# Run twice to create TOC.
pdflatex -dPDFSETTINGS=/prepress -dSubsetFonts=true -dEmbedAllFonts=true -dMaxSubsetPct=100 -dCompatibilityLevel=1.4 $^
pdflatex -dPDFSETTINGS=/prepress -dSubsetFonts=true -dEmbedAllFonts=true -dMaxSubsetPct=100 -dCompatibilityLevel=1.4 $^
......
doc/wrpc.tex
View file @ f24ed697
......@@ -159,8 +159,9 @@ distributed in the following places:
\item \url{https://ohwr.org/project/wrpc-sw.git}
Repository with the software running inside the WRPC. As today both, the LM32
and the RISC-V soft-core processors are supported by software.
Repository with the software running inside the WRPC. Starting from
version 5, the soft CPU core is a RISC-V, while previous versions were
using LM32.
\end{itemize*}
Other tools useful for building and running the WRPC can be downloaded from the
......@@ -173,26 +174,11 @@ following locations:
\textit{hdlmake} is used in the HDL synthesis process to create a Makefile and
Xilinx ISE / Altera Quartus project file
\item {\small\url{https://ohwr.org/project/wrpc-sw/uploads/a2e8eeba448fbc8d580e68004e6f6c7f/lm32.tar.xz}}
\item {\small\url{https://ohwr.org/project/wrpc-sw/wikis/uploads/9f9224d2249848ed3e854636de9c08dc/riscv-11.2-small.tgz}}
When the LM32 is used as soft-core processor inside the WRPC, this toolchain
can be used to compile the software for WRPC. This version of the toolchain
is for 32-bit systems. It can be used on 64-bit systems, but can fail to work
on some filesystems. If you encounter problems running this toolchain on
modern 64bit machines, try the 64-bit version described below.
\item {\small\url{https://ohwr.org/project/wrpc-sw/uploads/2776ce0ba43503d1486ae205b48fb450/lm32_host_64bit.tar.xz}}
When the LM32 is used as soft-core processor inside the WRPC, this toolchain
can be used to compile the software for WRPC. This is a 64-bit version of
the toolchain. For LM32 architecture this should be the default choice.
\item {\small\url{https://ohwr.org/project/wrpc-sw/wikis/uploads/e445916c27cc49cc62a370aded9cacb2/riscv_gcc_11_1_0.tar.xz}}
When the RISC-V is used as soft-core processor inside the WRPC, this toolchain
based on GCC 11.0.0 can be used to compile the software for WRPC. This
toolchain can work only on 64bit host machines. The instruction how to build
the toolchain for RISC-V can be found in
This toolchain based on GCC 11.2 can be used to compile the software
for WRPC. This toolchain can work only on 64bit host machines. The
instruction how to build the toolchain for RISC-V can be found in
the appendix~\ref{appendix:building_RISCV_toolchain}.
\end{itemize*}
......@@ -251,22 +237,6 @@ the soft-core processor's software, please check also
section~\ref{Software compilation}
which contains a description of the software compilation process.
% ==========================================================================
\subsection{Supported soft-core processors}
\label{Supported soft-core processors}
% TODO: fix before the release
The release v5.0 of WRPC supports the build with LM32 or RISC-V soft-core
processor. Both, the gateware and software have to be build for the same,
selected architecture.
The main reasons to introduce the RISC-V architecture are:
\begin{itemize}
\item lack of LM32 support by modern versions of GNU GCC
\item reduced footprint size of the software
\item licensing issues
\end{itemize}
% ==========================================================================
\subsection{HDL synthesis}
\label{HDL synthesis}
......@@ -336,13 +306,13 @@ $ chmod a+x /usr/bin/hdlmake
\end{lstlisting}
Having all the tools in place, you can now clone the main WR PTP Core git
repository for the v4.1 release. The set of commands below clones the WR PTP Core
repository for the v5 release. The set of commands below clones the WR PTP Core
repository, checks out the release tag, and downloads other HDL repositories
(submodules) needed to synthesize the core:
\begin{lstlisting}
$ git clone https://ohwr.org/project/wr-cores.git <your_location>/wr-cores
$ cd <your_location>/wr-cores
$ git checkout wrpc-v4.1
$ git checkout wrpc-v5
$ git submodule init
$ git submodule update
\end{lstlisting}
......@@ -446,7 +416,7 @@ Vivado flow to synthesize the bitstream.
\subsection{Software compilation}
\label{Software compilation}
By default, the LM32 or the RISC-V software for a stable release is embedded
By default, the RISC-V software for a stable release is embedded
inside the FPGA bitstream you've downloaded from \textit{ohwr.org} or
synthesized in section \ref{HDL synthesis}. You can skip this section, unless
you need to make some custom changes to the soft-core processor's software and
......@@ -457,58 +427,27 @@ package you will need a \emph{readline-dev} library. In some Linux distributions
you would have to install it manually. E.g. in Ubuntu, please install
\emph{libreadline-dev} package.\\
As mentioned in the section \ref{Supported soft-core processors}, the WRPC from
the v5.0 release can be build for LM32 or RISC-V soft-core processor. Major
parts of the building process are the same for both architecures.
First, you need to download and unpack the toolchain from the location
mentioned in section \ref{Repositories and Releases}. The following example
uses 32bit version of a LM32 toolchain.
\begin{lstlisting}
$ wget https://www.ohwr.org/project/wrpc-sw/uploads/a2e8eeba448fbc8d580e68004e6f6c7f/\
lm32.tar.xz
$ tar xJf lm32.tar.xz -C <your_location>
\end{lstlisting}
If you encounter problems running it, please use the LM32's 64bit version.
\begin{lstlisting}
$ wget https://www.ohwr.org/project/wrpc-sw/uploads/2776ce0ba43503d1486ae205b48fb450/\
lm32_host_64bit.tar.xz
$ tar xJf lm32_host_64bit.tar.xz -C <your_location>
\end{lstlisting}
If you decide to use RISC-V, please use the following toolchain:
mentioned in section \ref{Repositories and Releases}.
\begin{lstlisting}
$ wget https://ohwr.org/project/wrpc-sw/wikis/uploads/e445916c27cc49cc62a370aded9cacb2/\
riscv_gcc_11_1_0.tar.xz
$ tar xJf riscv_gcc_11_1_0.tar.xz -C <your_location>
$ wget https://ohwr.org/project/wrpc-sw/wikis/uploads/9f9224d2249848ed3e854636de9c08dc/\
riscv-11.2-small.tgz
$ tar xJf riscv-11.2-small.tgz -C <your_location>
\end{lstlisting}
Then you need to set a \texttt{CROSS\_COMPILE} environment variable in order
to compile the software. For the LM32 processor:
\begin{lstlisting}
$ export CROSS_COMPILE="<your_location>/lm32/bin/lm32-elf-"
\end{lstlisting}
For the RISC-V processor:
\begin{lstlisting}
$ export CROSS_COMPILE="<your_location>/riscv/bin/riscv32-unknown-elf-"
\end{lstlisting}
Or you can let the build system to select the proper toolchain based on
the selected architecture:
to compile the software. For the RISC-V processor:
\begin{lstlisting}
$ export CROSS_COMPILE_LM32="<your_location>/lm32/bin/lm32-elf-"
$ export CROSS_COMPILE_RISCV="<your_location>/riscv/bin/riscv32-unknown-elf-"
$ export CROSS_COMPILE="<your_location>/riscv-11.2-small/bin/riscv32-elf-"
\end{lstlisting}
To get the sources of the WRPC software, please clone the \textit{wrpc-sw} git
repository tagged with \texttt{wrpc-v5.0} tag. The commands in the listing below
clone the \textit{wrpc-sw} repository together with submodules needed for this software.\\
\begin{lstlisting}
$ git clone https://ohwr.org/project/wrpc-sw.git <your_location>/wrpc-sw
$ cd <your_location>/wrpc-sw
$ git checkout wrpc-v5.0
$ git checkout wrpc-v5
\end{lstlisting}
\textbf{Note:} If you use WRPC within another project, you may need to checkout
......@@ -534,11 +473,6 @@ three boards mentioned in this manual \code{spec\_defconfig} can be used.
$ make spec_defconfig
\end{lstlisting}
Each configuration file includes the definition of the architecture used for
soft-processor. To change it call the configuration tools described above or
manually set configuration options \texttt{CONFIG\_ARCH\_LM32} and
\texttt{CONFIG\_ARCH\_RISCV}.
After the package is configured, just run \code{make} without parameters to
build your binary file:
\begin{lstlisting}
......@@ -724,7 +658,7 @@ where \texttt{xx:xx:xx:xx:xx:xx} is the MAC address of your board.\\
Next, you should input calibration fixed delays values and alpha parameters. The
example below clears any existing entries and adds two Axcen transceivers with
$\Delta_{TX}$, $\Delta_{RX}$ and $\alpha$ parameters associated with them.
Please note that the $\alpha$ value is slit into two values. The most
Please note that the $\alpha$ value is split into two values. The most
significant 9 decimal digits and the least significant 9 decimal digits.
\begin{lstlisting}
......@@ -1786,8 +1720,7 @@ To this aim, you can pass a memory image (dump of RAM content) of \textit{wrpc}
The tool will print information for softpll, ppsi data structures,
ptp data sets and version information.
For example, for the \textit{spec} board and WRPC using LM32 as a soft-core
processor, you can use the resource file in
For example, for the \textit{spec} board, you can use the resource file in
\textit{sysfs} to look at a live system, or copy the file for off-line
analysis. The following command line show both uses:
......
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