Re: [PATCH v2 3/4] Documentation/local_ops.txt: convert to ReST markup

[Jani Nikula]

On Fri, 25 Nov 2016, Mauro Carvalho Chehab  wrote:
> Em Fri, 25 Nov 2016 14:47:11 +0100
> "S. Fricke"  escreveu:
>
>> Hi Mauro,
>> 
>> I have a question about the "code-block" and "::". On which situation should
>> I use "code-block" and on which condition a "::"?
>> For now I have used "::" on small one, two or three liners, and "code-block"
>> for "example code" snippets or longer code segments.
>
> They're equivalent, but :: makes the file to look nicer if someone is
> reading the text file directly.
>
> There's one difference, though: right now, I guess we're disabling
> pygments. So, "::" is assuming "code-block:: none". The default can
> be changed inside a document by adding:
>
>   .. highlight:: c
>
> before using the first "::".
>
> That said, IMHO, pygments is crap :) Instead of painting the file with
> some random colors, Sphinx should instead be doing something useful,
> e. g. producing cross-references for data structures and functions.
>
> So, I wouldn't be using "highlight" there.

My rules of thumb:

Use "::" for anything that doesn't really benefit from highlighting,
especially short snippets, whether they have a pygments highlighter or
not.

Use ".. code-block:: ", e.g. ".. code-block:: c" for longer
code blocks that benefit from highlighting.

Do *not* use ".. highlight:: " unless you have a *lot* of
short snippets that *do* benefit from highlighting (so you can use "::"
and still get highlighting for them). Best avoided altogether.

BR,
Jani.



>
>
>> 
>> Thanks for a small clarification,
>> Silvio
>> 
>> > Em Fri, 25 Nov 2016 11:02:41 +0100
>> > Silvio Fricke  escreveu:
>> >   
>> > > ... and move to core-api folder.
>> > > 
>> > > Signed-off-by: Silvio Fricke 
>> > > ---
>> > >  Documentation/core-api/index.rst|   
>> > > 1 +-
>> > >  Documentation/local_ops.txt => Documentation/core-api/local_ops.rst | 
>> > > 275 +++
>> > >  2 files changed, 147 insertions(+), 129 deletions(-)
>> > > 
>> > > diff --git a/Documentation/core-api/index.rst 
>> > > b/Documentation/core-api/index.rst
>> > > index f3e5f5e..25b4e4a 100644
>> > > --- a/Documentation/core-api/index.rst
>> > > +++ b/Documentation/core-api/index.rst
>> > > @@ -9,6 +9,7 @@ Kernel and driver related documentation.
>> > >  
>> > > assoc_array
>> > > atomic_ops
>> > > +   local_ops
>> > > workqueue
>> > >  
>> > >  .. only::  subproject
>> > > diff --git a/Documentation/local_ops.txt 
>> > > b/Documentation/core-api/local_ops.rst
>> > > similarity index 55%
>> > > rename from Documentation/local_ops.txt
>> > > rename to Documentation/core-api/local_ops.rst
>> > > index 407576a..01f1880 100644
>> > > --- a/Documentation/local_ops.txt
>> > > +++ b/Documentation/core-api/local_ops.rst
>> > > @@ -1,191 +1,208 @@
>> > > - Semantics and Behavior of Local Atomic Operations
>> > >  
>> > > -Mathieu Desnoyers
>> > > +.. _local_ops:
>> > >  
>> > > +=
>> > > +Semantics and Behavior of Local Atomic Operations
>> > > +=
>> > >  
>> > > -This document explains the purpose of the local atomic 
>> > > operations, how
>> > > +:Author: Mathieu Desnoyers
>> > > +
>> > > +
>> > > +This document explains the purpose of the local atomic operations, how
>> > >  to implement them for any given architecture and shows how they can be 
>> > > used
>> > >  properly. It also stresses on the precautions that must be taken when 
>> > > reading
>> > >  those local variables across CPUs when the order of memory writes 
>> > > matters.
>> > >  
>> > > -Note that local_t based operations are not recommended for general 
>> > > kernel use.
>> > > -Please use the this_cpu operations instead unless there is really a 
>> > > special purpose.
>> > > -Most uses of local_t in the kernel have been replaced by this_cpu 
>> > > operations.
>> > > -this_cpu operations combine the relocation with the local_t like 
>> > > semantics in
>> > > -a single instruction and yield more compact and faster executing code.
>> > > +.. note::
>> > >  
>> > > +Note that ``local_t`` based operations are not recommended for 
>> > > general
>> > > +kernel use. Please use the ``this_cpu`` operations instead unless 
>> > > there is
>> > > +really a special purpose. Most uses of ``local_t`` in the kernel 
>> > > have been
>> > > +replaced by ``this_cpu`` operations. ``this_cpu`` operations 
>> > > combine the
>> > > +relocation with the ``local_t`` like semantics in a single 
>> > > instruction and
>> > > +yield more compact and faster executing code.
>> > >  
>> > > -* Purpose of local atomic operations
>> > > +
>> > > +Purpose of local atomic operations
>> > > +==
>> > >  
>> > >  Local atomic operations are meant to provide fast and highly 

