[PATCH] crypto: clear htmldocs build warnings for crypto/hash

[PATCH] crypto: clear htmldocs build warnings for crypto/hash

[Tobin C. Harding]

SPHINX build emits multiple warnings of kind:

	warning: duplicate section name 'Note'

(when building kernel via make target 'htmldocs')

This is caused by repeated use of comments of form:

	* Note: soau soaeusoa uoe

We can change the format without loss of clarity and clear the build
warnings.

Add '**[mandatory]**' or '**[optional]**' as kernel-doc field element
description prefix

This renders in HTML as (prefixes in bold)

final
    [mandatory] Retrieve result from the driver. This function finalizes the
    transformation and retrieves the resulting hash from the driver and
    pushes it back to upper layers. No data processing happens at this
    point unless hardware requires it to finish the transformation (then
    the data buffered by the device driver is processed).

Signed-off-by: Tobin C. Harding <me@tobin.cc>
---

This patch begs the question why the other members of struct ahash_alg
are not marked? Some are marked 'optional' some 'mandatory'. It would
seem that if the marking were necessary for some members it is necessary
for all to eliminate ambiguity?

thanks

 include/crypto/hash.h | 12 ++++--------
 1 file changed, 4 insertions(+), 8 deletions(-)

diff --git a/include/crypto/hash.h b/include/crypto/hash.h
index 0ed31fd80242..d1cd75faff40 100644
--- a/include/crypto/hash.h
+++ b/include/crypto/hash.h
@@ -71,12 +71,11 @@ struct ahash_request {
 
 /**
  * struct ahash_alg - asynchronous message digest definition
- * @init: Initialize the transformation context. Intended only to initialize the
+ * @init: **[mandatory]** Initialize the transformation context. Intended only to initialize the
  *	  state of the HASH transformation at the beginning. This shall fill in
  *	  the internal structures used during the entire duration of the whole
  *	  transformation. No data processing happens at this point.
- *	  Note: mandatory.
- * @update: Push a chunk of data into the driver for transformation. This
+ * @update: **[mandatory]** Push a chunk of data into the driver for transformation. This
  *	   function actually pushes blocks of data from upper layers into the
  *	   driver, which then passes those to the hardware as seen fit. This
  *	   function must not finalize the HASH transformation by calculating the
@@ -85,20 +84,17 @@ struct ahash_request {
  *	   context, as this function may be called in parallel with the same
  *	   transformation object. Data processing can happen synchronously
  *	   [SHASH] or asynchronously [AHASH] at this point.
- *	   Note: mandatory.
- * @final: Retrieve result from the driver. This function finalizes the
+ * @final: **[mandatory]** Retrieve result from the driver. This function finalizes the
  *	   transformation and retrieves the resulting hash from the driver and
  *	   pushes it back to upper layers. No data processing happens at this
  *	   point unless hardware requires it to finish the transformation
  *	   (then the data buffered by the device driver is processed).
- *	   Note: mandatory.
- * @finup: Combination of @update and @final. This function is effectively a
+ * @finup: **[optional]** Combination of @update and @final. This function is effectively a
  *	   combination of @update and @final calls issued in sequence. As some
  *	   hardware cannot do @update and @final separately, this callback was
  *	   added to allow such hardware to be used at least by IPsec. Data
  *	   processing can happen synchronously [SHASH] or asynchronously [AHASH]
  *	   at this point.
- *	   Note: optional.
  * @digest: Combination of @init and @update and @final. This function
  *	    effectively behaves as the entire chain of operations, @init,
  *	    @update and @final issued in sequence. Just like @finup, this was
-- 
2.7.4

Re: [PATCH] crypto: clear htmldocs build warnings for crypto/hash

[Kamil Konieczny]

On 07.01.2018 00:01, Tobin C. Harding wrote:
> SPHINX build emits multiple warnings of kind:
> 
> 	warning: duplicate section name 'Note'
> 
> (when building kernel via make target 'htmldocs')
> 
> This is caused by repeated use of comments of form:
> 
> 	* Note: soau soaeusoa uoe
> 
> We can change the format without loss of clarity and clear the build
> warnings.
> 
> Add '**[mandatory]**' or '**[optional]**' as kernel-doc field element
> description prefix
> 
> This renders in HTML as (prefixes in bold)
> 
> final
>     [mandatory] Retrieve result from the driver. This function finalizes the
>     transformation and retrieves the resulting hash from the driver and
>     pushes it back to upper layers. No data processing happens at this
>     point unless hardware requires it to finish the transformation (then
>     the data buffered by the device driver is processed).
> 
> Signed-off-by: Tobin C. Harding <me@tobin.cc>
> ---
> 
> This patch begs the question why the other members of struct ahash_alg
> are not marked? Some are marked 'optional' some 'mandatory'. It would
> seem that if the marking were necessary for some members it is necessary
> for all to eliminate ambiguity?
> 
> thanks

import, export are optional
digest is mandatory

see declaration for function
static int crypto_ahash_init_tfm(struct crypto_tfm *tfm)

in crypto/hash.c

setkey is not allowed in hash, but mandatory for HMAC
(as you can find out from description)

>  include/crypto/hash.h | 12 ++++--------
>  1 file changed, 4 insertions(+), 8 deletions(-)
> 
> diff --git a/include/crypto/hash.h b/include/crypto/hash.h
> index 0ed31fd80242..d1cd75faff40 100644
> --- a/include/crypto/hash.h
> +++ b/include/crypto/hash.h
> @@ -71,12 +71,11 @@ struct ahash_request {
>  
>  /**
>   * struct ahash_alg - asynchronous message digest definition
> - * @init: Initialize the transformation context. Intended only to initialize the
> + * @init: **[mandatory]** Initialize the transformation context. Intended only to initialize the
>   *	  state of the HASH transformation at the beginning. This shall fill in
>   *	  the internal structures used during the entire duration of the whole
>   *	  transformation. No data processing happens at this point.
> - *	  Note: mandatory.
> - * @update: Push a chunk of data into the driver for transformation. This
> + * @update: **[mandatory]** Push a chunk of data into the driver for transformation. This
>   *	   function actually pushes blocks of data from upper layers into the
>   *	   driver, which then passes those to the hardware as seen fit. This
>   *	   function must not finalize the HASH transformation by calculating the
> @@ -85,20 +84,17 @@ struct ahash_request {
>   *	   context, as this function may be called in parallel with the same
>   *	   transformation object. Data processing can happen synchronously
>   *	   [SHASH] or asynchronously [AHASH] at this point.
> - *	   Note: mandatory.
> - * @final: Retrieve result from the driver. This function finalizes the
> + * @final: **[mandatory]** Retrieve result from the driver. This function finalizes the
>   *	   transformation and retrieves the resulting hash from the driver and
>   *	   pushes it back to upper layers. No data processing happens at this
>   *	   point unless hardware requires it to finish the transformation
>   *	   (then the data buffered by the device driver is processed).
> - *	   Note: mandatory.
> - * @finup: Combination of @update and @final. This function is effectively a
> + * @finup: **[optional]** Combination of @update and @final. This function is effectively a
>   *	   combination of @update and @final calls issued in sequence. As some
>   *	   hardware cannot do @update and @final separately, this callback was
>   *	   added to allow such hardware to be used at least by IPsec. Data
>   *	   processing can happen synchronously [SHASH] or asynchronously [AHASH]
>   *	   at this point.
> - *	   Note: optional.
>   * @digest: Combination of @init and @update and @final. This function
>   *	    effectively behaves as the entire chain of operations, @init,
>   *	    @update and @final issued in sequence. Just like @finup, this was
> 

-- 
Best regards,
Kamil Konieczny
Samsung R&D Institute Poland

Re: [PATCH] crypto: clear htmldocs build warnings for crypto/hash

[Herbert Xu]

On Mon, Jan 08, 2018 at 02:11:21PM +0100, Kamil Konieczny wrote:
> 
> 
> On 07.01.2018 00:01, Tobin C. Harding wrote:
> > SPHINX build emits multiple warnings of kind:
> > 
> > 	warning: duplicate section name 'Note'
> > 
> > (when building kernel via make target 'htmldocs')
> > 
> > This is caused by repeated use of comments of form:
> > 
> > 	* Note: soau soaeusoa uoe
> > 
> > We can change the format without loss of clarity and clear the build
> > warnings.
> > 
> > Add '**[mandatory]**' or '**[optional]**' as kernel-doc field element
> > description prefix
> > 
> > This renders in HTML as (prefixes in bold)
> > 
> > final
> >     [mandatory] Retrieve result from the driver. This function finalizes the
> >     transformation and retrieves the resulting hash from the driver and
> >     pushes it back to upper layers. No data processing happens at this
> >     point unless hardware requires it to finish the transformation (then
> >     the data buffered by the device driver is processed).
> > 
> > Signed-off-by: Tobin C. Harding <me@tobin.cc>
> > ---
> > 
> > This patch begs the question why the other members of struct ahash_alg
> > are not marked? Some are marked 'optional' some 'mandatory'. It would
> > seem that if the marking were necessary for some members it is necessary
> > for all to eliminate ambiguity?
> > 
> > thanks
> 
> import, export are optional

No import/export must be implemented for all hashes.

Cheers,
-- 
Email: Herbert Xu <herbert@gondor.apana.org.au>
Home Page: http://gondor.apana.org.au/~herbert/
PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt

Re: [PATCH] crypto: clear htmldocs build warnings for crypto/hash

[Kamil Konieczny]

On 08.01.2018 16:56, Herbert Xu wrote:
> On Mon, Jan 08, 2018 at 02:11:21PM +0100, Kamil Konieczny wrote:
>>
>>
>> On 07.01.2018 00:01, Tobin C. Harding wrote:
>>> SPHINX build emits multiple warnings of kind:
>>>
>>> 	warning: duplicate section name 'Note'
>>>
>>> (when building kernel via make target 'htmldocs')
>>>
>>> This is caused by repeated use of comments of form:
>>>
>>> 	* Note: soau soaeusoa uoe
>>>
>>> We can change the format without loss of clarity and clear the build
>>> warnings.
>>>
>>> Add '**[mandatory]**' or '**[optional]**' as kernel-doc field element
>>> description prefix
>>>
>>> This renders in HTML as (prefixes in bold)
>>>
>>> final
>>>     [mandatory] Retrieve result from the driver. This function finalizes the
>>>     transformation and retrieves the resulting hash from the driver and
>>>     pushes it back to upper layers. No data processing happens at this
>>>     point unless hardware requires it to finish the transformation (then
>>>     the data buffered by the device driver is processed).
>>>
>>> Signed-off-by: Tobin C. Harding <me@tobin.cc>
>>> ---
>>>
>>> This patch begs the question why the other members of struct ahash_alg
>>> are not marked? Some are marked 'optional' some 'mandatory'. It would
>>> seem that if the marking were necessary for some members it is necessary
>>> for all to eliminate ambiguity?
>>>
>>> thanks
>>
>> import, export are optional
> 
> No import/export must be implemented for all hashes.

Is it mandatory for both async hash and shash ?

in crypto/ahash.c in function

static int crypto_ahash_init_tfm(struct crypto_tfm *tfm)

there is:

	hash->export = ahash_no_export;
	hash->import = ahash_no_import;

and later in the same function:

	if (alg->export)
		hash->export = alg->export;
	if (alg->import)
		hash->import = alg->import;

-- 
Best regards,
Kamil Konieczny
Samsung R&D Institute Poland

Re: [PATCH] crypto: clear htmldocs build warnings for crypto/hash

[Herbert Xu]

On Mon, Jan 08, 2018 at 05:43:18PM +0100, Kamil Konieczny wrote:

> Is it mandatory for both async hash and shash ?
> 
> in crypto/ahash.c in function
> 
> static int crypto_ahash_init_tfm(struct crypto_tfm *tfm)
> 
> there is:
> 
> 	hash->export = ahash_no_export;
> 	hash->import = ahash_no_import;
> 
> and later in the same function:
> 
> 	if (alg->export)
> 		hash->export = alg->export;
> 	if (alg->import)
> 		hash->import = alg->import;

That's just a leftover from the old days before we started requiring
them.  These should be removed so that the registration fails if
they're not provided.

The requirement has been in place for a while now and we have been
failing any algorithms with a zero statesize which is only used by
import/export.

Thanks,
-- 
Email: Herbert Xu <herbert@gondor.apana.org.au>
Home Page: http://gondor.apana.org.au/~herbert/
PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt

Re: [PATCH] crypto: clear htmldocs build warnings for crypto/hash

[Herbert Xu]

On Sun, Jan 07, 2018 at 10:01:43AM +1100, Tobin C. Harding wrote:
> SPHINX build emits multiple warnings of kind:
> 
> 	warning: duplicate section name 'Note'
> 
> (when building kernel via make target 'htmldocs')
> 
> This is caused by repeated use of comments of form:
> 
> 	* Note: soau soaeusoa uoe
> 
> We can change the format without loss of clarity and clear the build
> warnings.
> 
> Add '**[mandatory]**' or '**[optional]**' as kernel-doc field element
> description prefix
> 
> This renders in HTML as (prefixes in bold)
> 
> final
>     [mandatory] Retrieve result from the driver. This function finalizes the
>     transformation and retrieves the resulting hash from the driver and
>     pushes it back to upper layers. No data processing happens at this
>     point unless hardware requires it to finish the transformation (then
>     the data buffered by the device driver is processed).
> 
> Signed-off-by: Tobin C. Harding <me@tobin.cc>

Patch applied.  Thanks.
-- 
Email: Herbert Xu <herbert@gondor.apana.org.au>
Home Page: http://gondor.apana.org.au/~herbert/
PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt