From 06ccf912225e17582bf28bfa7e97ed31f0e7979f Mon Sep 17 00:00:00 2001
From: Ross Thompson <ross1728@gmail.com>
Date: Sat, 21 Jan 2023 22:20:53 -0600
Subject: [PATCH] Readme formatting.

---
 README.md | 203 +++++++++++++++++++++++++++---------------------------
 1 file changed, 102 insertions(+), 101 deletions(-)

diff --git a/README.md b/README.md
index 6092fd74d..7c646a0f5 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,7 @@ This section describes the open source toolchain installation.  These steps shou
 The full instalation details are involved can be be skipped using the following script, wally-tool-chain-install.sh.
 The script installs the open source tools to /opt/riscv by default.  This can be changed by supply the path as the first argument.  This script does not install buildroot (see the Detailed Tool-chain Install Guide in the following section) and does not install commercial EDA tools; Siemens Questa, Synopsys Design Compiler, or Cadence Innovus (see section Installing IDA Tools). It must be run as root or with sudo. This script is tested for Ubuntu, 20.04 and 22.04. Fedora and Red Hat can be installed in the Detailed Tool-chain Install Guide.
 
-wally-tool-chain-install.sh <optional, install directory, defaults to /opt/riscv>
+	wally-tool-chain-install.sh <optional, install directory, defaults to /opt/riscv>
 
 ## Detailed Tool-chain Install Guide
 
@@ -49,11 +49,11 @@ wally-tool-chain-install.sh <optional, install directory, defaults to /opt/riscv
 
 Compiling, assembling, and simulating RISC-V programs requires downloading and installing the following free tools:
 
-1.	The GCC cross-compiler
-2.	A RISC-V simulator such as Spike, Sail, and/or QEMU
-3.      Spike is easy to use but doesn’t support peripherals to boot Linux
-4.	QEMU is faster and can boot Linux
-5.	Sail is presently the official golden reference for RISC-V and is used by the riscof verification suite, but runs slowly and is painful to instal
+	1. The GCC cross-compiler
+	2. A RISC-V simulator such as Spike, Sail, and/or QEMU
+	3. Spike is easy to use but doesn’t support peripherals to boot Linux
+	4. QEMU is faster and can boot Linux
+	5. Sail is presently the official golden reference for RISC-V and is used by the riscof verification suite, but runs slowly and is painful to instal
 
 This setup needs to be done once by the administrator
 
@@ -65,32 +65,32 @@ Note: Installing software in Linux is unreasonably touchy and varies with the fl
 
 First, set up a directory for riscv software in some place such as /opt/riscv.  We will call this shared directory $RISCV.
 
-$ export RISCV=/opt/riscv
-$ sudo mkdir $RISCV
-$ sudo chown cad $RISCV
-$ sudo su cad  (or root, if you don’t have a cad account)
-$ export RISCV=/opt/riscv
-$ chmod 755 $RISCV
-$ umask 0002
-$ cd $RISCV
+	$ export RISCV=/opt/riscv
+	$ sudo mkdir $RISCV
+	$ sudo chown cad $RISCV
+	$ sudo su cad  (or root, if you don’t have a cad account)
+	$ export RISCV=/opt/riscv
+	$ chmod 755 $RISCV
+	$ umask 0002
+	$ cd $RISCV
 
 ### Update Tools
 
 Ubuntu users may need to install and update various tools.
 
-$ sudo apt update
-$ sudo apt upgrade
-$ sudo apt install git gawk make texinfo bison flex build-essential python libz-dev libexpat-dev autoconf device-tree-compiler ninja-build libglib2.56-dev libpixman-1-dev build-essential ncurses-base ncurses-bin libncurses5-dev dialog 
+	$ sudo apt update
+	$ sudo apt upgrade
+	$ sudo apt install git gawk make texinfo bison flex build-essential python libz-dev libexpat-dev autoconf device-tree-compiler ninja-build libglib2.56-dev libpixman-1-dev build-essential ncurses-base ncurses-bin libncurses5-dev dialog 
 
 ### Install RISC-V GCC Cross-Compiler
 
 To install GCC from source can take hours to compile. This configuration enables multilib to target many flavors of RISC-V.   This book is tested with GCC 12.2 (tagged 2022.09.21), but will likely work with newer versions as well. 
 
