Difference between revisions of "CasperTutorial01"

From AstroBaki
Jump to navigationJump to search
 
(11 intermediate revisions by 3 users not shown)
Line 34: Line 34:
  
 
Start Matlab and open Simulink (type "simulink"
 
Start Matlab and open Simulink (type "simulink"
on the Matlab command line).  Start a new model file by following Simulink Library Browser $\rightarrow$ File $\rightarrow$ New $\rightarrow$ Model:
+
on the Matlab command line).  Start a new model file by following {\it Simulink Library Browser $\rightarrow$ File $\rightarrow$ New $\rightarrow$ Model}:
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig2.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig2.png}\end{figure}
Line 40: Line 40:
 
\subsubsection{Add Xilinx System Generator and XSG Core Config blocks}
 
\subsubsection{Add Xilinx System Generator and XSG Core Config blocks}
  
All CASPER designs must have two blocks: a System Generator and an XPS Core Config.
+
All CASPER designs must have two blocks: a {\bf System Generator} and an {\bf XPS Core Config}.
 +
Go to {\it Simulink Library Browser $\rightarrow$ Xilinx Blockset $\rightarrow$ Basic Elements} and drag a {\bf System Generator} block onto your new model:
 +
 +
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig3.png}\end{figure}
 +
 
 +
There appears to be a bug on the Linux version of Xilinx System Generator for Simulink that appears to be solved by setting {\it System Generator $\rightarrow$ Clock pin location} to "d7":
 +
 
 +
\begin{figure}[h!]\centering\includegraphics[scale=.5]{sysgen_d7_hack.png}\end{figure}
  
Go to Simulink Library Browser $\rightarrow$ Xilinx Blockset $\rightarrow$ Basic Elements and drag a System Generator
+
Otherwise you should not need to configure the {\bf System Generator} block directly; add an  
block onto your new model. You should not configure this block directly; add an  
+
{\bf XSG Core Config} block from {\it Simulink Library Browser $\rightarrow$ BEE\_XPS System Blockset} to do it for you:
XSG Core Config block from Simulink Library Browser $\rightarrow$ BEE\_XPS System Blockset to do it for you:
 
  
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig3.png}\end{figure}
+
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig4.png}\end{figure}
  
 
All hardware-related (possibly board-specific) blocks are yellow and can be found in this BEE\_XPS
 
All hardware-related (possibly board-specific) blocks are yellow and can be found in this BEE\_XPS
 
library. Blocks relating to Digital Signal Processing (DSP) are found in the CASPER DSP library and have other colors.
 
library. Blocks relating to Digital Signal Processing (DSP) are found in the CASPER DSP library and have other colors.
  
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig4.png}\end{figure}
+
Double click on the XSG core config block that you just added. Set it for
 +
"ROACH: SX95t" with "sys\_clk" as the clock source:
  
Double click on the XSG core config block that you just added. Set it for
+
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig5.png}\end{figure}
ROACH: SX95t with sys\_clk as the clock source. sys\_clk is an on-board 100MHz
 
crystal oscillator. Click OK. This will go off and configure the System Generator block which you previously
 
added.
 
  
 
For the curious, the available clocking options include:
 
For the curious, the available clocking options include:
 
\begin{itemize}
 
\begin{itemize}
     \item sys\_clk: use onboard 100MHz crystal connected to the FPGA
+
     \item sys\_clk: use on-board 100MHz crystal connected to the FPGA
 
     \item sys\_clk2x: use frequency-doubled version of sys\_clk generated using a Phase Locked Loop (PLL) set by a Digital Clock Manager (DCM) on the FPGA
 
     \item sys\_clk2x: use frequency-doubled version of sys\_clk generated using a Phase Locked Loop (PLL) set by a Digital Clock Manager (DCM) on the FPGA
 
     \item arb\_clk: use clock generated from sys\_clk using a DCM (rounded to nearest integer within range of DCM's abilities)
 
     \item arb\_clk: use clock generated from sys\_clk using a DCM (rounded to nearest integer within range of DCM's abilities)
Line 67: Line 71:
 
\end{itemize}
 
\end{itemize}
  
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig5.png}\end{figure}
+
\subsection{Flashing an LED}
  
\subsection{Flashing LED}
+
To demonstrate the basic use of hardware interfaces, we will implement a flashing LED by adding the following circuitry to our model:
  
To demonstrate the basic use of hardware interfaces, we will add a flashing LED.
+
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig13.png}\end{figure}
With the FPGA running at 100MHz, the most significant bit (msb) of a 27 bit
 
counter will toggle every 0.745 seconds. We can output this bit to an LED on
 
ROACH. ROACH has four green LEDs. We will now connect a counter to the first
 
one.
 
  
\subsubsection{Add a counter}
+
With the FPGA running at 100MHz, the most significant bit (msb) of a 27-bit
 +
counter will toggle every 0.745 seconds. We can output this bit to one of the four
 +
green LEDs on the
 +
ROACH.
  
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig6.png}\end{figure}
+
\subsubsection{Add a Counter}
  
Add a counter to your design by navigating to Xilinx Blockset $\rightarrow$ Basic Elements
+
Drag a {\bf Counter} into your design from {\it Simulink Library Browser $\rightarrow$ Xilinx Blockset $\rightarrow$ Basic Elements}.  Double-click it and set the parameters for a
$\rightarrow$ Counter and dragging it onto your model.  Double-click it and set it for
+
free-running, 27-bit, unsigned counter:
free running, 27 bits, unsigned.
 
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig7.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig7.png}\end{figure}
  
