[PATCH v3 4/4] crypto/Documentation: Add crypto_pool kernel API
From: Dmitry Safonov <hidden>
Date: 2023-01-16 20:15:42
Also in:
linux-crypto, lkml
Subsystem:
crypto api, documentation, the rest · Maintainers:
Herbert Xu, "David S. Miller", Jonathan Corbet, Linus Torvalds
Signed-off-by: Dmitry Safonov <redacted> --- Documentation/crypto/crypto_pool.rst | 36 ++++++++++++++++++++++++++++ Documentation/crypto/index.rst | 1 + 2 files changed, 37 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..84abd1f2ee80
--- /dev/null
+++ b/Documentation/crypto/crypto_pool.rst@@ -0,0 +1,36 @@ +.. 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 crypto requests on fast paths, potentially in 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_get(). 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_get() and crypto_pool_release() must be called +only for an already existing pool and can be called in atomic contexts. + +crypto_pool_start() 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_end() enables bh back once you've done with your crypto +operation. + +.. kernel-doc:: include/crypto/pool.h + :identifiers: + +.. kernel-doc:: crypto/crypto_pool.c + :identifiers:
diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst
index 21338fa92642..3eaf4e964e5b 100644
--- a/Documentation/crypto/index.rst
+++ b/Documentation/crypto/index.rst@@ -25,6 +25,7 @@ for cryptographic use cases, as well as programming examples. devel-algos userspace-if crypto_engine + crypto_pool api api-samples descore-readme
--
2.39.0