Subject: Re: [PATCH] crypto: clear htmldocs build warnings for crypto/hash
To: Herbert Xu <herbert@gondor.apana.org.au>
Cc: "Tobin C. Harding" <me@tobin.cc>,
        "David S. Miller" <davem@davemloft.net>,
        Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>,
        linux-kernel@vger.kernel.org,
        "linux-crypto@vger.kernel.org" <linux-crypto@vger.kernel.org>
From: Kamil Konieczny <k.konieczny@partner.samsung.com>
Message-id: <2b4fa5b0-dadb-47fe-2bbd-b051ad343bc4@partner.samsung.com>
Date: Mon, 08 Jan 2018 17:43:18 +0100
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101
        Thunderbird/52.5.0
MIME-version: 1.0
In-reply-to: <20180108155619.GA5350@gondor.apana.org.au>
Content-type: text/plain; charset="utf-8"
Content-language: en-US
Content-transfer-encoding: 7bit
CMS-TYPE: 201P
References: <CGME20180106230157epcas2p2a3dc70ac85fbd7861ddf916fde5dd2be@epcas2p2.samsung.com>
        <1515279703-14070-1-git-send-email-me@tobin.cc>
        <724b85c9-f3df-15b2-7aa2-4089f232c155@partner.samsung.com>
        <20180108155619.GA5350@gondor.apana.org.au>
Sender: linux-kernel-owner@vger.kernel.org


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