-$ git clone https://github.com/riscv/riscv-gnu-toolchain 
-$ cd riscv-gnu-toolchain 
-$ git checkout 2022.09.21 
-$ ./configure --prefix=$RISCV --enable-multilib --with-multilib-generator="rv32e-ilp32e--;rv32i-ilp32--;rv32im-ilp32--;rv32iac-ilp32--;rv32imac-ilp32--;rv32imafc-ilp32f--;rv32imafdc-ilp32d--;rv64i-lp64--;rv64ic-lp64--;rv64iac-lp64--;rv64imac-lp64--;rv64imafdc-lp64d--;rv64im-lp64--;"
-$ make --jobs
+	$ git clone https://github.com/riscv/riscv-gnu-toolchain 
+	$ cd riscv-gnu-toolchain 
+	$ git checkout 2022.09.21 
+	$ ./configure --prefix=$RISCV --enable-multilib --with-multilib-generator="rv32e-ilp32e--;rv32i-ilp32--;rv32im-ilp32--;rv32iac-ilp32--;rv32imac-ilp32--;rv32imafc-ilp32f--;rv32imafdc-ilp32d--;rv64i-lp64--;rv64ic-lp64--;rv64iac-lp64--;rv64imac-lp64--;rv64imafdc-lp64d--;rv64im-lp64--;"
+	$ make --jobs
 
 Note: make --jobs will reduce compile time by compiling in parallel.  However, adding this option could dramatically increase the memory utilization of your local machine.
 
@@ -98,14 +98,14 @@ Note: make --jobs will reduce compile time by compiling in parallel.  However, a
 
 We also need the elf2hex utility to convert executable files into hexadecimal files for Verilog simulation. Install with:
 
-$ cd $RISCV
-$ export PATH=$RISCV/riscv-gnu-toolchain/bin:$PATH
-$ git clone https://github.com/sifive/elf2hex.git
-$ cd elf2hex
-$ autoreconf -i
-$ ./configure --target=riscv64-unknown-elf --prefix=$RISCV
-$ make 
-$ make install 
+	$ cd $RISCV
+	$ export PATH=$RISCV/riscv-gnu-toolchain/bin:$PATH
+	$ git clone https://github.com/sifive/elf2hex.git
+	$ cd elf2hex
+	$ autoreconf -i
+	$ ./configure --target=riscv64-unknown-elf --prefix=$RISCV
+	$ make 
+	$ make install 
 
 Note: The exe2hex utility that comes with Spike doesn’t work for our purposes because it doesn’t handle programs that start at 0x80000000. The SiFive version above is touchy to install. For example, if Python version 2.x is in your path, it won’t install correctly.  Also, be sure riscv64-unknown-elf-objcopy shows up in your path in $RISCV/riscv-gnu-toolchain/bin at the time of compilation, or elf2hex won’t work properly.
 
@@ -113,16 +113,16 @@ Note: The exe2hex utility that comes with Spike doesn’t work for our purposes
 
 Spike also takes a while to install and compile, but this can be done concurrently with the GCC installation.  After the build, we need to change two Makefiles to support atomic instructions .
 
-$ cd $RISCV
-$ git clone https://github.com/riscv-software-src/riscv-isa-sim
-$ mkdir riscv-isa-sim/build
-$ cd riscv-isa-sim/build
-$ ../configure --prefix=$RISCV --enable-commitlog 
-$ make --jobs
-$ make install 
-$ cd ../arch_test_target/spike/device
-$ sed -i 's/--isa=rv32ic/--isa=rv32iac/' rv32i_m/privilege/Makefile.include
-$ sed -i 's/--isa=rv64ic/--isa=rv64iac/' rv64i_m/privilege/Makefile.include 
+	$ cd $RISCV
+	$ git clone https://github.com/riscv-software-src/riscv-isa-sim
+	$ mkdir riscv-isa-sim/build
+	$ cd riscv-isa-sim/build
+	$ ../configure --prefix=$RISCV --enable-commitlog 
+	$ make --jobs
+	$ make install 
+	$ cd ../arch_test_target/spike/device
+	$ sed -i 's/--isa=rv32ic/--isa=rv32iac/' rv32i_m/privilege/Makefile.include
+	$ sed -i 's/--isa=rv64ic/--isa=rv64iac/' rv64i_m/privilege/Makefile.include 
 
 ### Install Sail Simulator
 
@@ -134,43 +134,43 @@ $ sudo apt-get install opam  build-essential libgmp-dev z3 pkg-config zlib1g-dev
 
 If you are on RedHat/Rocky Linux 8, installation is much more difficult because packages are not available in the default package manager and some need to be built from source.
 
-$ sudo bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)"
+	$ sudo bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)"
 	When prompted, put it in /usr/bin
