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://opencores.org/project,sd_card_controller              %%%%
%%%%                                                              %%%%
%%%% 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 the simulation just change to the \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 errors 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 passed. 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 end with \path{_.sv}. Other simulation targets are:
    \begin{description}
    \item[\texttt{clean}] - remove all simulation output files,
    \item[\texttt{print\_testbenches}] - lists all available testbenches,
    \item[\texttt{modelsim}] - compiles all sources and launches modelsim (see \ref{sec:sim_make_var}),
    \item[\texttt{*\_tb}] - compiles and executes the 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 the simulation via command-line, launches modelsim.
    \end{description}
 
    \subsubsection{Simulation makefile environment variables}
    \label{sec:sim_make_var}
 
    The simulation makefile uses a couple of environment variables to setup the 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}
    The example project consists of all Verilog sources from the \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 a .sof file in the \path{syn/quartus/run} directory. Other synthesis targets are:
    \begin{description}
    \item[\texttt{clean}] - remove all synthesis output files,
    \item[\texttt{print\_config}] - prints project configuration of FPGA device,
    \item[\texttt{project}] - creates Quartus project files (.qpf and .qsf),
    \item[\texttt{quartus}] - creates Quartus project files and launches the Quartus IDE.
    \end{description}
 
    \subsubsection{Synthesis makefile environment variables}
    \label{sec:syn_make_var}
 
    The synthesis makefile uses a 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}