Re: [PATCH v2 3/4] Documentation/local_ops.txt: convert to ReST markup

[Mauro Carvalho Chehab]

Em Fri, 25 Nov 2016 11:02:41 +0100
Silvio Fricke  escreveu:

> ... and move to core-api folder.
> 
> Signed-off-by: Silvio Fricke 
> ---
>  Documentation/core-api/index.rst|   1 +-
>  Documentation/local_ops.txt => Documentation/core-api/local_ops.rst | 275 
> +++
>  2 files changed, 147 insertions(+), 129 deletions(-)
> 
> diff --git a/Documentation/core-api/index.rst 
> b/Documentation/core-api/index.rst
> index f3e5f5e..25b4e4a 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -9,6 +9,7 @@ Kernel and driver related documentation.
>  
> assoc_array
> atomic_ops
> +   local_ops
> workqueue
>  
>  .. only::  subproject
> diff --git a/Documentation/local_ops.txt 
> b/Documentation/core-api/local_ops.rst
> similarity index 55%
> rename from Documentation/local_ops.txt
> rename to Documentation/core-api/local_ops.rst
> index 407576a..01f1880 100644
> --- a/Documentation/local_ops.txt
> +++ b/Documentation/core-api/local_ops.rst
> @@ -1,191 +1,208 @@
> -  Semantics and Behavior of Local Atomic Operations
>  
> - Mathieu Desnoyers
> +.. _local_ops:
>  
> +=
> +Semantics and Behavior of Local Atomic Operations
> +=
>  
> - This document explains the purpose of the local atomic operations, how
> +:Author: Mathieu Desnoyers
> +
> +
> +This document explains the purpose of the local atomic operations, how
>  to implement them for any given architecture and shows how they can be used
>  properly. It also stresses on the precautions that must be taken when reading
>  those local variables across CPUs when the order of memory writes matters.
>  
> -Note that local_t based operations are not recommended for general kernel 
> use.
> -Please use the this_cpu operations instead unless there is really a special 
> purpose.
> -Most uses of local_t in the kernel have been replaced by this_cpu operations.
> -this_cpu operations combine the relocation with the local_t like semantics in
> -a single instruction and yield more compact and faster executing code.
> +.. note::
>  
> +Note that ``local_t`` based operations are not recommended for general
> +kernel use. Please use the ``this_cpu`` operations instead unless there 
> is
> +really a special purpose. Most uses of ``local_t`` in the kernel have 
> been
> +replaced by ``this_cpu`` operations. ``this_cpu`` operations combine the
> +relocation with the ``local_t`` like semantics in a single instruction 
> and
> +yield more compact and faster executing code.
>  
> -* Purpose of local atomic operations
> +
> +Purpose of local atomic operations
> +==
>  
>  Local atomic operations are meant to provide fast and highly reentrant per 
> CPU
>  counters. They minimize the performance cost of standard atomic operations by
>  removing the LOCK prefix and memory barriers normally required to synchronize
>  across CPUs.
>  
> -Having fast per CPU atomic counters is interesting in many cases : it does 
> not
> +Having fast per CPU atomic counters is interesting in many cases: it does not
>  require disabling interrupts to protect from interrupt handlers and it 
> permits
>  coherent counters in NMI handlers. It is especially useful for tracing 
> purposes
>  and for various performance monitoring counters.
>  
>  Local atomic operations only guarantee variable modification atomicity wrt 
> the
>  CPU which owns the data. Therefore, care must taken to make sure that only 
> one
> -CPU writes to the local_t data. This is done by using per cpu data and making
> -sure that we modify it from within a preemption safe context. It is however
> -permitted to read local_t data from any CPU : it will then appear to be 
> written
> -out of order wrt other memory writes by the owner CPU.
> +CPU writes to the ``local_t`` data. This is done by using per cpu data and
> +making sure that we modify it from within a preemption safe context. It is
> +however permitted to read ``local_t`` data from any CPU: it will then appear 
> to
> +be written out of order wrt other memory writes by the owner CPU.
>  
>  
> -* Implementation for a given architecture
> +Implementation for a given architecture
> +===
>  
> -It can be done by slightly modifying the standard atomic operations : only
> +It can be done by slightly modifying the standard atomic operations: only
>  their UP variant must be kept. It typically means removing LOCK prefix (on
>  i386 and x86_64) and any SMP synchronization barrier. If the architecture 
> does
> -not have a different behavior between SMP and UP, including 
> asm-generic/local.h
> -in your architecture's local.h is sufficient.
> +not have a different behavior between SMP and UP, including
> +``asm-generic/local.h`` in 

