finished appendix

tex/chapters/2_open_source_tools.tex

@@ -16,7 +16,7 @@ \section{Unique benefits and features of open-source tools.}
 
 Undoubtedly, proprietary tools offer a multitude of functionalities for advanced users that open-source tools cannot offer. However, open-source tools offer many unique features that are more desired by beginners. For example, Icarus runs short simulations much faster than proprietary simulators, making it perfect for receiving instant feedback as students are still learning the language syntax. Similarly, Yosys and Nextpnr perform synthesis and layout significantly faster than tools such as Vivado and Design Compiler, allowing for more rapid prototyping. Also, while ModelSim may happily parse and simulate un-synthesizable code, Verilator will give much more strict warnings, helping to demonstrate the syntax and features that should be allowed in synthesizable designs. (This is further discussed in \autoref{chapter:digital_design}).
 
-Possibly the most important attribute of open-source tools is that they get updates every day, and instructors have full transparency when reporting bugs and requesting new features. Depending on the difficulty of the request, the tool maintainers may complete the request within a few months. Multiple of my courses have directly benefited from this [appx]. Instructors may even decide they want to do a pull-request themselves; I personally have contributed two new warnings to Verilator in hopes of teaching best-practices. [appx] This is contrasted with the fact that many universities are not always running the most up-to-date proprietary software. For example, as of 9/10/23, UC Santa Barbara's Engineering Computing Infrastructure's latest version of ModelSim is 10.7d from April 2019, which does not support width-casting from parameters, which affected the UCSB Spring 2023 ECE 152A course experience. Bugs in tools will undoubtedly happen, but the only solution Siemens offers is to pay for an updated version with the bug fixed. Contrast this with submitting a GitHub issue with Verilator, and having the bug fixed by the next time the course is offered. Open-source tools are often simply the better choice for instructors.
+Possibly the most important attribute of open-source tools is that they get updates every day, and instructors have full transparency when reporting bugs and requesting new features. Depending on the difficulty of the request, the tool maintainers may complete the request within a few months. Instructors may even decide they want to do a pull-request themselves; I personally have contributed two new warnings to Verilator in hopes of teaching best-practices (see \autoref{appx:contributions}). This is contrasted with the fact that many universities are not always running the most up-to-date proprietary software. For example, as of 9/10/23, UC Santa Barbara's Engineering Computing Infrastructure's latest version of ModelSim is 10.7d from April 2019, which does not support width-casting from parameters, which affected the UCSB Spring 2023 ECE 152A course experience. Bugs in tools will undoubtedly happen, but the only solution Siemens offers is to pay for an updated version with the bug fixed. Contrast this with submitting a GitHub issue with Verilator, and having the bug fixed by the next time the course is offered. Open-source tools are often simply the better choice for instructors.
 
 \section{Avoid graphical user interfaces.}
 

tex/chapters/4_resources.tex

