[PATCH] docs: crypto: async-tx-api: fix broken code example

[PATCH] docs: crypto: async-tx-api: fix broken code example

[Ahmad Fatoum]

The code example fails to compile:

  1) ddr_conv is defined twice, once as a VLA, which have been phased out

  2) submit is not a pointer, but is still dereferenced with ->

Fix these issues and while at it, make the functions static as users
are unlikely to export them.

Fixes: 04ce9ab385dc ("async_xor: permit callers to pass in a 'dma/page scribble' region")
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/crypto/async-tx-api.rst | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/Documentation/crypto/async-tx-api.rst b/Documentation/crypto/async-tx-api.rst
index 27c146b54d71..2fa260f2a222 100644
--- a/Documentation/crypto/async-tx-api.rst
+++ b/Documentation/crypto/async-tx-api.rst
@@ -150,38 +150,38 @@ of an operation.
 Perform a xor->copy->xor operation where each operation depends on the
 result from the previous operation::
 
-    void callback(void *param)
+    static void callback(void *param)
     {
 	    struct completion *cmp = param;
 
 	    complete(cmp);
     }
 
-    void run_xor_copy_xor(struct page **xor_srcs,
-			int xor_src_cnt,
-			struct page *xor_dest,
-			size_t xor_len,
-			struct page *copy_src,
-			struct page *copy_dest,
-			size_t copy_len)
+    #define NDISKS  2
+
+    static void run_xor_copy_xor(struct page **xor_srcs,
+				 struct page *xor_dest,
+				 size_t xor_len,
+				 struct page *copy_src,
+				 struct page *copy_dest,
+				 size_t copy_len)
     {
 	    struct dma_async_tx_descriptor *tx;
-	    addr_conv_t addr_conv[xor_src_cnt];
 	    struct async_submit_ctl submit;
 	    addr_conv_t addr_conv[NDISKS];
 	    struct completion cmp;
 
 	    init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST, NULL, NULL, NULL,
 			    addr_conv);
-	    tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit)
+	    tx = async_xor(xor_dest, xor_srcs, 0, NDISKS, xor_len, &submit);
 
-	    submit->depend_tx = tx;
+	    submit.depend_tx = tx;
 	    tx = async_memcpy(copy_dest, copy_src, 0, 0, copy_len, &submit);
 
 	    init_completion(&cmp);
 	    init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST | ASYNC_TX_ACK, tx,
 			    callback, &cmp, addr_conv);
-	    tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit);
+	    tx = async_xor(xor_dest, xor_srcs, 0, NDISKS, xor_len, &submit);
 
 	    async_tx_issue_pending_all();
 

---
base-commit: a38297e3fb012ddfa7ce0321a7e5a8daeb1872b6
change-id: 20240523-async-dma-docs-00eb18a4e01c

Best regards,
-- 
Ahmad Fatoum <a.fatoum@pengutronix.de>

Re: [PATCH] docs: crypto: async-tx-api: fix broken code example

[Andre Noll]

On Thu, May 23, 15:18, Ahmad Fatoum wrote
> The code example fails to compile:
> 
>   1) ddr_conv is defined twice, once as a VLA, which have been phased out

       addr_conv
> 
>   2) submit is not a pointer, but is still dereferenced with ->

3) The first call to async_xor() lacked the trailing semicolon.

> Fix these issues and while at it, make the functions static as users
> are unlikely to export them.

No objections, but please don't consider me authoritative. Two nits
below, FWIW.

> --- a/Documentation/crypto/async-tx-api.rst
> +++ b/Documentation/crypto/async-tx-api.rst
> @@ -150,38 +150,38 @@ of an operation.
>  Perform a xor->copy->xor operation where each operation depends on the
>  result from the previous operation::

Maybe add

#include <linux/async_tx.h>

>  
> -    void callback(void *param)
> +    static void callback(void *param)
>      {
>  	    struct completion *cmp = param;
>  
>  	    complete(cmp);
>      }

This could be simplified to

static void callback(void *param)
{
	complete(param);
}

Best
Andre
-- 
Max Planck Institute for Biology
Tel: (+49) 7071 601 829
Max-Planck-Ring 5, 72076 Tübingen, Germany
http://people.tuebingen.mpg.de/maan/

Re: [PATCH] docs: crypto: async-tx-api: fix broken code example

[Ahmad Fatoum]

Hello Andre,

On 23.05.24 16:17, Andre Noll wrote:
> On Thu, May 23, 15:18, Ahmad Fatoum wrote
>> The code example fails to compile:
>>
>>   1) ddr_conv is defined twice, once as a VLA, which have been phased out
> 
>        addr_conv
>>
>>   2) submit is not a pointer, but is still dereferenced with ->
> 
> 3) The first call to async_xor() lacked the trailing semicolon.
> 
>> Fix these issues and while at it, make the functions static as users
>> are unlikely to export them.
> 
> No objections, but please don't consider me authoritative. Two nits
> below, FWIW.

Oh, thanks for catching these. I just sent a v2 with your feedback
incorporated including the nitpicks.

Cheers,
Ahmad

> 
>> --- a/Documentation/crypto/async-tx-api.rst
>> +++ b/Documentation/crypto/async-tx-api.rst
>> @@ -150,38 +150,38 @@ of an operation.
>>  Perform a xor->copy->xor operation where each operation depends on the
>>  result from the previous operation::
> 
> Maybe add
> 
> #include <linux/async_tx.h>
> 
>>  
>> -    void callback(void *param)
>> +    static void callback(void *param)
>>      {
>>  	    struct completion *cmp = param;
>>  
>>  	    complete(cmp);
>>      }
> 
> This could be simplified to
> 
> static void callback(void *param)
> {
> 	complete(param);
> }
> 
> Best
> Andre

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |