Received-SPF: pass (google.com: best guess record for domain of linux-crypto-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Message-ID: <983486e9b2daaa34f84f99a890fcedfeae22b24f.camel@perches.com>
Subject: Re: [PATCH v2 2/2] crypto: doc - Fix formatting of new crypto
 engine content
From:   Joe Perches <joe@perches.com>
To:     "Hook, Gary" <Gary.Hook@amd.com>,
        "herbert@gondor.apana.org.au" <herbert@gondor.apana.org.au>,
        "corbet@lwn.net" <corbet@lwn.net>,
        "linux-doc@vger.kernel.org" <linux-doc@vger.kernel.org>,
        "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
        "linux-crypto@vger.kernel.org" <linux-crypto@vger.kernel.org>,
        "davem@davemloft.net" <davem@davemloft.net>
Date:   Tue, 25 Jun 2019 17:13:25 -0700
In-Reply-To: <156150622886.22527.934327975584441429.stgit@taos>
References: <156150616764.22527.16524544899486041609.stgit@taos>
         <156150622886.22527.934327975584441429.stgit@taos>
Content-Type: text/plain; charset="ISO-8859-1"
User-Agent: Evolution 3.30.5-0ubuntu0.18.10.1 
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Sender: linux-crypto-owner@vger.kernel.org
Precedence: bulk

On Tue, 2019-06-25 at 23:43 +0000, Hook, Gary wrote:
> Tidy up the formatting/grammar in crypto_engine.rst. Use bulleted lists
> where appropriate.

Hi again Gary.

> diff --git a/Documentation/crypto/crypto_engine.rst b/Documentation/crypto/crypto_engine.rst
[]
> +Before transferring any request, you have to fill the context enginectx by
> +providing functions for the following:
> +
> +* ``prepare_crypt_hardware``: Called once before any prepare functions are
> +  called.
> +
> +* ``unprepare_crypt_hardware``: Called once after all unprepare functions have
> +  been called.
> +
> +* ``prepare_cipher_request``/``prepare_hash_request``: Called before each
> +  corresponding request is performed. If some processing or other preparatory
> +  work is required, do it here.
> +
> +* ``unprepare_cipher_request``/``unprepare_hash_request``: Called after each
> +  request is handled. Clean up / undo what was done in the prepare function.
> +
> +* ``cipher_one_request``/``hash_one_request``: Handle the current request by
> +  performing the operation.

I again suggest not using ``<func>`` but instead use <func>()
and remove unnecessary blank lines.

i.e.:

* prepare_crypt_hardware(): Called once before any prepare functions are
  called.
* unprepare_crypt_hardware():  Called once after all unprepare functions
  have been called.
* prepare_cipher_request()/prepare_hash_request(): Called before each
  corresponding request is performed. If some processing or other preparatory
  work is required, do it here.
* unprepare_cipher_request()/unprepare_hash_request(): Called after each
  request is handled. Clean up / undo what was done in the prepare function.
* cipher_one_request()/hash_one_request(): Handle the current request by
  performing the operation.

[]
> +When your driver receives a crypto_request, you must to transfer it to
> +the crypto engine via one of:
> +
> +* crypto_transfer_ablkcipher_request_to_engine()

And removing the unnecessary blank lines below

> +
> +* crypto_transfer_aead_request_to_engine()
> +
> +* crypto_transfer_akcipher_request_to_engine()
> +
> +* crypto_transfer_hash_request_to_engine()
> +
> +* crypto_transfer_skcipher_request_to_engine()
> +
> +At the end of the request process, a call to one of the following functions is needed:
> +
> +* crypto_finalize_ablkcipher_request()
> +
> +* crypto_finalize_aead_request()
> +
> +* crypto_finalize_akcipher_request()
> +
> +* crypto_finalize_hash_request()
> +
> +* crypto_finalize_skcipher_request()