Subversion Repositories ion

\chapter{Tools}

\label{tools}

    Directory '/tools' of the project includes a few tools -- small C or Python

    programs purpose-built for this project.

    What follows is a brief description of each of the tools. This document

    won't go into the implementation or usage details. The tools themselves have

    brief usage instructions and for any further details the user must read

    the source code.

\section{MIPS Software Simulator}

\label{sw_simulator}

    Plasma project includes a MIPS-I simulator made by Steve Rhoads, called

    'mlite.c'. According the the author, it was used as a golden model for the

    construction of the cpu, the same as I have done.\\

    I have made some modifications on Rhoads' code, mostly for logging, and

    called the new program 'slite' ('/tools/slite/src/slite.c').\\

    The most salient features are:

    \begin{itemize}

    \item Logs CPU state to a text file.

        The format is identical to that of the vhdl test bench log.

        You can select the code address that triggers the logging.

    \item Echoes CPU UART output to the host console or to a log file.

    \item Can be run in interactive mode (like a monitor).\\

        Step by step execution, breakpoints, that kind of thing.

    \item Can be run in batch (unattended) mode.\\

        So that you can easily run a program to compare logs with the

        vhdl test bench.

    \item Does not simulate the cache at all.

    \end{itemize}

    Each code sample includes a DOS batch file named 'swsim.bat' that runs the

    simulator in batch mode. Note that the BAT file invokes a windows binary

    which is included in the SVN repository and should be immediately useable

    after checkout.\\

    The program includes usage help (a short description of the command line

    parameters). The source code (very simple and straighforward) is included in

    the project. The BAT files provide an usage example. And anyone who is

    interested and finds trouble can always contact me.

    For all these reasons I think it is not necessary to explain the simulator

    in detail. Nothing to do with laziness, as you can see.\\

    Many system parameters are hardcoded, including the log file name, the

    simulated memory sizes and the code and data addresses.\\

    The hardcoded log file name is "sw\_sim\_log.txt" and it is generated in the

    same directory from which the simulator is run.\\

\section{Configuration Package Builder Script build\_pkg.py}

\label{python_script}

    This tools is used to build a simulation and synthesis configuration

    package.

    The generated package contains configuration constants used by the

    simulation test bench \emph{'mips\_tb.vhdl'} and by the hardware demo

    \emph{'c2sb\_demo.vhdl'}.

    It too includes memory initialization constants containing object code,

    used to initialize simulated and inferred memories, both in simulation

    and in synthesis.

    In the code samples, this script is used to generate two separate packages

    for simulation and synthesis. Please refer to the makefiles for detailed

    usage examples.

\section{Conversion Script bin2hdl.py}

\label{python_script}

    \begin{figure*}[ht]

    \begin{center}

    {\small

    \framebox[7in]{

    \begin{minipage}[t]{6.0in}

    NOTE: This script was used in previous versions of the project -- it came

    in handy to initialize byte-sliced memories when the caches were under

    development.

    It has been abandoned because it was far too complicated and no longer

    necessary. The VHDL

    templates it refers to and the script itself have been moved from the /src

    directory to their own subdirectory in /tools.

    It is being retained in case it becomes useful again but it is no longer

    used.

    \end{minipage}

    }

    }

    \end{center}

    \label{lb}

    \end{figure*}

    This Python script reads one or more binary files and 'inserts' them in a

    vhdl template. It makes the

    conversion from binary to vhdl strings and slices the data in byte columns,

    as required by the RAM implementation (in which each byte in a word is

    stored in a different RAM with a separate WE, 4 blocks in all).\\

    The 3 binary files the script can read are the object code image, the

    data image (initialized data sections) and a FLASH image.

    The script inserts a number of simulation parameters in the template file,

    as illustrated by the makefiles.\\

    The makefiles of the code samples can be used as an example. The script code

    is a bit convoluted but it is understandable if you do know Python,

    and includes some usage instructions.\\

    The vhdl templates (/src/*\_template.vhdl) have placeholder 'tags' that are

    replaced with real application data by this script.

    Some of the tags are these:

    \begin{tabular}{ l l }

    "@code0@"             & : Contents of RAM block for slice 0 (lsb) of code\\

       ...\\

    "@code3@"             & : Contents of RAM block for slice 3 (msb) of code\\

    "@code31@"            & : Contents of RAM block for slices 3 \& 1 (odd) of code\\

    "@code20@"            & : Contents of RAM block for slices 2 \& 0 (odd) of code\\

    "@data0@"             & : Contents of RAM block for slice 0 (lsb) of data\\

       ...\\

    "@data3@"             & : Contents of RAM block for slice 3 (msb) of data\\

    "@data31@"            & : Contents of RAM block for slices 3 \& 1 (odd) of data\\

    "@data20@"            & : Contents of RAM block for slices 2 \& 0 (odd) of data\\

    "@flash@"             & : Contents of simulated FLASH\\

    "@data-32bit@"        & : Contents of 32-bit-wide RAM block of data\\

    "@entity\_name@"      & : Name of entity in target vhdl file\\

    "@arch\_name@"        & : Name of architecture in target vhdl file\\

    "@code\_table\_size@" & : Size of RAM block to be used for code, in words\\

    "@code\_addr\_size@"  & : ceil(log2(@code\_table\_size@))\\

    "@data\_table\_size@" & : Size of RAM block to be used for data, in words\\

    "@data\_addr\_size@"  & : ceil(log2(@data\_table\_size@))\\

    \end{tabular}\\

    There's a few more tags; they are described in the script source and the

    usage help.\\

    These placeholders will be replaced with object code or with data values

    provided by the script command line (see makefiles).\\

    The script has been used with Python 2.6.2. It should work with earlier

    or later versions but I haven't tested.\\

    Note: all of the above info is in the script itself, and can be shown

    with command line option --h. Since it will be more up to date than this

    doc, you're advised to read the script.\\