chapter2.tex

% Free range VHDL
% Authors: Bryan Mealy, Fabrizio Tappero
% Date: May, 2012
% URL: freerangefactory.org
% (C) 2013 B. Mealy, F. Tappero
%
% !TEX root = master.tex
%
\chapter{VHDL Invariants}
There are several features of VHDL that you should know before moving forward. Although it is rarely a good idea for people to memorize anything, you should memorize the basic concepts presented in this section. This should help eliminate some of the drudgery involved in learning a new programming language and lay the foundation that will enable you to create visually pleasing and good VHDL source code.

\section{Case Sensitivity}
\textbf{VHDL is not case sensitive}. This means that the two statements shown in Listing~\ref{case_sens} have the exact same meaning (don't worry about what the statement actually means though). Keep in mind that Listing~\ref{case_sens} shows an example of VHDL case sensitivity and not good VHDL coding practices.

\noindent
\begin{minipage}{0.99\linewidth}
\begin{lstlisting}[label=case_sens, caption=An example of VHDL case insensitivity.]
Dout <= A and B;								doUt <= a AnD b;
\end{lstlisting}
\end{minipage}

\section{White Space}
\textbf{VHDL is not sensitive to white space} (spaces and tabs) in the source document. The two statements in Listing~\ref{white_spaces} have the exact same meaning. Once again, Listing~\ref{white_spaces} is not an example of good VHDL coding style. Note that Listing~\ref{white_spaces} once again indicates that VHDL is not case sensitive.

\noindent
\begin{minipage}{0.99\linewidth}
\begin{lstlisting}[label=white_spaces, caption=An example showing VHDL's indifference to white space.]
nQ <= In_a or In_b;						nQ   <=in_a OR       in_b;
\end{lstlisting}
\end{minipage}

\section{Comments}
Comments in VHDL begin with the symbol ``\texttt{--}'' (two consecutive dashes). The VHDL synthesizer ignores anything after the two dashes and up to the end of the line in which the dashes appear. Listing~\ref{comments} shows two types of commenting styles. Unfortunately, there are no block-style comments (comments that span multiple lines but do not require comment marks on every line) available in VHDL.

\noindent
\begin{minipage}{0.99\linewidth}
\begin{lstlisting}[label=comments, caption=Two typical uses of comments.]
-- This next section of code is used to blah-blah
-- This type of comment is the best fake for block-style commenting.
PS_reg <= NS_reg; -- Assign next_state value to present_state
\end{lstlisting}
\end{minipage}

Appropriate use of comments increases both the readability and the understandability of VHDL code. The general rule is to comment any line or section of code that may not be clear to a reader of your code besides yourself. The only inappropriate use of a comment is to state something that is patently obvious. It is hard to imagine code that has too few comments so don't be shy: use lots of comments. Research has shown that using lots of appropriate comments is actually a sign of high intelligence.

\section{Parentheses}
VHDL is relatively lax on its requirement for using parentheses. Like other computer languages, there are a few precedence rules associated with the various operators in the VHDL language. Though it is possible to learn all these rules and write clever VHDL source code that will ensure the readers of your code are left scratching their heads, a better idea is to practice liberal use of parentheses to ensure the human reader of your source code understands the purpose of the code. Once again, the two statements appearing in Listing~\ref{parenthesis} have the same meaning. Note that extra white space has been added along with the parentheses to make the lower statement clearer.

\noindent
\begin{minipage}{0.99\linewidth}
\begin{lstlisting}[label=parenthesis, caption=Example of parentheses that can improve clarity.]
if x = '0' and y = '0' or z = '1' then
	blah; -- some useful statement
	blah; -- some useful statement
end if;
if ( ((x = '0') and (y = '0')) or (z = '1') ) then
	blah; -- some useful statement
	blah; -- some useful statement
end if;
\end{lstlisting}
\end{minipage}

\section{VHDL Statements}
Similar to other algorithmic computer languages, every VHDL statement is terminated with a semicolon. This fact helps when attempting to remove compiling errors from your code since semicolons are often omitted during initial coding. The main challenge then is to know what constitutes a VHDL statement in order to know when to include semicolons. The VHDL synthesizer is not as forgiving as other languages when superfluous semicolons are placed in the source code.

\section{\texttt{if}, \texttt{case} and \texttt{loop} Statements}
As you will soon find out, the VHDL language contains \texttt{if}, \texttt{case} and \texttt{loop} statements. A common source of frustration that occurs when learning VHDL are the classic mistakes involving these statements. Always remember the rules stated below when writing or debugging your VHDL code and you will save yourself a lot of time. Make a note of this section as one you may want to read again once you have had a formal introduction to these particular statements.
\begin{my_list}
\item Every \texttt{if} statement has a corresponding \texttt{then} component
\item Each \texttt{if} statement is terminated with an \texttt{end if;}
\item If you need to use an \texttt{else if} construct, the VHDL version is \texttt{elsif}
\item Each \texttt{case} statement is terminated with an \texttt{end case;}
\item Each \texttt{loop} statement has a corresponding \texttt{end loop;} statement
\end{my_list}
In general, you should not worry too much about memorizing code syntax as chances are you will use an editor sophisticated enough to have code snippets (namely Gedit\footnote{Gedit, the official Linux GNOME text editor. {\footnotesize\url{http://projects.gnome.org/gedit}}}). A good programmer distinguishes himself by other means than perfectly remembering code syntax.

\section{Identifiers}
An identifier refers to the name given to various items in VHDL. Examples of identifiers in higher-level languages include variable names and function names. Examples of identifiers in VHDL include variable names, signal names and port names (all of which will be discussed soon). Listed below are the hard and soft rules (i.e. you must follow them or you should follow them), regarding VHDL identifiers.

\begin{my_list}
\item Identifiers should be self-describing. In other words, the text you apply to identifiers should provide information as to the use and purpose of the item the identifier represents.
\item Identifiers can be as long as you want (contain many characters). Shorter names make for better reading code, but longer names present more information. It is up to the programmer to choose a reasonable identifier length.
\item Identifiers can only contain a combination of letters (A-Z and a-z), digits (0-9) and the underscore character (``\_'').
\item Identifiers must start with an alphabetic character.
\item Identifiers must not end with an underscore and must never have two consecutive underscores.
\item The best identifier for a function that calculates the position of the Earth is \textbf{CalcEarthPosition} or \textbf{calc\_earth\_position}. Try to be consistent.
\item The best identifier for a variable that stores the age of your car is \textbf{AgeMyCar} or \textbf{age\_my\_car}. Again, try to be consistent.
\end{my_list}
Remember, intelligent choices for identifiers make your VHDL code more readable, understandable and more impressive to coworkers, superiors, family and friends. A few examples of both good and bad choices for identifier names appear in Listing~\ref{valid_identif} and in Listing~\ref{invalid_identif}.

\noindent
\begin{minipage}[lt]{0.49\linewidth}
\vspace{5pt}
\begin{lstlisting}[label=valid_identif, caption=Valid identifies.]
data_bus	--descriptive name
WE			--classic write enable
div_flag	--real winner
port_A		--provides some info
in_bus		--input bus
clk			--classic clock
clk_in
clk_out
mem_read_data
--
--
--
\end{lstlisting}
\end{minipage}
\begin{minipage}[tr]{0.49\linewidth}
\vspace{5pt}
\begin{flushright}
\begin{lstlisting}[label=invalid_identif, caption=Invalid identifies.]
3Bus_val -- begins with a number
DDD      -- not self commenting
mid_$num -- illegal character
last__val-- consec. underscores
str_val_ -- ends with underscore
in       -- uses VHDL reserved word
@#$%%    -- total garbage
it_sucks -- try to avoid
Big_vAlUe-- valid but ugly
pa       -- possibly lacks meaning
sim-val  -- illegal character(dash)
DDE_SUX  -- no comment
\end{lstlisting}
\end{flushright}
\end{minipage}

\section{Reserved Words}
There is a list of words that have been assigned special meaning by the VHDL language. These special words, usually referred to as reserved words, cannot be used as identifiers when writing VHDL code. A partial list of reserved words that you may be inclined to use appears in Listing~\ref{reserved_words_short}. A complete list of reserved words appears in the Appendix. Notably missing from Listing~\ref{reserved_words_short} are standard operator names such as AND, OR, XOR, etc.

\noindent
\begin{minipage}{0.99\linewidth}
\begin{lstlisting}[label=reserved_words_short, caption=A short list of VHDL reserved words.]
access   after      alias       all        attribute    block
body     buffer     bus         constant   exit         file
for      function   generic     group      in           is
label    loop       mod         new        next         null
of       on         open        out        range        rem
return   signal     shared      then       to           type
until    use        variable    wait       while        with
\end{lstlisting}
\end{minipage}

\section{VHDL Coding Style}
Coding style refers to the appearance of the VHDL source code. Obviously, the freedom provided by case insensitivity, indifference to white space and lax rules on parentheses creates a coding anarchy. The emphasis in coding style is therefore placed on readability. Unfortunately, the level of readability of any document, particularly coding text, is subjective. Writing VHDL code is similar to writing code in other computer languages such as C and Java where you have the ability to make the document more readable without changing the functioning of the code. This is primarily done by indenting certain portions of the program, using self-describing identifiers and providing proper comments when and where necessary.

Instead of stating here a bunch of rules for you to follow as to how your code should look, you should instead strive to simply make your source code readable. Listed below are a few thoughts on what makes readable source code.

\begin{my_list}
\item Chances are that if your VHDL source code is readable to you, it will be readable to others who may need to peruse your document. These other people may include someone who is helping you get the code working properly, someone who is assigning a grade to your code, or someone who signs your paycheck at the end of the day. These are the people you want to please. These people are probably very busy and more than willing to make a superficial glance at your code. Nice looking code will slant such subjectivity in your favor.
\item If in doubt, your VHDL source code should be modeled after some other VHDL document that you find organized and readable. Any code you look at that is written down somewhere is most likely written by someone with more VHDL experience than a beginner such as yourself. Emulate the good parts of their style while on the path to creating an even more readable style.
\item Adopting a good coding style helps you write code without mistakes. As with other compilers you have experience with, you will find that the VHDL compiler does a great job of knowing a document has an error but a marginal job at telling you where or what the error is. Using a consistent coding style enables you to find errors both before compilation and after the compiler has found an error.
\item A properly formatted document explicitly presents information about your design that would not otherwise be readily apparent. This is particularly true when using proper indentation and sufficient comments.
\end{my_list}
\null\newpage
\thispagestyle{empty}