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 {
