Make declaration type determination more robust.

When scripts/kernel-doc is deciding if some kernel-doc notation
contains an enum, a struct, a union, a typedef, or a function,
it does a pattern match on the beginning of the string, looking
for a match with one of "struct", "union", "enum", or "typedef",
and otherwise defaults to a function declaration type.
However, if a function or a function-like macro has a name that
begins with "struct" (e.g., struct_size()), then kernel-doc
incorrectly decides that this is a struct declaration.

Fix this by looking for the declaration type keywords having an
ending word boundary (\b), so that "struct_size" will not match
a struct declaration.

I compared lots of html before/after output from core-api, driver-api,
and networking.  There were no differences in any of the files that
I checked.
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Acked-by: NJani Nikula <jani.nikula@intel.com>
Tested-by: NKees Cook <keescook@chromium.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

There was a typo in adding-syscalls.rst that could mislead developers
to add a C filename in a makefile instead of an object filename.
This error, while not keeping developers from contributing could slow
the development process down by introducing build errors.
Signed-off-by: NGuillaume Dore <corwin@poussif.eu>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Remove "manual" table of contents and leave only the ReST tag so that
Sphinx will take care of TOC generation.
Signed-off-by: NMike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

When converting from text to rst, the kobjects section and its sole
subsection about device tree nodes were coalesced into a single section,
yielding an inconsistent result.

Remove all references to kobjects, as
  1. Device tree object pointers are not compatible to kobject pointers
     (the former may embed the latter, though), and
  2. there are no printk formats defined for kobject types.

Update the vsprintf() source code comments to match the above.

Fixes: b3ed2321 ("doc: convert printk-formats.txt to rst")
Signed-off-by: NGeert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The existing wording implies that the use of spin_unlock whilst irqs are
disabled might trigger a reschedule. However the preemptible() test in
preempt_schedule will prevent a reschedule if irqs are disabled.

Lets improve the clarity of this wording to change the example from
spin_unlock to cond_resched() and cond_resched_lock() as these are
functions that will trigger a reschedule if the preempt count is 0 without
testing that irqs are disabled.

Also remove the 'Last Updated' line as this is not up to date and better
tracked via GIT.
Signed-off-by: NAndrew Murray <andrew.murray@arm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Commit ef548c55 ("dm flakey: introduce "error_writes" feature")
added the ability to dm flakey to error out writes in contrast to
silently dropping it with 'drop_writes'. Unfortunately this feature
is not currently documented and one has to be either familiar with the
source code of dm flakey or check out xfstests sources to know of
this parameter. So document it.
Signed-off-by: NNikolay Borisov <nborisov@suse.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This patch fixes a couple of punctuation nits which can make the document
more correct and readable.

Also missing "()" are added to some function references for consistency.
Signed-off-by: NJohn Garry <john.garry@huawei.com>
Acked-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add the full text of the ISC license to the kernel tree. It was copied
directly from:

   https://spdx.org/licenses/ISC.html

With the mention of "ISC" in the warranty disclaimer replaced with
"THE AUTHOR" as done in the ISC license headers used in the ath10k and
brcmfmac wifi drivers.

Cc: Kalle Valo <kvalo@codeaurora.org>
Signed-off-by: NHans de Goede <hdegoede@redhat.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The only reason we have the CDDL-1.0 license text around is for some
dual-licensed files from virtualbox. New code should not use this license.

Add a note about this and change the example tag to be dual-licensed.
Signed-off-by: NHans de Goede <hdegoede@redhat.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Let's document the magic a bit, especially why device_hotplug_lock is
required when adding/removing memory and how it all play together with
requests to online/offline memory from user space.

[ rppt: moved the text to Documentation/core-api/memory-hotplug.rst ]

