Subversion Repositories ion

\chapter{Code samples}

\label{samples}

    Directory /src directory contains a few test applications that can be

    simulated and run on real hardware, except for the opcode test which can

    only be simulated. See the readme file and the makefile for each program.\\

    Please read the /src/reame.txt file for information that will probably be

    more up-to-date than this doc.\\

    The makefiles have been tested with the CodeSourcery toolchain for windows

    (that can be downloaded from www.codesourcery.com) and with the Buildroot

    toolchain for GNU/Linux.\\

    Most makefiles have two targets, to create a simulation test bench and a

    synthesizable demo.\\

    Target 'sim' will build the simulation test bench package files as described

    in section~\ref{logic_simulation}.

    Target 'demo' will build a synthesizable demo; it will compile the sample

    sources and place the resulting object code in file

    '/vhdl/SoC/bootstrap\_code\_pkg.vhdl'.\\

    The build process will produce two or more binary files ('*.code' and

    '*.data', or '*.bin') that can be run on the software simulator, plus a

    listing file (*.lst) handy for debugging.\\

    All projects include a DOS batch file 'swsim.bat' that invokes the

    software simulator with the proper parameters. As an example, these are the

    contents of the 'swsim.bat' file for the 'hello' demo:

    \needspace{8\baselineskip}

    \begin{verbatim}

    @rem Run software simulator in hands-off mode

    ..\..\tools\slite\slite\bin\Debug\slite.exe ^

        --bram=hello.code ^

        --trigger=bfc00000 ^

        --noprompt ^

        --nomips32 ^

        --map=hello.map ^

        --trace_log=trace_log.txt

    \end{verbatim}\\

    As you can see, the simulator is invoked in 'batch' or 'hands-off' mode, so

    the simulated program will be run to completion, generating a simulation

    log. The point of this is comparing that log to the log generated by the

    Modelsim simulation of the same program, as has already been explained.

    The python script 'bin2hdl.py' is used to insert binary data on vhdl

    templates.

    Assuming you have Python 2.5 or later in your machine, call the script with:

    \needspace{1\baselineskip}

    \begin{verbatim}

    python bin2hdl.py --help

    \end{verbatim}\\

    to get a short description (see section~\ref{python_script}).

\section{Support Code}

\label{support_code}

\subsection{Bootstrap Code}

\label{asm_bootstrap_code}

    File \emph{'/src/common/bootstrap.s'} contains the reset code and the stub

    interrupt handler.

    This code is meant to be placed at the reset vector address; in the present

    revision of the project, the bootstrap code would be placed in the

    bootstrap BRAM of the SoC module (see section ~\ref{bootstrap_code}). It

    can be placed in external memory if the SoC memory map and the makefiles are

    altered accordingly.

    The reset code initializes both I-Cache and D-Cache and jumps to symbol

    \texttt{'entry'} with the CPU in kernel mode and interrupts disabled.

    The interrupt code is somewhat more elaborate but nevertheless is still

    a stub. The interrupt code will find out the cause of the interrupt and will

    proceed.

    Table ~\ref{tab_irq_handling} shows interrupt sources recognized in the

    current version, and how the interrupt code deals with them.

    \begin{table}[h]

    \caption{Interrupt handling\label{tab_irq_handling}}

    \begin{tabularx}{\textwidth}{ l|X }

    \toprule

    Cause & Processing \\

    \midrule

    SYSCALL instruction             & Return immediately (STUB). \\

    BREAK instruction               & Return immediately (STUB). \\

    Invalid opcode                  & Return immediately (STUB). \\

    Unimplemented MIPS-32 opcode    & Emulate opcode. \\

    \bottomrule

    \end{tabularx}

    \end{table}

    Please note that the interrupt code does not even \emph{know} there is

    such a thing as a hardware interrupt -- hardware interrupts are not

    implemented yet in the CPU.

    As can be seen, most of the interrupt processing is missing, replaced by

    stubs. Eventually, those stubs will be replaced with calls to C functions

    that will be defined in the supporting libraries. I have yet to work out

    exactly how to do it without reinventing the wheel.

    The only interrupt processing that is performed (even if only partially) is

    the emulation of \emph{some} MIPS-32 opcodes.

\subsection{MIPS-32 Opcode Emulation}