Re: [PATCH v2 3/4] Documentation/local_ops.txt: convert to ReST markup

[Mauro Carvalho Chehab]

Em Fri, 25 Nov 2016 14:47:11 +0100
"S. Fricke"  escreveu:

> Hi Mauro,
> 
> I have a question about the "code-block" and "::". On which situation should
> I use "code-block" and on which condition a "::"?
> For now I have used "::" on small one, two or three liners, and "code-block"
> for "example code" snippets or longer code segments.

They're equivalent, but :: makes the file to look nicer if someone is
reading the text file directly.

There's one difference, though: right now, I guess we're disabling
pygments. So, "::" is assuming "code-block:: none". The default can
be changed inside a document by adding:

.. highlight:: c

before using the first "::".

That said, IMHO, pygments is crap :) Instead of painting the file with
some random colors, Sphinx should instead be doing something useful,
e. g. producing cross-references for data structures and functions.

So, I wouldn't be using "highlight" there.


> 
> Thanks for a small clarification,
> Silvio
> 
> > Em Fri, 25 Nov 2016 11:02:41 +0100
> > Silvio Fricke  escreveu:
> >   
> > > ... and move to core-api folder.
> > > 
> > > Signed-off-by: Silvio Fricke 
> > > ---
> > >  Documentation/core-api/index.rst|   
> > > 1 +-
> > >  Documentation/local_ops.txt => Documentation/core-api/local_ops.rst | 
> > > 275 +++
> > >  2 files changed, 147 insertions(+), 129 deletions(-)
> > > 
> > > diff --git a/Documentation/core-api/index.rst 
> > > b/Documentation/core-api/index.rst
> > > index f3e5f5e..25b4e4a 100644
> > > --- a/Documentation/core-api/index.rst
> > > +++ b/Documentation/core-api/index.rst
> > > @@ -9,6 +9,7 @@ Kernel and driver related documentation.
> > >  
> > > assoc_array
> > > atomic_ops
> > > +   local_ops
> > > workqueue
> > >  
> > >  .. only::  subproject
> > > diff --git a/Documentation/local_ops.txt 
> > > b/Documentation/core-api/local_ops.rst
> > > similarity index 55%
> > > rename from Documentation/local_ops.txt
> > > rename to Documentation/core-api/local_ops.rst
> > > index 407576a..01f1880 100644
> > > --- a/Documentation/local_ops.txt
> > > +++ b/Documentation/core-api/local_ops.rst
> > > @@ -1,191 +1,208 @@
> > > -  Semantics and Behavior of Local Atomic Operations
> > >  
> > > - Mathieu Desnoyers
> > > +.. _local_ops:
> > >  
> > > +=
> > > +Semantics and Behavior of Local Atomic Operations
> > > +=
> > >  
> > > - This document explains the purpose of the local atomic operations, how
> > > +:Author: Mathieu Desnoyers
> > > +
> > > +
> > > +This document explains the purpose of the local atomic operations, how
> > >  to implement them for any given architecture and shows how they can be 
> > > used
> > >  properly. It also stresses on the precautions that must be taken when 
> > > reading
> > >  those local variables across CPUs when the order of memory writes 
> > > matters.
> > >  
> > > -Note that local_t based operations are not recommended for general 
> > > kernel use.
> > > -Please use the this_cpu operations instead unless there is really a 
> > > special purpose.
> > > -Most uses of local_t in the kernel have been replaced by this_cpu 
> > > operations.
> > > -this_cpu operations combine the relocation with the local_t like 
> > > semantics in
> > > -a single instruction and yield more compact and faster executing code.
> > > +.. note::
> > >  
> > > +Note that ``local_t`` based operations are not recommended for 
> > > general
> > > +kernel use. Please use the ``this_cpu`` operations instead unless 
> > > there is
> > > +really a special purpose. Most uses of ``local_t`` in the kernel 
> > > have been
> > > +replaced by ``this_cpu`` operations. ``this_cpu`` operations combine 
> > > the
> > > +relocation with the ``local_t`` like semantics in a single 
> > > instruction and
> > > +yield more compact and faster executing code.
> > >  
> > > -* Purpose of local atomic operations
> > > +
> > > +Purpose of local atomic operations
> > > +==
> > >  
> > >  Local atomic operations are meant to provide fast and highly reentrant 
> > > per CPU
> > >  counters. They minimize the performance cost of standard atomic 
> > > operations by
> > >  removing the LOCK prefix and memory barriers normally required to 
> > > synchronize
> > >  across CPUs.
> > >  
> > > -Having fast per CPU atomic counters is interesting in many cases : it 
> > > does not
> > > +Having fast per CPU atomic counters is interesting in many cases: it 
> > > does not
> > >  require disabling interrupts to protect from interrupt handlers and it 
> > > permits
> > >  coherent counters in NMI handlers. It is especially useful for tracing 
> > > purposes
> > >  and for various performance monitoring counters.
> > >  
> > >  Local atomic operations only 