\subsubsection{Add a slice block to select out the msb}
+
\subsubsection{Add a Slice}
  
We now need to select the most significant bit of the counter. We do this using
+
To select the most significant bit (MSB) of the counter, we need to add a
a slice block, which Xilinx provides. Xilinx Blockset $\rightarrow$ Basic
+
{\bf Slice} block to your model from {\it Simulink Library Browser $\rightarrow$ Xilinx Blockset $\rightarrow$ Basic
Elements $\rightarrow$ Slice.
+
Elements}.
  
 
Double-click on the newly added slice block. There are multiple ways to select
 
Double-click on the newly added slice block. There are multiple ways to select
which bit(s) you want.  In this case, I find it simplest to index from the
+
which bit(s) you want.  In this case, it is simplest to index from the
upper end and select the first bit. If you wanted the lsb, you could also index
+
upper end (MSB) and select the first bit. Set your slice to be 1 bit wide with 0 offset from the top bit:
from the lsb,. You can either select the width and offset, or two bit
 
locations.
 
 
 
Set it for 1 bit wide with offset from top bit at zero.
 
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig9.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig9.png}\end{figure}
  
\subsubsection{Add a GPIO block }
+
You could also have indexed
 +
from the least significant bit (LSB) with an offset of 26.
  
(BEE\_XPS library $\rightarrow$ gpio).
+
\subsubsection{Add a GPIO}
  
Set it to use ROACH's LED bank as output, GPIO bit index 0 (the first LED).
+
Drag in a {\bf gpio} (General Purpose Input/Output) block from {\it Simulink Library Browser $\rightarrow$ BEE\_XPS System Blockset}.  This block is used to interface your Simulink design to specific pins on the FPGA chip.
 +
Set it to use ROACH's LED bank as output with GPIO bit index 0 (i.e. the first LED):
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig11.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig11.png}\end{figure}
  
\subsubsection{Add a terminator}
+
\subsubsection{Add a Terminator}
  
To prevent warnings about unconnected outputs, terminate all unused outputs using a Terminator:  
+
This isn't strictly required, but to prevent warnings about unconnected outputs, you can connect unused outputs to a {\bf Terminator} block from {\it Simulink Library Browser $\rightarrow$ Simulink $\rightarrow$ Sinks}:  
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig12.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig12.png}\end{figure}
  
Note that all blocks from the "Simulink" library (usually white), will not be
+
Only Xilinx blocks (blue with an "X" logo, from {\it Simulink Library Browser $\rightarrow$ Xilinx Blockset}) compile to hardware. Blocks from the {\it Simulink Library Browser $\rightarrow$ Simulink} library are usually white, and they never compile into hardware; they are for simulation only.  These blocks are not to be confused with {\bf Subsystems}, which can appear as white blocks, but are hierarchical elements that contain other blocks, including blocks that compile to hardware.
compiled into hardware. They are present for simulation only and expect
 
continuous signals, not discreet.
 
  
Only Xilinx blocks (they are blue with Xilinx logo) will be compiled to hardware.
+
Blocks from the {\it Xilinx Blockset} library use a different data type than the rest of Simulink.  For this reason, you need to use yellow {\bf Gateway} blocks (from {\it Simulink Library Browser $\rightarrow$ Xilinx Blockset}) whenever connecting them to other
 +
Simulink-provided, simulation-only blocks.  Many of
 +
the yellow blocks in the {\it BEE\_XPS System Blockset}, like the GPIO block, do this for you with "sim\_in" and
 +
"sim\_out" ports. We will see later how to use a {\bf Scope} block to monitor lines.
  
For this reason, you need to use gateway blocks whenever connecting a
+
\subsubsection{Wire the Blocks}
Simulink-provided block (like a scope or constant) for simulations.  Some of
 
the CASPER blocks (like the GPIO block) do this for you with "sim\_in" and
 
"sim\_out". We will see later how to use a 'scope to monitor these lines.
 
  
\subsubsection{Connect your design}
+
Draw wires between blocks by clicking on the output of a block and dragging the line over to the input of another block. You may want to refer to the figure at the beginning of this section to remember how they should look wired up.
 
 
It is a good idea to rename your blocks to something more sensible, like
 
counter\_led instead of just counter. Do this simply by double-clicking on the
 
name of the block and editing the text appropriately.
 
 
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig13.png}\end{figure}
 
  
It is a good time to save this new design. There are some Matlab limitations you should be aware-of:
+
It is good practice to rename your blocks to something descriptive, like
+
"counter\_led", instead of just "counter". Do this by double-clicking on the
Do not use spaces in your filenames, or anywhere in the file path as it will break the toolflow.
+
name of the block and editing the text.
  
Total path length cannot be more than 64 characters. By "path", I am refering
+
Now would also be a good time to save this new design. There are some Matlab limitations you should be aware-of.
to not only the file path, but also the path to any block within your design.
+
Do not use spaces in the names of your Matlab files, or in any of the directories upstream in your path, as it will break the toolflow.
For example, if you save this file to c:\verb=\=projects\verb=\=myfile.mdl, the
+
Inside Simulink, names cannot be more than 64 characters. Some low-level interface blocks will be automatically renamed to include your filename, any hierarchical subsystems containing the block, and its own name.  
 +
For example, if you save this file under Windows to c:\verb=\=projects\verb=\=myfile.mdl, the
 
longest Matlab-indexed path would be
 
