From 8363e3c6a128f02a4b8fa2edf877c0fe26629a46 Mon Sep 17 00:00:00 2001 From: Paul Duncan Date: Thu, 9 May 2024 01:49:27 -0400 Subject: sha3.c: document how to add a new backend --- sha3.c | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/sha3.c b/sha3.c index f456f7e..14d518e 100644 --- a/sha3.c +++ b/sha3.c @@ -33,6 +33,35 @@ // there are currently 5 backends, but only 2 of them -- scalar and // avx512 -- are auto-detected. the remaining three are experimental // neon backends and are currently slower than the scalar backend. +// +// To add a new backend: +// +// 1. Add a "#define BACKEND_FOO UNIQUE_ID" line to this section. +// Example: "#define BACKEND_FOO 99". +// 2. (optional) if the backend can be automatically detected, add a +// #elif branch to the auto-detect section below. +// 3. Add a section which begins with "#if BACKEND == BACKEND_FOO" and +// ends with "#endif /* BACKEND == BACKEND_FOO */" and contains a +// `permute_n_foo()` function and any helper functions. +// 4. Add a branch to the "map permute_n()" block which maps +// `permute_n()` to `permute_n_foo()`. +// 5. Add a branch to the "sha3_backend()" which returns the name of +// your backend. +// 6. Add `test_permute_12_foo()` and `test_permute_24_foo()` test +// functions in the TEST_SHA3 block. Use the test functions for the +// other backends as a template. +// 7. Add calls to the test functions from the previous step to `main()`. +// +// At this point you should be able to run the test suite and build the +// top-level shared library, the top-level example application, and the +// applications in the `examples/` directory with your new backend. +// +// For example, to run the test suite against the backend with a unique +// ID of 99, you would do this: +// +// # run test suite against backend 99 +// make test BACKEND=99 +// #define BACKEND_AUTO 0 // auto-detect (default) #define BACKEND_SCALAR 1 // scalar backend #define BACKEND_AVX512 2 // AVX-512 backend @@ -1281,6 +1310,7 @@ static inline void permute_n_hybrid(uint64_t a[static 25], const size_t num_roun } #endif /* (BACKEND == BACKEND_HYBRID) */ +// map permute_n() to active backend #if BACKEND == BACKEND_AVX512 #define permute_n permute_n_avx512 // use avx512 backend #elif BACKEND == BACKEND_NEON @@ -1312,9 +1342,6 @@ static inline void permute_12(uint64_t s[static 25]) { permute_n(s, 12); } -// absorb message into state, return updated byte count -// used by `hash_absorb()`, `hash_once()`, and `xof_absorb_raw()` - /** * @brief Absorb message into state and return updated byte count. * -- cgit v1.2.3