Linux-Doc Archive on lore.kernel.org
 help / color / Atom feed
From: Peter Zijlstra <peterz@infradead.org>
To: "Ahmed S. Darwish" <a.darwish@linutronix.de>
Cc: Ingo Molnar <mingo@redhat.com>, Will Deacon <will@kernel.org>,
	Thomas Gleixner <tglx@linutronix.de>,
	"Paul E. McKenney" <paulmck@kernel.org>,
	"Sebastian A. Siewior" <bigeasy@linutronix.de>,
	Steven Rostedt <rostedt@goodmis.org>,
	LKML <linux-kernel@vger.kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	linux-doc@vger.kernel.org
Subject: Re: [PATCH v3 01/20] Documentation: locking: Describe seqlock design and usage
Date: Mon, 6 Jul 2020 23:16:59 +0200
Message-ID: <20200706211659.GA5551@worktop.programming.kicks-ass.net> (raw)
In-Reply-To: <20200706210439.GD5523@worktop.programming.kicks-ass.net>

On Mon, Jul 06, 2020 at 11:04:39PM +0200, Peter Zijlstra wrote:
> On Tue, Jun 30, 2020 at 07:44:33AM +0200, Ahmed S. Darwish wrote:
> > +Sequence counters (:c:type:`seqcount_t`)
> > +========================================
> 
> > +.. code-block:: c
> 
> I so hate RST, of course it's C. Also, ISTR Jon saying you can leave
> that all out without issue.

Something like the below, and then there's all that :ref: nonsense in
that's unreadable gibberish.


Index: linux-2.6/Documentation/locking/seqlock.rst
===================================================================
--- linux-2.6.orig/Documentation/locking/seqlock.rst
+++ linux-2.6/Documentation/locking/seqlock.rst
@@ -33,10 +33,8 @@ class, it can spin forever and the kerne
 This mechanism cannot be used if the protected data contains pointers,
 as the writer can invalidate a pointer that the reader is following.
 
-.. _seqcount_t:
-
-Sequence counters (:c:type:`seqcount_t`)
-========================================
+Sequence counters (`seqcount_t`)
+================================
 
 This is the the raw counting mechanism, which does not protect against
 multiple writers.  Write side critical sections must thus be serialized