longest Matlab-indexed path would be
c:\verb=\=projects\verb=\=myfile.mdl\verb=\=counter\_led. While this is quite
+
c:\verb=\=projects\verb=\=myfile.mdl\verb=\=counter\_led. To avoid running against the 64-character limitation, try to keep your names concise but meaningful.
short, but there can be additional blocks hidden underneath some of your top
 
level blocks. This is the case with GPIO, for example. This will become clearer
 
later when we demonstrate the use of SubSystems. For now, try to keep your
 
names short.
 
  
Please save your design in c:\verb=\=projects\verb=\=<YOUR\_INITIALS>\_tut1.mdl.
+
\subsection{Controlling a Counter from Software}
  
 
+
In this section, we will demonstrate the use of special {\bf Software Register} blocks that can be accessed both from the FPGA and from an on-board Central Processing Unit (CPU) running Linux.  With these blocks, we will implement a counter that can be started, stopped, reset, and read out from software:
\subsection{Software control}
 
 
 
To demonstrate the use of software registers and control of the FPGA through
 
the PPC, we will add a controllable counter to the above design. The counter
 
can be started and stopped from software and also reset. We will be able to
 
monitor the counter's current value too.
 
 
 
By the end of this section, you will create a system that looks like this:
 
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig14.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig14.png}\end{figure}
  
\subsubsection{Add the software registers }
+
\subsubsection{Add Software Registers}
  
We need two software registers. One to control the counter, and a second one to
+
We need two {\bf Software Registers} from {\it Simulink Library Browser $\rightarrow$ BEE\_XPS System Blockset}: one to control the counter, and a second one to
read its current value. From the BEE\_XPS System Blockset library, drag two
+
read its current value.  
Software Registers onto your design.
+
On the first one, set the I/O direction to "From Processor" so that its value is controlled from the CPU.
 +
On the second, set the I/O direction to "To Processor" to allow the FPGA to set the value:
  
Set the I/O direction to From Processor on the first one to enable dataflow from PowerPC to the FPGA fabric. Set it to To Processor on the second one.
+
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig16.png}\end{figure}
  
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig16.png}\end{figure}
+
Note how "Data bitwidth" is greyed out with a value 32. All {\bf Software Registers} have a bitwidth fixed to 32 to match the width of the bus connecting them to the CPU.
  
Note the field Data bitwidth is greyed out with a value 32. This is because all software registers have a fixed data bitwidth of 32 bits.
+
The names of these {\bf Software Registers} are mapped to the names of
 +
files on the CPU that you will use to access values. Avoid using spaces, slashes
 +
and other funny characters in these names.  Spaces will be automatically remapped to
 +
underscores, but for clarity, we will avoid that for now.  Let's use "counter\_ctrl"
 +
and "counter\_value" to represent the control and output registers, respectively.
  
Rename the registers to something sensible, as these names are mapped to
+
{\bf Software Registers} have sim\_in and sim\_out ports. The
filenames in the PPC for controlling the design. Avoid using spaces, slashes
+
sim\_in input port provides a means of simulating how this register's value might be set by the CPU. The sim\_out output port provides a means to monitor the register's FPGA-assigned value, as it might be read by the CPU.
and other funny characters in these names (spaces automatically get remapped to
 
underscores anyway, but should be avoided for clarity). I suggest counter\_ctrl
 
and counter\_value, to represent the control and output registers respectively.
 
  
Also note that the software registers have sim\_in and sim\_out ports. The
+
\subsubsection{Add a Constant}
input port provides a means of simulating this register's value (as would be
 
set by the PPC) using the sim\_in line. The output port provides a means to
 
simulate this register's current FPGA-assigned value.
 
  
For now, set the sim\_in port to constant one using a Simulink-type constant.
+
For now, set the sim\_in port to 1 using a {\bf Constant} block from {\it Simulink Library Browser $\rightarrow$ Simulink $\rightarrow$ Sources}. This will simulate the counter being enabled.  
This will enable the counter during simulations.
 
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig17.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig17.png}\end{figure}
  
During simulation, we can monitor the counter's value using a scope:  
+
\subsubsection{Add a Scope}
 +
 
 +
We can monitor the value of the output register's sim\_out port by adding using {\bf Scope} from {\it Simulink Library Browser $\rightarrow$ Simulink $\rightarrow$ Sinks}:  
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig18.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig18.png}\end{figure}
  
\subsubsection{Add the counter}
+
\subsubsection{Add a Counter}
  
 
You can do this either by copying your existing counter block (copy-paste, or
 
You can do this either by copying your existing counter block (copy-paste, or
ctrl-click-drag-drop) or by placing a new one from the library.
+
ctrl-drag-drop) or by placing a new one from the library.
  
Configure it with a reset and enable port as follows:
+
Configure it with a reset and enable port:
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig19.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig19.png}\end{figure}
  
  
\subsubsection{Add the slice blocks}
+
\subsubsection{Add Two Slice Blocks}
  
Now we need some way to control the enable and reset ports of the counter. We
+
We could control the enable and reset ports of the counter using two separate software registers,
could do this using two separate software registers, but this is wasteful since
+
but this is wasteful; each register has 32 bits, and we only need two.
each register is 32 bits anyway.
+
We'll use a single register and slice out one bit for enabling the counter,
 
+
and another bit for resetting it. Either copy your existing {\bf Slice} block
So we'll use a single register and slice out one bit for enabling the counter,
+
(copy-paste, or ctrl-drag-drop) or add two more from
and another bit for resetting it. Either copy your existing slice block
 
(copy-paste it or hold ctrl while dragging/dropping it) or add two more from
 
 
the library.
 
