Add kerneldocs comments to the pr_*() macros in printk.h.

Add a new rst node in the core-api manual describing the basic usage of
printk and the related macro aliases.
Signed-off-by: NRicardo Cañuelo <ricardo.canuelo@collabora.com>
Link: https://lore.kernel.org/r/20200403093617.18003-1-ricardo.canuelo@collabora.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

The ioctl() documentation belongs with the rest of the driver-oriented
info, so move it there.
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Information about GCC plugins is relevant to kernel building, so move this
document to the kbuild manual.
Acked-by: NMasahiro Yamada <masahiroy@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The core-api manual has become a big, disorganized mess.  Try to bring a
small amount of order to it by organizing the documents into
subcategories.
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Moved the `kobject.txt` to `core-api/kobject.rst` and updated the
`core-api` index to point to it.
Signed-off-by: NSameer Rahmani <lxsameer@gnu.org>
[jc: moved it down from the top of core-api/index.rst]
Link: https://lore.kernel.org/r/20200225222125.61874-2-lxsameer@gnu.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Introduce pin_user_pages*() variations of get_user_pages*() calls, and
also pin_longterm_pages*() variations.

For now, these are placeholder calls, until the various call sites are
converted to use the correct get_user_pages*() or pin_user_pages*() API.

These variants will eventually all set FOLL_PIN, which is also
introduced, and thoroughly documented.

    pin_user_pages()
    pin_user_pages_remote()
    pin_user_pages_fast()

All pages that are pinned via the above calls, must be unpinned via
put_user_page().

The underlying rules are:

* FOLL_PIN is a gup-internal flag, so the call sites should not directly
  set it.  That behavior is enforced with assertions.

* Call sites that want to indicate that they are going to do DirectIO
  ("DIO") or something with similar characteristics, should call a
  get_user_pages()-like wrapper call that sets FOLL_PIN.  These wrappers
  will:

    * Start with "pin_user_pages" instead of "get_user_pages".  That
      makes it easy to find and audit the call sites.

    * Set FOLL_PIN

* For pages that are received via FOLL_PIN, those pages must be returned
  via put_user_page().

