linux/Documentation/core-api/index.rst

120 lines
2.1 KiB
ReStructuredText
Raw Normal View History

======================
Core API Documentation
======================
This is the beginning of a manual for core kernel APIs. The conversion
(and writing!) of documents for this manual is much appreciated!
Core utilities
==============
This section has general and "core core" documentation. The first is a
massive grab-bag of kerneldoc info left over from the docbook days; it
should really be broken up someday when somebody finds the energy to do
it.
.. toctree::
:maxdepth: 1
kernel-api
workqueue
printk-basics
printk-formats
symbol-namespaces
Data structures and low-level utilities
=======================================
Library functionality that is used throughout the kernel.
.. toctree::
:maxdepth: 1
kobject
assoc_array
xarray
idr
circular-buffers
rbtree
generic-radix-tree
packing
timekeeping
errseq
Concurrency primitives
======================
How Linux keeps everything from happening at the same time. See
:doc:`/locking/index` for more related documentation.
.. toctree::
:maxdepth: 1
atomic_ops
refcount-vs-atomic
irq/index
local_ops
padata
../RCU/index
Low-level hardware management
=============================
Cache management, managing CPU hotplug, etc.
.. toctree::
:maxdepth: 1
cachetlb
cpu_hotplug
memory-hotplug
genericirq
protection-keys
Memory management
=================
How to allocate and use memory in the kernel. Note that there is a lot
more memory-management documentation in :doc:`/vm/index`.
.. toctree::
:maxdepth: 1
memory-allocation
dma-api
dma-api-howto
dma-attributes
dma-isa-lpc
mm-api
genalloc
mm/gup: introduce pin_user_pages*() and FOLL_PIN 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.com Signed-off-by: John Hubbard <jhubbard@nvidia.com> Reviewed-by: Jan Kara <jack@suse.cz> Reviewed-by: Mike Rapoport <rppt@linux.ibm.com> [Documentation] Reviewed-by: Jé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: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2020-01-31 06:12:54 +00:00
pin_user_pages
boot-time-mm
gfp_mask-from-fs-io
Interfaces for kernel debugging
===============================
.. toctree::
:maxdepth: 1
debug-objects
tracepoint
debugging-via-ohci1394
Everything else
===============
Documents that don't fit elsewhere or which have yet to be categorized.
.. toctree::
:maxdepth: 1
librs
.. only:: subproject and html
Indices
=======
* :ref:`genindex`