the library.
  
 
The enable and reset ports of the counter require boolean values (which
 
The enable and reset ports of the counter require boolean values (which
Simulink interprets differently from ordinary 1-bit unsigned numbers).
+
Simulink interprets differently from 1-bit unsigned numbers).
Configure the slices as follows:
+
Configure the slice for the enable port as:
 
 
Slice for enable:
 
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig20.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig20.png}\end{figure}
  
Slice for reset:
+
and the slice for the reset port as:
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig21.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig21.png}\end{figure}
  
 +
\subsubsection{Wire the Blocks}
  
\subsubsection{Connect it all up}
+
Connect all these blocks together as per the diagram at the beginning of this section.  
 
+
To neaten things up, consider
Now we need to connect all these blocks together. To neaten things up, consider
 
 
resizing the slice blocks and hiding their names. Their function is clear
 
resizing the slice blocks and hiding their names. Their function is clear
 
enough from their icon without needing to see their names.
 
enough from their icon without needing to see their names.
  
Do so by right-clicking and selecting Format $\rightarrow$ Hide Name. You could do this
+
Do so by right-clicking and selecting {\it Format $\rightarrow$ Hide Name}. You could do this
with the counter too, but it's not a good idea with the software registers,
+
with the counter too, but it's not a good idea with the software registers.
because otherwise you wouldn't know how to address them when looking at your
+
You want to know how to address them by looking at your
diagram.
+
diagram!
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig22.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig22.png}\end{figure}
  
\subsection{Adder}
+
\subsection{Adding Two Numbers}
  
 
To demonstrate some simple mathematical operations, we will create an adder. It
 
To demonstrate some simple mathematical operations, we will create an adder. It
will add two numbers on demand and output the result to another software
+
will add numbers in two CPU-controllable registers and output the result to another software
register. Almost all astronomy DSP is done using fixed-point (integer)
+
register. As will be the case for most DSP in FPGAs, this adder will use fixed-point (integer)
notation, and this adder will be no different.
+
data types.
  
We will calculate a+b=sum\_a\_b.
+
We will calculate $a+b=sum\_a\_b$.
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig23.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig23.png}\end{figure}
  
\subsubsection{Add the software registers }
+
\subsubsection{Add Three Software Registers }
 
 
Add two more input software registers. These will allow us to specify the two
 
numbers to add. Add another output register for the sum output.
 
  
Either copy your existing software register blocks (copy-paste or holding ctrl
+
Add two more input {\bf Software Registers} to specify the
while dragging/dropping it) or add three more from the library. Set the I/O
+
numbers to add, and one more output {\bf Software Register} for returning the sum.
direction to From Processor on the first two and set it to To Processor on the
+
You may either copy your existing software register blocks or drag them in from the {\it BEE\_XPS Blockset} library.
 +
Set the I/O direction to "From Processor" on the first two, and "To Processor" on the
 
third one.
 
third one.
  
\subsubsection{Add the adder block }
+
\subsubsection{Add an AddSub Block}
  
Locate the adder/subtractor block, Xilinx Blockset $\rightarrow$ Math
+
Drag into your design the adder/subtractor block: {\it Xilinx Blockset $\rightarrow$ Math
$\rightarrow$ AddSub and drag one onto your design. This block can optionally
+
$\rightarrow$ AddSub}. This block can  
perform addition or subtraction. Let's leave it set at it's default, for
+
perform addition or subtraction. Its default configuration is for addition, and we'll leave that way:
addition.
 
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig24.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig24.png}\end{figure}
  
The output register is 32 bits. If we add two 32 bit numbers, we will have 33 bits.
+
Now we have an interesting problem.  The two input registers are 32 bits wide, and when we add them, we need 33 bits to guarantee that we can hold the full sum.  However, our output register has only 32 bits.
 
 
 
There are a number of ways of fixing this:
 
There are a number of ways of fixing this:
  
 
\begin{itemize}
 
\begin{itemize}
 
     \item limit the input bitwidth(s) with slice blocks
 
     \item limit the input bitwidth(s) with slice blocks
     \item limit the output bitwidth with slice blocks
+
     \item limit the output bitwidth with slice blocks, accepting that the sum may overflow and wrap
     \item create a 32 bit adder.
+
     \item saturate the sum at the maximum/minimum values that can be represented with 32 bits.
 
\end{itemize}
 
\end{itemize}
  
Since you have already seen slice blocks demonstrated, let's try to set the
+
Since {\bf Slice} blocks have already been demonstrated, let's try to set the
AddSub block to be a 32 bit saturating adder. On the second tab, set it for
+
{\bf AddSub} block to be a 32-bit saturating adder. On the second tab, set it for
user-defined precision, unsigned 32 bits.
+
user-defined precision, unsigned 32 bits. Change overflow to "saturate":
 +
 
 +
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig25.png}\end{figure}
 +
 
 +
Now, when the sum exceeds the maximum value that can be represented with 32 bits, this adder will return $2^{32} -1$.
 +
 
 +
\subsubsection{Add a Scope and Constants}
  
Also, under overflow, set it to saturate. Now if we add two very large numbers,
+
Add a {\bf Scope} and two {\bf Constant}. The constants are for simulation; set the values to anything you like.
it will simply return $2^{32} -1$.
 
  
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig25.png}\end{figure}
+
\subsubsection{Wire the Blocks}
  
\subsubsection{Add the scope and simulation inputs}
+
Connect the blocks as per the diagram at the beginning of this section.
  