Thanks to Jan Kara and Vlastimil Babka for explaining the 4 cases in
this documentation.  (I've reworded it and expanded upon it.)

Link: http://lkml.kernel.org/r/20200107224558.2362728-12-jhubbard@nvidia.comSigned-off-by: NJohn Hubbard <jhubbard@nvidia.com>
Reviewed-by: NJan Kara <jack@suse.cz>
Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>		[Documentation]
Reviewed-by: NJérôme Glisse <jglisse@redhat.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Ira Weiny <ira.weiny@intel.com>
Cc: Alex Williamson <alex.williamson@redhat.com>
Cc: Aneesh Kumar K.V <aneesh.kumar@linux.ibm.com>
Cc: Björn Töpel <bjorn.topel@intel.com>
Cc: Christoph Hellwig <hch@lst.de>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Dan Williams <dan.j.williams@intel.com>
Cc: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Cc: Jason Gunthorpe <jgg@mellanox.com>
Cc: Jason Gunthorpe <jgg@ziepe.ca>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: Kirill A. Shutemov <kirill@shutemov.name>
Cc: Leon Romanovsky <leonro@mellanox.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Documentation/process/botching-up-ioctls.rst was orignally written as
a blog post for DRM driver writers, so it it misses some points while
going into a lot of detail on others.

Try to provide a replacement that addresses typical issues across a wider
range of subsystems, and follows the style of the core-api documentation
better.

Many improvements to the document are suggested by Ben Hutchings
<ben.hutchings@codethink.co.uk>, Jonathan Corbet <corbet@lwn.net> and
Geert Uytterhoeven <geert@linux-m68k.org>.
Reviewed-by: NBen Hutchings <ben.hutchings@codethink.co.uk>
Signed-off-by: NArnd Bergmann <arnd@arndb.de>

Remove references to unused functions, standardize language, update to
reflect new functionality, migrate to rst format, and fix all kernel-doc
warnings.

Fixes: 815613da ("kernel/padata.c: removed unused code")
Signed-off-by: NDaniel Jordan <daniel.m.jordan@oracle.com>
Cc: Eric Biggers <ebiggers@kernel.org>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Steffen Klassert <steffen.klassert@secunet.com>
Cc: linux-crypto@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Signed-off-by: NDaniel Jordan <daniel.m.jordan@oracle.com>
Signed-off-by: NHerbert Xu <herbert@gondor.apana.org.au>

We discussed a better location for this file, and agreed that
core-api/ is a good fit. Rename it to symbol-namespaces.rst
for disambiguation, and also add it to index.rst and MAINTAINERS.
Signed-off-by: NMasahiro Yamada <yamada.masahiro@socionext.com>
Acked-by: NMatthias Maennich <maennich@google.com>
Signed-off-by: NJessica Yu <jeyu@kernel.org>

The genindex logic is meant to be used only for html output, as
pdf build has its own way to generate indexes.
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Vinod Koul <vkoul@kernel.org> # dmaengine and soundwire
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The packing.txt file was misplaced, as docs should be part of
a documentation book, and not at the root dir.

So, move it to the core-api directory and add to its index.

Also, ensure that the file will be properly parsed and the bitmap
ascii artwork will use a monotonic font.

Fixes: 554aae35 ("lib: Add support for generic packing operations")
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: NVladimir Oltean <olteanv@gmail.com>
Tested-by: NVladimir Oltean <olteanv@gmail.com>
Reviewed-by: NMike Rapoport <rppt@linux.ibm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The gcc_plugins.txt file is already a ReST file. Move it
to the core-api book while renaming it.
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: NKees Cook <keescook@chromium.org>

We should really move the RCU directory there as well, but that can wait
for another day.
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This document is used by multiple architectures:

	$ echo $(git grep -l  pkey_mprotect arch|cut -d'/' -f 2|sort|uniq)
	alpha arm arm64 ia64 m68k microblaze mips parisc powerpc s390 sh sparc x86 xtensa

So, let's move it to the core book and adjust the links to it
accordingly.
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This file doesn't exist anymore.

Fixes: 586187d7 ("Drop flex_arrays")
Reviewed-by: NMukesh Ojha <mojha@codeaurora.org>
Signed-off-by: NJonathan Neuschäfer <j.neuschaefer@gmx.net>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Very simple radix tree implementation that supports storing arbitrary
size entries, up to PAGE_SIZE - upcoming patches will convert existing
flex_array users to genradixes.  The new genradix code has a much
simpler API and implementation, and doesn't have a hard limit on the
number of elements like flex_array does.

Link: http://lkml.kernel.org/r/20181217131929.11727-5-kent.overstreet@gmail.comSigned-off-by: NKent Overstreet <kent.overstreet@gmail.com>
Cc: Alexey Dobriyan <adobriyan@gmail.com>
Cc: Al Viro <viro@zeniv.linux.org.uk>
Cc: Dave Hansen <dave.hansen@intel.com>
Cc: Eric Paris <eparis@parisplace.org>
Cc: Marcelo Ricardo Leitner <marcelo.leitner@gmail.com>
Cc: Matthew Wilcox <willy@infradead.org>
Cc: Neil Horman <nhorman@tuxdriver.com>
Cc: Paul Moore <paul@paul-moore.com>
Cc: Pravin B Shelar <pshelar@ovn.org>
Cc: Shaohua Li <shli@kernel.org>
Cc: Stephen Smalley <sds@tycho.nsa.gov>
Cc: Vlad Yasevich <vyasevich@gmail.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

This is documentation on how to use the XArray, not details about its
internal implementation.
Signed-off-by: NMatthew Wilcox <willy@infradead.org>
Acked-by: NJosef Bacik <jbacik@fb.com>

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>

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>

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>

This is basically copy-paste of the memory management section from
kernel-api.rst with some minor adjustments:

* The "User Space Memory Access" is moved to the beginning
* The get_user_pages_fast reference is now a part of "User Space Memory
  Access"
* And, of course, headings are adjusted with section being promoted to
  chapters

Link: http://lkml.kernel.org/r/1532626360-16650-6-git-send-email-rppt@linux.vnet.ibm.comSigned-off-by: NMike Rapoport <rppt@linux.vnet.ibm.com>
Reviewed-by: NAndrew Morton <akpm@linux-foundation.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Matthew Wilcox <willy@infradead.org>
Cc: Michal Hocko <mhocko@kernel.org>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Both bootmem and memblock are have pretty good internal documentation
coverage. With addition of some overview we get a nice description of the
early memory management.
Signed-off-by: NMike Rapoport <rppt@linux.vnet.ibm.com>
Acked-by: NMichal Hocko <mhocko@suse.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

As Dave Chinner points out, we don't have a proper documentation for the
ktime_get() family of interfaces, making it rather unclear which of the
over 30 (!) interfaces one should actually use in a driver or elsewhere
in the kernel.

I wrote up an explanation from how I personally see the interfaces,
documenting what each of the functions do and hopefully making it a bit
clearer which should be used where.

This is the first time I tried writing .rst format documentation, so
in addition to any mistakes in the content, I probably also introduce
nonstandard formatting ;-)

I first tried to add an extra section to
Documentation/timers/timekeeping.txt, but this is currently not included
in the generated API, and it seems useful to have the API docs as part
of what gets generated in
https://www.kernel.org/doc/html/latest/core-api/index.html#core-utilities
instead, so I started a new file there.

