[v2,5/5] crypto/Documentation: Add crypto_pool kernel API
Commit Message
Signed-off-by: Dmitry Safonov <dima@arista.com>
---
Documentation/crypto/crypto_pool.rst | 33 ++++++++++++++++++++++++++++
1 file changed, 33 insertions(+)
create mode 100644 Documentation/crypto/crypto_pool.rst
Comments
Hi Dmitry,
Thank you for the patch! Perhaps something to improve:
[auto build test WARNING on 69b41ac87e4a664de78a395ff97166f0b2943210]
url: https://github.com/intel-lab-lkp/linux/commits/Dmitry-Safonov/crypto-Introduce-crypto_pool/20230104-024749
base: 69b41ac87e4a664de78a395ff97166f0b2943210
patch link: https://lore.kernel.org/r/20230103184257.118069-6-dima%40arista.com
patch subject: [PATCH v2 5/5] crypto/Documentation: Add crypto_pool kernel API
reproduce:
# https://github.com/intel-lab-lkp/linux/commit/8f97b82187da5291dc1618377c97338118eb36e1
git remote add linux-review https://github.com/intel-lab-lkp/linux
git fetch --no-tags linux-review Dmitry-Safonov/crypto-Introduce-crypto_pool/20230104-024749
git checkout 8f97b82187da5291dc1618377c97338118eb36e1
make menuconfig
# enable CONFIG_COMPILE_TEST, CONFIG_WARN_MISSING_DOCUMENTS, CONFIG_WARN_ABI_ERRORS
make htmldocs
If you fix the issue, kindly add following tag where applicable
| Reported-by: kernel test robot <lkp@intel.com>
All warnings (new ones prefixed by >>):
>> Documentation/crypto/crypto_pool.rst:4: WARNING: Title underline too short.
>> Documentation/crypto/crypto_pool.rst: WARNING: document isn't included in any toctree
vim +4 Documentation/crypto/crypto_pool.rst
2
3 Per-CPU pool of crypto requests
> 4 =============
5
Some extra nits here since you need to respin for the build warning
(include the document in some index / toc tree and adjust the length
of the underscores to match the line length).
On Tue, 3 Jan 2023 18:42:57 +0000 Dmitry Safonov wrote:
> diff --git a/Documentation/crypto/crypto_pool.rst b/Documentation/crypto/crypto_pool.rst
> new file mode 100644
> index 000000000000..4b8443171421
> --- /dev/null
> +++ b/Documentation/crypto/crypto_pool.rst
> @@ -0,0 +1,33 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Per-CPU pool of crypto requests
> +=============
> +
> +Overview
> +--------
> +The crypto pool API manages pre-allocated per-CPU pool of crypto requests,
> +providing ability to use async crypto requests on fast paths, potentially
.. you *don't* enable async crypto in this series, right?
> +on atomic contexts. The allocation and initialization of the requests should
s/on/in/ atomic contexts
> +be done before their usage as it's slow-path and may sleep.
> +
> +Order of operations
> +-------------------
> +You are required to allocate a new pool prior using it and manage its lifetime.
The use of second person is quite uncommon for documentation, but if
you prefer so be it..
> +You can allocate a per-CPU pool of ahash requests by ``crypto_pool_alloc_ahash()``.
You don't need to use the backticks around function names and struct
names. Our doc rendering system recognizes them automatically.
`make htmldocs` to see for yourself.
On 1/7/23 02:06, Jakub Kicinski wrote:
> Some extra nits here since you need to respin for the build warning
> (include the document in some index / toc tree and adjust the length
> of the underscores to match the line length).
Thanks again, will correct according to your review notes,
>
> On Tue, 3 Jan 2023 18:42:57 +0000 Dmitry Safonov wrote:
>> diff --git a/Documentation/crypto/crypto_pool.rst b/Documentation/crypto/crypto_pool.rst
>> new file mode 100644
>> index 000000000000..4b8443171421
>> --- /dev/null
>> +++ b/Documentation/crypto/crypto_pool.rst
>> @@ -0,0 +1,33 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +Per-CPU pool of crypto requests
>> +=============
>> +
>> +Overview
>> +--------
>> +The crypto pool API manages pre-allocated per-CPU pool of crypto requests,
>> +providing ability to use async crypto requests on fast paths, potentially
>
> .. you *don't* enable async crypto in this series, right?
>
>> +on atomic contexts. The allocation and initialization of the requests should
>
> s/on/in/ atomic contexts
>
>> +be done before their usage as it's slow-path and may sleep.
>> +
>> +Order of operations
>> +-------------------
>> +You are required to allocate a new pool prior using it and manage its lifetime.
>
> The use of second person is quite uncommon for documentation, but if
> you prefer so be it..
I used Documentation/crypto/crypto_engine.rst as an example :-)
[where "example" was `cp crypto_{engine,pool}.rst && vim crypto_pool.rst`]
>
>> +You can allocate a per-CPU pool of ahash requests by ``crypto_pool_alloc_ahash()``.
>
> You don't need to use the backticks around function names and struct
> names. Our doc rendering system recognizes them automatically.
>
> `make htmldocs` to see for yourself.
Thanks,
Dmitry
new file mode 100644
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Per-CPU pool of crypto requests
+=============
+
+Overview
+--------
+The crypto pool API manages pre-allocated per-CPU pool of crypto requests,
+providing ability to use async crypto requests on fast paths, potentially
+on atomic contexts. The allocation and initialization of the requests should
+be done before their usage as it's slow-path and may sleep.
+
+Order of operations
+-------------------
+You are required to allocate a new pool prior using it and manage its lifetime.
+You can allocate a per-CPU pool of ahash requests by ``crypto_pool_alloc_ahash()``.
+It will give you a pool id that you can use further on fast-path for hashing.
+You can increase the reference counter for an allocated pool via
+``crypto_pool_add()``. Decrease the reference counter by ``crypto_pool_release()``.
+When the refcounter hits zero, the pool is scheduled for destruction and you
+can't use the corresponding crypto pool id anymore.
+Note that ``crypto_pool_add()`` and ``crypto_pool_release()`` must be called
+only for an already existing pool and can be called in atomic contexts.
+
+``crypto_pool_get()`` disables bh and returns you back ``struct crypto_pool *``,
+which is a generic type for different crypto requests and has ``scratch`` area
+that can be used as a temporary buffer for your operation.
+
+``crypto_pool_put()`` enables bh back once you've done with your crypto
+operation.
+
+If you need to pre-allocate a bigger per-CPU ``scratch`` area for you requests,
+you can use ``crypto_pool_reserve_scratch()``.