# Artifact for DimSum: A Decentralized Approach to Multi-language Semantics and Verification

This is the artifact for the paper "DimSum: A Decentralized Approach
to Multi-language Semantics and Verification". It contains a
VirtualBox virtual machine with the development already prebuilt and
manual installation instructions using opam.

## List of Claims
The main claim of this artifact is that the description in the paper corresponds
to the Coq development (modulo small simplifications for presentation purposes).
The mapping from concepts in the paper to the Coq development can be found below
under "Guide through the Coq development" and a recommendation for how to evaluate
the artifact can be found under "Evaluation instructions".

An additional claim is that Coq development only depends on the axioms
listed under "Axioms" below.

## Installation instructions and sanity-testing
This artifact contains both the raw source-code of DimSum
(`dimsum_artifact.tgz`) and a virtual machine containing the source-code
with all dependencies already installed (`artifact.ova`). We recommend using
the virtual machine unless you are an experienced opam user.


### Use the virtual machine (artifact.ova)
To use the virtual machine, please install
[VirtualBox](https://www.virtualbox.org/wiki/Downloads) (version 6.1.18
is tested) and open `artifact.ova`. This VM contains all necessary
dependencies of DimSum and contains a prebuilt version of `dimsum_artifact.tgz`
in `~/Desktop/dimsum_artifact`. To check that everything is installed
correctly, please navigate with a shell to `~/Desktop/dimsum_artifact/dimsum/`
and run
```
make -j4
```
It should output the following as everything is prebuilt:
```
make[1]: Entering directory '/home/vagrant/Desktop/dimsum_artifact/dimsum'
make[2]: Nothing to be done for 'real-all'.
make[1]: Leaving directory '/home/vagrant/Desktop/dimsum_artifact/dimsum'
```

The user of the VM image is "vagrant" and the password also "vagrant".
The VM comes with the VirtualBox Guest Additions installed, so the
screen size should change automatically when resizing the window. It
might be necessary to resize the window once for the automatic
resizing to kick in. To change the keyboard layout, go to
"Applications > Settings > Keyboard > Layout", add the desired variant
via "Add" and move it to the top.

The VM has coqide preinstalled in the opam switch in
`~/Desktop/dimsum_artifact/`. To open a `*.v` file in coqide, go to this
folder in the terminal and run e.g. `coqide dimsum/dimsum/module.v`.

### Installing the artifact locally (dimsum_artifact.tgz)
(Only tested on Linux and MacOS. Might work on Windows using WSL.)

