Add alternative emulation through unicorn engine

.github/workflows/build.yml

@@ -20,6 +20,11 @@ jobs:
         sudo apt install -y build-essential ninja-build libglib2.0-dev libfdt-dev libpixman-1-dev zlib1g-dev libprotobuf-c-dev protobuf-compiler protobuf-c-compiler libcap-dev
         pip install -r requirements.txt
 
+    - name: Install latest stable Rust toolchain
+      uses: actions-rs/toolchain@v1
+      with:
+          toolchain: stable
+
     - name: Checkout submodules
       run: git submodule update --init
 
@@ -29,6 +34,9 @@ jobs:
     - name: Build Faultplugin
       run: cd faultplugin; make -j; echo "done"
 
+    - name: Build Emulation Worker
+      run: cd emulation_worker; cargo build --release; mv target/release/libemulation_worker.so ../emulation_worker.so; echo "done"
+
     - name: Run ARCHIE
       run: cd examples/stm32; ./run.sh; cd ../riscv64; ./run.sh; cd ../stm32-timeout-wfi; ./run.sh; cd ../aarch64-softmmu; ./run.sh
 
@@ -49,6 +57,28 @@ jobs:
           examples/aarch64-softmmu/*.txt
           examples/aarch64-softmmu/*.hdf5
 
+    - name: Clean test results
+      run: |
+        rm examples/*/log*.txt
+        rm examples/*/output.hdf5
+
+    - name: Run ARCHIE Unicorn
+      run: cd examples/stm32; ./run.sh --unicorn; cd ../riscv64; ./run.sh --unicorn
+
+    - name: Synchronize cached writes for artifact storage
+      run: sync
+
+    - name: Upload test artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: test-artifacts-unicorn
+        path: |
+          examples/riscv64/*.txt
+          examples/riscv64/*.hdf5
+          examples/stm32/*.txt
+          examples/stm32/*.hdf5
+
+
   build_with_script:
     name: Test build.sh Script
     runs-on: ubuntu-latest
@@ -79,15 +109,26 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: test-artifacts
-          path : .
+          path : test-artifacts
+
+      - name: Download unicorn test artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: test-artifacts-unicorn
+          path : test-artifacts-unicorn
 
       - name: Verify stm32 results
         run: |
-          cat stm32/log_-2.txt | grep -A8 800006a | tail -8 | grep 'Reached end point'
-          cat stm32/log_-1.txt | grep -A8 8000056 | tail -8 | grep 'Reached end point'
-          cat stm32/log_0.txt | grep -A8 8000070 | tail -8 | grep 'Reached end point'
-          cat stm32/log_1.txt | grep -A8 8000070 | tail -8 | grep 'Reached end point'
-          cat stm32/log_2.txt | grep -A8 8000070 | tail -8 | grep 'Reached end point'
+          cat test-artifacts/stm32/log_-2.txt | grep -A8 800006a | tail -8 | grep 'Reached end point'
+          cat test-artifacts/stm32/log_-1.txt | grep -A8 8000056 | tail -8 | grep 'Reached end point'
+          cat test-artifacts/stm32/log_0.txt | grep -A8 8000070 | tail -8 | grep 'Reached end point'
+          cat test-artifacts/stm32/log_1.txt | grep -A8 8000070 | tail -8 | grep 'Reached end point'
+          cat test-artifacts/stm32/log_2.txt | grep -A8 8000070 | tail -8 | grep 'Reached end point'
+          cat test-artifacts-unicorn/stm32/log_-2.txt | grep -A8 800006a | tail -8 | grep 'Reached end point'
+          cat test-artifacts-unicorn/stm32/log_-1.txt | grep -A8 8000056 | tail -8 | grep 'Reached end point'
+          cat test-artifacts-unicorn/stm32/log_0.txt | grep 'Reached endpoint at 0x8000070'
+          cat test-artifacts-unicorn/stm32/log_1.txt | grep 'Reached endpoint at 0x8000070'
+          cat test-artifacts-unicorn/stm32/log_2.txt | grep 'Reached endpoint at 0x8000070'
 
   verify_stm32-timeout-wfi:
     name: Verify results of stm32-timeout-wfi experiment
@@ -99,15 +140,21 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: test-artifacts
-          path : .
+          path : test-artifacts
+
+      - name: Download unicorn test artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: test-artifacts-unicorn
+          path : test-artifacts-unicorn
 
       - name: Verify stm32-timeout-wfi results
         run: |
-          cat stm32-timeout-wfi/log_-2.txt | grep -A8 800006a | tail -8 | grep 'Reached end point'
-          cat stm32-timeout-wfi/log_-1.txt | grep -A8 8000056 | tail -8 | grep 'Reached end point'
-          cat stm32-timeout-wfi/log.txt | grep 'Experiment 0 ran into timeout'
-          cat stm32-timeout-wfi/log.txt | grep 'Experiment 1 ran into timeout'
-          cat stm32-timeout-wfi/log.txt | grep 'Experiment 2 ran into timeout'
+          cat test-artifacts/stm32-timeout-wfi/log_-2.txt | grep -A8 800006a | tail -8 | grep 'Reached end point'
+          cat test-artifacts/stm32-timeout-wfi/log_-1.txt | grep -A8 8000056 | tail -8 | grep 'Reached end point'
+          cat test-artifacts/stm32-timeout-wfi/log.txt | grep 'Experiment 0 ran into timeout'
+          cat test-artifacts/stm32-timeout-wfi/log.txt | grep 'Experiment 1 ran into timeout'
+          cat test-artifacts/stm32-timeout-wfi/log.txt | grep 'Experiment 2 ran into timeout'
 
   verify_riscv64:
     name: Verify results of riscv64 experiment
@@ -119,15 +166,26 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: test-artifacts
-          path : .
+          path : test-artifacts
+
+      - name: Download unicorn test artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: test-artifacts-unicorn
+          path : test-artifacts-unicorn
 
       - name: Verify riscv64 results
         run: |
-          cat riscv64/log_-2.txt | grep -A8 80000014 | tail -8 | grep 'Reached end point'
-          cat riscv64/log_-1.txt | grep -A8 8000002a | tail -8 | grep 'Reached end point'
-          cat riscv64/log_0.txt | grep -A8 8000003c| tail -8 | grep 'Reached end point'
-          cat riscv64/log_1.txt | grep -A8 8000003c | tail -8 | grep 'Reached end point'
-          cat riscv64/log_2.txt | grep -A8 8000003c | tail -8 | grep 'Reached end point'
+          cat test-artifacts/riscv64/log_-2.txt | grep -A8 80000014 | tail -8 | grep 'Reached end point'
+          cat test-artifacts/riscv64/log_-1.txt | grep -A8 8000002a | tail -8 | grep 'Reached end point'
+          cat test-artifacts/riscv64/log_0.txt | grep -A8 8000003c| tail -8 | grep 'Reached end point'
+          cat test-artifacts/riscv64/log_1.txt | grep -A8 8000003c | tail -8 | grep 'Reached end point'
+          cat test-artifacts/riscv64/log_2.txt | grep -A8 8000003c | tail -8 | grep 'Reached end point'
+          cat test-artifacts-unicorn/riscv64/log_-2.txt | grep -A8 80000014 | tail -8 | grep 'Reached end point'
+          cat test-artifacts-unicorn/riscv64/log_-1.txt | grep -A8 8000002a | tail -8 | grep 'Reached end point'
+          cat test-artifacts-unicorn/riscv64/log_0.txt | grep 'Reached endpoint at 0x8000003c'
+          cat test-artifacts-unicorn/riscv64/log_1.txt | grep 'Reached endpoint at 0x8000003c'
+          cat test-artifacts-unicorn/riscv64/log_2.txt | grep 'Reached endpoint at 0x8000003c'
 
   verify_aarch64-softmmu:
     name: Verify results of aarch64-softmmu experiment

.github/workflows/lint.yml

@@ -24,3 +24,22 @@ jobs:
       - run: |
           black --version
           black --check --diff *.py analysis/*.py
+
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+          components: rustfmt, clippy
+      - uses: actions-rs/cargo@v1
+        with:
+          command: fmt
+          args: --all --manifest-path ./emulation_worker/Cargo.toml -- --check
+      - run: |
+          cd emulation_worker
+          cargo clippy -- -D warnings

.gitignore

@@ -1,6 +1,6 @@
 # ARCHIE specific debug files
 *.hdf5
-log_*
+log*.txt
 
 # C
 ## Prerequisites

README.md

@@ -49,9 +49,12 @@ cd qemu/build
 make -j $(nproc)
 cd ../../faultplugin/
 make
+cd emulation_worker
+cargo build --release
+cp target/release/libemulation_worker.so ../emulation_worker.so
 ```
 
-With this, *archie-qemu* is build in qemu/build/ and the plugin is build in *faultplugin/*
+With this, *archie-qemu* is built in qemu/build/, the plugin is built in *faultplugin/* and the unicorn emulation worker is built and moved to the project's root directory.
 If you change the build directory for *archie-qemu*, please change the path in the [Makefile](faultplugin/Makefile) in the *faultplugin/* folder for building the plugin.
 
 ## In [archie](https://github.com/Fraunhofer-AISEC/archie)
@@ -60,11 +63,14 @@ If you change the build directory for *archie-qemu*, please change the path in t
 
 For the Python3 program, the following libraries are needed
 ```
-pandas (tested 0.25.3)
-tables (tested 3.6.1)
-python-prctl (tested 1.6.1)
-numpy (tested 1.17.4)
-json (tested 2.0.9), or json5 (tested 0.9.6)
+pandas (tested 2.2)
+python-prctl (tested 1.8)
+tables (tested 3.10)
+json (tested 2.0.9), or json5 (tested 0.12)
+protobuf (tested 6.31)
+tqdm (tested 4.67)
+psutil (tested 7.0)
+pyelftools (tested 0.32)
 ```
 These python3 libraries can either be installed using your linux-distribution's installation method or by using pip3.
 JSON5 is strongly recommended as it allows integers to be represented as hexadecimal numbers.
@@ -111,3 +117,14 @@ To connect from GDB to the QEMU session use
 targ rem:localhost:1234
 ```
 QEMU will wait unil the GDB session is attached. The debugging mode is only suitable for the analysis of a low number of faults. Stepping through a large amount of faults is cumbersome. This should be considered when adjusting the JSON files.
+
+#### Unicorn Engine
+
+Instead of QEMU, the unicorn engine can be used for emulating the experiments.
+This feature can be used interchangeably with the QEMU emulation without the need to adjust any of the configuration files.
+One exception for this are register faults, which have different target addresses between the two versions.
+The mapping for the registers can be looked up in the documentation of unicorn's [Rust bindings](https://docs.rs/unicorn-engine/latest/unicorn_engine/unicorn_const/index.html).
+To enable this feature the *--unicorn* flag can be set.
+
+Using the unicorn engine can result in a substantial increase in performance.
+However, this mode is not capable of emulating any features related to the hardware of the target platform such as interrupts or communication with devices.

build.sh

@@ -37,7 +37,7 @@ install_python3_distro() {
 	if [ "${ID:-linux}" = "debian" ] || [ "${ID_LIKE#*debian*}" != "${ID_LIKE}" ]
 	then
 		echo "Looks like Debian!"
-		sudo apt-get install python3-tables python3-pandas python3-prctl python3-protobuf python3-tqdm python3-psutil python3-json5 python3-setuptools
+		sudo apt-get install python3-tables python3-pandas python3-prctl python3-protobuf python3-tqdm python3-psutil python3-json5 python3-setuptools python3-pyelftools
 
 		echo "Rebuild protobuf files to support the installed package versions"
 		cd protobuf
@@ -102,6 +102,12 @@ cd ../../faultplugin/
 make clean && make
 cd ..
 
+echo "Building emulation worker"
+cd emulation_worker
+cargo build --release
+cp target/release/libemulation_worker.so ../emulation_worker.so
+cd -
+
 echo "Test ARCHIE"
 cd examples/stm32
 ./run.sh
@@ -119,4 +125,4 @@ select yn in "YES" "NO"; do
 	esac
 	echo "Please type the number corresponding to Yes or No"
 done
-echo "Archie was build and tested successfully"
+echo "Archie was built and tested successfully"