Re: [PATCH v2 3/4] Documentation/local_ops.txt: convert to ReST markup

[S. Fricke]

Hi Mauro,

I have a question about the "code-block" and "::". On which situation should
I use "code-block" and on which condition a "::"?
For now I have used "::" on small one, two or three liners, and "code-block"
for "example code" snippets or longer code segments.

Thanks for a small clarification,
Silvio

> Em Fri, 25 Nov 2016 11:02:41 +0100
> Silvio Fricke  escreveu:
> 
> > ... and move to core-api folder.
> > 
> > Signed-off-by: Silvio Fricke 
> > ---
> >  Documentation/core-api/index.rst|   1 
> > +-
> >  Documentation/local_ops.txt => Documentation/core-api/local_ops.rst | 275 
> > +++
> >  2 files changed, 147 insertions(+), 129 deletions(-)
> > 
> > diff --git a/Documentation/core-api/index.rst 
> > b/Documentation/core-api/index.rst
> > index f3e5f5e..25b4e4a 100644
> > --- a/Documentation/core-api/index.rst
> > +++ b/Documentation/core-api/index.rst
> > @@ -9,6 +9,7 @@ Kernel and driver related documentation.
> >  
> > assoc_array
> > atomic_ops
> > +   local_ops
> > workqueue
> >  
> >  .. only::  subproject
> > diff --git a/Documentation/local_ops.txt 
> > b/Documentation/core-api/local_ops.rst
> > similarity index 55%
> > rename from Documentation/local_ops.txt
> > rename to Documentation/core-api/local_ops.rst
> > index 407576a..01f1880 100644
> > --- a/Documentation/local_ops.txt
> > +++ b/Documentation/core-api/local_ops.rst
> > @@ -1,191 +1,208 @@
> > -Semantics and Behavior of Local Atomic Operations
> >  
> > -   Mathieu Desnoyers
> > +.. _local_ops:
> >  
> > +=
> > +Semantics and Behavior of Local Atomic Operations
> > +=
> >  
> > -   This document explains the purpose of the local atomic operations, how
> > +:Author: Mathieu Desnoyers
> > +
> > +
> > +This document explains the purpose of the local atomic operations, how
> >  to implement them for any given architecture and shows how they can be used
> >  properly. It also stresses on the precautions that must be taken when 
> > reading
> >  those local variables across CPUs when the order of memory writes matters.
> >  
> > -Note that local_t based operations are not recommended for general kernel 
> > use.
> > -Please use the this_cpu operations instead unless there is really a 
> > special purpose.
> > -Most uses of local_t in the kernel have been replaced by this_cpu 
> > operations.
> > -this_cpu operations combine the relocation with the local_t like semantics 
> > in
> > -a single instruction and yield more compact and faster executing code.
> > +.. note::
> >  
> > +Note that ``local_t`` based operations are not recommended for general
> > +kernel use. Please use the ``this_cpu`` operations instead unless 
> > there is
> > +really a special purpose. Most uses of ``local_t`` in the kernel have 
> > been
> > +replaced by ``this_cpu`` operations. ``this_cpu`` operations combine 
> > the
> > +relocation with the ``local_t`` like semantics in a single instruction 
> > and
> > +yield more compact and faster executing code.
> >  
> > -* Purpose of local atomic operations
> > +
> > +Purpose of local atomic operations
> > +==
> >  
> >  Local atomic operations are meant to provide fast and highly reentrant per 
> > CPU
> >  counters. They minimize the performance cost of standard atomic operations 
> > by
> >  removing the LOCK prefix and memory barriers normally required to 
> > synchronize
> >  across CPUs.
> >  
> > -Having fast per CPU atomic counters is interesting in many cases : it does 
> > not
> > +Having fast per CPU atomic counters is interesting in many cases: it does 
> > not
> >  require disabling interrupts to protect from interrupt handlers and it 
> > permits
> >  coherent counters in NMI handlers. It is especially useful for tracing 
> > purposes
> >  and for various performance monitoring counters.
> >  
> >  Local atomic operations only guarantee variable modification atomicity wrt 
> > the
> >  CPU which owns the data. Therefore, care must taken to make sure that only 
> > one
> > -CPU writes to the local_t data. This is done by using per cpu data and 
> > making
> > -sure that we modify it from within a preemption safe context. It is however
> > -permitted to read local_t data from any CPU : it will then appear to be 
> > written
> > -out of order wrt other memory writes by the owner CPU.
> > +CPU writes to the ``local_t`` data. This is done by using per cpu data and
> > +making sure that we modify it from within a preemption safe context. It is
> > +however permitted to read ``local_t`` data from any CPU: it will then 
> > appear to
> > +be written out of order wrt other memory writes by the owner CPU.
> >  
> >  
> > -* Implementation for a given architecture
> > +Implementation for a given architecture
> > 

