Subversion Repositories ion

\chapter{Logic Simulation}
\label{logic_simulation}
 
    The project has been simulated using Modelsim 6.3g. The test bench
    uses some features not present in earlier versions (namely library Signal 
    Spy) so if you use some other simulator or some earlier version of Modelsim, 
    see section on Modelsim dependencies (\ref{modelsim_dependencies}) below.\\
 
    In short, the simulation test bench is meant to run any of the code samples
    provided in directory /src, under a controlled environment, while logging
    the cpu state to a text log file.\\
 
    This log file can then be compared to a log file generated by a software
    simulator for the same code sample (see section 5.1). The software
    simulator is the 'golden model' against which the cpu is tested, so any
    difference between both log files means trouble.\\
 
    This method is far easier than building a fully automated test bench, and
    much more convenient and reliable than a visual inspection of the simulation
    state.\\
 
    In addition to the main log file, there is a console log file to which all 
    data written to the UART is logged (see section~\ref{uart_logging}).\\
 
    There are a few simulation test bench templates in the /src directory, which 
    are used by all the code samples.\\
    The only ones actually used are '/src/code\_rom\_template.vhdl' and 
    '/src/sim\_params\_template.vhdl'. The others
    are remnants of previous versions that will be removed ASAP.\\
 
    The template in file '/src/code\_rom\_template.vhdl' is filled with object
    code meant to be run from internal FPGA BRAM. This is how we load bootstrap
    code into our FPGA. The resulting file is '/vhdl/demo/code\_rom\_pkg.vhdl'
    and is used by both the simulation test bench and the synthesizable MCU.\\
 
    The template in file '/src/sim\_params\_template.vhdl' is filled with 
    simulation parameters (such as the simulation length, etc.) and the resulting 
    file is written as '/vhdl/tb/sim\_params\_pkg.vhdl'. This file is only used
    by the simulation test bench.
 
    All of this template filling is done by a python script (/src/bin2hdl.py) 
    which is invoked from the makefiles and explained in section xxx.\\
 
    Note that all code samples share the same vhdl files: you need to run the 
    makefile target 'sim' for the sample you want to simulate; that will 
    overwrite the two files mentioned above. So there's no vhdl file that is
    specific to a particular code sample.\\
 
    The actual test bench entity is at '/vhdl/tb/mips\_tb.vhdl' and is shared 
    by all the code samples.\\
 
    While the test benches and sample code are good enough to catch MOST errors
    in the full system (i.e. cache included) they don't help with diagnostic;
    once you know there's an error, and the approximate address where it's
    triggered (approximate because of the cache) you have to dig into the 
    simulation waveforms to find it. It's easier than it seems.\\
 
\section{Running the Simulation}
\label{running_the_simulation}
 
    A simulation script can be found at '/sim/mips\_tb.do'. This script will
    simulate the test bench entity in file '/vhdl/tb/mips\_tb.vhdl'.\\
 
    All the code samples are run with the same script.\\
 
    The test bench files mentioned in the previous section are automatically 
    generated for each of the sample programs. This is automatically done by the 
    sample code makefile,
    assuming you have a MIPS cross-toolchain in your computer (see section~\ref{code_samples}).\\
 
    For convenience, a pre-generated mips\_tb.vhdl is included so you can launch
    a simulation without having to install toolchains, etc. The code is that
    of the 'hello world' sample.\\
 
    I guess that if you are interested in this sort of stuff then you probably
    know more about Modelsim than I do. Yet, here's a step-by-step guide to
    simulating the 'hello world' sample:
 
\begin{enumerate}
    \item Run 'make hello\_sim' from directory '/src/hello'.
        This will compile the program sources, build the necessary binary object
        files and then create the two package files mentioned above.\\
        Read the makefile and comments in the python script '/src/bin2hdl.py'
        for details.\\
 
        ALTERNATIVELY, if you don't have a toolchain you can just skip this
        step and use the default vhdl files provided, which are those of the
        'hello world' sample.\\
 
    \item Within Modelsim, change directory to /syn. Modelsim will create its 
        stuff in this directory. This includes the
        log file, which by default will be '/syn/hw\_sim\_log.txt', and the 
        console log file '/syn/hw\_sim\_console.log'.\\
        (You could use any other directory, this is just a convenient place to
        put modelsim data out of the way. Just remember where the log files
        are.).
 
    \item Run script '/sim/mips\_tb.do' (menu tools-\textgreater tcl-\textgreater execute macro)
        The simulation will run to completion and print a message in Modelsim's 
        transcript window when it's done. You can open the console log file 
        to see the program output, in this case the 'Hello world' message.\\
 
