Subversion Repositories sd_card_controller

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%                                                              %%%%

%%%% WISHBONE SD Card Controller IP Core                          %%%%

%%%%                                                              %%%%

%%%% usage.tex                                                    %%%%

%%%%                                                              %%%%

%%%% This file is part of the WISHBONE SD Card                    %%%%

%%%% Controller IP Core project                                   %%%%

%%%% http://www.opencores.org/cores/xxx/                          %%%%

%%%%                                                              %%%%

%%%% Description                                                  %%%%

%%%% documentation 'Usage' chapter                                %%%%

%%%%                                                              %%%%

%%%% Author(s):                                                   %%%%

%%%%     - Marek Czerski, ma.czerski@gmail.com                    %%%%

%%%%                                                              %%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%                                                              %%%%

%%%% Copyright (C) 2013 Authors                                   %%%%

%%%%                                                              %%%%

%%%% This source file may be used and distributed without         %%%%

%%%% restriction provided that this copyright statement is not    %%%%

%%%% removed from the file and that any derivative work contains  %%%%

%%%% the original copyright notice and the associated disclaimer. %%%%

%%%%                                                              %%%%

%%%% This source file is free software; you can redistribute it   %%%%

%%%% and/or modify it under the terms of the GNU Lesser General   %%%%

%%%% Public License as published by the Free Software Foundation; %%%%

%%%% either version 2.1 of the License, or (at your option) any   %%%%

%%%% later version.                                               %%%%

%%%%                                                              %%%%

%%%% This source is distributed in the hope that it will be       %%%%

%%%% useful, but WITHOUT ANY WARRANTY; without even the implied   %%%%

%%%% warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR      %%%%

%%%% PURPOSE. See the GNU Lesser General Public License for more  %%%%

%%%% details.                                                     %%%%

%%%%                                                              %%%%

%%%% You should have received a copy of the GNU Lesser General    %%%%

%%%% Public License along with this source; if not, download it   %%%%

%%%% from http://www.opencores.org/lgpl.shtml                     %%%%

%%%%                                                              %%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Usage}

\label{chap:usage}

    This chapter describes usage of the IP core.

    \subsection{Directory structure}

    \label{sec:dir_struct}

    \textit{Wishbone SD Card Controller IP Core} comes with following directory structure:

    \dirtree{%

        .1 ..

        .2 bench.

        .3 verilog.

        .2 doc.

        .3 references.

        .3 src.

        .2 rtl.

        .3 verilog.

        .2 sim.

        .3 rtl\_sim.

        .4 bin.

        .4 log.

        .4 run.

        .2 sw.

        .3 example.

        .2 syn.

        .3 quartus.

        .4 bin.

        .4 run.

        .4 src.

    }

    \begin{description}

    \item[\texttt{bench/verilog}] - verilog testbench sources,

    \item[\texttt{doc}] - documentation files,

    \item[\texttt{doc/src}] - documentation \LaTeX sources,

    \item[\texttt{rtl/verilog}] - ip core verilog sources,

    \item[\texttt{sim/rtl\_sim/bin}] - simulation makefile and modelsim scripts,

    \item[\texttt{sim/rtl\_sim/log}] - log files created during simulation,

    \item[\texttt{sim/rtl\_sim/run}] - simulation execution directory,

    \item[\texttt{sw/example}] - baremetal example application for or1k,

    \item[\texttt{syn/quartus/bin}] - synthesis makefile and scripts for quartus example project,

    \item[\texttt{syn/quartus/run}] - synthesis execution directory,

    \item[\texttt{syn/quartus/src}] - example project sources.

    \end{description}

    \subsection{Simulation}

    \label{sec:simulation}

    To start simulation just enter to \path{sim/rtl_sim/run} directory and type \texttt{make}:

    \begin{verbatim}

#> cd sim/rtl_sim/run

#> make

    \end{verbatim}

    Every testbench is written in SystemVerilog (mostly due to use of \texttt{assert} keyword). Every testbench is self checking. Test error are represented by

    assert failures. Every testbench starts by displaying:

    \begin{verbatim}

# testbench_name start ...

    \end{verbatim}

    and ends by displaying:

    \begin{verbatim}

# testbench_name finish ...

    \end{verbatim}

    If no asserts are displayed between these lines, the test passes. Below is an example of passing test:

    \begin{verbatim}

