Re: [PATCH v2 2/2] crypto: doc - Fix formatting of new crypto engine content

[Gary R Hook]

On 6/25/19 7:13 PM, Joe Perches wrote:
> On Tue, 2019-06-25 at 23:43 +0000, Hook, Gary wrote:
>> Tidy up the formatting/grammar in crypto_engine.rst. Use bulleted lists
>> where appropriate.
> 
> Hi again Gary.

Howdy!

> 
>> diff --git a/Documentation/crypto/crypto_engine.rst b/Documentation/crypto/crypto_engine.rst
> []
>> +Before transferring any request, you have to fill the context enginectx by
>> +providing functions for the following:
>> +
>> +* ``prepare_crypt_hardware``: Called once before any prepare functions are
>> +  called.
>> +
>> +* ``unprepare_crypt_hardware``: Called once after all unprepare functions have
>> +  been called.
>> +
>> +* ``prepare_cipher_request``/``prepare_hash_request``: Called before each
>> +  corresponding request is performed. If some processing or other preparatory
>> +  work is required, do it here.
>> +
>> +* ``unprepare_cipher_request``/``unprepare_hash_request``: Called after each
>> +  request is handled. Clean up / undo what was done in the prepare function.
>> +
>> +* ``cipher_one_request``/``hash_one_request``: Handle the current request by
>> +  performing the operation.
> 
> I again suggest not using ``<func>`` but instead use <func>()
> and remove unnecessary blank lines.

with all due respect, those aren't functions, they're function pointers 
(as structure members). Therefore, if anything, they should be notated 
as (*func)(). But I tried that (with the new patches), and they weren't 
detected and emboldened (that's not a word, I know) in the html.

So I left them as-is.

I don't pretend to be a guru on this markup, but if there's a way to 
make symbol names fixed-width and bold, I'll gladly do it. But I 
disagree on turning these into functions, because that's not what they are.


> i.e.:
> 
> * prepare_crypt_hardware(): Called once before any prepare functions are
>    called.
> * unprepare_crypt_hardware():  Called once after all unprepare functions
>    have been called.
> * prepare_cipher_request()/prepare_hash_request(): Called before each
>    corresponding request is performed. If some processing or other preparatory
>    work is required, do it here.
> * unprepare_cipher_request()/unprepare_hash_request(): Called after each
>    request is handled. Clean up / undo what was done in the prepare function.
> * cipher_one_request()/hash_one_request(): Handle the current request by
>    performing the operation.
> 
> []
>> +When your driver receives a crypto_request, you must to transfer it to
>> +the crypto engine via one of:
>> +
>> +* crypto_transfer_ablkcipher_request_to_engine()
> 
> And removing the unnecessary blank lines below
> 
>> +
>> +* crypto_transfer_aead_request_to_engine()
>> +
>> +* crypto_transfer_akcipher_request_to_engine()
>> +
>> +* crypto_transfer_hash_request_to_engine()
>> +
>> +* crypto_transfer_skcipher_request_to_engine()
>> +
>> +At the end of the request process, a call to one of the following functions is needed:
>> +
>> +* crypto_finalize_ablkcipher_request()
>> +
>> +* crypto_finalize_aead_request()
>> +
>> +* crypto_finalize_akcipher_request()
>> +
>> +* crypto_finalize_hash_request()
>> +
>> +* crypto_finalize_skcipher_request()
> 
> 

The lines between the bulleted items will go, yes. Not the ones around 
the leading text of each list (which are necessary to delineate the lists).