Introduce global config and reorganize backends

This commit introduces a global configuration file `mlkem/config.h` which should contain all user-configurable parameters. With this commit, it contains: - MLKEM_K - MLKEM_NAMESPACE - FIPS202_NAMESPACE - MLKEM_USE_NATIVE - MLKEM_NATIVE_ARITH_BACKEND - MLKEM_NATIVE_FIPS202_BACKEND The backends have been reorganized to follow a simpler file structure: Every backend profile is identified by metadata file in the toplevel directory of the backend. For example, `aarch64` has `opt.h` and `clean.h`. Those metadata files so far only set the name of the backend, and point to the actual implementation. The reason why the metadata file and the implementation are kept separate is so that assembly files can include the metadata file and know if they should be assembled: For example, `aarch64/opt.h` sets `MLKEM_NATIVE_ARITH_BACKEND_AARCH64_OPT` which all relevant files are guarded by; similar for clean. Previously, they were all guarded more coarsely by `MLKEM_USE_NATIVE_AARCH64` or `MLKEM_USE_NATIVE_X86_64` -- those have been removed. The source code of the backends has been moved into `src` directories. Ultimately, we may want to split `aarch64` into `aarch64_opt` and `aarch64_clean`, so the distinction between profile and backend goes away, but this is not yet attempted. Signed-off-by: Hanno Becker <[email protected]>
pq-code-package · Dec 16, 2024 · 67de1dc · 67de1dc
1 parent 668dbab
commit 67de1dc
Show file tree

Hide file tree

Showing 104 changed files with 689 additions and 636 deletions.
diff --git a/.github/workflows/bench.yml b/.github/workflows/bench.yml
@@ -43,7 +43,7 @@ jobs:
           name: Arm Cortex-A55 (Snapdragon 888) benchmarks
           bench_pmu: PERF
           archflags: "-mcpu=cortex-a55 -march=armv8.2-a"
-          cflags: "-flto -static -DFORCE_AARCH64 -DFIPS202_NATIVE_PROFILE=\"aarch64/profiles/cortex_a55.h\""
+          cflags: "-flto -static -DFORCE_AARCH64 -DMLKEM_NATIVE_FIPS202_BACKEND=\"'aarch64/cortex_a55.h'\""
           bench_extra_args: -w exec-on-a55
         - system: bpi
           name: Bananapi bpi-f3 benchmarks

diff --git a/examples/bring_your_own_fips202/Makefile b/examples/bring_your_own_fips202/Makefile
@@ -19,7 +19,6 @@ INC=
 INC+=-Imlkem_native/mlkem
 INC+=-Imlkem_native/mlkem
 INC+=-Imlkem_native/mlkem/native
-INC+=-Imlkem_native/mlkem/sys
 
 # Part B:
 #

diff --git a/examples/bring_your_own_fips202/custom_fips202/fips202.h b/examples/bring_your_own_fips202/custom_fips202/fips202.h
@@ -11,7 +11,7 @@
 #ifndef FIPS202_H
 #define FIPS202_H
 
-#include "namespace.h"
+#include "common.h"
 #include "tiny_sha3/sha3.h"
 
 #define SHAKE128_RATE 168

diff --git a/examples/bring_your_own_fips202/custom_fips202/namespace.h b/examples/bring_your_own_fips202/custom_fips202/namespace.h
diff --git a/examples/mlkem_native_as_code_package/Makefile b/examples/mlkem_native_as_code_package/Makefile
@@ -21,7 +21,6 @@ INC+=-Imlkem_native/mlkem
 INC+=-Imlkem_native/mlkem/native
 INC+=-Imlkem_native/fips202
 INC+=-Imlkem_native/fips202/native
-INC+=-Imlkem_native/mlkem/sys
 
 # Part B:
 #

diff --git a/fips202/fips202.h b/fips202/fips202.h
@@ -7,9 +7,8 @@
 
 #include <stddef.h>
 #include <stdint.h>
-#include "namespace.h"
-
 #include "cbmc.h"
+#include "common.h"
 
 #define SHAKE128_RATE 168
 #define SHAKE256_RATE 136

