1 |
210 |
ja_rd |
|
2 |
|
|
\chapter{Usage}
|
3 |
|
|
|
4 |
|
|
\section{Main Modules}
|
5 |
|
|
\label{main_modules}
|
6 |
|
|
|
7 |
|
|
The core is split in three main modules:
|
8 |
|
|
|
9 |
|
|
\begin{enumerate}
|
10 |
|
|
\item The CPU (mips\_cpu.vhdl).
|
11 |
|
|
\item The cache+memory controller (mips\_cache.vhdl).
|
12 |
221 |
ja_rd |
\item A 'SoC' entity which combines CPU+Cache (mips\_soc.vhdl).
|
13 |
210 |
ja_rd |
\end{enumerate}
|
14 |
|
|
|
15 |
221 |
ja_rd |
The entity you should use in your projects is the SoC module. The project
|
16 |
210 |
ja_rd |
includes a 'hardware demo' built around this module (see section
|
17 |
221 |
ja_rd |
~\ref{pregenerated_demo}) which is meant as an usage example.\\
|
18 |
210 |
ja_rd |
|
19 |
|
|
|
20 |
221 |
ja_rd |
\section{Bootstrap Code}
|
21 |
|
|
\label{bootstrap_code}
|
22 |
210 |
ja_rd |
|
23 |
221 |
ja_rd |
Though the core is meant to run mostly from off-chip memory, the current version
|
24 |
|
|
of the SoC module includes a small ROM implemented as FPGA BRAM and called
|
25 |
|
|
'bootstrap BRAM'. In the current version of the core, this BRAM can be loaded
|
26 |
|
|
with arbitrary code and its size can be configured by using generics, but it
|
27 |
|
|
can't be removed from the SoC. Even though the memory map can be modified to
|
28 |
|
|
boot from external FLASH and not use a BRAM at all, a BRAM will still be
|
29 |
|
|
inferred within the SoC -- subsequent versions will fix this.
|
30 |
210 |
ja_rd |
|
31 |
221 |
ja_rd |
As can be seen in table~\ref{tab_soc_memory_map}, the internal BRAM is mirrored
|
32 |
|
|
all over a wide area starting at \texttt{0xb8000000}. In practice, this means
|
33 |
|
|
the BRAM will be mapped at the CPU reset address (\texttt{0xbfc00000}) and thus
|
34 |
|
|
the bootstrap code should be placed there.
|
35 |
|
|
Unless the bootstrap BRAM is very small, it will span over the interrupt vector
|
36 |
|
|
address too (\texttt{0xbfc00180}).
|
37 |
210 |
ja_rd |
|
38 |
221 |
ja_rd |
For example, the 'Adventure' demo included with the project uses bootstrap
|
39 |
|
|
code included in file \texttt{/src/common/bootstrap.s}. This bootstrap code
|
40 |
|
|
is fairly incomplete (interrupt response code is mostly a stub) yet it's enough
|
41 |
|
|
to boot most applications.
|
42 |
|
|
Note that the C startup code, which deals with things like initializing the
|
43 |
|
|
static variables on the data segment, etc. is not part of this bootstrap code.
|
44 |
|
|
It can be found in file \texttt{/src/common/c\_startup.s}
|
45 |
210 |
ja_rd |
|
46 |
221 |
ja_rd |
So, in short, the code loaded onto the startup BRAM should include the most
|
47 |
|
|
basic system initialization (cache initialization at least) and the entry point
|
48 |
|
|
for the interrupt response code; plus a jump to the main program entry address.
|
49 |
210 |
ja_rd |
|
50 |
221 |
ja_rd |
Anyone trying to build some application on this core is advised to use the code
|
51 |
|
|
samples as starting points, specially the makefiles.
|
52 |
210 |
ja_rd |
|
53 |
|
|
|
54 |
221 |
ja_rd |
\subsection{Loading Bootstrap Code on the SoC Module}
|
55 |
|
|
\label{loading_bootstrap_code}
|
56 |
210 |
ja_rd |
|
57 |
221 |
ja_rd |
Once the code that is to be loaded on the bootstrap BRAM has been built, you
|
58 |
|
|
need to load it onto the bootstrap BRAM within the FPGA.
|
59 |
210 |
ja_rd |
|
60 |
221 |
ja_rd |
As you probably already know, there are several possible ways to deal with this
|
61 |
|
|
and most of them involve using \emph{'Memory Initialization Files'} of
|
62 |
|
|
some sort. This project is different.
|
63 |
210 |
ja_rd |
|
64 |
221 |
ja_rd |
So far, this project does not include any support for using IMF
|
65 |
|
|
files of any kind. Instead, the bootstrap BRAM is inferred and initialized
|
66 |
|
|
using regular VHDL constructs and a constant passed to the SoC module as a
|
67 |
|
|
generic.
|
68 |
210 |
ja_rd |
|
69 |
221 |
ja_rd |
This scheme has a big drawback: every time the object code within the FPGA
|
70 |
|
|
changes, the whole synthesis needs to be re-run. This drawback is manageable
|
71 |
|
|
as long as the core is not used in any big project or if the bootstrap code
|
72 |
|
|
does not change often.
|
73 |
210 |
ja_rd |
|
74 |
221 |
ja_rd |
On the other hand, I see some big advantages in using regular BRAM inference in
|
75 |
|
|
this stage of the project:
|
76 |
210 |
ja_rd |
|
77 |
221 |
ja_rd |
\begin{enumerate}
|
78 |
|
|
\item The whole scheme is totally vendor agnostic.
|
79 |
|
|
\item Object code embedded on VHDL constants can very easily be used in both simulation and synthesis.
|
80 |
|
|
\end{enumerate}
|
81 |
210 |
ja_rd |
|
82 |
221 |
ja_rd |
So, whatever object code is to be used to initialize the SoC bootstrap BRAM has
|
83 |
|
|
to be passed to the SoC module instance as a generic constant (see section
|
84 |
|
|
~\ref{soc_generics}). The constant must be of type \texttt{t\_obj\_code}, which
|
85 |
|
|
is defined in package \emph{mips\_pkg}.
|
86 |
210 |
ja_rd |
|
87 |
|
|
|
88 |
221 |
ja_rd |
\subsection{Building the Bootstrap Initialization Constant}
|
89 |
|
|
\label{boot_code_conversion}
|
90 |
210 |
ja_rd |
|
91 |
221 |
ja_rd |
The project includes a python script (\texttt{/tools/build\_pkg/build\_pkg.py})
|
92 |
|
|
whose purpose is to build an VHDL \texttt{t\_obj\_code} constant out of a
|
93 |
|
|
\emph{binary} object code file.
|
94 |
|
|
|
95 |
|
|
This script will read one or more big-endian, binary object files and will
|
96 |
|
|
produce a VHDL package file that will contain initialization constants for
|
97 |
|
|
the bootstrap BRAM and for some other memories that are only used in the
|
98 |
|
|
simulation test bench.
|
99 |
|
|
The package can optionally include too some simulation and synthesis
|
100 |
|
|
configuration constants -- such as the size of the bootstrap BRAM.
|
101 |
210 |
ja_rd |
|
102 |
221 |
ja_rd |
The makefiles included in the code samples invoke this script twice: once
|
103 |
|
|
to generate a package called \emph{sim\_params\_pkg} and used in the
|
104 |
|
|
simulation test bench; and once to build a package called
|
105 |
|
|
\emph{bootstrap\_code\_pkg} used for synthesis.
|
106 |
|
|
|
107 |
|
|
Please refer to the makefiles for usage examples, and read the script source
|
108 |
|
|
for more detailed usage instructions.
|
109 |
|
|
|
110 |
|
|
|