Signed-off-by: Dmitry Safonov <dima@xxxxxxxxxx> --- Documentation/crypto/crypto_pool.rst | 33 ++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 Documentation/crypto/crypto_pool.rst 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 +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()``. -- 2.39.0
