Received-SPF: pass (google.com: domain of linux-kernel+bounces-55463-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) client-ip=147.75.80.249;
From: Nhat Pham <nphamcs@gmail.com>
To: mark.rutland@arm.com
Cc: linux-kernel@vger.kernel.org,
	boqun.feng@gmail.com,
	frederic@kernel.org,
	joel@joelfernandes.org,
	neeraj.iitr10@gmail.com,
	paulmck@kernel.org,
	peterz@infradead.org,
	will@kernel.org
Subject: Re: [PATCH] locking/atomic: scripts: clarify ordering of conditional atomics
Date: Tue,  6 Feb 2024 10:40:05 -0800
Message-Id: <20240206184005.4125128-1-nphamcs@gmail.com>
In-Reply-To: <20240129122250.1086874-1-mark.rutland@arm.com>
References: <20240129122250.1086874-1-mark.rutland@arm.com>
Precedence: bulk
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

Let me bring in some beginners' perspective :)

For the most part, LGTM! My only comment is regarding the conditional
atomics with relaxed ordering on success:

/**
  * If (@v == @old), atomically updates @v to @new with relaxed ordering.
+ * Otherwise, @v is not modified and no ordering is provided.

This is technically correct, but it can be confusing. It reads as if
"relaxed ordering" is much different from no ordering, since we are
juxtaposing them when we compare what happens when the condition holds
v.s when it does not.

This can be potentially confusing to unfamiliar users. I consulted
with Paul about this, and he suggested this rewording, which I like
better:

"Otherwise, @v is not modified and relaxed ordering is provided."

With something along that line in place:
Reviewed-by: Nhat Pham <nphamcs@gmail.com>