Make allocation of large structures/buffers configurable (without workspaces)

.github/actions/config-variations/action.yml

@@ -8,7 +8,10 @@ inputs:
     description: 'GitHub token'
     required: true
   tests:
-    description: 'List of tests to run (space-separated IDs) or "all" for all tests. Available IDs: pct-enabled, pct-enabled-broken, custom-zeroize, native-cap-ON, native-cap-OFF, native-cap-ID_AA64PFR1_EL1, native-cap-CPUID_AVX2, no-asm, serial-fips202, custom-randombytes, custom-memcpy, custom-memset, custom-stdlib, nblocks-1, nblocks-2, nblocks-4'
+    description: 'List of tests to run (space-separated IDs) or "all" for all tests. Available IDs: pct-enabled,
+    pct-enabled-broken, custom-alloc-heap, custom-zeroize, native-cap-ON, native-cap-OFF, native-cap-ID_AA64PFR1_EL1,
+    native-cap-CPUID_AVX2, no-asm, serial-fips202, custom-randombytes, custom-memcpy, custom-memset, custom-stdlib,
+    nblocks-1, nblocks-2, nblocks-4'
     required: false
     default: 'all'
   opt:
@@ -47,6 +50,20 @@ runs:
         else
            echo "PCT failed as expected"
         fi
+    - name: "Custom allocation (heap based)"
+      if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-alloc-heap') }}
+      uses: ./.github/actions/multi-functest
+      with:
+        gh_token: ${{ inputs.gh_token }}
+        compile_mode: native
+        cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLK_CONFIG_FILE=\\\\\\\"custom_heap_alloc_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+        func: true
+        kat: true
+        acvp: true
+        opt: ${{ inputs.opt }}
+        extra_env: 'ASAN_OPTIONS=detect_leaks=1'
+        examples: false # Some examples use a custom config themselves
     - name: "Custom zeroization (explicit_bzero)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-zeroize') }}
       uses: ./.github/actions/multi-functest

BIBLIOGRAPHY.md

@@ -53,6 +53,7 @@ source code and documentation.
   - [mlkem/mlkem_native_config.h](mlkem/mlkem_native_config.h)
   - [mlkem/src/kem.c](mlkem/src/kem.c)
   - [test/break_pct_config.h](test/break_pct_config.h)
+  - [test/custom_heap_alloc_config.h](test/custom_heap_alloc_config.h)
   - [test/custom_memcpy_config.h](test/custom_memcpy_config.h)
   - [test/custom_memset_config.h](test/custom_memset_config.h)
   - [test/custom_native_capability_config_0.h](test/custom_native_capability_config_0.h)
@@ -111,6 +112,7 @@ source code and documentation.
   - [mlkem/src/symmetric.h](mlkem/src/symmetric.h)
   - [mlkem/src/verify.h](mlkem/src/verify.h)
   - [test/break_pct_config.h](test/break_pct_config.h)
+  - [test/custom_heap_alloc_config.h](test/custom_heap_alloc_config.h)
   - [test/custom_memcpy_config.h](test/custom_memcpy_config.h)
   - [test/custom_memset_config.h](test/custom_memset_config.h)
   - [test/custom_native_capability_config_0.h](test/custom_native_capability_config_0.h)

examples/basic_deterministic/mlkem_native/mlkem_native_config.h

