Add blank lines where needed to get the document to render properly.  Also
add a TOC of existing profiles just so that the nvdimm profile is linked
into the toctree, is discoverable, and doesn't generate a warning.
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Document the basic policies of the libnvdimm subsystem and provide a first
example of a Maintainer Entry Profile for others to duplicate and edit.

Cc: Vishal Verma <vishal.l.verma@intel.com>
Cc: Dave Jiang <dave.jiang@intel.com>
Signed-off-by: NDan Williams <dan.j.williams@intel.com>
Link: https://lore.kernel.org/r/157462919825.1729495.5877405723948988416.stgit@dwillia2-desk3.amr.corp.intel.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

As presented at the 2018 Linux Plumbers conference [1], the Maintainer
Entry Profile (formerly Subsystem Profile) is proposed as a way to reduce
friction between committers and maintainers and encourage conversations
amongst maintainers about common best practices. While coding-style,
submit-checklist, and submitting-drivers lay out some common expectations
there remain local customs and maintainer preferences that vary by
subsystem.

The profile contains documentation of some of the common policy
questions a contributor might have that are local to the subsystem /
device-driver, special considerations for the subsystem, or other
guidelines that are otherwise not covered by the top-level process
documents.

The initial and hopefully non-controversial headings in the profile are:

    Overview:
    General introduction to how the subsystem operates

    Submit Checklist Addendum:
    Mechanical items that gate submission staging, or other requirements
    that gate patch acceptance.

    Key Cycle Dates:
     - Last -rc for new feature submissions: Expected lead time for submissions
     - Last -rc to merge features: Deadline for merge decisions

    Resubmit Cadence: When and preferred method to follow up with the
    maintainer

Note that coding style guidelines are explicitly left out of this list.

See Documentation/maintainer/maintainer-entry-profile.rst for more details,
and a follow-on example profile for the libnvdimm subsystem.

[1]: https://linuxplumbersconf.org/event/2/contributions/59/

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Steve French <stfrench@microsoft.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Tobin C. Harding <me@tobin.cc>
Cc: Olof Johansson <olof@lixom.net>
Cc: Martin K. Petersen <martin.petersen@oracle.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Joe Perches <joe@perches.com>
Cc: Dmitry Vyukov <dvyukov@google.com>
Cc: Alexandre Belloni <alexandre.belloni@bootlin.com>
Cc: Paul Walmsley <paul.walmsley@sifive.com>
Signed-off-by: NDan Williams <dan.j.williams@intel.com>
Link: https://lore.kernel.org/r/157462919309.1729495.10585699280061787229.stgit@dwillia2-desk3.amr.corp.intel.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Fixup some P: entries to be M: and delete the others that do not include an
email address. The P: tag will be used to indicate the location of a
Profile for a given MAINTAINERS entry.

Cc: Joe Perches <joe@perches.com>
Signed-off-by: NDan Williams <dan.j.williams@intel.com>
Link: https://lore.kernel.org/r/157462918794.1729495.10838545318307341653.stgit@dwillia2-desk3.amr.corp.intel.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Rasmus correctly observed that the existing jobserver reservation only
worked if no other build targets were specified. The correct approach
is to hold the jobserver slots until sphinx has finished. To fix this,
the following changes are made:

- refactor (and rename) scripts/jobserver-exec to set an environment
  variable for the maximally reserved jobserver slots and exec a
  child, to release the slots on exit.

- create Documentation/scripts/parallel-wrapper.sh which examines both
  $PARALLELISM and the detected "-jauto" logic from Documentation/Makefile
  to decide sphinx's final -j argument.

- chain these together in Documentation/Makefile
Suggested-by: NRasmus Villemoes <linux@rasmusvillemoes.dk>
Link: https://lore.kernel.org/lkml/eb25959a-9ec4-3530-2031-d9d716b40b20@rasmusvillemoes.dkSigned-off-by: NKees Cook <keescook@chromium.org>
Link: https://lore.kernel.org/r/20191121205929.40371-4-keescook@chromium.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Setting non-blocking via a local copy of the jobserver file descriptor
is safer than just assuming other reader processes with the same fd open
are prepared for it to be non-blocking.
Suggested-by: NRasmus Villemoes <linux@rasmusvillemoes.dk>
Link: https://lore.kernel.org/lkml/44c01043-ab24-b4de-6544-e8efd153e27a@rasmusvillemoes.dkSigned-off-by: NKees Cook <keescook@chromium.org>
Link: https://lore.kernel.org/r/20191121205929.40371-3-keescook@chromium.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Rasmus noted that the failure path didn't correctly exit. Fix this and
add another comment about GNU Make's job server environment variable
names over time.
Reported-by: NRasmus Villemoes <linux@rasmusvillemoes.dk>
Link: https://lore.kernel.org/lkml/eb25959a-9ec4-3530-2031-d9d716b40b20@rasmusvillemoes.dkSigned-off-by: NKees Cook <keescook@chromium.org>
Link: https://lore.kernel.org/r/20191121205929.40371-2-keescook@chromium.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Remove bootmem_debug kernel paramenter because it has been
replaced by memblock=debug.
Signed-off-by: NMasami Hiramatsu <mhiramat@kernel.org>
Cc: Mike Rapoport <rppt@linux.ibm.com>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/157443061745.20995.9432492850513217966.stgit@devnote2Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Fix warnings due to missing markup, no change in content otherwise.
Signed-off-by: NDaniel W. S. Almeida <dwlsalmeida@gmail.com>
Link: https://lore.kernel.org/r/20191122041806.68650-1-dwlsalmeida@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Translate this commit to Korean:

  d2b008f1 ("Documentation/process/howto: Update for 4.x -> 5.x versioning")
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Link: https://lore.kernel.org/r/20191121234125.28032-8-sj38.park@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Link: https://lore.kernel.org/r/20191121234125.28032-7-sj38.park@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

