Subversion Repositories ion

\chapter{Usage}

\section{Main Modules}

\label{main_modules}

The core is split in three main modules:

\begin{enumerate}

    \item The CPU (mips\_cpu.vhdl).

    \item The cache+memory controller (mips\_cache.vhdl).

    \item A 'SoC' entity which combines CPU+Cache (mips\_soc.vhdl).

\end{enumerate}

The entity you should use in your projects is the SoC module. The project

includes a 'hardware demo' built around this module (see section

~\ref{pregenerated_demo}) which is meant as an usage example.\\

\section{Bootstrap Code}

\label{bootstrap_code}

Though the core is meant to run mostly from off-chip memory, the current version

of the SoC module includes a small ROM implemented as FPGA BRAM and called

'bootstrap BRAM'. In the current version of the core, this BRAM can be loaded

with arbitrary code and its size can be configured by using generics, but it

can't be removed from the SoC. Even though the memory map can be modified to

boot from external FLASH and not use a BRAM at all, a BRAM will still be

inferred within the SoC -- subsequent versions will fix this.

As can be seen in table~\ref{tab_soc_memory_map}, the internal BRAM is mirrored

all over a wide area starting at \texttt{0xb8000000}. In practice, this means

the BRAM will be mapped at the CPU reset address (\texttt{0xbfc00000}) and thus

the bootstrap code should be placed there.

Unless the bootstrap BRAM is very small, it will span over the interrupt vector

address too (\texttt{0xbfc00180}).

For example, the 'Adventure' demo included with the project uses bootstrap

code included in file \texttt{/src/common/bootstrap.s}. This bootstrap code

is fairly incomplete (interrupt response code is mostly a stub) yet it's enough

to boot most applications.

Note that the C startup code, which deals with things like initializing the

static variables on the data segment, etc. is not part of this bootstrap code.

It can be found in file \texttt{/src/common/c\_startup.s}

So, in short, the code loaded onto the startup BRAM should include the most

basic system initialization (cache initialization at least) and the entry point

for the interrupt response code; plus a jump to the main program entry address.

Anyone trying to build some application on this core is advised to use the code

samples as starting points, specially the makefiles.

\subsection{Loading Bootstrap Code on the SoC Module}

\label{loading_bootstrap_code}

Once the code that is to be loaded on the bootstrap BRAM has been built, you

need to load it onto the bootstrap BRAM within the FPGA.

As you probably already know, there are several possible ways to deal with this

and most of them involve using \emph{'Memory Initialization Files'} of

some sort. This project is different.

So far, this project does not include any support for using IMF

files of any kind. Instead, the bootstrap BRAM is inferred and initialized

using regular VHDL constructs and a constant passed to the SoC module as a

generic.

This scheme has a big drawback: every time the object code within the FPGA

changes, the whole synthesis needs to be re-run. This drawback is manageable

as long as the core is not used in any big project or if the bootstrap code

does not change often.

On the other hand, I see some big advantages in using regular BRAM inference in

this stage of the project:

\begin{enumerate}

\item The whole scheme is totally vendor agnostic.

\item Object code embedded on VHDL constants can very easily be used in both simulation and synthesis.

\end{enumerate}

So, whatever object code is to be used to initialize the SoC bootstrap BRAM has

to be passed to the SoC module instance as a generic constant (see section

~\ref{soc_generics}). The constant must be of type \texttt{t\_obj\_code}, which

is defined in package \emph{mips\_pkg}.

\subsection{Building the Bootstrap Initialization Constant}

\label{boot_code_conversion}

    The project includes a python script (\texttt{/tools/build\_pkg/build\_pkg.py})

    whose purpose is to build an VHDL \texttt{t\_obj\_code} constant out of a

    \emph{binary} object code file.

    This script will read one or more big-endian, binary object files and will

    produce a  VHDL package file that will contain initialization constants for

    the bootstrap BRAM and for some other memories that are only used in the

    simulation test bench.

    The package can optionally include too some simulation and synthesis

    configuration constants -- such as the size of the bootstrap BRAM.

    The makefiles included in the code samples invoke this script twice: once

    to generate a package called \emph{sim\_params\_pkg} and used in the

    simulation test bench; and once to build a package called

    \emph{bootstrap\_code\_pkg} used for synthesis.

    Please refer to the makefiles for usage examples, and read the script source

    for more detailed usage instructions.