@@ -459,6 +459,52 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLK_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: Set this option and define `MLK_CUSTOM_ALLOC` and
+ *              `MLK_CUSTOM_FREE` if you want to use custom allocation for
+ *              large local structures or buffers.
+ *
+ *              By default, all buffers/structures are allocated on the stack.
+ *              If this option is set, most of them will be allocated via
+ *              MLK_CUSTOM_ALLOC.
+ *
+ *              Parameters to MLK_CUSTOM_ALLOC:
+ *              - T* v: Target pointer to declare.
+ *              - T: Type of structure to be allocated
+ *              - N: Number of elements to be allocated.
+ *
+ *              Parameters to MLK_CUSTOM_FREE:
+ *              - T* v: Target pointer to free. May be NULL.
+ *              - T: Type of structure to be freed.
+ *              - N: Number of elements to be freed.
+ *
+ *              WARNING: This option is experimental!
+ *              Its scope, configuration and function/macro signatures may
+ *              change at any time. We expect a stable API for v2.
+ *
+ *              NOTE: Even if this option is set, some allocations further down
+ *              the call stack will still be made from the stack, consuming up
+ *              to 3KB of stack space. Those will likely be added to the scope
+ *              of this option in the future.
+ *
+ *              NOTE: MLK_CUSTOM_ALLOC need not guarantee a successful
+ *              allocation nor include error handling. Upon failure, the
+ *              target pointer should simply be set to NULL. The calling
+ *              code will handle this case and invoke MLK_CUSTOM_FREE.
+ *
+ *****************************************************************************/
+/* #define MLK_CONFIG_CUSTOM_ALLOC_FREE
+   #if !defined(__ASSEMBLER__)
+   #include <stdlib.h>
+   #define MLK_CUSTOM_ALLOC(v, T, N)                              \
+     T* (v) = (T *)aligned_alloc(MLK_DEFAULT_ALIGN,               \
+                                 MLK_ALIGN_UP(sizeof(T) * (N)))
+   #define MLK_CUSTOM_FREE(v, T, N) free(v)
+   #endif
+*/
+
 /******************************************************************************
  * Name:        MLK_CONFIG_CUSTOM_MEMCPY
  *

examples/bring_your_own_fips202/mlkem_native/mlkem_native_config.h

@@ -459,6 +459,52 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLK_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: Set this option and define `MLK_CUSTOM_ALLOC` and
+ *              `MLK_CUSTOM_FREE` if you want to use custom allocation for
+ *              large local structures or buffers.
+ *
+ *              By default, all buffers/structures are allocated on the stack.
+ *              If this option is set, most of them will be allocated via
+ *              MLK_CUSTOM_ALLOC.
+ *
+ *              Parameters to MLK_CUSTOM_ALLOC:
+ *              - T* v: Target pointer to declare.
+ *              - T: Type of structure to be allocated
+ *              - N: Number of elements to be allocated.
+ *
+ *              Parameters to MLK_CUSTOM_FREE:
+ *              - T* v: Target pointer to free. May be NULL.
+ *              - T: Type of structure to be freed.
+ *              - N: Number of elements to be freed.
+ *
+ *              WARNING: This option is experimental!
+ *              Its scope, configuration and function/macro signatures may
+ *              change at any time. We expect a stable API for v2.
+ *
+ *              NOTE: Even if this option is set, some allocations further down
+ *              the call stack will still be made from the stack, consuming up
+ *              to 3KB of stack space. Those will likely be added to the scope
+ *              of this option in the future.
+ *
+ *              NOTE: MLK_CUSTOM_ALLOC need not guarantee a successful
+ *              allocation nor include error handling. Upon failure, the
+ *              target pointer should simply be set to NULL. The calling
+ *              code will handle this case and invoke MLK_CUSTOM_FREE.
+ *
+ *****************************************************************************/
+/* #define MLK_CONFIG_CUSTOM_ALLOC_FREE
+   #if !defined(__ASSEMBLER__)
+   #include <stdlib.h>
+   #define MLK_CUSTOM_ALLOC(v, T, N)                              \
+     T* (v) = (T *)aligned_alloc(MLK_DEFAULT_ALIGN,               \
+                                 MLK_ALIGN_UP(sizeof(T) * (N)))
+   #define MLK_CUSTOM_FREE(v, T, N) free(v)
+   #endif
+*/
+
 /******************************************************************************
  * Name:        MLK_CONFIG_CUSTOM_MEMCPY
  *

examples/bring_your_own_fips202_static/mlkem_native/mlkem_native_config.h

@@ -460,6 +460,52 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLK_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: Set this option and define `MLK_CUSTOM_ALLOC` and
+ *              `MLK_CUSTOM_FREE` if you want to use custom allocation for
+ *              large local structures or buffers.
+ *
+ *              By default, all buffers/structures are allocated on the stack.
+ *              If this option is set, most of them will be allocated via
+ *              MLK_CUSTOM_ALLOC.
+ *
+ *              Parameters to MLK_CUSTOM_ALLOC:
+ *              - T* v: Target pointer to declare.
+ *              - T: Type of structure to be allocated
+ *              - N: Number of elements to be allocated.
+ *
+ *              Parameters to MLK_CUSTOM_FREE:
+ *              - T* v: Target pointer to free. May be NULL.
+ *              - T: Type of structure to be freed.
+ *              - N: Number of elements to be freed.
+ *
+ *              WARNING: This option is experimental!
+ *              Its scope, configuration and function/macro signatures may
+ *              change at any time. We expect a stable API for v2.
+ *
+ *              NOTE: Even if this option is set, some allocations further down
+ *              the call stack will still be made from the stack, consuming up
+ *              to 3KB of stack space. Those will likely be added to the scope
+ *              of this option in the future.
+ *
+ *              NOTE: MLK_CUSTOM_ALLOC need not guarantee a successful
+ *              allocation nor include error handling. Upon failure, the
+ *              target pointer should simply be set to NULL. The calling
+ *              code will handle this case and invoke MLK_CUSTOM_FREE.
+ *
+ *****************************************************************************/
+/* #define MLK_CONFIG_CUSTOM_ALLOC_FREE
+   #if !defined(__ASSEMBLER__)
+   #include <stdlib.h>
+   #define MLK_CUSTOM_ALLOC(v, T, N)                              \
+     T* (v) = (T *)aligned_alloc(MLK_DEFAULT_ALIGN,               \
+                                 MLK_ALIGN_UP(sizeof(T) * (N)))
+   #define MLK_CUSTOM_FREE(v, T, N) free(v)
+   #endif
+*/
+
 /******************************************************************************
  * Name:        MLK_CONFIG_CUSTOM_MEMCPY
  *

examples/custom_backend/mlkem_native/mlkem_native_config.h

@@ -455,6 +455,52 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLK_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: Set this option and define `MLK_CUSTOM_ALLOC` and
+ *              `MLK_CUSTOM_FREE` if you want to use custom allocation for
+ *              large local structures or buffers.
+ *
+ *              By default, all buffers/structures are allocated on the stack.
+ *              If this option is set, most of them will be allocated via
+ *              MLK_CUSTOM_ALLOC.
+ *
+ *              Parameters to MLK_CUSTOM_ALLOC:
+ *              - T* v: Target pointer to declare.
+ *              - T: Type of structure to be allocated
+ *              - N: Number of elements to be allocated.
+ *
+ *              Parameters to MLK_CUSTOM_FREE:
+ *              - T* v: Target pointer to free. May be NULL.
+ *              - T: Type of structure to be freed.
+ *              - N: Number of elements to be freed.
+ *
+ *              WARNING: This option is experimental!
+ *              Its scope, configuration and function/macro signatures may
+ *              change at any time. We expect a stable API for v2.
+ *
+ *              NOTE: Even if this option is set, some allocations further down
+ *              the call stack will still be made from the stack, consuming up
+ *              to 3KB of stack space. Those will likely be added to the scope
+ *              of this option in the future.
+ *
+ *              NOTE: MLK_CUSTOM_ALLOC need not guarantee a successful
+ *              allocation nor include error handling. Upon failure, the
+ *              target pointer should simply be set to NULL. The calling
+ *              code will handle this case and invoke MLK_CUSTOM_FREE.
+ *
+ *****************************************************************************/
+/* #define MLK_CONFIG_CUSTOM_ALLOC_FREE
+   #if !defined(__ASSEMBLER__)
+   #include <stdlib.h>
+   #define MLK_CUSTOM_ALLOC(v, T, N)                              \
+     T* (v) = (T *)aligned_alloc(MLK_DEFAULT_ALIGN,               \
+                                 MLK_ALIGN_UP(sizeof(T) * (N)))
+   #define MLK_CUSTOM_FREE(v, T, N) free(v)
+   #endif
+*/
+
 /******************************************************************************
  * Name:        MLK_CONFIG_CUSTOM_MEMCPY
  *

examples/monolithic_build/mlkem_native/mlkem_native_config.h

@@ -458,6 +458,52 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLK_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: Set this option and define `MLK_CUSTOM_ALLOC` and
+ *              `MLK_CUSTOM_FREE` if you want to use custom allocation for
+ *              large local structures or buffers.
+ *
+ *              By default, all buffers/structures are allocated on the stack.
+ *              If this option is set, most of them will be allocated via
+ *              MLK_CUSTOM_ALLOC.
+ *
+ *              Parameters to MLK_CUSTOM_ALLOC:
+ *              - T* v: Target pointer to declare.
+ *              - T: Type of structure to be allocated
+ *              - N: Number of elements to be allocated.
+ *
+ *              Parameters to MLK_CUSTOM_FREE:
+ *              - T* v: Target pointer to free. May be NULL.
+ *              - T: Type of structure to be freed.
+ *              - N: Number of elements to be freed.
+ *
+ *              WARNING: This option is experimental!
+ *              Its scope, configuration and function/macro signatures may
+ *              change at any time. We expect a stable API for v2.
+ *
+ *              NOTE: Even if this option is set, some allocations further down
+ *              the call stack will still be made from the stack, consuming up
+ *              to 3KB of stack space. Those will likely be added to the scope
+ *              of this option in the future.
+ *
+ *              NOTE: MLK_CUSTOM_ALLOC need not guarantee a successful
+ *              allocation nor include error handling. Upon failure, the
+ *              target pointer should simply be set to NULL. The calling
+ *              code will handle this case and invoke MLK_CUSTOM_FREE.
+ *
+ *****************************************************************************/
+/* #define MLK_CONFIG_CUSTOM_ALLOC_FREE
+   #if !defined(__ASSEMBLER__)
+   #include <stdlib.h>
+   #define MLK_CUSTOM_ALLOC(v, T, N)                              \
+     T* (v) = (T *)aligned_alloc(MLK_DEFAULT_ALIGN,               \
+                                 MLK_ALIGN_UP(sizeof(T) * (N)))
+   #define MLK_CUSTOM_FREE(v, T, N) free(v)
+   #endif
+*/
+
 /******************************************************************************
  * Name:        MLK_CONFIG_CUSTOM_MEMCPY
  *

examples/monolithic_build_multilevel/mlkem_native/mlkem_native_config.h

@@ -459,6 +459,52 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLK_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: Set this option and define `MLK_CUSTOM_ALLOC` and
+ *              `MLK_CUSTOM_FREE` if you want to use custom allocation for
+ *              large local structures or buffers.
+ *
+ *              By default, all buffers/structures are allocated on the stack.
+ *              If this option is set, most of them will be allocated via
+ *              MLK_CUSTOM_ALLOC.
+ *
+ *              Parameters to MLK_CUSTOM_ALLOC:
+ *              - T* v: Target pointer to declare.
+ *              - T: Type of structure to be allocated
+ *              - N: Number of elements to be allocated.
+ *
+ *              Parameters to MLK_CUSTOM_FREE:
+ *              - T* v: Target pointer to free. May be NULL.
+ *              - T: Type of structure to be freed.
+ *              - N: Number of elements to be freed.
+ *
+ *              WARNING: This option is experimental!
+ *              Its scope, configuration and function/macro signatures may
+ *              change at any time. We expect a stable API for v2.
+ *
+ *              NOTE: Even if this option is set, some allocations further down
+ *              the call stack will still be made from the stack, consuming up
+ *              to 3KB of stack space. Those will likely be added to the scope
+ *              of this option in the future.
+ *
+ *              NOTE: MLK_CUSTOM_ALLOC need not guarantee a successful
+ *              allocation nor include error handling. Upon failure, the
+ *              target pointer should simply be set to NULL. The calling
+ *              code will handle this case and invoke MLK_CUSTOM_FREE.
+ *
+ *****************************************************************************/
+/* #define MLK_CONFIG_CUSTOM_ALLOC_FREE
+   #if !defined(__ASSEMBLER__)
+   #include <stdlib.h>
+   #define MLK_CUSTOM_ALLOC(v, T, N)                              \
+     T* (v) = (T *)aligned_alloc(MLK_DEFAULT_ALIGN,               \
+                                 MLK_ALIGN_UP(sizeof(T) * (N)))
+   #define MLK_CUSTOM_FREE(v, T, N) free(v)
+   #endif
+*/
+
 /******************************************************************************
  * Name:        MLK_CONFIG_CUSTOM_MEMCPY
  *