Link: http://lkml.kernel.org/r/20180925091457.28651-7-david@redhat.comSigned-off-by: NDavid Hildenbrand <david@redhat.com>
Reviewed-by: NPavel Tatashin <pavel.tatashin@microsoft.com>
Reviewed-by: NRashmica Gupta <rashmica.g@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Michal Hocko <mhocko@suse.com>
Cc: Balbir Singh <bsingharora@gmail.com>
Cc: Benjamin Herrenschmidt <benh@kernel.crashing.org>
Cc: Boris Ostrovsky <boris.ostrovsky@oracle.com>
Cc: Dan Williams <dan.j.williams@intel.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Haiyang Zhang <haiyangz@microsoft.com>
Cc: Heiko Carstens <heiko.carstens@de.ibm.com>
Cc: John Allen <jallen@linux.vnet.ibm.com>
Cc: Joonsoo Kim <iamjoonsoo.kim@lge.com>
Cc: Juergen Gross <jgross@suse.com>
Cc: Kate Stewart <kstewart@linuxfoundation.org>
Cc: "K. Y. Srinivasan" <kys@microsoft.com>
Cc: Len Brown <lenb@kernel.org>
Cc: Martin Schwidefsky <schwidefsky@de.ibm.com>
Cc: Mathieu Malaterre <malat@debian.org>
Cc: Michael Ellerman <mpe@ellerman.id.au>
Cc: Michael Neuling <mikey@neuling.org>
Cc: Nathan Fontenot <nfont@linux.vnet.ibm.com>
Cc: Oscar Salvador <osalvador@suse.de>
Cc: Paul Mackerras <paulus@samba.org>
Cc: Philippe Ombredanne <pombredanne@nexb.com>
Cc: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Cc: "Rafael J. Wysocki" <rjw@rjwysocki.net>
Cc: Stephen Hemminger <sthemmin@microsoft.com>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Vlastimil Babka <vbabka@suse.cz>
Cc: YASUAKI ISHIMATSU <yasu.isimatu@gmail.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NMike Rapoport <rppt@linux.ibm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

to allow additions of new documentation about memory hotplug under the same
roof.
Signed-off-by: NMike Rapoport <rppt@linux.vnet.ibm.com>
Reviewed-by: NDavid Hildenbrand <david@redhat.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

My eyesight is not in good shape, which means that I have difficulty
reading the online Linux documentation.  Specifically, body text is
oddly small compared to list items and the contrast of various text
elements is too low for me to be able to see easily.

Therefore, alter the HTML theme overrides to make the text larger and
increase the contrast for better visibility, and trust the typeface
choices of the reader's browser.

For the PDF output, increase the text size, use a sans-serif typeface
for sans-serif text, and use a serif typeface for "roman" serif text.
Signed-off-by: NDarrick J. Wong <darrick.wong@oracle.com>
Acked-by: NDave Chinner <dchinner@redhat.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Current phrasing is ambiguous since it's unclear if attaching to a
children through PTRACE_TRACEME requires CAP_SYS_PTRACE. Rephrase the
sentence to make that clear.
Signed-off-by: NYves-Alexis Perez <corsac@corsac.net>
Acked-by: NKees Cook <keescook@chromium.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The memory hotplug notifier description is about kernel internals rather
than admin/user visible API. Place it appropriately.
Signed-off-by: NMike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The memory hotplug description in Documentation/memory-hotplug.txt is
already formatted as ReST and can be easily added to admin-guide/mm
section.

While on it, slightly update formatting to make it consistent with the
doc-guide.
Signed-off-by: NMike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

"FEFEK" was incorrectly used as acronym for "File Encryption Key
Encryption Key". This replaces all occurences with "FEKEK".
Signed-off-by: NFelix Eckhofer <felix@eckhofer.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Some documentation files received recent changes and are
pointing to wrong places.

Those references can easily fixed with the help of a
script:

	$ ./scripts/documentation-file-ref-check --fix
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: NJan Kara <jack@suse.cz>
Reviewed-by: NDarrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Document that the default for "iommu.passthrough" is now configurable.

