Examples: Add monolithic_build_multilevel example

This ports the monolithic_build_multilevel from mlkem-native.
This examples demonstrated how to build multiple instances of mldsa-native in a
single compilation unit

Signed-off-by: Matthias J. Kannwischer <[email protected]>

Author: mkannwischer

BIBLIOGRAPHY.md

@@ -17,6 +17,7 @@ source code and documentation.
   - [examples/monolithic_build/config_44.h](examples/monolithic_build/config_44.h)
   - [examples/monolithic_build/config_65.h](examples/monolithic_build/config_65.h)
   - [examples/monolithic_build/config_87.h](examples/monolithic_build/config_87.h)
+  - [examples/monolithic_build_multilevel/multilevel_config.h](examples/monolithic_build_multilevel/multilevel_config.h)
   - [integration/liboqs/config_aarch64.h](integration/liboqs/config_aarch64.h)
   - [integration/liboqs/config_c.h](integration/liboqs/config_c.h)
   - [integration/liboqs/config_x86_64.h](integration/liboqs/config_x86_64.h)
@@ -51,6 +52,7 @@ source code and documentation.
   - [examples/monolithic_build/config_44.h](examples/monolithic_build/config_44.h)
   - [examples/monolithic_build/config_65.h](examples/monolithic_build/config_65.h)
   - [examples/monolithic_build/config_87.h](examples/monolithic_build/config_87.h)
+  - [examples/monolithic_build_multilevel/multilevel_config.h](examples/monolithic_build_multilevel/multilevel_config.h)
   - [mldsa/mldsa_native.h](mldsa/mldsa_native.h)
   - [mldsa/src/config.h](mldsa/src/config.h)
   - [mldsa/src/ct.h](mldsa/src/ct.h)

examples/monolithic_build_multilevel/.gitignore

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+
+build/
+*.d

examples/monolithic_build_multilevel/Makefile

