[PATCH 1/2] defer: Update Hlist RCU API tables

[PATCH 1/2] defer: Update Hlist RCU API tables

[Akira Yokosawa]

From ce79ac6df2f3d3fcb6d24b1b629ce78f69eea6f8 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 2 Dec 2018 19:05:54 +0900
Subject: [PATCH 1/2] defer: Update Hlist RCU API tables

Current Linux kernel API does not have hlist_add_after_rcu()
but has hlist_add_behind_rcu().

It was renamed in the 3.17 development cycle due to swapping of
the arguments.

While we are here, add the missing category of "Hlist update"
and reference the table by the label instead of just saying
"the following table".

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 defer/rcuapi.tex         | 14 +++++++++-----
 defer/rcufundamental.tex |  4 ++--
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/defer/rcuapi.tex b/defer/rcuapi.tex
index 5502092..8dc2cc3 100644
--- a/defer/rcuapi.tex
+++ b/defer/rcuapi.tex
@@ -439,8 +439,9 @@ their scope.
 \label{sec:defer:RCU has Publish-Subscribe and Version-Maintenance APIs}
 
 Fortunately, the RCU publish-subscribe and version-maintenance
-primitives shown in the following
-table apply to all of the variants of RCU discussed above.
+primitives shown in
+Table~\ref{tab:defer:RCU Publish-Subscribe and Version Maintenance APIs}
+apply to all of the variants of RCU discussed above.
 This commonality can in some cases allow more code to be shared,
 which certainly reduces the API proliferation that would otherwise
 occur.
@@ -491,9 +492,12 @@ Hlist traversal &
 	\tco{hlist_for_each_entry_rcu()} &
 		2.6.8 &
 			Simple instructions (memory barrier on Alpha) \\
-&
-	\tco{hlist_add_after_rcu()} &
-		2.6.14 &
+\midrule
+Hlist Update &
+	\tco{hlist_add_behind_rcu()} &
+		\parbox[t][0.3in][t]{0.8in}{
+		    2.6.14 \\
+                    (renamed in 3.17)} &
 			Memory barrier \\
 &
 	\tco{hlist_add_before_rcu()} &
