Merge pull request #541 from pq-code-package/api_order_include

Fix ordering of includes in arith/fips202 backend
pq-code-package · Dec 18, 2024 · 271b362 · 271b362 · oqs-bot · Dec 18, 2024
2 parents e9e0eea + e80f650
commit 271b362
Show file tree

Hide file tree

Showing 7 changed files with 72 additions and 35 deletions.
diff --git a/mlkem/arith_backend.h b/mlkem/arith_backend.h
@@ -8,11 +8,17 @@
 #else
 #define MLKEM_NATIVE_ARITH_IMPL_H
 
-/* Include to enforce consistency of API and implementation */
-#include "native/api.h"
+#include "common.h"
 
 #if defined(MLKEM_NATIVE_ARITH_BACKEND_IMPL)
 #include MLKEM_NATIVE_ARITH_BACKEND_IMPL
+
+/* Include to enforce consistency of API and implementation,
+ * and conduct sanity checks on the backend.
+ *
+ * Keep this _after_ the inclusion of the backend; otherwise,
+ * the sanity checks won't have an effect. */
+#include "native/api.h"
 #endif
 
 #endif /* MLKEM_NATIVE_ARITH_IMPL_H */
diff --git a/mlkem/fips202/fips202_backend.h b/mlkem/fips202/fips202_backend.h
@@ -8,11 +8,16 @@
 #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
+
+/* Include to enforce consistency of API and implementation,
+ * and conduct sanity checks on the backend.
+ *
+ * Keep this _after_ the inclusion of the backend; otherwise,
+ * the sanity checks won't have an effect. */
+#include "fips202/native/api.h"
 #endif
 
+
 #endif /* MLKEM_NATIVE_FIPS202_IMPL_H */
diff --git a/mlkem/fips202/native/api.h b/mlkem/fips202/native/api.h
@@ -2,22 +2,33 @@
  * Copyright (c) 2024 The mlkem-native project authors
  * SPDX-License-Identifier: Apache-2.0
  */
-#ifndef FIPS202_NATIVE_H
-#define FIPS202_NATIVE_H
-
-#include <stdint.h>
-#include "common.h"
 
 /*
- * FIPS202 native interface
+ * FIPS-202 native interface
+ *
+ * This header is primarily for documentation purposes.
+ * It should not be included by backend implementations.
  */
+#ifdef MLKEM_NATIVE_FIPS202_NATIVE_API_H
+#error \
+    "The FIPS-202 backend API `mlkem/fips202/native/api.h` "		\
+    "should not be directly included. Please include the relevant "	\
+    "structure headers directly."
+#else /* MLKEM_NATIVE_FIPS202_NATIVE_API_H */
+#define MLKEM_NATIVE_FIPS202_NATIVE_API_H
+
+#include <stdint.h>
 
 /*
- * Those functions are meant to be trivial wrappers around
- *  the chosen native implementation. The are static inline
- * to avoid unnecessary calls.
- * The macro before each declaration controls whether a native
- * implementation is present.
+ * This is the C<->native interface allowing for the drop-in
+ * of custom Keccak-F1600 implementations.
+ *
+ * A _backend_ is a specific implementation of parts of this interface.
+ *
+ * You can replace 1-fold, 2-fold, or 4-fold batched Keccak-F1600.
+ * To enable, set MLKEM_USE_FIPS202_X{1,2,4}_NATIVE in your backend,
+ * and define the inline wrapper keccak_f1600_x{1,2,4}_native() to
+ * forward to your implementation.
  */
 
 #if defined(MLKEM_USE_FIPS202_X1_NATIVE)
@@ -30,4 +41,4 @@ static INLINE void keccak_f1600_x2_native(uint64_t *state);
 static INLINE void keccak_f1600_x4_native(uint64_t *state);
 #endif
 
-#endif /* FIPS202_NATIVE_H */
+#endif /* MLKEM_NATIVE_FIPS202_NATIVE_API_H */
diff --git a/mlkem/native/aarch64/src/clean_impl.h b/mlkem/native/aarch64/src/clean_impl.h
@@ -12,6 +12,9 @@
 
 #include "arith_native_aarch64.h"
 
+#include "poly.h"
+#include "polyvec.h"
+
 /* Set of primitives that this backend replaces */
 #define MLKEM_USE_NATIVE_NTT
 #define MLKEM_USE_NATIVE_INTT

