Add qemu emulation + CI tests

.github/actions/setup-nix/action.yaml

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+
+name: Setup nix
+description: Setup nix
+
+inputs:
+  script:
+    description: The script to be run in the nix shell
+    required: false
+
+runs:
+  using: composite
+  steps:
+    - uses: nixbuild/nix-quick-install-action@v27
+      with: {load_nixConfig: false}
+    - name: Prepare nix dev shell
+      shell: nix develop .#ci -c bash -e {0}
+      run: |
+    - name: Dependency check
+      shell: nix develop .#ci -c bash -e {0}
+      if: inputs.script != ''
+      env:
+        INPUT_SCRIPT: ${{ inputs.script }}
+      run: eval "$INPUT_SCRIPT"

.github/workflows/build.yaml

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+
 name: Build
 on:
   push:
@@ -8,36 +10,19 @@ jobs:
   build_test:
     runs-on: ubuntu-latest
     steps:
-    - name: install jq
-      shell: bash
-      run: |
-        if ! (command -v jq) &> /dev/null
-        then
-          sudo apt install -y --no-install-recommends jq
-        fi
     - uses: actions/checkout@v4
-    - id: nixpkgs
-      shell: bash
-      run: |
-        if [ -f flake.lock ]; then
-          nixpkgs="flake:$(cat flake.lock | jq -r '.nodes.nixpkgs.locked // empty | .type + ":" + .owner + "/" + .repo + "/" + .rev')"
-        else
-          nixpkgs=channel:nixos-unstable
-        fi
-        echo "nixpkgs=$nixpkgs" >> "$GITHUB_OUTPUT"
-    - uses: cachix/install-nix-action@v25
+    - name: Setup nix
+      uses: ./.github/actions/setup-nix
       with:
-        nix_path: nixpkgs=${{ steps.nixpkgs.outputs.nixpkgs }}
-    - name: Prepare nix dev shell
-      shell: nix develop .#ci -c bash -e {0}
-      run: |
+        script: |
           astyle --version
+          arm-none-eabi-gcc --version
     - name: Astyle
       shell: nix develop .#ci -c bash -e {0}
       run: |