@@ -0,0 +1,103 @@
+# Copyright (c) The mlkem-native project authors
+# Copyright (c) The mldsa-native project authors
+# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+
+.PHONY: build run clean
+.DEFAULT_GOAL := all
+
+CC  ?= gcc
+AR  ?= ar
+
+# Adjust CFLAGS if needed
+CFLAGS := \
+	-Wall \
+	-Wextra \
+	-Werror=unused-result \
+	-Wpedantic \
+	-Werror \
+	-Wmissing-prototypes \
+	-Wshadow \
+	-Wpointer-arith \
+	-Wredundant-decls \
+	-Wconversion \
+	-Wsign-conversion \
+	-Wno-long-long \
+	-Wno-unknown-pragmas \
+	-Wno-unused-command-line-argument \
+	-O3 \
+	-fomit-frame-pointer \
+	-std=c99 \
+	-pedantic \
+	-MMD \
+	$(CFLAGS)
+
+
+# The following only concerns the cross-compilation tests.
+# You can likely ignore the following for your application.
+#
+# Append cross-prefix for cross compilation
+# When called from the root Makefile, CROSS_PREFIX has already been added here
+ifeq (,$(findstring $(CROSS_PREFIX),$(CC)))
+CC  := $(CROSS_PREFIX)$(CC)
+endif
+
+ifeq (,$(findstring $(CROSS_PREFIX),$(AR)))
+AR  := $(CROSS_PREFIX)$(AR)
+endif
+
+# Part A:
+#
+# mldsa-native source and header files
+#
+# Here, we use just a single monolithic compilation unit to include
+# multiple instances of mldsa-native.
+
+MLD_SOURCE=mldsa_native_all.c
+
+INC=-Imldsa/ -I./
+
+# Part B:
+#
+# Random number generator
+#
+# !!! WARNING !!!
+#
+# The randombytes() implementation used here is for TESTING ONLY.
+# You MUST NOT use this implementation outside of testing.
+#
+# !!! WARNING !!!
+RNG_SOURCE=$(wildcard test_only_rng/*.c)
+
+# Part C:
+#
+# Your application source code
+APP_SOURCE=$(RNG_SOURCE) main.c
+
+BUILD_DIR=build
+BIN=test_binary
+LIB=libmldsa.a
+
+BINARY_NAME_FULL=$(BUILD_DIR)/$(BIN)
+LIB_NAME_FULL=$(BUILD_DIR)/$(LIB)
+
+$(LIB_NAME_FULL): $(MLD_SOURCE)
+	echo "$@"
+	mkdir -p $(BUILD_DIR)
+	$(CC) -c $(CFLAGS) $(INC) $^ -o $(BUILD_DIR)/mldsa_native.o
+	$(AR) rcs $@ $(BUILD_DIR)/mldsa_native.o
+	strip -S $@
+
+$(BINARY_NAME_FULL): $(APP_SOURCE) $(LIB_NAME_FULL)
+	echo "$@"
+	mkdir -p $(BUILD_DIR)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@
+
+all: build
+
+build: $(BINARY_NAME_FULL)
+
+run: $(BINARY_NAME_FULL)
+	$(EXEC_WRAPPER) ./$(BINARY_NAME_FULL)
+
+clean:
+	rm -rf $(BUILD_DIR)

examples/monolithic_build_multilevel/README.md

@@ -0,0 +1,87 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Multi-level mldsa-native in a single compilation unit
+
+This directory contains a minimal example for how to build multiple instances of mldsa-native in a single compilation
+unit. Only the C-backend is exercised.
+
+The auto-generated source file [mldsa_native.c](mldsa/mldsa_native.c) includes all mldsa-native C source
+files. Moreover, it clears all `#define`s clauses set by mldsa-native at the end, and is hence amenable to multiple
+inclusion in another compilation unit.
+
+The manually written source file [mldsa_native_all.c](mldsa_native_all.c) includes
+[mldsa_native.c](mldsa/mldsa_native.c) three times, each time using the fixed config
+[multilevel_config.h](multilevel_config.h), but changing the security level (specified
+by `MLD_CONFIG_PARAMETER_SET`) every time.
+```C
+#define MLD_CONFIG_FILE "multilevel_config.h"
+
+/* Three instances of mldsa-native for all security levels */
+
+/* Include level-independent code */
+#define MLD_CONFIG_MULTILEVEL_WITH_SHARED
+/* Keep level-independent headers at the end of monobuild file */
+#define MLD_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS
+#define MLD_CONFIG_PARAMETER_SET 44
+#include "mldsa_native.c"
+#undef MLD_CONFIG_PARAMETER_SET
+#undef MLD_CONFIG_MULTILEVEL_WITH_SHARED
+
+/* Exclude level-independent code */
+#define MLD_CONFIG_MULTILEVEL_NO_SHARED
+#define MLD_CONFIG_PARAMETER_SET 65
+#include "mldsa_native.c"
+#undef MLD_CONFIG_PARAMETER_SET
+/* `#undef` all headers at the and of the monobuild file */
+#undef MLD_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS
+
+#define MLD_CONFIG_PARAMETER_SET 87
+#include "mldsa_native.c"
+#undef MLD_CONFIG_PARAMETER_SET
+```
+
+Note the setting `MLD_CONFIG_MULTILEVEL_WITH_SHARED` which forces the inclusion of all level-independent
+code in the MLDSA-44 build, and the setting `MLD_CONFIG_MULTILEVEL_NO_SHARED`, which drops all
+level-independent code in the subsequent builds. Finally, `MLD_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS` entails that
+`mldsa_native.c` does not `#undefine` the `#define` clauses from level-independent files.
+
+To make the monolithic multi-level build accessible from the application source [main.c](main.c), we provide
+[mldsa_native_all.h](mldsa_native_all.h), which includes [mldsa_native.h](../../mldsa/mldsa_native.h) once per
+configuration. Note that we don't refer to the configuration using `MLD_CONFIG_FILE`, but by setting
+`MLD_CONFIG_API_XXX` explicitly. Otherwise, [mldsa_native.h](../../mldsa/mldsa_native.h) would include the confg, which
+would lead to name-clashes upon multiple use.
+
+```C
+#define MLD_CONFIG_API_NO_SUPERCOP
+
+/* API for MLDSA-44 */
+#define MLD_CONFIG_API_PARAMETER_SET 44
+#define MLD_CONFIG_API_NAMESPACE_PREFIX mldsa44
+#include <mldsa_native.h>
+#undef MLD_CONFIG_API_PARAMETER_SET
+#undef MLD_CONFIG_API_NAMESPACE_PREFIX
+#undef MLD_H
+
+/* API for MLDSA-65*/
+#define MLD_CONFIG_API_PARAMETER_SET 65
+#define MLD_CONFIG_API_NAMESPACE_PREFIX mldsa65
+#include <mldsa_native.h>
+#undef MLD_CONFIG_API_PARAMETER_SET
+#undef MLD_CONFIG_API_NAMESPACE_PREFIX
+#undef MLD_H
+
+/* API for MLDSA_87 */
+#define MLD_CONFIG_API_PARAMETER_SET 87
+#define MLD_CONFIG_API_NAMESPACE_PREFIX mldsa87
+#include <mldsa_native.h>
+#undef MLD_CONFIG_API_PARAMETER_SET
+#undef MLD_CONFIG_API_NAMESPACE_PREFIX
+#undef MLD_H
+```
+
+## Usage
+
+Build this example with `make build`, run with `make run`.
+
+**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
+outside of testing.