Either copy your existing scope and simulation constants (copy-paste or
 
ctrl-drag) or place a new one from the library as before. Set the values of the
 
simulation inputs to anything you like.
 
  
\subsubsection{Connect it all together}
 
  
Like this:
 
  
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig26.png}\end{figure}
 
  
 
\section{Simulating}
 
\section{Simulating}
  
 
The design can be simulated with clock-for-clock accuracy directly from within
 
The design can be simulated with clock-for-clock accuracy directly from within
Simulink. Set the number of clock cycles that you'd like to simulate and press
+
Simulink. If you are on a Windows machine, set the number of clock cycles that you'd like to simulate and press
the play button in the top toolbar.
+
the play button in the top toolbar:
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig27.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig27.png}\end{figure}
 +
 +
If you are on a Linux machine, got to {\it Simulation $\rightarrow$ Configuration Parameters} to set the number of clock cycles in the simulation, and {\it Simulation $\rightarrow$ Start} to start the simulation.
 +
 +
If you get an error at this point, you may have a bug in your design.  However, if your error reads "Bad Cast From Null to Scalar" or causes Matlab itself to crash, and you are on a Linux system, the bug may not be your fault.  If you haven't already, try setting {\it System Generator $\rightarrow$ Clock pin location} to "d7" as per the recommendation in "Beginning a New Model".
  
 
You can watch the simulation progress in the status bar in the bottom right. It
 
You can watch the simulation progress in the status bar in the bottom right. It
 
will complete in the blink of an eye for this small design with just 10 clock
 
will complete in the blink of an eye for this small design with just 10 clock
 
cycles.  
 
cycles.  
 
 
You can double-click on the scopes to see what the signals look like on those
 
You can double-click on the scopes to see what the signals look like on those
lines. For example, the one connected to the counter should look like this:
+
lines. For example, the one connected to the counter should look like:
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig28.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig28.png}\end{figure}
Line 327: Line 302:
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig29.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig29.png}\end{figure}
  
Once you have verified that that design functions as you'd like, you're ready
+
Once you have verified that the design functions as you'd like, you're ready
to compile for the FPGA...
+
to compile for the FPGA.
 +
 
 +
 
 +
 
 +
 
  
 
\section{Compiling}
 
\section{Compiling}
  
Essentially, you have constructed three completely separate little instruments.
+
You have constructed essentially three completely separate little instruments.
You have a flashing LED, a counter which you can start/stop/reset from software
+
There is a flashing LED, a counter you can start/stop/reset from software,
and also an adder. These components are all clocked off the same 100MHz system
+
and an adder. These components are driven by the same 100MHz clock, but they operate independently.  
clock crystal, but they will operate independently.  
 
  
In order to compile this to an FPGA bitstream, type bee\_xps on the Matlab
+
In order to compile this to an FPGA bitstream, type "bee\_xps" on the Matlab
command line. Leave all options on defaults. Ensure that the listed design is
+
command line. Leave all options on defaults. Ensure that the listed design under System Generator Design Name is
the one you want to compile (System Generator Design Name). If it is not, click
+
the one you want to compile. If it is not, click
anywhere on your design such that it is the highlighted window, then click gcs.
+
anywhere on your design (making it the highlighted window), then click gcs (for Get Current System).
To start the process, simply click RUN XPS.
+
To start the process, click "RUN XPS":
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig30.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig30.png}\end{figure}
  
Compile time is approximately 15 minutes on the little blue computers. When
+
Compile time will vary by computer (on the computer we tried, it took 15 minutes). When
complete, you should receive a popup box like this:
+
complete, you should see a popup box:
  
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig31.png}\end{figure}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig31.png}\end{figure}
  
\section{Transferring your bitstream to your ROACH board}
+
 
 +
 
 +
 
 +
 
 +
 
 +
\section{Transferring the Bitstream to ROACH}
  
 
If you navigate to the directory containing your *.mdl file, you
 
If you navigate to the directory containing your *.mdl file, you
will find a subfolder with the same name as your Simulink design.
+
will find a directory with the same name as your Simulink design.
You will find your bitstreams inside the folder called bit\_files. There are
+
In that directory, you will find another directory "bit\_files" that holds your bitstreams.
two files with names of the form  
+
There should be two files with names of the form  
 
<design\_name>\_<start\_compile\_time>.XXX.
 
<design\_name>\_<start\_compile\_time>.XXX.
The *.bit is the raw FPGA bitstream that you could load manually using a Xilinx
+
The *.bit is the raw FPGA bitstream that can be manually loaded using a Xilinx
JTAG programmer. Of interest to us now is the *.bof file. This is a BORPH
+
JTAG programmer. Instead, we'll opt to use the *.bof file--a BORPH
executable. We will transfer this to your ROACH board now.
+
executable. Let's transfer this file to your ROACH board now.
  
 
To transfer files to ROACH, you can use any program capable of doing Secure Copy over SSH
 
To transfer files to ROACH, you can use any program capable of doing Secure Copy over SSH
 
Protocol (SCP) transfers.  On Linux, scp is the standard tool.
 
Protocol (SCP) transfers.  On Linux, scp is the standard tool.
 +
You will need to place your *.bof file in the /boffiles directory of the ROACH filesystem, and make it executable.
 +
If your ROACH is configured to have its own file system and you are running Linux, this may be as simple as:
 +
\begin{verbatim}
 +
bash$ scp *.bof root@<roach-ip>:/boffiles
 +
bash$ ssh root@<roach-ip>
 +
root@roach020112:~# chmod a+x /boffiles/*.bof
 +