...

some compilation output

...

# sd_cmd_master_tb start ...

# sd_cmd_master_tb finish ...

# ** Note: $finish    : ../../../bench/verilog/sd_cmd_master_tb.sv(385)

#    Time: 3620 ps  Iteration: 0  Instance: /sd_cmd_master_tb

    \end{verbatim}

    Below is an example of failing test:

    \begin{verbatim}

...

some compilation output

...

# sd_cmd_master_tb start ...

# ** Error: Assertion error.

#    Time: 3280 ps  Scope: sd_cmd_master_tb File: ../../../bench/verilog/

                                                    sd_cmd_master_tb.sv Line: 376

# sd_cmd_master_tb finish ...

# ** Note: $finish    : ../../../bench/verilog/sd_cmd_master_tb.sv(385)

#    Time: 3620 ps  Iteration: 0  Instance: /sd_cmd_master_tb

    \end{verbatim}

    \subsubsection{Simulation makefile targets}

    \label{sec:sim_make_targ}

    The default simulation target is to run all testbenches from \path{bench/verilog} directory that ends with \path{_.sv}. Other simulation targets are:

    \begin{description}

    \item[\texttt{clean}] - remove all simulation output files,

    \item[\texttt{print\_testbenches}] - lists all availible testbenches,

    \item[\texttt{modelsim}] - compiles all sources and launches modelsim (see \ref{sec:sim_make_var}),

    \item[\texttt{*\_tb}] - compiles and executes given testbench. All items listed by the \path{print_testbenches} target can be executed this way,

    \item[\texttt{*\_tb\_gui}] - same as \path{*_tb} target, only instead of executing simulation in command-line, launches modelsim.

    \end{description}

    \subsubsection{Simulation makefile environment variables}

    \label{sec:sim_make_var}

    Simulation makefile uses couple of environment variables to setup simulation:

    \begin{description}

    \item[\texttt{MODELSIM\_DIR}] - modelsim installation directory (\path{\$(MODELSIM_DIR)/bin/vsim} should be a valid path),

    \item[\texttt{VCD}] - when set to 1 - all waveforms are dumped to \path{sim/rtl_sim/out/*.vcd} files; when set to 0 - no waveforms are dumped (0 is default),

    \item[\texttt{V}] - when set to 1 - enables verbose output; when set to 0 - normal simulation output (0 is default).

    \end{description}

    \subsection{Synthesis}

    \label{sec:synthesis}

    For the purpose of synthesis verification there is an example FPGA project made for Altera Quartus.

    To start synthesis just enter to \path{syn/quartus/run} directory and type \texttt{make}:

    \begin{verbatim}

#> cd syn/quartus/run

#> make

    \end{verbatim}

    Example project consist of all verilog sources from \path{rtl/verilog} directory and \path{syn/quartus/src/sdc_controller_top.v} source file.

    The purpose of the additional verilog file is to instantiate the \textit{Wishbone SD Card Controller IP Core} and register all inputs/outputs to/from the core.

    This makes timing verification more accurate.

    \subsubsection{Synthesis makefile targets}

    \label{sec:syn_make_targ}

    The default synthesis target is to synthesize the project and create .sof file in \path{syn/quartus/run} directory. Other synthesis targets are:

    \begin{description}

    \item[\texttt{clean}] - remove all synthesis output files,

    \item[\texttt{print\_config}] - prints projects configuration of FPGA device,

    \item[\texttt{project}] - creates quartus project files (.qpf and .qsf),

    \item[\texttt{quartus}] - creates quartus project files and launches quartus IDE.

    \end{description}

    \subsubsection{Synthesis makefile environment variables}

    \label{sec:syn_make_var}

    Synthesis makefile uses couple of environment variables to setup synthesis:

    \begin{description}

    \item[\texttt{QUARTUS\_DIR}] - quartus installation directory (\path{\$(QUARTUS_DIR)/bin/quartus} should be a valid path),

    \item[\texttt{FPGA\_FAMILY}] - name of the FPGA device family,

    \item[\texttt{FPGA\_PART}] - name of the FPGA device,

    \item[\texttt{V}] - when set to 1 - enables verbose output; when set to 0 - normal simulation output (0 is default).

    \end{description}