Subversion Repositories ion

\chapter{Hardware Demo}

\label{hw_demo}

\section{Pre-generated demo}

\label{pregenerated_demo}

    The project includes a few synthesizable code samples, including a

    'Hello world' demo and a memory tester. Only the 'hello' demo is included

    in pre-generated form, the others have to be built using the included

    makefiles -- assuming you have a mips toolchain.\\

    'Pre-generated' in this context means that all the vhdl files necessary for

    building the demo are already included with the project, and the only

    tool needed is the synthesis tool.

    The pregenerated demo is included just for convenience, so that you can

    launch some small application on hardware without installing a C toolchain.\\

    A constraints file is provided ('/vhdl/demo/c2sb\_demo.csv') which includes

    all the pin constraints for the default target board, in CSV format. This

    constraints file is shared by all demos targeted to the DE-1 board.\\

    The default target board is TerasIC's DE-1, with a Cyclone-II FPGA

    (EP2C20F484C7). This is the only hardware platform the core has been

    tested in, so far.\\

    I have used the free Altera IDE (Altera Quartus II 9.0). This version of

    Quartus does not even require a free license file and can be downloaded for

    free from the altera web site. But if you have a DE-1 board on hand I guess

    you already know that.\\

    I assume you are familiar with Altera tools but anyway this is how to set up

    a project using Quartus II:

    \begin{enumerate}

        \item Create new project with the new project wizard.

            Top entity should be c2sb\_demo.

            Suggested path is /syn/altera/(project name).

        \item Set target device as EP2C20F484C7.

            This choice tells the synth tool what speed grade and chip package

            we'll be targetting.

        \item 'Next' your way out of the new project wizard.

        \item Add to the project all the vhdl files in /vhdl and /vhdl/demo,

              except mips\_cache\_stub.vhdl and sdram\_controller.vhdl.

        \item Select file c2sb\_demo.vhdl as top.

        \item Import pin constraints file (assignments-\textgreater import assignments).

        \item Create a clock constraint for signal clk (51 MHz or some other

            suitable speed which gives us some minimal slack).

        \item In the device settings window, click "Device and pin options...".

        \item Select tab "Dual-Purpose pins".

        \item Double-click on nCEO value column and select "use as regular I/O".

            IMPORTANT: otherwise the synthesis will fail; we need to use a FPGA

            pin that happens to be dual-purpose (programming and regular).

        \item Select 'balanced' optimization.

        \item Save the project and synthesize.

        \item Make sure the clock constraint is met (timing analyzer report).

            There is a random element to the synthesis process, as you know,

            but the core as shipped should pass the constraint.

        \item Program the FPGA from Quartus-2

        \item If you have a terminal hooked to the serial port (19200/8/N/1) you

            should see a welcome message after depressing the reset button.

            (by default this is pusbutton 2).

    \end{enumerate}

    In the present version, the synthesis will produce a lot of warnings. The

    ugliest are about unused pins and an undeclared clock line. None of them

    should be really scary.\\

    Note that none of the on-board goodies are used in the demo except as noted

    in section ~\ref{porting_hw_demo} below.\\

    In order to generate the demos (not using the pre-generated file) you

    have to use the makefiles provided with the code samples. Please see

    the sample readme files and the makefiles for details. In short, provided

    you have a MIPS toolchain installed and Python 2.5+, all you have to do

    is run make (which will automatically build all the vhdl files where they

    need to be, etc.) and run the synthesis.\\

\section{Porting to other dev boards}

\label{porting_hw_demo}

    I will only deal here with the 'hello' demo, the process is the same

    for all other samples that don't involve external FLASH.\\

    The 'hello' demo should be easily portable to any board which has all of

    this:

    \begin{itemize}

    \item An FPGA capable enough (the demo uses internal memory for code)

    \item At least 4KB of 16-bit wide external, asynchronous, old-fashioned SRAM

    \item A reset pin (possibly a pushbutton)

    \item A clock input (uart modules assume 50MHz, see below)

    \item RXD and TXD UART pins, plus a connector, header or whatever

    \end{itemize}

    The only modules that care at all about clock rate are the UART

    modules. They are hardwired to 19200 bauds when clocked at 50MHz, so if you

    use a different frequency you must edit the generics in the demo entity

    accordingly.\\

    Be aware that these uart modules have been used a lot in other projects but

    have not been tested with a wide range of clock rates; they should work but

    you have been warned.\\

    Though there is no reset control logic, the reset input is synchronized

    internally, so you can use a raw pushbutton -- you may trigger multiple

    resets if your pushbutton isn't tight but you'll never cause metastability

    trouble.\\

    Assuming you take care of all of the above, the easiest way I see to port

    the demo is just editing the top module ports ('/vhdl/demo/c2sb\_demo.vhdl')

    to match your board setup.\\

    All the code in this project is vendor agnostic (or should be, I have only

    tried it on Quartus and ISE). Specifically, it does not instantiate memory

    blocks (relying instead on memory inference) or clock managers or buffers.

    This has its drawbacks but is an stated goal of the project -- in the long

    run it pays, I think, and it certainly makes the porting easier.\\

\section{'Adventure' demo}

\label{adventure}

    There is another demo targeting the same hardware as the 'hello' demo above:

    a port of 'Adventure'. The C source (included) has been slightly modified

    to not use any library functions nor any filesystem (instead uses a built-in

    constant string table).\\

    Build steps are the same as for the hello demo (the make target is 'demo').\\

    Since the binary executable is too large to fit internal BRAM, it has to be

    executed from the DE-1 onboard flash. You need to write file 'adventure.bin'

    to the start of the FLASH using the 'Control Panel' tool that came with your

    DE-1 board. That's the only salient difference. That and the amount of SRAM;

    The 512KB present on the DE-1 are enough but I don't remember right now

    what is the minimum, please look at the map file. This should only matter

    if you want to port to another board.\\

    The game will offer you an auto-walkthrough option. Answer 'y' and it will

    play itself for about 250 moves, leaving you at an intermediate stage of

    the game from which you can play on.\\

    Now, admittedly 'Adventure' is no standard benchmark and even running it to

    completion does not guarantee that there are no bugs hidden in the cache or

    any of the opcodes.

    On the other hand, when you get to the \emph{maze of twisty little passages}

    you know you have a computer, finished or not. The 'Adventure' demo is

    great as a confidence builder.\\

    Besides, running Adventure on a computer built by myself is something

    I just wanted to do :)\\