Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   "Paul E. McKenney" <paulmck@kernel.org>
To:     linux-kernel@vger.kernel.org
Cc:     x86@kernel.org, akiyks@gmail.com, linux-doc@vger.kernel.org,
        kernel-team@meta.com, "Paul E. McKenney" <paulmck@kernel.org>,
        Will Deacon <will@kernel.org>,
        Peter Zijlstra <peterz@infradead.org>,
        Boqun Feng <boqun.feng@gmail.com>,
        Mark Rutland <mark.rutland@arm.com>
Subject: [PATCH locking/atomic 13/19] locking/atomic: Script to auto-generate acquire, fence, and release headers
Date:   Wed, 10 May 2023 11:17:11 -0700
Message-Id: <20230510181717.2200934-13-paulmck@kernel.org>
In-Reply-To: <19135936-06d7-4705-8bc8-bb31c2a478ca@paulmck-laptop>
References: <19135936-06d7-4705-8bc8-bb31c2a478ca@paulmck-laptop>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

The scripts/atomic/fallbacks/{acquire,fence,release} scripts require almost
identical scripting to automatically generated the required kernel-doci
headers.  Therefore, provide a single acqrel.sh script that does this
work.  This new script is to be invoked from each of those scripts using
the "." command, and with the shell variable "acqrel" set to either
"acquire", "full", or "release".

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Cc: Will Deacon <will@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Boqun Feng <boqun.feng@gmail.com>
Cc: Mark Rutland <mark.rutland@arm.com>
---
 scripts/atomic/acqrel.sh | 67 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 scripts/atomic/acqrel.sh

diff --git a/scripts/atomic/acqrel.sh b/scripts/atomic/acqrel.sh
new file mode 100644
index 000000000000..5009a54fdac5
--- /dev/null
+++ b/scripts/atomic/acqrel.sh
@@ -0,0 +1,67 @@
+echo ${args} | tr -d ' ' | tr ',' '\012' |
+	awk -v atomic=${atomic} \
+	    -v name_op=${name} \
+	    -v ret=${ret} \
+	    -v oldnew=${docbook_oldnew} \
+	    -v acqrel=${acqrel} \
+	    -v basefuncname=arch_${atomic}_${pfx}${name}${sfx} '
+	BEGIN {
+		print "/**";
+		sfxord = "_" acqrel;
+		if (acqrel == "full")
+			sfxord = "";
+		print " * " basefuncname sfxord " - Atomic " name_op " with " acqrel " ordering";
+		longname["add"] = "add";
+		longname["sub"] = "subtract";
+		longname["inc"] = "increment";
+		longname["dec"] = "decrement";
+		longname["and"] = "AND";
+		longname["andnot"] = "complement then AND";
+		longname["or"] = "OR";
+		longname["xor"] = "XOR";
+		longname["xchg"] = "exchange";
+		longname["add_negative"] = "add";
+		desc["i"] = "value to " longname[name_op];
+		desc["v"] = "pointer of type " atomic "_t";
+		desc["old"] = "desired old value to match";
+		desc["new"] = "new value to put in";
+		opmod = "with";
+		if (name_op == "add")
+			opmod = "to";
+		else if (name_op == "sub")
+			opmod = "from";
+	}
+
+	{
+		print " * @" $1 ": " desc[$1];
+		have[$1] = 1;
+	}
+
+	END {
+		print " *";
+		if (name_op ~ /cmpxchg/) {
+			print " * Atomically compares @new to *@v, and if equal,";
+			print " * stores @new to *@v, providing " acqrel " ordering.";
+		} else if (have["i"]) {
+			print " * Atomically " longname[name_op] " @i " opmod " @v using " acqrel " ordering.";
+		} else {
+			print " * Atomically " longname[name_op] " @v using " acqrel " ordering.";
+		}
+		if (name_op ~ /cmpxchg/ && ret == "bool") {
+			print " * Returns @true if the cmpxchg operation succeeded,";
+			print " * and false otherwise.  Either way, stores the old";
+			print " * value of *@v to *@old.";
+		} else if (name_op == "cmpxchg") {
+			print " * Returns the old value *@v regardless of the result of";
+			print " * the comparison.  Therefore, if the return value is not";
+			print " * equal to @old, the cmpxchg operation failed.";
+		} else if (name_op == "xchg") {
+			print " * Return old value.";
+		} else if (name_op == "add_negative") {
+			print " * Return @true if the result is negative, or @false when"
+			print " * the result is greater than or equal to zero.";
+		} else {
+			print " * Return " oldnew " value.";
+		}
+		print " */";
+	}'
-- 
2.40.1