Fixes: 58d11317 ("iommu: Add config option to set passthrough as default")
Signed-off-by: NRobin Murphy <robin.murphy@arm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NMike Rapoport <rppt@linux.vnet.ibm.com>
Acked-by: NMichal Hocko <mhocko@suse.com>
Acked-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NMike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NMike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

There were several rounds of the patches that enabled "functions" directive
with no parameters in kerneldoc.py to allow including all the kernel-doc
comments except the DOC: sections.

Yet, the boot-time-mm.rst sneaked in with the older version of that
directive and was not updated. Update it now.
Signed-off-by: NMike Rapoport <rppt@linux.vnet.ibm.com>
Tested-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This is a respin with a wider audience (all that get_maintainer returned)
and I know this spams a *lot* of people. Not sure what would be the correct
way, so my apologies for ruining your inbox.

The 00-INDEX files are supposed to give a summary of all files present
in a directory, but these files are horribly out of date and their
usefulness is brought into question. Often a simple "ls" would reveal
the same information as the filenames are generally quite descriptive as
a short introduction to what the file covers (it should not surprise
anyone what Documentation/sched/sched-design-CFS.txt covers)

A few years back it was mentioned that these files were no longer really
needed, and they have since then grown further out of date, so perhaps
it is time to just throw them out.

A short status yields the following _outdated_ 00-INDEX files, first
counter is files listed in 00-INDEX but missing in the directory, last
is files present but not listed in 00-INDEX.

List of outdated 00-INDEX:
Documentation: (4/10)
Documentation/sysctl: (0/1)
Documentation/timers: (1/0)
Documentation/blockdev: (3/1)
Documentation/w1/slaves: (0/1)
Documentation/locking: (0/1)
Documentation/devicetree: (0/5)
Documentation/power: (1/1)
Documentation/powerpc: (0/5)
Documentation/arm: (1/0)
Documentation/x86: (0/9)
Documentation/x86/x86_64: (1/1)
Documentation/scsi: (4/4)
Documentation/filesystems: (2/9)
Documentation/filesystems/nfs: (0/2)
Documentation/cgroup-v1: (0/2)
Documentation/kbuild: (0/4)
Documentation/spi: (1/0)
Documentation/virtual/kvm: (1/0)
Documentation/scheduler: (0/2)
Documentation/fb: (0/1)
Documentation/block: (0/1)
Documentation/networking: (6/37)
Documentation/vm: (1/3)

Then there are 364 subdirectories in Documentation/ with several files that
are missing 00-INDEX alltogether (and another 120 with a single file and no
00-INDEX).

I don't really have an opinion to whether or not we /should/ have 00-INDEX,
but the above 00-INDEX should either be removed or be kept up to date. If
we should keep the files, I can try to keep them updated, but I rather not
if we just want to delete them anyway.

As a starting point, remove all index-files and references to 00-INDEX and
see where the discussion is going.
Signed-off-by: NHenrik Austad <henrik@austad.us>
Acked-by: N"Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
Just-do-it-by: NSteven Rostedt <rostedt@goodmis.org>
Reviewed-by: NJens Axboe <axboe@kernel.dk>
Acked-by: NPaul Moore <paul@paul-moore.com>
Acked-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: NMark Brown <broonie@kernel.org>
Acked-by: NMike Rapoport <rppt@linux.vnet.ibm.com>
Cc: [Almost everybody else]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

