Prepare files under Documentation/*.txt to build with Sphinx
Subsystems (4)
cover Prepare files under Documentation/*.txt to build with Sphinx
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(-)
Signature · 1 line
2.20.1
PATCH 2/8 docs: atomic_bitops.txt: add a title for this document
This document misses a title. Add it, in order to follow the documentation standard.
--- Documentation/atomic_bitops.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/atomic_bitops.txt +3 -3
@@ -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.
Signature · 1 line
2.20.1
PATCH 5/8 docs: unaligned-memory-access.txt: use a lowercase title
In reply to Mauro Carvalho ChehabAs all other titles at the documentation, use lower case for its title.
--- Documentation/unaligned-memory-access.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/unaligned-memory-access.txt +1 -1
@@ -1,5 +1,5 @@ ========================= -UNALIGNED MEMORY ACCESSES +Unaligned Memory Accesses ========================= :Author: Daniel Drake <[email protected]>,
Signature · 1 line
2.20.1
PATCH 7/8 docs: ntb.txt: add blank lines to clean up some Sphinx warnings
In reply to Mauro Carvalho ChehabIn order to make it easier to parse and produce the right output, add some extra blank lines.
--- Documentation/ntb.txt | 4 ++++ 1 file changed, 4 insertions(+)
Documentation/ntb.txt +4 -0
@@ -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
Signature · 1 line
2.20.1
PATCH 8/8 docs: speculation.txt: mark example blocks as such
In reply to Mauro Carvalho ChehabIdentify the example blocks there, in order to avoid Sphinx warnings.
--- Documentation/speculation.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/speculation.txt +4 -4
@@ -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) {
Signature · 1 line
2.20.1
PATCH 4/8 docs: ntb.txt: use Sphinx notation for the two ascii figures
In reply to Mauro Carvalho ChehabIn order to make it to build with Sphinx, we need to fix the notation for two ascii artwork.
--- Documentation/ntb.txt | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-)
Documentation/ntb.txt +6 -4
@@ -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
Signature · 1 line
2.20.1
PATCH 6/8 docs: video-output.txt: convert it to ReST format
In reply to Mauro Carvalho ChehabThis file doesn't follow the documentation style we use within the Kernel. Fix it.
--- Documentation/video-output.txt | 52 +++++++++++++++++----------------- 1 file changed, 26 insertions(+), 26 deletions(-)
Documentation/video-output.txt +26 -26
@@ -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
Signature · 1 line
2.20.1
PATCH 1/8 docs: DMA-API-HOWTO: add a missing "="
In reply to Mauro Carvalho ChehabThe === line is shorter than the section title.
As this will generate a warning with rst build, fix it.
--- Documentation/DMA-API-HOWTO.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/DMA-API-HOWTO.txt +1 -1
@@ -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
Signature · 1 line
2.20.1
PATCH 3/8 docs: clearing-warn-once.txt: add a title for this document
In reply to Mauro Carvalho ChehabThis document misses a title. Add it, in order to follow the documentation standard.
--- Documentation/clearing-warn-once.txt | 2 ++ 1 file changed, 2 insertions(+)
Documentation/clearing-warn-once.txt +2 -0
@@ -1,3 +1,5 @@ +Clearing WARN_ONCE +------------------ WARN_ONCE / WARN_ON_ONCE only print a warning once.
Signature · 1 line
2.20.1
Quoted 9 lines · On Wed, 10 Apr 2019 06:56:19 -0300 Mauro Carvalho Chehab…
In the past, we did some efforts to ensure that almost all files under
Documentation/*.txtcould 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
David Howells
maintainerQuoted 2 lines · Mauro Carvalho Chehab
In the past, we did some efforts to ensure that almost all files under
Documentation/*.txtcould 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:
Quoted 6 lines
Quoted 2 lines · Mauro Carvalho Chehab
In the past, we did some efforts to ensure that almost all files under
Documentation/*.txtcould 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 --
David Howells
maintainerQuoted 3 lines · Markus Heiser
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:
Quoted 8 lines
Quoted 3 lines · Markus Heiser
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 --
Quoted 7 lines · David Howells
Quoted 3 lines · Markus Heiser
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/
Signature · 1 line
Jani Nikula, Intel Open Source Graphics Center
Jonathan Corbet
maintainerQuoted 5 lines · On Fri, 12 Apr 2019 14:34:25 +0200 Markus Heiser <[email protected]>…
Am 12.04.19 um 14:19 schrieb David Howells:
Quoted 4 lines
Quoted 2 lines · Markus Heiser
Which is already named in our 'How to write kernel documentation' introduction
Quoted 7 lines
Quoted 4 lines
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:
Quoted 16 lines
Quoted 5 lines · On Fri, 12 Apr 2019 14:34:25 +0200 Markus Heiser <[email protected]>…
Am 12.04.19 um 14:19 schrieb David Howells:
Quoted 4 lines
Quoted 2 lines · Markus Heiser
Which is already named in our 'How to write kernel documentation' introduction
Quoted 7 lines
Quoted 4 lines
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.
Quoted 6 lines
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 --