-$ sudo yum groupinstall 'Development Tools'
-$ sudo yum -y install gmp-devel
-$ sudo yum -y install zlib-devel
-$ git clone https://github.com/Z3Prover/z3.git 
-$ cd z3
-$ python scripts/mk_make.py
-$ cd build
-$ make
-$ sudo make install
-$ cd ../..
-$ sudo pip3 install chardet==3.0.4
-$ sudo pip3 install urllib3==1.22
+	$ sudo yum groupinstall 'Development Tools'
+	$ sudo yum -y install gmp-devel
+	$ sudo yum -y install zlib-devel
+	$ git clone https://github.com/Z3Prover/z3.git 
+	$ cd z3
+	$ python scripts/mk_make.py
+	$ cd build
+	$ make
+	$ sudo make install
+	$ cd ../..
+	$ sudo pip3 install chardet==3.0.4
+	$ sudo pip3 install urllib3==1.22
 
 Once you have installed the packages on either Ubuntu or RedHat, use opam to install the OCaml compiler and Sail.  Run as the cad user because you will be installing Sail in $RISCV.
 
-$ sudo su cad
-$ opam init -y --disable-sandboxing
-$ opam switch create ocaml-base-compiler.4.06.1
-$ opam install sail -y
+	$ sudo su cad
+	$ opam init -y --disable-sandboxing
+	$ opam switch create ocaml-base-compiler.4.06.1
+	$ opam install sail -y
 
 Now you can clone and compile Sail-RISCV.  This will take a while.
 
-$ eval $(opam config env)
-$ cd $RISCV
-$ git clone https://github.com/riscv/sail-riscv.git
-$ cd sail-riscv
-$ make
-$ ARCH=RV32 make
-$ ARCH=RV64 make
-$ exit
-$ sudo su
-$ export RISCV=/opt/riscv
-$ ln -s $RISCV/sail-riscv/c_emulator/riscv_sim_RV64 /usr/bin/riscv_sim_RV64
-$ ln -s $RISCV/sail-riscv/c_emulator/riscv_sim_RV32 /usr/bin/riscv_sim_RV32
-$ exit
+	$ eval $(opam config env)
+	$ cd $RISCV
+	$ git clone https://github.com/riscv/sail-riscv.git
+	$ cd sail-riscv
+	$ make
+	$ ARCH=RV32 make
+	$ ARCH=RV64 make
+	$ exit
+	$ sudo su
+	$ export RISCV=/opt/riscv
+	$ ln -sf $RISCV/sail-riscv/c_emulator/riscv_sim_RV64 /usr/bin/riscv_sim_RV64
+	$ ln -sf $RISCV/sail-riscv/c_emulator/riscv_sim_RV32 /usr/bin/riscv_sim_RV32
+	$ exit
 
 ### Install riscof
 
@@ -178,8 +178,8 @@ riscof is a Python library used as the RISC-V compatibility framework test an im
 
 It is most convenient if the sysadmin installs riscof into the server’s Python libraries:
 
-$ sudo pip3 install testresources
-$ sudo pip3 install riscof --ignore-installed PyYAML
+	$ sudo pip3 install testresources
+	$ sudo pip3 install riscof --ignore-installed PyYAML
 
 However, riscof can also be installed and run locally by individual users.
 
@@ -196,13 +196,13 @@ QEMU is another simulator used when booting Linux in Chapter 17. You can optiona
 The QEMU patch changes the VirtIO driver to match the Wally peripherals, and also adds print statements to log the state of the CSRs (see Section 2.5XREF).
 </END>
 
-$ cd $RISCV
-$ git clone --recurse-submodules https://github.com/qemu/qemu
-$ cd qemu
-$ git checkout v6.2.0    # last version tested; newer versions might be ok
-$ ./configure --target-list=riscv64-softmmu --prefix=$RISCV
-$ make --jobs
-$ make install
+	$ cd $RISCV
+	$ git clone --recurse-submodules https://github.com/qemu/qemu
+	$ cd qemu
+	$ git checkout v6.2.0    # last version tested; newer versions might be ok
+	$ ./configure --target-list=riscv64-softmmu --prefix=$RISCV
+	$ make --jobs
+	$ make install
 
 ### Cross-Compile Buildroot Linux
 
@@ -212,14 +212,14 @@ Buildroot depends on configuration files in riscv-wally, so the cad user must in
 
 To configure and build Buildroot:
 
