diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ab885db --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +verilated/ +*.a +*.o +*.vcd +test.x +riscv-sim diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..d290365 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,113 @@ +# 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 + +# 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 \ + git \ + sudo \ + wget \ + curl \ + screen \ + locales + +# 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 + +# ################################ +# ### 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 ########### +# ################################ + + +# 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 + +# 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 + +# 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/local/bin/fish"] +# ENTRYPOINT ["/bin/bash"] diff --git a/README.md b/README.md index c83f987..fa1fc83 100644 --- a/README.md +++ b/README.md @@ -86,20 +86,41 @@ 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 -```` +``` + +### 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) 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)