[PATCH v2 3/4] Documentation/local_ops.txt: convert to ReST markup

[Silvio Fricke]

... and move to core-api folder.

Signed-off-by: Silvio Fricke 
---
 Documentation/core-api/index.rst|   1 +-
 Documentation/local_ops.txt => Documentation/core-api/local_ops.rst | 275 
+++
 2 files changed, 147 insertions(+), 129 deletions(-)

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index f3e5f5e..25b4e4a 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -9,6 +9,7 @@ Kernel and driver related documentation.
 
assoc_array
atomic_ops
+   local_ops
workqueue
 
 .. only::  subproject
diff --git a/Documentation/local_ops.txt b/Documentation/core-api/local_ops.rst
similarity index 55%
rename from Documentation/local_ops.txt
rename to Documentation/core-api/local_ops.rst
index 407576a..01f1880 100644
--- a/Documentation/local_ops.txt
+++ b/Documentation/core-api/local_ops.rst
@@ -1,191 +1,208 @@
-Semantics and Behavior of Local Atomic Operations
 
-   Mathieu Desnoyers
+.. _local_ops:
 
+=
+Semantics and Behavior of Local Atomic Operations
+=
 
-   This document explains the purpose of the local atomic operations, how
+:Author: Mathieu Desnoyers
+
+
+This document explains the purpose of the local atomic operations, how
 to implement them for any given architecture and shows how they can be used
 properly. It also stresses on the precautions that must be taken when reading
 those local variables across CPUs when the order of memory writes matters.
 