-$ cd $RISCV
-$ export WALLY=~/riscv-wally  # make sure you haven’t sourced ~/riscv-wally/setup.sh by now
-$ git clone https://github.com/buildroot/buildroot.git
-$ cd buildroot
-$ git checkout 2021.05 # last tested working version
-$ cp -r $WALLY/linux/buildroot-config-src/wally ./board
-$ cp ./board/wally/main.config .config
-$ make --jobs
+	$ cd $RISCV
+	$ export WALLY=~/riscv-wally  # make sure you haven’t sourced ~/riscv-wally/setup.sh by now
+	$ git clone https://github.com/buildroot/buildroot.git
+	$ cd buildroot
+	$ git checkout 2021.05 # last tested working version
+	$ cp -r $WALLY/linux/buildroot-config-src/wally ./board
+	$ cp ./board/wally/main.config .config
+	$ make --jobs
 
 To generate disassembly files and the device tree, run another make script.  Note that you can expect some warnings about phandle references while running dtc on wally-virt.dtb.
 
@@ -233,11 +233,11 @@ Note: When the make tasks complete, you’ll find source code in $RISCV/buildroo
 
 For logic synthesis, we need a synthesis tool (see Section 3.XREF) and a cell library.  Clone the OSU 12-track cell library for the Skywater 130 nm process:
 
-$ cd $RISCV
-$ mkdir cad
-$ mkdir cad/lib
-$ cd cad/lib
-$ git clone https://foss-eda-tools.googlesource.com/skywater-pdk/libs/sky130_osu_sc_t12
+	$ cd $RISCV
+	$ mkdir cad
+	$ mkdir cad/lib
+	$ cd cad/lib
+	$ git clone https://foss-eda-tools.googlesource.com/skywater-pdk/libs/sky130_osu_sc_t12
 
 ## Installing EDA Tools
 
@@ -258,7 +258,7 @@ Synopsys Design Compiler (DC)
 
 Many commercial synthesis and place and route tools require a common installer.  These installers are provided by the EDA vendor and Synopsys has one called Synopsys Installer.  To use Synopsys Installer, you will need to acquire a license through Synopsys that is typically Called Synopsys Common Licensing (SCL).  Both the Synopsys Installer, license key file, and Design Compiler can all be downloaded through Synopsys Solvnet.  First open a web browser, log into Synsopsy Solvnet, and download the installer and Design Compiler installation files.  Then, install the Installer
 
-$ firefox &
+	$ firefox &
 Navigate to https://solvnet.synopsys.com
 Log in with your institution’s username and password
 Click on Downloads, then scroll down to Synopsys Installer
@@ -268,19 +268,20 @@ Return to downloads and also get Design Compiler (synthesis) latest version, and
 	Click on all parts and the .spf file, then click Download Files near the top
 move the SynopsysIntaller into /cad/synopsys/Installer_5.4 with 755 permission for cad, 
 move other files into /cad/synopsys/downloads and work as user cad from here on
-$ cd /cad/synopsys/installer_5.4
-$ ./SynopsysInstaller_v5.4.run
-Accept default installation directory
-$ ./installer
-Enter source path as /cad/synopsys/downloads, and installation path as /cad/synopsys
-When prompted, enter your site ID
-Follow prompts
+
+	$ cd /cad/synopsys/installer_5.4
+	$ ./SynopsysInstaller_v5.4.run
+	Accept default installation directory
+	$ ./installer
+	Enter source path as /cad/synopsys/downloads, and installation path as /cad/synopsys
+	When prompted, enter your site ID
+	Follow prompts
 
 Installer can be utilized in graphical or text-based modes.  It is far easier to use the text-based installation tool.  To install DC, navigate to the location where your downloaded DC files are and type installer.  You should be prompted with questions related to where you wish to have your files installed.  
 
 The Synopsys Installer automatically installs all downloaded product files into a single top-level target directory. You do not need to specify the installation directory for each product. For example, if you specify /import/programs/synopsys as the target directory, your installation directory structure might look like this after installation:
 
-/import/programs/synopsys/syn/S-2021.06-SP1
+	/import/programs/synopsys/syn/S-2021.06-SP1
 
 Note: Although most parts of Wally, including the software used in this chapter and Questa simulation, will work on most modern Linux platforms, as of 2022, the Synopsys CAD tools for SoC design are only supported on RedHat Enterprise Linux 7.4 or 8 or SUSE Linux Enterprise Server (SLES) 12 or 15. Moreover, the RISC-V formal specification (sail-riscv) does not build gracefully on RHEL7.