\label{mips32_opcode_emulation}

    I have found out that most MIPS toolchains target the MIPS-32 architecture

    and can only be made to work with the MIPS-I architecture with some

    difficulty. This applies specially to the C support libraries, where

    MIPS-32 opcodes are used occasionally.

    Other reasons, such as the availability of MIPS-32 ports of

    uClinux, make at least partial compatibility to MIPS-32 very desirable.

    On the other hand, extending the core to implement the full MIPS-32 specs (as

    opposed to the far simpler MIPS-I) might not be possible without running

    into a patent minefield -- I may be wrong in this.

    Therefore, I have chosen to just emulate whatever subset of the

    MIPS-32 ISA is enough to overcome the above obstacles. I have run some

    experiments with uClinux and have found out that only a few MIPS-32 opcodes

    need to be emulated -- see table ~\ref{tab_emulated_opcodes}.

    \begin{table}[h]

    \caption{Emulated MIPS-32 opcodes\label{tab_emulated_opcodes}}

    \begin{tabularx}{\textwidth}{ l|X }

    \toprule

    Opcode & Emulation \\

    \midrule

    EXT                 & Fully emulated. \\

    INS                 & Fully emulated. \\

    CLO                 & Fully emulated. \\

    CLZ                 & Fully emulated. \\

    \midrule

    MUL (3-reg version) & To Be Done. \\

    LWL                 & To Be Done. \\

    LWR                 & To Be Done. \\

    SWL                 & To Be Done. \\

    SWR                 & To Be Done. \\

    \bottomrule

    \end{tabularx}

    \end{table}

    Opcode emulation is implemented in file \emph{/src/common/opcode\_emu.s}.

    The emulation code has been tested (code sample \emph{'opcodes'}) but is

    still unfinished: not only are there opcodes to be emulated, as can

    be seen in table ~\ref{tab_emulated_opcodes}, but the emulation does NOT

    work when the MIPS-32 opcode is in a delay slot; or more precisely, the

    jump instruction of the delay slot is not emulated as it should -- this is

    just work to be done, nothing specially difficult.

    If the trapped MIPS-32 opcode is not one of the emulated opcodes, it is

    ignored exactly as if it was a NOP. A flag is raised in a special, reserved

    area of the BSS segment -- see the source for details. Eventually the trap

    handling will be complete and unimplemented MIPS-32 opcodes will be dealt

    with as undefined opcodes.

    Note that opcode emulation can be disabled in the makefiles, by defining

    symbol \texttt{NO\_EMU\_MIPS32} when assembling \emph{bootstrap.s}.

\subsection{C Startup Code}

\label{c_startup_code}

    File \emph{'/src/common/c\_startup.s'} contains the C startup code used

    in all C code samples.

    This startup code does what's usual in these cases, namely:

    \begin{enumerate}

    \item Initialize the stack at the end of the bss area.

    \item Clear the bss area.

    \item Move the data section from FLASH to RAM (if applicable).

    \item Call main().

    \item Freeze in endless loop after main() returns, if it does.

    \end{enumerate}

    See the makefile of any of the C code samples for examples on how to

    assemble, configure and link the startup code.

\subsection{C Support Library Replacement}

\label{libsoc}

    The core will eventually be tested with one of the regular, free libc

    replacement libraries available. It isn't yet because building those

    libraries for a MIPS-I target (i.e. with no MIPS-32 stuff mixed in) has

    turned out to be much more difficult than I had anticipated.

    In order to be able to use the C toolchain and provide some code samples in

    C, I have built a minimalistic libc replacement called 'libsoc'. The

    source code can be found in \emph{/src/common/libsoc/src}.

    This mini-libc provides only those C support functions I have found

    necessary so far; it will be extended with new functionality as I add more

    code samples, until I can finally use some real C library.

    Apart from a number of utility functions that the C runtime needs, libsoc

    provides the following:

    \begin{itemize}

    \item Floating point support (SW, float and double).

    \item \texttt{putchar} and \texttt{getchar} using the SoC UART.

    \item Replacement for the built-in \texttt{printf} provided by gcc.

    \end{itemize}

    That's it. Yet, even this little is enough to run the Adventure demo...

    All the source code has been lifted from the original Plasma supporting code

    or has been scavenged from the net -- see credits in the file headers.