Merge remote-tracking branch 'iteasyndikat/batman_merge' into waschtl

preamble.tex

@@ -412,8 +412,13 @@ minimum height=1cm, align=center, text width=3cm, draw=black, fill=blue!30]
 
 \newcommand\instrset{rv32i}
 
-\newcommand{\entityheader}[2]{
-	\lstinputlisting[style=vhdlstyle,title=\texttt{#2}]{#1}
+\newcommand{\entityheader}[1]{
+	\lstinputlisting[
+        style=vhdlstyle,
+        label={lst:entity-header-#1},
+        caption={Header for #1 entity},
+        title=\texttt{#1.vhd},
+    ]{entities/#1_entity.vhd}
 }
 
 \usepackage{tcolorbox}

sections/core/core.tex

@@ -26,13 +26,13 @@ It is constructed according to the traditional RISC pipeline:
 
 \section{Control}
 
-\entityheader{entities/control_entity.vhd}{control.vhd}
+\entityheader{control}
 
 The control unit is responsible for coordinating subcomponents and the data flow between them. Internally, it is based on \icode{instruction\_info\_t} structures, which contain all the information required to pass an instruction along the different pipeline stages. Before the fetch stage, when an instruction is first scheduled, it contains only the instruction's address (because nothing else is known about it). Then, information is added incrementally by the different stages.
 
 \section{Decoder}
 
-\entityheader{entities/decoder_entity.vhd}{decoder.vhd}
+\entityheader{decoder}
 
 The decoder receives an instruction and interprets it. Among others, it determines
 
@@ -45,31 +45,31 @@ The decoder receives an instruction and interprets it. Among others, it determin
 
 \section{Registers}
 
-\entityheader{entities/registers_entity.vhd}{registers.vhd}
+\entityheader{registers}
 
 The registers store the 32 general-purpose values required by \instrset{} (each 32-bit wide). They are accessible through two read ports and one write port. As specified by the RISC-V standard, the first register (\icode{x0}) is hard-wired to 0, and any writes to it are ignored.
 
 \section{Arithmetic and Logic Unit (ALU)}
 
-\entityheader{entities/alu_entity.vhd}{alu.vhd}
+\entityheader{alu}
 
 The ALU contains a math/logic unit as well as a comparator. It is used both explicitly by instructions such as \icode{add} or \icode{shiftl}, as well as to add offsets to base addresses for memory instructions and to decide whether an instructions should branch.
 
 \section{Control and Status Registers (CSR)}
 
-\entityheader{entities/csr_entity.vhd}{csr.vhd}
+\entityheader{csr}
 
 The control and status registers contain configurations relevant to the core itself. For example, they can be used to control interrupts.
 
 \section{Memory Arbiter}
 
-\entityheader{entities/memory_arbiter_entity.vhd}{memory\_arbiter.vhd}
+\entityheader{memory_arbiter}
 
 Since both fetch and memory stages need to access the same system memory, access to this common resource has to be controlled. The memory arbiter acts as a proxy for both fetch and data memory requests and stalls either until the other one completes.
 
 \section{Exception Control}
 
-\entityheader{entities/exception_control_entity.vhd}{exception\_control.vhd}
+\entityheader{exception_control}
 
 Several components in the core may raise a synchronous exception when an unexpected error (such as a malformed instruction or an unaligned memory access) occurs. Additionally, asynchronous interrupts (like from a timer or a UART) can be triggered externally. When an exception or an enabled interrupt is registered, program flow is diverted to the trap handler, defined using the machine trap vector (\icode{mtvec}) CSR.
 

sections/vhdl_intro/vhdl_intro.tex

@@ -25,15 +25,28 @@ Other than a text editor, the following Free Software packages have to be instal
 
 A simple starting design is an up/down counter. The following VHDL code describes the device:
 
-\lstinputlisting[style=vhdlstyle,title=\texttt{counter.vhd}]{vhdl/counter.vhd}
+\lstinputlisting[
+    style=vhdlstyle,
+    label={lst:counter},
+    caption={Counter entity},
+    title=\texttt{counter.vhd},
+]{vhdl/counter.vhd}
 
 In order to test this design, a test bench has to be created:
 
-\lstinputlisting[style=vhdlstyle,title=\texttt{counter_tb.vhd}]{vhdl/counter_tb.vhd}
+\lstinputlisting[
+    style=vhdlstyle,
+    label={lst:counter-tb},
+    caption={Counter test bench entity},
+    title=\texttt{counter_tb.vhd},
+]{vhdl/counter_tb.vhd}
 
 \section{Simulating a design}
 
-\begin{lstlisting}[style=terminal]
+\begin{lstlisting}[
+    style=terminal,
+    label={lst:counter-sim-commands},
+    caption={Commands required to simulate the counter design}]
 # analyze the design files
 ghdl -a --std=08 *.vhd
 # elaborate the test bench entity
@@ -53,9 +66,16 @@ gtkwave counter_tb.ghw counter_tb.gtkw
 
 An additional Xilinx Design Constraints (XDC) file is required to assign the signals to pins on the FPGA:
 
-\lstinputlisting[title=\texttt{counter.xdc}]{vhdl/counter.xdc}
+\lstinputlisting[
+    label={lst:counter-constraints},
+    caption={Counter design constraints file},
+    title=\texttt{counter.xdc},
+]{vhdl/counter.xdc}
 
-\begin{lstlisting}[style=terminal]
+\begin{lstlisting}[
+    style=terminal,
+    label={lst:counter-synth-commands},
+    caption={Commands required to synthesize the counter design}]
 # synthesize with yosys
 yosys -m ghdl.so -p '
     ghdl --std=08 counter.vhd -e counter;