\end{enumerate}
 
    The test bench terminates the simulation when:
 
\begin{enumerate}
 
    \item It detects two consecutive code fetches from the same address.
    \item The simulation timeout is reached.
 
\end{enumerate}
 
    Condition 1 is meant to detect single-instruction loops such as those
    commonly found after the invocation of the main() function in a C program. 
    This is a convenient way for the software to signal its termination.\\
 
    The timeout is one of the simulation parameters which is defined in
    the makefiles. It is arbitrarily fixed for each sample by trial and error 
    so that the program has time to execute. Change them if necessary.\\
 
\section{Simulation File Logging}
\label{sim_logging}
 
    The simulation test bench will log any of the following events:
 
    \begin{itemize}
    \item Changes in the register bank.
    \item Changes in registers HI and LO (implemented even if mul/div is not).
    \item Changes in registers EPC and SR.
    \item Data loads (any resulting register change is logged separately).
    \item Data stores.
    \end{itemize}
 
    Note that changes in other internal registers, including PC, are not logged.
    This means that for example a long chain of NOPs, or MOVEs that don't change
    register values, will not be seen in the log file. This is on purpose.\\
 
    Events are logged with the address of the instruction that triggered 
    the change. This holds true even for load instructions.\\
    Early versions of the project logged the address of the 
    preceding instruction -- it was confusing and I have fixed it.\\
 
    The simulation log file is stored by default in modelsim's working directory
    (see above). I don't provide any automated script to do the comparison, you
    should use whatever diff tool you like best.\\
 
\section{Log File Format}
\label{log_file_format}
 
    There is a text line for each of the following events:
 
    \begin{itemize}
    \item Register change
 
        "(pc) [reg\_num]=value"\\
 
        Where:
 
        \begin{tabular}{ l l }
            pc       & =\textgreater PC value (8-digit hex)\\
            reg\_num & =\textgreater Register index (2-digit hex), or any of {LO,HI,EP}\\
            value    & =\textgreater New register value (8-digit hex)\\
        \end{tabular}\\
 
 
    \item Write cycle (store)
 
        "(pc) [address] |mask|=value WR"\\
 
        Where:
 
        \begin{tabular}{ l l }
        pc      & =\textgreater PC value (8-digit hex)\\
        address & =\textgreater Write address\\
        mask    & =\textgreater Byte-enable mask (2-digit hex)\\
        value   & =\textgreater Write data\\
        \end{tabular}\\
 
        The PC value is the address of the instruction that caused the logged
        change, NOT the actual value of the PC at the time of the change. 
        This is so to make the hardware logger's life easier -- the SW simulator
        and the real HW don't work exactly the same when the cache starts 
        stalling the cpu (which the SW does not simulate) and the best reference
        point for all instructions is their own adddress.
 
        The mask will have a '1' at bits 3..0 for each byte write-enabled. MSB
        is bit 3, LSB is bit 0. Note that the data is big endian, so the MSB
        is actually the LOWER address. The upper nibble of the mask is always 0.
 
        The value will match the behavior of the ion cpu; the significant
        byte(s) will have the actual write data and the other bytes will not
        be relevant but will behave exactly as the real hardware (so that the
        logs are directly comparable).
 
        The WR at the end of the line is for visual reference only.
 
    \item Read cycle (load)
 
        "(pc) [address] \textless ** \textgreater =value RD"\\
 
        Where:
 
        \begin{tabular}{ l l }
        pc      & =\textgreater PC value (8-digit hex)\\
        address & =\textgreater Read address\\
        \textless ** \textgreater    & =\textgreater Padding (ignore)\\
        value   & =\textgreater Read data\\
        \end{tabular}\\
 
        Note that in the real machine, the data is read into the cpu one cycle
        after the address bus is output (because the memory is synchronous) so
        that the full read cycle spans 2 clock cycles (when proper interlocking
        is implemented, the load will overlap the next instruction; right now
        it just stalls the pipeline for 1 cycle). This is simplified in the log
        files for readability.
 
        Note that the size of the read (LH/LB/LW) instruction is not recorded:
        the CPU always reads 32-bit words.
 
        The RD at the end of the line is for visual reference only.
 
    \end{itemize}
 
 
    For example, these are lines 1153-1162 of the simulation log for the
    default 'hello world' test program:
 
                \begin{verbatim}
                ...
                (BFC009AC) [05]=20000000
                (BFC009B0) [20000020] <**>=00000003 RD
                (BFC009B0) [03]=00000003
                (BFC009B8) [03]=00000002
                (BFC009C0) [03]=20000000
                (BFC009C4) [20000000] |0F|=00000070 WR
                (BFC00E74) [12]=00000004
                (BFC00E78) [10]=BFC01048
                (BFC00E7C) [BFC01048] <**>=00000069 RD
                (BFC00E7C) [05]=00000069
                ...
                \end{verbatim}\\
 
    (NOTE: this example taken from revision 176, yours may vary)\\
 
    The read cycle at pc=0xbfc009b0 modifies register 0x03; that's why there 
    are two lines with the same pc value.\\
 
    The code that produced that log is this (from hello.lst):
 
                \begin{verbatim}
                ...
                bfc009ac:    3c052000     lui   a1,0x2000
                bfc009b0:    8ca30020     lw    v1,32(a1)
                bfc009b4:    00000000     nop
                bfc009b8:    30630002     andi  v1,v1,0x2
                bfc009bc:    1060fffc     beqz  v1,0xbfc009b0
                bfc009c0:    3c032000     lui   v1,0x2000
                bfc009c4:    ac620000     sw    v0,0(v1)
                bfc009c8:    03e00008     jr    ra
                bfc009cc:    00000000     nop
                ...
                bfc00e74:    26520001     addiu  s2,s2,1
                bfc00e78:    26100001     addiu  s0,s0,1
                bfc00e7c:    92050000     lbu    a1,0(s0)
                bfc00e80:    00000000     nop
                ...
                \end{verbatim}\\
 
    (Remember the register numbers: \$v0=0x02, \$v1=0x03, \$a1=0x05, \$s0=0x10, 
    \$s2=0x12)\\
 
    Note that, unlike previous versions of this project, all changes are logged
    with the address of the instruction that caused them.\\
 
    The log file format is hardcoded into vhdl package mips\_sim\_pkg
    and the software simulator C source that implement it. It will
    be probably modified as the project moves on so it is best if you verify
    all of this yourself with the project version you intend to use before 
    using this information.\\
 
    Note that the software simulation log and the modelsim log need not be the
    same size even if both CPUs behave identically; the one that spans a longer 
    simulated time will be longer.\\
    The point is that both need to be identical up to the last line of the
    shortest file.\\
 