\end{verbatim}
 +
 +
 +
  
You will then login to the Linux server wsserv that boots the ROACH boards and
 
hosts their filesystem. The ROACH filesystem lives in /srv/roach\_boot/etch/.
 
  
In the root folder of this filesystem is a directory called /boffiles. ROACH
 
boards look in here for executable BORPH files. You will need to transfer your
 
bof file into this directory and make it executable. Navigate to /srv/roach\_boot/etch/boffiles. This
 
directory is shared amongst all the ROACH boards, so you will notice a list of
 
everyone else's bof files too.
 
  
 
\section{Connecting to your ROACH board}
 
\section{Connecting to your ROACH board}
  
\subsection{Booting your ROACH}
+
\subsection{Boot the ROACH}
  
To watch ROACH boot, you need to connect to it using a serial port. Under Linux, minicom is  
+
If you want to watch ROACH boot, you need to connect to it using a serial port. Under Linux, minicom is  
 
a standard tool for communicating over the serial port.  On Windows, try HyperTerminal.
 
a standard tool for communicating over the serial port.  On Windows, try HyperTerminal.
 
Set the serial connection to use your serial port (usually of the form /dev/tty* on Linux or
 
Set the serial connection to use your serial port (usually of the form /dev/tty* on Linux or
 
com1 on Windows) at 115200 baud, 8N1 with no flow control.
 
com1 on Windows) at 115200 baud, 8N1 with no flow control.
 
\subsection{Turn the ROACH on}
 
  
 
You will be greeted with a printout similar to this one:
 
You will be greeted with a printout similar to this one:
Line 415: Line 399:
 
\end{verbatim}
 
\end{verbatim}
  
This is ROACH's version of a BIOS along with some basic PPC health printouts.
+
This is ROACH's version of a BIOS along with some basic CPU health printouts.
 
Press any key here to stop the automatic boot process. This is the state of the
 
Press any key here to stop the automatic boot process. This is the state of the
 
ROACH boards when shipping. You can configure it differently should you please.
 
ROACH boards when shipping. You can configure it differently should you please.
Line 427: Line 411:
 
where to find the filesystem.  
 
where to find the filesystem.  
  
After Linux has completed its boot process, you will be greeted with a Debian prompt.
+
After Linux has completed its boot process, you will be greeted with a Debian Linux prompt.
  
 
\begin{verbatim}
 
\begin{verbatim}
Line 434: Line 418:
 
roach020112 login:   
 
roach020112 login:   
 
\end{verbatim}
 
\end{verbatim}
 +
 +
\subsection{SSH into ROACH}
  
 
You can connect to your ROACH board by SSHing directly into it. Under Linux, use the command "ssh".
 
You can connect to your ROACH board by SSHing directly into it. Under Linux, use the command "ssh".
Line 447: Line 433:
  
 
We are now ready to start working with the ROACH board.
 
We are now ready to start working with the ROACH board.
 +
 +
 +
 +
 +
 +
  
 
\section{Communicating directly using BORPH}
 
\section{Communicating directly using BORPH}
Line 452: Line 444:
 
\subsection{Programming the FPGA from BORPH}
 
\subsection{Programming the FPGA from BORPH}
  
To do so, simply execute it as you would any other linux program. Recall that
+
To program the ROACH FPGA, execute your *.bof file as you would any other Linux program.  
the filesystem is mapped from the server and the BORPH files were in
+
Change to the /boffiles directory and see which files are available:
/boffiles/.
 
 
 
Let's change to that directory now and see which files are available:
 
  
 
\begin{verbatim}
 
\begin{verbatim}
Line 466: Line 455:
 
-rwxr-xr-x  1 1000 1000 3894183 Aug 20  2009 das_blinken_lichte_2009_Feb_04_1837.bof
 
-rwxr-xr-x  1 1000 1000 3894183 Aug 20  2009 das_blinken_lichte_2009_Feb_04_1837.bof
 
-rw-r--r--  1 1001 1001 4468934 Aug 14  2009 tut1_2009_Aug_14_1140.bof
 
-rw-r--r--  1 1001 1001 4468934 Aug 14  2009 tut1_2009_Aug_14_1140.bof
root@roach020112:/boffiles#
 
 
\end{verbatim}
 
\end{verbatim}
  
  
We need to ensure that the file is marked as an executable, so that Linux is
+
If you haven't already, ensure that the file is marked as an executable, so that Linux is
able to run it. You will notice that our tut1 file is not executable (look at
+
able to run it:
the leftmost columns and see that there are no 'x's). Let's make it executable
 
now:
 
  
 
\begin{verbatim}
 
\begin{verbatim}
 
root@roach020112:/boffiles# chmod a+x tut1_2009_Aug_14_1140.bof  
 
root@roach020112:/boffiles# chmod a+x tut1_2009_Aug_14_1140.bof  
root@roach020112:/boffiles#
 
 
\end{verbatim}
 
\end{verbatim}
  
This will change permissions on the file, by adding executable permissions for
+
Now we are ready to execute it:
everybody. Rechecking:
 
 
 
\begin{verbatim}
 
root@roach020112:/boffiles# ls -al
 
total 8196
 
drwxrwxrwx  2 root root    4096 Aug 20  2009 .
 
drwxr-xr-x 23 root root    4096 Feb  2  2009 ..
 
-rwxr-xr-x  1 1000 1000 3894183 Aug 20  2009 das_blinken_lichte_2009_Feb_04_1837.bof
 
-rwxr-xr-x  1 1001 1001 4468934 Aug 14  2009 tut1_2009_Aug_14_1140.bof
 
