linux-kernel - Re: [PATCH v2 5/5] crypto/Documentation: Add crypto

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20230106180616.4a39dd2a@kernel.org>
Date:   Fri, 6 Jan 2023 18:06:16 -0800
From:   Jakub Kicinski <kuba@...nel.org>
To:     Dmitry Safonov <dima@...sta.com>
Cc:     linux-kernel@...r.kernel.org, David Ahern <dsahern@...nel.org>,
        Eric Dumazet <edumazet@...gle.com>,
        Herbert Xu <herbert@...dor.apana.org.au>,
        "David S. Miller" <davem@...emloft.net>,
        Andy Lutomirski <luto@...capital.net>,
        Bob Gilligan <gilligan@...sta.com>,
        Dmitry Safonov <0x7f454c46@...il.com>,
        Hideaki YOSHIFUJI <yoshfuji@...ux-ipv6.org>,
        Leonard Crestez <cdleonard@...il.com>,
        Paolo Abeni <pabeni@...hat.com>,
        Salam Noureddine <noureddine@...sta.com>,
        netdev@...r.kernel.org, linux-crypto@...r.kernel.org
Subject: Re: [PATCH v2 5/5] crypto/Documentation: Add crypto_pool kernel API

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.