Re: [PATCH v2] crypto: doc - clarify hash callbacks state machine

[Horia Geantă]

On 3/20/2018 10:50 AM, Kamil Konieczny wrote:
> On 20.03.2018 08:56, Horia Geantă wrote:
>> Add a note that it is perfectly legal to "abandon" a request object:
>> - call .init() and then (as many times) .update()
>> - _not_ call any of .final(), .finup() or .export() at any point in
>>   future
>>
>> Link: https://lkml.kernel.org/r/20180222114741.ga27...@xxxxxxxxxxxxxxxxxxx
>> Signed-off-by: Horia Geantă <horia.geanta@xxxxxxx>
>> ---
>>  Documentation/crypto/devel-algos.rst | 8 ++++++++
>>  1 file changed, 8 insertions(+)
>>
>> diff --git a/Documentation/crypto/devel-algos.rst b/Documentation/crypto/devel-algos.rst
>> index 66f50d32dcec..c45c6f400dbd 100644
>> --- a/Documentation/crypto/devel-algos.rst
>> +++ b/Documentation/crypto/devel-algos.rst
>> @@ -236,6 +236,14 @@ when used from another part of the kernel.
>>                                 |
>>                                 '---------------> HASH2
>>  
>> +Note that it is perfectly legal to "abandon" a request object:
>> +- call .init() and then (as many times) .update()
>> +- _not_ call any of .final(), .finup() or .export() at any point in future
>> +
>> +In other words implementations should mind the resource allocation and clean-up.
>> +No resources related to request objects should remain allocated after a call
> -- ^^^^^^^^^^^^
>> +to .init() or .update(), since there might be no chance to free them.
> 
> is it for crypto api  users or for drivers ?
> 
For drivers / providers (below crypto API).

> the creator of request context is responsible for alloc and destroy,
> so why there are no chance of free ?
> 
Hash request object (including request context) is allocated by the user /
client by means of ahash_request_alloc(), and later on freed using
ahash_request_free().
I don't see a problem with this.

However, besides the memory allocated for the request context, other resources
(related to the request) might be needed by the driver.
I provided an example of needing to DMA map a buffer (to load/store HW state
from/to crypto engine), and I am not happy with either solutions:
-DMA map & unmap after each .update()
-Herbert's proposal to use a convoluted DMA mapping scheme

Another example: dynamic memory allocation might be needed beyond what's
available in request context, i.e. driver might not have apriori all the
information needed to inform the tfm about required memory using
crypto_ahash_set_reqsize().

This happens due to the semantics of the crypto API, which allows the user to
initialize a request object and drop it without getting a result (final or
partial hash).
I don't see what below use case is good for, maybe just for benchmarking:
req = ahash_request_alloc();
[...]
crypto_ahash_init(req);
crypto_ahash_update(req);
ahash_request_free(req);

Horia