root@roach020112:/boffiles#
 
\end{verbatim}
 
 
 
Now we are ready to execute it.
 
  
 
\begin{verbatim}
 
\begin{verbatim}
Line 499: Line 471:
 
\end{verbatim}
 
\end{verbatim}
  
This will go'n program the FPGA, and you should notice that LED0 on the ROACH
+
This will program the FPGA, and you should notice immediately that LED0 on the ROACH
hardware is now blinking. However, we've lost our terminal, because the process
+
hardware is blinking. However, we've lost control of our terminal because the *.bof file is
has captured it. To keep the process running, but return the prompt to us, we
+
continuing to execute. To keep the process running, but return the prompt to us, we
can now choose to background the task (ctrl-z), or we can kill it (ctrl-c) and
+
can now choose to background the task (ctrl-z, the "bg"), or we can kill it (ctrl-c) and
restart it with an amperstand, which will start it backgrounded.
+
restart it with an ampersand, which will start it in the background.
  
 
\begin{verbatim}
 
\begin{verbatim}
 
root@roach020112:/boffiles# ./tut1_2009_Aug_14_1140.bof &
 
root@roach020112:/boffiles# ./tut1_2009_Aug_14_1140.bof &
 
[1] 323
 
[1] 323
root@roach020112:/boffiles#
 
 
\end{verbatim}
 
\end{verbatim}
  
Our FPGA is now programmed (check for the flashing LED) and we have our prompt back!
+
Our FPGA is now programmed (check for the flashing LED) and we have our prompt back.
 
 
 
 
 
We can now see that a process in Linux has started...
 
We can now see that a process in Linux has started...
  
Line 531: Line 500:
 
root      328  0.8  0.3  3524  1800 pts/0    Ss  07:36  0:00 -bash
 
root      328  0.8  0.3  3524  1800 pts/0    Ss  07:36  0:00 -bash
 
root      332  0.0  0.1  2780  996 pts/0    R+  07:37  0:00 ps aux
 
root      332  0.0  0.1  2780  996 pts/0    R+  07:37  0:00 ps aux
root@roach020112:/boffiles#
 
 
\end{verbatim}
 
\end{verbatim}
  
Notice that PID 323 (yours may be different) is our process. We can now
+
Notice that PID 323 (yours may be different) is the *.bof file. We can now
navigate to the proc directory which contains our software registers.
+
navigate to a /proc directory that contains our software registers:
  
 
\begin{verbatim}
 
\begin{verbatim}
Line 553: Line 521:
 
-rw-rw-rw- 1 root root 4 Aug 21 08:00 sys_rev_rcs
 
-rw-rw-rw- 1 root root 4 Aug 21 08:00 sys_rev_rcs
 
-rw-rw-rw- 1 root root 4 Aug 21 08:00 sys_scratchpad
 
-rw-rw-rw- 1 root root 4 Aug 21 08:00 sys_scratchpad
root@roach020112:/proc/323/hw/ioreg#
 
 
\end{verbatim}
 
\end{verbatim}
  
Now you can see all our software registers. We have a, b, counter\_ctrl,
+
Now you can see all our software registers: a, b, counter\_ctrl,
counter\_value and sum\_a\_b as expect. However, in addition, the toolflow has
+
counter\_value and sum\_a\_b . In addition, the toolflow has
automatically added a few other registers.
+
automatically added a few other registers:
 
+
\begin{itemize}
sys\_board\_id is simply a constant which allows software to identify what
+
\item sys\_board\_id is simply a constant which allows software to identify what
 
hardware platform is running. For ROACH, this is a constant 0xb00b001.
 
hardware platform is running. For ROACH, this is a constant 0xb00b001.
  
sys\_clkcounter is a 32-bit counter that increments automatically on every FPGA
+
\item sys\_clkcounter is a 32-bit counter that increments automatically on every FPGA
 
clock tick. This allows software to estimate the FPGA's clock rate. Useful for
 
clock tick. This allows software to estimate the FPGA's clock rate. Useful for
 
debugging boards with bad clock inputs.
 
debugging boards with bad clock inputs.
  
sys\_rev is not yet implemented, but will eventually indicate the revision of
+
\item sys\_rev is not yet implemented, but will eventually indicate the revision of
 
the software toolchain that was used to compile the design
 
the software toolchain that was used to compile the design
  
sys\_rcs is also not yet implemented, but will eventually indicate the SVN revision of the CASPER library that was used to compile your design.
+
\item sys\_rcs is also not yet implemented, but will eventually indicate the SVN revision of the CASPER library that was used to compile your design.
  
sys\_scratchpad is simply a read/write software register where you can write a
+
\item sys\_scratchpad is simply a read/write software register where you can write a
 
register and read it back again as a sanity check.  Communicating with your
 
register and read it back again as a sanity check.  Communicating with your
 
FPGA process in BORPH The registers contain binary data. To read and represent
 
FPGA process in BORPH The registers contain binary data. To read and represent
Line 579: Line 546:
 
binary files. To write into these files, we'll use Linux's echo utility. Echo
 
binary files. To write into these files, we'll use Linux's echo utility. Echo
 
does not support writing hex values, but does support octal (base-8).  
 
does not support writing hex values, but does support octal (base-8).  
 +
\end{itemize}
  
Let's start by having a look at our counter value. Since we haven't started it
+
Start by having a look at our counter value. Since we haven't started it
 
yet, we expect it to be zero.  
 
yet, we expect it to be zero.  
  
Line 587: Line 555:
 