\section{Console Output Logging}
\label{uart_logging}
 
    Every byte written to the UART TX register is logged (in ascii) to a text
    file which by default is '/syn/hw\_sim\_console.log'. Apart from the
    automatic insertion of a CR after every LF, the data is logged verbatim.\\
 
    Though the UART is included in the test bench, the actual UART operation is 
    bypassed: The test bench forces the 'tx ready' high so that the CPU never has
    to wait for a character to be transmitted. This is a simplification that 
    saves me the trouble to do a cycle-accurate simulation of the UART in the 
    software simulator.\\
 
    The UART input is not simulated at all, for simplicity. So, for example, the
    Adventure sample, which does read the console input, can't be properly 
    simulated past the first console input -- there is plenty of code to 
    simulate before that so this is no problem for the moment.\\
 
 
\section{Use of Modelsim Features}
\label{modelsim_dependencies}
 
    Apart from the format of the simulation scripts, which would be easy to port
    to any other simulation tool, the simulation test bench uses a feature of
    Modelsim 6.3 that is not even present in earlier versions -- SignalSpy.\\
 
    The test bench uses SignalSpy to examine internal cpu signals from the top
    entity, including the whole register bank. There is no other way to examine
    those signals in vhdl, unless you want to add them to the module interface.\\
 
    The test bench needs to access those signals in order to detect changes in
    the internal cpu state that should be logged. That is, it really needs to
    look at those signals if it is to be of any use.\\
 
    If you are using any other simulation tool, look for an alternative method
    to get those internal signals or just add them to the core interface. I
    would suggest adding a debug port of type record to mips\_cpu -- and hope the
    synthesis tool does not choke on it. Adding individual debug ports would be
    a PITA.\\
    I guess this is why Mentor people took the trouble to write SygnalSpy.\\
 
    I plan to move to Symphony EDA eventually, so I'll have to fix this.\\
 
    Using GHDL would be an option, except because it only supports vhdl. The
    project will use a SDRAM model in verilog for which I could not find a
    vhdl replacement. If the project is to be ported to GHDL (a very desirable 
    goal even if only because not everybody has access to Modelsim) this will 
    have to be worked around.\\