In the past, we did some efforts to ensure that almost all files under
Documentation/*.txt could be built with Sphinx.
Some regressions happened there (and some new files got added).
Fix those files in order to allow them to be able to build with Sphinx.
The changes on this series are trivial, adding the minimum stuff to allow
building those files with sphinx-build with no warnings and to make the
contents minimally consistent with other documentation files.
Mauro Carvalho Chehab (8):
docs: DMA-API-HOWTO: add a missing "="
docs: atomic_bitops.txt: add a title for this document
docs: clearing-warn-once.txt: add a title for this document
docs: ntb.txt: use Sphinx notation for the two ascii figures
docs: unaligned-memory-access.txt: use a lowercase title
docs: video-output.txt: convert it to ReST format
docs: ntb.txt: add blank lines to clean up some Sphinx warnings
docs: speculation.txt: mark example blocks as such
Documentation/DMA-API-HOWTO.txt | 2 +-
Documentation/atomic_bitops.txt | 6 +--
Documentation/clearing-warn-once.txt | 2 +
Documentation/ntb.txt | 14 ++++--
Documentation/speculation.txt | 8 ++--
Documentation/unaligned-memory-access.txt | 2 +-
Documentation/video-output.txt | 52 +++++++++++------------
7 files changed, 47 insertions(+), 39 deletions(-)
--
2.20.1
In order to make it to build with Sphinx, we need to fix the
notation for two ascii artwork.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/ntb.txt | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/Documentation/ntb.txt b/Documentation/ntb.txt
index a043854d28df..344a075f81f5 100644
--- a/Documentation/ntb.txt
+++ b/Documentation/ntb.txt
@@ -41,9 +41,10 @@ mainly used to perform the proper memory window initialization. Typically
there are two types of memory window interfaces supported by the NTB API:
inbound translation configured on the local ntb port and outbound translation
configured by the peer, on the peer ntb port. The first type is
-depicted on the next figure
+depicted on the next figure::
+
+ Inbound translation:
-Inbound translation:
Memory: Local NTB Port: Peer NTB Port: Peer MMIO:
____________
| dma-mapped |-ntb_mw_set_trans(addr) |
@@ -58,9 +59,10 @@ maps corresponding outbound memory window so to have access to the shared
memory region.
The second type of interface, that implies the shared windows being
-initialized by a peer device, is depicted on the figure:
+initialized by a peer device, is depicted on the figure::
+
+ Outbound translation:
-Outbound translation:
Memory: Local NTB Port: Peer NTB Port: Peer MMIO:
____________ ______________
| dma-mapped | | | MW base addr |<== memory-mapped IO
--
2.20.1
This document misses a title. Add it, in order to follow
the documentation standard.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/clearing-warn-once.txt | 2 ++
1 file changed, 2 insertions(+)
diff --git a/Documentation/clearing-warn-once.txt b/Documentation/clearing-warn-once.txt
index 5b1f5d547be1..4aa938262d0e 100644
--- a/Documentation/clearing-warn-once.txt
+++ b/Documentation/clearing-warn-once.txt
@@ -1,3 +1,5 @@
+Clearing WARN_ONCE
+------------------
WARN_ONCE / WARN_ON_ONCE only print a warning once.
--
2.20.1
The === line is shorter than the section title.
As this will generate a warning with rst build, fix it.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/DMA-API-HOWTO.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt
index 1a721d0f35c8..db48c6fd3162 100644
--- a/Documentation/DMA-API-HOWTO.txt
+++ b/Documentation/DMA-API-HOWTO.txt
@@ -147,7 +147,7 @@ networking subsystems make sure that the buffers they use are valid
for you to DMA from/to.
DMA addressing capabilities
-==========================
+===========================
By default, the kernel assumes that your device can address 32-bits of DMA
addressing. For a 64-bit capable device, this needs to be increased, and for
--
2.20.1
Identify the example blocks there, in order to avoid Sphinx
warnings.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/speculation.txt | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/speculation.txt b/Documentation/speculation.txt
index e9e6cbae2841..50d7ea857cff 100644
--- a/Documentation/speculation.txt
+++ b/Documentation/speculation.txt
@@ -17,7 +17,7 @@ observed to extract secret information.
For example, in the presence of branch prediction, it is possible for bounds
checks to be ignored by code which is speculatively executed. Consider the
-following code:
+following code::
int load_array(int *array, unsigned int index)
{
@@ -27,7 +27,7 @@ following code:
return array[index];
}
-Which, on arm64, may be compiled to an assembly sequence such as:
+Which, on arm64, may be compiled to an assembly sequence such as::
CMP <index>, #MAX_ARRAY_ELEMS
B.LT less
@@ -44,7 +44,7 @@ microarchitectural state which can be subsequently measured.
More complex sequences involving multiple dependent memory accesses may
result in sensitive information being leaked. Consider the following
-code, building on the prior example:
+code, building on the prior example::
int load_dependent_arrays(int *arr1, int *arr2, int index)
{
@@ -77,7 +77,7 @@ A call to array_index_nospec(index, size) returns a sanitized index
value that is bounded to [0, size) even under cpu speculation
conditions.
-This can be used to protect the earlier load_array() example:
+This can be used to protect the earlier load_array() example::
int load_array(int *array, unsigned int index)
{
--
2.20.1
In order to make it easier to parse and produce the right output,
add some extra blank lines.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/ntb.txt | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/ntb.txt b/Documentation/ntb.txt
index 344a075f81f5..074a423c853c 100644
--- a/Documentation/ntb.txt
+++ b/Documentation/ntb.txt
@@ -77,11 +77,13 @@ outbound memory window so to have access to the shared memory region.
As one can see the described scenarios can be combined in one portable
algorithm.
+
Local device:
1) Allocate memory for a shared window
2) Initialize memory window by translated address of the allocated region
(it may fail if local memory window initialization is unsupported)
3) Send the translated address and memory window index to a peer device
+
Peer device:
1) Initialize memory window with retrieved address of the allocated
by another device memory region (it may fail if peer memory window
@@ -90,6 +92,7 @@ algorithm.
In accordance with this scenario, the NTB Memory Window API can be used as
follows:
+
Local device:
1) ntb_mw_count(pidx) - retrieve number of memory ranges, which can
be allocated for memory windows between local device and peer device
@@ -105,6 +108,7 @@ follows:
5) Send translated base address (usually together with memory window
number) to the peer device using, for instance, scratchpad or message
registers.
+
Peer device:
1) ntb_peer_mw_set_trans(pidx, midx) - try to set received from other
device (related to pidx) translated address for specified memory
--
2.20.1
This file doesn't follow the documentation style we use
within the Kernel. Fix it.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/video-output.txt | 52 +++++++++++++++++-----------------
1 file changed, 26 insertions(+), 26 deletions(-)
diff --git a/Documentation/video-output.txt b/Documentation/video-output.txt
index e517011be4f9..56d6fa2e2368 100644
--- a/Documentation/video-output.txt
+++ b/Documentation/video-output.txt
@@ -1,34 +1,34 @@
+Video Output Switcher Control
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Video Output Switcher Control
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 2006 [email protected]
+2006 [email protected]
The output sysfs class driver provides an abstract video output layer that
can be used to hook platform specific methods to enable/disable video output
device through common sysfs interface. For example, on my IBM ThinkPad T42
laptop, The ACPI video driver registered its output devices and read/write
-method for 'state' with output sysfs class. The user interface under sysfs is:
+method for 'state' with output sysfs class. The user interface under sysfs is::
-linux:/sys/class/video_output # tree .
-.
-|-- CRT0
-| |-- device -> ../../../devices/pci0000:00/0000:00:01.0
-| |-- state
-| |-- subsystem -> ../../../class/video_output
-| `-- uevent
-|-- DVI0
-| |-- device -> ../../../devices/pci0000:00/0000:00:01.0
-| |-- state
-| |-- subsystem -> ../../../class/video_output
-| `-- uevent
-|-- LCD0
-| |-- device -> ../../../devices/pci0000:00/0000:00:01.0
-| |-- state
-| |-- subsystem -> ../../../class/video_output
-| `-- uevent
-`-- TV0
- |-- device -> ../../../devices/pci0000:00/0000:00:01.0
- |-- state
- |-- subsystem -> ../../../class/video_output
- `-- uevent
+ linux:/sys/class/video_output # tree .
+ .
+ |-- CRT0
+ | |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+ | |-- state
+ | |-- subsystem -> ../../../class/video_output
+ | `-- uevent
+ |-- DVI0
+ | |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+ | |-- state
+ | |-- subsystem -> ../../../class/video_output
+ | `-- uevent
+ |-- LCD0
+ | |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+ | |-- state
+ | |-- subsystem -> ../../../class/video_output
+ | `-- uevent
+ `-- TV0
+ |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+ |-- state
+ |-- subsystem -> ../../../class/video_output
+ `-- uevent
--
2.20.1
As all other titles at the documentation, use lower case
for its title.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/unaligned-memory-access.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/unaligned-memory-access.txt b/Documentation/unaligned-memory-access.txt
index 51b4ff031586..1ee82419d8aa 100644
--- a/Documentation/unaligned-memory-access.txt
+++ b/Documentation/unaligned-memory-access.txt
@@ -1,5 +1,5 @@
=========================
-UNALIGNED MEMORY ACCESSES
+Unaligned Memory Accesses
=========================
:Author: Daniel Drake <[email protected]>,
--
2.20.1
This document misses a title. Add it, in order to follow
the documentation standard.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/atomic_bitops.txt | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/atomic_bitops.txt b/Documentation/atomic_bitops.txt
index be70b32c95d9..093cdaefdb37 100644
--- a/Documentation/atomic_bitops.txt
+++ b/Documentation/atomic_bitops.txt
@@ -1,6 +1,6 @@
-
-On atomic bitops.
-
+=============
+Atomic bitops
+=============
While our bitmap_{}() functions are non-atomic, we have a number of operations
operating on single bits in a bitmap that are atomic.
--
2.20.1
On Wed, 10 Apr 2019 06:56:19 -0300
Mauro Carvalho Chehab <[email protected]> wrote:
> In the past, we did some efforts to ensure that almost all files under
> Documentation/*.txt could be built with Sphinx.
>
> Some regressions happened there (and some new files got added).
> Fix those files in order to allow them to be able to build with Sphinx.
>
> The changes on this series are trivial, adding the minimum stuff to allow
> building those files with sphinx-build with no warnings and to make the
> contents minimally consistent with other documentation files.
I've applied this set, thanks.
jon
Mauro Carvalho Chehab <[email protected]> wrote:
> In the past, we did some efforts to ensure that almost all files under
> Documentation/*.txt could be built with Sphinx.
Would recommend a URL. Presumably this: http://www.sphinx-doc.org
David
Am 12.04.19 um 12:21 schrieb David Howells:
> Mauro Carvalho Chehab <[email protected]> wrote:
>
>> In the past, we did some efforts to ensure that almost all files under
>> Documentation/*.txt could be built with Sphinx.
>
> Would recommend a URL. Presumably this: http://www.sphinx-doc.org
I recommend the Sphinx reStructuredText Primer
- https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
Which is already named in our 'How to write kernel documentation' introduction
- https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
-- Markus --
Markus Heiser <[email protected]> wrote:
> Which is already named in our 'How to write kernel documentation' introduction
>
> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
This should really be in Documentation/ directory.
David
Am 12.04.19 um 14:19 schrieb David Howells:
> Markus Heiser <[email protected]> wrote:
>
>> Which is already named in our 'How to write kernel documentation' introduction
>>
>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
>
> This should really be in Documentation/ directory.
>
I agree with you, it is a kind of information hiding. If you know proper
places, please send a patch to Jon.
-- Markus --
On Fri, 12 Apr 2019, David Howells <[email protected]> wrote:
> Markus Heiser <[email protected]> wrote:
>
>> Which is already named in our 'How to write kernel documentation' introduction
>>
>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
>
> This should really be in Documentation/ directory.
It is. Documentation/doc-guide/sphinx.rst.
Just double checking, you do know that all of [1] is generated from
Documentation/ using 'make html'?
BR,
Jani.
[1] https://www.kernel.org/doc/html/latest/
--
Jani Nikula, Intel Open Source Graphics Center
On Fri, 12 Apr 2019 14:34:25 +0200
Markus Heiser <[email protected]> wrote:
> Am 12.04.19 um 14:19 schrieb David Howells:
> > Markus Heiser <[email protected]> wrote:
> >
> >> Which is already named in our 'How to write kernel documentation' introduction
> >>
> >> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
> >
> > This should really be in Documentation/ directory.
> >
>
> I agree with you, it is a kind of information hiding. If you know proper
> places, please send a patch to Jon.
As Jani pointed out, it's in Documentation/doc-guide.
If you're saying it should be in the top level, I kind of disagree.
Documentation/ is an exercise in hiding information by placing it in the
middle of 200 other, unrelated files. We've made some progress on that,
and I would like to continue to do so.
Thanks,
jon
Am 12.04.19 um 17:39 schrieb Jonathan Corbet:
> On Fri, 12 Apr 2019 14:34:25 +0200
> Markus Heiser <[email protected]> wrote:
>
>> Am 12.04.19 um 14:19 schrieb David Howells:
>>> Markus Heiser <[email protected]> wrote:
>>>
>>>> Which is already named in our 'How to write kernel documentation' introduction
>>>>
>>>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
>>>
>>> This should really be in Documentation/ directory.
>>>
>>
>> I agree with you, it is a kind of information hiding. If you know proper
>> places, please send a patch to Jon.
>
> As Jani pointed out, it's in Documentation/doc-guide.
>
> If you're saying it should be in the top level, I kind of disagree.
> Documentation/ is an exercise in hiding information by placing it in the
> middle of 200 other, unrelated files. We've made some progress on that,
> and I would like to continue to do so.
For those who are new and are willing to document, it migth be a good idea
to have a simple Documentation/README.txt with a link to doc-guide?
Just a few words, I find with my editor, this is what I find often helpful
when I'am new to a project.
-- Markus --