compliance: Start work on #27

- Documented a work flow for the compliance tests in tests/compliance/README.md

- A single (not very good) test for sha2sum0 is there as an example.

- Passes on Spike and SAIL (for what it's worth right now).

- Next steps are to generate the tests from the kat generator.

 On branch dev/next-release
 Your branch is up-to-date with 'origin/dev/next-release'.

 Changes to be committed:
	modified:   .gitmodules
	modified:   bin/conf.sh
	new file:   extern/riscv-compliance
	new file:   tests/compliance/Makefile
	new file:   tests/compliance/README.md
	new file:   tests/compliance/riscv-compliance.patch

 Changes not staged for commit:
	modified:   extern/riscv-compliance (modified content)
	modified:   extern/riscv-gnu-toolchain (modified content)
	modified:   extern/riscv-isa-sim (modified content)
	modified:   extern/sail-riscv (modified content, untracked content)

.gitmodules

@@ -10,3 +10,6 @@
 [submodule "extern/sail-riscv"]
 	path = extern/sail-riscv
 	url = https://github.com/rems-project/sail-riscv.git
+[submodule "extern/riscv-compliance"]
+	path = extern/riscv-compliance
+	url = https://github.com/riscv/riscv-compliance.git

bin/conf.sh

@@ -24,12 +24,19 @@ if [ -z $RISCV_ARCH ] ; then
 fi
 
 export RISCV=$REPO_BUILD/$RISCV_ARCH
+export SAIL_RISCV=$REPO_HOME/extern/sail-riscv
+
+[[ ":$PATH:" != *":$RISCV/bin:"* ]] && export PATH="${RISCV}/bin:${PATH}"
+[[ ":$PATH:" != *":$SAIL_RISCV/c_emulator:"* ]] && export PATH="$SAIL_RISCV/c_emulator:${PATH}"
+[[ ":$PATH:" != *":$SAIL_RISCV/ocaml_emulator:"* ]] && export PATH="$SAIL_RISCV/ocaml_emulator:${PATH}"
 
 echo "REPO_HOME  = $REPO_HOME"
 echo "REPO_BUILD = $REPO_BUILD"
 echo "RISCV_ARCH = $RISCV_ARCH"
 echo "RISCV      = $RISCV"
 echo "YOSYS_ROOT = $YOSYS_ROOT"
+echo "SAIL_RISCV = $SAIL_RISCV"
+echo "PATH       = $PATH"
 
 echo "------------------------------"
 

tests/compliance/Makefile

@@ -0,0 +1,34 @@
+
+ifndef REPO_HOME
+    $(error "Please run 'source ./bin/conf.sh' to setup the project workspace")
+endif
+
+COMPLIANCE_REPO=$(REPO_HOME)/extern/riscv-compliance
+COMPLIANCE_PATCH=$(REPO_HOME)/tests/compliance/riscv-compliance.patch
+
+compliance-revert-patch:
+	cd $(COMPLIANCE_REPO) && git reset HEAD && git checkout . && git clean -dxf
+
+compliance-apply-patch:
+	cd $(COMPLIANCE_REPO) && git apply $(COMPLIANCE_PATCH)
+	cd $(COMPLIANCE_REPO) && git add .
+
+compliance-update-patch:
+	cd $(COMPLIANCE_REPO) && git diff --cached > $(COMPLIANCE_PATCH)
+
+
+compliance-run-spike:
+	$(MAKE) -C $(COMPLIANCE_REPO) RISCV_PREFIX=riscv64-unknown-elf \
+        RISCV_TARGET=spike
+
+compliance-run-sail-csim:
+	$(MAKE) -C $(COMPLIANCE_REPO) RISCV_PREFIX=riscv64-unknown-elf \
+        RISCV_TARGET=sail-riscv-c
+
+compliance-run-sail-ocaml:
+	$(MAKE) -C $(COMPLIANCE_REPO) RISCV_PREFIX=riscv64-unknown-elf \
+        RISCV_TARGET=sail-riscv-ocaml
+
+compliance-run-all: compliance-run-spike        \
+                    compliance-run-sail-csim    \
+                    compliance-run-sail-ocaml

tests/compliance/README.md

@@ -0,0 +1,94 @@
+
+# RISC-V Crypto Compliance Tests
+
+*Work in progress compliance test development framework.*
+
+---
+
+## Useful Links
+
+- [RISC-V Compliance Github Repo](https://github.com/riscv/riscv-compliance)
+  - [Documentation](https://github.com/riscv/riscv-compliance/tree/master/doc)
+
+
+## Getting Started
+
+- Make sure that you are in the root of the `riscv-crypto` repository, and
+  run the workspace setup script:
+
+  ```
+  source bin/conf.sh
+  ```
+
+  This makes sure that the `spike` and `sail` simulators (if they are
+  built) are in the `$PATH`, which is needed by the compliance framework.
+
+- Ensure the riscv-compliance sub-module is checked out:
+
+  ```
+  git submodule update --init extern/riscv-compliance
+  ```
+
+- The compliance tests are currently maintained as a patch to a known-good
+  commit of the riscv-compliance repository.
+  Once the riscv-compliance repo submodule is checked out, the following
+  commands can be used to manage the patch.
+
+  - Apply the patch to the submodule:
+
+    ```
+    make -C tests/compliance compliance-apply-patch
+    ```
+
+    This applies the `tests/compliance/riscv-compliance.patch` to
+    the submodule, and stages the modifications.
+
+  - Revert the patch:
+
+    ```
+    make -C tests/compliance compliance-revert-patch
+    ```
+
+    This puts the riscv-compliance sub-module pack to an un-modified state.
+
+  - Update the patch:
+
+    ```
+    make -C tests/compliance compliance-update-patch
+    ```
+
+    This takes all of the *staged* changes in the riscv-compliance
+    submodule, and updates the patch file in the riscv-crypto
+    repository.
+
+
+## Running the compliance tests
+
+- Run:
+
+  ```make
+  make -C extern/riscv-compliance RISCV_TARGET=<target> RISCV_DEVICE=<device> RISCV_PREFIX=riscv64-unknown-elf
+  ```
+
+  Where:
+
+  - `target` is one of `spike`, `sail-riscv-c` or `sail-riscv-ocaml`
+
+    and
+
+  - `device` is `rv32ik` or `rv64ik`, indicating the base 32/64-bit integer
+    ISA, with support for the Crypto extension.
+
+
+- Alternativley, run these short commands:
+
+  ```make
+  make -C tests/compliance compliance-run-spike
+  make -C tests/compliance compliance-run-sail-csim
+  make -C tests/compliance compliance-run-sail-ocaml
+  make -C tests/compliance compliance-run-all
+  ```
+
+  Which just wrap up the above long-form commands and run all of the
+  available compliance tests.
+