@@ -56,8 +54,6 @@ requirements, use a :ref:`sequential loc
 
 Initialization:
 
-.. code-block:: c
-
 	/* dynamic */
 	seqcount_t foo_seqcount;
 	seqcount_init(&foo_seqcount);
@@ -72,9 +68,6 @@ Initialization:
 
 Write path:
 
-.. _seqcount_write_ops:
-.. code-block:: c
-
 	/* Serialized context with disabled preemption */
 
 	write_seqcount_begin(&foo_seqcount);
@@ -85,9 +78,6 @@ Write path:
 
 Read path:
 
-.. _seqcount_read_ops:
-.. code-block:: c
-
 	do {
 		seq = read_seqcount_begin(&foo_seqcount);
 
@@ -95,9 +85,7 @@ Read path:
 
 	} while (read_seqcount_retry(&foo_seqcount, seq));
 
-.. _seqcount_locktype_t:
-
-Sequence counters with associated locks (:c:type:`seqcount_LOCKTYPE_t`)
+Sequence counters with associated locks (`seqcount_LOCKTYPE_t`)
 -----------------------------------------------------------------------
 
 As :ref:`earlier discussed <seqcount_t>`, seqcount write side critical
@@ -117,11 +105,11 @@ protection is enforced in the write side
 
 The following seqcounts with associated locks are defined:
 
-  - :c:type:`seqcount_spinlock_t`
-  - :c:type:`seqcount_raw_spinlock_t`
-  - :c:type:`seqcount_rwlock_t`
-  - :c:type:`seqcount_mutex_t`
-  - :c:type:`seqcount_ww_mutex_t`
+  - `seqcount_spinlock_t`
+  - `seqcount_raw_spinlock_t`
+  - `seqcount_rwlock_t`
+  - `seqcount_mutex_t`
+  - `seqcount_ww_mutex_t`
 
 The plain seqcount read and write APIs branch out to the specific
 seqcount_LOCKTYPE_t implementation at compile-time. This avoids kernel
@@ -129,8 +117,6 @@ API explosion per each new seqcount LOCK
 
 Initialization (replace "LOCKTYPE" with one of the supported locks):
 
-.. code-block:: c
-
 	/* dynamic */
 	seqcount_LOCKTYPE_t foo_seqcount;
 	seqcount_LOCKTYPE_init(&foo_seqcount, &lock);
@@ -149,9 +135,7 @@ while running from a context with the as
 
 Read path: same as in :ref:`plain seqcount_t <seqcount_read_ops>`.
 
-.. _seqlock_t:
-
-Sequential locks (:c:type:`seqlock_t`)
+Sequential locks (`seqlock_t`)
 ======================================
 
 This contains the :ref:`sequence counting mechanism <seqcount_t>`
@@ -164,8 +148,6 @@ halves respectively.
 
 Initialization:
 
-.. code-block:: c
-
 	/* dynamic */
 	seqlock_t foo_seqlock;
 	seqlock_init(&foo_seqlock);
@@ -180,8 +162,6 @@ Initialization:
 
 Write path:
 
-.. code-block:: c
-
 	write_seqlock(&foo_seqlock);
 
 	/* ... [[write-side critical section]] ... */
@@ -194,8 +174,6 @@ Read path, three categories:
    retry if a writer is in progress by detecting change in the sequence
    number.  Writers do not wait for a sequence reader.
 
-   .. code-block:: c
-
 	do {
 		seq = read_seqbegin(&foo_seqlock);
 
@@ -208,8 +186,6 @@ Read path, three categories:
    from entering its critical section. This read lock is
    exclusive. Unlike rwlock_t, only one locking reader can acquire it.
 
-   .. code-block:: c
-
 	read_seqlock_excl(&foo_seqlock);
 
 	/* ... [[read-side critical section]] ... */
@@ -224,8 +200,6 @@ Read path, three categories:
    the next iteration marker), the lockless read is transformed to a
    full locking read and no retry loop is necessary.
 
-   .. code-block:: c
-
 	/* marker; even initialization */
 	int seq = 0;
 	do {


  parent reply index

Thread overview: 42+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-05-19 21:45 [PATCH v1 00/25] seqlock: Extend seqcount API with associated locks Ahmed S. Darwish
2020-05-19 21:45 ` [PATCH v1 09/25] Documentation: locking: Describe seqlock design and usage Ahmed S. Darwish
2020-05-22 18:01   ` Peter Zijlstra
2020-05-22 22:24     ` Steven Rostedt
2020-05-25 10:50       ` Ahmed S. Darwish
2020-05-25 11:02         ` Ahmed S. Darwish
2020-05-19 21:45 ` [PATCH v1 10/25] seqlock: Add RST directives to kernel-doc code samples and notes Ahmed S. Darwish
2020-05-22 18:02   ` Peter Zijlstra
2020-05-22 18:03     ` Peter Zijlstra
2020-05-22 18:26       ` Thomas Gleixner
2020-05-22 18:32         ` Peter Zijlstra
2020-05-25  9:36           ` Ahmed S. Darwish
2020-05-25 13:44             ` Peter Zijlstra
2020-05-25 14:07               ` Peter Zijlstra
2020-05-19 21:45 ` [PATCH v1 11/25] seqlock: Add missing kernel-doc annotations Ahmed S. Darwish
2020-05-19 21:45 ` [PATCH v1 12/25] seqlock: Extend seqcount API with associated locks Ahmed S. Darwish
2020-06-08  0:57 ` [PATCH v2 00/18] " Ahmed S. Darwish
2020-06-08  0:57   ` [PATCH v2 01/18] Documentation: locking: Describe seqlock design and usage Ahmed S. Darwish
2020-06-08  0:57   ` [PATCH v2 02/18] seqlock: Properly format kernel-doc code samples Ahmed S. Darwish
2020-06-08  0:57   ` [PATCH v2 03/18] seqlock: Add missing kernel-doc annotations Ahmed S. Darwish
2020-06-30  5:44 ` [PATCH v3 00/20] seqlock: Extend seqcount API with associated locks Ahmed S. Darwish
2020-06-30  5:44   ` [PATCH v3 01/20] Documentation: locking: Describe seqlock design and usage Ahmed S. Darwish
2020-07-06 21:04     ` Peter Zijlstra
2020-07-06 21:12       ` Jonathan Corbet
2020-07-06 21:16       ` Peter Zijlstra [this message]
2020-07-07 10:12       ` Ahmed S. Darwish
2020-07-07 12:47         ` Peter Zijlstra
2020-06-30  5:44   ` [PATCH v3 02/20] seqlock: Properly format kernel-doc code samples Ahmed S. Darwish
2020-06-30  5:44   ` [PATCH v3 03/20] seqlock: Add missing kernel-doc annotations Ahmed S. Darwish
2020-07-20 15:55 ` [PATCH v4 00/24] seqlock: Extend seqcount API with associated locks Ahmed S. Darwish
2020-07-20 15:55   ` [PATCH v4 01/24] Documentation: locking: Describe seqlock design and usage Ahmed S. Darwish
2020-07-21  1:35     ` Steven Rostedt
2020-07-21  1:37       ` Steven Rostedt
2020-07-21  5:34       ` Ahmed S. Darwish
2020-07-21  1:44     ` Steven Rostedt
2020-07-21  1:51       ` Steven Rostedt
2020-07-21  7:15         ` Ahmed S. Darwish
2020-07-20 15:55   ` [PATCH v4 02/24] seqlock: Properly format kernel-doc code samples Ahmed S. Darwish
2020-07-20 15:55   ` [PATCH v4 03/24] seqlock: seqcount_t latch: End read sections with read_seqcount_retry() Ahmed S. Darwish
2020-07-20 15:55   ` [PATCH v4 05/24] seqlock: Add kernel-doc for seqcount_t and seqlock_t APIs Ahmed S. Darwish
2020-07-20 16:49   ` [PATCH v4 00/24] seqlock: Extend seqcount API with associated locks Eric Biggers
2020-07-20 17:33     ` Ahmed S. Darwish

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200706211659.GA5551@worktop.programming.kicks-ass.net \
    --to=peterz@infradead.org \
    --cc=a.darwish@linutronix.de \
    --cc=bigeasy@linutronix.de \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mingo@redhat.com \
    --cc=paulmck@kernel.org \
    --cc=rostedt@goodmis.org \
    --cc=tglx@linutronix.de \
    --cc=will@kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-Doc Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-doc/0 linux-doc/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-doc linux-doc/ https://lore.kernel.org/linux-doc \
		linux-doc@vger.kernel.org
	public-inbox-index linux-doc

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-doc


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git