Improve the crypto library documentation
Subsystems (3)
Eric Biggers
maintainerv2 cover Improve the crypto library documentation
While the crypto library already has a lot of kernel-doc, it's not being included in the HTML or PDF documentation (except for the SHA-3 kernenl-doc which is already included). Update Documentation/crypto/ to include it, and also add a high-level overview of the library.
I'd like to take this series via the libcrypto tree for 7.1.
Changed in v2:
- Use simple string replacement instead of regex in kdoc_parser.py
- Minor editorial revisions
Eric Biggers (2):
docs: kdoc: Expand 'at_least' when creating parameter list lib/crypto: docs: Add rst documentation to Documentation/crypto/
Documentation/crypto/index.rst | 2 +- .../crypto/libcrypto-blockcipher.rst | 19 ++ Documentation/crypto/libcrypto-hash.rst | 86 +++++++++ Documentation/crypto/libcrypto-signature.rst | 11 ++ Documentation/crypto/libcrypto-utils.rst | 6 + Documentation/crypto/libcrypto.rst | 165 ++++++++++++++++++ Documentation/crypto/sha3.rst | 2 + tools/lib/python/kdoc/kdoc_parser.py | 5 + 8 files changed, 295 insertions(+), 1 deletion(-) create mode 100644 Documentation/crypto/libcrypto-blockcipher.rst create mode 100644 Documentation/crypto/libcrypto-hash.rst create mode 100644 Documentation/crypto/libcrypto-signature.rst create mode 100644 Documentation/crypto/libcrypto-utils.rst create mode 100644 Documentation/crypto/libcrypto.rst
base-commit: 8541d8f725c673db3bd741947f27974358b2e163
Signature · 1 line
2.53.0
Eric Biggers
maintainerPATCH v2 1/2 docs: kdoc: Expand 'at_least' when creating parameter list
sphinx doesn't know that the kernel headers do:
#define at_least static
Do this replacement before declarations are passed to it.
This prevents errors like the following from appearing once the lib/crypto/ kernel-doc is wired up to the sphinx build:
linux/Documentation/crypto/libcrypto:128: ./include/crypto/sha2.h:773: WARNING: Error in declarator or parameters
Error in declarator or parameters
Invalid C declaration: Expected ']' in end of array operator. [error at 59]
void sha512_final (struct sha512_ctx *ctx, u8 out[at_least SHA512_DIGEST_SIZE])
--- tools/lib/python/kdoc/kdoc_parser.py | 5 +++++ 1 file changed, 5 insertions(+)
tools/lib/python/kdoc/kdoc_parser.py +5 -0
@@ -437,10 +437,15 @@ class KernelDoc: for arg in args.split(splitter): # Ignore argument attributes arg = KernRe(r'\sPOS0?\s').sub(' ', arg) + # Replace '[at_least ' with '[static '. This allows sphinx to parse + # array parameter declarations like 'char A[at_least 4]', where + # 'at_least' is #defined to 'static' by the kernel headers. + arg = arg.replace('[at_least ', '[static ') + # Strip leading/trailing spaces arg = arg.strip() arg = KernRe(r'\s+').sub(' ', arg, count=1) if arg.startswith('#'):
Signature · 1 line
2.53.0
Re: [PATCH v2 1/2] docs: kdoc: Expand 'at_least' when creating parameter list
Quoted 9 lines · Eric Biggers
sphinx doesn't know that the kernel headers do:
#define at_least staticDo this replacement before declarations are passed to it.
This prevents errors like the following from appearing once the
lib/crypto/kernel-doc is wired up to the sphinx build:
Quoted 8 lines
linux/Documentation/crypto/libcrypto:128:
./include/crypto/sha2.h:773: WARNING: Error in declarator or parameters
Error in declarator or parameters
Invalid C declaration: Expected ']' in end of array operator. [error at 59]
voidsha512_final(structsha512_ctx*ctx, u8 out[at_leastSHA512_DIGEST_SIZE])Acked-by Jonathan Corbet <[email protected]>Reviewed-by Ard Biesheuvel <[email protected]>Signed-off-by Eric Biggers <[email protected]>
Quoted 24 lines
--- tools/lib/python/kdoc/kdoc_parser.py | 5 +++++ 1 file changed, 5 insertions(+)tools/lib/python/kdoc/kdoc_parser.py +5
-0@@ -437,10 +437,15 @@ class KernelDoc: for arg in args.split(splitter): # Ignore argument attributes arg = KernRe(r'\sPOS0?\s').sub(' ', arg) + # Replace '[at_least ' with '[static '. This allows sphinx to parse + # array parameter declarations like 'char A[at_least 4]', where + # 'at_least' is #defined to 'static' by the kernel headers. + arg = arg.replace('[at_least ', '[static ') + # Strip leading/trailing spaces arg = arg.strip() arg = KernRe(r'\s+').sub(' ', arg, count=1) if arg.startswith('#'):
Signature · 1 line
~Randy
Eric Biggers
maintainerPATCH v2 2/2 lib/crypto: docs: Add rst documentation to Documentation/crypto/
In reply to Eric BiggersAdd a documentation file Documentation/crypto/libcrypto.rst which provides a high-level overview of lib/crypto/.
Also add several sub-pages which include the kernel-doc for the algorithms that have it. This makes the existing, quite extensive kernel-doc start being included in the HTML and PDF documentation.
Note that the intent is very much *not* that everyone has to read these Documentation/ files. The library is intended to be straightforward and use familiar conventions; generally it should be possible to dive right into the kernel-doc. You shouldn't need to read a lot of documentation to just call sha256(), for example, or to run the unit tests if you're already familiar with KUnit. (This differs from the traditional crypto API which has a larger barrier to entry.)
Nevertheless, this seems worth adding. Hopefully it is useful and makes LWN no longer consider the library to be "meticulously undocumented".
--- Documentation/crypto/index.rst | 2 +- .../crypto/libcrypto-blockcipher.rst | 19 ++ Documentation/crypto/libcrypto-hash.rst | 86 +++++++++ Documentation/crypto/libcrypto-signature.rst | 11 ++ Documentation/crypto/libcrypto-utils.rst | 6 + Documentation/crypto/libcrypto.rst | 165 ++++++++++++++++++ Documentation/crypto/sha3.rst | 2 + 7 files changed, 290 insertions(+), 1 deletion(-) create mode 100644 Documentation/crypto/libcrypto-blockcipher.rst create mode 100644 Documentation/crypto/libcrypto-hash.rst create mode 100644 Documentation/crypto/libcrypto-signature.rst create mode 100644 Documentation/crypto/libcrypto-utils.rst create mode 100644 Documentation/crypto/libcrypto.rst
Documentation/crypto/index.rst +1 -1
@@ -11,10 +11,11 @@ for cryptographic use cases, as well as programming examples. .. toctree:: :caption: Table of contents :maxdepth: 2 + libcrypto intro api-intro architecture async-tx-api
@@ -25,6 +26,5 @@ for cryptographic use cases, as well as programming examples. api api-samples descore-readme device_drivers/index krb5 - sha3
Documentation/crypto/libcrypto-blockcipher.rst new file +19 -0
@@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Block ciphers +============= + +AES +--- + +Support for the AES block cipher. + +.. kernel-doc:: include/crypto/aes.h + +DES +--- + +Support for the DES block cipher. This algorithm is obsolete and is supported +only for backwards compatibility. + +.. kernel-doc:: include/crypto/des.h
Documentation/crypto/libcrypto-hash.rst new file +86 -0
86 lines not on this page · raw message
Documentation/crypto/libcrypto-signature.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Digital signature algorithms +============================ + +ML-DSA +------ + +Support for the ML-DSA digital signature algorithm. + +.. kernel-doc:: include/crypto/mldsa.h
Documentation/crypto/libcrypto-utils.rst new file +6 -0
@@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Utility functions +================= + +.. kernel-doc:: include/crypto/utils.h
Documentation/crypto/libcrypto.rst new file +165 -0
165 lines not on this page · raw message
Documentation/crypto/sha3.rst +2 -0
@@ -1,7 +1,9 @@ .. SPDX-License-Identifier: GPL-2.0-or-later +.. _sha3: + ========================== SHA-3 Algorithm Collection ========================== .. contents::
Signature · 1 line
2.53.0
Re: [PATCH v2 2/2] lib/crypto: docs: Add rst documentation to Documentation/crypto/
Quoted 15 lines · Eric Biggers
Add a documentation file
Documentation/crypto/libcrypto.rstwhich provides a high-level overview oflib/crypto/.Also add several sub-pages which include the kernel-doc for the algorithms that have it. This makes the existing, quite extensive kernel-doc start being included in the HTML and PDF documentation.
Note that the intent is very much *not* that everyone has to read these
Documentation/files. The library is intended to be straightforward and use familiar conventions; generally it should be possible to dive right into the kernel-doc. You shouldn't need to read a lot of documentation to just callsha256(), for example, or to run the unit tests if you're already familiar with KUnit. (This differs from the traditional crypto API which has a larger barrier to entry.)
Quoted 5 lines
Nevertheless, this seems worth adding. Hopefully it is useful and makes LWN no longer consider the library to be "meticulously undocumented".
Reviewed-by Ard Biesheuvel <[email protected]>Signed-off-by Eric Biggers <[email protected]>
Quoted 15 lines
--- Documentation/crypto/index.rst | 2 +- .../crypto/libcrypto-blockcipher.rst | 19 ++ Documentation/crypto/libcrypto-hash.rst | 86 +++++++++ Documentation/crypto/libcrypto-signature.rst | 11 ++ Documentation/crypto/libcrypto-utils.rst | 6 + Documentation/crypto/libcrypto.rst | 165 ++++++++++++++++++ Documentation/crypto/sha3.rst | 2 + 7 files changed, 290 insertions(+), 1 deletion(-) create mode 100644 Documentation/crypto/libcrypto-blockcipher.rst create mode 100644 Documentation/crypto/libcrypto-hash.rst create mode 100644 Documentation/crypto/libcrypto-signature.rst create mode 100644 Documentation/crypto/libcrypto-utils.rst create mode 100644 Documentation/crypto/libcrypto.rst
Signature · 1 line
~Randy