sysfs-pci and sysfs-tagging were mis-filed: their locations within
Documentation/ implied that they were related to file systems. Actually,
each topic is about a very specific *use* of sysfs, and sysfs *happens*
to be a (virtual) filesystem, so this is not really the right place.
It's jarring to be reading about filesystems in general and then come
across these specific details about PCI, and tagging...and then back to
general filesystems again.
Move sysfs-pci to PCI, and move sysfs-tagging to networking. (Thanks to
Jonathan Corbet for coming up with the final locations.)
Signed-off-by: John Hubbard <jhubbard@nvidia.com>
Link: https://lore.kernel.org/r/20201009070128.118639-1-jhubbard@nvidia.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are behavioural requirements on the seq_file next() function in
terms of how it updates *pos at end-of-file, and these are now enforced
by a warning.
I was recently attempting to justify the reason this was needed, and
couldn't remember the details, and didn't find them in the
documentation.
So I re-read the code until I understood it again, and updated the
documentation to match.
I also enhanced the text about SEQ_START_TOKEN as it seemed potentially
misleading.
Cc: Vasily Averin <vvs@virtuozzo.com>
Signed-off-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/87eemqiazh.fsf@notabene.neil.brown.name
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Following the structure used in sysctl/kernel.rst, this updates
abi.rst to use ReStructured Text more fully and updates the entries to
match current kernels:
* the list of files is now the table of contents;
* links are used to point to other documentation and other sections;
* all the existing entries are no longer present, so this removes
them;
* document vsyscall32.
Mentions of the kernel version are dropped. Since the document is
entirely rewritten, I've replaced the copyright statement.
Signed-off-by: Stephen Kitt <steve@sk2.org>
Link: https://lore.kernel.org/r/20200917072123.8847-1-steve@sk2.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Following the structure used in sysctl/kernel.rst, this updates
abi.rst to use ReStructured Text more fully and updates the entries to
match current kernels:
* the list of files is now the table of contents;
* links are used to point to other documentation and other sections;
* all the existing entries are no longer present, so this removes
them;
* document vsyscall32.
Mentions of the kernel version are dropped. Since the document is
entirely rewritten, I've replaced the copyright statement.
Signed-off-by: Stephen Kitt <steve@sk2.org>
Link: https://lore.kernel.org/r/20200911190152.29730-1-steve@sk2.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Subroutine dump_struct uses type attributes to check if the struct
syntax is valid. Then, it removes all attributes before using it for
output. `____cacheline_aligned` is an attribute that is
not included in both steps. Add it, since it is used by kernel structs.
Based on previous patch to add ____cacheline_aligned_in_smp.
Motivated by patches to reorder this attribute to before the
variable name. Whilst we could do that in all cases, that would
be a massive change and it is more common in the kernel to place
this particular attribute after the variable name. A quick grep
suggests approximately 400 instances of which 341 have this
attribute just before a semicolon and hence after the variable name.
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Cc: Lee Jones <lee.jones@linaro.org>
Link: https://lore.kernel.org/r/20200910185415.653139-1-jic23@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Document the notes file in sysfs as the running vmlinux's .note section
in binary format. Hopefully this helps someone like me realize the
kernel exposes the note section in sysfs in the future. Take the date
from when the file was introduced. It's been a while so presumably this
is stable and not testing material.
Signed-off-by: Stephen Boyd <swboyd@chromium.org>
Link: https://lore.kernel.org/r/20200909063752.931283-1-swboyd@chromium.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Cross-referencing to other documentation pages is possible using the
:doc:`doc-file` directive from Sphinx.
Add automatic markup for references to other documentation pages in the
format Documentation/subfolder/doc-file.rst (the extension being
optional).
This requires that the path be passed all the way from the Documentation
folder, which can be longer than passing a relative path through the
:doc: directive, but avoids the markup, making the text cleaner when
read in plain text.
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
Link: https://lore.kernel.org/r/20200911133339.327721-3-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The automarkup script previously matched expressions and substituted
them with markup to enable automatic cross-reference all in the same
function.
Split the expression matching iteration and the markup substitution into
different functions to make it easier to add new regular expressions and
functions to treat each of them.
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
Link: https://lore.kernel.org/r/20200911133339.327721-2-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are two broken references at submitting-patches.rst:
Documentation/process/submitting-patches.rst:240: WARNING: undefined label: security-bugs (if the link has no caption the label must precede a section header)
Documentation/process/submitting-patches.rst:336: WARNING: undefined label: documentation/process/email-clients.rst (if the link has no caption the label must precede a section header)
Those are due to some recent renames and file moves.
It turns that maintaining :ref: is currently harder than using
:doc:, as we now have a script to help checking such references.
So, replace :ref: to :doc: there, making them to point to the
current file name.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/3ba405f579cf35ef2b39dd210d8ad46adc79f0ad.1599660067.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are some warnings:
Documentation/virt/kvm/api.rst:4354: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/virt/kvm/api.rst:4358: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/virt/kvm/api.rst:4363: WARNING: Definition list ends without a blank line; unexpected unindent.
Produced by the lack of identation on a single line. That
caused the literal block to end prematurely.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/b6b3679b6c2329dc9b16d397c289b5ade0184c63.1599660067.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix those warnings:
Documentation/watch_queue.rst:108: WARNING: Inline literal start-string without end-string.
Documentation/watch_queue.rst:108: WARNING: Inline emphasis start-string without end-string.
Documentation/watch_queue.rst:108: WARNING: Inline emphasis start-string without end-string.
Documentation/watch_queue.rst:108: WARNING: Inline emphasis start-string without end-string.
Documentation/watch_queue.rst:185: WARNING: Inline literal start-string without end-string.
Documentation/watch_queue.rst:185: WARNING: Inline emphasis start-string without end-string.
Documentation/watch_queue.rst:184: WARNING: Inline emphasis start-string without end-string.
The problem here is that the ``notation`` doesn't accept
multi lines. So, replace it to a code block using:
::
notation
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/42706310c09a6b4588a1a41078207246ad1238fa.1599660067.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