diff --git a/fips202/fips202_backend.h b/fips202/fips202_backend.h
@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) 2024 The mlkem-native project authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifdef MLKEM_NATIVE_FIPS202_IMPL_H
+#error Only one FIPS202 assembly profile can be defined -- did you include multiple profiles?
+#else
+#define MLKEM_NATIVE_FIPS202_IMPL_H
+
+/* Include to enforce consistency of API and implementation */
+#include "native/api.h"
+
+#if defined(MLKEM_NATIVE_FIPS202_BACKEND_IMPL)
+#include MLKEM_NATIVE_FIPS202_BACKEND_IMPL
+#endif
+
+#endif /* MLKEM_NATIVE_FIPS202_IMPL_H */
diff --git a/fips202/fips202x4.h b/fips202/fips202x4.h
@@ -7,9 +7,9 @@
 
 #include <stddef.h>
 #include <stdint.h>
+#include "common.h"
 #include "fips202.h"
 #include "keccakf1600.h"
-#include "namespace.h"
 
 #include "cbmc.h"
 

diff --git a/fips202/keccakf1600.c b/fips202/keccakf1600.c
@@ -15,7 +15,7 @@
 #include <stdint.h>
 
 #include "config.h"
-#include "fips202_native.h"
+#include "fips202_backend.h"
 
 #include "cbmc.h"
 

diff --git a/fips202/keccakf1600.h b/fips202/keccakf1600.h
@@ -6,10 +6,8 @@
 #define KECCAKF1600_H
 
 #include <stdint.h>
-#include "fips202_native.h"
-#include "namespace.h"
-
 #include "cbmc.h"
+#include "common.h"
 #define KECCAK_LANES 25
 
 /*

diff --git a/fips202/namespace.h b/fips202/namespace.h
diff --git a/fips202/native/aarch64/cortex_a55.h b/fips202/native/aarch64/cortex_a55.h
@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2024 The mlkem-native project authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/* FIPS202 assembly profile targeting Cortex-A55 */
+
+#ifdef FIPS202_NATIVE_PROFILE_H
+#error Only one FIPS202 assembly profile can be defined -- did you include multiple profiles?
+#else
+#define FIPS202_NATIVE_PROFILE_H
+
+/* Identifier for this backend so that source and assembly files
+ * in the build can be appropriately guarded. */
+#define MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_A55
+
+#define MLKEM_NATIVE_FIPS202_BACKEND_NAME AARCH64_A55
+
+/* Filename of the C backend implementation.
+ * This is not inlined here because this header is included in assembly
+ * files as well. */
+#define MLKEM_NATIVE_FIPS202_BACKEND_IMPL "aarch64/src/cortex_a55_impl.h"
+
+#endif /* FIPS202_NATIVE_PROFILE_H */
diff --git a/fips202/native/aarch64/default.h b/fips202/native/aarch64/default.h
@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2024 The mlkem-native project authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/* Default FIPS202 assembly profile for AArch64 systems */
+
+#ifdef FIPS202_NATIVE_PROFILE_H
+#error Only one FIPS202 assembly profile can be defined -- did you include multiple profiles?
+#else
+#define FIPS202_NATIVE_PROFILE_H
+
+/* Identifier for this backend so that source and assembly files
+ * in the build can be appropriately guarded. */
+#define MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_DEFAULT
+
+#define MLKEM_NATIVE_FIPS202_BACKEND_NAME AARCH64_DEFAULT
+
+/* Filename of the C backend implementation.
+ * This is not inlined here because this header is included in assembly
+ * files as well. */
+#define MLKEM_NATIVE_FIPS202_BACKEND_IMPL "aarch64/src/default_impl.h"
+
+#endif /* FIPS202_NATIVE_PROFILE_H */
diff --git a/fips202/native/aarch64/common.i → fips202/native/aarch64/src/common.i b/fips202/native/aarch64/common.i → fips202/native/aarch64/src/common.i
diff --git a/fips202/native/aarch64/profiles/cortex_a55.h → fips202/native/aarch64/src/cortex_a55_impl.h b/fips202/native/aarch64/profiles/cortex_a55.h → fips202/native/aarch64/src/cortex_a55_impl.h
@@ -5,12 +5,12 @@
 
 /* FIPS202 assembly profile targeting Cortex-A55 */
 