@@ -13,7 +13,7 @@ \section{Style guides and linters record synthesizable features and best-practic
 
 Even while avoiding commonly unsynthesizable SystemVerilog features, design tools are infamous for misinterpreting syntax and often providing little or misleading information on errors. Therefore, using linters and well-verified style guides is crucial in ensuring that an RTL implementation will work on an assortment of tools. As mentioned in \autoref{chapter:digital_design}, style guides and linters help direct engineers away from ambiguous or poorly-supported language features, and towards syntax and features that are verified to tape-out chips successfully. By introducing Verilog alongside an exhaustive style guide, and providing test flows with linting, students can feel much more confident exploring new language features.
 
-The lowRISC Style Guide discusses many best-practices of language features such as the alias statement, automatic scopes, package imports, and floating begin-end blocks \cite{lowRISCstyleguides}. The Bespoke Silicon Group Style Guide is also strong due to its discussion of structures, enumerations, and memories \cite{BSGstyleguide}. There are also style guides published by tool manufacturers that show how to infer different types of logic \cite{Xilinxstyleguide, Intelstyleguide, Latticestyleguide}. There are many style guides available; see [appx] for a(n incomplete) list. Personally, I teach the lowRISC style guide because of its thorough explanations, because of the clarity in \mintinline{systemverilog}{_d} and \mintinline{systemverilog}{_q} as suffixes for register inputs and outputs, and to match the ``Labs with CVA6'' project (as described in \autoref{chapter:labs_with_cva6}).
+The lowRISC Style Guide discusses many best-practices of language features such as the alias statement, automatic scopes, package imports, and floating begin-end blocks \cite{lowRISCstyleguides}. The Bespoke Silicon Group Style Guide is also strong due to its discussion of structures, enumerations, and memories \cite{BSGstyleguide}. There are also style guides published by tool manufacturers that show how to infer different types of logic \cite{Xilinxstyleguide, Intelstyleguide, Latticestyleguide}. There are many style guides available; see \autoref{appx:style_guides} for a(n incomplete) list. Personally, I teach the lowRISC style guide because of its thorough explanations, because of the clarity in \mintinline{systemverilog}{_d} and \mintinline{systemverilog}{_q} as suffixes for register inputs and outputs, and to match the ``Labs with CVA6'' project (as described in \autoref{chapter:labs_with_cva6}).
 
 Linters such as Verible \cite{veribleGitHub}, Verilator \cite{verilatorGitHub}, and svlint \cite{svlintGitHub} are all popular in design flows. Each are configurable to warn on or forbid specific language features, and many open-source projects choose to lint with more than one of these tools. For example, Verible is known for its auto-formatting capabilities; Verilator is powerful enough to warn on multidriven signals and accidental latches in \mintinline{systemverilog}{always_comb} blocks; and Svlint is unique for its ability to verify complex whitespace layouts and enforce custom net naming styles. Each have their purpose and should be used on student submissions to ensure best-practices are enforced.
 

tex/final/appendix.tex

@@ -1,67 +1,84 @@
 
 \begin{appendices}
 
+
+
 \chapter{Open-source Contributions}
 \label{appx:contributions}
 
-This appendix identifies several open-source issues and contributions I have made. Most of the contributions in this appendix were related to my efforts as an HDL educator.
+This appendix identifies several open-source issues and contributions I have made. Most of the contributions in this appendix are related to my efforts as an HDL educator.
 
-\section{My open-source issues and contributions}
+\section{Open-source issues and contributions created by me}
 
 \begin{itemize}
-    \item \url{https://github.com/olofk/fusesoc/pull/645} [\textbf{open-pr}] Improved inheritance elaboration
-    \item \url{https://github.com/verilator/verilator/pull/4409} [\textbf{closed-pr}] Add check for conflicting options e.g. --binary and --lint-only
-    \item \url{https://github.com/olofk/edalize/pull/389} [\textbf{open-pr}] Added support for additional Verilator modes
-    \item \url{https://github.com/Rain92/FPGA-Mandelbrot/pull/1} [\textbf{open-pr}] Fixed build issues
-    \item \url{https://github.com/lowRISC/style-guides/pull/66} [\textbf{closed-pr}] Specified that functions should avoid non-local references
-    \item \url{https://github.com/steveicarus/iverilog/pull/980} [\textbf{closed-pr}] Argumentless functions fix
-    \item \url{https://github.com/verilator/verilator/pull/4172} [\textbf{closed-pr}] Added NEWERSTD warning when using feature in newer language standard
-    \item \url{https://github.com/openhwgroup/cva6/pull/1142} [\textbf{closed-pr}] Improved Acronym List in Glossary
+    \item [\pullrequesticon] \githubpull{olofk/fusesoc}{645}: Improved inheritance elaboration
+    \item [\mergedicon] \githubpull{verilator/verilator}{4409}: Check for conflicting options e.g. --binary and --lint-only
+    \item [\pullrequesticon] \githubpull{olofk/edalize}{389}: Added support for additional Verilator modes
+    \item [\pullrequesticon] \githubpull{Rain92/FPGA-Mandelbrot}{1}: Fixed build issues
+    \item [\mergedicon] \githubpull{lowRISC/style-guides}{66}: Prohibit functions from using non-local references
+    \item [\mergedicon] \githubpull{steveicarus/iverilog}{980}: Argumentless functions fix
+    \item [\mergedicon] \githubpull{verilator/verilator}{4172}: Added NEWERSTD warning
+    \item [\mergedicon] \githubpull{openhwgroup/cva6}{1142}: Improved Acronym List in Glossary
 \end{itemize}
 
 \section{Open-source issues created by my students for my classes}
 
 \begin{itemize}
-    \item \url{https://github.com/YosysHQ/oss-cad-suite-build/issues/28} [\textbf{closed-issue}] nextpnr-gowin support requested
+    \item [\issueclosedicon] \githubissue{YosysHQ/oss-cad-suite-build}{28} nextpnr-gowin support requested
 \end{itemize}
 
+
+
 \chapter{Style Guide Survey}
 \label{appx:style_guides}
 
 This appendix identifies several prominent Verilog and SystemVerilog style guides.
 
-\section{Projects that use lowRISC SystemVerilog Coding Style}
+\section{lowRISC Verilog Coding Style Guide}
 
 \begin{itemize}
-    \item \url{https://github.com/openhwgroup/cva6}
-    \item \url{https://github.com/lowRISC/ibex}
-    \item \url{https://github.com/lowRISC/opentitan}
-    \item \url{https://github.com/openhwgroup/cv32e40p}
-    \item \url{https://github.com/openhwgroup/cvfpu}
-    \item \url{https://github.com/pulp-platform/ara}
+    \item \url{https://github.com/lowRISC/style-guides} \cite{lowRISCstyleguides}
+    \item Projects that use lowRISC Verilog Coding Style Guide:
+    \begin{itemize}
+        \item lowRISC: Ibex RISC-V Core \cite{Ibex}
+        \item lowRISC: OpenTitan RISC-V Core \cite{OpenTitan}
+        \item OpenHW Group: CV32E40P RISC-V Core \cite{cv32e40p}
+        \item OpenHW Group: CVA6 RISC-V Core \cite{cva6}
+        \item OpenHW Group: FPnew Floating-Point Unit \cite{cvfpu}
+        \item PULP Platform: Ara Vector Unit \cite{Ara}
+        \item PULP Platform: MemPool Many-Core System \cite{MemPool}
+    \end{itemize}
 \end{itemize}
 
-\section{Projects that use BSG SystemVerilog Coding Style}
+\pagebreak
+
+\section{BSG System Verilog Coding Standards}
 
 \begin{itemize}
-    \item \url{https://github.com/black-parrot/black-parrot}
-    \item \url{https://github.com/bespoke-silicon-group/basejump_stl}
+    \item \href{https://docs.google.com/document/d/1xA5XUzBtz_D6aSyIBQUwFk_kSUdckrfxa2uzGjMgmCU}{\footnotesize docs.google.com/document/d/1xA5XUzBtz\_D6aSyIBQUwFk\_kSUdckrfxa2uzGjMgmCU} \cite{BSGstyleguide}
+    \item Projects that use BSG System Verilog Coding Standards:
+    \begin{itemize}
+        \item Bespoke Silicon Group: BlackParrot RISC-V Core \cite{blackparrot}
+        \item Bespoke Silicon Group: BaseJump Standard Template Library \cite{basejumpstl}
+    \end{itemize}
 \end{itemize}
 
-\section{Misc Style Guides}
+\section{Company Style Guides}
 
 \begin{itemize}
-    \item \url{https://michaeltaylor.org/edu/papers/FreescaleVerilog.pdf}
-    \item \url{https://docs.xilinx.com/r/en-US/ug901-vivado-synthesis/HDL-Coding-Techniques}
-    \item \url{https://www.intel.com/content/www/us/en/docs/programmable/683082/23-1/recommended-hdl-coding-styles.html}
-    \item \url{https://www.latticesemi.com/~/media/LatticeSemi/Documents/UserManuals/EI/HDLcodingguidelines.PDF?document_id=48203}
+    \item Xilinx -- HDL Coding Techniques \cite{Xilinxstyleguide}
+    \item Intel -- Recommended HDL Coding Styles \cite{Intelstyleguide}
+    \item Lattice -- HDL Coding Guidelines \cite{Latticestyleguide}
+    \item Freescale -- Verilog HDL Coding \cite{Freescalestyleguide}
 \end{itemize}
 
-\section{Less-complete Style Guides}
+\section{Miscellaneous Style Guides}
 
 \begin{itemize}
-    \item \url{https://github.com/rsd-devel/rsd/wiki/en-devel-coding-convention}
-    \item \url{https://github.com/hughperkins/VeriGPU/blob/main/docs/coding_guidelines.md}
+    \item RSD RISC-V Core -- Coding conventions \cite{RSDstyleguide}
+    \item VeriGPU -- Coding guidelines \cite{VeriGPUstyleguide}
 \end{itemize}
 
+
+
 \end{appendices}

tex/thesis.bib

@@ -243,6 +243,72 @@ @misc{cvwally
   note = {[Accessed 18-09-2023]},
 }
 
+@misc{basejumpstl,
+  author = {{Bespoke Silicon Group}},
+  title = {{B}ase{J}ump {S}tandard {T}emplate {L}ibrary},
+  howpublished = {\url{https://github.com/bespoke-silicon-group/basejump_stl}},
+  note = {[Accessed 18-09-2023]},
+}
+
+@misc{blackparrot,
+  author = {Petrisko, D. and Gilani, F. and Wyse, M. and D. Jung, C. and Davidson, S. and Gao, P. and Zhao, C. and Azad, Z. and Canakci, S. and Veluri, B. and Guarino, T. and A. Joshi, J. and Oskin, M. and Taylor, M. B.},
+  title = {{B}lack{P}arrot: {A}n {A}gile {O}pen {S}ource {R}{I}{S}{C}-{V} {M}ulticore for {A}ccelerator {S}o{C}s},
+  howpublished = {\doi{10.1109/MM.2020.2996145}},
+  doi = {10.1109/MM.2020.2996145},
+  note = {IEEE Micro Special Issue on Agile and Open-Source Hardware, July/August},
+}
+
+@inproceedings{MemPool,
+  author = {Matheus Cavalcante and Samuel Riedel and Antonio Pullini and Luca Benini},
+  title = {{MemPool}: A Shared-{L1} Memory Many-Core Cluster with a Low-Latency Interconnect},
+  booktitle = {2021 Design, Automation, and Test in Europe Conference and Exhibition (DATE)},
+  year = {2021},
+  month = {March},
+  address = {Grenoble, FR},
+  pages = {701-706},
+  doi = {10.23919/DATE51398.2021.9474087},
+  note = {\doi{10.23919/DATE51398.2021.9474087}}
+}
+
+@article{Ara,
+  author = {Matheus Cavalcante and Fabian Schuiki and Florian Zaruba and Michael Schaffner and Luca Benini},
+  journal = {IEEE Transactions on Very Large Scale Integration (VLSI) Systems},
+  title = {Ara: A 1-GHz+ Scalable and Energy-Efficient RISC-V Vector Processor With Multiprecision Floating-Point Support in 22-nm FD-SOI},
+  year = {2020},
+  volume = {28},
+  number = {2},
+  pages = {530-543},
+  doi = {10.1109/TVLSI.2019.2950087}
+}
+
+@misc{cvfpu,
+  author = {{OpenHW Group}},
+  title = {{F}{P}new {F}loating-{P}oint {U}nit},
+  howpublished = {\url{https://github.com/openhwgroup/cvfpu}},
+  note = {[Accessed 18-09-2023]},
+}
+
+@misc{cv32e40p,
+  author = {{OpenHW Group}},
+  title = {{C}{V}32{E}40{P}},
+  howpublished = {\url{https://github.com/openhwgroup/cv32e40p}},
+  note = {[Accessed 18-09-2023]},
+}
+
+@misc{OpenTitan,
+  author = {{lowRISC}},
+  title = {{O}pen{T}itan},
+  howpublished = {\url{https://github.com/lowRISC/opentitan}},
+  note = {[Accessed 18-09-2023]},
+}
+
+@misc{Ibex,
+  author = {{lowRISC}},
+  title = {{I}bex},
+  howpublished = {\url{https://github.com/lowRISC/ibex}},
+  note = {[Accessed 18-09-2023]},
+}
+
 @misc{licensePricesReddit,
   author = {{u/[deleted]}},
   title = {{M}odelsim and {Q}uesta license price: {T}oo expensive?},
@@ -367,6 +433,27 @@ @misc{Latticestyleguide
   note = {[Accessed 19-09-2023]},
 }
 
+@misc{Freescalestyleguide,
+	author = {{Freescale Semiconductor}},
+	title = {{F}reescale {V}erilog {H}{D}{L} {C}oding},
+	howpublished = {\url{https://michaeltaylor.org/edu/papers/FreescaleVerilog.pdf}},
+	note = {[Accessed 20-09-2023]},
+}
+
+@misc{VeriGPUstyleguide,
+	author = {Perkins, Hugh},
+	title = {{V}eri{G}{P}{U} {C}oding guidelines},
+	howpublished = {\url{https://github.com/hughperkins/VeriGPU/blob/main/docs/coding_guidelines.md}},
+	note = {[Accessed 20-09-2023]},
+}
+
+@misc{RSDstyleguide,
+	author = {{RSD}},
+	title = {{R}{S}{D} {C}oding conventions},
+	howpublished = {\url{https://github.com/rsd-devel/rsd/wiki/en-devel-coding-convention}},
+	note = {[Accessed 20-09-2023]},
+}
+
 @misc{asicworld,
   author = {Tala, Deepak Kumar and {ASIC World}},
   title = {{V}erilog {E}xamples},

tex/thesis.tex

@@ -50,6 +50,13 @@
 \renewcommand{\bibname}{References}
 \newcommand{\subfigureautorefname}{Subfigure}
 
+\newcommand{\githubpull}[2]{\href{https://github.com/#1/pull/#2}{#1\##2}}
+\newcommand{\githubissue}[2]{\href{https://github.com/#1/issues/#2}{#1\##2}}
+\newcommand{\issueclosedicon}{\raisebox{-0.15em}{\includegraphics[height=1em]{media/graphics/github/issue-closed.pdf}}}
+\newcommand{\issueopenicon}{\raisebox{-0.15em}{\includegraphics[height=1em]{media/graphics/github/issue-open.pdf}}}
+\newcommand{\mergedicon}{\raisebox{-0.15em}{\includegraphics[height=1em]{media/graphics/github/merged.pdf}}}
+\newcommand{\pullrequesticon}{\raisebox{-0.15em}{\includegraphics[height=1em]{media/graphics/github/pull-request.pdf}}}
+
 %---Set Margins ------------------------------------------------------
 \setlength\oddsidemargin{0.25 in} \setlength\evensidemargin{0.25 in} \setlength\textwidth{6.25 in} \setlength\textheight{8.50 in}
 \setlength\footskip{0.25 in} \setlength\topmargin{0 in} \setlength\headheight{0.25 in} \setlength\headsep{0.25 in}