diff mbox series

[v2,6/8] crypto: x86/ghash - add kernel-doc comments to assembly

Message ID 20221219185555.433233-7-elliott@hpe.com
State New
Headers
Series crypto: kernel-doc for assembly language |

Commit Message

Elliott, Robert (Servers) Dec. 19, 2022, 6:55 p.m. UTC 
  Add kernel-doc comments for assembly language functions exported to
C glue code.

Signed-off-by: Robert Elliott <elliott@hpe.com>
---
 arch/x86/crypto/ghash-clmulni-intel_asm.S | 27 +++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

Comments

Eric Biggers Dec. 20, 2022, 6:01 a.m. UTC | #1 
On Mon, Dec 19, 2022 at 12:55:53PM -0600, Robert Elliott wrote:
> +/**
> + * clmul_ghash_mul - Calculate GHASH final multiplication using x86 PCLMULQDQ instructions

Well, it does one multiplication.  It's not necessarily the final one.

> + * @dst:	address of hash value to update (%rdi)
> + * @shash:	address of hash context (%rsi)

This terminology is confusing.  I would call these the accumulator and key,
respectively.

> +/**
> + * clmul_ghash_update - Calculate GHASH using x86 PCLMULQDQ instructions
> + * @dst:	address of hash value to update (%rdi)
> + * @src:	address of data to hash (%rsi)
> + * @srclen:	number of bytes in data buffer (%rdx);
> + *		function does nothing and returns if below 16
> + * @shash:	address of hash context (%rcx)
> + *
> + * This supports 64-bit CPUs.
> + *
> + * Return:	none (but @dst is updated)
> + * Prototype:	asmlinkage clmul_ghash_update(char *dst, const char *src,
> + *					      unsigned int srclen, const u128 *shash);

"function does nothing and returns if below 16" =>
"function processes round_down(srclen, 16) bytes".

- Eric
diff mbox series

Patch

diff --git a/arch/x86/crypto/ghash-clmulni-intel_asm.S b/arch/x86/crypto/ghash-clmulni-intel_asm.S
index 2bf871899920..09cf9271b83a 100644
--- a/arch/x86/crypto/ghash-clmulni-intel_asm.S
+++ b/arch/x86/crypto/ghash-clmulni-intel_asm.S
@@ -88,7 +88,16 @@  SYM_FUNC_START_LOCAL(__clmul_gf128mul_ble)
 	RET
 SYM_FUNC_END(__clmul_gf128mul_ble)
 
-/* void clmul_ghash_mul(char *dst, const u128 *shash) */
+/**
+ * clmul_ghash_mul - Calculate GHASH final multiplication using x86 PCLMULQDQ instructions
+ * @dst:	address of hash value to update (%rdi)
+ * @shash:	address of hash context (%rsi)
+ *
+ * This supports 64-bit CPUs.
+ *
+ * Return:	none (but @dst is updated)
+ * Prototype:	asmlinkage void clmul_ghash_mul(char *dst, const u128 *shash)
+ */
 SYM_FUNC_START(clmul_ghash_mul)
 	FRAME_BEGIN
 	movups (%rdi), DATA
@@ -102,9 +111,19 @@  SYM_FUNC_START(clmul_ghash_mul)
 	RET
 SYM_FUNC_END(clmul_ghash_mul)
 
-/*
- * void clmul_ghash_update(char *dst, const char *src, unsigned int srclen,
- *			   const u128 *shash);
+/**
+ * clmul_ghash_update - Calculate GHASH using x86 PCLMULQDQ instructions
+ * @dst:	address of hash value to update (%rdi)
+ * @src:	address of data to hash (%rsi)
+ * @srclen:	number of bytes in data buffer (%rdx);
+ *		function does nothing and returns if below 16
+ * @shash:	address of hash context (%rcx)
+ *
+ * This supports 64-bit CPUs.
+ *
+ * Return:	none (but @dst is updated)
+ * Prototype:	asmlinkage clmul_ghash_update(char *dst, const char *src,
+ *					      unsigned int srclen, const u128 *shash);
  */
 SYM_FUNC_START(clmul_ghash_update)
 	FRAME_BEGIN