diff --git a/defer/rcufundamental.tex b/defer/rcufundamental.tex
index c4a8905..2660e7d 100644
--- a/defer/rcufundamental.tex
+++ b/defer/rcufundamental.tex
@@ -399,8 +399,8 @@ Lists     & \parbox[c][0.37in][c]{1.3in}{
 					& \tco{list_for_each_entry_rcu()} \\
 \midrule
 Hlists    & \parbox[c][0.5in][c]{1.3in}{
-		\co{hlist_add_after_rcu()} \\
-		\co{hlist_add_before_rcu()}  \\
+		\co{hlist_add_behind_rcu()} \\
+		\co{hlist_add_before_rcu()} \\
 		\co{hlist_add_head_rcu()} \\
 		\co{hlist_replace_rcu()} }
 			& \tco{hlist_del_rcu()}
-- 
2.7.4

Re: [PATCH v2 1/2] defer: Update Hlist RCU API table

[Akira Yokosawa]

Paul,

IIUC, your work on RCU API consolidation seems to affect Section 9.5.4,
especially Table 9.3.

I'm not sure, but one idea would be to keep Table 9.3 for future
reference and add a new one representing consolidated set of API.

Just a reminder.

        Thanks, Akira

 

Re: [PATCH v2 1/2] defer: Update Hlist RCU API table

[Paul E. McKenney]

[-- Attachment #1: Type: text/plain, Size: 574 bytes --]

On Mon, Dec 03, 2018 at 12:11:20AM +0900, Akira Yokosawa wrote:
> Paul,
> 
> IIUC, your work on RCU API consolidation seems to affect Section 9.5.4,
> especially Table 9.3.
> 
> I'm not sure, but one idea would be to keep Table 9.3 for future
> reference and add a new one representing consolidated set of API.
> 
> Just a reminder.

And a timely one!  Please see attached for a possible LWN article.
Though the LWN editors might quite rightly decide that a third
RCU API article is one too many, in which case I will blog it.

But either way, thoughts?

							Thanx, Paul

[-- Attachment #2: LWNRCUAPI2018.11.26a.tgz --]
[-- Type: application/x-gtar-compressed, Size: 51025 bytes --]

Re: [PATCH v2 1/2] defer: Update Hlist RCU API table

[Paul E. McKenney]

On Sun, Dec 02, 2018 at 11:57:47PM +0900, Akira Yokosawa wrote:
> >From 8cd7d7bb4b42f67e67d2273c6c048b26a9ec3366 Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa <akiyks@gmail.com>
> Date: Sun, 2 Dec 2018 23:35:43 +0900
> Subject: [PATCH v2 1/2] defer: Update Hlist RCU API table
> 
> Current Linux kernel API does not have hlist_add_after_rcu()
> but has hlist_add_behind_rcu().
> 
> It was renamed in the 3.17 development cycle due to swapping of
> the arguments.
> 
> While we are here, reference the table by the label instead of
> just saying "the following table".
> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>

Applied both, thank you!

							Thanx, Paul

> ---
> Hi Paul,
> 
> This one keeps the original API name in the table.
> It also fixes "Hlist Update" -> "Hlist update" for consistency.
> 
> I'm submitting v2 of [1/2] only.
> 
>         Thanks, Akira
> --
>  defer/rcuapi.tex         | 12 ++++++++----
>  defer/rcufundamental.tex |  4 ++--
>  2 files changed, 10 insertions(+), 6 deletions(-)
> 
> diff --git a/defer/rcuapi.tex b/defer/rcuapi.tex
> index 5502092..a50dcbe 100644
> --- a/defer/rcuapi.tex
> +++ b/defer/rcuapi.tex
> @@ -439,8 +439,9 @@ their scope.
>  \label{sec:defer:RCU has Publish-Subscribe and Version-Maintenance APIs}
>  
>  Fortunately, the RCU publish-subscribe and version-maintenance
> -primitives shown in the following
> -table apply to all of the variants of RCU discussed above.
> +primitives shown in
> +Table~\ref{tab:defer:RCU Publish-Subscribe and Version Maintenance APIs}
> +apply to all of the variants of RCU discussed above.
>  This commonality can in some cases allow more code to be shared,
>  which certainly reduces the API proliferation that would otherwise
>  occur.
> @@ -491,10 +492,13 @@ Hlist traversal &
>  	\tco{hlist_for_each_entry_rcu()} &
>  		2.6.8 &
>  			Simple instructions (memory barrier on Alpha) \\
> -&
> -	\tco{hlist_add_after_rcu()} &
> +\midrule
> +Hlist update &
> +	\tco{hlist_add_behind_rcu()} &
>  		2.6.14 &
>  			Memory barrier \\
> +&	\multicolumn{2}{l}{(Renamed from \tco{hlist_add_after_rcu()} in 3.17)} &
> +			\\ \addlinespace[2pt]
>  &
>  	\tco{hlist_add_before_rcu()} &
>  		2.6.14 &
> diff --git a/defer/rcufundamental.tex b/defer/rcufundamental.tex
> index c4a8905..2660e7d 100644
> --- a/defer/rcufundamental.tex
> +++ b/defer/rcufundamental.tex
> @@ -399,8 +399,8 @@ Lists     & \parbox[c][0.37in][c]{1.3in}{
>  					& \tco{list_for_each_entry_rcu()} \\
>  \midrule
>  Hlists    & \parbox[c][0.5in][c]{1.3in}{
> -		\co{hlist_add_after_rcu()} \\
> -		\co{hlist_add_before_rcu()}  \\
> +		\co{hlist_add_behind_rcu()} \\
> +		\co{hlist_add_before_rcu()} \\
>  		\co{hlist_add_head_rcu()} \\
>  		\co{hlist_replace_rcu()} }
>  			& \tco{hlist_del_rcu()}
> -- 
> 2.7.4
> 
>