To start using the artifact you must first install the dependencies
and also compile everything. To do this, we provide a script
`build_artifact.sh` which assumes that a suitable version of Opam
is available. To check this, you can run `opam --version`. You will
need at least version `2.1.0`. If you do not already have Opam then
follow [these instructions](https://opam.ocaml.org/doc/Install.html).

To build the artifact, run the following commands:
```bash
tar xf dimsum_artifact.tgz
cd dimsum_artifact
./build_artifact.sh
```
After the last command finishes everything has been compiled, and all
examples checked.

`./build_artifact.sh` creates an new opam switch in the artifact directory.
To make the Coq installation installed in this switch available,
run the following command inside the artifact directory:
```
eval $(opam env)
```
Afterwards, to test the installation, navigate to the `dimsum` folder and run
```
make -j4
```
It should output the following as everything is prebuilt:
```
make[1]: Entering directory '/home/vagrant/Desktop/dimsum_artifact/dimsum'
make[2]: Nothing to be done for 'real-all'.
make[1]: Leaving directory '/home/vagrant/Desktop/dimsum_artifact/dimsum'
```

## Overview of the artifact folder
The artifact folder mainly contains the following files and folders:
- Folder `dimsum` contains the source code of DimSum.
  - Subfolder `dimsum/dimsum` contains the general DimSum framework
    that is not specific to the Asm and Rec languages described in the
    paper.
  - Subfolder `dimsum/dimsum_examples` contains the instantiation of
    DimSum with Rec and Asm and the verification of the examples
    mentioned in the paper.
- File `appendix.pdf` contains the appendix for the main paper.

The following directories are dependencies that we
provide for easing the installation, **not part of the artifact proper**:
- Folders `coq-iris` and `coq-stdpp` provide the source code of the
  Iris framework for separation logic, and the std++ Coq library.

The remaining files and folders of the directory are less relevant:
- File `build_artifact.sh` is a script used to build the artifact.
- Folder `_opam` (created during installation) contains a local installation
  of OCaml and the packages required by the artifact.
- File `generation_data.txt` tracks the git commits that were used to
  create this artifact.
- File `README.md` is, well, this file.

In the following, all paths are given relative to the `dimsum` folder
in the toplevel artifact directory.

## Evaluation instructions
To evaluate this artifact, we propose the following steps:
1. Confirm that the Coq development compiles without problems.
   To do so, run `make clean` if you have previously built the Coq development or are using the VM.
   Thereafter, run `make -jN` where `N` is the number of cores you wish to use.
2. Search for `admit` or `Admitted.` in the source code files. As you
   will see, the development does not have any admits.
3. Read the Section "Differences to the paper" to familiarize yourself
   with the differences between the on-paper presentation and the Coq
   developement.
4. Step through the Coq development and compare the Theorems and
   Definitions with those from the paper. You can find a mapping from
   paper to Coq below in the section "Mapping between the paper and
   the Coq development". You can find the Coq files in the folder
   `dimsum`. To step through the proofs, you can use CoqIDE in the
   virtual machine.
5. Check that the axioms used in the development are only the ones
   listed under "Axioms" below. To do so, you can use grep in the
   `dimsum` folder:
   ```
   grep Axiom $(find . -name "*.v")
   grep Admitted $(find . -name "*.v")
   ```
   (Make sure to execute this command in the `dimsum` folder, not
   the toplevel artifact folder as otherwise the command might return
   results from other packages.)
   Additionally, one can use `Print Assumptions` to show the axioms used by
   key theorems. For example, add and execute `Print Assumptions complete_refinement.`
   and `Print Assumptions sim_trefines.` at the end of `dimsum_examples/memmove.v`.
6. Check that the Gitlab https://gitlab.mpi-sws.org/iris/dimsum
   hosting the project is publicly accessible, includes an issue
   tracker, and the code has an open source license. The commit that
   was used to generate the artifact can be found here:
   https://gitlab.mpi-sws.org/iris/dimsum/-/tree/7d5f0d636030173748e4a9e331e0d03718b8c8a6

## Differences to the paper
Before exploring the Coq development, note the following differences between the paper and the mechanization:
- The definition of the DimSum simulation is `sim` in `dimsum/proof_techniques.v`.
  For historic reasons, the Coq development mostly uses an equivalent definition: `trefines` in `dimsum/trefines.v`.
  The two definitions are proven equivalent by `sim_trefines` in `dimsum/proof_techniques.v`.
- Spec programs in the Coq development also have `put` and `get` constructors to access private state.
  This does not give additional expressive power but makes some Spec programs easier to write.
- As mentioned briefly in the paper, the instructions in Asm are composed of micro instructions.
  The instructions shown in the paper are `deep_asm_instr` in the mechanization.

## Mapping between the paper and the Coq development

Section 2:
- Verification of the running example including programs and specifications: `dimsum_examples/memmove.v`
- Proof rules in Figure 5:
  - `asm-link-syn`: `asm_syn_link_refines_link` and `asm_link_refines_syn_link` in `dimsum_examples/asm.v`
  - `rec-link-syn`: `rec_syn_link_refines_link` and `rec_link_refines_syn_link` in `dimsum_examples/rec.v`
  - `asm-link-horizontal`: `asm_link_trefines` in `dimsum_examples/asm.v`
  - `rec-link-horizontal`: `rec_link_trefines` in `dimsum_examples/rec.v`
  - `rec-wrapper-compat`: `rec_to_asm_trefines` in `dimsum_examples/rec_to_asm.v`
  - `compiler-correct`: `compile_correct` in `dimsum_examples/compiler/compiler.v`
  - `rec-to-asm-link`: `rec_to_asm_combine` in `dimsum_examples/rec_to_asm.v`
- Definition of the Rec to Asm wrapper: `rec_to_asm` in `dimsum_examples/rec_to_asm.v`

Section 3.1:
- Definition of module: `module` in `dimsum/module.v`
- Definition of the multi-step relation: `lhas_trace` in `dimsum/lrefines.v`
- Definition of refinement / simulation: `sim` in `dimsum/proof_techniques.v` / `trefines` in `dimsum/trefines.v`
- Lemma 3.1: `trefines_preorder` in `dimsum/trefines.v`
- Theorem 3.2: `trefines_lrefines` in `dimsum/refines_meta.v`

Section 3.2:
- Definition of the syntax of Spec: `spec` in `dimsum/spec.v`
- Definition of the semantics of Spec: `spec_mod` in `dimsum/spec_mod.v`

Section 3.3:
- Product: `seq_product_mod` in `dimsum/seq_product.v`
- Filter: `seq_map_mod` in `dimsum/seq_product.v`
  - Note that the filter is defined using more primitive combinators not discussed in the paper.
- Linking: `link_mod` in `dimsum/link.v`
- (Kripke) wrappers: `prepost_mod` in `dimsum/prepost.v`
- Rules in Figure 10:
  - `product-compat`: `seq_product_mod_trefines` in `dimsum/seq_product.v`
  - `filter-compat`: `seq_map_mod_trefines` in `dimsum/seq_product.v`
  - `link-compat`: `link_mod_trefines` in `dimsum/link.v`
  - `wrapper-compat`: `prepost_mod_trefines` in `dimsum/prepost.v`

Section 4:
- Definition of Asm:
  - Syntax: `deep_asm_instr` in `dimsum_examples/asm.v`
  - Module Semantics: `asm_mod`, `deep_to_asm_instrs` in `dimsum_examples/asm.v`
  - Syntactic Linking: `asm_syn_link` in `dimsum_examples/asm.v`
  - Semantic Linking: `asm_link` in `dimsum_examples/asm.v`
- Definition of Rec:
  - Syntax: `expr` in `dimsum_examples/rec.v`
  - Module Semantics: `rec_mod` in `dimsum_examples/rec.v`
  - Syntactic Linking: `rec_syn_link` in `dimsum_examples/rec.v`
  - Semantic Linking: `rec_link` in `dimsum_examples/rec.v`
- Coroutine Library:
  - Definition of the linking operator: `coro_link` in `dimsum_examples/coroutine.v`
  - `yield`: `yield_asm` in `dimsum_examples/coroutine.v`
  - `coro-link`: `coro_spec` in `dimsum_examples/coroutine.v`
  - Verification of the example: `dimsum_examples/coroutine_example.v`

Section 5:
- Compiler: `dimsum_examples/compiler/compiler.v`
  - Compiler correctness: compiler_correct in `dimsum_examples/compiler/compiler.v`
    - Note that the compiler_correct lemma only allows compiling
      single functions but they can be combined using
      `rec_to_asm_combine` in `dimsum_examples/rec_to_asm.v` and the equivalence
      of syntactic and semantic linking.
  - SSA pass: `dimsum_examples/compiler/ssa.v`
  - Linearize pass: `dimsum_examples/compiler/linearize.v`
  - Mem2Reg pass: `dimsum_examples/compiler/mem2reg.v`
  - Codegen pass: `dimsum_examples/compiler/codegen.v`
- Rec-to-Rec wrapper: `rec_heap_bij` in `dimsum_examples/rec_heap_bij.v`
- `rec-to-asm-vertical`: `r2a_bij_vertical` in `dimsum_examples/r2a_bij_vertical.v`

## Axioms
The development relies on the following non-constructive axioms (see `dimsum/axioms.v`):
* Functional form of the (non extensional) axiom of choice, Choice (`FunctionalChoice` of `Coq.Logic.ChoiceFacts`)
* (Dependent) Functional Extensionality, (D)FE (`functional_extensionality_dep` from `Coq.Logic.FunctionalExtensionality`)
* Proof Irrelevance, PI (`proof_irrelevance` from `Coq.Logic.ProofIrrelevance`)
* Excluded Middle (already implied by the combination of Choice and FE), XM (`classic` from `Coq.Logic.Classical_Prop`)
* Invariance by Substitution of Reflexive Equality Proofs (already implied XM), UIP (`Eq_rect_eq` from `Coq.Logic.EqdepFacts`)
These axioms [can be safely added to Coq](https://github.com/coq/coq/wiki/The-Logic-of-Coq#what-axioms-can-be-safely-added-to-coq).
