%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%% WISHBONE SD Card Controller IP Core %%%%
|
%%%% WISHBONE SD Card Controller IP Core %%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%% usage.tex %%%%
|
%%%% usage.tex %%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%% This file is part of the WISHBONE SD Card %%%%
|
%%%% This file is part of the WISHBONE SD Card %%%%
|
%%%% Controller IP Core project %%%%
|
%%%% Controller IP Core project %%%%
|
%%%% http://opencores.org/project,sd_card_controller %%%%
|
%%%% http://opencores.org/project,sd_card_controller %%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%% Description %%%%
|
%%%% Description %%%%
|
%%%% documentation 'Usage' chapter %%%%
|
%%%% documentation 'Usage' chapter %%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%% Author(s): %%%%
|
%%%% Author(s): %%%%
|
%%%% - Marek Czerski, ma.czerski@gmail.com %%%%
|
%%%% - Marek Czerski, ma.czerski@gmail.com %%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%% Copyright (C) 2013 Authors %%%%
|
%%%% Copyright (C) 2013 Authors %%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%% This source file may be used and distributed without %%%%
|
%%%% This source file may be used and distributed without %%%%
|
%%%% restriction provided that this copyright statement is not %%%%
|
%%%% restriction provided that this copyright statement is not %%%%
|
%%%% removed from the file and that any derivative work contains %%%%
|
%%%% removed from the file and that any derivative work contains %%%%
|
%%%% the original copyright notice and the associated disclaimer. %%%%
|
%%%% the original copyright notice and the associated disclaimer. %%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%% This source file is free software; you can redistribute it %%%%
|
%%%% This source file is free software; you can redistribute it %%%%
|
%%%% and/or modify it under the terms of the GNU Lesser General %%%%
|
%%%% and/or modify it under the terms of the GNU Lesser General %%%%
|
%%%% Public License as published by the Free Software Foundation; %%%%
|
%%%% Public License as published by the Free Software Foundation; %%%%
|
%%%% either version 2.1 of the License, or (at your option) any %%%%
|
%%%% either version 2.1 of the License, or (at your option) any %%%%
|
%%%% later version. %%%%
|
%%%% later version. %%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%% This source is distributed in the hope that it will be %%%%
|
%%%% This source is distributed in the hope that it will be %%%%
|
%%%% useful, but WITHOUT ANY WARRANTY; without even the implied %%%%
|
%%%% useful, but WITHOUT ANY WARRANTY; without even the implied %%%%
|
%%%% warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR %%%%
|
%%%% warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR %%%%
|
%%%% PURPOSE. See the GNU Lesser General Public License for more %%%%
|
%%%% PURPOSE. See the GNU Lesser General Public License for more %%%%
|
%%%% details. %%%%
|
%%%% details. %%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%% You should have received a copy of the GNU Lesser General %%%%
|
%%%% You should have received a copy of the GNU Lesser General %%%%
|
%%%% Public License along with this source; if not, download it %%%%
|
%%%% Public License along with this source; if not, download it %%%%
|
%%%% from http://www.opencores.org/lgpl.shtml %%%%
|
%%%% from http://www.opencores.org/lgpl.shtml %%%%
|
%%%% %%%%
|
%%%% %%%%
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
\section{Usage}
|
\section{Usage}
|
\label{chap:usage}
|
\label{chap:usage}
|
|
|
This chapter describes usage of the IP core.
|
This chapter describes usage of the IP core.
|
|
|
\subsection{Directory structure}
|
\subsection{Directory structure}
|
\label{sec:dir_struct}
|
\label{sec:dir_struct}
|
|
|
\textit{Wishbone SD Card Controller IP Core} comes with following directory structure:
|
\textit{Wishbone SD Card Controller IP Core} comes with following directory structure:
|
|
|
\dirtree{%
|
\dirtree{%
|
.1 ..
|
.1 ..
|
.2 bench.
|
.2 bench.
|
.3 verilog.
|
.3 verilog.
|
.2 doc.
|
.2 doc.
|
.3 references.
|
.3 references.
|
.3 src.
|
.3 src.
|
.2 rtl.
|
.2 rtl.
|
.3 verilog.
|
.3 verilog.
|
.2 sim.
|
.2 sim.
|
.3 rtl\_sim.
|
.3 rtl\_sim.
|
.4 bin.
|
.4 bin.
|
.4 log.
|
.4 log.
|
.4 run.
|
.4 run.
|
.2 sw.
|
.2 sw.
|
.3 example.
|
.3 example.
|
.2 syn.
|
.2 syn.
|
.3 quartus.
|
.3 quartus.
|
.4 bin.
|
.4 bin.
|
.4 run.
|
.4 run.
|
.4 src.
|
.4 src.
|
}
|
}
|
|
|
\begin{description}
|
\begin{description}
|
\item[\texttt{bench/verilog}] - verilog testbench sources,
|
\item[\texttt{bench/verilog}] - Verilog testbench sources,
|
\item[\texttt{doc}] - documentation files,
|
\item[\texttt{doc}] - documentation files,
|
\item[\texttt{doc/src}] - documentation \LaTeX sources,
|
\item[\texttt{doc/src}] - documentation \LaTeX sources,
|
\item[\texttt{rtl/verilog}] - ip core verilog 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/bin}] - simulation makefile and modelsim scripts,
|
\item[\texttt{sim/rtl\_sim/log}] - log files created during simulation,
|
\item[\texttt{sim/rtl\_sim/log}] - log files created during simulation,
|
\item[\texttt{sim/rtl\_sim/run}] - simulation execution directory,
|
\item[\texttt{sim/rtl\_sim/run}] - simulation execution directory,
|
\item[\texttt{sw/example}] - baremetal example application for or1k,
|
\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/bin}] - synthesis makefile and scripts for Quartus example project,
|
\item[\texttt{syn/quartus/run}] - synthesis execution directory,
|
\item[\texttt{syn/quartus/run}] - synthesis execution directory,
|
\item[\texttt{syn/quartus/src}] - example project sources.
|
\item[\texttt{syn/quartus/src}] - example project sources.
|
\end{description}
|
\end{description}
|
|
|
\subsection{Simulation}
|
\subsection{Simulation}
|
\label{sec:simulation}
|
\label{sec:simulation}
|
|
|
To start simulation just enter to \path{sim/rtl_sim/run} directory and type \texttt{make}:
|
To start the simulation just change to the \path{sim/rtl_sim/run} directory and type \texttt{make}:
|
\begin{verbatim}
|
\begin{verbatim}
|
#> cd sim/rtl_sim/run
|
#> cd sim/rtl_sim/run
|
#> make
|
#> make
|
\end{verbatim}
|
\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
|
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:
|
assert failures. Every testbench starts by displaying:
|
\begin{verbatim}
|
\begin{verbatim}
|
# testbench_name start ...
|
# testbench_name start ...
|
\end{verbatim}
|
\end{verbatim}
|
and ends by displaying:
|
and ends by displaying:
|
\begin{verbatim}
|
\begin{verbatim}
|
# testbench_name finish ...
|
# testbench_name finish ...
|
\end{verbatim}
|
\end{verbatim}
|
If no asserts are displayed between these lines, the test passes. Below is an example of passing test:
|
If no asserts are displayed between these lines, the test passed. Below is an example of passing test:
|
\begin{verbatim}
|
\begin{verbatim}
|
...
|
...
|
some compilation output
|
some compilation output
|
...
|
...
|
# sd_cmd_master_tb start ...
|
# sd_cmd_master_tb start ...
|
# sd_cmd_master_tb finish ...
|
# sd_cmd_master_tb finish ...
|
# ** Note: $finish : ../../../bench/verilog/sd_cmd_master_tb.sv(385)
|
# ** Note: $finish : ../../../bench/verilog/sd_cmd_master_tb.sv(385)
|
# Time: 3620 ps Iteration: 0 Instance: /sd_cmd_master_tb
|
# Time: 3620 ps Iteration: 0 Instance: /sd_cmd_master_tb
|
\end{verbatim}
|
\end{verbatim}
|
Below is an example of failing test:
|
Below is an example of failing test:
|
\begin{verbatim}
|
\begin{verbatim}
|
...
|
...
|
some compilation output
|
some compilation output
|
...
|
...
|
# sd_cmd_master_tb start ...
|
# sd_cmd_master_tb start ...
|
# ** Error: Assertion error.
|
# ** Error: Assertion error.
|
# Time: 3280 ps Scope: sd_cmd_master_tb File: ../../../bench/verilog/
|
# Time: 3280 ps Scope: sd_cmd_master_tb File: ../../../bench/verilog/
|
sd_cmd_master_tb.sv Line: 376
|
sd_cmd_master_tb.sv Line: 376
|
# sd_cmd_master_tb finish ...
|
# sd_cmd_master_tb finish ...
|
# ** Note: $finish : ../../../bench/verilog/sd_cmd_master_tb.sv(385)
|
# ** Note: $finish : ../../../bench/verilog/sd_cmd_master_tb.sv(385)
|
# Time: 3620 ps Iteration: 0 Instance: /sd_cmd_master_tb
|
# Time: 3620 ps Iteration: 0 Instance: /sd_cmd_master_tb
|
\end{verbatim}
|
\end{verbatim}
|
|
|
\subsubsection{Simulation makefile targets}
|
\subsubsection{Simulation makefile targets}
|
\label{sec:sim_make_targ}
|
\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:
|
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}
|
\begin{description}
|
\item[\texttt{clean}] - remove all simulation output files,
|
\item[\texttt{clean}] - remove all simulation output files,
|
\item[\texttt{print\_testbenches}] - lists all availible testbenches,
|
\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{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}] - 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 simulation in command-line, launches modelsim.
|
\item[\texttt{*\_tb\_gui}] - same as \path{*_tb} target, only instead of executing the simulation via command-line, launches modelsim.
|
\end{description}
|
\end{description}
|
|
|
\subsubsection{Simulation makefile environment variables}
|
\subsubsection{Simulation makefile environment variables}
|
\label{sec:sim_make_var}
|
\label{sec:sim_make_var}
|
|
|
Simulation makefile uses couple of environment variables to setup simulation:
|
The simulation makefile uses a couple of environment variables to setup the simulation:
|
\begin{description}
|
\begin{description}
|
\item[\texttt{MODELSIM\_DIR}] - modelsim installation directory (\path{\$(MODELSIM_DIR)/bin/vsim} should be a valid path),
|
\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{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).
|
\item[\texttt{V}] - when set to 1 - enables verbose output; when set to 0 - normal simulation output (0 is default).
|
\end{description}
|
\end{description}
|
|
|
|
|
\subsection{Synthesis}
|
\subsection{Synthesis}
|
\label{sec:synthesis}
|
\label{sec:synthesis}
|
|
|
For the purpose of synthesis verification there is an example FPGA project made for Altera Quartus.
|
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}:
|
To start synthesis just enter to \path{syn/quartus/run} directory and type \texttt{make}:
|
\begin{verbatim}
|
\begin{verbatim}
|
#> cd syn/quartus/run
|
#> cd syn/quartus/run
|
#> make
|
#> make
|
\end{verbatim}
|
\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 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.
|
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.
|
This makes timing verification more accurate.
|
|
|
\subsubsection{Synthesis makefile targets}
|
\subsubsection{Synthesis makefile targets}
|
\label{sec:syn_make_targ}
|
\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:
|
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}
|
\begin{description}
|
\item[\texttt{clean}] - remove all synthesis output files,
|
\item[\texttt{clean}] - remove all synthesis output files,
|
\item[\texttt{print\_config}] - prints projects configuration of FPGA device,
|
\item[\texttt{print\_config}] - prints project configuration of FPGA device,
|
\item[\texttt{project}] - creates quartus project files (.qpf and .qsf),
|
\item[\texttt{project}] - creates Quartus project files (.qpf and .qsf),
|
\item[\texttt{quartus}] - creates quartus project files and launches quartus IDE.
|
\item[\texttt{quartus}] - creates Quartus project files and launches the Quartus IDE.
|
\end{description}
|
\end{description}
|
|
|
\subsubsection{Synthesis makefile environment variables}
|
\subsubsection{Synthesis makefile environment variables}
|
\label{sec:syn_make_var}
|
\label{sec:syn_make_var}
|
|
|
Synthesis makefile uses couple of environment variables to setup synthesis:
|
The synthesis makefile uses a couple of environment variables to setup synthesis:
|
\begin{description}
|
\begin{description}
|
\item[\texttt{QUARTUS\_DIR}] - quartus installation directory (\path{\$(QUARTUS_DIR)/bin/quartus} should be a valid path),
|
\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\_FAMILY}] - name of the FPGA device family,
|
\item[\texttt{FPGA\_PART}] - name of the FPGA device,
|
\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).
|
\item[\texttt{V}] - when set to 1 - enables verbose output; when set to 0 - normal simulation output (0 is default).
|
\end{description}
|
\end{description}
|
|
|