I'll handle these myself but thanks for providing the fallback!
Signed-off-by: NWolfram Sang <wsa@the-dreams.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Helps reading and hopefully avoids duplicates. Also, consistently add
the trailing '/' to make clear those are directories.
Signed-off-by: NWolfram Sang <wsa@the-dreams.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The dtb= parameter is no longer the primary mechanism for providing a
devicetree to the kernel. Now either firmware or the boot selector (ex.
Grub) should provide the devicetree and dtb= should only be used for
debug or when using firmware that doesn't understand DT.
Update the EFI stub documentation to reflect the current usage.
Signed-off-by: NGrant Likely <grant.likely@arm.com>
Reviewed-by: NAlexander Graf <agraf@suse.de>
Acked-by: NLeif Lindholm <leif.lindholm@linaro.org>
Acked-by: NOlof Johansson <olof@lixom.net>
Acked-by: NArd Biesheuvel <ard.biesheuvel@linaro.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Replace the Introduction section's TBD with some useful overview text.
Signed-off-by: NTakashi Sakamoto <o-takashi@sakamocchi.jp>
Acked-by: NRandy Dunlap <rdunlap@infradead.org>
Tested-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add a basic Firewire/IEEE 1394 driver API chapter to the Linux
kernel documentation.
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Clean up kernel-doc warnings in <drivers/firewire/core-transaction.c>
so that it can be added to a Firewire/IEEE 1394 driver-api chapter
without adding lots of noisy warnings to the documentation build.
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Clean up kernel-doc warnings in <drivers/firewire/core-iso.c> so that
it can be added to a Firewire/IEEE 1394 driver-api chapter
without adding lots of noisy warnings to the documentation build.
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Clean up kernel-doc warnings in <linux/firewire-cdev.h> so that
it can be added to a Firewire/IEEE 1394 driver-api chapter
without adding lots of noisy warnings to the documentation build.
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: linux-scsi@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

* Fix install instruction by adding `./autogen` command
  before `./configure`.
* Add link to a more detailed installation instruction.
* Add link to SmPL grammar documentation.
* Add single space after ',' to slightly improve readability.
Signed-off-by: NHimanshu Jha <himanshujha199640@gmail.com>
Acked-by: NJulia Lawall <julia.lawall@lip6.fr>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The documentation and TOCs are organized in a manner of a tree. Adding a TOC to
the root, which refers to a file which is located in a subfolder forms a
grid. Those TOCs are a bit confusing and thats why we get additional error
messages while building partial documentation::

  $ make SPHINXDIRS=process htmldocs
  ...
  checking consistency... Documentation/process/license-rules.rst: \
  WARNING: document isn't included in any toctree

To fix it, the *root-license-TOC* is replaced by a reference and the
'license-roles.txt' is added to the Documentation/process/index.rst TOC.

BTW: there was an old licences remark in Documentation/process/howto.rst which
is also updated, mentioning SPDX and pointing to the license-rules.rst
Signed-off-by: NMarkus Heiser <markus.heiser@darmarit.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Fix small typo (wiil -> will) in the "3.4. Nested virtual machines"
section.

Fixes: 5b76a3cf ("KVM: VMX: Tell the nested hypervisor to skip L1D flush on vmentry")
Cc: linux-kernel@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Josh Poimboeuf <jpoimboe@redhat.com>
Cc: Paolo Bonzini <pbonzini@redhat.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Tony Luck <tony.luck@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: trivial@kernel.org
Signed-off-by: NSalvatore Bonaccorso <carnil@debian.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add a description of stacktrace filter command.
Signed-off-by: NMasami Hiramatsu <mhiramat@kernel.org>
Acked-by: NSteven Rostedt (VMware) <rostedt@goodmis.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Spell the vesafb "inverse" option correctly and tell what it does.
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Cc: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
Cc: dri-devel@lists.freedesktop.org
Cc: linux-fbdev@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Antonino A. Daplas <adaplas@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Fix s/4.17/4.16/ typo.

Fixes: 8962e40c ("docs: update kernel versions and dates in tables")
Cc: Tim Bird <tim.bird@sony.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: NAkinobu Mita <akinobu.mita@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Config fragment files should be placed in
tools/testing/selftests/<testdir>/config
Signed-off-by: NAnders Roxell <anders.roxell@linaro.org>
Acked-by: NShuah Khan (Samsung OSG) <shuah@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This space missing caused the colour scheme in vim editor messy
after that line. Add it to fix.
Signed-off-by: NBaoquan He <bhe@redhat.com>
[ jc: fixed alignment after the changed line ]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>