I also considered adding the documentation inline in the
include/linux/timekeeping.h header, but couldn't figure out how to do
that in a way that would result both in helpful inline comments as
well as readable html output, so I settled for the latter, with
a small note pointing to it from the header.

Cc: Dave Chinner <david@fromorbit.com>
Cc: John Stultz <john.stultz@linaro.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Stephen Boyd <sboyd@kernel.org>
Tested-by: NRandy Dunlap <rdunlap@infradead.org>
Reviewed-by: NRandy Dunlap <rdunlap@infradead.org>
Reviewed-by: NLinus Walleij <linus.walleij@linaro.org>
Signed-off-by: NArnd Bergmann <arnd@arndb.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Although the api is documented in the source code Ted has pointed out
that there is no mention in the core-api Documentation and there are
people looking there to find answers how to use a specific API.
Requested-by: N"Theodore Y. Ts'o" <tytso@mit.edu>
Reviewed-by: NDave Chinner <dchinner@redhat.com>
Signed-off-by: NMichal Hocko <mhocko@suse.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The circular-buffers.txt is already in ReST format. So, move it to the
core-api guide, where it belongs.
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The cachetlb.txt is already in ReST format. So, move it to the
core-api guide, where it belongs.
Signed-off-by: NMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Move the idr kernel-doc to its own idr.rst file and add a few
paragraphs about how to use it.  Also add some more kernel-doc.
Signed-off-by: NMatthew Wilcox <mawilcox@microsoft.com>

 - Move errseq.rst into core-api
 - Add errseq to the core-api index
 - Promote the header to a more prominent header type, otherwise we get three
   entries in the table of contents.
 - Reformat the table to look nicer and be a little more proportional in
   terms of horizontal width per bit (the SF bit is still disproportionately
   large, but there's no way to fix that).
 - Include errseq kernel-doc in the errseq.rst
 - Neaten some kernel-doc markup
Signed-off-by: NMatthew Wilcox <mawilcox@microsoft.com>
Reviewed-by: NJeff Layton <jlayton@redhat.com>
Reviewed-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Documentation/printk-formats.txt is a candidate for conversion to
ReStructuredText format. Some effort has already been made to do this
conversion even thought the suffix is currently .txt

Changes required to complete conversion

 - Move printk-formats.txt to core-api/printk-formats.rst
 - Add entry to Documentation/core-api/index.rst
 - Remove entry from Documentation/00-INDEX
 - Fix minor grammatical errors.
 - Order heading adornments as suggested by rst docs.
 - Use 'Passed by reference' uniformly.
 - Update pointer documentation around %px specifier.
 - Fix erroneous double backticks (to commas).
 - Remove extraneous double backticks (suggested by Jonathan Corbet).
 - Simplify documentation for kobject.
Signed-off-by: NTobin C. Harding <me@tobin.cc>
[jc: downcased "kernel"]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Some functions from refcount_t API provide different
memory ordering guarantees that their atomic counterparts.
This adds a document outlining these differences (
Documentation/core-api/refcount-vs-atomic.rst) as well as
some other minor improvements.
Signed-off-by: NElena Reshetova <elena.reshetova@intel.com>
Signed-off-by: NKees Cook <keescook@chromium.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Genalloc/genpool has kerneldoc comments, but nothing has ever been pulled
into the docs themselves.  Here's a first attempt, repurposed from an
article I wrote at https://lwn.net/Articles/729653/.
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Brainless conversion of genericirq.tmpl book to ReST, via
	Documentation/sphinx/tmplcvt
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Brainless conversion of genericirq.tmpl book to ReST, via
	Documentation/sphinx/tmplcvt

Copyright information inserted manually.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add flexible-arrays.rst to Documentation/core-api. Add kernel-doc
comments to allow referencing.
Signed-off-by: Nsayli karnik <karniksayli1995@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The current CPU hotplug is outdated. During the update to what we
currently have I rewrote it partly and moved to sphinx format.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Rusty Russell <rusty@rustcorp.com.au>
Cc: Srivatsa Vaddagiri <vatsa@in.ibm.com>
Cc: Ashok Raj <ashok.raj@intel.com>
Cc: Joel Schopp <jschopp@austin.ibm.com>
Cc: linux-doc@vger.kernel.org
Signed-off-by: NSebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

... and move to core-api folder.
Signed-off-by: NSilvio Fricke <silvio.fricke@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

... and move to core-api folder.
Signed-off-by: NSilvio Fricke <silvio.fricke@gmail.com>
Reviewed-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

... and move to Documentation/core-api folder.
Signed-off-by: NSilvio Fricke <silvio.fricke@gmail.com>
Reviewed-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Convert the tracepoint docbook template to RST and add it to the core-api
manual.  No changes to the actual text beyond the mechanical formatting
conversion.

Cc: Jason Baron <jbaron@redhat.com>
Cc: William Cohen <wcohen@redhat.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>