-          err=$(astyle $(git ls-files "*.c" "*.h") --options=.astylerc --dry-run --formatted)
+          err=$(astyle $(git ls-files "*.c" "*.h") --options=.astylerc --dry-run --formatted | awk '{print $2}')
           if [[ ${#err} != 0 ]]; then
-            echo "$err" | awk '{split($0,a);print a[2]}' | while IFS= read -r file; do
+            echo "$err" | while IFS= read -r file; do
               echo "::error file={"$file"},title={checking}::Formatted $file"
             done
             exit 1
@@ -46,3 +31,58 @@ jobs:
       shell: nix develop .#ci -c bash -e {0}
       run: |
           make
+
+  emulate_test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Setup nix
+      uses: ./.github/actions/setup-nix
+      with:
+        script: |
+          arm-none-eabi-gcc --version
+          qemu-system-arm --version
+    - name: Emulate on QEMU
+      shell: nix develop .#ci -c bash -e {0}
+      run: |
+          tests=10
+          output=$(make emulate NTESTS="$tests")
+          echo "::group::make emulate"
+          echo "$output"
+          echo "::endgroup::"
+
+          for file in elf/*.elf; do
+            echo "::group::Emulate $file"
+
+            output=$(make emulate ELF_FILE="$file")
+            echo "$output"
+
+            # check if error occurred
+            err=$(echo "$output" | awk '/ERROR/{code=1;print $2} END {exit code}')
+            if [[ $? == 1 ]]; then
+              echo "::error file={"$file"},title={emulate failed}::$err"
+              fail=1
+            fi
+
+            # check if num of ok is as expected
+            if [[ "$file" == *"test"* ]]; then
+              expect=$((tests*3))
+            elif [[ "$file" == *"speed"* ]] then
+              expect=$tests
+            fi
+
+            actual=$(echo "$output" | awk 'BEGIN{c=0} /OK/ {c++} END {print c}')
+
+            if [[ $actual != $expect ]]; then
+              echo "::error file={"$file"},title={emulate unexpected}::Expected $expect OKs, but received $actual OKs"
+              fail=1
+            else
+              echo "Emulate as expected"
+            fi
+
+            echo "::endgroup::"
+          done
+
+          if [[ $fail == 1 ]]; then
+            exit 1
+          fi

Makefile

@@ -13,7 +13,15 @@ include mk/rules.mk
 test: $(foreach scheme,$(KEM_SCHEMES),$(scheme)-test)
 speed: $(foreach scheme,$(KEM_SCHEMES),$(scheme)-speed)
 
-.PHONY: clean libclean
+.PHONY: emulate clean libclean
+
+emulate: PLATFORM = mps2-an386
+emulate: NTESTS = 10
+emulate:
+	$(MAKE) PLATFORM=$(PLATFORM) NTESTS=$(NTESTS)
+ifdef ELF_FILE
+	qemu-system-arm -machine $(PLATFORM) -nographic -semihosting -kernel $(ELF_FILE)
+endif
 
 clean:
 	rm -rf elf/

README.md

@@ -67,14 +67,19 @@ For further details, please refer to [DevSupport](dev-support/)
 
 ## Running tests and benchmarks
 
-The build system compiles tests and benchmarks for each mlkem parameter set on specified platform (currently only `stm32f4discovery` is supported).
+The build system compiles tests and benchmarks for each mlkem parameter set on specified platform, currently supported platform includes `stm32f4discovery` and `mps2-an386` (could be simulated with the `QEMU` simulator).
+The PLATFORM configuration is optional, with the default platform set to `stm32f4discovery`.
 
 For example,
-- `make bin/mlkem768-test.hex` assembles the `mlkem768` binary performing functional tests.
-- `make bin/mlkem1024-speed.hex` assembles the `mlkem-1024` speed benchmark binary.
-- `make test` assembles all binaries for functional tests.
-- `make speed` assembles all binaries for speed benchmarking
-- `make (all)` assembles all the above targets for all parameter sets.
+- `make [PLATFORM=<PLATFORM_NAME>] bin/mlkem768-test.hex` assembles the `mlkem768` binary performing functional tests.
+- `make [PLATFORM=<PLATFORM_NAME>] bin/mlkem1024-speed.hex` assembles the `mlkem-1024` speed benchmark binary.
+- `make [PLATFORM=<PLATFORM_NAME>] test` assembles all binaries for functional tests.
+- `make [PLATFORM=<PLATFORM_NAME>] speed` assembles all binaries for speed benchmarking
+- `make [PLATFORM=<PLATFORM_NAME>] (all)` assembles all the above targets for all parameter sets.
+
+- `make emulate` emulate `mps2-an386` with `QEMU`
+- `make clean` cleans up intermediate artifacts
+- `make distclean` additionally cleanup the `libopencm3` library
 
 After generating the specified hex files, you can flash it to the development board using `openocd`. 
 For example,

dev-support/README.md

@@ -4,6 +4,16 @@
 
 ## Recommended Prerequisites
 
+### [flake](https://nixos.wiki/wiki/Flakes)
+
+As `flake` is still an experimental feature of nix, `--experimental-features 'nix-command flakes'` is needed for `nix` command.
+
+Add the following to `~/.config/nix/nix.conf` or `/etc/nix/nix.conf` could avoid adding the option every time invoking `nix` command.
+```
+experimental-features = nix-command flakes
+```
+
+
 ### [direnv](https://direnv.net/)
 
 Enabling `direnv` would greatly enhance the development experience. Once enabled, all dependencies will be installed, and the shell will be augmented according to the specifications in [flake.nix](../flake.nix) whenever you enter the project directory from your shell. The initial setup might take a bit longer when entering the project directory for the first time.

dev-support/bin/style

@@ -7,7 +7,6 @@ set -o nounset
 set -o pipefail
 
 ROOT="$(realpath "$(dirname "$0")"/../../)"
-DEVSUPPORT="$(realpath "$(dirname "$0")"/../)"
 CURDIR="$(realpath "$(dirname "$0")")"
 . "$CURDIR/log"
 
@@ -19,7 +18,7 @@ info "Formatting shell scripts"
 shfmt -s -w -l -i 2 -ci -fn $(shfmt -f $(git grep -l '' :/))
 
 info "Chekcking misspellings"
-codespell --skip "$ROOT/.direnv,$ROOT/.git,$ROOT/libopencm3" --ignore-words "$DEVSUPPORT/codespell-ignore-words" "$ROOT"
+codespell --skip "$ROOT/.direnv,$ROOT/.git,$ROOT/libopencm3,*.c,*.h" "$ROOT"
 
 info "Formatting c files"
 # shellcheck disable=SC2046

flake.nix

@@ -12,20 +12,19 @@
     };
   };
 
-  outputs = inputs@{ flake-parts, nixpkgs, ... }:
+  outputs = inputs@{ flake-parts, ... }:
     flake-parts.lib.mkFlake { inherit inputs; } {
       imports = [ ];
       systems = [ "x86_64-linux" "aarch64-linux" "aarch64-darwin" "x86_64-darwin" ];
-      perSystem = { pkgs, system, inputs', ... }:
+      perSystem = { pkgs, ... }:
         let
           core = with pkgs; [
             # formatter & linters
             astyle # 3.4.10
 
             # build dependencies
             gcc-arm-embedded-13 # arm-gnu-toolchain-13.2.rel1
-            openocd # 0.12.0
-            python311Packages.pyserial # 3.5
+            qemu # 8.1.5
           ];
         in
         {
@@ -38,6 +37,10 @@
               nixpkgs-fmt
               shfmt
               codespell
+
+              # debug dependencies
+              openocd # 0.12.0
+              python311Packages.pyserial # 3.5
             ];
 
             shellHook = ''
@@ -58,4 +61,3 @@
       };
     };
 }
-