| Message ID | 20230103184257.118069-6-dima@arista.com (mailing list archive) |
|---|---|
| State | Not Applicable |
| Delegated to: | Herbert Xu |
| Headers | show |
| Series | net/crypto: Introduce crypto_pool | expand |
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
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()``.
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