Message-ID: <20250717080617.35577-3-bagasdotme@gmail.com>
Date: Thu, 17 Jul 2025 15:06:15 +0700
From: Bagas Sanjaya <bagasdotme@...il.com>
To: Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
	Linux Documentation <linux-doc@...r.kernel.org>,
	Linux RCU <rcu@...r.kernel.org>,
	Linux CPU Architectures Development <linux-arch@...r.kernel.org>,
	Linux LKMM <lkmm@...ts.linux.dev>,
	Linux KVM <kvm@...r.kernel.org>
Cc: "Paul E. McKenney" <paulmck@...nel.org>,
	Frederic Weisbecker <frederic@...nel.org>,
	Neeraj Upadhyay <neeraj.upadhyay@...nel.org>,
	Joel Fernandes <joelagnelf@...dia.com>,
	Josh Triplett <josh@...htriplett.org>,
	Boqun Feng <boqun.feng@...il.com>,
	Uladzislau Rezki <urezki@...il.com>,
	Steven Rostedt <rostedt@...dmis.org>,
	Mathieu Desnoyers <mathieu.desnoyers@...icios.com>,
	Lai Jiangshan <jiangshanlai@...il.com>,
	Zqiang <qiang.zhang@...ux.dev>,
	Jonathan Corbet <corbet@....net>,
	Alan Stern <stern@...land.harvard.edu>,
	Andrea Parri <parri.andrea@...il.com>,
	Will Deacon <will@...nel.org>,
	Peter Zijlstra <peterz@...radead.org>,
	Nicholas Piggin <npiggin@...il.com>,
	David Howells <dhowells@...hat.com>,
	Jade Alglave <j.alglave@....ac.uk>,
	Luc Maranget <luc.maranget@...ia.fr>,
	Akira Yokosawa <akiyks@...il.com>,
	Daniel Lustig <dlustig@...dia.com>,
	Mark Rutland <mark.rutland@....com>,
	Ingo Molnar <mingo@...hat.com>,
	Waiman Long <longman@...hat.com>,
	Paolo Bonzini <pbonzini@...hat.com>,
	Bagas Sanjaya <bagasdotme@...il.com>,
	Andrew Morton <akpm@...ux-foundation.org>,
	Tejun Heo <tj@...nel.org>,
	"Mike Rapoport (Microsoft)" <rppt@...nel.org>,
	Changyuan Lyu <changyuanl@...gle.com>,
	Dan Williams <dan.j.williams@...el.com>,
	Xavier <xavier_qy@....com>,
	Randy Dunlap <rdunlap@...radead.org>,
	Maarten Lankhorst <dev@...khorst.se>,
	Christian Brauner <brauner@...nel.org>
Subject: [PATCH 2/4] Documentation: atomic_bitops: Convert to reST format

Convert atomic bitops documentation to reST syntax:

* Sentence-case headings
* List API functions and their semantics in bullet list

Signed-off-by: Bagas Sanjaya <bagasdotme@...il.com>
---
 .../atomic_bitops.rst}                        | 39 +++++++++----------
 Documentation/core-api/index.rst              |  2 +-
 .../core-api/wrappers/atomic_bitops.rst       | 18 ---------
 3 files changed, 20 insertions(+), 39 deletions(-)
 rename Documentation/{atomic_bitops.txt => core-api/atomic_bitops.rst} (60%)
 delete mode 100644 Documentation/core-api/wrappers/atomic_bitops.rst

diff --git a/Documentation/atomic_bitops.txt b/Documentation/core-api/atomic_bitops.rst
similarity index 60%
rename from Documentation/atomic_bitops.txt
rename to Documentation/core-api/atomic_bitops.rst
index edea4656c5c05f..b93c388fd9bdc4 100644
--- a/Documentation/atomic_bitops.txt
+++ b/Documentation/core-api/atomic_bitops.rst
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
 =============
 Atomic bitops
 =============
@@ -11,53 +13,50 @@ API
 
 The single bit operations are:
 
-Non-RMW ops:
+* Non-RMW ops:
 
-  test_bit()
+  * test_bit()
 
-RMW atomic operations without return value:
+* RMW atomic operations without return value:
 
-  {set,clear,change}_bit()
-  clear_bit_unlock()
+  * {set,clear,change}_bit()
+  * clear_bit_unlock()
 
-RMW atomic operations with return value:
+* RMW atomic operations with return value:
 
-  test_and_{set,clear,change}_bit()
-  test_and_set_bit_lock()
+  * test_and_{set,clear,change}_bit()
+  * test_and_set_bit_lock()
 
-Barriers:
+* Barriers:
 
-  smp_mb__{before,after}_atomic()
+  * smp_mb__{before,after}_atomic()
 
 
 All RMW atomic operations have a '__' prefixed variant which is non-atomic.
 
 
-SEMANTICS
+Semantics
 ---------
 
-Non-atomic ops:
+* Non-atomic ops:
 
-In particular __clear_bit_unlock() suffers the same issue as atomic_set(),
-which is why the generic version maps to clear_bit_unlock(), see atomic_t.txt.
+  In particular __clear_bit_unlock() suffers the same issue as atomic_set(),
+  which is why the generic version maps to clear_bit_unlock(), see atomic_t.txt.
 
 
-RMW ops:
+* RMW ops:
 
-The test_and_{}_bit() operations return the original value of the bit.
+  The test_and_{}_bit() operations return the original value of the bit.
 
 
-ORDERING
+Ordering
 --------
 
 Like with atomic_t, the rule of thumb is:
 
  - non-RMW operations are unordered;
-
  - RMW operations that have no return value are unordered;
-
  - RMW operations that have a return value are fully ordered.
-
  - RMW operations that are conditional are fully ordered.
 
 Except for a successful test_and_set_bit_lock() which has ACQUIRE semantics,
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index a0c3749c655b05..4bc132fefaab7f 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -49,7 +49,7 @@ Library functionality that is used throughout the kernel.
    timekeeping
    errseq
    wrappers/atomic_t
-   wrappers/atomic_bitops
+   atomic_bitops
    floating-point
    union_find
    min_heap
diff --git a/Documentation/core-api/wrappers/atomic_bitops.rst b/Documentation/core-api/wrappers/atomic_bitops.rst
deleted file mode 100644
index bf24e4081a8f4c..00000000000000
--- a/Documentation/core-api/wrappers/atomic_bitops.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-   This is a simple wrapper to bring atomic_bitops.txt into the RST world
-   until such a time as that file can be converted directly.
-
-=============
-Atomic bitops
-=============
-
-.. raw:: latex
-
-    \footnotesize
-
-.. include:: ../../atomic_bitops.txt
-   :literal:
-
-.. raw:: latex
-
-    \normalsize
-- 
An old man doll... just what I always wanted! - Clara

Powered by blists - more mailing lists