-#ifdef FIPS202_NATIVE_PROFILE_H
+#ifdef FIPS202_NATIVE_PROFILE_IMPL_H
 #error Only one FIPS202 assembly profile can be defined -- did you include multiple profiles?
 #else
-#define FIPS202_NATIVE_PROFILE_H
+#define FIPS202_NATIVE_PROFILE_IMPL_H
 
-#include "../fips202_native_aarch64.h"
+#include "fips202_native_aarch64.h"
 
 /*
  * On Cortex-A55, we use lazy rotation assembly for Keccak-x1,
@@ -22,4 +22,4 @@ static INLINE void keccak_f1600_x1_native(uint64_t *state)
   keccak_f1600_x1_scalar_asm_opt(state);
 }
 
-#endif /* FIPS202_NATIVE_PROFILE_H */
+#endif /* FIPS202_NATIVE_PROFILE_IMPL_H */
diff --git a/fips202/native/aarch64/profiles/default.h → fips202/native/aarch64/src/default_impl.h b/fips202/native/aarch64/profiles/default.h → fips202/native/aarch64/src/default_impl.h
@@ -5,12 +5,12 @@
 
 /* Default FIPS202 assembly profile for AArch64 systems */
 
-#ifdef FIPS202_NATIVE_PROFILE_H
+#ifdef FIPS202_NATIVE_PROFILE_IMPL_H
 #error Only one FIPS202 assembly profile can be defined -- did you include multiple profiles?
 #else
-#define FIPS202_NATIVE_PROFILE_H
+#define FIPS202_NATIVE_PROFILE_IMPL_H
 
-#include "../fips202_native_aarch64.h"
+#include "fips202_native_aarch64.h"
 
 /*
  * Default logic to decide which implementation to use.

diff --git a/...2/native/aarch64/fips202_native_aarch64.h → ...tive/aarch64/src/fips202_native_aarch64.h b/...2/native/aarch64/fips202_native_aarch64.h → ...tive/aarch64/src/fips202_native_aarch64.h
@@ -6,11 +6,8 @@
 #define FIPS202_AARCH64_NATIVE_H
 
 #include <stdint.h>
-#include "config.h"
-#include "namespace.h"
-#include "params.h"
+#include "common.h"
 
-#ifdef MLKEM_USE_NATIVE_AARCH64
 #define keccak_f1600_x1_scalar_asm_opt \
   FIPS202_NAMESPACE(keccak_f1600_x1_scalar_asm_opt)
 void keccak_f1600_x1_scalar_asm_opt(uint64_t *state);
@@ -38,6 +35,5 @@ void keccak_f1600_x4_scalar_v84a_asm_hybrid_opt(uint64_t *state);
 #define keccak_f1600_x4_scalar_v8a_v84a_hybrid_asm_opt \
   FIPS202_NAMESPACE(keccak_f1600_x4_scalar_v8a_v84a_hybrid_asm_opt)
 void keccak_f1600_x4_scalar_v8a_v84a_hybrid_asm_opt(uint64_t *state);
-#endif /* MLKEM_USE_NATIVE_AARCH64 */
 
 #endif /* FIPS202_AARCH64_NATIVE_H */
diff --git a/.../aarch64/keccak_f1600_x1_scalar_asm_opt.S → ...ch64/src/keccak_f1600_x1_scalar_asm_opt.S b/.../aarch64/keccak_f1600_x1_scalar_asm_opt.S → ...ch64/src/keccak_f1600_x1_scalar_asm_opt.S
@@ -28,12 +28,12 @@
 // Author: Hanno Becker <[email protected]>
 // Author: Matthias Kannwischer <[email protected]>
 
-#include "config.h"
-#if defined(MLKEM_USE_NATIVE_AARCH64)
+#include "common.h"
+#if defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_DEFAULT) || \
+    defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_A55)
 
 // Needed to provide ASM_LOAD directive
 #include "common.i"
-#include "namespace.h"
 
 /********************** CONSTANTS *************************/
     .data
@@ -457,4 +457,5 @@ initial:
     free_stack
     ret
 
-#endif /* MLKEM_USE_NATIVE_AARCH64 */
+#endif /* defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_DEFAULT) ||
+          defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_A55) */
diff --git a/.../aarch64/keccak_f1600_x1_v84a_asm_clean.S → ...ch64/src/keccak_f1600_x1_v84a_asm_clean.S b/.../aarch64/keccak_f1600_x1_v84a_asm_clean.S → ...ch64/src/keccak_f1600_x1_v84a_asm_clean.S
@@ -37,8 +37,9 @@
 // during load and store, so that the caller need not do this.
 //
 
