Add shell.nix for Nix-based PicoRV32 development

The net result of this is that cd'ing into the main source directory and
running:

    $ nix-shell

will get you every tool needed to immediately do RISC-V development with
picorv32 or picosoc (assuming you're targeting ICE40 or ECP5).

The shell.nix file contains many comments on how to use the resulting
environment.

Signed-off-by: Austin Seipp <aseipp@pobox.com>

1 files changed, 139 insertions, 0 deletions

diff --git a/shell.nix b/shell.nix
new file mode 100644
index 0000000..92ec1ff
--- /dev/null
+++ b/shell.nix
@@ -0,0 +1,139 @@
+# nix.shell: PicoRV32 Development Environment
+#
+# This file allows you to use the Nix Package Manager (https://nixos.org/nix)
+# in order to download, install, and prepare a working environment for doing
+# PicoRV32/PicoSoC development on _any_ existing Linux distribution, provided
+# the Nix package manager is installed.
+#
+# Current included tools:
+#
+#   - Synthesis: Recent Yosys and SymbiYosys
+#   - Place and Route: arachne-pnr and nextpnr (ICE40, ECP5, Python, no GUI)
+#   - Packing: Project IceStorm (Trellis tools may be included later?)
+#   - SMT Solvers: Z3 4.7.x, Yices 2.6.x, and Boolector 3.0.x
+#   - Verification: Recent Verilator, Recent (unreleased) Icarus Verilog
+#   - A bare-metal RISC-V cross compiler toolchain, based on GCC 8.2.x
+#
+# With these tools, you can immediately begin development, simulation, firmware
+# hacking, etc with almost no need to fiddle with recent tools yourself. Almost
+# all of the tools will be downloaded on-demand (except the GCC toolchain)
+# meaning you don't have to compile any recent tools yourself. Due to the
+# "hermetic" nature of Nix, these packages should also work on practically any
+# Linux distribution, as well.
+#
+# (This environment should also be suitable for running riscv-formal test
+# harnesses on PicoRV32, as well. In fact it is probably useful for almost
+# _any_ RTL implementation of the RV32I core.)
+#
+# Usage
+# -----
+#
+# At the top-level of the picorv32 directory, simply run the 'nix-shell' command,
+# which will then drop you into a bash prompt:
+#
+#
+#     $ nix-shell
+#     ...
+#     [nix-shell:~/src/picorv32]$
+#
+#
+# When you run 'nix-shell', you will automatically begin downloading all of the
+# various tools you need from an upstream "cache", so most of this will execute
+# very quickly. However, this may take a while, as you will at least have to
+# build a cross-compiled RISC-V toolchain, which may take some time. (These
+# binaries are not available from the cache, so they must be built by you.) Once
+# you have done this once, you do not need to do it again.
+#
+# At this point, once you are inside the shell, you can begin running tests
+# like normal. For example, to run the Verilator tests with the included test
+# firmware, which is substantially faster than Icarus:
+#
+#     [nix-shell:~/src/picorv32]$ make test_verilator TOOLCHAIN_PREFIX=riscv32-unknown-elf-
+#     ...
+#
+#
+# Note that you must override TOOLCHAIN_PREFIX (in the top-level Makefile, it
+# looks in /opt by default).
+#
+# This will work immediately with no extra fiddling necessary. You can also run
+# formal verification tests using a provided SMT solver, for example, yices and
+# boolector (Z3 is not used since it does not complete in a reasonable amount
+# of time for these examples):
+#
+#     [nix-shell:~/src/picorv32]$ make check-yices check-boolector
+#     ...
+#
+# You can also run the PicoSoC tests and build bitstreams. To run the
+# simulation tests and then build bitstreams for the HX8K and IceBreaker
+# boards:
+#
+#     [nix-shell:~/src/picorv32]$ cd picosoc/
+#     [nix-shell:~/src/picorv32/picosoc]$ make hx8ksynsim icebsynsim
+#     ...
+#     [nix-shell:~/src/picorv32/picosoc]$ make hx8kdemo.bin icebreaker.bin
+#     ...
+#
+# The HX8K simulation and IceBreaker simulation will be synthesized with Yosys
+# and then run with Icarus Verilog. The bitstreams for HX8K and IceBreaker will
+# be P&R'd with arachne-pnr and nextpnr, respectively.
+#
+
+{ architecture ? "rv32imc"
+}:
+
+# TODO FIXME: fix this to a specific version of nixpkgs.
+# ALSO: maybe use cachix to make it easier for contributors(?)
+with import <nixpkgs> {};
+
+let
+  # risc-v toolchain source code. TODO FIXME: this should be replaced with
+  # upstream versions of GCC. in the future we could also include LLVM (the
+  # upstream nixpkgs LLVM expression should be built with it in time)
+  riscv-toolchain-ver = "8.2.0";
+  riscv-src = pkgs.fetchFromGitHub {
+    owner  = "riscv";
+    repo   = "riscv-gnu-toolchain";
+    rev    = "c3ad5556197e374c25bc475ffc9285b831f869f8";
+    sha256 = "1j9y3ai42xzzph9rm116sxfzhdlrjrk4z0v4yrk197j72isqyxbc";
+    fetchSubmodules = true;
+  };
+
+  # given an architecture like 'rv32i', this will generate the given
+  # toolchain derivation based on the above source code.
+  make-riscv-toolchain = arch:
+    stdenv.mkDerivation rec {
+      name    = "riscv-${arch}-toolchain-${version}";
+      version = "${riscv-toolchain-ver}-${builtins.substring 0 7 src.rev}";
+      src     = riscv-src;
+
+      configureFlags   = [ "--with-arch=${arch}" ];
+      installPhase     = ":"; # 'make' installs on its own
+      hardeningDisable = [ "all" ];
+      enableParallelBuilding = true;
+
+      # Stripping/fixups break the resulting libgcc.a archives, somehow.
+      # Maybe something in stdenv that does this...
+      dontStrip = true;
+      dontFixup = true;
+
+      nativeBuildInputs = with pkgs; [ curl gawk texinfo bison flex gperf ];
+      buildInputs = with pkgs; [ libmpc mpfr gmp expat ];
+    };
+
+  riscv-toolchain = make-riscv-toolchain architecture;
+
+  # These are all the packages that will be available inside the nix-shell
+  # environment.
+  buildInputs = with pkgs;
+    # these are generally useful packages for tests, verification, synthesis
+    # and deployment, etc
+    [ python3 gcc
+      yosys symbiyosys nextpnr arachne-pnr icestorm
+      z3 boolector yices
+      verilog verilator
+      # also include the RISC-V toolchain
+      riscv-toolchain
+    ];
+
+# Export a usable shell environment
+in runCommand "picorv32-shell" { inherit buildInputs; } ""