Received-SPF: pass (google.com: domain of linux-crypto-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Robert Elliott <elliott@hpe.com>
To:     herbert@gondor.apana.org.au, davem@davemloft.net, corbet@lwn.net,
        linux-crypto@vger.kernel.org, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
Cc:     Robert Elliott <elliott@hpe.com>
Subject: [PATCH v2 0/8] crypto: kernel-doc for assembly language
Date:   Mon, 19 Dec 2022 12:55:47 -0600
Message-Id: <20221219185555.433233-1-elliott@hpe.com>
In-Reply-To: <20221215063857.161665-1-elliott@hpe.com>
References: <20221215063857.161665-1-elliott@hpe.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Precedence: bulk

Clean up the existing kernel-doc headers in the crypto subsystem,
then add support for kernel-doc headers in assembly language files
for functions called from C code.

This provides a place to document the assumptions made by the
assembly language functions about their arguments (e.g., how
they handle length values of 0, less than some value, not
multiples of some value, etc.).

Not all the assembly language files are tackled yet - just some
of the x86 files pending changes related to kernel_fpu_begin/end.

Changes in patch series v2:
* rebased to upstream after Herbert's v6.2-p1 tag was merged
* made not dependent on any of the proposed FPU patches
  (instead, those will assume this is in place)
* adds Documentation for the new kernel-doc Prototype line

Example man page formatted output for one of them:

$ nroff -man /tmp/man/sha1_transform_avx2.9
sha1_transform_avx2(9)      Kernel Hacker's Manual      sha1_transform_avx2(9)

NAME
       sha1_transform_avx2  -  Calculate  SHA1 hash using the x86 AVX2 feature
       set

SYNOPSIS
       void sha1_transform_avx2 (u32 *digest , const u8 *data , int blocks );

ARGUMENTS
       digest      address of current 20-byte hash value (rdi, CTX macro)

       data        address of data (rsi, BUF macro); data size must be a mul‐
		   tiple of 64 bytes

       blocks      number of 64-byte blocks (rdx, CNT macro)

DESCRIPTION
       This function supports 64-bit CPUs.

RETURN
       none

PROTOTYPE
       asmlinkage  void  sha1_transform_avx2(u32  *digest, const u8 *data, int
       blocks)

December 2022                 sha1_transform_avx2 sha1_transform_avx2(9)


Robert Elliott (8):
  crypto: clean up kernel-doc headers
  doc: support kernel-doc for asm functions
  crypto: x86/sha - add kernel-doc comments to assembly
  crypto: x86/crc - add kernel-doc comments to assembly
  crypto: x86/sm3 - add kernel-doc comments to assembly
  crypto: x86/ghash - add kernel-doc comments to assembly
  crypto: x86/blake2s - add kernel-doc comments to assembly
  crypto: x86/chacha - add kernel-doc comments to assembly

 .../mips/cavium-octeon/crypto/octeon-crypto.c | 19 ++--
 arch/x86/crypto/blake2s-core.S                | 26 +++++
 arch/x86/crypto/chacha-avx2-x86_64.S          | 90 ++++++++++++------
 arch/x86/crypto/chacha-avx512vl-x86_64.S      | 94 ++++++++++++-------
 arch/x86/crypto/chacha-ssse3-x86_64.S         | 75 ++++++++++-----
 arch/x86/crypto/crc32-pclmul_asm.S            | 24 ++---
 arch/x86/crypto/crc32c-pcl-intel-asm_64.S     | 29 +++---
 arch/x86/crypto/crct10dif-pcl-asm_64.S        | 24 +++--
 arch/x86/crypto/ghash-clmulni-intel_asm.S     | 27 +++++-
 arch/x86/crypto/sha1_avx2_x86_64_asm.S        | 32 +++----
 arch/x86/crypto/sha1_ni_asm.S                 | 22 +++--
 arch/x86/crypto/sha1_ssse3_asm.S              | 33 ++++---
 arch/x86/crypto/sha256-avx-asm.S              | 24 +++--
 arch/x86/crypto/sha256-avx2-asm.S             | 25 +++--
 arch/x86/crypto/sha256-ssse3-asm.S            | 26 ++---
 arch/x86/crypto/sha256_ni_asm.S               | 25 ++---
 arch/x86/crypto/sha512-avx-asm.S              | 33 +++----
 arch/x86/crypto/sha512-avx2-asm.S             | 34 +++----
 arch/x86/crypto/sha512-ssse3-asm.S            | 36 ++++---
 arch/x86/crypto/sm3-avx-asm_64.S              | 18 ++--
 crypto/asymmetric_keys/verify_pefile.c        |  2 +-
 crypto/async_tx/async_pq.c                    | 11 +--
 crypto/async_tx/async_tx.c                    |  4 +-
 crypto/crypto_engine.c                        |  2 +-
 include/crypto/acompress.h                    |  2 +-
 include/crypto/des.h                          |  4 +-
 include/crypto/if_alg.h                       | 26 ++---
 include/crypto/internal/ecc.h                 |  8 +-
 include/crypto/internal/rsa.h                 |  2 +-
 include/crypto/kdf_sp800108.h                 | 39 ++++----
 scripts/kernel-doc                            | 48 +++++++++-
 31 files changed, 545 insertions(+), 319 deletions(-)

-- 
2.38.1


Robert Elliott (8):
  crypto: clean up kernel-doc headers
  doc: support kernel-doc for asm functions
  crypto: x86/sha - add kernel-doc comments to assembly
  crypto: x86/crc - add kernel-doc comments to assembly
  crypto: x86/sm3 - add kernel-doc comments to assembly
  crypto: x86/ghash - add kernel-doc comments to assembly
  crypto: x86/blake2s - add kernel-doc comments to assembly
  crypto: x86/chacha - add kernel-doc comments to assembly

 Documentation/doc-guide/kernel-doc.rst        | 79 ++++++++++++++++
 .../mips/cavium-octeon/crypto/octeon-crypto.c | 19 ++--
 arch/x86/crypto/blake2s-core.S                | 26 +++++
 arch/x86/crypto/chacha-avx2-x86_64.S          | 90 ++++++++++++------
 arch/x86/crypto/chacha-avx512vl-x86_64.S      | 94 ++++++++++++-------
 arch/x86/crypto/chacha-ssse3-x86_64.S         | 75 ++++++++++-----
 arch/x86/crypto/crc32-pclmul_asm.S            | 24 ++---
 arch/x86/crypto/crc32c-pcl-intel-asm_64.S     | 29 +++---
 arch/x86/crypto/crct10dif-pcl-asm_64.S        | 24 +++--
 arch/x86/crypto/ghash-clmulni-intel_asm.S     | 27 +++++-
 arch/x86/crypto/sha1_avx2_x86_64_asm.S        | 32 +++----
 arch/x86/crypto/sha1_ni_asm.S                 | 19 ++--
 arch/x86/crypto/sha1_ssse3_asm.S              | 33 ++++---
 arch/x86/crypto/sha256-avx-asm.S              | 23 +++--
 arch/x86/crypto/sha256-avx2-asm.S             | 24 +++--
 arch/x86/crypto/sha256-ssse3-asm.S            | 25 +++--
 arch/x86/crypto/sha256_ni_asm.S               | 22 +++--
 arch/x86/crypto/sha512-avx-asm.S              | 33 +++----
 arch/x86/crypto/sha512-avx2-asm.S             | 34 +++----
 arch/x86/crypto/sha512-ssse3-asm.S            | 36 ++++---
 arch/x86/crypto/sm3-avx-asm_64.S              | 18 ++--
 crypto/asymmetric_keys/verify_pefile.c        |  2 +-
 crypto/async_tx/async_pq.c                    | 11 +--
 crypto/async_tx/async_tx.c                    |  4 +-
 crypto/crypto_engine.c                        |  2 +-
 include/crypto/acompress.h                    |  2 +-
 include/crypto/des.h                          |  4 +-
 include/crypto/if_alg.h                       | 26 ++---
 include/crypto/internal/ecc.h                 |  8 +-
 include/crypto/internal/rsa.h                 |  2 +-
 include/crypto/kdf_sp800108.h                 | 39 ++++----
 scripts/kernel-doc                            | 49 +++++++++-
 32 files changed, 623 insertions(+), 312 deletions(-)

-- 
2.38.1