[v2,2/2] crypto: doc - Fix formatting of new crypto engine content
diff mbox series

Message ID 156150622886.22527.934327975584441429.stgit@taos
State Accepted
Delegated to: Herbert Xu
Headers show
Series
  • Clean up crypto documentation
Related show

Commit Message

Gary R Hook June 25, 2019, 11:43 p.m. UTC
Tidy up the formatting/grammar in crypto_engine.rst. Use bulleted lists
where appropriate.

Signed-off-by: Gary R Hook <gary.hook@amd.com>
---
 Documentation/crypto/crypto_engine.rst |  111 +++++++++++++++++++++-----------
 1 file changed, 73 insertions(+), 38 deletions(-)

Comments

Joe Perches June 26, 2019, 12:13 a.m. UTC | #1
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.

> 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.

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()
Gary R Hook June 26, 2019, 4:50 p.m. UTC | #2
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).

Patch
diff mbox series

diff --git a/Documentation/crypto/crypto_engine.rst b/Documentation/crypto/crypto_engine.rst
index 1d56221dfe35..236c674d6897 100644
--- a/Documentation/crypto/crypto_engine.rst
+++ b/Documentation/crypto/crypto_engine.rst
@@ -1,50 +1,85 @@ 
-=============
-CRYPTO ENGINE
+.. SPDX-License-Identifier: GPL-2.0
+Crypto Engine
 =============
 
 Overview
 --------
-The crypto engine API (CE), is a crypto queue manager.
+The crypto engine (CE) API is a crypto queue manager.
 
 Requirement
 -----------
-You have to put at start of your tfm_ctx the struct crypto_engine_ctx::
+You must put, at the start of your transform context your_tfm_ctx, the structure
+crypto_engine:
+
+::
 
-  struct your_tfm_ctx {
-        struct crypto_engine_ctx enginectx;
-        ...
-  };
+	struct your_tfm_ctx {
+		struct crypto_engine engine;
+		...
+	};
 
-Why: Since CE manage only crypto_async_request, it cannot know the underlying
-request_type and so have access only on the TFM.
-So using container_of for accessing __ctx is impossible.
-Furthermore, the crypto engine cannot know the "struct your_tfm_ctx",
-so it must assume that crypto_engine_ctx is at start of it.
+The crypto engine only manages asynchronous requests in the form of
+crypto_async_request. It cannot know the underlying request type and thus only
+has access to the transform structure. It is not possible to access the context
+using container_of. In addition, the engine knows nothing about your
+structure "``struct your_tfm_ctx``". The engine assumes (requires) the placement
+of the known member ``struct crypto_engine`` at the beginning.
 
 Order of operations
 -------------------
-You have to obtain a struct crypto_engine via crypto_engine_alloc_init().
-And start it via crypto_engine_start().
-
-Before transferring any request, you have to fill the enginectx.
-- prepare_request: (taking a function pointer) If you need to do some processing before doing the request
-- unprepare_request: (taking a function pointer) Undoing what's done in prepare_request
-- do_one_request: (taking a function pointer) Do encryption for current request
-
-Note: that those three functions get the crypto_async_request associated with the received request.
-So your need to get the original request via container_of(areq, struct yourrequesttype_request, base);
-
-When your driver receive a crypto_request, you have to transfer it to
-the cryptoengine via one of:
-- crypto_transfer_ablkcipher_request_to_engine()
-- 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 function is needed:
-- crypto_finalize_ablkcipher_request
-- crypto_finalize_aead_request
-- crypto_finalize_akcipher_request
-- crypto_finalize_hash_request
-- crypto_finalize_skcipher_request
+You are required to obtain a struct crypto_engine via ``crypto_engine_alloc_init()``.
+Start it via ``crypto_engine_start()``. When finished with your work, shut down the
+engine using ``crypto_engine_stop()`` and destroy the engine with
+``crypto_engine_exit()``.
+
+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.
+
+Note that these functions access the crypto_async_request structure
+associated with the received request. You are able to retrieve the original
+request by using:
+
+::
+
+	container_of(areq, struct yourrequesttype_request, base);
+
+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()
+
+* 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()