-Note that local_t based operations are not recommended for general kernel use.
-Please use the this_cpu operations instead unless there is really a special 
purpose.
-Most uses of local_t in the kernel have been replaced by this_cpu operations.
-this_cpu operations combine the relocation with the local_t like semantics in
-a single instruction and yield more compact and faster executing code.
+.. note::
 
+Note that ``local_t`` based operations are not recommended for general
+kernel use. Please use the ``this_cpu`` operations instead unless there is
+really a special purpose. Most uses of ``local_t`` in the kernel have been
+replaced by ``this_cpu`` operations. ``this_cpu`` operations combine the
+relocation with the ``local_t`` like semantics in a single instruction and
+yield more compact and faster executing code.
 
-* Purpose of local atomic operations
+
+Purpose of local atomic operations
+==
 
 Local atomic operations are meant to provide fast and highly reentrant per CPU
 counters. They minimize the performance cost of standard atomic operations by
 removing the LOCK prefix and memory barriers normally required to synchronize
 across CPUs.
 
-Having fast per CPU atomic counters is interesting in many cases : it does not
+Having fast per CPU atomic counters is interesting in many cases: it does not
 require disabling interrupts to protect from interrupt handlers and it permits
 coherent counters in NMI handlers. It is especially useful for tracing purposes
 and for various performance monitoring counters.
 
 Local atomic operations only guarantee variable modification atomicity wrt the
 CPU which owns the data. Therefore, care must taken to make sure that only one
-CPU writes to the local_t data. This is done by using per cpu data and making
-sure that we modify it from within a preemption safe context. It is however
-permitted to read local_t data from any CPU : it will then appear to be written
-out of order wrt other memory writes by the owner CPU.
+CPU writes to the ``local_t`` data. This is done by using per cpu data and
+making sure that we modify it from within a preemption safe context. It is
+however permitted to read ``local_t`` data from any CPU: it will then appear to
+be written out of order wrt other memory writes by the owner CPU.
 
 
-* Implementation for a given architecture
+Implementation for a given architecture
+===
 
-It can be done by slightly modifying the standard atomic operations : only
+It can be done by slightly modifying the standard atomic operations: only
 their UP variant must be kept. It typically means removing LOCK prefix (on
 i386 and x86_64) and any SMP synchronization barrier. If the architecture does
-not have a different behavior between SMP and UP, including asm-generic/local.h
-in your architecture's local.h is sufficient.
+not have a different behavior between SMP and UP, including
+``asm-generic/local.h`` in your architecture's ``local.h`` is sufficient.
 
-The local_t type is defined as an opaque signed long by embedding an
-atomic_long_t inside a structure. This is made so a cast from this type to a
-long fails. The definition looks like :
+The ``local_t`` type is defined as an opaque ``signed long`` by embedding an
+``atomic_long_t``