From be5f790a7d2fdd2fc01cea0b5feceb76f1cb4722 Mon Sep 17 00:00:00 2001
From: parker-research <166864283+parker-research@users.noreply.github.com>
Date: Thu, 31 Oct 2024 21:09:13 -0600
Subject: [PATCH 1/9] Add preliminary dockerfile

---
 Dockerfile | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 Dockerfile

diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..64aeb2a
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,78 @@
+# This Dockerfile sets up an environment to build and test the ultraembedded RISC-V project.
+# To run it, mount the project directory into the container, e.g.,
+#
+# Bash:
+# docker run -it --rm -v $(pwd):/project riscv_build
+#
+# Fish:
+# docker build -t riscv_build .
+# docker run -it --rm -v (pwd):/project riscv_build
+
+# FROM ubuntu:22.04
+# FROM verilator/verilator:latest
+FROM verilator/verilator:4.038
+# Versions: https://hub.docker.com/r/verilator/verilator
+# Use version 4.038, per https://github.com/ultraembedded/riscv/issues/17
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    gcc \
+    make \
+    libelf-dev \
+    binutils-dev \
+    # systemc-dev \
+    # verilator \
+    git \
+    fish \
+    sudo \
+    wget
+
+# Change the default shell to fish
+RUN echo "fish" >> ~/.bashrc
+RUN echo "echo 'Fish exited.' && exit" >> ~/.bashrc
+
+# Install SystemC.
+# Guide: https://gist.github.com/bagheriali2001/0736fabf7da95fb02bbe6777d53fabf7
+# SystemC version 2.3.x is good, per note in the following Makefiles (mentioning version 2.3.3):
+    # ./top_tcm_axi/tb/makefile.build_sysc_tb
+    # ./top_cache_axi/tb/makefile.build_verilated
+WORKDIR /systemc
+RUN wget https://accellera.org/images/downloads/standards/systemc/systemc-2.3.3.tar.gz
+RUN tar -xvzf systemc-2.3.3.tar.gz
+# cd systemc-2.3.3 ; mkdir objdir ; cd objdir
+WORKDIR /systemc/systemc-2.3.3/objdir
+# export CXX=g++
+ENV CXX=g++
+RUN ../configure
+RUN make -j $(nproc)
+RUN make install
+WORKDIR /systemc/systemc-2.3.3
+RUN rm -rf objdir
+
+# Set important environment variables.
+ENV SYSTEMC_INCLUDE=/usr/local/systemc/include
+ENV SYSTEMC_LIBDIR=/usr/local/systemc/lib-linux64
+ENV SYSTEMC_HOME=/systemc/systemc-2.3.3
+
+ENV C_INCLUDE_PATH=/usr/local/share/verilator/include/:/usr/local/share/verilator/include/vltstd:/usr/local/systemc/include
+ENV CPLUS_INCLUDE_PATH=/usr/local/share/verilator/include/:/usr/local/share/verilator/include/vltstd:/usr/local/systemc/include
+
+# The following line must contain `verilated.cpp` file.
+ENV VERILATOR_SRC=/usr/local/share/verilator/share
+
+# Create a working directory
+WORKDIR /project
+
+# Instructions for building and running the testbench
+# Run the testbench using:
+# ```
+# cd top_tcm_axi/tb
+# make
+# make run
+# ```
+
+# If any environment variables or dependencies are specific to your system, refer to the documentation
+# at https://github.com/ultraembedded/riscv
+
+ENTRYPOINT ["/usr/bin/fish"]

From 281fd3cb83c5d6780a5407403d517271740064b0 Mon Sep 17 00:00:00 2001
From: parker-research <166864283+parker-research@users.noreply.github.com>
Date: Thu, 31 Oct 2024 21:43:23 -0600
Subject: [PATCH 2/9] Update Dockerfile so project build passes

---
 Dockerfile | 45 ++++++++++++++++++++++++++++++++++-----------
 1 file changed, 34 insertions(+), 11 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 64aeb2a..22b02a6 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -14,23 +14,20 @@ FROM verilator/verilator:4.038
 # Versions: https://hub.docker.com/r/verilator/verilator
 # Use version 4.038, per https://github.com/ultraembedded/riscv/issues/17
 
-# Install build dependencies
+# Prepare for non-interactive prompts, esp. for `software-properties-common`.
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install build dependencies.
 RUN apt-get update && apt-get install -y \
     build-essential \
     gcc \
     make \
     libelf-dev \
     binutils-dev \
-    # systemc-dev \
-    # verilator \
     git \
-    fish \
     sudo \
-    wget
-
-# Change the default shell to fish
-RUN echo "fish" >> ~/.bashrc
-RUN echo "echo 'Fish exited.' && exit" >> ~/.bashrc
+    wget \
+    curl
 
 # Install SystemC.
 # Guide: https://gist.github.com/bagheriali2001/0736fabf7da95fb02bbe6777d53fabf7
@@ -59,7 +56,32 @@ ENV C_INCLUDE_PATH=/usr/local/share/verilator/include/:/usr/local/share/verilato
 ENV CPLUS_INCLUDE_PATH=/usr/local/share/verilator/include/:/usr/local/share/verilator/include/vltstd:/usr/local/systemc/include
 
 # The following line must contain `verilated.cpp` file.
