tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
crypto: doc - Fix formatting of new crypto engine content
Tidy up the formatting/grammar in crypto_engine.rst. Use bulleted lists
where appropriate.
Signed-off-by: Gary R Hook <gary.hook@amd.com>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
authored by
Hook, Gary
and committed by
Herbert Xu
ae400be9
5a35316d
+69
-34
+69
-34
Documentation/crypto/crypto_engine.rst
+69
-34
Documentation/crypto/crypto_engine.rst
···
1
-
=============
2
-
CRYPTO ENGINE
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
Crypto Engine
3
3
=============
4
4
5
5
Overview
6
6
--------
7
-
The crypto engine API (CE), is a crypto queue manager.
7
+
The crypto engine (CE) API is a crypto queue manager.
8
8
9
9
Requirement
10
10
-----------
11
-
You have to put at start of your tfm_ctx the struct crypto_engine_ctx::
11
+
You must put, at the start of your transform context your_tfm_ctx, the structure
12
+
crypto_engine:
12
13
13
-
struct your_tfm_ctx {
14
-
struct crypto_engine_ctx enginectx;
15
-
...
16
-
};
14
+
::
17
15
18
-
Why: Since CE manage only crypto_async_request, it cannot know the underlying
19
-
request_type and so have access only on the TFM.
20
-
So using container_of for accessing __ctx is impossible.
21
-
Furthermore, the crypto engine cannot know the "struct your_tfm_ctx",
22
-
so it must assume that crypto_engine_ctx is at start of it.
16
+
struct your_tfm_ctx {
17
+
struct crypto_engine engine;
18
+
...
19
+
};
20
+
21
+
The crypto engine only manages asynchronous requests in the form of
22
+
crypto_async_request. It cannot know the underlying request type and thus only
23
+
has access to the transform structure. It is not possible to access the context
24
+
using container_of. In addition, the engine knows nothing about your
25
+
structure "``struct your_tfm_ctx``". The engine assumes (requires) the placement
26
+
of the known member ``struct crypto_engine`` at the beginning.
23
27
24
28
Order of operations
25
29
-------------------
26
-
You have to obtain a struct crypto_engine via crypto_engine_alloc_init().
27
-
And start it via crypto_engine_start().
30
+
You are required to obtain a struct crypto_engine via ``crypto_engine_alloc_init()``.
31
+
Start it via ``crypto_engine_start()``. When finished with your work, shut down the
32
+
engine using ``crypto_engine_stop()`` and destroy the engine with
33
+
``crypto_engine_exit()``.
28
34
29
-
Before transferring any request, you have to fill the enginectx.
30
-
- prepare_request: (taking a function pointer) If you need to do some processing before doing the request
31
-
- unprepare_request: (taking a function pointer) Undoing what's done in prepare_request
32
-
- do_one_request: (taking a function pointer) Do encryption for current request
35
+
Before transferring any request, you have to fill the context enginectx by
36
+
providing functions for the following:
33
37
34
-
Note: that those three functions get the crypto_async_request associated with the received request.
35
-
So your need to get the original request via container_of(areq, struct yourrequesttype_request, base);
38
+
* ``prepare_crypt_hardware``: Called once before any prepare functions are
39
+
called.
36
40
37
-
When your driver receive a crypto_request, you have to transfer it to
38
-
the cryptoengine via one of:
39
-
- crypto_transfer_ablkcipher_request_to_engine()
40
-
- crypto_transfer_aead_request_to_engine()
41
-
- crypto_transfer_akcipher_request_to_engine()
42
-
- crypto_transfer_hash_request_to_engine()
43
-
- crypto_transfer_skcipher_request_to_engine()
41
+
* ``unprepare_crypt_hardware``: Called once after all unprepare functions have
42
+
been called.
44
43
45
-
At the end of the request process, a call to one of the following function is needed:
46
-
- crypto_finalize_ablkcipher_request
47
-
- crypto_finalize_aead_request
48
-
- crypto_finalize_akcipher_request
49
-
- crypto_finalize_hash_request
50
-
- crypto_finalize_skcipher_request
44
+
* ``prepare_cipher_request``/``prepare_hash_request``: Called before each
45
+
corresponding request is performed. If some processing or other preparatory
46
+
work is required, do it here.
47
+
48
+
* ``unprepare_cipher_request``/``unprepare_hash_request``: Called after each
49
+
request is handled. Clean up / undo what was done in the prepare function.
50
+
51
+
* ``cipher_one_request``/``hash_one_request``: Handle the current request by
52
+
performing the operation.
53
+
54
+
Note that these functions access the crypto_async_request structure
55
+
associated with the received request. You are able to retrieve the original
56
+
request by using:
57
+
58
+
::
59
+
60
+
container_of(areq, struct yourrequesttype_request, base);
61
+
62
+
When your driver receives a crypto_request, you must to transfer it to
63
+
the crypto engine via one of:
64
+
65
+
* crypto_transfer_ablkcipher_request_to_engine()
66
+
67
+
* crypto_transfer_aead_request_to_engine()
68
+
69
+
* crypto_transfer_akcipher_request_to_engine()
70
+
71
+
* crypto_transfer_hash_request_to_engine()
72
+
73
+
* crypto_transfer_skcipher_request_to_engine()
74
+
75
+
At the end of the request process, a call to one of the following functions is needed:
76
+
77
+
* crypto_finalize_ablkcipher_request()
78
+
79
+
* crypto_finalize_aead_request()
80
+
81
+
* crypto_finalize_akcipher_request()
82
+
83
+
* crypto_finalize_hash_request()
84
+
85
+
* crypto_finalize_skcipher_request()