This commit removes references to sections erased by Commit 91553039
("Documentation: Kill all references to mmiowb()").
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Link: https://lore.kernel.org/r/20191121234125.28032-6-sj38.park@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Translate this commit to Korean:

  9726840d ("docs/memory-barriers.txt: Update I/O section to be clearer about CPU vs thread")
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Link: https://lore.kernel.org/r/20191121234125.28032-5-sj38.park@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Translate this commit to Korean:

  0cde62a4 ("docs/memory-barriers.txt: Fix style, spacing and grammar in I/O section")
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Link: https://lore.kernel.org/r/20191121234125.28032-4-sj38.park@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Translate this commit to Korean:

  91553039 ("Documentation: Kill all references to mmiowb()")
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Link: https://lore.kernel.org/r/20191121234125.28032-3-sj38.park@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Translate this commit to Korean:

  4614bbde ("docs/memory-barriers.txt: Rewrite "KERNEL I/O BARRIER EFFECTS" section")
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Link: https://lore.kernel.org/r/20191121234125.28032-2-sj38.park@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

The devfreq subsystem has plenty of kernel-doc comments but they're not
currently included in sphinx documentation.

Add a minimal devfreq.rst file which mostly just includes kernel-doc
comments from devfreq source. This also exposes a number of kernel-doc
warnings on `make htmldocs`
Signed-off-by: NLeonard Crestez <leonard.crestez@nxp.com>
Link: https://lore.kernel.org/r/e32fa9de8a60060a6ee5fc42f163111034f9a550.1574181341.git.leonard.crestez@nxp.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

This adds Kees' clever apply hook to the kernel documentation so
it can be easily references when needed.

Cc: Kees Cook <keescook@chromium.org>
Link: https://lists.linuxfoundation.org/pipermail/ksummit-discuss/2019-July/006608.htmlSigned-off-by: NLinus Walleij <linus.walleij@linaro.org>
Link: https://lore.kernel.org/r/20191118223019.81708-1-linus.walleij@linaro.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

While checking the results of the :c:func: removal, I noticed that there
was no documentation for request_irq(), and request_threaded_irq() was not
mentioned at all.  Add a kerneldoc comment for request_irq() and add
request_threaded_irq() to the list of functions.
Reviewed-by: NThomas Gleixner <tglx@linutronix.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The second paragraph of the content section does not properly
describe how mount points are determined by autofs.

Replace the lines detailing how the determination of these mount
points is "ad hoc" by a short description of the mount map syntax
used by autofs.
Signed-off-by: NJaskaran Singh <jaskaransingh7654321@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Some of the struct definitions now have an autofs packet header.
Reflect these changes by adding a definition of this header and
place it wherever suitable.
Signed-off-by: NJaskaran Singh <jaskaransingh7654321@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Convert autofs.txt to reST.

The following changes abound:

- Introduce reST formatting for headings, lists et al.
- Add an indentation of an 8 space tab wherever suitable, so as
  to maintain consistency.
- Remove indentation of the description of the ioctls which are similar
  to the AUTOFS_IOC ioctls, as it does not come out quite right in HTML.
- Add an entry for autofs in the index.
Signed-off-by: NJaskaran Singh <jaskaransingh7654321@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This reverts commit 7f70ae56.

Christoph H. notes that the information is redundant, and Paul W. agrees
with reverting.
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add myself as the AMD ambassador to the embargoed hardware issues
document.
Signed-off-by: NTom Lendacky <thomas.lendacky@amd.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

When print the difference between two pointers, we should use
the ptrdiff_t modifier %t.
Signed-off-by: NMiles Chen <miles.chen@mediatek.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add in detailed programmers reference for users wanting to program the
CoreSight ETM 4.x driver using sysfs.
Signed-off-by: NMike Leach <mike.leach@linaro.org>
Reviewed-by: NMathieu Poirier <mathieu.poirier@linaro.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

There are two files in the Documentation/trace directory relating to
coresight, with more to follow, so create a Documentation/trace/coresight
directory and move existing files there. Fixup index to reference
new location.