-ENV VERILATOR_SRC=/usr/local/share/verilator/share
+ENV VERILATOR_SRC=/usr/local/share/verilator/include
+
+# ################################
+# ### Optional Fish Section ######
+# ################################
+# Install fish shell.
+# RUN apt-add-repository -y ppa:fish-shell/release-3
+# RUN apt-get update
+# RUN apt-get install -y fish
+RUN apt-get install -y build-essential cmake libpcre2-dev gettext libncurses-dev
+WORKDIR /fish-build
+RUN wget https://github.com/fish-shell/fish-shell/releases/download/3.7.1/fish-3.7.1.tar.xz
+RUN tar -xvf fish-3.7.1.tar.xz
+WORKDIR /fish-build/fish-3.7.1
+RUN cmake .
+RUN make -j $(nproc)
+RUN make install
+RUN fish --version
+
+# Change the default shell to fish
+RUN echo "fish" >> ~/.bashrc
+RUN echo "echo 'Fish exited.' && exit" >> ~/.bashrc
+
+# ################################
+# ### End Fish Section ###########
+# ################################
 
 # Create a working directory
 WORKDIR /project
@@ -75,4 +97,5 @@ WORKDIR /project
 # If any environment variables or dependencies are specific to your system, refer to the documentation
 # at https://github.com/ultraembedded/riscv
 
-ENTRYPOINT ["/usr/bin/fish"]
+ENTRYPOINT ["/usr/local/bin/fish"]
+# ENTRYPOINT ["/bin/bash"]

From e259da7e2b4bf0af5a170e7154dfd764a7c318e6 Mon Sep 17 00:00:00 2001
From: parker-research <166864283+parker-research@users.noreply.github.com>
Date: Thu, 31 Oct 2024 21:50:51 -0600
Subject: [PATCH 3/9] Update Dockerfile so project `make run` passes

---
 Dockerfile | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 22b02a6..839a759 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -47,17 +47,6 @@ RUN make install
 WORKDIR /systemc/systemc-2.3.3
 RUN rm -rf objdir
 
-# Set important environment variables.
-ENV SYSTEMC_INCLUDE=/usr/local/systemc/include
-ENV SYSTEMC_LIBDIR=/usr/local/systemc/lib-linux64
-ENV SYSTEMC_HOME=/systemc/systemc-2.3.3
-
-ENV C_INCLUDE_PATH=/usr/local/share/verilator/include/:/usr/local/share/verilator/include/vltstd:/usr/local/systemc/include
-ENV CPLUS_INCLUDE_PATH=/usr/local/share/verilator/include/:/usr/local/share/verilator/include/vltstd:/usr/local/systemc/include
-
-# The following line must contain `verilated.cpp` file.
-ENV VERILATOR_SRC=/usr/local/share/verilator/include
-
 # ################################
 # ### Optional Fish Section ######
 # ################################
@@ -78,11 +67,26 @@ RUN fish --version
 # Change the default shell to fish
 RUN echo "fish" >> ~/.bashrc
 RUN echo "echo 'Fish exited.' && exit" >> ~/.bashrc
-
 # ################################
 # ### End Fish Section ###########
 # ################################
 
+
+# Set important environment variables.
+ENV SYSTEMC_INCLUDE=/systemc/systemc-2.3.3/include
+ENV SYSTEMC_LIBDIR=/systemc/systemc-2.3.3/lib-linux64
+ENV SYSTEMC_HOME=/systemc/systemc-2.3.3
+
+ENV C_INCLUDE_PATH=/usr/local/share/verilator/include/:/usr/local/share/verilator/include/vltstd:/systemc/systemc-2.3.3/include
+ENV CPLUS_INCLUDE_PATH=/usr/local/share/verilator/include/:/usr/local/share/verilator/include/vltstd:/systemc/systemc-2.3.3/include
+
+# The following folder must contain `libsystemc-2.3.3.so`.
+ENV LD_LIBRARY_PATH=/systemc/systemc-2.3.3/lib-linux64
+
+# The following folder must contain `verilated.cpp` file.
+ENV VERILATOR_SRC=/usr/local/share/verilator/include
+
+
 # Create a working directory
 WORKDIR /project
 

From 26e9158fafb817ad53077fb2bae3379c46a2ad5e Mon Sep 17 00:00:00 2001
From: parker-research <166864283+parker-research@users.noreply.github.com>
Date: Thu, 31 Oct 2024 21:52:30 -0600
Subject: [PATCH 4/9] Add gitignore

---
 .gitignore | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .gitignore

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..8fa39db
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+verilated/
+*.a
+*.o
+*.vcd
+test.x

From 1b54e116fdd1e81dc8ad6efd8729d32f9c05f8a9 Mon Sep 17 00:00:00 2001
From: parker-research <166864283+parker-research@users.noreply.github.com>
Date: Thu, 31 Oct 2024 22:00:14 -0600
Subject: [PATCH 5/9] Add versions to README

---
 README.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index c83f987..387b429 100644