-#include "config.h"
-#if defined(MLKEM_USE_NATIVE_AARCH64)
+#include "common.h"
+#if defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_DEFAULT) || \
+    defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_A55)
 
 // Needed to provide ASM_LOAD directive
 #include "common.i"

diff --git a/.../aarch64/keccak_f1600_x2_v84a_asm_clean.S → ...ch64/src/keccak_f1600_x2_v84a_asm_clean.S b/.../aarch64/keccak_f1600_x2_v84a_asm_clean.S → ...ch64/src/keccak_f1600_x2_v84a_asm_clean.S
@@ -37,8 +37,9 @@
 // during load and store, so that the caller need not do this.
 //
 
-#include "config.h"
-#if defined(MLKEM_USE_NATIVE_AARCH64)
+#include "common.h"
+#if defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_DEFAULT) || \
+    defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_A55)
 
 // Needed to provide ASM_LOAD directive
 #include "common.i"

diff --git a/...h64/keccak_f1600_x2_v8a_v84a_asm_hybrid.S → ...src/keccak_f1600_x2_v8a_v84a_asm_hybrid.S b/...h64/keccak_f1600_x2_v8a_v84a_asm_hybrid.S → ...src/keccak_f1600_x2_v8a_v84a_asm_hybrid.S
@@ -37,12 +37,12 @@
 // during load and store, so that the caller need not do this.
 //
 
-#include "config.h"
-#if defined(MLKEM_USE_NATIVE_AARCH64)
+#include "common.h"
+#if defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_DEFAULT) || \
+    defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_A55)
 
 // Needed to provide ASM_LOAD directive
 #include "common.i"
-#include "namespace.h"
 
 #if defined(__ARM_FEATURE_SHA3)
 

diff --git a/...cak_f1600_x4_scalar_v84a_asm_hybrid_opt.S → ...cak_f1600_x4_scalar_v84a_asm_hybrid_opt.S b/...cak_f1600_x4_scalar_v84a_asm_hybrid_opt.S → ...cak_f1600_x4_scalar_v84a_asm_hybrid_opt.S
@@ -24,12 +24,12 @@
  *
  */
 
-#include "config.h"
-#if defined(MLKEM_USE_NATIVE_AARCH64)
+#include "common.h"
+#if defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_DEFAULT) || \
+    defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_A55)
 
 // Needed to provide ASM_LOAD directive
 #include "common.i"
-#include "namespace.h"
 
 #if defined(__ARM_FEATURE_SHA3)
 

diff --git a/...ccak_f1600_x4_v8a_scalar_hybrid_asm_opt.S → ...ccak_f1600_x4_v8a_scalar_hybrid_asm_opt.S b/...ccak_f1600_x4_v8a_scalar_hybrid_asm_opt.S → ...ccak_f1600_x4_v8a_scalar_hybrid_asm_opt.S
@@ -24,12 +24,12 @@
  *
  */
 
-#include "config.h"
-#if defined(MLKEM_USE_NATIVE_AARCH64)
+#include "common.h"
+#if defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_DEFAULT) || \
+    defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_A55)
 
 // Needed to provide ASM_LOAD directive
 #include "common.i"
-#include "namespace.h"
 
 #define KECCAK_F1600_ROUNDS 24
 

diff --git a/...f1600_x4_v8a_v84a_scalar_hybrid_asm_opt.S → ...f1600_x4_v8a_v84a_scalar_hybrid_asm_opt.S b/...f1600_x4_v8a_v84a_scalar_hybrid_asm_opt.S → ...f1600_x4_v8a_v84a_scalar_hybrid_asm_opt.S
@@ -24,8 +24,9 @@
  *
  */
 
-#include "config.h"
-#if defined(MLKEM_USE_NATIVE_AARCH64)
+#include "common.h"
+#if defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_DEFAULT) || \
+    defined(MLKEM_NATIVE_FIPS202_BACKEND_AARCH64_A55)
 
 // Needed to provide ASM_LOAD directive
 #include "common.i"