From dc77d4bf61526bc2c367baa2e24a12232a65856d Mon Sep 17 00:00:00 2001 From: Xiretza Date: Fri, 27 Mar 2020 14:20:22 +0100 Subject: [PATCH] Add labels and captions to listings --- preamble.tex | 9 +++++++-- sections/core/core.tex | 14 +++++++------- sections/vhdl_intro/vhdl_intro.tex | 30 +++++++++++++++++++++++++----- 3 files changed, 39 insertions(+), 14 deletions(-) diff --git a/preamble.tex b/preamble.tex index 0bd11ac..ef3dcdd 100644 --- a/preamble.tex +++ b/preamble.tex @@ -310,8 +310,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} diff --git a/sections/core/core.tex b/sections/core/core.tex index 9a71e28..3fc3a7e 100644 --- a/sections/core/core.tex +++ b/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. diff --git a/sections/vhdl_intro/vhdl_intro.tex b/sections/vhdl_intro/vhdl_intro.tex index 56fa62b..f185710 100644 --- a/sections/vhdl_intro/vhdl_intro.tex +++ b/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;