--- a/README.md
+++ b/README.md
@@ -86,20 +86,20 @@ Dependencies;
 * gcc
 * make
 * libelf
-* System-C (specify path using SYSTEMC_HOME)
-* Verilator (specify path using VERILATOR_SRC)
+* System-C (specify path using `SYSTEMC_HOME`), version 3.2.x
+* Verilator (specify path using `VERILATOR_SRC`), version 4.038
 
 To build the testbench;
-```
+```bash
 cd top_tcm_axi/tb
 make
-````
+```
 
 To run the provided test executable;
-```
+```bash
 cd top_tcm_axi/tb
 make run
-````
+```
 
 ## Example Core Instance (with caches)
 

From 26aaa0970a372e3fd032b4a80f5263eccde7e647 Mon Sep 17 00:00:00 2001
From: parker-research <166864283+parker-research@users.noreply.github.com>
Date: Thu, 31 Oct 2024 22:42:56 -0600
Subject: [PATCH 6/9] Fix makefile formatting

---
 isa_sim/README.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/isa_sim/README.md b/isa_sim/README.md
index a9c5a2b..49cf2ae 100644
--- a/isa_sim/README.md
+++ b/isa_sim/README.md
@@ -11,19 +11,19 @@ Dependencies;
 * libbfd
 
 To install the dependencies on Linux Ubuntu/Mint;
-```
+```bash
 sudo apt-get install libelf-dev binutils-dev
 ```
 
 To build the executable, type:
-```
+```bash
 make
-````
+```
 
 ## Usage
 
 The simulator will load and run a compiled ELF (compiled with RV32I or RV32IM compiler options);
-```
+```bash
 # Using a makerule
 make run
 
@@ -38,7 +38,7 @@ which boots Linux (modified 4.19 compiled for RV32IM).
 ## Extensions
 
 The following primitives can be used to print to the console or to exit a simulation;
-```
+```c
 
 #define CSR_SIM_CTRL_EXIT (0 << 24)
 #define CSR_SIM_CTRL_PUTC (1 << 24)

From b18333ef4ed07b7470ce0f145ef4c8d1b893622d Mon Sep 17 00:00:00 2001
From: parker-research <166864283+parker-research@users.noreply.github.com>
Date: Fri, 1 Nov 2024 00:30:23 -0600
Subject: [PATCH 7/9] Update gitignore

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 8fa39db..ab885db 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@ verilated/
 *.o
 *.vcd
 test.x
+riscv-sim

From 5839d7231ae7e2f387e6dc5bb9e08ba588718549 Mon Sep 17 00:00:00 2001
From: parker-research <166864283+parker-research@users.noreply.github.com>
Date: Sun, 3 Nov 2024 18:52:06 -0700
Subject: [PATCH 8/9] Add locals and screen to Dockerfile

---
 Dockerfile | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Dockerfile b/Dockerfile
index 839a759..d290365 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -27,7 +27,9 @@ RUN apt-get update && apt-get install -y \
     git \
     sudo \
     wget \
-    curl
+    curl \
+    screen \
+    locales
 
 # Install SystemC.
 # Guide: https://gist.github.com/bagheriali2001/0736fabf7da95fb02bbe6777d53fabf7
@@ -86,6 +88,12 @@ ENV LD_LIBRARY_PATH=/systemc/systemc-2.3.3/lib-linux64
 # The following folder must contain `verilated.cpp` file.
 ENV VERILATOR_SRC=/usr/local/share/verilator/include
 
+# Set locale variables to avoid warnings.
+ENV LANG=en_US.UTF-8
+ENV LANGUAGE=en_US:en
+ENV LC_ALL=en_US.UTF-8
+RUN locale-gen $LANG
+RUN locale-gen $LC_ALL
 
 # Create a working directory
 WORKDIR /project

From 304efc1a383b5f37d8b7731dcf9fe1a53ef6864f Mon Sep 17 00:00:00 2001
From: parker-research <166864283+parker-research@users.noreply.github.com>
Date: Thu, 7 Nov 2024 15:56:04 -0500
Subject: [PATCH 9/9] Add Dockerfile usage instructions to README

---
 README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/README.md b/README.md
index 387b429..fa1fc83 100644
--- a/README.md
+++ b/README.md
@@ -101,6 +101,27 @@ cd top_tcm_axi/tb
 make run
 ```
 
+### Testbench Using Docker
+
+To run the testbench using the provided Dockerfile, run:
+
+```bash
+# 1. Build the Docker container:
+docker build -t riscv_build .
+
+# 2. Start Docker container:
+docker run -it --rm --user (id -u):(id -g) -v (pwd):/project riscv_build
+# Press enter again.
+
+# 3. Inside the Docker container's shell, run:
+cd cd top_tcm_axi/tb
+make run
+
+# 4. Run an arbitary .elf file.
+./build/test.x -f ../../isa_sim/images/basic.elf
+./build/test.x -f ../../isa_sim/images/linux.elf -b 0x80000000 -s 33554432
+```
+
 ## Example Core Instance (with caches)
 
 The top (top_cache_axi/src_v/riscv_top.v) contains;