Update MAINTAINERS to reference this sub-directory rather than the
individual files.
Signed-off-by: NMike Leach <mike.leach@linaro.org>
Reviewed-by: NMathieu Poirier <mathieu.poirier@linaro.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This updates the ABI document to reflect recent additions to the ETM4.X
driver sysfs interface.
Signed-off-by: NMike Leach <mike.leach@linaro.org>
[Updated Date and KernelVersion fields]
Reviewed-by: NMathieu Poirier <mathieu.poirier@linaro.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Recent updates to CoreSight drivers have changed the component naming
schema used in sysfs.

This updates the ABI document to reflect the new naming schema.
Signed-off-by: NMike Leach <mike.leach@linaro.org>
Reviewed-by: NMathieu Poirier <mathieu.poirier@linaro.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The exclusive lock is only held when O_CREAT is set.
Signed-off-by: NJeff Layton <jlayton@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

One of the recurring complaints from both maintainers and CI system
operators is that performing git-am on received patches is difficult
without knowing the parent object in the git history on which the
patches are based. Without this information, there is a high likelihood
that git-am will fail due to conflicts, which is particularly
frustrating to CI operators.

Git versions starting with v2.9.0 are able to automatically include
base-commit information using the --base flag of git-format-patch.
Document this usage in process/submitting-patches, and add the rationale
for its inclusion, plus instructions for those not using git on where
the "base-commit:" trailer should go.
Signed-off-by: NKonstantin Ryabitsev <konstantin@linuxfoundation.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The 'functions' directive is not only for functions, but also works for
structs/unions. So the name is misleading. This patch renames it to
'identifiers', which specific the functions/types to be included in
documentation. We keep the old name as an alias of the new one before
all documentation are updated.
Signed-off-by: NChangbin Du <changbin.du@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Since following path was merged in 5.4-rc3,
auto-tuning feature in threads-max does not exist any more.
Fix the admin-guide document as is.

kernel/sysctl.c: do not override max_threads provided by userspace
b0f53dbc

Fixes: b0f53dbc ("kernel/sysctl.c: do not override max_threads provided by userspace")
Signed-off-by: NMasanari Iida <standby24x7@gmail.com>
Acked-by: NMichal Hocko <mhocko@suse.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Since following patch was merged 5.4-rc3, minimum value for
threads-max changed to 1.

kernel/sysctl.c: do not override max_threads provided by userspace
b0f53dbc

Fixes: b0f53dbc ("kernel/sysctl.c: do not override max_threads provided by userspace")
Signed-off-by: NMasanari Iida <standby24x7@gmail.com>
Acked-by: NMichal Hocko <mhocko@suse.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

On Arch Linux, latexmk is installed in the texlive-core package.
Signed-off-by: NLouis Taylor <louis@kragniz.eu>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This makes it consistent with the other headings in the Linux driver
implementer's API guide.
Signed-off-by: NLouis Taylor <louis@kragniz.eu>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Currently, when kernel-doc encounters a macro with a named variable
argument[1], such as this:

   #define hlist_for_each_entry_rcu(pos, head, member, cond...)

... it expects the variable argument to be documented as `cond...`,
rather than `cond`. This is semantically wrong, because the name (as
used in the macro body) is actually `cond`.

With this patch, kernel-doc will accept the name without dots (`cond`
in the example above) in doc comments, and warn if the name with dots
(`cond...`) is used and verbose mode[2] is enabled.

The support for the `cond...` syntax can be removed later, when the
documentation of all such macros has been switched to the new syntax.

Testing this patch on top of v5.4-rc6, `make htmldocs` shows a few
changes in log output and HTML output:

 1) The following warnings[3] are eliminated:

   ./include/linux/rculist.h:374: warning:
        Excess function parameter 'cond' description in 'list_for_each_entry_rcu'
   ./include/linux/rculist.h:651: warning:
        Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'

 2) For list_for_each_entry_rcu and hlist_for_each_entry_rcu, the
    correct description is shown

 3) Named variable arguments are shown without dots

[1]: https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html
[2]: scripts/kernel-doc -v
[3]: See also https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git/commit/?h=dev&id=5bc4bc0d6153617eabde275285b7b5a8137fdf3cSigned-off-by: NJonathan Neuschäfer <j.neuschaefer@gmx.net>
Tested-by: NPaul E. McKenney <paulmck@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Mention struct_size(), array_size() and array3_size() in the same place
as kmalloc() and friends.
Signed-off-by: NChris Packham <chris.packham@alliedtelesis.co.nz>
Acked-by: NMike Rapoport <rppt@linux.ibm.com>
Reviewed-by: NMatthew Wilcox (Oracle) <willy@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

These are no longer needed as the documentation build will automatically
add the cross references.
Signed-off-by: NChris Packham <chris.packham@alliedtelesis.co.nz>
Acked-by: NMike Rapoport <rppt@linux.ibm.com>
Reviewed-by: NMatthew Wilcox (Oracle) <willy@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

"on the safe size" should be "on the safe side".
Signed-off-by: NChris Packham <chris.packham@alliedtelesis.co.nz>
Acked-by: NMike Rapoport <rppt@linux.ibm.com>
Reviewed-by: NMatthew Wilcox (Oracle) <willy@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>