Hi Ayoub, On 2026-09-18T17:21:23, Ayoub Zaki <[email protected]> wrote: > doc: describe ML-DSA verification > > Document the verifier config symbol and the raw FIPS 204 public-key > and signature encodings accepted by the public API. Describe the > single per-parameter-set workspace allocation. > > Record the exact Linux file revisions used for the port. Explain which > kernel facilities were dropped or replaced by U-Boot equivalents. > > Note that the initial API takes one contiguous message. State that FIT > and mkimage integration is deferred to a separate series. > > Signed-off-by: Ayoub Zaki <[email protected]> > > doc/develop/index.rst | 1 + > doc/develop/mldsa.rst | 67 > +++++++++++++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 68 insertions(+)
> diff --git a/doc/develop/mldsa.rst b/doc/develop/mldsa.rst > @@ -0,0 +1,67 @@ > +Verification makes a single heap allocation whose size depends on the > +parameter set and ABI alignment. Targets with 8-byte ``u64`` alignment use > +8800 bytes for ML-DSA-44, 10336 bytes for ML-DSA-65 and 12896 bytes for > +ML-DSA-87. This includes x86_64 and 32-bit ARM EABI. Targets with 4-byte > +``u64`` alignment use 8792 bytes, 10328 bytes and 12888 bytes respectively. These exact byte counts depend on the layout of struct shake_ctx and struct mldsa_verification_workspace. They will be wrong as soon as either struct changes (e.g. when a Linux fix is pulled in), and nothing will catch it. Please can you give an approximate figure (about 9KB to 13KB, as in the cover letter) and point to the workspace_len calculation in mldsa_verify()? If the exact values matter, a unit test that checks them would keep them accurate. > diff --git a/doc/develop/mldsa.rst b/doc/develop/mldsa.rst > @@ -0,0 +1,67 @@ > +The verifier, SHAKE code, APIs and test vectors were adapted from these exact > +Linux file revisions:: > + > + include/crypto/sha3.h > + f1799d17285ca99243328cd92133a9f84ee3a593 > + lib/crypto/sha3.c > + 0354d3c1f1b8628e60eceb304b6d2ef75eea6f41 > + include/crypto/mldsa.h > + lib/crypto/mldsa.c > + ffd42b6d0420c4be97cc28fd1bb5f4c29e286e98 > + lib/crypto/tests/mldsa_kunit.c > + lib/crypto/tests/mldsa-testvecs.h > + ed894faccb8de55cd755e093c4b0971f190d384d > + > +Each imported file header links to its corresponding kernel.org commit. The These commits are already recorded in each file header and in the commit messages. Every Linux sync then means updating two places, and given Tom's concern about maintenance, they will likely drift apart. I suggest treating the file headers as the single source of truth and having the doc point to them. Alternatively, keep this table and add a note that it must be updated with each sync. What do you think? > diff --git a/doc/develop/mldsa.rst b/doc/develop/mldsa.rst > @@ -0,0 +1,67 @@ > +The initial API accepts one contiguous message. Its Linux origin does the > same. > +There is no FIT or mkimage integration yet. A follow-up can add a generic > +incremental API that lets the verifier absorb FIT signed regions directly. Plans for future work go stale in documentation. I suggest keeping them in the cover letter and having the doc describe only what exists now. Regards, Simon
