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.\\