diff --git a/mlkem/native/aarch64/src/opt_impl.h b/mlkem/native/aarch64/src/opt_impl.h
@@ -12,6 +12,9 @@
 
 #include "arith_native_aarch64.h"
 
+#include "poly.h"
+#include "polyvec.h"
+
 /* Set of primitives that this backend replaces */
 #define MLKEM_USE_NATIVE_NTT
 #define MLKEM_USE_NATIVE_INTT

diff --git a/mlkem/native/api.h b/mlkem/native/api.h
@@ -2,28 +2,37 @@
  * Copyright (c) 2024 The mlkem-native project authors
  * SPDX-License-Identifier: Apache-2.0
  */
-#ifndef MLKEM_ARITH_NATIVE_H
-#define MLKEM_ARITH_NATIVE_H
 
-#include <stdint.h>
+/*
+ * Native arithmetic interface
+ *
+ * This header is primarily for documentation purposes.
+ * It should not be included by backend implementations.
+ *
+ * To ensure consistency with backends, the header will be
+ * included automatically after inclusion of the active
+ * backend, to ensure consistency of function signatures,
+ * and run sanity checks.
+ */
+#ifdef MLKEM_NATIVE_ARITH_NATIVE_API_H
+#error \
+    "The arithmetic backend API `mlkem/native/api.h` "		\
+    "should not be directly included. Please include the relevant "	\
+    "structure headers directly."
+#else /* MLKEM_NATIVE_ARITH_NATIVE_API_H */
+#define MLKEM_NATIVE_ARITH_NATIVE_API_H
 
-#include "cbmc.h"
+#include <stdint.h>
 #include "poly.h"
 #include "polyvec.h"
 
-#include "common.h"
-
 /*
- * MLKEM native arithmetic interface
- *
- * This is the C<->native arithmetic interface used in this repository
- * to allow for the drop-in of native code for performance critical
- * components of ML-KEM.
+ * This is the C<->native interface allowing for the drop-in of
+ * native code for performance critical arithmetic components of ML-KEM.
  *
- * A _profile_ is a specific implementation of (part of) this interface.
- * The active profile (if any) is determined in profile.h.
+ * A _backend_ is a specific implementation of (part of) this interface.
  *
- * To add a function to a profile, define MLKEM_USE_NATIVE_XXX and
+ * To add a function to a backend, define MLKEM_USE_NATIVE_XXX and
  * implement `static inline xxx(...)` in the profile header.
  *
  * The only exception is MLKEM_USE_NATIVE_NTT_CUSTOM_ORDER. This option can
@@ -37,9 +46,8 @@
  */
 
 /*
- * Those functions are meant to be trivial wrappers around
- * the chosen native implementation. The are static inline
- * to avoid unnecessary calls.
+ * Those functions are meant to be trivial wrappers around the chosen native
+ * implementation. The are static inline to avoid unnecessary calls.
  * The macro before each declaration controls whether a native
  * implementation is present.
  */
@@ -244,4 +252,4 @@ static INLINE int rej_uniform_native(int16_t *r, unsigned int len,
                                      const uint8_t *buf, unsigned int buflen);
 #endif /* MLKEM_USE_NATIVE_REJ_UNIFORM */
 
-#endif /* MLKEM_ARITH_NATIVE_H */
+#endif /* MLKEM_NATIVE_ARITH_NATIVE_API_H */
diff --git a/mlkem/native/x86_64/src/default_impl.h b/mlkem/native/x86_64/src/default_impl.h
@@ -14,6 +14,7 @@
 
 #include "arith_native_x86_64.h"
 #include "poly.h"
+#include "polyvec.h"
 
 #define MLKEM_USE_NATIVE_NTT_CUSTOM_ORDER
