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.