mirror of
https://github.com/torvalds/linux.git
synced 2024-11-10 22:21:40 +00:00
a354049532
- Some initial page-table documentation from Linus (the other Linus)
- Regression-handling documentation improvements from Thorsten
- Addition of kerneldoc documentation for the ERR_PTR() and related
macros from James Seo
...and the usual collection of fixes and updates.
-----BEGIN PGP SIGNATURE-----
iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAmSbC9wPHGNvcmJldEBs
d24ubmV0AAoJEBdDWhNsDH5Yw7YH/Rcd2oVQ/B8ui9TYcXTQid0ly5GvLl/ot0zf
pml725bZSKodcdtmLvQ6CzMGRdzxhQpVfzy21zHAlQWiBMdheWeu0Etmpspn8fCI
wnJIlUbGdp5Aq4ZtoJPTtE3vXvWEQ32gVytGjbTVNtSLRLXQ1bc+A/IvmRj3jdkV
dwPfN7hPLVhBt5770pHMywlFVBQ9FUjUNC+uX0JkcNZJ3598c4ZzndBEaLdqfPHC
DtWucRdnHubTncKECgYbspsfH6zuntFk8FgsD1gZ1K9izMAwVBsKSS+MeOz8oxx8
rPq4Tscqs/9mpist/PqxEu0fvTC3xsyMbxLA4hAORmgpdnbWIaQ=
=q2B4
-----END PGP SIGNATURE-----
Merge tag 'docs-6.5' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"It's been a relatively calm cycle in docsland. We do have:
- Some initial page-table documentation from Linus (the other Linus)
- Regression-handling documentation improvements from Thorsten
- Addition of kerneldoc documentation for the ERR_PTR() and related
macros from James Seo
... and the usual collection of fixes and updates"
* tag 'docs-6.5' of git://git.lwn.net/linux:
docs: consolidate storage interfaces
Documentation: update git configuration for Link: tag
Documentation: KVM: make corrections to vcpu-requests.rst
Documentation: KVM: make corrections to ppc-pv.rst
Documentation: KVM: make corrections to locking.rst
Documentation: KVM: make corrections to halt-polling.rst
Documentation: virt: correct location of haltpoll module params
Documentation/mm: Initial page table documentation
docs: crypto: async-tx-api: fix typo in struct name
docs/doc-guide: Clarify how to write tables
docs: handling-regressions: rework section about fixing procedures
docs: process: fix a typoed cross-reference
docs: submitting-patches: Discuss interleaved replies
MAINTAINERS: direct process doc changes to a dedicated ML
Documentation: core-api: Add error pointer functions to kernel-api
err.h: Add missing kerneldocs for error pointer functions
Documentation: conf.py: Add __force to c_id_attributes
docs: clarify KVM related kernel parameters' descriptions
docs: consolidate human interface subsystems
docs: admin-guide: Add information about intel_pstate active mode
433 lines
8.9 KiB
ReStructuredText
433 lines
8.9 KiB
ReStructuredText
====================
|
|
The Linux Kernel API
|
|
====================
|
|
|
|
|
|
List Management Functions
|
|
=========================
|
|
|
|
.. kernel-doc:: include/linux/list.h
|
|
:internal:
|
|
|
|
Basic C Library Functions
|
|
=========================
|
|
|
|
When writing drivers, you cannot in general use routines which are from
|
|
the C Library. Some of the functions have been found generally useful
|
|
and they are listed below. The behaviour of these functions may vary
|
|
slightly from those defined by ANSI, and these deviations are noted in
|
|
the text.
|
|
|
|
String Conversions
|
|
------------------
|
|
|
|
.. kernel-doc:: lib/vsprintf.c
|
|
:export:
|
|
|
|
.. kernel-doc:: include/linux/kstrtox.h
|
|
:functions: kstrtol kstrtoul
|
|
|
|
.. kernel-doc:: lib/kstrtox.c
|
|
:export:
|
|
|
|
.. kernel-doc:: lib/string_helpers.c
|
|
:export:
|
|
|
|
String Manipulation
|
|
-------------------
|
|
|
|
.. kernel-doc:: include/linux/fortify-string.h
|
|
:internal:
|
|
|
|
.. kernel-doc:: lib/string.c
|
|
:export:
|
|
|
|
.. kernel-doc:: include/linux/string.h
|
|
:internal:
|
|
|
|
.. kernel-doc:: mm/util.c
|
|
:functions: kstrdup kstrdup_const kstrndup kmemdup kmemdup_nul memdup_user
|
|
vmemdup_user strndup_user memdup_user_nul
|
|
|
|
Basic Kernel Library Functions
|
|
==============================
|
|
|
|
The Linux kernel provides more basic utility functions.
|
|
|
|
Bit Operations
|
|
--------------
|
|
|
|
.. kernel-doc:: include/asm-generic/bitops/instrumented-atomic.h
|
|
:internal:
|
|
|
|
.. kernel-doc:: include/asm-generic/bitops/instrumented-non-atomic.h
|
|
:internal:
|
|
|
|
.. kernel-doc:: include/asm-generic/bitops/instrumented-lock.h
|
|
:internal:
|
|
|
|
Bitmap Operations
|
|
-----------------
|
|
|
|
.. kernel-doc:: lib/bitmap.c
|
|
:doc: bitmap introduction
|
|
|
|
.. kernel-doc:: include/linux/bitmap.h
|
|
:doc: declare bitmap
|
|
|
|
.. kernel-doc:: include/linux/bitmap.h
|
|
:doc: bitmap overview
|
|
|
|
.. kernel-doc:: include/linux/bitmap.h
|
|
:doc: bitmap bitops
|
|
|
|
.. kernel-doc:: lib/bitmap.c
|
|
:export:
|
|
|
|
.. kernel-doc:: lib/bitmap.c
|
|
:internal:
|
|
|
|
.. kernel-doc:: include/linux/bitmap.h
|
|
:internal:
|
|
|
|
Command-line Parsing
|
|
--------------------
|
|
|
|
.. kernel-doc:: lib/cmdline.c
|
|
:export:
|
|
|
|
Error Pointers
|
|
--------------
|
|
|
|
.. kernel-doc:: include/linux/err.h
|
|
:internal:
|
|
|
|
Sorting
|
|
-------
|
|
|
|
.. kernel-doc:: lib/sort.c
|
|
:export:
|
|
|
|
.. kernel-doc:: lib/list_sort.c
|
|
:export:
|
|
|
|
Text Searching
|
|
--------------
|
|
|
|
.. kernel-doc:: lib/textsearch.c
|
|
:doc: ts_intro
|
|
|
|
.. kernel-doc:: lib/textsearch.c
|
|
:export:
|
|
|
|
.. kernel-doc:: include/linux/textsearch.h
|
|
:functions: textsearch_find textsearch_next \
|
|
textsearch_get_pattern textsearch_get_pattern_len
|
|
|
|
CRC and Math Functions in Linux
|
|
===============================
|
|
|
|
Arithmetic Overflow Checking
|
|
----------------------------
|
|
|
|
.. kernel-doc:: include/linux/overflow.h
|
|
:internal:
|
|
|
|
CRC Functions
|
|
-------------
|
|
|
|
.. kernel-doc:: lib/crc4.c
|
|
:export:
|
|
|
|
.. kernel-doc:: lib/crc7.c
|
|
:export:
|
|
|
|
.. kernel-doc:: lib/crc8.c
|
|
:export:
|
|
|
|
.. kernel-doc:: lib/crc16.c
|
|
:export:
|
|
|
|
.. kernel-doc:: lib/crc32.c
|
|
|
|
.. kernel-doc:: lib/crc-ccitt.c
|
|
:export:
|
|
|
|
.. kernel-doc:: lib/crc-itu-t.c
|
|
:export:
|
|
|
|
Base 2 log and power Functions
|
|
------------------------------
|
|
|
|
.. kernel-doc:: include/linux/log2.h
|
|
:internal:
|
|
|
|
Integer power Functions
|
|
-----------------------
|
|
|
|
.. kernel-doc:: lib/math/int_pow.c
|
|
:export:
|
|
|
|
.. kernel-doc:: lib/math/int_sqrt.c
|
|
:export:
|
|
|
|
Division Functions
|
|
------------------
|
|
|
|
.. kernel-doc:: include/asm-generic/div64.h
|
|
:functions: do_div
|
|
|
|
.. kernel-doc:: include/linux/math64.h
|
|
:internal:
|
|
|
|
.. kernel-doc:: lib/math/gcd.c
|
|
:export:
|
|
|
|
UUID/GUID
|
|
---------
|
|
|
|
.. kernel-doc:: lib/uuid.c
|
|
:export:
|
|
|
|
Kernel IPC facilities
|
|
=====================
|
|
|
|
IPC utilities
|
|
-------------
|
|
|
|
.. kernel-doc:: ipc/util.c
|
|
:internal:
|
|
|
|
FIFO Buffer
|
|
===========
|
|
|
|
kfifo interface
|
|
---------------
|
|
|
|
.. kernel-doc:: include/linux/kfifo.h
|
|
:internal:
|
|
|
|
relay interface support
|
|
=======================
|
|
|
|
Relay interface support is designed to provide an efficient mechanism
|
|
for tools and facilities to relay large amounts of data from kernel
|
|
space to user space.
|
|
|
|
relay interface
|
|
---------------
|
|
|
|
.. kernel-doc:: kernel/relay.c
|
|
:export:
|
|
|
|
.. kernel-doc:: kernel/relay.c
|
|
:internal:
|
|
|
|
Module Support
|
|
==============
|
|
|
|
Kernel module auto-loading
|
|
--------------------------
|
|
|
|
.. kernel-doc:: kernel/module/kmod.c
|
|
:export:
|
|
|
|
Module debugging
|
|
----------------
|
|
|
|
.. kernel-doc:: kernel/module/stats.c
|
|
:doc: module debugging statistics overview
|
|
|
|
dup_failed_modules - tracks duplicate failed modules
|
|
****************************************************
|
|
|
|
.. kernel-doc:: kernel/module/stats.c
|
|
:doc: dup_failed_modules - tracks duplicate failed modules
|
|
|
|
module statistics debugfs counters
|
|
**********************************
|
|
|
|
.. kernel-doc:: kernel/module/stats.c
|
|
:doc: module statistics debugfs counters
|
|
|
|
Inter Module support
|
|
--------------------
|
|
|
|
Refer to the files in kernel/module/ for more information.
|
|
|
|
Hardware Interfaces
|
|
===================
|
|
|
|
DMA Channels
|
|
------------
|
|
|
|
.. kernel-doc:: kernel/dma.c
|
|
:export:
|
|
|
|
Resources Management
|
|
--------------------
|
|
|
|
.. kernel-doc:: kernel/resource.c
|
|
:internal:
|
|
|
|
.. kernel-doc:: kernel/resource.c
|
|
:export:
|
|
|
|
MTRR Handling
|
|
-------------
|
|
|
|
.. kernel-doc:: arch/x86/kernel/cpu/mtrr/mtrr.c
|
|
:export:
|
|
|
|
Security Framework
|
|
==================
|
|
|
|
.. kernel-doc:: security/security.c
|
|
:internal:
|
|
|
|
.. kernel-doc:: security/inode.c
|
|
:export:
|
|
|
|
Audit Interfaces
|
|
================
|
|
|
|
.. kernel-doc:: kernel/audit.c
|
|
:export:
|
|
|
|
.. kernel-doc:: kernel/auditsc.c
|
|
:internal:
|
|
|
|
.. kernel-doc:: kernel/auditfilter.c
|
|
:internal:
|
|
|
|
Accounting Framework
|
|
====================
|
|
|
|
.. kernel-doc:: kernel/acct.c
|
|
:internal:
|
|
|
|
Block Devices
|
|
=============
|
|
|
|
.. kernel-doc:: include/linux/bio.h
|
|
.. kernel-doc:: block/blk-core.c
|
|
:export:
|
|
|
|
.. kernel-doc:: block/blk-core.c
|
|
:internal:
|
|
|
|
.. kernel-doc:: block/blk-map.c
|
|
:export:
|
|
|
|
.. kernel-doc:: block/blk-sysfs.c
|
|
:internal:
|
|
|
|
.. kernel-doc:: block/blk-settings.c
|
|
:export:
|
|
|
|
.. kernel-doc:: block/blk-flush.c
|
|
:export:
|
|
|
|
.. kernel-doc:: block/blk-lib.c
|
|
:export:
|
|
|
|
.. kernel-doc:: block/blk-integrity.c
|
|
:export:
|
|
|
|
.. kernel-doc:: kernel/trace/blktrace.c
|
|
:internal:
|
|
|
|
.. kernel-doc:: block/genhd.c
|
|
:internal:
|
|
|
|
.. kernel-doc:: block/genhd.c
|
|
:export:
|
|
|
|
.. kernel-doc:: block/bdev.c
|
|
:export:
|
|
|
|
Char devices
|
|
============
|
|
|
|
.. kernel-doc:: fs/char_dev.c
|
|
:export:
|
|
|
|
Clock Framework
|
|
===============
|
|
|
|
The clock framework defines programming interfaces to support software
|
|
management of the system clock tree. This framework is widely used with
|
|
System-On-Chip (SOC) platforms to support power management and various
|
|
devices which may need custom clock rates. Note that these "clocks"
|
|
don't relate to timekeeping or real time clocks (RTCs), each of which
|
|
have separate frameworks. These :c:type:`struct clk <clk>`
|
|
instances may be used to manage for example a 96 MHz signal that is used
|
|
to shift bits into and out of peripherals or busses, or otherwise
|
|
trigger synchronous state machine transitions in system hardware.
|
|
|
|
Power management is supported by explicit software clock gating: unused
|
|
clocks are disabled, so the system doesn't waste power changing the
|
|
state of transistors that aren't in active use. On some systems this may
|
|
be backed by hardware clock gating, where clocks are gated without being
|
|
disabled in software. Sections of chips that are powered but not clocked
|
|
may be able to retain their last state. This low power state is often
|
|
called a *retention mode*. This mode still incurs leakage currents,
|
|
especially with finer circuit geometries, but for CMOS circuits power is
|
|
mostly used by clocked state changes.
|
|
|
|
Power-aware drivers only enable their clocks when the device they manage
|
|
is in active use. Also, system sleep states often differ according to
|
|
which clock domains are active: while a "standby" state may allow wakeup
|
|
from several active domains, a "mem" (suspend-to-RAM) state may require
|
|
a more wholesale shutdown of clocks derived from higher speed PLLs and
|
|
oscillators, limiting the number of possible wakeup event sources. A
|
|
driver's suspend method may need to be aware of system-specific clock
|
|
constraints on the target sleep state.
|
|
|
|
Some platforms support programmable clock generators. These can be used
|
|
by external chips of various kinds, such as other CPUs, multimedia
|
|
codecs, and devices with strict requirements for interface clocking.
|
|
|
|
.. kernel-doc:: include/linux/clk.h
|
|
:internal:
|
|
|
|
Synchronization Primitives
|
|
==========================
|
|
|
|
Read-Copy Update (RCU)
|
|
----------------------
|
|
|
|
.. kernel-doc:: include/linux/rcupdate.h
|
|
|
|
.. kernel-doc:: kernel/rcu/tree.c
|
|
|
|
.. kernel-doc:: kernel/rcu/tree_exp.h
|
|
|
|
.. kernel-doc:: kernel/rcu/update.c
|
|
|
|
.. kernel-doc:: include/linux/srcu.h
|
|
|
|
.. kernel-doc:: kernel/rcu/srcutree.c
|
|
|
|
.. kernel-doc:: include/linux/rculist_bl.h
|
|
|
|
.. kernel-doc:: include/linux/rculist.h
|
|
|
|
.. kernel-doc:: include/linux/rculist_nulls.h
|
|
|
|
.. kernel-doc:: include/linux/rcu_sync.h
|
|
|
|
.. kernel-doc:: kernel/rcu/sync.c
|
|
|
|
.. kernel-doc:: kernel/rcu/tasks.h
|
|
|
|
.. kernel-doc:: kernel/rcu/tree_stall.h
|
|
|
|
.. kernel-doc:: include/linux/rcupdate_trace.h
|
|
|
|
.. kernel-doc:: include/linux/rcupdate_wait.h
|
|
|
|
.. kernel-doc:: include/linux/rcuref.h
|
|
|
|
.. kernel-doc:: include/linux/rcutree.h
|