00000000  00 00 00 00                                      |....|
 
00000000  00 00 00 00                                      |....|
 
00000004
 
00000004
root@roach020112:/proc/323/hw/ioreg#
 
 
\end{verbatim}
 
\end{verbatim}
  
Line 604: Line 571:
  
 
Here we have told echo not to append a newline character to the end of the line
 
Here we have told echo not to append a newline character to the end of the line
(-n), and told it to interpret the incoming string's escape characters
+
(-n), and told it to interpret the incoming string's escape characters
(\verb=\=0 specifies octal values). Then we pipe it's output into
+
(\verb=\=0 specifies octal values). Then we pipe its output into
counter\_ctrl. Now let's relook at the counter value...
+
counter\_ctrl. Now when we look at the counter value...
  
 
\begin{verbatim}
 
\begin{verbatim}
Line 632: Line 599:
 
00000000  00 00 00 00                                      |....|
 
00000000  00 00 00 00                                      |....|
 
00000004
 
00000004
root@roach020112:/proc/323/hw/ioreg#
 
 
\end{verbatim}
 
\end{verbatim}
  
Line 688: Line 654:
 
\section{Interacting using KATCP}
 
\section{Interacting using KATCP}
  
KATCP is a process running on the ROACH boards which listens for TCP
+
KATCP is a process running on the ROACH boards that listens for TCP
 
connections on port 7147 (tcpborphserver). It talks using machine-parseable
 
connections on port 7147 (tcpborphserver). It talks using machine-parseable
 
ASCII text strings. It was designed this way so that it is easy to debug by
 
ASCII text strings. It was designed this way so that it is easy to debug by
watching the exchange of network traffic, whilst still being easy to program
+
watching the exchange of network traffic, and also be easy to program
 
clients and servers.
 
clients and servers.
  
 
\subsection{Connecting to your ROACH}
 
\subsection{Connecting to your ROACH}
  
Telnet allows you to connect directly to an open TCP port. Let's connect to ROACH's KATCP port now.  
+
Telnet (either "telnet" under Linux, or Putty on Windows) allows you to connect directly to an open TCP port. Let's connect to ROACH's KATCP port now:  
Open putty.exe.
+
 
 
\begin{itemize}
 
\begin{itemize}
 
     \item Select Telnet as the connection type.
 
     \item Select Telnet as the connection type.
Line 704: Line 670:
 
     \item Press Open.
 
     \item Press Open.
 
\end{itemize}
 
\end{itemize}
 
\begin{figure}[h!]\centering\includegraphics[scale=.5]{tut1_fig36.png}\end{figure}
 
  
 
You will be greeted with the KATCP welcome header.
 
You will be greeted with the KATCP welcome header.
Line 759: Line 723:
 
Here you can see what a multiline response looks like. Although a little hard
 
Here you can see what a multiline response looks like. Although a little hard
 
to read by us humans, this is easy to parse by a machine. We have clients
 
to read by us humans, this is easy to parse by a machine. We have clients
available for decoding this text and constructing commands automatically. They
+
available for decoding this text and constructing commands automatically. For now, let's look at constructing some
will be demonstrated in Tutorial 2. For now, let's look at constructing some
 
 
commands by hand.
 
commands by hand.
 
+
To get a list of bof files available:
To get a list of bof files available, type ?listbof.
 
  
 
\begin{verbatim}
 
\begin{verbatim}
Line 772: Line 734:
 
\end{verbatim}
 
\end{verbatim}
  
To program the FPGA with one of these bitstreams, type ?progdev <my\_boffile>.
+
To program the FPGA with one of these bitstreams:
 +
 
 
\begin{verbatim}
 
\begin{verbatim}
 
?progdev tut1_2009_Aug_14_1140.bof
 
?progdev tut1_2009_Aug_14_1140.bof
Line 779: Line 742:
  
 
You will notice that commands are ignored if you don't include the ? in the
 
You will notice that commands are ignored if you don't include the ? in the
front.  To list the registers available to you, type ?listdev.
+
front.  To list the registers available to you:
  
 
\begin{verbatim}
 
\begin{verbatim}
Line 818: Line 781:
 
index offset. It is used when writing to blocks of memory, rather than software
 
index offset. It is used when writing to blocks of memory, rather than software
 
registers. For example, if you wanted to write a single 32 bit number into a
 
registers. For example, if you wanted to write a single 32 bit number into a
1GB DRAM memory chunk, at address 0x12808, you would say ?wordwrite <my\_dram>
+
1GB DRAM memory chunk, at address 0x12808, you would say:
0x12808 <my\_value>.
+
\begin{verbatim}
 +
?wordwrite <my\_dram> 0x12808 <my\_value>
 +
\end{verbatim}
  
 
As you can see, the same FPGA functions that are available in BORPH are
 
As you can see, the same FPGA functions that are available in BORPH are
Line 827: Line 792:
 
\section{Conclusion}
 
\section{Conclusion}
  
This concludes Tutorial 1. You have learnt how to constuct a simple Simulink
+
This concludes Tutorial 1. You have constucted a simple Simulink
design, transfer the files to a ROACH board and interact with it using BORPH
+
design, transfered the BORPH files to a ROACH board, and interacted with a running FPGA design using BORPH
 
and KATCP.
 
and KATCP.
 
In Tutorial 2, you will learn how to use the 10GbE network interfaces and
 
interact with your design using the KATCP Python client.
 
  
 
\end{document}
 
\end{document}
 
</latex>
 
</latex>

Latest revision as of 15:56, 31 March 2010