Benchmark suite	Current: `271b362`	Previous: `e9e0eea`	Ratio
`ML-KEM-512 keypair`	`29180` cycles	`29180` cycles	`1`
`ML-KEM-512 encaps`	`35550` cycles	`35555` cycles	`1.00`
`ML-KEM-512 decaps`	`46096` cycles	`46099` cycles	`1.00`
`ML-KEM-768 keypair`	`49220` cycles	`49219` cycles	`1.00`
`ML-KEM-768 encaps`	`55380` cycles	`55379` cycles	`1.00`
`ML-KEM-768 decaps`	`70208` cycles	`70208` cycles	`1`
`ML-KEM-1024 keypair`	`72237` cycles	`72230` cycles	`1.00`
`ML-KEM-1024 encaps`	`81077` cycles	`81071` cycles	`1.00`
`ML-KEM-1024 decaps`	`100881` cycles	`100876` cycles	`1.00`
Benchmark suite	Current: `271b362`	Previous: `e9e0eea`	Ratio
`ML-KEM-512 keypair`	`13533` cycles	`13547` cycles	`1.00`
`ML-KEM-512 encaps`	`17316` cycles	`17319` cycles	`1.00`
`ML-KEM-512 decaps`	`22850` cycles	`22860` cycles	`1.00`
`ML-KEM-768 keypair`	`22537` cycles	`22495` cycles	`1.00`
`ML-KEM-768 encaps`	`24505` cycles	`24463` cycles	`1.00`
`ML-KEM-768 decaps`	`32559` cycles	`32469` cycles	`1.00`
`ML-KEM-1024 keypair`	`31461` cycles	`31409` cycles	`1.00`
`ML-KEM-1024 encaps`	`34950` cycles	`34979` cycles	`1.00`
`ML-KEM-1024 decaps`	`45838` cycles	`45906` cycles	`1.00`
Benchmark suite	Current: `271b362`	Previous: `e9e0eea`	Ratio
`ML-KEM-512 keypair`	`20340` cycles	`20331` cycles	`1.00`
`ML-KEM-512 encaps`	`27297` cycles	`27001` cycles	`1.01`
`ML-KEM-512 decaps`	`35844` cycles	`35818` cycles	`1.00`
`ML-KEM-768 keypair`	`34886` cycles	`34917` cycles	`1.00`
`ML-KEM-768 encaps`	`38189` cycles	`38215` cycles	`1.00`
`ML-KEM-768 decaps`	`50924` cycles	`50962` cycles	`1.00`
`ML-KEM-1024 keypair`	`48027` cycles	`47969` cycles	`1.00`
`ML-KEM-1024 encaps`	`54197` cycles	`54208` cycles	`1.00`
`ML-KEM-1024 decaps`	`71804` cycles	`71766` cycles	`1.00`
Benchmark suite	Current: `271b362`	Previous: `e9e0eea`	Ratio
`ML-KEM-512 keypair`	`18137` cycles	`18134` cycles	`1.00`
`ML-KEM-512 encaps`	`23201` cycles	`23184` cycles	`1.00`
`ML-KEM-512 decaps`	`30511` cycles	`30491` cycles	`1.00`
`ML-KEM-768 keypair`	`31078` cycles	`31060` cycles	`1.00`
`ML-KEM-768 encaps`	`34162` cycles	`34144` cycles	`1.00`
`ML-KEM-768 decaps`	`44729` cycles	`44726` cycles	`1.00`
`ML-KEM-1024 keypair`	`44565` cycles	`44648` cycles	`1.00`
`ML-KEM-1024 encaps`	`49897` cycles	`49879` cycles	`1.00`
`ML-KEM-1024 decaps`	`64402` cycles	`64405` cycles	`1.00`
Benchmark suite	Current: `271b362`	Previous: `e9e0eea`	Ratio
`ML-KEM-512 keypair`	`15077` cycles	`15071` cycles	`1.00`
`ML-KEM-512 encaps`	`19660` cycles	`19650` cycles	`1.00`
`ML-KEM-512 decaps`	`26308` cycles	`26299` cycles	`1.00`
`ML-KEM-768 keypair`	`25578` cycles	`25601` cycles	`1.00`
`ML-KEM-768 encaps`	`28154` cycles	`28220` cycles	`1.00`
`ML-KEM-768 decaps`	`37846` cycles	`37873` cycles	`1.00`
`ML-KEM-1024 keypair`	`35641` cycles	`35572` cycles	`1.00`
`ML-KEM-1024 encaps`	`40966` cycles	`40971` cycles	`1.00`
`ML-KEM-1024 decaps`	`54548` cycles	`54546` cycles	`1.00`
Benchmark suite	Current: `271b362`	Previous: `e9e0eea`	Ratio
`ML-KEM-512 keypair`	`34897` cycles	`34854` cycles	`1.00`
`ML-KEM-512 encaps`	`44978` cycles	`45023` cycles	`1.00`
`ML-KEM-512 decaps`	`58945` cycles	`58898` cycles	`1.00`
`ML-KEM-768 keypair`	`59225` cycles	`59325` cycles	`1.00`
`ML-KEM-768 encaps`	`71828` cycles	`71988` cycles	`1.00`
`ML-KEM-768 decaps`	`89397` cycles	`89449` cycles	`1.00`
`ML-KEM-1024 keypair`	`87542` cycles	`87443` cycles	`1.00`
`ML-KEM-1024 encaps`	`104646` cycles	`104554` cycles	`1.00`
`ML-KEM-1024 decaps`	`127678` cycles	`127585` cycles	`1.00`
Benchmark suite	Current: `271b362`	Previous: `e9e0eea`	Ratio
`ML-KEM-512 keypair`	`18199` cycles	`18189` cycles	`1.00`
`ML-KEM-512 encaps`	`22233` cycles	`22234` cycles	`1.00`
`ML-KEM-512 decaps`	`28985` cycles	`28991` cycles	`1.00`
`ML-KEM-768 keypair`	`30681` cycles	`30684` cycles	`1.00`
`ML-KEM-768 encaps`	`33725` cycles	`33728` cycles	`1.00`
`ML-KEM-768 decaps`	`43302` cycles	`43304` cycles	`1.00`
`ML-KEM-1024 keypair`	`44354` cycles	`44357` cycles	`1.00`
`ML-KEM-1024 encaps`	`49788` cycles	`49786` cycles	`1.00`
`ML-KEM-1024 decaps`	`62840` cycles	`62844` cycles	`1.00`
Benchmark suite	Current: `271b362`	Previous: `e9e0eea`	Ratio
`ML-KEM-512 keypair`	`19003` cycles	`19006` cycles	`1.00`
`ML-KEM-512 encaps`	`23602` cycles	`23603` cycles	`1.00`
`ML-KEM-512 decaps`	`30765` cycles	`30765` cycles	`1`
`ML-KEM-768 keypair`	`32272` cycles	`32272` cycles	`1`
`ML-KEM-768 encaps`	`35727` cycles	`35732` cycles	`1.00`
`ML-KEM-768 decaps`	`45872` cycles	`45878` cycles	`1.00`
`ML-KEM-1024 keypair`	`46840` cycles	`46836` cycles	`1.00`
`ML-KEM-1024 encaps`	`52612` cycles	`52612` cycles	`1`
`ML-KEM-1024 decaps`	`66495` cycles	`66492` cycles	`1.00`
Benchmark suite	Current: `271b362`	Previous: `e9e0eea`	Ratio
`ML-KEM-512 keypair`	`29190` cycles	`29187` cycles	`1.00`
`ML-KEM-512 encaps`	`35560` cycles	`35558` cycles	`1.00`
`ML-KEM-512 decaps`	`46112` cycles	`46109` cycles	`1.00`
`ML-KEM-768 keypair`	`49228` cycles	`49215` cycles	`1.00`
`ML-KEM-768 encaps`	`55407` cycles	`55389` cycles	`1.00`
`ML-KEM-768 decaps`	`70217` cycles	`70193` cycles	`1.00`
`ML-KEM-1024 keypair`	`72353` cycles	`72316` cycles	`1.00`
`ML-KEM-1024 encaps`	`81163` cycles	`81115` cycles	`1.00`
`ML-KEM-1024 decaps`	`100914` cycles	`100848` cycles	`1.00`
Benchmark suite	Current: `271b362`	Previous: `e9e0eea`	Ratio
`ML-KEM-512 keypair`	`57964` cycles	`57872` cycles	`1.00`
`ML-KEM-512 encaps`	`65238` cycles	`65139` cycles	`1.00`
`ML-KEM-512 decaps`	`83987` cycles	`83694` cycles	`1.00`
`ML-KEM-768 keypair`	`97986` cycles	`98126` cycles	`1.00`
`ML-KEM-768 encaps`	`109131` cycles	`109055` cycles	`1.00`
`ML-KEM-768 decaps`	`135466` cycles	`135879` cycles	`1.00`
`ML-KEM-1024 keypair`	`148680` cycles	`148610` cycles	`1.00`
`ML-KEM-1024 encaps`	`164777` cycles	`165125` cycles	`1.00`
`ML-KEM-1024 decaps`	`200003` cycles	`200493` cycles	`1.00`