Skip to content

L
linux
Commit 02bafd96 authored by Linus Torvalds's avatar Linus Torvalds
Browse files
Options

Merge tag 'docs-4.9' of git://git.lwn.net/linux 

Pull documentation updates from Jonathan Corbet:
 "This is the documentation update pull for the 4.9 merge window.

  The Sphinx transition is still creating a fair amount of work. Here we
  have a number of fixes and, importantly, a proper PDF output solution,
  thanks to Jani Nikula, Mauro Carvalho Chehab and Markus Heiser.

  I've started a couple of new books: a driver API book (based on the
  old device-drivers.tmpl) and a development tools book. Both are meant
  to show how we can integrate together our existing documentation into
  a more coherent and accessible whole. It involves moving some stuff
  around and formatting changes, but, I think, the results are worth it.
  The good news is that most of our existing Documentation/*.txt files
  are *almost* in RST format already; the amount of messing around
  required is minimal.

  And, of course, there's the usual set of updates, typo fixes, and
  more"

* tag 'docs-4.9' of git://git.lwn.net/linux: (120 commits)
  URL changed for Linux Foundation TAB
  dax : Fix documentation with respect to struct pages
  iio: Documentation: Correct the path used to create triggers.
  docs: Remove space-before-label guidance from CodingStyle
  docs-rst: add inter-document cross references
  Documentation/email-clients.txt: convert it to ReST markup
  Documentation/kernel-docs.txt: reorder based on timestamp
  Documentation/kernel-docs.txt: Add dates for online docs
  Documentation/kernel-docs.txt: get rid of broken docs
  Documentation/kernel-docs.txt: move in-kernel docs
  Documentation/kernel-docs.txt: remove more legacy references
  Documentation/kernel-docs.txt: add two published books
  Documentation/kernel-docs.txt: sort books per publication date
  Documentation/kernel-docs.txt: adjust LDD references
  Documentation/kernel-docs.txt: some improvements on the ReST output
  Documentation/kernel-docs.txt: Consistent indenting: 4 spaces
  Documentation/kernel-docs.txt: Add 4 paper/book references
  Documentation/kernel-docs.txt: Improve layouting of book list
  Documentation/kernel-docs.txt: Remove offline or outdated entries
  docs: Clean up bare :: lines
  ...
parents 2105b9ff 3c76ff47
Hide whitespace changes
Inline Side-by-side
Showing with 5207 additions and 2720 deletions
Documentation/Changes
View file @ 02bafd96
.. _changes:
Minimal requerements to compile the Kernel
++++++++++++++++++++++++++++++++++++++++++
Intro Intro
===== =====
This document is designed to provide a list of the minimum levels of This document is designed to provide a list of the minimum levels of
software necessary to run the 3.0 kernels. software necessary to run the 4.x kernels.
This document is originally based on my "Changes" file for 2.0.x kernels This document is originally based on my "Changes" file for 2.0.x kernels
and therefore owes credit to the same people as that file (Jared Mauch, and therefore owes credit to the same people as that file (Jared Mauch,
...@@ -10,9 +15,9 @@ Axel Boldt, Alessandro Sigala, and countless other users all over the ...@@ -10,9 +15,9 @@ Axel Boldt, Alessandro Sigala, and countless other users all over the
'net). 'net).
Current Minimal Requirements Current Minimal Requirements
============================ ****************************
Upgrade to at *least* these software revisions before thinking you've Upgrade to at **least** these software revisions before thinking you've
encountered a bug! If you're unsure what version you're currently encountered a bug! If you're unsure what version you're currently
running, the suggested command should tell you. running, the suggested command should tell you.
...@@ -21,34 +26,40 @@ running a Linux kernel. Also, not all tools are necessary on all ...@@ -21,34 +26,40 @@ running a Linux kernel. Also, not all tools are necessary on all
systems; obviously, if you don't have any ISDN hardware, for example, systems; obviously, if you don't have any ISDN hardware, for example,
you probably needn't concern yourself with isdn4k-utils. you probably needn't concern yourself with isdn4k-utils.
o GNU C 3.2 # gcc --version ====================== =============== ========================================
o GNU make 3.80 # make --version Program Minimal version Command to check the version
o binutils 2.12 # ld -v ====================== =============== ========================================
o util-linux 2.10o # fdformat --version GNU C 3.2 gcc --version
o module-init-tools 0.9.10 # depmod -V GNU make 3.80 make --version
o e2fsprogs 1.41.4 # e2fsck -V binutils 2.12 ld -v
o jfsutils 1.1.3 # fsck.jfs -V util-linux 2.10o fdformat --version
o reiserfsprogs 3.6.3 # reiserfsck -V module-init-tools 0.9.10 depmod -V
o xfsprogs 2.6.0 # xfs_db -V e2fsprogs 1.41.4 e2fsck -V
o squashfs-tools 4.0 # mksquashfs -version jfsutils 1.1.3 fsck.jfs -V
o btrfs-progs 0.18 # btrfsck reiserfsprogs 3.6.3 reiserfsck -V
o pcmciautils 004 # pccardctl -V xfsprogs 2.6.0 xfs_db -V
o quota-tools 3.09 # quota -V squashfs-tools 4.0 mksquashfs -version
o PPP 2.4.0 # pppd --version btrfs-progs 0.18 btrfsck
o isdn4k-utils 3.1pre1 # isdnctrl 2>&1|grep version pcmciautils 004 pccardctl -V
o nfs-utils 1.0.5 # showmount --version quota-tools 3.09 quota -V
o procps 3.2.0 # ps --version PPP 2.4.0 pppd --version
o oprofile 0.9 # oprofiled --version isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version
o udev 081 # udevd --version nfs-utils 1.0.5 showmount --version
o grub 0.93 # grub --version || grub-install --version procps 3.2.0 ps --version
o mcelog 0.6 # mcelog --version oprofile 0.9 oprofiled --version
o iptables 1.4.2 # iptables -V udev 081 udevd --version
o openssl & libcrypto 1.0.0 # openssl version grub 0.93 grub --version || grub-install --version
o bc 1.06.95 # bc --version mcelog 0.6 mcelog --version
iptables 1.4.2 iptables -V
openssl & libcrypto 1.0.0 openssl version
bc 1.06.95 bc --version
Sphinx\ [#f1]_ 1.2 sphinx-build --version
====================== =============== ========================================
.. [#f1] Sphinx is needed only to build the Kernel documentation
Kernel compilation Kernel compilation
================== ******************
GCC GCC
--- ---
...@@ -64,16 +75,16 @@ You will need GNU make 3.80 or later to build the kernel. ...@@ -64,16 +75,16 @@ You will need GNU make 3.80 or later to build the kernel.
Binutils Binutils
-------- --------
Linux on IA-32 has recently switched from using as86 to using gas for Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for
assembling the 16-bit boot code, removing the need for as86 to compile assembling the 16-bit boot code, removing the need for ``as86`` to compile
your kernel. This change does, however, mean that you need a recent your kernel. This change does, however, mean that you need a recent
release of binutils. release of binutils.
Perl Perl
---- ----
You will need perl 5 and the following modules: Getopt::Long, Getopt::Std, You will need perl 5 and the following modules: ``Getopt::Long``,
File::Basename, and File::Find to build the kernel. ``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel.
BC BC
-- --
...@@ -93,7 +104,7 @@ and higher. ...@@ -93,7 +104,7 @@ and higher.
System utilities System utilities
================ ****************
Architectural changes Architectural changes
--------------------- ---------------------
...@@ -115,7 +126,7 @@ well as the desired DocBook stylesheets. ...@@ -115,7 +126,7 @@ well as the desired DocBook stylesheets.
Util-linux Util-linux
---------- ----------
New versions of util-linux provide *fdisk support for larger disks, New versions of util-linux provide ``fdisk`` support for larger disks,
support new options to mount, recognize more supported partition support new options to mount, recognize more supported partition
types, have a fdformat which works with 2.4 kernels, and similar goodies. types, have a fdformat which works with 2.4 kernels, and similar goodies.
You'll probably want to upgrade. You'll probably want to upgrade.
...@@ -125,54 +136,57 @@ Ksymoops ...@@ -125,54 +136,57 @@ Ksymoops
If the unthinkable happens and your kernel oopses, you may need the If the unthinkable happens and your kernel oopses, you may need the
ksymoops tool to decode it, but in most cases you don't. ksymoops tool to decode it, but in most cases you don't.
It is generally preferred to build the kernel with CONFIG_KALLSYMS so It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so
that it produces readable dumps that can be used as-is (this also that it produces readable dumps that can be used as-is (this also
produces better output than ksymoops). If for some reason your kernel produces better output than ksymoops). If for some reason your kernel
is not build with CONFIG_KALLSYMS and you have no way to rebuild and is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and
reproduce the Oops with that option, then you can still decode that Oops reproduce the Oops with that option, then you can still decode that Oops
with ksymoops. with ksymoops.
Module-Init-Tools Module-Init-Tools
----------------- -----------------
A new module loader is now in the kernel that requires module-init-tools A new module loader is now in the kernel that requires ``module-init-tools``
to use. It is backward compatible with the 2.4.x series kernels. to use. It is backward compatible with the 2.4.x series kernels.
Mkinitrd Mkinitrd
-------- --------
These changes to the /lib/modules file tree layout also require that These changes to the ``/lib/modules`` file tree layout also require that
mkinitrd be upgraded. mkinitrd be upgraded.
E2fsprogs E2fsprogs
--------- ---------
The latest version of e2fsprogs fixes several bugs in fsck and The latest version of ``e2fsprogs`` fixes several bugs in fsck and
debugfs. Obviously, it's a good idea to upgrade. debugfs. Obviously, it's a good idea to upgrade.
JFSutils JFSutils
-------- --------
The jfsutils package contains the utilities for the file system. The ``jfsutils`` package contains the utilities for the file system.
The following utilities are available: The following utilities are available:
o fsck.jfs - initiate replay of the transaction log, and check
- ``fsck.jfs`` - initiate replay of the transaction log, and check
and repair a JFS formatted partition. and repair a JFS formatted partition.
o mkfs.jfs - create a JFS formatted partition.
o other file system utilities are also available in this package. - ``mkfs.jfs`` - create a JFS formatted partition.
- other file system utilities are also available in this package.
Reiserfsprogs Reiserfsprogs
------------- -------------
The reiserfsprogs package should be used for reiserfs-3.6.x The reiserfsprogs package should be used for reiserfs-3.6.x
(Linux kernels 2.4.x). It is a combined package and contains working (Linux kernels 2.4.x). It is a combined package and contains working
versions of mkreiserfs, resize_reiserfs, debugreiserfs and versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and
reiserfsck. These utils work on both i386 and alpha platforms. ``reiserfsck``. These utils work on both i386 and alpha platforms.
Xfsprogs Xfsprogs
-------- --------
The latest version of xfsprogs contains mkfs.xfs, xfs_db, and the The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the
xfs_repair utilities, among others, for the XFS filesystem. It is ``xfs_repair`` utilities, among others, for the XFS filesystem. It is
architecture independent and any version from 2.0.0 onward should architecture independent and any version from 2.0.0 onward should
work correctly with this version of the XFS kernel code (2.6.0 or work correctly with this version of the XFS kernel code (2.6.0 or
later is recommended, due to some significant improvements). later is recommended, due to some significant improvements).
...@@ -180,7 +194,7 @@ later is recommended, due to some significant improvements). ...@@ -180,7 +194,7 @@ later is recommended, due to some significant improvements).
PCMCIAutils PCMCIAutils
----------- -----------
PCMCIAutils replaces pcmcia-cs. It properly sets up PCMCIAutils replaces ``pcmcia-cs``. It properly sets up
PCMCIA sockets at system startup and loads the appropriate modules PCMCIA sockets at system startup and loads the appropriate modules
for 16-bit PCMCIA devices if the kernel is modularized and the hotplug for 16-bit PCMCIA devices if the kernel is modularized and the hotplug
subsystem is used. subsystem is used.
...@@ -198,19 +212,20 @@ Intel IA32 microcode ...@@ -198,19 +212,20 @@ Intel IA32 microcode
A driver has been added to allow updating of Intel IA32 microcode, A driver has been added to allow updating of Intel IA32 microcode,
accessible as a normal (misc) character device. If you are not using accessible as a normal (misc) character device. If you are not using
udev you may need to: udev you may need to::
mkdir /dev/cpu mkdir /dev/cpu
mknod /dev/cpu/microcode c 10 184 mknod /dev/cpu/microcode c 10 184
chmod 0644 /dev/cpu/microcode chmod 0644 /dev/cpu/microcode
as root before you can use this. You'll probably also want to as root before you can use this. You'll probably also want to
get the user-space microcode_ctl utility to use with this. get the user-space microcode_ctl utility to use with this.
udev udev
---- ----
udev is a userspace application for populating /dev dynamically with
only entries for devices actually present. udev replaces the basic ``udev`` is a userspace application for populating ``/dev`` dynamically with
only entries for devices actually present. ``udev`` replaces the basic
functionality of devfs, while allowing persistent device naming for functionality of devfs, while allowing persistent device naming for
devices. devices.
...@@ -218,10 +233,10 @@ FUSE ...@@ -218,10 +233,10 @@ FUSE
---- ----
Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount
options 'direct_io' and 'kernel_cache' won't work. options ``direct_io`` and ``kernel_cache`` won't work.
Networking Networking
========== **********
General changes General changes
--------------- ---------------
...@@ -243,9 +258,9 @@ enable it to operate over diverse media layers. If you use PPP, ...@@ -243,9 +258,9 @@ enable it to operate over diverse media layers. If you use PPP,
upgrade pppd to at least 2.4.0. upgrade pppd to at least 2.4.0.
If you are not using udev, you must have the device file /dev/ppp If you are not using udev, you must have the device file /dev/ppp
which can be made by: which can be made by::
mknod /dev/ppp c 108 0 mknod /dev/ppp c 108 0
as root. as root.
...@@ -260,22 +275,22 @@ NFS-utils ...@@ -260,22 +275,22 @@ NFS-utils
In ancient (2.4 and earlier) kernels, the nfs server needed to know In ancient (2.4 and earlier) kernels, the nfs server needed to know
about any client that expected to be able to access files via NFS. This about any client that expected to be able to access files via NFS. This
information would be given to the kernel by "mountd" when the client information would be given to the kernel by ``mountd`` when the client
mounted the filesystem, or by "exportfs" at system startup. exportfs mounted the filesystem, or by ``exportfs`` at system startup. exportfs
would take information about active clients from /var/lib/nfs/rmtab. would take information about active clients from ``/var/lib/nfs/rmtab``.
This approach is quite fragile as it depends on rmtab being correct This approach is quite fragile as it depends on rmtab being correct
which is not always easy, particularly when trying to implement which is not always easy, particularly when trying to implement
fail-over. Even when the system is working well, rmtab suffers from fail-over. Even when the system is working well, ``rmtab`` suffers from
getting lots of old entries that never get removed. getting lots of old entries that never get removed.
With modern kernels we have the option of having the kernel tell mountd With modern kernels we have the option of having the kernel tell mountd
when it gets a request from an unknown host, and mountd can give when it gets a request from an unknown host, and mountd can give
appropriate export information to the kernel. This removes the appropriate export information to the kernel. This removes the
dependency on rmtab and means that the kernel only needs to know about dependency on ``rmtab`` and means that the kernel only needs to know about
currently active clients. currently active clients.
To enable this new functionality, you need to: To enable this new functionality, you need to::
mount -t nfsd nfsd /proc/fs/nfsd mount -t nfsd nfsd /proc/fs/nfsd
...@@ -287,8 +302,32 @@ mcelog ...@@ -287,8 +302,32 @@ mcelog
------ ------
On x86 kernels the mcelog utility is needed to process and log machine check On x86 kernels the mcelog utility is needed to process and log machine check
events when CONFIG_X86_MCE is enabled. Machine check events are errors reported events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors
by the CPU. Processing them is strongly encouraged. reported by the CPU. Processing them is strongly encouraged.
Kernel documentation
********************
Sphinx
------
The ReST markups currently used by the Documentation/ files are meant to be
built with ``Sphinx`` version 1.2 or upper. If you're desiring to build
PDF outputs, it is recommended to use version 1.4.6.
.. note::
Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX``
version 3.14159265. Depending on the distribution, you may also need
to install a series of ``texlive`` packages that provide the minimal
set of functionalities required for ``XeLaTex`` to work.
Other tools
-----------
In order to produce documentation from DocBook, you'll also need ``xmlto``.
Please notice, however, that we're currently migrating all documents to use
``Sphinx``.
Getting updated software Getting updated software
======================== ========================
...@@ -298,114 +337,149 @@ Kernel compilation ...@@ -298,114 +337,149 @@ Kernel compilation
gcc gcc
--- ---
o <ftp://ftp.gnu.org/gnu/gcc/>
- <ftp://ftp.gnu.org/gnu/gcc/>
Make Make
---- ----
o <ftp://ftp.gnu.org/gnu/make/>
- <ftp://ftp.gnu.org/gnu/make/>
Binutils Binutils
-------- --------
o <ftp://ftp.kernel.org/pub/linux/devel/binutils/>
- <ftp://ftp.kernel.org/pub/linux/devel/binutils/>
OpenSSL OpenSSL
------- -------
o <https://www.openssl.org/>
- <https://www.openssl.org/>
System utilities System utilities
**************** ****************
Util-linux Util-linux
---------- ----------
o <ftp://ftp.kernel.org/pub/linux/utils/util-linux/>
- <ftp://ftp.kernel.org/pub/linux/utils/util-linux/>
Ksymoops Ksymoops
-------- --------
o <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>
- <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>
Module-Init-Tools Module-Init-Tools
----------------- -----------------
o <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/>
- <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/>
Mkinitrd Mkinitrd
-------- --------
o <https://code.launchpad.net/initrd-tools/main>
- <https://code.launchpad.net/initrd-tools/main>
E2fsprogs E2fsprogs
--------- ---------
o <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz>
- <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz>
JFSutils JFSutils
-------- --------
o <http://jfs.sourceforge.net/>
- <http://jfs.sourceforge.net/>
Reiserfsprogs Reiserfsprogs
------------- -------------
o <http://www.kernel.org/pub/linux/utils/fs/reiserfs/>
- <http://www.kernel.org/pub/linux/utils/fs/reiserfs/>
Xfsprogs Xfsprogs
-------- --------
o <ftp://oss.sgi.com/projects/xfs/>
- <ftp://oss.sgi.com/projects/xfs/>
Pcmciautils Pcmciautils
----------- -----------
o <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/>
- <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/>
Quota-tools Quota-tools
---------- -----------
o <http://sourceforge.net/projects/linuxquota/>
- <http://sourceforge.net/projects/linuxquota/>
DocBook Stylesheets DocBook Stylesheets
------------------- -------------------
o <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
XMLTO XSLT Frontend XMLTO XSLT Frontend
------------------- -------------------
o <http://cyberelk.net/tim/xmlto/>
- <http://cyberelk.net/tim/xmlto/>
Intel P6 microcode Intel P6 microcode
------------------ ------------------
o <https://downloadcenter.intel.com/>
- <https://downloadcenter.intel.com/>
udev udev
---- ----
o <http://www.freedesktop.org/software/systemd/man/udev.html>
- <http://www.freedesktop.org/software/systemd/man/udev.html>
FUSE FUSE
---- ----
o <http://sourceforge.net/projects/fuse>
- <http://sourceforge.net/projects/fuse>
mcelog mcelog
------ ------
o <http://www.mcelog.org/>
- <http://www.mcelog.org/>
Networking Networking
********** **********
PPP PPP
--- ---
o <ftp://ftp.samba.org/pub/ppp/>
- <ftp://ftp.samba.org/pub/ppp/>
Isdn4k-utils Isdn4k-utils
------------ ------------
o <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
- <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
NFS-utils NFS-utils
--------- ---------
o <http://sourceforge.net/project/showfiles.php?group_id=14>
- <http://sourceforge.net/project/showfiles.php?group_id=14>
Iptables Iptables
-------- --------
o <http://www.iptables.org/downloads.html>
- <http://www.iptables.org/downloads.html>
Ip-route2 Ip-route2
--------- ---------
o <https://www.kernel.org/pub/linux/utils/net/iproute2/>
- <https://www.kernel.org/pub/linux/utils/net/iproute2/>
OProfile OProfile
-------- --------
o <http://oprofile.sf.net/download/>
- <http://oprofile.sf.net/download/>
NFS-Utils NFS-Utils
--------- ---------
o <http://nfs.sourceforge.net/>
- <http://nfs.sourceforge.net/>
Kernel documentation
********************
Sphinx
------
- <http://www.sphinx-doc.org/>
Documentation/CodeOfConflict
View file @ 02bafd96
...@@ -19,7 +19,7 @@ please contact the Linux Foundation's Technical Advisory Board at ...@@ -19,7 +19,7 @@ please contact the Linux Foundation's Technical Advisory Board at
will work to resolve the issue to the best of their ability. For more will work to resolve the issue to the best of their ability. For more
information on who is on the Technical Advisory Board and what their information on who is on the Technical Advisory Board and what their
role is, please see: role is, please see:
http://www.linuxfoundation.org/programs/advisory-councils/tab http://www.linuxfoundation.org/projects/linux/tab
As a reviewer of code, please strive to keep things civil and focused on As a reviewer of code, please strive to keep things civil and focused on
the technical issues involved. We are all humans, and frustrations can the technical issues involved. We are all humans, and frustrations can
......
Documentation/CodingStyle
View file @ 02bafd96
.. _codingstyle:
Linux kernel coding style Linux kernel coding style
=========================
This is a short document describing the preferred coding style for the This is a short document describing the preferred coding style for the
linux kernel. Coding style is very personal, and I won't _force_ my linux kernel. Coding style is very personal, and I won't **force** my
views on anybody, but this is what goes for anything that I have to be views on anybody, but this is what goes for anything that I have to be
able to maintain, and I'd prefer it for most other things too. Please able to maintain, and I'd prefer it for most other things too. Please
at least consider the points made here. at least consider the points made here.
...@@ -13,7 +15,8 @@ and NOT read it. Burn them, it's a great symbolic gesture. ...@@ -13,7 +15,8 @@ and NOT read it. Burn them, it's a great symbolic gesture.
Anyway, here goes: Anyway, here goes:
Chapter 1: Indentation 1) Indentation
--------------
Tabs are 8 characters, and thus indentations are also 8 characters. Tabs are 8 characters, and thus indentations are also 8 characters.
There are heretic movements that try to make indentations 4 (or even 2!) There are heretic movements that try to make indentations 4 (or even 2!)
...@@ -36,8 +39,10 @@ benefit of warning you when you're nesting your functions too deep. ...@@ -36,8 +39,10 @@ benefit of warning you when you're nesting your functions too deep.
Heed that warning. Heed that warning.
The preferred way to ease multiple indentation levels in a switch statement is The preferred way to ease multiple indentation levels in a switch statement is
to align the "switch" and its subordinate "case" labels in the same column to align the ``switch`` and its subordinate ``case`` labels in the same column
instead of "double-indenting" the "case" labels. E.g.: instead of ``double-indenting`` the ``case`` labels. E.g.:
.. code-block:: c
switch (suffix) { switch (suffix) {
case 'G': case 'G':
...@@ -59,6 +64,8 @@ instead of "double-indenting" the "case" labels. E.g.: ...@@ -59,6 +64,8 @@ instead of "double-indenting" the "case" labels. E.g.:
Don't put multiple statements on a single line unless you have Don't put multiple statements on a single line unless you have
something to hide: something to hide:
.. code-block:: c
if (condition) do_this; if (condition) do_this;
do_something_everytime; do_something_everytime;
...@@ -71,7 +78,8 @@ used for indentation, and the above example is deliberately broken. ...@@ -71,7 +78,8 @@ used for indentation, and the above example is deliberately broken.
Get a decent editor and don't leave whitespace at the end of lines. Get a decent editor and don't leave whitespace at the end of lines.
Chapter 2: Breaking long lines and strings 2) Breaking long lines and strings
----------------------------------
Coding style is all about readability and maintainability using commonly Coding style is all about readability and maintainability using commonly
available tools. available tools.
...@@ -87,7 +95,8 @@ with a long argument list. However, never break user-visible strings such as ...@@ -87,7 +95,8 @@ with a long argument list. However, never break user-visible strings such as
printk messages, because that breaks the ability to grep for them. printk messages, because that breaks the ability to grep for them.
Chapter 3: Placing Braces and Spaces 3) Placing Braces and Spaces
----------------------------
The other issue that always comes up in C styling is the placement of The other issue that always comes up in C styling is the placement of
braces. Unlike the indent size, there are few technical reasons to braces. Unlike the indent size, there are few technical reasons to
...@@ -95,6 +104,8 @@ choose one placement strategy over the other, but the preferred way, as ...@@ -95,6 +104,8 @@ choose one placement strategy over the other, but the preferred way, as
shown to us by the prophets Kernighan and Ritchie, is to put the opening shown to us by the prophets Kernighan and Ritchie, is to put the opening
brace last on the line, and put the closing brace first, thusly: brace last on the line, and put the closing brace first, thusly:
.. code-block:: c
if (x is true) { if (x is true) {
we do y we do y
} }
...@@ -102,6 +113,8 @@ brace last on the line, and put the closing brace first, thusly: ...@@ -102,6 +113,8 @@ brace last on the line, and put the closing brace first, thusly:
This applies to all non-function statement blocks (if, switch, for, This applies to all non-function statement blocks (if, switch, for,
while, do). E.g.: while, do). E.g.:
.. code-block:: c
switch (action) { switch (action) {
case KOBJ_ADD: case KOBJ_ADD:
return "add"; return "add";
...@@ -116,6 +129,8 @@ while, do). E.g.: ...@@ -116,6 +129,8 @@ while, do). E.g.:
However, there is one special case, namely functions: they have the However, there is one special case, namely functions: they have the
opening brace at the beginning of the next line, thus: opening brace at the beginning of the next line, thus:
.. code-block:: c
int function(int x) int function(int x)
{ {
body of function body of function
...@@ -123,20 +138,24 @@ opening brace at the beginning of the next line, thus: ...@@ -123,20 +138,24 @@ opening brace at the beginning of the next line, thus:
Heretic people all over the world have claimed that this inconsistency Heretic people all over the world have claimed that this inconsistency
is ... well ... inconsistent, but all right-thinking people know that is ... well ... inconsistent, but all right-thinking people know that
(a) K&R are _right_ and (b) K&R are right. Besides, functions are (a) K&R are **right** and (b) K&R are right. Besides, functions are
special anyway (you can't nest them in C). special anyway (you can't nest them in C).
Note that the closing brace is empty on a line of its own, _except_ in Note that the closing brace is empty on a line of its own, **except** in
the cases where it is followed by a continuation of the same statement, the cases where it is followed by a continuation of the same statement,
ie a "while" in a do-statement or an "else" in an if-statement, like ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
this: this:
.. code-block:: c
do { do {
body of do-loop body of do-loop
} while (condition); } while (condition);
and and
.. code-block:: c
if (x == y) { if (x == y) {
.. ..
} else if (x > y) { } else if (x > y) {
...@@ -155,11 +174,15 @@ comments on. ...@@ -155,11 +174,15 @@ comments on.
Do not unnecessarily use braces where a single statement will do. Do not unnecessarily use braces where a single statement will do.
.. code-block:: c
if (condition) if (condition)
action(); action();
and and
.. code-block:: none
if (condition) if (condition)
do_this(); do_this();
else else
...@@ -168,6 +191,8 @@ and ...@@ -168,6 +191,8 @@ and
This does not apply if only one branch of a conditional statement is a single This does not apply if only one branch of a conditional statement is a single
statement; in the latter case use braces in both branches: statement; in the latter case use braces in both branches:
.. code-block:: c
if (condition) { if (condition) {
do_this(); do_this();
do_that(); do_that();
...@@ -175,57 +200,67 @@ statement; in the latter case use braces in both branches: ...@@ -175,57 +200,67 @@ statement; in the latter case use braces in both branches:
otherwise(); otherwise();
} }
3.1: Spaces 3.1) Spaces
***********
Linux kernel style for use of spaces depends (mostly) on Linux kernel style for use of spaces depends (mostly) on
function-versus-keyword usage. Use a space after (most) keywords. The function-versus-keyword usage. Use a space after (most) keywords. The
notable exceptions are sizeof, typeof, alignof, and __attribute__, which look notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
somewhat like functions (and are usually used with parentheses in Linux, somewhat like functions (and are usually used with parentheses in Linux,
although they are not required in the language, as in: "sizeof info" after although they are not required in the language, as in: ``sizeof info`` after
"struct fileinfo info;" is declared). ``struct fileinfo info;`` is declared).
So use a space after these keywords: So use a space after these keywords::
if, switch, case, for, do, while if, switch, case, for, do, while
but not with sizeof, typeof, alignof, or __attribute__. E.g., but not with sizeof, typeof, alignof, or __attribute__. E.g.,
.. code-block:: c
s = sizeof(struct file); s = sizeof(struct file);
Do not add spaces around (inside) parenthesized expressions. This example is Do not add spaces around (inside) parenthesized expressions. This example is
*bad*: **bad**:
.. code-block:: c
s = sizeof( struct file ); s = sizeof( struct file );
When declaring pointer data or a function that returns a pointer type, the When declaring pointer data or a function that returns a pointer type, the
preferred use of '*' is adjacent to the data name or function name and not preferred use of ``*`` is adjacent to the data name or function name and not
adjacent to the type name. Examples: adjacent to the type name. Examples:
.. code-block:: c
char *linux_banner; char *linux_banner;
unsigned long long memparse(char *ptr, char **retptr); unsigned long long memparse(char *ptr, char **retptr);
char *match_strdup(substring_t *s); char *match_strdup(substring_t *s);
Use one space around (on each side of) most binary and ternary operators, Use one space around (on each side of) most binary and ternary operators,
such as any of these: such as any of these::
= + - < > * / % | & ^ <= >= == != ? : = + - < > * / % | & ^ <= >= == != ? :
but no space after unary operators: but no space after unary operators::
& * + - ~ ! sizeof typeof alignof __attribute__ defined & * + - ~ ! sizeof typeof alignof __attribute__ defined
no space before the postfix increment & decrement unary operators: no space before the postfix increment & decrement unary operators::
++ -- ++ --
no space after the prefix increment & decrement unary operators: no space after the prefix increment & decrement unary operators::
++ -- ++ --
and no space around the '.' and "->" structure member operators. and no space around the ``.`` and ``->`` structure member operators.
Do not leave trailing whitespace at the ends of lines. Some editors with Do not leave trailing whitespace at the ends of lines. Some editors with
"smart" indentation will insert whitespace at the beginning of new lines as ``smart`` indentation will insert whitespace at the beginning of new lines as
appropriate, so you can start typing the next line of code right away. appropriate, so you can start typing the next line of code right away.
However, some such editors do not remove the whitespace if you end up not However, some such editors do not remove the whitespace if you end up not
putting a line of code there, such as if you leave a blank line. As a result, putting a line of code there, such as if you leave a blank line. As a result,
...@@ -237,22 +272,23 @@ of patches, this may make later patches in the series fail by changing their ...@@ -237,22 +272,23 @@ of patches, this may make later patches in the series fail by changing their
context lines. context lines.
Chapter 4: Naming 4) Naming
---------
C is a Spartan language, and so should your naming be. Unlike Modula-2 C is a Spartan language, and so should your naming be. Unlike Modula-2
and Pascal programmers, C programmers do not use cute names like and Pascal programmers, C programmers do not use cute names like
ThisVariableIsATemporaryCounter. A C programmer would call that ThisVariableIsATemporaryCounter. A C programmer would call that
variable "tmp", which is much easier to write, and not the least more variable ``tmp``, which is much easier to write, and not the least more
difficult to understand. difficult to understand.
HOWEVER, while mixed-case names are frowned upon, descriptive names for HOWEVER, while mixed-case names are frowned upon, descriptive names for
global variables are a must. To call a global function "foo" is a global variables are a must. To call a global function ``foo`` is a
shooting offense. shooting offense.
GLOBAL variables (to be used only if you _really_ need them) need to GLOBAL variables (to be used only if you **really** need them) need to
have descriptive names, as do global functions. If you have a function have descriptive names, as do global functions. If you have a function
that counts the number of active users, you should call that that counts the number of active users, you should call that
"count_active_users()" or similar, you should _not_ call it "cntusr()". ``count_active_users()`` or similar, you should **not** call it ``cntusr()``.
Encoding the type of a function into the name (so-called Hungarian Encoding the type of a function into the name (so-called Hungarian
notation) is brain damaged - the compiler knows the types anyway and can notation) is brain damaged - the compiler knows the types anyway and can
...@@ -260,9 +296,9 @@ check those, and it only confuses the programmer. No wonder MicroSoft ...@@ -260,9 +296,9 @@ check those, and it only confuses the programmer. No wonder MicroSoft
makes buggy programs. makes buggy programs.
LOCAL variable names should be short, and to the point. If you have LOCAL variable names should be short, and to the point. If you have
some random integer loop counter, it should probably be called "i". some random integer loop counter, it should probably be called ``i``.
Calling it "loop_counter" is non-productive, if there is no chance of it Calling it ``loop_counter`` is non-productive, if there is no chance of it
being mis-understood. Similarly, "tmp" can be just about any type of being mis-understood. Similarly, ``tmp`` can be just about any type of
variable that is used to hold a temporary value. variable that is used to hold a temporary value.
If you are afraid to mix up your local variable names, you have another If you are afraid to mix up your local variable names, you have another
...@@ -270,59 +306,69 @@ problem, which is called the function-growth-hormone-imbalance syndrome. ...@@ -270,59 +306,69 @@ problem, which is called the function-growth-hormone-imbalance syndrome.
See chapter 6 (Functions). See chapter 6 (Functions).
Chapter 5: Typedefs 5) Typedefs
-----------
Please don't use things like ``vps_t``.
It's a **mistake** to use typedef for structures and pointers. When you see a
.. code-block:: c
Please don't use things like "vps_t".
It's a _mistake_ to use typedef for structures and pointers. When you see a
vps_t a; vps_t a;
in the source, what does it mean? in the source, what does it mean?
In contrast, if it says In contrast, if it says
.. code-block:: c
struct virtual_container *a; struct virtual_container *a;
you can actually tell what "a" is. you can actually tell what ``a`` is.
Lots of people think that typedefs "help readability". Not so. They are Lots of people think that typedefs ``help readability``. Not so. They are
useful only for: useful only for:
(a) totally opaque objects (where the typedef is actively used to _hide_ (a) totally opaque objects (where the typedef is actively used to **hide**
what the object is). what the object is).
Example: "pte_t" etc. opaque objects that you can only access using Example: ``pte_t`` etc. opaque objects that you can only access using
the proper accessor functions. the proper accessor functions.
NOTE! Opaqueness and "accessor functions" are not good in themselves. .. note::
The reason we have them for things like pte_t etc. is that there
really is absolutely _zero_ portably accessible information there. Opaqueness and ``accessor functions`` are not good in themselves.
The reason we have them for things like pte_t etc. is that there
really is absolutely **zero** portably accessible information there.
(b) Clear integer types, where the abstraction _helps_ avoid confusion (b) Clear integer types, where the abstraction **helps** avoid confusion
whether it is "int" or "long". whether it is ``int`` or ``long``.
u8/u16/u32 are perfectly fine typedefs, although they fit into u8/u16/u32 are perfectly fine typedefs, although they fit into
category (d) better than here. category (d) better than here.
NOTE! Again - there needs to be a _reason_ for this. If something is .. note::
"unsigned long", then there's no reason to do
Again - there needs to be a **reason** for this. If something is
``unsigned long``, then there's no reason to do
typedef unsigned long myflags_t; typedef unsigned long myflags_t;
but if there is a clear reason for why it under certain circumstances but if there is a clear reason for why it under certain circumstances
might be an "unsigned int" and under other configurations might be might be an ``unsigned int`` and under other configurations might be
"unsigned long", then by all means go ahead and use a typedef. ``unsigned long``, then by all means go ahead and use a typedef.
(c) when you use sparse to literally create a _new_ type for (c) when you use sparse to literally create a **new** type for
type-checking. type-checking.
(d) New types which are identical to standard C99 types, in certain (d) New types which are identical to standard C99 types, in certain
exceptional circumstances. exceptional circumstances.
Although it would only take a short amount of time for the eyes and Although it would only take a short amount of time for the eyes and
brain to become accustomed to the standard types like 'uint32_t', brain to become accustomed to the standard types like ``uint32_t``,
some people object to their use anyway. some people object to their use anyway.
Therefore, the Linux-specific 'u8/u16/u32/u64' types and their Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
signed equivalents which are identical to standard types are signed equivalents which are identical to standard types are
permitted -- although they are not mandatory in new code of your permitted -- although they are not mandatory in new code of your
own. own.
...@@ -333,7 +379,7 @@ useful only for: ...@@ -333,7 +379,7 @@ useful only for:
(e) Types safe for use in userspace. (e) Types safe for use in userspace.
In certain structures which are visible to userspace, we cannot In certain structures which are visible to userspace, we cannot
require C99 types and cannot use the 'u32' form above. Thus, we require C99 types and cannot use the ``u32`` form above. Thus, we
use __u32 and similar types in all structures which are shared use __u32 and similar types in all structures which are shared
with userspace. with userspace.
...@@ -341,10 +387,11 @@ Maybe there are other cases too, but the rule should basically be to NEVER ...@@ -341,10 +387,11 @@ Maybe there are other cases too, but the rule should basically be to NEVER
EVER use a typedef unless you can clearly match one of those rules. EVER use a typedef unless you can clearly match one of those rules.
In general, a pointer, or a struct that has elements that can reasonably In general, a pointer, or a struct that has elements that can reasonably
be directly accessed should _never_ be a typedef. be directly accessed should **never** be a typedef.
Chapter 6: Functions 6) Functions
------------
Functions should be short and sweet, and do just one thing. They should Functions should be short and sweet, and do just one thing. They should
fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
...@@ -372,8 +419,10 @@ and it gets confused. You know you're brilliant, but maybe you'd like ...@@ -372,8 +419,10 @@ and it gets confused. You know you're brilliant, but maybe you'd like
to understand what you did 2 weeks from now. to understand what you did 2 weeks from now.
In source files, separate functions with one blank line. If the function is In source files, separate functions with one blank line. If the function is
exported, the EXPORT* macro for it should follow immediately after the closing exported, the **EXPORT** macro for it should follow immediately after the
function brace line. E.g.: closing function brace line. E.g.:
.. code-block:: c
int system_is_up(void) int system_is_up(void)
{ {
...@@ -386,7 +435,8 @@ Although this is not required by the C language, it is preferred in Linux ...@@ -386,7 +435,8 @@ Although this is not required by the C language, it is preferred in Linux
because it is a simple way to add valuable information for the reader. because it is a simple way to add valuable information for the reader.
Chapter 7: Centralized exiting of functions 7) Centralized exiting of functions
-----------------------------------
Albeit deprecated by some people, the equivalent of the goto statement is Albeit deprecated by some people, the equivalent of the goto statement is
used frequently by compilers in form of the unconditional jump instruction. used frequently by compilers in form of the unconditional jump instruction.
...@@ -396,18 +446,21 @@ locations and some common work such as cleanup has to be done. If there is no ...@@ -396,18 +446,21 @@ locations and some common work such as cleanup has to be done. If there is no
cleanup needed then just return directly. cleanup needed then just return directly.
Choose label names which say what the goto does or why the goto exists. An Choose label names which say what the goto does or why the goto exists. An
example of a good name could be "out_buffer:" if the goto frees "buffer". Avoid example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``.
using GW-BASIC names like "err1:" and "err2:". Also don't name them after the Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to
goto location like "err_kmalloc_failed:" renumber them if you ever add or remove exit paths, and they make correctness
difficult to verify anyway.
The rationale for using gotos is: The rationale for using gotos is:
- unconditional statements are easier to understand and follow - unconditional statements are easier to understand and follow
- nesting is reduced - nesting is reduced
- errors by not updating individual exit points when making - errors by not updating individual exit points when making
modifications are prevented modifications are prevented
- saves the compiler work to optimize redundant code away ;) - saves the compiler work to optimize redundant code away ;)
.. code-block:: c
int fun(int a) int fun(int a)
{ {
int result = 0; int result = 0;
...@@ -425,27 +478,41 @@ The rationale for using gotos is: ...@@ -425,27 +478,41 @@ The rationale for using gotos is:
goto out_buffer; goto out_buffer;
} }
... ...
out_buffer: out_free_buffer:
kfree(buffer); kfree(buffer);
return result; return result;
} }
A common type of bug to be aware of is "one err bugs" which look like this: A common type of bug to be aware of is ``one err bugs`` which look like this:
.. code-block:: c
err: err:
kfree(foo->bar); kfree(foo->bar);
kfree(foo); kfree(foo);
return ret; return ret;
The bug in this code is that on some exit paths "foo" is NULL. Normally the The bug in this code is that on some exit paths ``foo`` is NULL. Normally the
fix for this is to split it up into two error labels "err_bar:" and "err_foo:". fix for this is to split it up into two error labels ``err_free_bar:`` and
``err_free_foo:``:
.. code-block:: c
Chapter 8: Commenting err_free_bar:
kfree(foo->bar);
err_free_foo:
kfree(foo);
return ret;
Ideally you should simulate errors to test all exit paths.
8) Commenting
-------------
Comments are good, but there is also a danger of over-commenting. NEVER Comments are good, but there is also a danger of over-commenting. NEVER
try to explain HOW your code works in a comment: it's much better to try to explain HOW your code works in a comment: it's much better to
write the code so that the _working_ is obvious, and it's a waste of write the code so that the **working** is obvious, and it's a waste of
time to explain badly written code. time to explain badly written code.
Generally, you want your comments to tell WHAT your code does, not HOW. Generally, you want your comments to tell WHAT your code does, not HOW.
...@@ -461,11 +528,10 @@ When commenting the kernel API functions, please use the kernel-doc format. ...@@ -461,11 +528,10 @@ When commenting the kernel API functions, please use the kernel-doc format.
See the files Documentation/kernel-documentation.rst and scripts/kernel-doc See the files Documentation/kernel-documentation.rst and scripts/kernel-doc
for details. for details.
Linux style for comments is the C89 "/* ... */" style.
Don't use C99-style "// ..." comments.
The preferred style for long (multi-line) comments is: The preferred style for long (multi-line) comments is:
.. code-block:: c
/* /*
* This is the preferred style for multi-line * This is the preferred style for multi-line
* comments in the Linux kernel source code. * comments in the Linux kernel source code.
...@@ -478,6 +544,8 @@ The preferred style for long (multi-line) comments is: ...@@ -478,6 +544,8 @@ The preferred style for long (multi-line) comments is:
For files in net/ and drivers/net/ the preferred style for long (multi-line) For files in net/ and drivers/net/ the preferred style for long (multi-line)
comments is a little different. comments is a little different.
.. code-block:: c
/* The preferred comment style for files in net/ and drivers/net /* The preferred comment style for files in net/ and drivers/net
* looks like this. * looks like this.
* *
...@@ -491,10 +559,11 @@ multiple data declarations). This leaves you room for a small comment on each ...@@ -491,10 +559,11 @@ multiple data declarations). This leaves you room for a small comment on each
item, explaining its use. item, explaining its use.
Chapter 9: You've made a mess of it 9) You've made a mess of it
---------------------------
That's OK, we all do. You've probably been told by your long-time Unix That's OK, we all do. You've probably been told by your long-time Unix
user helper that "GNU emacs" automatically formats the C sources for user helper that ``GNU emacs`` automatically formats the C sources for
you, and you've noticed that yes, it does do that, but the defaults it you, and you've noticed that yes, it does do that, but the defaults it
uses are less than desirable (in fact, they are worse than random uses are less than desirable (in fact, they are worse than random
typing - an infinite number of monkeys typing into GNU emacs would never typing - an infinite number of monkeys typing into GNU emacs would never
...@@ -503,63 +572,66 @@ make a good program). ...@@ -503,63 +572,66 @@ make a good program).
So, you can either get rid of GNU emacs, or change it to use saner So, you can either get rid of GNU emacs, or change it to use saner
values. To do the latter, you can stick the following in your .emacs file: values. To do the latter, you can stick the following in your .emacs file:
(defun c-lineup-arglist-tabs-only (ignored) .. code-block:: none
"Line up argument lists by tabs, not spaces"
(let* ((anchor (c-langelem-pos c-syntactic-element)) (defun c-lineup-arglist-tabs-only (ignored)
(column (c-langelem-2nd-pos c-syntactic-element)) "Line up argument lists by tabs, not spaces"
(offset (- (1+ column) anchor)) (let* ((anchor (c-langelem-pos c-syntactic-element))
(steps (floor offset c-basic-offset))) (column (c-langelem-2nd-pos c-syntactic-element))
(* (max steps 1) (offset (- (1+ column) anchor))
c-basic-offset))) (steps (floor offset c-basic-offset)))
(* (max steps 1)
(add-hook 'c-mode-common-hook c-basic-offset)))
(lambda ()
;; Add kernel style (add-hook 'c-mode-common-hook
(c-add-style (lambda ()
"linux-tabs-only" ;; Add kernel style
'("linux" (c-offsets-alist (c-add-style
(arglist-cont-nonempty "linux-tabs-only"
c-lineup-gcc-asm-reg '("linux" (c-offsets-alist
c-lineup-arglist-tabs-only)))))) (arglist-cont-nonempty
c-lineup-gcc-asm-reg
(add-hook 'c-mode-hook c-lineup-arglist-tabs-only))))))
(lambda ()
(let ((filename (buffer-file-name))) (add-hook 'c-mode-hook
;; Enable kernel mode for the appropriate files (lambda ()
(when (and filename (let ((filename (buffer-file-name)))
(string-match (expand-file-name "~/src/linux-trees") ;; Enable kernel mode for the appropriate files
filename)) (when (and filename
(setq indent-tabs-mode t) (string-match (expand-file-name "~/src/linux-trees")
(setq show-trailing-whitespace t) filename))
(c-set-style "linux-tabs-only"))))) (setq indent-tabs-mode t)
(setq show-trailing-whitespace t)
(c-set-style "linux-tabs-only")))))
This will make emacs go better with the kernel coding style for C This will make emacs go better with the kernel coding style for C
files below ~/src/linux-trees. files below ``~/src/linux-trees``.
But even if you fail in getting emacs to do sane formatting, not But even if you fail in getting emacs to do sane formatting, not
everything is lost: use "indent". everything is lost: use ``indent``.
Now, again, GNU indent has the same brain-dead settings that GNU emacs Now, again, GNU indent has the same brain-dead settings that GNU emacs
has, which is why you need to give it a few command line options. has, which is why you need to give it a few command line options.
However, that's not too bad, because even the makers of GNU indent However, that's not too bad, because even the makers of GNU indent
recognize the authority of K&R (the GNU people aren't evil, they are recognize the authority of K&R (the GNU people aren't evil, they are
just severely misguided in this matter), so you just give indent the just severely misguided in this matter), so you just give indent the
options "-kr -i8" (stands for "K&R, 8 character indents"), or use options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
"scripts/Lindent", which indents in the latest style. ``scripts/Lindent``, which indents in the latest style.
"indent" has a lot of options, and especially when it comes to comment ``indent`` has a lot of options, and especially when it comes to comment
re-formatting you may want to take a look at the man page. But re-formatting you may want to take a look at the man page. But
remember: "indent" is not a fix for bad programming. remember: ``indent`` is not a fix for bad programming.
Chapter 10: Kconfig configuration files 10) Kconfig configuration files
-------------------------------
For all of the Kconfig* configuration files throughout the source tree, For all of the Kconfig* configuration files throughout the source tree,
the indentation is somewhat different. Lines under a "config" definition the indentation is somewhat different. Lines under a ``config`` definition
are indented with one tab, while help text is indented an additional two are indented with one tab, while help text is indented an additional two
spaces. Example: spaces. Example::
config AUDIT config AUDIT
bool "Auditing support" bool "Auditing support"
depends on NET depends on NET
help help
...@@ -569,9 +641,9 @@ config AUDIT ...@@ -569,9 +641,9 @@ config AUDIT
auditing without CONFIG_AUDITSYSCALL. auditing without CONFIG_AUDITSYSCALL.
Seriously dangerous features (such as write support for certain Seriously dangerous features (such as write support for certain
filesystems) should advertise this prominently in their prompt string: filesystems) should advertise this prominently in their prompt string::
config ADFS_FS_RW config ADFS_FS_RW
bool "ADFS write support (DANGEROUS)" bool "ADFS write support (DANGEROUS)"
depends on ADFS_FS depends on ADFS_FS
... ...
...@@ -580,41 +652,45 @@ For full documentation on the configuration files, see the file ...@@ -580,41 +652,45 @@ For full documentation on the configuration files, see the file
Documentation/kbuild/kconfig-language.txt. Documentation/kbuild/kconfig-language.txt.
Chapter 11: Data structures 11) Data structures
-------------------
Data structures that have visibility outside the single-threaded Data structures that have visibility outside the single-threaded
environment they are created and destroyed in should always have environment they are created and destroyed in should always have
reference counts. In the kernel, garbage collection doesn't exist (and reference counts. In the kernel, garbage collection doesn't exist (and
outside the kernel garbage collection is slow and inefficient), which outside the kernel garbage collection is slow and inefficient), which
means that you absolutely _have_ to reference count all your uses. means that you absolutely **have** to reference count all your uses.
Reference counting means that you can avoid locking, and allows multiple Reference counting means that you can avoid locking, and allows multiple
users to have access to the data structure in parallel - and not having users to have access to the data structure in parallel - and not having
to worry about the structure suddenly going away from under them just to worry about the structure suddenly going away from under them just
because they slept or did something else for a while. because they slept or did something else for a while.
Note that locking is _not_ a replacement for reference counting. Note that locking is **not** a replacement for reference counting.
Locking is used to keep data structures coherent, while reference Locking is used to keep data structures coherent, while reference
counting is a memory management technique. Usually both are needed, and counting is a memory management technique. Usually both are needed, and
they are not to be confused with each other. they are not to be confused with each other.
Many data structures can indeed have two levels of reference counting, Many data structures can indeed have two levels of reference counting,
when there are users of different "classes". The subclass count counts when there are users of different ``classes``. The subclass count counts
the number of subclass users, and decrements the global count just once the number of subclass users, and decrements the global count just once
when the subclass count goes to zero. when the subclass count goes to zero.
Examples of this kind of "multi-level-reference-counting" can be found in Examples of this kind of ``multi-level-reference-counting`` can be found in
memory management ("struct mm_struct": mm_users and mm_count), and in memory management (``struct mm_struct``: mm_users and mm_count), and in
filesystem code ("struct super_block": s_count and s_active). filesystem code (``struct super_block``: s_count and s_active).
Remember: if another thread can find your data structure, and you don't Remember: if another thread can find your data structure, and you don't
have a reference count on it, you almost certainly have a bug. have a reference count on it, you almost certainly have a bug.
Chapter 12: Macros, Enums and RTL 12) Macros, Enums and RTL
-------------------------
Names of macros defining constants and labels in enums are capitalized. Names of macros defining constants and labels in enums are capitalized.
.. code-block:: c
#define CONSTANT 0x12345 #define CONSTANT 0x12345
Enums are preferred when defining several related constants. Enums are preferred when defining several related constants.
...@@ -626,7 +702,9 @@ Generally, inline functions are preferable to macros resembling functions. ...@@ -626,7 +702,9 @@ Generally, inline functions are preferable to macros resembling functions.
Macros with multiple statements should be enclosed in a do - while block: Macros with multiple statements should be enclosed in a do - while block:
#define macrofun(a, b, c) \ .. code-block:: c
#define macrofun(a, b, c) \
do { \ do { \
if (a == 5) \ if (a == 5) \
do_this(b, c); \ do_this(b, c); \
...@@ -636,17 +714,21 @@ Things to avoid when using macros: ...@@ -636,17 +714,21 @@ Things to avoid when using macros:
1) macros that affect control flow: 1) macros that affect control flow:
.. code-block:: c
#define FOO(x) \ #define FOO(x) \
do { \ do { \
if (blah(x) < 0) \ if (blah(x) < 0) \
return -EBUGGERED; \ return -EBUGGERED; \
} while (0) } while (0)
is a _very_ bad idea. It looks like a function call but exits the "calling" is a **very** bad idea. It looks like a function call but exits the ``calling``
function; don't break the internal parsers of those who will read the code. function; don't break the internal parsers of those who will read the code.
2) macros that depend on having a local variable with a magic name: 2) macros that depend on having a local variable with a magic name:
.. code-block:: c
#define FOO(val) bar(index, val) #define FOO(val) bar(index, val)
might look like a good thing, but it's confusing as hell when one reads the might look like a good thing, but it's confusing as hell when one reads the
...@@ -659,18 +741,22 @@ bite you if somebody e.g. turns FOO into an inline function. ...@@ -659,18 +741,22 @@ bite you if somebody e.g. turns FOO into an inline function.
must enclose the expression in parentheses. Beware of similar issues with must enclose the expression in parentheses. Beware of similar issues with
macros using parameters. macros using parameters.
.. code-block:: c
#define CONSTANT 0x4000 #define CONSTANT 0x4000
#define CONSTEXP (CONSTANT | 3) #define CONSTEXP (CONSTANT | 3)
5) namespace collisions when defining local variables in macros resembling 5) namespace collisions when defining local variables in macros resembling
functions: functions:
#define FOO(x) \ .. code-block:: c
({ \
typeof(x) ret; \ #define FOO(x) \
ret = calc_ret(x); \ ({ \
(ret); \ typeof(x) ret; \
}) ret = calc_ret(x); \
(ret); \
})
ret is a common name for a local variable - __foo_ret is less likely ret is a common name for a local variable - __foo_ret is less likely
to collide with an existing variable. to collide with an existing variable.
...@@ -679,11 +765,12 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also ...@@ -679,11 +765,12 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also
covers RTL which is used frequently with assembly language in the kernel. covers RTL which is used frequently with assembly language in the kernel.
Chapter 13: Printing kernel messages 13) Printing kernel messages
----------------------------
Kernel developers like to be seen as literate. Do mind the spelling Kernel developers like to be seen as literate. Do mind the spelling
of kernel messages to make a good impression. Do not use crippled of kernel messages to make a good impression. Do not use crippled
words like "dont"; use "do not" or "don't" instead. Make the messages words like ``dont``; use ``do not`` or ``don't`` instead. Make the messages
concise, clear, and unambiguous. concise, clear, and unambiguous.
Kernel messages do not have to be terminated with a period. Kernel messages do not have to be terminated with a period.
...@@ -713,7 +800,8 @@ already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be ...@@ -713,7 +800,8 @@ already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
used. used.
Chapter 14: Allocating memory 14) Allocating memory
---------------------
The kernel provides the following general purpose memory allocators: The kernel provides the following general purpose memory allocators:
kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
...@@ -722,6 +810,8 @@ about them. ...@@ -722,6 +810,8 @@ about them.
The preferred form for passing a size of a struct is the following: The preferred form for passing a size of a struct is the following:
.. code-block:: c
p = kmalloc(sizeof(*p), ...); p = kmalloc(sizeof(*p), ...);
The alternative form where struct name is spelled out hurts readability and The alternative form where struct name is spelled out hurts readability and
...@@ -734,20 +824,25 @@ language. ...@@ -734,20 +824,25 @@ language.
The preferred form for allocating an array is the following: The preferred form for allocating an array is the following:
.. code-block:: c
p = kmalloc_array(n, sizeof(...), ...); p = kmalloc_array(n, sizeof(...), ...);
The preferred form for allocating a zeroed array is the following: The preferred form for allocating a zeroed array is the following:
.. code-block:: c
p = kcalloc(n, sizeof(...), ...); p = kcalloc(n, sizeof(...), ...);
Both forms check for overflow on the allocation size n * sizeof(...), Both forms check for overflow on the allocation size n * sizeof(...),
and return NULL if that occurred. and return NULL if that occurred.
Chapter 15: The inline disease 15) The inline disease
----------------------
There appears to be a common misperception that gcc has a magic "make me There appears to be a common misperception that gcc has a magic "make me
faster" speedup option called "inline". While the use of inlines can be faster" speedup option called ``inline``. While the use of inlines can be
appropriate (for example as a means of replacing macros, see Chapter 12), it appropriate (for example as a means of replacing macros, see Chapter 12), it
very often is not. Abundant use of the inline keyword leads to a much bigger very often is not. Abundant use of the inline keyword leads to a much bigger
kernel, which in turn slows the system as a whole down, due to a bigger kernel, which in turn slows the system as a whole down, due to a bigger
...@@ -771,26 +866,27 @@ appears outweighs the potential value of the hint that tells gcc to do ...@@ -771,26 +866,27 @@ appears outweighs the potential value of the hint that tells gcc to do
something it would have done anyway. something it would have done anyway.
Chapter 16: Function return values and names 16) Function return values and names
------------------------------------
Functions can return values of many different kinds, and one of the Functions can return values of many different kinds, and one of the
most common is a value indicating whether the function succeeded or most common is a value indicating whether the function succeeded or
failed. Such a value can be represented as an error-code integer failed. Such a value can be represented as an error-code integer
(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure, (-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
non-zero = success). non-zero = success).
Mixing up these two sorts of representations is a fertile source of Mixing up these two sorts of representations is a fertile source of
difficult-to-find bugs. If the C language included a strong distinction difficult-to-find bugs. If the C language included a strong distinction
between integers and booleans then the compiler would find these mistakes between integers and booleans then the compiler would find these mistakes
for us... but it doesn't. To help prevent such bugs, always follow this for us... but it doesn't. To help prevent such bugs, always follow this
convention: convention::
If the name of a function is an action or an imperative command, If the name of a function is an action or an imperative command,
the function should return an error-code integer. If the name the function should return an error-code integer. If the name
is a predicate, the function should return a "succeeded" boolean. is a predicate, the function should return a "succeeded" boolean.
For example, "add work" is a command, and the add_work() function returns 0 For example, ``add work`` is a command, and the add_work() function returns 0
for success or -EBUSY for failure. In the same way, "PCI device present" is for success or -EBUSY for failure. In the same way, ``PCI device present`` is
a predicate, and the pci_dev_present() function returns 1 if it succeeds in a predicate, and the pci_dev_present() function returns 1 if it succeeds in
finding a matching device or 0 if it doesn't. finding a matching device or 0 if it doesn't.
...@@ -805,17 +901,22 @@ result. Typical examples would be functions that return pointers; they use ...@@ -805,17 +901,22 @@ result. Typical examples would be functions that return pointers; they use
NULL or the ERR_PTR mechanism to report failure. NULL or the ERR_PTR mechanism to report failure.
Chapter 17: Don't re-invent the kernel macros 17) Don't re-invent the kernel macros
-------------------------------------
The header file include/linux/kernel.h contains a number of macros that The header file include/linux/kernel.h contains a number of macros that
you should use, rather than explicitly coding some variant of them yourself. you should use, rather than explicitly coding some variant of them yourself.
For example, if you need to calculate the length of an array, take advantage For example, if you need to calculate the length of an array, take advantage
of the macro of the macro
.. code-block:: c
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
Similarly, if you need to calculate the size of some structure member, use Similarly, if you need to calculate the size of some structure member, use
.. code-block:: c
#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
There are also min() and max() macros that do strict type checking if you There are also min() and max() macros that do strict type checking if you
...@@ -823,16 +924,21 @@ need them. Feel free to peruse that header file to see what else is already ...@@ -823,16 +924,21 @@ need them. Feel free to peruse that header file to see what else is already
defined that you shouldn't reproduce in your code. defined that you shouldn't reproduce in your code.
Chapter 18: Editor modelines and other cruft 18) Editor modelines and other cruft
------------------------------------
Some editors can interpret configuration information embedded in source files, Some editors can interpret configuration information embedded in source files,
indicated with special markers. For example, emacs interprets lines marked indicated with special markers. For example, emacs interprets lines marked
like this: like this:
.. code-block:: c
-*- mode: c -*- -*- mode: c -*-
Or like this: Or like this:
.. code-block:: c
/* /*
Local Variables: Local Variables:
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
...@@ -841,6 +947,8 @@ Or like this: ...@@ -841,6 +947,8 @@ Or like this:
Vim interprets markers that look like this: Vim interprets markers that look like this:
.. code-block:: c
/* vim:set sw=8 noet */ /* vim:set sw=8 noet */
Do not include any of these in source files. People have their own personal Do not include any of these in source files. People have their own personal
...@@ -850,7 +958,8 @@ own custom mode, or may have some other magic method for making indentation ...@@ -850,7 +958,8 @@ own custom mode, or may have some other magic method for making indentation
work correctly. work correctly.
Chapter 19: Inline assembly 19) Inline assembly
-------------------
In architecture-specific code, you may need to use inline assembly to interface In architecture-specific code, you may need to use inline assembly to interface
with CPU or platform functionality. Don't hesitate to do so when necessary. with CPU or platform functionality. Don't hesitate to do so when necessary.
...@@ -863,7 +972,7 @@ that inline assembly can use C parameters. ...@@ -863,7 +972,7 @@ that inline assembly can use C parameters.
Large, non-trivial assembly functions should go in .S files, with corresponding Large, non-trivial assembly functions should go in .S files, with corresponding
C prototypes defined in C header files. The C prototypes for assembly C prototypes defined in C header files. The C prototypes for assembly
functions should use "asmlinkage". functions should use ``asmlinkage``.
You may need to mark your asm statement as volatile, to prevent GCC from You may need to mark your asm statement as volatile, to prevent GCC from
removing it if GCC doesn't notice any side effects. You don't always need to removing it if GCC doesn't notice any side effects. You don't always need to
...@@ -874,12 +983,15 @@ instructions, put each instruction on a separate line in a separate quoted ...@@ -874,12 +983,15 @@ instructions, put each instruction on a separate line in a separate quoted
string, and end each string except the last with \n\t to properly indent the string, and end each string except the last with \n\t to properly indent the
next instruction in the assembly output: next instruction in the assembly output:
.. code-block:: c
asm ("magic %reg1, #42\n\t" asm ("magic %reg1, #42\n\t"
"more_magic %reg2, %reg3" "more_magic %reg2, %reg3"
: /* outputs */ : /* inputs */ : /* clobbers */); : /* outputs */ : /* inputs */ : /* clobbers */);
Chapter 20: Conditional Compilation 20) Conditional Compilation
---------------------------
Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
files; doing so makes code harder to read and logic harder to follow. Instead, files; doing so makes code harder to read and logic harder to follow. Instead,
...@@ -903,6 +1015,8 @@ unused, delete it.) ...@@ -903,6 +1015,8 @@ unused, delete it.)
Within code, where possible, use the IS_ENABLED macro to convert a Kconfig Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
symbol into a C boolean expression, and use it in a normal C conditional: symbol into a C boolean expression, and use it in a normal C conditional:
.. code-block:: c
if (IS_ENABLED(CONFIG_SOMETHING)) { if (IS_ENABLED(CONFIG_SOMETHING)) {
... ...
} }
...@@ -918,12 +1032,15 @@ At the end of any non-trivial #if or #ifdef block (more than a few lines), ...@@ -918,12 +1032,15 @@ At the end of any non-trivial #if or #ifdef block (more than a few lines),
place a comment after the #endif on the same line, noting the conditional place a comment after the #endif on the same line, noting the conditional
expression used. For instance: expression used. For instance:
.. code-block:: c
#ifdef CONFIG_SOMETHING #ifdef CONFIG_SOMETHING
... ...
#endif /* CONFIG_SOMETHING */ #endif /* CONFIG_SOMETHING */
Appendix I: References Appendix I) References
----------------------
The C Programming Language, Second Edition The C Programming Language, Second Edition
by Brian W. Kernighan and Dennis M. Ritchie. by Brian W. Kernighan and Dennis M. Ritchie.
...@@ -943,4 +1060,3 @@ language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ ...@@ -943,4 +1060,3 @@ language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
Kernel CodingStyle, by greg@kroah.com at OLS 2002: Kernel CodingStyle, by greg@kroah.com at OLS 2002:
http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
Documentation/DMA-API-HOWTO.txt
View file @ 02bafd96
...@@ -699,7 +699,7 @@ to use the dma_sync_*() interfaces. ...@@ -699,7 +699,7 @@ to use the dma_sync_*() interfaces.
dma_addr_t mapping; dma_addr_t mapping;
mapping = dma_map_single(cp->dev, buffer, len, DMA_FROM_DEVICE); mapping = dma_map_single(cp->dev, buffer, len, DMA_FROM_DEVICE);
if (dma_mapping_error(cp->dev, dma_handle)) { if (dma_mapping_error(cp->dev, mapping)) {
/* /*
* reduce current DMA mapping usage, * reduce current DMA mapping usage,
* delay and try again later or * delay and try again later or
...@@ -931,10 +931,8 @@ to "Closing". ...@@ -931,10 +931,8 @@ to "Closing".
1) Struct scatterlist requirements. 1) Struct scatterlist requirements.
Don't invent the architecture specific struct scatterlist; just use You need to enable CONFIG_NEED_SG_DMA_LENGTH if the architecture
<asm-generic/scatterlist.h>. You need to enable supports IOMMUs (including software IOMMU).
CONFIG_NEED_SG_DMA_LENGTH if the architecture supports IOMMUs
(including software IOMMU).
2) ARCH_DMA_MINALIGN 2) ARCH_DMA_MINALIGN
......
Documentation/DocBook/Makefile
View file @ 02bafd96
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
# To add a new book the only step required is to add the book to the # To add a new book the only step required is to add the book to the
# list of DOCBOOKS. # list of DOCBOOKS.
DOCBOOKS := z8530book.xml device-drivers.xml \ DOCBOOKS := z8530book.xml \
kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
writing_usb_driver.xml networking.xml \ writing_usb_driver.xml networking.xml \
kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
...@@ -22,9 +22,15 @@ ifeq ($(DOCBOOKS),) ...@@ -22,9 +22,15 @@ ifeq ($(DOCBOOKS),)
# Skip DocBook build if the user explicitly requested no DOCBOOKS. # Skip DocBook build if the user explicitly requested no DOCBOOKS.
.DEFAULT: .DEFAULT:
@echo " SKIP DocBook $@ target (DOCBOOKS=\"\" specified)." @echo " SKIP DocBook $@ target (DOCBOOKS=\"\" specified)."
else
ifneq ($(SPHINXDIRS),)
# Skip DocBook build if the user explicitly requested a sphinx dir
.DEFAULT:
@echo " SKIP DocBook $@ target (SPHINXDIRS specified)."
else else
### ###
# The build process is as follows (targets): # The build process is as follows (targets):
# (xmldocs) [by docproc] # (xmldocs) [by docproc]
...@@ -66,6 +72,7 @@ installmandocs: mandocs ...@@ -66,6 +72,7 @@ installmandocs: mandocs
# no-op for the DocBook toolchain # no-op for the DocBook toolchain
epubdocs: epubdocs:
latexdocs:
### ###
#External programs used #External programs used
...@@ -221,6 +228,7 @@ silent_gen_xml = : ...@@ -221,6 +228,7 @@ silent_gen_xml = :
echo "</programlisting>") > $@ echo "</programlisting>") > $@
endif # DOCBOOKS="" endif # DOCBOOKS=""
endif # SPHINDIR=...
### ###
# Help targets as used by the top-level makefile # Help targets as used by the top-level makefile
......
Documentation/DocBook/device-drivers.tmpl deleted 100644 → 0
View file @ 2105b9ff
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
<book id="LinuxDriversAPI">
<bookinfo>
<title>Linux Device Drivers</title>
<legalnotice>
<para>
This documentation is free software; you can redistribute
it and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.
</para>
<para>
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
</para>
<para>
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA
</para>
<para>
For more details see the file COPYING in the source
distribution of Linux.
</para>
</legalnotice>
</bookinfo>
<toc></toc>
<chapter id="Basics">
<title>Driver Basics</title>
<sect1><title>Driver Entry and Exit points</title>
!Iinclude/linux/init.h
</sect1>
<sect1><title>Atomic and pointer manipulation</title>
!Iarch/x86/include/asm/atomic.h
</sect1>
<sect1><title>Delaying, scheduling, and timer routines</title>
!Iinclude/linux/sched.h
!Ekernel/sched/core.c
!Ikernel/sched/cpupri.c
!Ikernel/sched/fair.c
!Iinclude/linux/completion.h
!Ekernel/time/timer.c
</sect1>
<sect1><title>Wait queues and Wake events</title>
!Iinclude/linux/wait.h
!Ekernel/sched/wait.c
</sect1>
<sect1><title>High-resolution timers</title>
!Iinclude/linux/ktime.h
!Iinclude/linux/hrtimer.h
!Ekernel/time/hrtimer.c
</sect1>
<sect1><title>Workqueues and Kevents</title>
!Iinclude/linux/workqueue.h
!Ekernel/workqueue.c
</sect1>
<sect1><title>Internal Functions</title>
!Ikernel/exit.c
!Ikernel/signal.c
!Iinclude/linux/kthread.h
!Ekernel/kthread.c
</sect1>
<sect1><title>Kernel objects manipulation</title>
<!--
X!Iinclude/linux/kobject.h
-->
!Elib/kobject.c
</sect1>
<sect1><title>Kernel utility functions</title>
!Iinclude/linux/kernel.h
!Ekernel/printk/printk.c
!Ekernel/panic.c
!Ekernel/sys.c
!Ekernel/rcu/srcu.c
!Ekernel/rcu/tree.c
!Ekernel/rcu/tree_plugin.h
!Ekernel/rcu/update.c
</sect1>
<sect1><title>Device Resource Management</title>
!Edrivers/base/devres.c
</sect1>
</chapter>
<chapter id="devdrivers">
<title>Device drivers infrastructure</title>
<sect1><title>The Basic Device Driver-Model Structures </title>
!Iinclude/linux/device.h
</sect1>
<sect1><title>Device Drivers Base</title>
!Idrivers/base/init.c
!Edrivers/base/driver.c
!Edrivers/base/core.c
!Edrivers/base/syscore.c
!Edrivers/base/class.c
!Idrivers/base/node.c
!Edrivers/base/firmware_class.c
!Edrivers/base/transport_class.c
<!-- Cannot be included, because
attribute_container_add_class_device_adapter
and attribute_container_classdev_to_container
exceed allowed 44 characters maximum
X!Edrivers/base/attribute_container.c
-->
!Edrivers/base/dd.c
<!--
X!Edrivers/base/interface.c
-->
!Iinclude/linux/platform_device.h
!Edrivers/base/platform.c
!Edrivers/base/bus.c
</sect1>
<sect1>
<title>Buffer Sharing and Synchronization</title>
<para>
The dma-buf subsystem provides the framework for sharing buffers
for hardware (DMA) access across multiple device drivers and
subsystems, and for synchronizing asynchronous hardware access.
</para>
<para>
This is used, for example, by drm "prime" multi-GPU support, but
is of course not limited to GPU use cases.
</para>
<para>
The three main components of this are: (1) dma-buf, representing
a sg_table and exposed to userspace as a file descriptor to allow
passing between devices, (2) fence, which provides a mechanism
to signal when one device as finished access, and (3) reservation,
which manages the shared or exclusive fence(s) associated with
the buffer.
</para>
<sect2><title>dma-buf</title>
!Edrivers/dma-buf/dma-buf.c
!Iinclude/linux/dma-buf.h
</sect2>
<sect2><title>reservation</title>
!Pdrivers/dma-buf/reservation.c Reservation Object Overview
!Edrivers/dma-buf/reservation.c
!Iinclude/linux/reservation.h
</sect2>
<sect2><title>fence</title>
!Edrivers/dma-buf/fence.c
!Iinclude/linux/fence.h
!Edrivers/dma-buf/seqno-fence.c
!Iinclude/linux/seqno-fence.h
!Edrivers/dma-buf/fence-array.c
!Iinclude/linux/fence-array.h
!Edrivers/dma-buf/reservation.c
!Iinclude/linux/reservation.h
!Edrivers/dma-buf/sync_file.c
!Iinclude/linux/sync_file.h
</sect2>
</sect1>
<sect1><title>Device Drivers DMA Management</title>
!Edrivers/base/dma-coherent.c
!Edrivers/base/dma-mapping.c
</sect1>
<sect1><title>Device Drivers Power Management</title>
!Edrivers/base/power/main.c
</sect1>
<sect1><title>Device Drivers ACPI Support</title>
<!-- Internal functions only
X!Edrivers/acpi/sleep/main.c
X!Edrivers/acpi/sleep/wakeup.c
X!Edrivers/acpi/motherboard.c
X!Edrivers/acpi/bus.c
-->
!Edrivers/acpi/scan.c
!Idrivers/acpi/scan.c
<!-- No correct structured comments
X!Edrivers/acpi/pci_bind.c
-->
</sect1>
<sect1><title>Device drivers PnP support</title>
!Idrivers/pnp/core.c
<!-- No correct structured comments
X!Edrivers/pnp/system.c
-->
!Edrivers/pnp/card.c
!Idrivers/pnp/driver.c
!Edrivers/pnp/manager.c
!Edrivers/pnp/support.c
</sect1>
<sect1><title>Userspace IO devices</title>
!Edrivers/uio/uio.c
!Iinclude/linux/uio_driver.h
</sect1>
</chapter>
<chapter id="parportdev">
<title>Parallel Port Devices</title>
!Iinclude/linux/parport.h
!Edrivers/parport/ieee1284.c
!Edrivers/parport/share.c
!Idrivers/parport/daisy.c
</chapter>
<chapter id="message_devices">
<title>Message-based devices</title>
<sect1><title>Fusion message devices</title>
!Edrivers/message/fusion/mptbase.c
!Idrivers/message/fusion/mptbase.c
!Edrivers/message/fusion/mptscsih.c
!Idrivers/message/fusion/mptscsih.c
!Idrivers/message/fusion/mptctl.c
!Idrivers/message/fusion/mptspi.c
!Idrivers/message/fusion/mptfc.c
!Idrivers/message/fusion/mptlan.c
</sect1>
</chapter>
<chapter id="snddev">
<title>Sound Devices</title>
!Iinclude/sound/core.h
!Esound/sound_core.c
!Iinclude/sound/pcm.h
!Esound/core/pcm.c
!Esound/core/device.c
!Esound/core/info.c
!Esound/core/rawmidi.c
!Esound/core/sound.c
!Esound/core/memory.c
!Esound/core/pcm_memory.c
!Esound/core/init.c
!Esound/core/isadma.c
!Esound/core/control.c
!Esound/core/pcm_lib.c
!Esound/core/hwdep.c
!Esound/core/pcm_native.c
!Esound/core/memalloc.c
<!-- FIXME: Removed for now since no structured comments in source
X!Isound/sound_firmware.c
-->
</chapter>
<chapter id="uart16x50">
<title>16x50 UART Driver</title>
!Edrivers/tty/serial/serial_core.c
!Edrivers/tty/serial/8250/8250_core.c
</chapter>
<chapter id="fbdev">
<title>Frame Buffer Library</title>
<para>
The frame buffer drivers depend heavily on four data structures.
These structures are declared in include/linux/fb.h. They are
fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs.
The last three can be made available to and from userland.
</para>
<para>
fb_info defines the current state of a particular video card.
Inside fb_info, there exists a fb_ops structure which is a
collection of needed functions to make fbdev and fbcon work.
fb_info is only visible to the kernel.
</para>
<para>
fb_var_screeninfo is used to describe the features of a video card
that are user defined. With fb_var_screeninfo, things such as
depth and the resolution may be defined.
</para>
<para>
The next structure is fb_fix_screeninfo. This defines the
properties of a card that are created when a mode is set and can't
be changed otherwise. A good example of this is the start of the
frame buffer memory. This "locks" the address of the frame buffer
memory, so that it cannot be changed or moved.
</para>
<para>
The last structure is fb_monospecs. In the old API, there was
little importance for fb_monospecs. This allowed for forbidden things
such as setting a mode of 800x600 on a fix frequency monitor. With
the new API, fb_monospecs prevents such things, and if used
correctly, can prevent a monitor from being cooked. fb_monospecs
will not be useful until kernels 2.5.x.
</para>
<sect1><title>Frame Buffer Memory</title>
!Edrivers/video/fbdev/core/fbmem.c
</sect1>
<!--
<sect1><title>Frame Buffer Console</title>
X!Edrivers/video/console/fbcon.c
</sect1>
-->
<sect1><title>Frame Buffer Colormap</title>
!Edrivers/video/fbdev/core/fbcmap.c
</sect1>
<!-- FIXME:
drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment
out until somebody adds docs. KAO
<sect1><title>Frame Buffer Generic Functions</title>
X!Idrivers/video/fbgen.c
</sect1>
KAO -->
<sect1><title>Frame Buffer Video Mode Database</title>
!Idrivers/video/fbdev/core/modedb.c
!Edrivers/video/fbdev/core/modedb.c
</sect1>
<sect1><title>Frame Buffer Macintosh Video Mode Database</title>
!Edrivers/video/fbdev/macmodes.c
</sect1>
<sect1><title>Frame Buffer Fonts</title>
<para>
Refer to the file lib/fonts/fonts.c for more information.
</para>
<!-- FIXME: Removed for now since no structured comments in source
X!Ilib/fonts/fonts.c
-->
</sect1>
</chapter>
<chapter id="input_subsystem">
<title>Input Subsystem</title>
<sect1><title>Input core</title>
!Iinclude/linux/input.h
!Edrivers/input/input.c
!Edrivers/input/ff-core.c
!Edrivers/input/ff-memless.c
</sect1>
<sect1><title>Multitouch Library</title>
!Iinclude/linux/input/mt.h
!Edrivers/input/input-mt.c
</sect1>
<sect1><title>Polled input devices</title>
!Iinclude/linux/input-polldev.h
!Edrivers/input/input-polldev.c
</sect1>
<sect1><title>Matrix keyboards/keypads</title>
!Iinclude/linux/input/matrix_keypad.h
</sect1>
<sect1><title>Sparse keymap support</title>
!Iinclude/linux/input/sparse-keymap.h
!Edrivers/input/sparse-keymap.c
</sect1>
</chapter>
<chapter id="spi">
<title>Serial Peripheral Interface (SPI)</title>
<para>
SPI is the "Serial Peripheral Interface", widely used with
embedded systems because it is a simple and efficient
interface: basically a multiplexed shift register.
Its three signal wires hold a clock (SCK, often in the range
of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and
a "Master In, Slave Out" (MISO) data line.
SPI is a full duplex protocol; for each bit shifted out the
MOSI line (one per clock) another is shifted in on the MISO line.
Those bits are assembled into words of various sizes on the
way to and from system memory.
An additional chipselect line is usually active-low (nCS);
four signals are normally used for each peripheral, plus
sometimes an interrupt.
</para>
<para>
The SPI bus facilities listed here provide a generalized
interface to declare SPI busses and devices, manage them
according to the standard Linux driver model, and perform
input/output operations.
At this time, only "master" side interfaces are supported,
where Linux talks to SPI peripherals and does not implement
such a peripheral itself.
(Interfaces to support implementing SPI slaves would
necessarily look different.)
</para>
<para>
The programming interface is structured around two kinds of driver,
and two kinds of device.
A "Controller Driver" abstracts the controller hardware, which may
be as simple as a set of GPIO pins or as complex as a pair of FIFOs
connected to dual DMA engines on the other side of the SPI shift
register (maximizing throughput). Such drivers bridge between
whatever bus they sit on (often the platform bus) and SPI, and
expose the SPI side of their device as a
<structname>struct spi_master</structname>.
SPI devices are children of that master, represented as a
<structname>struct spi_device</structname> and manufactured from
<structname>struct spi_board_info</structname> descriptors which
are usually provided by board-specific initialization code.
A <structname>struct spi_driver</structname> is called a
"Protocol Driver", and is bound to a spi_device using normal
driver model calls.
</para>
<para>
The I/O model is a set of queued messages. Protocol drivers
submit one or more <structname>struct spi_message</structname>
objects, which are processed and completed asynchronously.
(There are synchronous wrappers, however.) Messages are
built from one or more <structname>struct spi_transfer</structname>
objects, each of which wraps a full duplex SPI transfer.
A variety of protocol tweaking options are needed, because
different chips adopt very different policies for how they
use the bits transferred with SPI.
</para>
!Iinclude/linux/spi/spi.h
!Fdrivers/spi/spi.c spi_register_board_info
!Edrivers/spi/spi.c
</chapter>
<chapter id="i2c">
<title>I<superscript>2</superscript>C and SMBus Subsystem</title>
<para>
I<superscript>2</superscript>C (or without fancy typography, "I2C")
is an acronym for the "Inter-IC" bus, a simple bus protocol which is
widely used where low data rate communications suffice.
Since it's also a licensed trademark, some vendors use another
name (such as "Two-Wire Interface", TWI) for the same bus.
I2C only needs two signals (SCL for clock, SDA for data), conserving
board real estate and minimizing signal quality issues.
Most I2C devices use seven bit addresses, and bus speeds of up
to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet
found wide use.
I2C is a multi-master bus; open drain signaling is used to
arbitrate between masters, as well as to handshake and to
synchronize clocks from slower clients.
</para>
<para>
The Linux I2C programming interfaces support only the master
side of bus interactions, not the slave side.
The programming interface is structured around two kinds of driver,
and two kinds of device.
An I2C "Adapter Driver" abstracts the controller hardware; it binds
to a physical device (perhaps a PCI device or platform_device) and
exposes a <structname>struct i2c_adapter</structname> representing
each I2C bus segment it manages.
On each I2C bus segment will be I2C devices represented by a
<structname>struct i2c_client</structname>. Those devices will
be bound to a <structname>struct i2c_driver</structname>,
which should follow the standard Linux driver model.
(At this writing, a legacy model is more widely used.)
There are functions to perform various I2C protocol operations; at
this writing all such functions are usable only from task context.
</para>
<para>
The System Management Bus (SMBus) is a sibling protocol. Most SMBus
systems are also I2C conformant. The electrical constraints are
tighter for SMBus, and it standardizes particular protocol messages
and idioms. Controllers that support I2C can also support most
SMBus operations, but SMBus controllers don't support all the protocol
options that an I2C controller will.
There are functions to perform various SMBus protocol operations,
either using I2C primitives or by issuing SMBus commands to
i2c_adapter devices which don't support those I2C operations.
</para>
!Iinclude/linux/i2c.h
!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info
!Edrivers/i2c/i2c-core.c
</chapter>
<chapter id="hsi">
<title>High Speed Synchronous Serial Interface (HSI)</title>
<para>
High Speed Synchronous Serial Interface (HSI) is a
serial interface mainly used for connecting application
engines (APE) with cellular modem engines (CMT) in cellular
handsets.
HSI provides multiplexing for up to 16 logical channels,
low-latency and full duplex communication.
</para>
!Iinclude/linux/hsi/hsi.h
!Edrivers/hsi/hsi_core.c
</chapter>
<chapter id="pwm">
<title>Pulse-Width Modulation (PWM)</title>
<para>
Pulse-width modulation is a modulation technique primarily used to
control power supplied to electrical devices.
</para>
<para>
The PWM framework provides an abstraction for providers and consumers
of PWM signals. A controller that provides one or more PWM signals is
registered as <structname>struct pwm_chip</structname>. Providers are
expected to embed this structure in a driver-specific structure. This
structure contains fields that describe a particular chip.
</para>
<para>
A chip exposes one or more PWM signal sources, each of which exposed
as a <structname>struct pwm_device</structname>. Operations can be
performed on PWM devices to control the period, duty cycle, polarity
and active state of the signal.
</para>
<para>
Note that PWM devices are exclusive resources: they can always only be
used by one consumer at a time.
</para>
!Iinclude/linux/pwm.h
!Edrivers/pwm/core.c
</chapter>
</book>
Documentation/HOWTO
View file @ 02bafd96
HOWTO do Linux kernel development HOWTO do Linux kernel development
--------------------------------- =================================
This is the be-all, end-all document on this topic. It contains This is the be-all, end-all document on this topic. It contains
instructions on how to become a Linux kernel developer and how to learn instructions on how to become a Linux kernel developer and how to learn
...@@ -28,6 +28,7 @@ kernel development. Assembly (any architecture) is not required unless ...@@ -28,6 +28,7 @@ kernel development. Assembly (any architecture) is not required unless
you plan to do low-level development for that architecture. Though they you plan to do low-level development for that architecture. Though they
are not a good substitute for a solid C education and/or years of are not a good substitute for a solid C education and/or years of
experience, the following books are good for, if anything, reference: experience, the following books are good for, if anything, reference:
- "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
- "Practical C Programming" by Steve Oualline [O'Reilly] - "Practical C Programming" by Steve Oualline [O'Reilly]
- "C: A Reference Manual" by Harbison and Steele [Prentice Hall] - "C: A Reference Manual" by Harbison and Steele [Prentice Hall]
...@@ -64,7 +65,8 @@ people on the mailing lists are not lawyers, and you should not rely on ...@@ -64,7 +65,8 @@ people on the mailing lists are not lawyers, and you should not rely on
their statements on legal matters. their statements on legal matters.
For common questions and answers about the GPL, please see: For common questions and answers about the GPL, please see:
http://www.gnu.org/licenses/gpl-faq.html
https://www.gnu.org/licenses/gpl-faq.html
Documentation Documentation
...@@ -82,96 +84,118 @@ linux-api@vger.kernel.org. ...@@ -82,96 +84,118 @@ linux-api@vger.kernel.org.
Here is a list of files that are in the kernel source tree that are Here is a list of files that are in the kernel source tree that are
required reading: required reading:
README README
This file gives a short background on the Linux kernel and describes This file gives a short background on the Linux kernel and describes
what is necessary to do to configure and build the kernel. People what is necessary to do to configure and build the kernel. People
who are new to the kernel should start here. who are new to the kernel should start here.
Documentation/Changes :ref:`Documentation/Changes <changes>`
This file gives a list of the minimum levels of various software This file gives a list of the minimum levels of various software
packages that are necessary to build and run the kernel packages that are necessary to build and run the kernel
successfully. successfully.
Documentation/CodingStyle :ref:`Documentation/CodingStyle <codingstyle>`
This describes the Linux kernel coding style, and some of the This describes the Linux kernel coding style, and some of the
rationale behind it. All new code is expected to follow the rationale behind it. All new code is expected to follow the
guidelines in this document. Most maintainers will only accept guidelines in this document. Most maintainers will only accept
patches if these rules are followed, and many people will only patches if these rules are followed, and many people will only
review code if it is in the proper style. review code if it is in the proper style.
Documentation/SubmittingPatches :ref:`Documentation/SubmittingPatches <submittingpatches>` and :ref:`Documentation/SubmittingDrivers <submittingdrivers>`
Documentation/SubmittingDrivers
These files describe in explicit detail how to successfully create These files describe in explicit detail how to successfully create
and send a patch, including (but not limited to): and send a patch, including (but not limited to):
- Email contents - Email contents
- Email format - Email format
- Who to send it to - Who to send it to
Following these rules will not guarantee success (as all patches are Following these rules will not guarantee success (as all patches are
subject to scrutiny for content and style), but not following them subject to scrutiny for content and style), but not following them
will almost always prevent it. will almost always prevent it.
Other excellent descriptions of how to create patches properly are: Other excellent descriptions of how to create patches properly are:
"The Perfect Patch" "The Perfect Patch"
http://www.ozlabs.org/~akpm/stuff/tpp.txt https://www.ozlabs.org/~akpm/stuff/tpp.txt
"Linux kernel patch submission format" "Linux kernel patch submission format"
http://linux.yyz.us/patch-format.html http://linux.yyz.us/patch-format.html
Documentation/stable_api_nonsense.txt :ref:`Documentation/stable_api_nonsense.txt <stable_api_nonsense>`
This file describes the rationale behind the conscious decision to This file describes the rationale behind the conscious decision to
not have a stable API within the kernel, including things like: not have a stable API within the kernel, including things like:
- Subsystem shim-layers (for compatibility?) - Subsystem shim-layers (for compatibility?)
- Driver portability between Operating Systems. - Driver portability between Operating Systems.
- Mitigating rapid change within the kernel source tree (or - Mitigating rapid change within the kernel source tree (or
preventing rapid change) preventing rapid change)
This document is crucial for understanding the Linux development This document is crucial for understanding the Linux development
philosophy and is very important for people moving to Linux from philosophy and is very important for people moving to Linux from
development on other Operating Systems. development on other Operating Systems.
Documentation/SecurityBugs :ref:`Documentation/SecurityBugs <securitybugs>`
If you feel you have found a security problem in the Linux kernel, If you feel you have found a security problem in the Linux kernel,
please follow the steps in this document to help notify the kernel please follow the steps in this document to help notify the kernel
developers, and help solve the issue. developers, and help solve the issue.
Documentation/ManagementStyle :ref:`Documentation/ManagementStyle <managementstyle>`
This document describes how Linux kernel maintainers operate and the This document describes how Linux kernel maintainers operate and the
shared ethos behind their methodologies. This is important reading shared ethos behind their methodologies. This is important reading
for anyone new to kernel development (or anyone simply curious about for anyone new to kernel development (or anyone simply curious about
it), as it resolves a lot of common misconceptions and confusion it), as it resolves a lot of common misconceptions and confusion
about the unique behavior of kernel maintainers. about the unique behavior of kernel maintainers.
Documentation/stable_kernel_rules.txt :ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
This file describes the rules on how the stable kernel releases This file describes the rules on how the stable kernel releases
happen, and what to do if you want to get a change into one of these happen, and what to do if you want to get a change into one of these
releases. releases.
Documentation/kernel-docs.txt :ref:`Documentation/kernel-docs.txt <kernel_docs>`
A list of external documentation that pertains to kernel A list of external documentation that pertains to kernel
development. Please consult this list if you do not find what you development. Please consult this list if you do not find what you
are looking for within the in-kernel documentation. are looking for within the in-kernel documentation.
Documentation/applying-patches.txt :ref:`Documentation/applying-patches.txt <applying_patches>`
A good introduction describing exactly what a patch is and how to A good introduction describing exactly what a patch is and how to
apply it to the different development branches of the kernel. apply it to the different development branches of the kernel.
The kernel also has a large number of documents that can be The kernel also has a large number of documents that can be
automatically generated from the source code itself. This includes a automatically generated from the source code itself or from
ReStructuredText markups (ReST), like this one. This includes a
full description of the in-kernel API, and rules on how to handle full description of the in-kernel API, and rules on how to handle
locking properly. The documents will be created in the locking properly.
Documentation/DocBook/ directory and can be generated as PDF,
Postscript, HTML, and man pages by running: All such documents can be generated as PDF or HTML by running::
make pdfdocs make pdfdocs
make psdocs
make htmldocs make htmldocs
make mandocs
respectively from the main kernel source directory. respectively from the main kernel source directory.
The documents that uses ReST markup will be generated at Documentation/output.
They can also be generated on LaTeX and ePub formats with::
make latexdocs
make epubdocs
Currently, there are some documents written on DocBook that are in
the process of conversion to ReST. Such documents will be created in the
Documentation/DocBook/ directory and can be generated also as
Postscript or man pages by running::
make psdocs
make mandocs
Becoming A Kernel Developer Becoming A Kernel Developer
--------------------------- ---------------------------
If you do not know anything about Linux kernel development, you should If you do not know anything about Linux kernel development, you should
look at the Linux KernelNewbies project: look at the Linux KernelNewbies project:
http://kernelnewbies.org
https://kernelnewbies.org
It consists of a helpful mailing list where you can ask almost any type It consists of a helpful mailing list where you can ask almost any type
of basic kernel development question (make sure to search the archives of basic kernel development question (make sure to search the archives
first, before asking something that has already been answered in the first, before asking something that has already been answered in the
...@@ -187,7 +211,9 @@ apply a patch. ...@@ -187,7 +211,9 @@ apply a patch.
If you do not know where you want to start, but you want to look for If you do not know where you want to start, but you want to look for
some task to start doing to join into the kernel development community, some task to start doing to join into the kernel development community,
go to the Linux Kernel Janitor's project: go to the Linux Kernel Janitor's project:
http://kernelnewbies.org/KernelJanitors
https://kernelnewbies.org/KernelJanitors
It is a great place to start. It describes a list of relatively simple It is a great place to start. It describes a list of relatively simple
problems that need to be cleaned up and fixed within the Linux kernel problems that need to be cleaned up and fixed within the Linux kernel
source tree. Working with the developers in charge of this project, you source tree. Working with the developers in charge of this project, you
...@@ -199,7 +225,8 @@ If you already have a chunk of code that you want to put into the kernel ...@@ -199,7 +225,8 @@ If you already have a chunk of code that you want to put into the kernel
tree, but need some help getting it in the proper form, the tree, but need some help getting it in the proper form, the
kernel-mentors project was created to help you out with this. It is a kernel-mentors project was created to help you out with this. It is a
mailing list, and can be found at: mailing list, and can be found at:
http://selenic.com/mailman/listinfo/kernel-mentors
https://selenic.com/mailman/listinfo/kernel-mentors
Before making any actual modifications to the Linux kernel code, it is Before making any actual modifications to the Linux kernel code, it is
imperative to understand how the code in question works. For this imperative to understand how the code in question works. For this
...@@ -209,6 +236,7 @@ tools. One such tool that is particularly recommended is the Linux ...@@ -209,6 +236,7 @@ tools. One such tool that is particularly recommended is the Linux
Cross-Reference project, which is able to present source code in a Cross-Reference project, which is able to present source code in a
self-referential, indexed webpage format. An excellent up-to-date self-referential, indexed webpage format. An excellent up-to-date
repository of the kernel code may be found at: repository of the kernel code may be found at:
http://lxr.free-electrons.com/ http://lxr.free-electrons.com/
...@@ -218,6 +246,7 @@ The development process ...@@ -218,6 +246,7 @@ The development process
Linux kernel development process currently consists of a few different Linux kernel development process currently consists of a few different
main kernel "branches" and lots of different subsystem-specific kernel main kernel "branches" and lots of different subsystem-specific kernel
branches. These different branches are: branches. These different branches are:
- main 4.x kernel tree - main 4.x kernel tree
- 4.x.y -stable kernel tree - 4.x.y -stable kernel tree
- 4.x -git kernel patches - 4.x -git kernel patches
...@@ -227,14 +256,15 @@ branches. These different branches are: ...@@ -227,14 +256,15 @@ branches. These different branches are:
4.x kernel tree 4.x kernel tree
----------------- -----------------
4.x kernels are maintained by Linus Torvalds, and can be found on 4.x kernels are maintained by Linus Torvalds, and can be found on
kernel.org in the pub/linux/kernel/v4.x/ directory. Its development https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development
process is as follows: process is as follows:
- As soon as a new kernel is released a two weeks window is open, - As soon as a new kernel is released a two weeks window is open,
during this period of time maintainers can submit big diffs to during this period of time maintainers can submit big diffs to
Linus, usually the patches that have already been included in the Linus, usually the patches that have already been included in the
-next kernel for a few weeks. The preferred way to submit big changes -next kernel for a few weeks. The preferred way to submit big changes
is using git (the kernel's source management tool, more information is using git (the kernel's source management tool, more information
can be found at http://git-scm.com/) but plain patches are also just can be found at https://git-scm.com/) but plain patches are also just
fine. fine.
- After two weeks a -rc1 kernel is released it is now possible to push - After two weeks a -rc1 kernel is released it is now possible to push
only patches that do not include new features that could affect the only patches that do not include new features that could affect the
...@@ -253,9 +283,10 @@ process is as follows: ...@@ -253,9 +283,10 @@ process is as follows:
It is worth mentioning what Andrew Morton wrote on the linux-kernel It is worth mentioning what Andrew Morton wrote on the linux-kernel
mailing list about kernel releases: mailing list about kernel releases:
"Nobody knows when a kernel will be released, because it's
*"Nobody knows when a kernel will be released, because it's
released according to perceived bug status, not according to a released according to perceived bug status, not according to a
preconceived timeline." preconceived timeline."*
4.x.y -stable kernel tree 4.x.y -stable kernel tree
------------------------- -------------------------
...@@ -301,7 +332,7 @@ submission and other already ongoing work are avoided. ...@@ -301,7 +332,7 @@ submission and other already ongoing work are avoided.
Most of these repositories are git trees, but there are also other SCMs Most of these repositories are git trees, but there are also other SCMs
in use, or patch queues being published as quilt series. Addresses of in use, or patch queues being published as quilt series. Addresses of
these subsystem repositories are listed in the MAINTAINERS file. Many these subsystem repositories are listed in the MAINTAINERS file. Many
of them can be browsed at http://git.kernel.org/. of them can be browsed at https://git.kernel.org/.
Before a proposed patch is committed to such a subsystem tree, it is Before a proposed patch is committed to such a subsystem tree, it is
subject to review which primarily happens on mailing lists (see the subject to review which primarily happens on mailing lists (see the
...@@ -310,7 +341,7 @@ process is tracked with the tool patchwork. Patchwork offers a web ...@@ -310,7 +341,7 @@ process is tracked with the tool patchwork. Patchwork offers a web
interface which shows patch postings, any comments on a patch or interface which shows patch postings, any comments on a patch or
revisions to it, and maintainers can mark patches as under review, revisions to it, and maintainers can mark patches as under review,
accepted, or rejected. Most of these patchwork sites are listed at accepted, or rejected. Most of these patchwork sites are listed at
http://patchwork.kernel.org/. https://patchwork.kernel.org/.
4.x -next kernel tree for integration tests 4.x -next kernel tree for integration tests
------------------------------------------- -------------------------------------------
...@@ -318,7 +349,8 @@ Before updates from subsystem trees are merged into the mainline 4.x ...@@ -318,7 +349,8 @@ Before updates from subsystem trees are merged into the mainline 4.x
tree, they need to be integration-tested. For this purpose, a special tree, they need to be integration-tested. For this purpose, a special
testing repository exists into which virtually all subsystem trees are testing repository exists into which virtually all subsystem trees are
pulled on an almost daily basis: pulled on an almost daily basis:
http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
This way, the -next kernel gives a summary outlook onto what will be This way, the -next kernel gives a summary outlook onto what will be
expected to go into the mainline kernel at the next merge period. expected to go into the mainline kernel at the next merge period.
...@@ -328,10 +360,11 @@ Adventurous testers are very welcome to runtime-test the -next kernel. ...@@ -328,10 +360,11 @@ Adventurous testers are very welcome to runtime-test the -next kernel.
Bug Reporting Bug Reporting
------------- -------------
bugzilla.kernel.org is where the Linux kernel developers track kernel https://bugzilla.kernel.org is where the Linux kernel developers track kernel
bugs. Users are encouraged to report all bugs that they find in this bugs. Users are encouraged to report all bugs that they find in this
tool. For details on how to use the kernel bugzilla, please see: tool. For details on how to use the kernel bugzilla, please see:
http://bugzilla.kernel.org/page.cgi?id=faq.html
https://bugzilla.kernel.org/page.cgi?id=faq.html
The file REPORTING-BUGS in the main kernel source directory has a good The file REPORTING-BUGS in the main kernel source directory has a good
template for how to report a possible kernel bug, and details what kind template for how to report a possible kernel bug, and details what kind
...@@ -349,13 +382,14 @@ your skills, and other developers will be aware of your presence. Fixing ...@@ -349,13 +382,14 @@ your skills, and other developers will be aware of your presence. Fixing
bugs is one of the best ways to get merits among other developers, because bugs is one of the best ways to get merits among other developers, because
not many people like wasting time fixing other people's bugs. not many people like wasting time fixing other people's bugs.
To work in the already reported bug reports, go to http://bugzilla.kernel.org. To work in the already reported bug reports, go to https://bugzilla.kernel.org.
If you want to be advised of the future bug reports, you can subscribe to the If you want to be advised of the future bug reports, you can subscribe to the
bugme-new mailing list (only new bug reports are mailed here) or to the bugme-new mailing list (only new bug reports are mailed here) or to the
bugme-janitor mailing list (every change in the bugzilla is mailed here) bugme-janitor mailing list (every change in the bugzilla is mailed here)
http://lists.linux-foundation.org/mailman/listinfo/bugme-new https://lists.linux-foundation.org/mailman/listinfo/bugme-new
http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
...@@ -365,10 +399,14 @@ Mailing lists ...@@ -365,10 +399,14 @@ Mailing lists
As some of the above documents describe, the majority of the core kernel As some of the above documents describe, the majority of the core kernel
developers participate on the Linux Kernel Mailing list. Details on how developers participate on the Linux Kernel Mailing list. Details on how
to subscribe and unsubscribe from the list can be found at: to subscribe and unsubscribe from the list can be found at:
http://vger.kernel.org/vger-lists.html#linux-kernel http://vger.kernel.org/vger-lists.html#linux-kernel
There are archives of the mailing list on the web in many different There are archives of the mailing list on the web in many different
places. Use a search engine to find these archives. For example: places. Use a search engine to find these archives. For example:
http://dir.gmane.org/gmane.linux.kernel http://dir.gmane.org/gmane.linux.kernel
It is highly recommended that you search the archives about the topic It is highly recommended that you search the archives about the topic
you want to bring up, before you post it to the list. A lot of things you want to bring up, before you post it to the list. A lot of things
already discussed in detail are only recorded at the mailing list already discussed in detail are only recorded at the mailing list
...@@ -381,11 +419,13 @@ groups. ...@@ -381,11 +419,13 @@ groups.
Many of the lists are hosted on kernel.org. Information on them can be Many of the lists are hosted on kernel.org. Information on them can be
found at: found at:
http://vger.kernel.org/vger-lists.html http://vger.kernel.org/vger-lists.html
Please remember to follow good behavioral habits when using the lists. Please remember to follow good behavioral habits when using the lists.
Though a bit cheesy, the following URL has some simple guidelines for Though a bit cheesy, the following URL has some simple guidelines for
interacting with the list (or any list): interacting with the list (or any list):
http://www.albion.com/netiquette/ http://www.albion.com/netiquette/
If multiple people respond to your mail, the CC: list of recipients may If multiple people respond to your mail, the CC: list of recipients may
...@@ -400,13 +440,14 @@ add your statements between the individual quoted sections instead of ...@@ -400,13 +440,14 @@ add your statements between the individual quoted sections instead of
writing at the top of the mail. writing at the top of the mail.
If you add patches to your mail, make sure they are plain readable text If you add patches to your mail, make sure they are plain readable text
as stated in Documentation/SubmittingPatches. Kernel developers don't as stated in Documentation/SubmittingPatches.
want to deal with attachments or compressed patches; they may want Kernel developers don't want to deal with
to comment on individual lines of your patch, which works only that way. attachments or compressed patches; they may want to comment on
Make sure you use a mail program that does not mangle spaces and tab individual lines of your patch, which works only that way. Make sure you
characters. A good first test is to send the mail to yourself and try use a mail program that does not mangle spaces and tab characters. A
to apply your own patch by yourself. If that doesn't work, get your good first test is to send the mail to yourself and try to apply your
mail program fixed or change it until it works. own patch by yourself. If that doesn't work, get your mail program fixed
or change it until it works.
Above all, please remember to show respect to other subscribers. Above all, please remember to show respect to other subscribers.
...@@ -418,6 +459,7 @@ The goal of the kernel community is to provide the best possible kernel ...@@ -418,6 +459,7 @@ The goal of the kernel community is to provide the best possible kernel
there is. When you submit a patch for acceptance, it will be reviewed there is. When you submit a patch for acceptance, it will be reviewed
on its technical merits and those alone. So, what should you be on its technical merits and those alone. So, what should you be
expecting? expecting?
- criticism - criticism
- comments - comments
- requests for change - requests for change
...@@ -432,6 +474,7 @@ If there are no responses to your posting, wait a few days and try ...@@ -432,6 +474,7 @@ If there are no responses to your posting, wait a few days and try
again, sometimes things get lost in the huge volume. again, sometimes things get lost in the huge volume.
What should you not do? What should you not do?
- expect your patch to be accepted without question - expect your patch to be accepted without question
- become defensive - become defensive
- ignore comments - ignore comments
...@@ -445,8 +488,8 @@ Remember, being wrong is acceptable as long as you are willing to work ...@@ -445,8 +488,8 @@ Remember, being wrong is acceptable as long as you are willing to work
toward a solution that is right. toward a solution that is right.
It is normal that the answers to your first patch might simply be a list It is normal that the answers to your first patch might simply be a list
of a dozen things you should correct. This does _not_ imply that your of a dozen things you should correct. This does **not** imply that your
patch will not be accepted, and it is _not_ meant against you patch will not be accepted, and it is **not** meant against you
personally. Simply correct all issues raised against your patch and personally. Simply correct all issues raised against your patch and
resend it. resend it.
...@@ -457,7 +500,9 @@ Differences between the kernel community and corporate structures ...@@ -457,7 +500,9 @@ Differences between the kernel community and corporate structures
The kernel community works differently than most traditional corporate The kernel community works differently than most traditional corporate
development environments. Here are a list of things that you can try to development environments. Here are a list of things that you can try to
do to avoid problems: do to avoid problems:
Good things to say regarding your proposed changes: Good things to say regarding your proposed changes:
- "This solves multiple problems." - "This solves multiple problems."
- "This deletes 2000 lines of code." - "This deletes 2000 lines of code."
- "Here is a patch that explains what I am trying to describe." - "Here is a patch that explains what I am trying to describe."
...@@ -466,6 +511,7 @@ do to avoid problems: ...@@ -466,6 +511,7 @@ do to avoid problems:
- "This increases performance on typical machines..." - "This increases performance on typical machines..."
Bad things you should avoid saying: Bad things you should avoid saying:
- "We did it this way in AIX/ptx/Solaris, so therefore it must be - "We did it this way in AIX/ptx/Solaris, so therefore it must be
good..." good..."
- "I've being doing this for 20 years, so..." - "I've being doing this for 20 years, so..."
...@@ -527,17 +573,18 @@ The reasons for breaking things up are the following: ...@@ -527,17 +573,18 @@ The reasons for breaking things up are the following:
and simplify (or simply re-order) patches before submitting them. and simplify (or simply re-order) patches before submitting them.
Here is an analogy from kernel developer Al Viro: Here is an analogy from kernel developer Al Viro:
"Think of a teacher grading homework from a math student. The
*"Think of a teacher grading homework from a math student. The
teacher does not want to see the student's trials and errors teacher does not want to see the student's trials and errors
before they came up with the solution. They want to see the before they came up with the solution. They want to see the
cleanest, most elegant answer. A good student knows this, and cleanest, most elegant answer. A good student knows this, and
would never submit her intermediate work before the final would never submit her intermediate work before the final
solution." solution.*
The same is true of kernel development. The maintainers and *The same is true of kernel development. The maintainers and
reviewers do not want to see the thought process behind the reviewers do not want to see the thought process behind the
solution to the problem one is solving. They want to see a solution to the problem one is solving. They want to see a
simple and elegant solution." simple and elegant solution."*
It may be challenging to keep the balance between presenting an elegant It may be challenging to keep the balance between presenting an elegant
solution and working together with the community and discussing your solution and working together with the community and discussing your
...@@ -565,6 +612,7 @@ When sending in your patches, pay special attention to what you say in ...@@ -565,6 +612,7 @@ When sending in your patches, pay special attention to what you say in
the text in your email. This information will become the ChangeLog the text in your email. This information will become the ChangeLog
information for the patch, and will be preserved for everyone to see for information for the patch, and will be preserved for everyone to see for
all time. It should describe the patch completely, containing: all time. It should describe the patch completely, containing:
- why the change is necessary - why the change is necessary
- the overall design approach in the patch - the overall design approach in the patch
- implementation details - implementation details
...@@ -572,12 +620,11 @@ all time. It should describe the patch completely, containing: ...@@ -572,12 +620,11 @@ all time. It should describe the patch completely, containing:
For more details on what this should all look like, please see the For more details on what this should all look like, please see the
ChangeLog section of the document: ChangeLog section of the document:
"The Perfect Patch" "The Perfect Patch"
http://www.ozlabs.org/~akpm/stuff/tpp.txt http://www.ozlabs.org/~akpm/stuff/tpp.txt
All of these things are sometimes very hard to do. It can take years to All of these things are sometimes very hard to do. It can take years to
perfect these practices (if at all). It's a continuous process of perfect these practices (if at all). It's a continuous process of
improvement that requires a lot of patience and determination. But improvement that requires a lot of patience and determination. But
...@@ -588,8 +635,9 @@ start exactly where you are now. ...@@ -588,8 +635,9 @@ start exactly where you are now.
---------- ----------
Thanks to Paolo Ciarrocchi who allowed the "Development Process" Thanks to Paolo Ciarrocchi who allowed the "Development Process"
(http://lwn.net/Articles/94386/) section (https://lwn.net/Articles/94386/) section
to be based on text he had written, and to Randy Dunlap and Gerrit to be based on text he had written, and to Randy Dunlap and Gerrit
Huizenga for some of the list of things you should and should not say. Huizenga for some of the list of things you should and should not say.
Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
......
Documentation/Makefile.sphinx
View file @ 02bafd96
...@@ -5,6 +5,9 @@ ...@@ -5,6 +5,9 @@
# You can set these variables from the command line. # You can set these variables from the command line.
SPHINXBUILD = sphinx-build SPHINXBUILD = sphinx-build
SPHINXOPTS = SPHINXOPTS =
SPHINXDIRS = .
_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))
SPHINX_CONF = conf.py
PAPER = PAPER =
BUILDDIR = $(obj)/output BUILDDIR = $(obj)/output
...@@ -25,38 +28,62 @@ else ifneq ($(DOCBOOKS),) ...@@ -25,38 +28,62 @@ else ifneq ($(DOCBOOKS),)
else # HAVE_SPHINX else # HAVE_SPHINX
# User-friendly check for rst2pdf # User-friendly check for pdflatex
HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi) HAVE_PDFLATEX := $(shell if which xelatex >/dev/null 2>&1; then echo 1; else echo 0; fi)
# Internal variables. # Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter PAPEROPT_letter = -D latex_paper_size=letter
KERNELDOC = $(srctree)/scripts/kernel-doc KERNELDOC = $(srctree)/scripts/kernel-doc
KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
ALLSPHINXOPTS = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src) ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
# the i18n builder cannot share the environment and doctrees with the others # the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
quiet_cmd_sphinx = SPHINX $@ # commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
cmd_sphinx = BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2 loop_cmd = $(echo-cmd) $(cmd_$(1))
# $2 sphinx builder e.g. "html"
# $3 name of the build subfolder / e.g. "media", used as:
# * dest folder relative to $(BUILDDIR) and
# * cache folder relative to $(BUILDDIR)/.doctrees
# $4 dest subfolder e.g. "man" for man pages at media/man
# $5 reST source folder relative to $(srctree)/$(src),
# e.g. "media" for the linux-tv book-set at ./Documentation/media
quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4);
cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
$(SPHINXBUILD) \
-b $2 \
-c $(abspath $(srctree)/$(src)) \
-d $(abspath $(BUILDDIR)/.doctrees/$3) \
-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
$(ALLSPHINXOPTS) \
$(abspath $(srctree)/$(src)/$5) \
$(abspath $(BUILDDIR)/$3/$4);
htmldocs: htmldocs:
$(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/media/Makefile $@ @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
$(call cmd,sphinx,html)
pdfdocs: latexdocs:
ifeq ($(HAVE_RST2PDF),0) ifeq ($(HAVE_PDFLATEX),0)
$(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.) $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
@echo " SKIP Sphinx $@ target." @echo " SKIP Sphinx $@ target."
else # HAVE_RST2PDF else # HAVE_PDFLATEX
$(call cmd,sphinx,pdf) @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
endif # HAVE_RST2PDF endif # HAVE_PDFLATEX
pdfdocs: latexdocs
ifneq ($(HAVE_PDFLATEX),0)
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex)
endif # HAVE_PDFLATEX
epubdocs: epubdocs:
$(call cmd,sphinx,epub) @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
xmldocs: xmldocs:
$(call cmd,sphinx,xml) @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
# no-ops for the Sphinx toolchain # no-ops for the Sphinx toolchain
sgmldocs: sgmldocs:
...@@ -72,7 +99,14 @@ endif # HAVE_SPHINX ...@@ -72,7 +99,14 @@ endif # HAVE_SPHINX
dochelp: dochelp:
@echo ' Linux kernel internal documentation in different formats (Sphinx):' @echo ' Linux kernel internal documentation in different formats (Sphinx):'
@echo ' htmldocs - HTML' @echo ' htmldocs - HTML'
@echo ' latexdocs - LaTeX'
@echo ' pdfdocs - PDF' @echo ' pdfdocs - PDF'
@echo ' epubdocs - EPUB' @echo ' epubdocs - EPUB'
@echo ' xmldocs - XML' @echo ' xmldocs - XML'
@echo ' cleandocs - clean all generated files' @echo ' cleandocs - clean all generated files'
@echo
@echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
@echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
@echo
@echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
@echo ' configuration. This is e.g. useful to build with nit-picking config.'
Documentation/ManagementStyle
View file @ 02bafd96
.. _managementstyle:
Linux kernel management style Linux kernel management style
=============================
This is a short document describing the preferred (or made up, depending This is a short document describing the preferred (or made up, depending
on who you ask) management style for the linux kernel. It's meant to on who you ask) management style for the linux kernel. It's meant to
mirror the CodingStyle document to some degree, and mainly written to mirror the CodingStyle document to some degree, and mainly written to
avoid answering (*) the same (or similar) questions over and over again. avoid answering [#f1]_ the same (or similar) questions over and over again.
Management style is very personal and much harder to quantify than Management style is very personal and much harder to quantify than
simple coding style rules, so this document may or may not have anything simple coding style rules, so this document may or may not have anything
...@@ -14,50 +16,52 @@ might not actually be true. You'll have to decide for yourself. ...@@ -14,50 +16,52 @@ might not actually be true. You'll have to decide for yourself.
Btw, when talking about "kernel manager", it's all about the technical Btw, when talking about "kernel manager", it's all about the technical
lead persons, not the people who do traditional management inside lead persons, not the people who do traditional management inside
companies. If you sign purchase orders or you have any clue about the companies. If you sign purchase orders or you have any clue about the
budget of your group, you're almost certainly not a kernel manager. budget of your group, you're almost certainly not a kernel manager.
These suggestions may or may not apply to you. These suggestions may or may not apply to you.
First off, I'd suggest buying "Seven Habits of Highly Effective First off, I'd suggest buying "Seven Habits of Highly Effective
People", and NOT read it. Burn it, it's a great symbolic gesture. People", and NOT read it. Burn it, it's a great symbolic gesture.
(*) This document does so not so much by answering the question, but by .. [#f1] This document does so not so much by answering the question, but by
making it painfully obvious to the questioner that we don't have a clue making it painfully obvious to the questioner that we don't have a clue
to what the answer is. to what the answer is.
Anyway, here goes: Anyway, here goes:
.. _decisions:
Chapter 1: Decisions 1) Decisions
------------
Everybody thinks managers make decisions, and that decision-making is Everybody thinks managers make decisions, and that decision-making is
important. The bigger and more painful the decision, the bigger the important. The bigger and more painful the decision, the bigger the
manager must be to make it. That's very deep and obvious, but it's not manager must be to make it. That's very deep and obvious, but it's not
actually true. actually true.
The name of the game is to _avoid_ having to make a decision. In The name of the game is to **avoid** having to make a decision. In
particular, if somebody tells you "choose (a) or (b), we really need you particular, if somebody tells you "choose (a) or (b), we really need you
to decide on this", you're in trouble as a manager. The people you to decide on this", you're in trouble as a manager. The people you
manage had better know the details better than you, so if they come to manage had better know the details better than you, so if they come to
you for a technical decision, you're screwed. You're clearly not you for a technical decision, you're screwed. You're clearly not
competent to make that decision for them. competent to make that decision for them.
(Corollary:if the people you manage don't know the details better than (Corollary:if the people you manage don't know the details better than
you, you're also screwed, although for a totally different reason. you, you're also screwed, although for a totally different reason.
Namely that you are in the wrong job, and that _they_ should be managing Namely that you are in the wrong job, and that **they** should be managing
your brilliance instead). your brilliance instead).
So the name of the game is to _avoid_ decisions, at least the big and So the name of the game is to **avoid** decisions, at least the big and
painful ones. Making small and non-consequential decisions is fine, and painful ones. Making small and non-consequential decisions is fine, and
makes you look like you know what you're doing, so what a kernel manager makes you look like you know what you're doing, so what a kernel manager
needs to do is to turn the big and painful ones into small things where needs to do is to turn the big and painful ones into small things where
nobody really cares. nobody really cares.
It helps to realize that the key difference between a big decision and a It helps to realize that the key difference between a big decision and a
small one is whether you can fix your decision afterwards. Any decision small one is whether you can fix your decision afterwards. Any decision
can be made small by just always making sure that if you were wrong (and can be made small by just always making sure that if you were wrong (and
you _will_ be wrong), you can always undo the damage later by you **will** be wrong), you can always undo the damage later by
backtracking. Suddenly, you get to be doubly managerial for making backtracking. Suddenly, you get to be doubly managerial for making
_two_ inconsequential decisions - the wrong one _and_ the right one. **two** inconsequential decisions - the wrong one **and** the right one.
And people will even see that as true leadership (*cough* bullshit And people will even see that as true leadership (*cough* bullshit
*cough*). *cough*).
...@@ -65,10 +69,10 @@ And people will even see that as true leadership (*cough* bullshit ...@@ -65,10 +69,10 @@ And people will even see that as true leadership (*cough* bullshit
Thus the key to avoiding big decisions becomes to just avoiding to do Thus the key to avoiding big decisions becomes to just avoiding to do
things that can't be undone. Don't get ushered into a corner from which things that can't be undone. Don't get ushered into a corner from which
you cannot escape. A cornered rat may be dangerous - a cornered manager you cannot escape. A cornered rat may be dangerous - a cornered manager
is just pitiful. is just pitiful.
It turns out that since nobody would be stupid enough to ever really let It turns out that since nobody would be stupid enough to ever really let
a kernel manager have huge fiscal responsibility _anyway_, it's usually a kernel manager have huge fiscal responsibility **anyway**, it's usually
fairly easy to backtrack. Since you're not going to be able to waste fairly easy to backtrack. Since you're not going to be able to waste
huge amounts of money that you might not be able to repay, the only huge amounts of money that you might not be able to repay, the only
thing you can backtrack on is a technical decision, and there thing you can backtrack on is a technical decision, and there
...@@ -76,113 +80,118 @@ back-tracking is very easy: just tell everybody that you were an ...@@ -76,113 +80,118 @@ back-tracking is very easy: just tell everybody that you were an
incompetent nincompoop, say you're sorry, and undo all the worthless incompetent nincompoop, say you're sorry, and undo all the worthless
work you had people work on for the last year. Suddenly the decision work you had people work on for the last year. Suddenly the decision
you made a year ago wasn't a big decision after all, since it could be you made a year ago wasn't a big decision after all, since it could be
easily undone. easily undone.
It turns out that some people have trouble with this approach, for two It turns out that some people have trouble with this approach, for two
reasons: reasons:
- admitting you were an idiot is harder than it looks. We all like to - admitting you were an idiot is harder than it looks. We all like to
maintain appearances, and coming out in public to say that you were maintain appearances, and coming out in public to say that you were
wrong is sometimes very hard indeed. wrong is sometimes very hard indeed.
- having somebody tell you that what you worked on for the last year - having somebody tell you that what you worked on for the last year
wasn't worthwhile after all can be hard on the poor lowly engineers wasn't worthwhile after all can be hard on the poor lowly engineers
too, and while the actual _work_ was easy enough to undo by just too, and while the actual **work** was easy enough to undo by just
deleting it, you may have irrevocably lost the trust of that deleting it, you may have irrevocably lost the trust of that
engineer. And remember: "irrevocable" was what we tried to avoid in engineer. And remember: "irrevocable" was what we tried to avoid in
the first place, and your decision ended up being a big one after the first place, and your decision ended up being a big one after
all. all.
Happily, both of these reasons can be mitigated effectively by just Happily, both of these reasons can be mitigated effectively by just
admitting up-front that you don't have a friggin' clue, and telling admitting up-front that you don't have a friggin' clue, and telling
people ahead of the fact that your decision is purely preliminary, and people ahead of the fact that your decision is purely preliminary, and
might be the wrong thing. You should always reserve the right to change might be the wrong thing. You should always reserve the right to change
your mind, and make people very _aware_ of that. And it's much easier your mind, and make people very **aware** of that. And it's much easier
to admit that you are stupid when you haven't _yet_ done the really to admit that you are stupid when you haven't **yet** done the really
stupid thing. stupid thing.
Then, when it really does turn out to be stupid, people just roll their Then, when it really does turn out to be stupid, people just roll their
eyes and say "Oops, he did it again". eyes and say "Oops, he did it again".
This preemptive admission of incompetence might also make the people who This preemptive admission of incompetence might also make the people who
actually do the work also think twice about whether it's worth doing or actually do the work also think twice about whether it's worth doing or
not. After all, if _they_ aren't certain whether it's a good idea, you not. After all, if **they** aren't certain whether it's a good idea, you
sure as hell shouldn't encourage them by promising them that what they sure as hell shouldn't encourage them by promising them that what they
work on will be included. Make them at least think twice before they work on will be included. Make them at least think twice before they
embark on a big endeavor. embark on a big endeavor.
Remember: they'd better know more about the details than you do, and Remember: they'd better know more about the details than you do, and
they usually already think they have the answer to everything. The best they usually already think they have the answer to everything. The best
thing you can do as a manager is not to instill confidence, but rather a thing you can do as a manager is not to instill confidence, but rather a
healthy dose of critical thinking on what they do. healthy dose of critical thinking on what they do.
Btw, another way to avoid a decision is to plaintively just whine "can't Btw, another way to avoid a decision is to plaintively just whine "can't
we just do both?" and look pitiful. Trust me, it works. If it's not we just do both?" and look pitiful. Trust me, it works. If it's not
clear which approach is better, they'll eventually figure it out. The clear which approach is better, they'll eventually figure it out. The
answer may end up being that both teams get so frustrated by the answer may end up being that both teams get so frustrated by the
situation that they just give up. situation that they just give up.
That may sound like a failure, but it's usually a sign that there was That may sound like a failure, but it's usually a sign that there was
something wrong with both projects, and the reason the people involved something wrong with both projects, and the reason the people involved
couldn't decide was that they were both wrong. You end up coming up couldn't decide was that they were both wrong. You end up coming up
smelling like roses, and you avoided yet another decision that you could smelling like roses, and you avoided yet another decision that you could
have screwed up on. have screwed up on.
Chapter 2: People 2) People
---------
Most people are idiots, and being a manager means you'll have to deal Most people are idiots, and being a manager means you'll have to deal
with it, and perhaps more importantly, that _they_ have to deal with with it, and perhaps more importantly, that **they** have to deal with
_you_. **you**.
It turns out that while it's easy to undo technical mistakes, it's not It turns out that while it's easy to undo technical mistakes, it's not
as easy to undo personality disorders. You just have to live with as easy to undo personality disorders. You just have to live with
theirs - and yours. theirs - and yours.
However, in order to prepare yourself as a kernel manager, it's best to However, in order to prepare yourself as a kernel manager, it's best to
remember not to burn any bridges, bomb any innocent villagers, or remember not to burn any bridges, bomb any innocent villagers, or
alienate too many kernel developers. It turns out that alienating people alienate too many kernel developers. It turns out that alienating people
is fairly easy, and un-alienating them is hard. Thus "alienating" is fairly easy, and un-alienating them is hard. Thus "alienating"
immediately falls under the heading of "not reversible", and becomes a immediately falls under the heading of "not reversible", and becomes a
no-no according to Chapter 1. no-no according to :ref:`decisions`.
There's just a few simple rules here: There's just a few simple rules here:
(1) don't call people d*ckheads (at least not in public) (1) don't call people d*ckheads (at least not in public)
(2) learn how to apologize when you forgot rule (1) (2) learn how to apologize when you forgot rule (1)
The problem with #1 is that it's very easy to do, since you can say The problem with #1 is that it's very easy to do, since you can say
"you're a d*ckhead" in millions of different ways (*), sometimes without "you're a d*ckhead" in millions of different ways [#f2]_, sometimes without
even realizing it, and almost always with a white-hot conviction that even realizing it, and almost always with a white-hot conviction that
you are right. you are right.
And the more convinced you are that you are right (and let's face it, And the more convinced you are that you are right (and let's face it,
you can call just about _anybody_ a d*ckhead, and you often _will_ be you can call just about **anybody** a d*ckhead, and you often **will** be
right), the harder it ends up being to apologize afterwards. right), the harder it ends up being to apologize afterwards.
To solve this problem, you really only have two options: To solve this problem, you really only have two options:
- get really good at apologies - get really good at apologies
- spread the "love" out so evenly that nobody really ends up feeling - spread the "love" out so evenly that nobody really ends up feeling
like they get unfairly targeted. Make it inventive enough, and they like they get unfairly targeted. Make it inventive enough, and they
might even be amused. might even be amused.
The option of being unfailingly polite really doesn't exist. Nobody will The option of being unfailingly polite really doesn't exist. Nobody will
trust somebody who is so clearly hiding his true character. trust somebody who is so clearly hiding his true character.
(*) Paul Simon sang "Fifty Ways to Leave Your Lover", because quite .. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite
frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't
scan nearly as well. But I'm sure he thought about it. scan nearly as well. But I'm sure he thought about it.
Chapter 3: People II - the Good Kind 3) People II - the Good Kind
----------------------------
While it turns out that most people are idiots, the corollary to that is While it turns out that most people are idiots, the corollary to that is
sadly that you are one too, and that while we can all bask in the secure sadly that you are one too, and that while we can all bask in the secure
knowledge that we're better than the average person (let's face it, knowledge that we're better than the average person (let's face it,
nobody ever believes that they're average or below-average), we should nobody ever believes that they're average or below-average), we should
also admit that we're not the sharpest knife around, and there will be also admit that we're not the sharpest knife around, and there will be
other people that are less of an idiot than you are. other people that are less of an idiot than you are.
Some people react badly to smart people. Others take advantage of them. Some people react badly to smart people. Others take advantage of them.
Make sure that you, as a kernel maintainer, are in the second group. Make sure that you, as a kernel maintainer, are in the second group.
Suck up to them, because they are the people who will make your job Suck up to them, because they are the people who will make your job
easier. In particular, they'll be able to make your decisions for you, easier. In particular, they'll be able to make your decisions for you,
which is what the game is all about. which is what the game is all about.
...@@ -191,7 +200,7 @@ So when you find somebody smarter than you are, just coast along. Your ...@@ -191,7 +200,7 @@ So when you find somebody smarter than you are, just coast along. Your
management responsibilities largely become ones of saying "Sounds like a management responsibilities largely become ones of saying "Sounds like a
good idea - go wild", or "That sounds good, but what about xxx?". The good idea - go wild", or "That sounds good, but what about xxx?". The
second version in particular is a great way to either learn something second version in particular is a great way to either learn something
new about "xxx" or seem _extra_ managerial by pointing out something the new about "xxx" or seem **extra** managerial by pointing out something the
smarter person hadn't thought about. In either case, you win. smarter person hadn't thought about. In either case, you win.
One thing to look out for is to realize that greatness in one area does One thing to look out for is to realize that greatness in one area does
...@@ -199,47 +208,49 @@ not necessarily translate to other areas. So you might prod people in ...@@ -199,47 +208,49 @@ not necessarily translate to other areas. So you might prod people in
specific directions, but let's face it, they might be good at what they specific directions, but let's face it, they might be good at what they
do, and suck at everything else. The good news is that people tend to do, and suck at everything else. The good news is that people tend to
naturally gravitate back to what they are good at, so it's not like you naturally gravitate back to what they are good at, so it's not like you
are doing something irreversible when you _do_ prod them in some are doing something irreversible when you **do** prod them in some
direction, just don't push too hard. direction, just don't push too hard.
Chapter 4: Placing blame 4) Placing blame
----------------
Things will go wrong, and people want somebody to blame. Tag, you're it. Things will go wrong, and people want somebody to blame. Tag, you're it.
It's not actually that hard to accept the blame, especially if people It's not actually that hard to accept the blame, especially if people
kind of realize that it wasn't _all_ your fault. Which brings us to the kind of realize that it wasn't **all** your fault. Which brings us to the
best way of taking the blame: do it for another guy. You'll feel good best way of taking the blame: do it for another guy. You'll feel good
for taking the fall, he'll feel good about not getting blamed, and the for taking the fall, he'll feel good about not getting blamed, and the
guy who lost his whole 36GB porn-collection because of your incompetence guy who lost his whole 36GB porn-collection because of your incompetence
will grudgingly admit that you at least didn't try to weasel out of it. will grudgingly admit that you at least didn't try to weasel out of it.
Then make the developer who really screwed up (if you can find him) know Then make the developer who really screwed up (if you can find him) know
_in_private_ that he screwed up. Not just so he can avoid it in the **in_private** that he screwed up. Not just so he can avoid it in the
future, but so that he knows he owes you one. And, perhaps even more future, but so that he knows he owes you one. And, perhaps even more
importantly, he's also likely the person who can fix it. Because, let's importantly, he's also likely the person who can fix it. Because, let's
face it, it sure ain't you. face it, it sure ain't you.
Taking the blame is also why you get to be manager in the first place. Taking the blame is also why you get to be manager in the first place.
It's part of what makes people trust you, and allow you the potential It's part of what makes people trust you, and allow you the potential
glory, because you're the one who gets to say "I screwed up". And if glory, because you're the one who gets to say "I screwed up". And if
you've followed the previous rules, you'll be pretty good at saying that you've followed the previous rules, you'll be pretty good at saying that
by now. by now.
Chapter 5: Things to avoid 5) Things to avoid
------------------
There's one thing people hate even more than being called "d*ckhead", There's one thing people hate even more than being called "d*ckhead",
and that is being called a "d*ckhead" in a sanctimonious voice. The and that is being called a "d*ckhead" in a sanctimonious voice. The
first you can apologize for, the second one you won't really get the first you can apologize for, the second one you won't really get the
chance. They likely will no longer be listening even if you otherwise chance. They likely will no longer be listening even if you otherwise
do a good job. do a good job.
We all think we're better than anybody else, which means that when We all think we're better than anybody else, which means that when
somebody else puts on airs, it _really_ rubs us the wrong way. You may somebody else puts on airs, it **really** rubs us the wrong way. You may
be morally and intellectually superior to everybody around you, but be morally and intellectually superior to everybody around you, but
don't try to make it too obvious unless you really _intend_ to irritate don't try to make it too obvious unless you really **intend** to irritate
somebody (*). somebody [#f3]_.
Similarly, don't be too polite or subtle about things. Politeness easily Similarly, don't be too polite or subtle about things. Politeness easily
ends up going overboard and hiding the problem, and as they say, "On the ends up going overboard and hiding the problem, and as they say, "On the
...@@ -251,15 +262,16 @@ Some humor can help pad both the bluntness and the moralizing. Going ...@@ -251,15 +262,16 @@ Some humor can help pad both the bluntness and the moralizing. Going
overboard to the point of being ridiculous can drive a point home overboard to the point of being ridiculous can drive a point home
without making it painful to the recipient, who just thinks you're being without making it painful to the recipient, who just thinks you're being
silly. It can thus help get through the personal mental block we all silly. It can thus help get through the personal mental block we all
have about criticism. have about criticism.
(*) Hint: internet newsgroups that are not directly related to your work .. [#f3] Hint: internet newsgroups that are not directly related to your work
are great ways to take out your frustrations at other people. Write are great ways to take out your frustrations at other people. Write
insulting posts with a sneer just to get into a good flame every once in insulting posts with a sneer just to get into a good flame every once in
a while, and you'll feel cleansed. Just don't crap too close to home. a while, and you'll feel cleansed. Just don't crap too close to home.
Chapter 6: Why me? 6) Why me?
----------
Since your main responsibility seems to be to take the blame for other Since your main responsibility seems to be to take the blame for other
peoples mistakes, and make it painfully obvious to everybody else that peoples mistakes, and make it painfully obvious to everybody else that
...@@ -268,9 +280,9 @@ first place? ...@@ -268,9 +280,9 @@ first place?
First off, while you may or may not get screaming teenage girls (or First off, while you may or may not get screaming teenage girls (or
boys, let's not be judgmental or sexist here) knocking on your dressing boys, let's not be judgmental or sexist here) knocking on your dressing
room door, you _will_ get an immense feeling of personal accomplishment room door, you **will** get an immense feeling of personal accomplishment
for being "in charge". Never mind the fact that you're really leading for being "in charge". Never mind the fact that you're really leading
by trying to keep up with everybody else and running after them as fast by trying to keep up with everybody else and running after them as fast
as you can. Everybody will still think you're the person in charge. as you can. Everybody will still think you're the person in charge.
It's a great job if you can hack it. It's a great job if you can hack it.
Documentation/SecurityBugs
View file @ 02bafd96
.. _securitybugs:
Security bugs
=============
Linux kernel developers take security very seriously. As such, we'd Linux kernel developers take security very seriously. As such, we'd
like to know when a security bug is found so that it can be fixed and like to know when a security bug is found so that it can be fixed and
disclosed as quickly as possible. Please report security bugs to the disclosed as quickly as possible. Please report security bugs to the
Linux kernel security team. Linux kernel security team.
1) Contact 1) Contact
----------
The Linux kernel security team can be contacted by email at The Linux kernel security team can be contacted by email at
<security@kernel.org>. This is a private list of security officers <security@kernel.org>. This is a private list of security officers
...@@ -18,6 +24,7 @@ Any exploit code is very helpful and will not be released without ...@@ -18,6 +24,7 @@ Any exploit code is very helpful and will not be released without
consent from the reporter unless it has already been made public. consent from the reporter unless it has already been made public.
2) Disclosure 2) Disclosure
-------------
The goal of the Linux kernel security team is to work with the The goal of the Linux kernel security team is to work with the
bug submitter to bug resolution as well as disclosure. We prefer bug submitter to bug resolution as well as disclosure. We prefer
...@@ -33,6 +40,7 @@ to a few weeks. As a basic default policy, we expect report date to ...@@ -33,6 +40,7 @@ to a few weeks. As a basic default policy, we expect report date to
disclosure date to be on the order of 7 days. disclosure date to be on the order of 7 days.
3) Non-disclosure agreements 3) Non-disclosure agreements
----------------------------
The Linux kernel security team is not a formal body and therefore unable The Linux kernel security team is not a formal body and therefore unable
to enter any non-disclosure agreements. to enter any non-disclosure agreements.
Documentation/SubmitChecklist
View file @ 02bafd96
.. _submitchecklist:
Linux Kernel patch submission checklist Linux Kernel patch submission checklist
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here are some basic things that developers should do if they want to see their Here are some basic things that developers should do if they want to see their
kernel patch submissions accepted more quickly. kernel patch submissions accepted more quickly.
These are all above and beyond the documentation that is provided in These are all above and beyond the documentation that is provided in
Documentation/SubmittingPatches and elsewhere regarding submitting Linux :ref:`Documentation/SubmittingPatches <submittingpatches>`
kernel patches. and elsewhere regarding submitting Linux kernel patches.
1: If you use a facility then #include the file that defines/declares 1) If you use a facility then #include the file that defines/declares
that facility. Don't depend on other header files pulling in ones that facility. Don't depend on other header files pulling in ones
that you use. that you use.
2: Builds cleanly with applicable or modified CONFIG options =y, =m, and 2) Builds cleanly:
=n. No gcc warnings/errors, no linker warnings/errors.
a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and
``=n``. No ``gcc`` warnings/errors, no linker warnings/errors.
2b: Passes allnoconfig, allmodconfig b) Passes ``allnoconfig``, ``allmodconfig``
2c: Builds successfully when using O=builddir c) Builds successfully when using ``O=builddir``
3: Builds on multiple CPU architectures by using local cross-compile tools 3) Builds on multiple CPU architectures by using local cross-compile tools
or some other build farm. or some other build farm.
4: ppc64 is a good architecture for cross-compilation checking because it 4) ppc64 is a good architecture for cross-compilation checking because it
tends to use `unsigned long' for 64-bit quantities. tends to use ``unsigned long`` for 64-bit quantities.
5: Check your patch for general style as detailed in 5) Check your patch for general style as detailed in
Documentation/CodingStyle. Check for trivial violations with the :ref:`Documentation/CodingStyle <codingstyle>`.
patch style checker prior to submission (scripts/checkpatch.pl). Check for trivial violations with the patch style checker prior to
submission (``scripts/checkpatch.pl``).
You should be able to justify all violations that remain in You should be able to justify all violations that remain in
your patch. your patch.
6: Any new or modified CONFIG options don't muck up the config menu. 6) Any new or modified ``CONFIG`` options don't muck up the config menu.
7: All new Kconfig options have help text. 7) All new ``Kconfig`` options have help text.
8: Has been carefully reviewed with respect to relevant Kconfig 8) Has been carefully reviewed with respect to relevant ``Kconfig``
combinations. This is very hard to get right with testing -- brainpower combinations. This is very hard to get right with testing -- brainpower
pays off here. pays off here.
9: Check cleanly with sparse. 9) Check cleanly with sparse.
10) Use ``make checkstack`` and ``make namespacecheck`` and fix any problems
that they find.
.. note::
10: Use 'make checkstack' and 'make namespacecheck' and fix any problems ``checkstack`` does not point out problems explicitly,
that they find. Note: checkstack does not point out problems explicitly, but any one function that uses more than 512 bytes on the stack is a
but any one function that uses more than 512 bytes on the stack is a candidate for change.
candidate for change.
11: Include kernel-doc to document global kernel APIs. (Not required for 11) Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs.
static functions, but OK there also.) Use 'make htmldocs' or 'make (Not required for static functions, but OK there also.) Use
mandocs' to check the kernel-doc and fix any issues. ``make htmldocs`` or ``make pdfdocs`` to check the
:ref:`kernel-doc <kernel_doc>` and fix any issues.
12: Has been tested with CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, 12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
CONFIG_DEBUG_SLAB, CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_ATOMIC_SLEEP, CONFIG_PROVE_RCU ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
and CONFIG_DEBUG_OBJECTS_RCU_HEAD all simultaneously enabled. ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all
simultaneously enabled.
13: Has been build- and runtime tested with and without CONFIG_SMP and 13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and
CONFIG_PREEMPT. ``CONFIG_PREEMPT.``
14: If the patch affects IO/Disk, etc: has been tested with and without 14) If the patch affects IO/Disk, etc: has been tested with and without
CONFIG_LBDAF. ``CONFIG_LBDAF.``
15: All codepaths have been exercised with all lockdep features enabled. 15) All codepaths have been exercised with all lockdep features enabled.
16: All new /proc entries are documented under Documentation/ 16) All new ``/proc`` entries are documented under ``Documentation/``
17: All new kernel boot parameters are documented in 17) All new kernel boot parameters are documented in
Documentation/kernel-parameters.txt. ``Documentation/kernel-parameters.txt``.
18: All new module parameters are documented with MODULE_PARM_DESC() 18) All new module parameters are documented with ``MODULE_PARM_DESC()``
19: All new userspace interfaces are documented in Documentation/ABI/. 19) All new userspace interfaces are documented in ``Documentation/ABI/``.
See Documentation/ABI/README for more information. See ``Documentation/ABI/README`` for more information.
Patches that change userspace interfaces should be CCed to Patches that change userspace interfaces should be CCed to
linux-api@vger.kernel.org. linux-api@vger.kernel.org.
20: Check that it all passes `make headers_check'. 20) Check that it all passes ``make headers_check``.
21: Has been checked with injection of at least slab and page-allocation 21) Has been checked with injection of at least slab and page-allocation
failures. See Documentation/fault-injection/. failures. See ``Documentation/fault-injection/``.
If the new code is substantial, addition of subsystem-specific fault If the new code is substantial, addition of subsystem-specific fault
injection might be appropriate. injection might be appropriate.
22: Newly-added code has been compiled with `gcc -W' (use "make 22) Newly-added code has been compiled with ``gcc -W`` (use
EXTRA_CFLAGS=-W"). This will generate lots of noise, but is good for ``make EXTRA_CFLAGS=-W``). This will generate lots of noise, but is good
finding bugs like "warning: comparison between signed and unsigned". for finding bugs like "warning: comparison between signed and unsigned".
23: Tested after it has been merged into the -mm patchset to make sure 23) Tested after it has been merged into the -mm patchset to make sure
that it still works with all of the other queued patches and various that it still works with all of the other queued patches and various
changes in the VM, VFS, and other subsystems. changes in the VM, VFS, and other subsystems.
24: All memory barriers {e.g., barrier(), rmb(), wmb()} need a comment in the 24) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a
source code that explains the logic of what they are doing and why. comment in the source code that explains the logic of what they are doing
and why.
25: If any ioctl's are added by the patch, then also update 25) If any ioctl's are added by the patch, then also update
Documentation/ioctl/ioctl-number.txt. ``Documentation/ioctl/ioctl-number.txt``.
26: If your modified source code depends on or uses any of the kernel 26) If your modified source code depends on or uses any of the kernel
APIs or features that are related to the following kconfig symbols, APIs or features that are related to the following ``Kconfig`` symbols,
then test multiple builds with the related kconfig symbols disabled then test multiple builds with the related ``Kconfig`` symbols disabled
and/or =m (if that option is available) [not all of these at the and/or ``=m`` (if that option is available) [not all of these at the
same time, just various/random combinations of them]: same time, just various/random combinations of them]:
CONFIG_SMP, CONFIG_SYSFS, CONFIG_PROC_FS, CONFIG_INPUT, CONFIG_PCI, ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
CONFIG_BLOCK, CONFIG_PM, CONFIG_MAGIC_SYSRQ, ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``).
CONFIG_NET, CONFIG_INET=n (but latter with CONFIG_NET=y)
Documentation/SubmittingDrivers
View file @ 02bafd96
.. _submittingdrivers:
Submitting Drivers For The Linux Kernel Submitting Drivers For The Linux Kernel
--------------------------------------- =======================================
This document is intended to explain how to submit device drivers to the This document is intended to explain how to submit device drivers to the
various kernel trees. Note that if you are interested in video card drivers various kernel trees. Note that if you are interested in video card drivers
...@@ -38,42 +40,48 @@ Linux 2.4: ...@@ -38,42 +40,48 @@ Linux 2.4:
maintainer does not respond or you cannot find the appropriate maintainer does not respond or you cannot find the appropriate
maintainer then please contact Willy Tarreau <w@1wt.eu>. maintainer then please contact Willy Tarreau <w@1wt.eu>.
Linux 2.6: Linux 2.6 and upper:
The same rules apply as 2.4 except that you should follow linux-kernel The same rules apply as 2.4 except that you should follow linux-kernel
to track changes in API's. The final contact point for Linux 2.6 to track changes in API's. The final contact point for Linux 2.6+
submissions is Andrew Morton. submissions is Andrew Morton.
What Criteria Determine Acceptance What Criteria Determine Acceptance
---------------------------------- ----------------------------------
Licensing: The code must be released to us under the Licensing:
The code must be released to us under the
GNU General Public License. We don't insist on any kind GNU General Public License. We don't insist on any kind
of exclusive GPL licensing, and if you wish the driver of exclusive GPL licensing, and if you wish the driver
to be useful to other communities such as BSD you may well to be useful to other communities such as BSD you may well
wish to release under multiple licenses. wish to release under multiple licenses.
See accepted licenses at include/linux/module.h See accepted licenses at include/linux/module.h
Copyright: The copyright owner must agree to use of GPL. Copyright:
The copyright owner must agree to use of GPL.
It's best if the submitter and copyright owner It's best if the submitter and copyright owner
are the same person/entity. If not, the name of are the same person/entity. If not, the name of
the person/entity authorizing use of GPL should be the person/entity authorizing use of GPL should be
listed in case it's necessary to verify the will of listed in case it's necessary to verify the will of
the copyright owner. the copyright owner.
Interfaces: If your driver uses existing interfaces and behaves like Interfaces:
If your driver uses existing interfaces and behaves like
other drivers in the same class it will be much more likely other drivers in the same class it will be much more likely
to be accepted than if it invents gratuitous new ones. to be accepted than if it invents gratuitous new ones.
If you need to implement a common API over Linux and NT If you need to implement a common API over Linux and NT
drivers do it in userspace. drivers do it in userspace.
Code: Please use the Linux style of code formatting as documented Code:
in Documentation/CodingStyle. If you have sections of code Please use the Linux style of code formatting as documented
in :ref:`Documentation/CodingStyle <codingStyle>`.
If you have sections of code
that need to be in other formats, for example because they that need to be in other formats, for example because they
are shared with a windows driver kit and you want to are shared with a windows driver kit and you want to
maintain them just once separate them out nicely and note maintain them just once separate them out nicely and note
this fact. this fact.
Portability: Pointers are not always 32bits, not all computers are little Portability:
Pointers are not always 32bits, not all computers are little
endian, people do not all have floating point and you endian, people do not all have floating point and you
shouldn't use inline x86 assembler in your driver without shouldn't use inline x86 assembler in your driver without
careful thought. Pure x86 drivers generally are not popular. careful thought. Pure x86 drivers generally are not popular.
...@@ -81,12 +89,14 @@ Portability: Pointers are not always 32bits, not all computers are little ...@@ -81,12 +89,14 @@ Portability: Pointers are not always 32bits, not all computers are little
but it is easy to make sure the code can easily be made but it is easy to make sure the code can easily be made
portable. portable.
Clarity: It helps if anyone can see how to fix the driver. It helps Clarity:
It helps if anyone can see how to fix the driver. It helps
you because you get patches not bug reports. If you submit a you because you get patches not bug reports. If you submit a
driver that intentionally obfuscates how the hardware works driver that intentionally obfuscates how the hardware works
it will go in the bitbucket. it will go in the bitbucket.
PM support: Since Linux is used on many portable and desktop systems, your PM support:
Since Linux is used on many portable and desktop systems, your
driver is likely to be used on such a system and therefore it driver is likely to be used on such a system and therefore it
should support basic power management by implementing, if should support basic power management by implementing, if
necessary, the .suspend and .resume methods used during the necessary, the .suspend and .resume methods used during the
...@@ -101,7 +111,8 @@ PM support: Since Linux is used on many portable and desktop systems, your ...@@ -101,7 +111,8 @@ PM support: Since Linux is used on many portable and desktop systems, your
complete overview of the power management issues related to complete overview of the power management issues related to
drivers see Documentation/power/devices.txt . drivers see Documentation/power/devices.txt .
Control: In general if there is active maintenance of a driver by Control:
In general if there is active maintenance of a driver by
the author then patches will be redirected to them unless the author then patches will be redirected to them unless
they are totally obvious and without need of checking. they are totally obvious and without need of checking.
If you want to be the contact and update point for the If you want to be the contact and update point for the
...@@ -111,13 +122,15 @@ Control: In general if there is active maintenance of a driver by ...@@ -111,13 +122,15 @@ Control: In general if there is active maintenance of a driver by
What Criteria Do Not Determine Acceptance What Criteria Do Not Determine Acceptance
----------------------------------------- -----------------------------------------
Vendor: Being the hardware vendor and maintaining the driver is Vendor:
Being the hardware vendor and maintaining the driver is
often a good thing. If there is a stable working driver from often a good thing. If there is a stable working driver from
other people already in the tree don't expect 'we are the other people already in the tree don't expect 'we are the
vendor' to get your driver chosen. Ideally work with the vendor' to get your driver chosen. Ideally work with the
existing driver author to build a single perfect driver. existing driver author to build a single perfect driver.
Author: It doesn't matter if a large Linux company wrote the driver, Author:
It doesn't matter if a large Linux company wrote the driver,
or you did. Nobody has any special access to the kernel or you did. Nobody has any special access to the kernel
tree. Anyone who tells you otherwise isn't telling the tree. Anyone who tells you otherwise isn't telling the
whole story. whole story.
...@@ -127,8 +140,10 @@ Resources ...@@ -127,8 +140,10 @@ Resources
--------- ---------
Linux kernel master tree: Linux kernel master tree:
ftp.??.kernel.org:/pub/linux/kernel/... ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/...
?? == your country code, such as "us", "uk", "fr", etc.
where *country_code* == your country code, such as
**us**, **uk**, **fr**, etc.
http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git
...@@ -141,14 +156,19 @@ Linux Device Drivers, Third Edition (covers 2.6.10): ...@@ -141,14 +156,19 @@ Linux Device Drivers, Third Edition (covers 2.6.10):
LWN.net: LWN.net:
Weekly summary of kernel development activity - http://lwn.net/ Weekly summary of kernel development activity - http://lwn.net/
2.6 API changes: 2.6 API changes:
http://lwn.net/Articles/2.6-kernel-api/ http://lwn.net/Articles/2.6-kernel-api/
Porting drivers from prior kernels to 2.6: Porting drivers from prior kernels to 2.6:
http://lwn.net/Articles/driver-porting/ http://lwn.net/Articles/driver-porting/
KernelNewbies: KernelNewbies:
Documentation and assistance for new kernel programmers Documentation and assistance for new kernel programmers
http://kernelnewbies.org/
http://kernelnewbies.org/
Linux USB project: Linux USB project:
http://www.linux-usb.org/ http://www.linux-usb.org/
......
Documentation/SubmittingPatches
View file @ 02bafd96
.. _submittingpatches:
How to Get Your Change Into the Linux Kernel How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
or =========================================================================================
Care And Operation Of Your Linus Torvalds
For a person or company who wishes to submit a change to the Linux For a person or company who wishes to submit a change to the Linux
kernel, the process can sometimes be daunting if you're not familiar kernel, the process can sometimes be daunting if you're not familiar
...@@ -12,57 +10,59 @@ can greatly increase the chances of your change being accepted. ...@@ -12,57 +10,59 @@ can greatly increase the chances of your change being accepted.
This document contains a large number of suggestions in a relatively terse This document contains a large number of suggestions in a relatively terse
format. For detailed information on how the kernel development process format. For detailed information on how the kernel development process
works, see Documentation/development-process. Also, read works, see :ref:`Documentation/development-process <development_process_main>`.
Documentation/SubmitChecklist for a list of items to check before Also, read :ref:`Documentation/SubmitChecklist <submitchecklist>`
for a list of items to check before
submitting code. If you are submitting a driver, also read submitting code. If you are submitting a driver, also read
Documentation/SubmittingDrivers; for device tree binding patches, read :ref:`Documentation/SubmittingDrivers <submittingdrivers>`;
for device tree binding patches, read
Documentation/devicetree/bindings/submitting-patches.txt. Documentation/devicetree/bindings/submitting-patches.txt.
Many of these steps describe the default behavior of the git version Many of these steps describe the default behavior of the ``git`` version
control system; if you use git to prepare your patches, you'll find much control system; if you use ``git`` to prepare your patches, you'll find much
of the mechanical work done for you, though you'll still need to prepare of the mechanical work done for you, though you'll still need to prepare
and document a sensible set of patches. In general, use of git will make and document a sensible set of patches. In general, use of ``git`` will make
your life as a kernel developer easier. your life as a kernel developer easier.
-------------------------------------------- Creating and Sending your Change
SECTION 1 - CREATING AND SENDING YOUR CHANGE ********************************
--------------------------------------------
0) Obtain a current source tree 0) Obtain a current source tree
------------------------------- -------------------------------
If you do not have a repository with the current kernel source handy, use If you do not have a repository with the current kernel source handy, use
git to obtain one. You'll want to start with the mainline repository, ``git`` to obtain one. You'll want to start with the mainline repository,
which can be grabbed with: which can be grabbed with::
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Note, however, that you may not want to develop against the mainline tree Note, however, that you may not want to develop against the mainline tree
directly. Most subsystem maintainers run their own trees and want to see directly. Most subsystem maintainers run their own trees and want to see
patches prepared against those trees. See the "T:" entry for the subsystem patches prepared against those trees. See the **T:** entry for the subsystem
in the MAINTAINERS file to find that tree, or simply ask the maintainer if in the MAINTAINERS file to find that tree, or simply ask the maintainer if
the tree is not listed there. the tree is not listed there.
It is still possible to download kernel releases via tarballs (as described It is still possible to download kernel releases via tarballs (as described
in the next section), but that is the hard way to do kernel development. in the next section), but that is the hard way to do kernel development.
1) "diff -up" 1) ``diff -up``
------------ ---------------
If you must generate your patches by hand, use "diff -up" or "diff -uprN" If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN``
to create patches. Git generates patches in this form by default; if to create patches. Git generates patches in this form by default; if
you're using git, you can skip this section entirely. you're using ``git``, you can skip this section entirely.
All changes to the Linux kernel occur in the form of patches, as All changes to the Linux kernel occur in the form of patches, as
generated by diff(1). When creating your patch, make sure to create it generated by :manpage:`diff(1)`. When creating your patch, make sure to
in "unified diff" format, as supplied by the '-u' argument to diff(1). create it in "unified diff" format, as supplied by the ``-u`` argument
Also, please use the '-p' argument which shows which C function each to :manpage:`diff(1)`.
change is in - that makes the resultant diff a lot easier to read. Also, please use the ``-p`` argument which shows which C function each
change is in - that makes the resultant ``diff`` a lot easier to read.
Patches should be based in the root kernel source directory, Patches should be based in the root kernel source directory,
not in any lower subdirectory. not in any lower subdirectory.
To create a patch for a single file, it is often sufficient to do: To create a patch for a single file, it is often sufficient to do::
SRCTREE= linux SRCTREE= linux
MYFILE= drivers/net/mydriver.c MYFILE= drivers/net/mydriver.c
...@@ -74,8 +74,8 @@ To create a patch for a single file, it is often sufficient to do: ...@@ -74,8 +74,8 @@ To create a patch for a single file, it is often sufficient to do:
diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
To create a patch for multiple files, you should unpack a "vanilla", To create a patch for multiple files, you should unpack a "vanilla",
or unmodified kernel source tree, and generate a diff against your or unmodified kernel source tree, and generate a ``diff`` against your
own source tree. For example: own source tree. For example::
MYSRC= /devel/linux MYSRC= /devel/linux
...@@ -84,27 +84,27 @@ own source tree. For example: ...@@ -84,27 +84,27 @@ own source tree. For example:
diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
linux-3.19-vanilla $MYSRC > /tmp/patch linux-3.19-vanilla $MYSRC > /tmp/patch
"dontdiff" is a list of files which are generated by the kernel during ``dontdiff`` is a list of files which are generated by the kernel during
the build process, and should be ignored in any diff(1)-generated the build process, and should be ignored in any :manpage:`diff(1)`-generated
patch. patch.
Make sure your patch does not include any extra files which do not Make sure your patch does not include any extra files which do not
belong in a patch submission. Make sure to review your patch -after- belong in a patch submission. Make sure to review your patch -after-
generating it with diff(1), to ensure accuracy. generating it with :manpage:`diff(1)`, to ensure accuracy.
If your changes produce a lot of deltas, you need to split them into If your changes produce a lot of deltas, you need to split them into
individual patches which modify things in logical stages; see section individual patches which modify things in logical stages; see
#3. This will facilitate review by other kernel developers, :ref:`split_changes`. This will facilitate review by other kernel developers,
very important if you want your patch accepted. very important if you want your patch accepted.
If you're using git, "git rebase -i" can help you with this process. If If you're using ``git``, ``git rebase -i`` can help you with this process. If
you're not using git, quilt <http://savannah.nongnu.org/projects/quilt> you're not using ``git``, ``quilt`` <http://savannah.nongnu.org/projects/quilt>
is another popular alternative. is another popular alternative.
.. _describe_changes:
2) Describe your changes
2) Describe your changes. ------------------------
-------------------------
Describe your problem. Whether your patch is a one-line bug fix or Describe your problem. Whether your patch is a one-line bug fix or
5000 lines of a new feature, there must be an underlying problem that 5000 lines of a new feature, there must be an underlying problem that
...@@ -137,11 +137,11 @@ as you intend it to. ...@@ -137,11 +137,11 @@ as you intend it to.
The maintainer will thank you if you write your patch description in a The maintainer will thank you if you write your patch description in a
form which can be easily pulled into Linux's source code management form which can be easily pulled into Linux's source code management
system, git, as a "commit log". See #15, below. system, ``git``, as a "commit log". See :ref:`explicit_in_reply_to`.
Solve only one problem per patch. If your description starts to get Solve only one problem per patch. If your description starts to get
long, that's a sign that you probably need to split up your patch. long, that's a sign that you probably need to split up your patch.
See #3, next. See :ref:`split_changes`.
When you submit or resubmit a patch or patch series, include the When you submit or resubmit a patch or patch series, include the
complete patch description and justification for it. Don't just complete patch description and justification for it. Don't just
...@@ -160,7 +160,7 @@ its behaviour. ...@@ -160,7 +160,7 @@ its behaviour.
If the patch fixes a logged bug entry, refer to that bug entry by If the patch fixes a logged bug entry, refer to that bug entry by
number and URL. If the patch follows from a mailing list discussion, number and URL. If the patch follows from a mailing list discussion,
give a URL to the mailing list archive; use the https://lkml.kernel.org/ give a URL to the mailing list archive; use the https://lkml.kernel.org/
redirector with a Message-Id, to ensure that the links cannot become redirector with a ``Message-Id``, to ensure that the links cannot become
stale. stale.
However, try to make your explanation understandable without external However, try to make your explanation understandable without external
...@@ -171,7 +171,7 @@ patch as submitted. ...@@ -171,7 +171,7 @@ patch as submitted.
If you want to refer to a specific commit, don't just refer to the If you want to refer to a specific commit, don't just refer to the
SHA-1 ID of the commit. Please also include the oneline summary of SHA-1 ID of the commit. Please also include the oneline summary of
the commit, to make it easier for reviewers to know what it is about. the commit, to make it easier for reviewers to know what it is about.
Example: Example::
Commit e21d2170f36602ae2708 ("video: remove unnecessary Commit e21d2170f36602ae2708 ("video: remove unnecessary
platform_set_drvdata()") removed the unnecessary platform_set_drvdata()") removed the unnecessary
...@@ -185,23 +185,25 @@ there is no collision with your six-character ID now, that condition may ...@@ -185,23 +185,25 @@ there is no collision with your six-character ID now, that condition may
change five years from now. change five years from now.
If your patch fixes a bug in a specific commit, e.g. you found an issue using If your patch fixes a bug in a specific commit, e.g. you found an issue using
git-bisect, please use the 'Fixes:' tag with the first 12 characters of the ``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
SHA-1 ID, and the one line summary. For example: the SHA-1 ID, and the one line summary. For example::
Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
The following git-config settings can be used to add a pretty format for The following ``git config`` settings can be used to add a pretty format for
outputting the above style in the git log or git show commands outputting the above style in the ``git log`` or ``git show`` commands::
[core] [core]
abbrev = 12 abbrev = 12
[pretty] [pretty]
fixes = Fixes: %h (\"%s\") fixes = Fixes: %h (\"%s\")
3) Separate your changes. .. _split_changes:
-------------------------
3) Separate your changes
------------------------
Separate each _logical change_ into a separate patch. Separate each **logical change** into a separate patch.
For example, if your changes include both bug fixes and performance For example, if your changes include both bug fixes and performance
enhancements for a single driver, separate those changes into two enhancements for a single driver, separate those changes into two
...@@ -217,12 +219,12 @@ change that can be verified by reviewers. Each patch should be justifiable ...@@ -217,12 +219,12 @@ change that can be verified by reviewers. Each patch should be justifiable
on its own merits. on its own merits.
If one patch depends on another patch in order for a change to be If one patch depends on another patch in order for a change to be
complete, that is OK. Simply note "this patch depends on patch X" complete, that is OK. Simply note **"this patch depends on patch X"**
in your patch description. in your patch description.
When dividing your change into a series of patches, take special care to When dividing your change into a series of patches, take special care to
ensure that the kernel builds and runs properly after each patch in the ensure that the kernel builds and runs properly after each patch in the
series. Developers using "git bisect" to track down a problem can end up series. Developers using ``git bisect`` to track down a problem can end up
splitting your patch series at any point; they will not thank you if you splitting your patch series at any point; they will not thank you if you
introduce bugs in the middle. introduce bugs in the middle.
...@@ -231,11 +233,13 @@ then only post say 15 or so at a time and wait for review and integration. ...@@ -231,11 +233,13 @@ then only post say 15 or so at a time and wait for review and integration.
4) Style-check your changes. 4) Style-check your changes
---------------------------- ---------------------------
Check your patch for basic style violations, details of which can be Check your patch for basic style violations, details of which can be
found in Documentation/CodingStyle. Failure to do so simply wastes found in
:ref:`Documentation/CodingStyle <codingstyle>`.
Failure to do so simply wastes
the reviewers time and will get your patch rejected, probably the reviewers time and will get your patch rejected, probably
without even being read. without even being read.
...@@ -260,8 +264,8 @@ You should be able to justify all violations that remain in your ...@@ -260,8 +264,8 @@ You should be able to justify all violations that remain in your
patch. patch.
5) Select the recipients for your patch. 5) Select the recipients for your patch
---------------------------------------- ---------------------------------------
You should always copy the appropriate subsystem maintainer(s) on any patch You should always copy the appropriate subsystem maintainer(s) on any patch
to code that they maintain; look through the MAINTAINERS file and the to code that they maintain; look through the MAINTAINERS file and the
...@@ -295,13 +299,14 @@ to allow distributors to get the patch out to users; in such cases, ...@@ -295,13 +299,14 @@ to allow distributors to get the patch out to users; in such cases,
obviously, the patch should not be sent to any public lists. obviously, the patch should not be sent to any public lists.
Patches that fix a severe bug in a released kernel should be directed Patches that fix a severe bug in a released kernel should be directed
toward the stable maintainers by putting a line like this: toward the stable maintainers by putting a line like this::
Cc: stable@vger.kernel.org Cc: stable@vger.kernel.org
into the sign-off area of your patch (note, NOT an email recipient). You into the sign-off area of your patch (note, NOT an email recipient). You
should also read Documentation/stable_kernel_rules.txt in addition to this should also read
file. :ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
in addition to this file.
Note, however, that some subsystem maintainers want to come to their own Note, however, that some subsystem maintainers want to come to their own
conclusions on which patches should go to the stable trees. The networking conclusions on which patches should go to the stable trees. The networking
...@@ -312,28 +317,30 @@ If changes affect userland-kernel interfaces, please send the MAN-PAGES ...@@ -312,28 +317,30 @@ If changes affect userland-kernel interfaces, please send the MAN-PAGES
maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
least a notification of the change, so that some information makes its way least a notification of the change, so that some information makes its way
into the manual pages. User-space API changes should also be copied to into the manual pages. User-space API changes should also be copied to
linux-api@vger.kernel.org. linux-api@vger.kernel.org.
For small patches you may want to CC the Trivial Patch Monkey For small patches you may want to CC the Trivial Patch Monkey
trivial@kernel.org which collects "trivial" patches. Have a look trivial@kernel.org which collects "trivial" patches. Have a look
into the MAINTAINERS file for its current manager. into the MAINTAINERS file for its current manager.
Trivial patches must qualify for one of the following rules: Trivial patches must qualify for one of the following rules:
Spelling fixes in documentation
Spelling fixes for errors which could break grep(1) - Spelling fixes in documentation
Warning fixes (cluttering with useless warnings is bad) - Spelling fixes for errors which could break :manpage:`grep(1)`
Compilation fixes (only if they are actually correct) - Warning fixes (cluttering with useless warnings is bad)
Runtime fixes (only if they actually fix things) - Compilation fixes (only if they are actually correct)
Removing use of deprecated functions/macros - Runtime fixes (only if they actually fix things)
Contact detail and documentation fixes - Removing use of deprecated functions/macros
Non-portable code replaced by portable code (even in arch-specific, - Contact detail and documentation fixes
since people copy, as long as it's trivial) - Non-portable code replaced by portable code (even in arch-specific,
Any fix by the author/maintainer of the file (ie. patch monkey since people copy, as long as it's trivial)
in re-transmission mode) - Any fix by the author/maintainer of the file (ie. patch monkey
in re-transmission mode)
6) No MIME, no links, no compression, no attachments. Just plain text. 6) No MIME, no links, no compression, no attachments. Just plain text
----------------------------------------------------------------------- ----------------------------------------------------------------------
Linus and other kernel developers need to be able to read and comment Linus and other kernel developers need to be able to read and comment
on the changes you are submitting. It is important for a kernel on the changes you are submitting. It is important for a kernel
...@@ -341,8 +348,11 @@ developer to be able to "quote" your changes, using standard e-mail ...@@ -341,8 +348,11 @@ developer to be able to "quote" your changes, using standard e-mail
tools, so that they may comment on specific portions of your code. tools, so that they may comment on specific portions of your code.
For this reason, all patches should be submitted by e-mail "inline". For this reason, all patches should be submitted by e-mail "inline".
WARNING: Be wary of your editor's word-wrap corrupting your patch,
if you choose to cut-n-paste your patch. .. warning::
Be wary of your editor's word-wrap corrupting your patch,
if you choose to cut-n-paste your patch.
Do not attach the patch as a MIME attachment, compressed or not. Do not attach the patch as a MIME attachment, compressed or not.
Many popular e-mail applications will not always transmit a MIME Many popular e-mail applications will not always transmit a MIME
...@@ -353,11 +363,12 @@ decreasing the likelihood of your MIME-attached change being accepted. ...@@ -353,11 +363,12 @@ decreasing the likelihood of your MIME-attached change being accepted.
Exception: If your mailer is mangling patches then someone may ask Exception: If your mailer is mangling patches then someone may ask
you to re-send them using MIME. you to re-send them using MIME.
See Documentation/email-clients.txt for hints about configuring See :ref:`Documentation/email-clients.txt <email_clients>`
your e-mail client so that it sends your patches untouched. for hints about configuring your e-mail client so that it sends your patches
untouched.
7) E-mail size. 7) E-mail size
--------------- --------------
Large changes are not appropriate for mailing lists, and some Large changes are not appropriate for mailing lists, and some
maintainers. If your patch, uncompressed, exceeds 300 kB in size, maintainers. If your patch, uncompressed, exceeds 300 kB in size,
...@@ -366,8 +377,8 @@ server, and provide instead a URL (link) pointing to your patch. But note ...@@ -366,8 +377,8 @@ server, and provide instead a URL (link) pointing to your patch. But note
that if your patch exceeds 300 kB, it almost certainly needs to be broken up that if your patch exceeds 300 kB, it almost certainly needs to be broken up
anyway. anyway.
8) Respond to review comments. 8) Respond to review comments
------------------------------ -----------------------------
Your patch will almost certainly get comments from reviewers on ways in Your patch will almost certainly get comments from reviewers on ways in
which the patch can be improved. You must respond to those comments; which the patch can be improved. You must respond to those comments;
...@@ -382,8 +393,8 @@ reviewers sometimes get grumpy. Even in that case, though, respond ...@@ -382,8 +393,8 @@ reviewers sometimes get grumpy. Even in that case, though, respond
politely and address the problems they have pointed out. politely and address the problems they have pointed out.
9) Don't get discouraged - or impatient. 9) Don't get discouraged - or impatient
---------------------------------------- ---------------------------------------
After you have submitted your change, be patient and wait. Reviewers are After you have submitted your change, be patient and wait. Reviewers are
busy people and may not get to your patch right away. busy people and may not get to your patch right away.
...@@ -419,9 +430,10 @@ patch, which certifies that you wrote it or otherwise have the right to ...@@ -419,9 +430,10 @@ patch, which certifies that you wrote it or otherwise have the right to
pass it on as an open-source patch. The rules are pretty simple: if you pass it on as an open-source patch. The rules are pretty simple: if you
can certify the below: can certify the below:
Developer's Certificate of Origin 1.1 Developer's Certificate of Origin 1.1
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By making a contribution to this project, I certify that: By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I (a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license have the right to submit it under the open source license
...@@ -445,7 +457,7 @@ can certify the below: ...@@ -445,7 +457,7 @@ can certify the below:
maintained indefinitely and may be redistributed consistent with maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved. this project or the open source license(s) involved.
then you just add a line saying then you just add a line saying::
Signed-off-by: Random J Developer <random@developer.example.org> Signed-off-by: Random J Developer <random@developer.example.org>
...@@ -466,7 +478,7 @@ you add a line between the last Signed-off-by header and yours, indicating ...@@ -466,7 +478,7 @@ you add a line between the last Signed-off-by header and yours, indicating
the nature of your changes. While there is nothing mandatory about this, it the nature of your changes. While there is nothing mandatory about this, it
seems like prepending the description with your mail and/or name, all seems like prepending the description with your mail and/or name, all
enclosed in square brackets, is noticeable enough to make it obvious that enclosed in square brackets, is noticeable enough to make it obvious that
you are responsible for last-minute changes. Example : you are responsible for last-minute changes. Example::
Signed-off-by: Random J Developer <random@developer.example.org> Signed-off-by: Random J Developer <random@developer.example.org>
[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
...@@ -481,15 +493,15 @@ which appears in the changelog. ...@@ -481,15 +493,15 @@ which appears in the changelog.
Special note to back-porters: It seems to be a common and useful practice Special note to back-porters: It seems to be a common and useful practice
to insert an indication of the origin of a patch at the top of the commit to insert an indication of the origin of a patch at the top of the commit
message (just after the subject line) to facilitate tracking. For instance, message (just after the subject line) to facilitate tracking. For instance,
here's what we see in a 3.x-stable release: here's what we see in a 3.x-stable release::
Date: Tue Oct 7 07:26:38 2014 -0400 Date: Tue Oct 7 07:26:38 2014 -0400
libata: Un-break ATA blacklist libata: Un-break ATA blacklist
commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
And here's what might appear in an older kernel once a patch is backported: And here's what might appear in an older kernel once a patch is backported::
Date: Tue May 13 22:12:27 2008 +0200 Date: Tue May 13 22:12:27 2008 +0200
...@@ -529,7 +541,7 @@ When in doubt people should refer to the original discussion in the mailing ...@@ -529,7 +541,7 @@ When in doubt people should refer to the original discussion in the mailing
list archives. list archives.
If a person has had the opportunity to comment on a patch, but has not If a person has had the opportunity to comment on a patch, but has not
provided such comments, you may optionally add a "Cc:" tag to the patch. provided such comments, you may optionally add a ``Cc:`` tag to the patch.
This is the only tag which might be added without an explicit action by the This is the only tag which might be added without an explicit action by the
person it names - but it should indicate that this person was copied on the person it names - but it should indicate that this person was copied on the
patch. This tag documents that potentially interested parties patch. This tag documents that potentially interested parties
...@@ -552,11 +564,12 @@ future patches, and ensures credit for the testers. ...@@ -552,11 +564,12 @@ future patches, and ensures credit for the testers.
Reviewed-by:, instead, indicates that the patch has been reviewed and found Reviewed-by:, instead, indicates that the patch has been reviewed and found
acceptable according to the Reviewer's Statement: acceptable according to the Reviewer's Statement:
Reviewer's statement of oversight Reviewer's statement of oversight
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By offering my Reviewed-by: tag, I state that: By offering my Reviewed-by: tag, I state that:
(a) I have carried out a technical review of this patch to (a) I have carried out a technical review of this patch to
evaluate its appropriateness and readiness for inclusion into evaluate its appropriateness and readiness for inclusion into
the mainline kernel. the mainline kernel.
...@@ -594,24 +607,25 @@ A Fixes: tag indicates that the patch fixes an issue in a previous commit. It ...@@ -594,24 +607,25 @@ A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
is used to make it easy to determine where a bug originated, which can help is used to make it easy to determine where a bug originated, which can help
review a bug fix. This tag also assists the stable kernel team in determining review a bug fix. This tag also assists the stable kernel team in determining
which stable kernel versions should receive your fix. This is the preferred which stable kernel versions should receive your fix. This is the preferred
method for indicating a bug fixed by the patch. See #2 above for more details. method for indicating a bug fixed by the patch. See :ref:`describe_changes`
for more details.
14) The canonical patch format 14) The canonical patch format
------------------------------ ------------------------------
This section describes how the patch itself should be formatted. Note This section describes how the patch itself should be formatted. Note
that, if you have your patches stored in a git repository, proper patch that, if you have your patches stored in a ``git`` repository, proper patch
formatting can be had with "git format-patch". The tools cannot create formatting can be had with ``git format-patch``. The tools cannot create
the necessary text, though, so read the instructions below anyway. the necessary text, though, so read the instructions below anyway.
The canonical patch subject line is: The canonical patch subject line is::
Subject: [PATCH 001/123] subsystem: summary phrase Subject: [PATCH 001/123] subsystem: summary phrase
The canonical patch message body contains the following: The canonical patch message body contains the following:
- A "from" line specifying the patch author (only needed if the person - A ``from`` line specifying the patch author (only needed if the person
sending the patch is not the author). sending the patch is not the author).
- An empty line. - An empty line.
...@@ -619,46 +633,46 @@ The canonical patch message body contains the following: ...@@ -619,46 +633,46 @@ The canonical patch message body contains the following:
- The body of the explanation, line wrapped at 75 columns, which will - The body of the explanation, line wrapped at 75 columns, which will
be copied to the permanent changelog to describe this patch. be copied to the permanent changelog to describe this patch.
- The "Signed-off-by:" lines, described above, which will - The ``Signed-off-by:`` lines, described above, which will
also go in the changelog. also go in the changelog.
- A marker line containing simply "---". - A marker line containing simply ``---``.
- Any additional comments not suitable for the changelog. - Any additional comments not suitable for the changelog.
- The actual patch (diff output). - The actual patch (``diff`` output).
The Subject line format makes it very easy to sort the emails The Subject line format makes it very easy to sort the emails
alphabetically by subject line - pretty much any email reader will alphabetically by subject line - pretty much any email reader will
support that - since because the sequence number is zero-padded, support that - since because the sequence number is zero-padded,
the numerical and alphabetic sort is the same. the numerical and alphabetic sort is the same.
The "subsystem" in the email's Subject should identify which The ``subsystem`` in the email's Subject should identify which
area or subsystem of the kernel is being patched. area or subsystem of the kernel is being patched.
The "summary phrase" in the email's Subject should concisely The ``summary phrase`` in the email's Subject should concisely
describe the patch which that email contains. The "summary describe the patch which that email contains. The ``summary
phrase" should not be a filename. Do not use the same "summary phrase`` should not be a filename. Do not use the same ``summary
phrase" for every patch in a whole patch series (where a "patch phrase`` for every patch in a whole patch series (where a ``patch
series" is an ordered sequence of multiple, related patches). series`` is an ordered sequence of multiple, related patches).
Bear in mind that the "summary phrase" of your email becomes a Bear in mind that the ``summary phrase`` of your email becomes a
globally-unique identifier for that patch. It propagates all the way globally-unique identifier for that patch. It propagates all the way
into the git changelog. The "summary phrase" may later be used in into the ``git`` changelog. The ``summary phrase`` may later be used in
developer discussions which refer to the patch. People will want to developer discussions which refer to the patch. People will want to
google for the "summary phrase" to read discussion regarding that google for the ``summary phrase`` to read discussion regarding that
patch. It will also be the only thing that people may quickly see patch. It will also be the only thing that people may quickly see
when, two or three months later, they are going through perhaps when, two or three months later, they are going through perhaps
thousands of patches using tools such as "gitk" or "git log thousands of patches using tools such as ``gitk`` or ``git log
--oneline". --oneline``.
For these reasons, the "summary" must be no more than 70-75 For these reasons, the ``summary`` must be no more than 70-75
characters, and it must describe both what the patch changes, as well characters, and it must describe both what the patch changes, as well
as why the patch might be necessary. It is challenging to be both as why the patch might be necessary. It is challenging to be both
succinct and descriptive, but that is what a well-written summary succinct and descriptive, but that is what a well-written summary
should do. should do.
The "summary phrase" may be prefixed by tags enclosed in square The ``summary phrase`` may be prefixed by tags enclosed in square
brackets: "Subject: [PATCH <tag>...] <summary phrase>". The tags are brackets: "Subject: [PATCH <tag>...] <summary phrase>". The tags are
not considered part of the summary phrase, but describe how the patch not considered part of the summary phrase, but describe how the patch
should be treated. Common tags might include a version descriptor if should be treated. Common tags might include a version descriptor if
...@@ -670,19 +684,19 @@ that developers understand the order in which the patches should be ...@@ -670,19 +684,19 @@ that developers understand the order in which the patches should be
applied and that they have reviewed or applied all of the patches in applied and that they have reviewed or applied all of the patches in
the patch series. the patch series.
A couple of example Subjects: A couple of example Subjects::
Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
Subject: [PATCH v2 01/27] x86: fix eflags tracking Subject: [PATCH v2 01/27] x86: fix eflags tracking
The "from" line must be the very first line in the message body, The ``from`` line must be the very first line in the message body,
and has the form: and has the form:
From: Original Author <author@example.com> From: Original Author <author@example.com>
The "from" line specifies who will be credited as the author of the The ``from`` line specifies who will be credited as the author of the
patch in the permanent changelog. If the "from" line is missing, patch in the permanent changelog. If the ``from`` line is missing,
then the "From:" line from the email header will be used to determine then the ``From:`` line from the email header will be used to determine
the patch author in the changelog. the patch author in the changelog.
The explanation body will be committed to the permanent source The explanation body will be committed to the permanent source
...@@ -694,35 +708,37 @@ especially useful for people who might be searching the commit logs ...@@ -694,35 +708,37 @@ especially useful for people who might be searching the commit logs
looking for the applicable patch. If a patch fixes a compile failure, looking for the applicable patch. If a patch fixes a compile failure,
it may not be necessary to include _all_ of the compile failures; just it may not be necessary to include _all_ of the compile failures; just
enough that it is likely that someone searching for the patch can find enough that it is likely that someone searching for the patch can find
it. As in the "summary phrase", it is important to be both succinct as it. As in the ``summary phrase``, it is important to be both succinct as
well as descriptive. well as descriptive.
The "---" marker line serves the essential purpose of marking for patch The ``---`` marker line serves the essential purpose of marking for patch
handling tools where the changelog message ends. handling tools where the changelog message ends.
One good use for the additional comments after the "---" marker is for One good use for the additional comments after the ``---`` marker is for
a diffstat, to show what files have changed, and the number of a ``diffstat``, to show what files have changed, and the number of
inserted and deleted lines per file. A diffstat is especially useful inserted and deleted lines per file. A ``diffstat`` is especially useful
on bigger patches. Other comments relevant only to the moment or the on bigger patches. Other comments relevant only to the moment or the
maintainer, not suitable for the permanent changelog, should also go maintainer, not suitable for the permanent changelog, should also go
here. A good example of such comments might be "patch changelogs" here. A good example of such comments might be ``patch changelogs``
which describe what has changed between the v1 and v2 version of the which describe what has changed between the v1 and v2 version of the
patch. patch.
If you are going to include a diffstat after the "---" marker, please If you are going to include a ``diffstat`` after the ``---`` marker, please
use diffstat options "-p 1 -w 70" so that filenames are listed from use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from
the top of the kernel source tree and don't use too much horizontal the top of the kernel source tree and don't use too much horizontal
space (easily fit in 80 columns, maybe with some indentation). (git space (easily fit in 80 columns, maybe with some indentation). (``git``
generates appropriate diffstats by default.) generates appropriate diffstats by default.)
See more details on the proper patch format in the following See more details on the proper patch format in the following
references. references.
.. _explicit_in_reply_to:
15) Explicit In-Reply-To headers 15) Explicit In-Reply-To headers
-------------------------------- --------------------------------
It can be helpful to manually add In-Reply-To: headers to a patch It can be helpful to manually add In-Reply-To: headers to a patch
(e.g., when using "git send-email") to associate the patch with (e.g., when using ``git send-email``) to associate the patch with
previous relevant discussion, e.g. to link a bug fix to the email with previous relevant discussion, e.g. to link a bug fix to the email with
the bug report. However, for a multi-patch series, it is generally the bug report. However, for a multi-patch series, it is generally
best to avoid using In-Reply-To: to link to older versions of the best to avoid using In-Reply-To: to link to older versions of the
...@@ -732,12 +748,12 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in ...@@ -732,12 +748,12 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
the cover email text) to link to an earlier version of the patch series. the cover email text) to link to an earlier version of the patch series.
16) Sending "git pull" requests 16) Sending ``git pull`` requests
------------------------------- ---------------------------------
If you have a series of patches, it may be most convenient to have the If you have a series of patches, it may be most convenient to have the
maintainer pull them directly into the subsystem repository with a maintainer pull them directly into the subsystem repository with a
"git pull" operation. Note, however, that pulling patches from a developer ``git pull`` operation. Note, however, that pulling patches from a developer
requires a higher degree of trust than taking patches from a mailing list. requires a higher degree of trust than taking patches from a mailing list.
As a result, many subsystem maintainers are reluctant to take pull As a result, many subsystem maintainers are reluctant to take pull
requests, especially from new, unknown developers. If in doubt you can use requests, especially from new, unknown developers. If in doubt you can use
...@@ -746,7 +762,7 @@ series, giving the maintainer the option of using either. ...@@ -746,7 +762,7 @@ series, giving the maintainer the option of using either.
A pull request should have [GIT] or [PULL] in the subject line. The A pull request should have [GIT] or [PULL] in the subject line. The
request itself should include the repository name and the branch of request itself should include the repository name and the branch of
interest on a single line; it should look something like: interest on a single line; it should look something like::
Please pull from Please pull from
...@@ -755,10 +771,10 @@ interest on a single line; it should look something like: ...@@ -755,10 +771,10 @@ interest on a single line; it should look something like:
to get these changes: to get these changes:
A pull request should also include an overall message saying what will be A pull request should also include an overall message saying what will be
included in the request, a "git shortlog" listing of the patches included in the request, a ``git shortlog`` listing of the patches
themselves, and a diffstat showing the overall effect of the patch series. themselves, and a ``diffstat`` showing the overall effect of the patch series.
The easiest way to get all this information together is, of course, to let The easiest way to get all this information together is, of course, to let
git do it for you with the "git request-pull" command. ``git`` do it for you with the ``git request-pull`` command.
Some maintainers (including Linus) want to see pull requests from signed Some maintainers (including Linus) want to see pull requests from signed
commits; that increases their confidence that the request actually came commits; that increases their confidence that the request actually came
...@@ -770,8 +786,8 @@ signed by one or more core kernel developers. This step can be hard for ...@@ -770,8 +786,8 @@ signed by one or more core kernel developers. This step can be hard for
new developers, but there is no way around it. Attending conferences can new developers, but there is no way around it. Attending conferences can
be a good way to find developers who can sign your key. be a good way to find developers who can sign your key.
Once you have prepared a patch series in git that you wish to have somebody Once you have prepared a patch series in ``git`` that you wish to have somebody
pull, create a signed tag with "git tag -s". This will create a new tag pull, create a signed tag with ``git tag -s``. This will create a new tag
identifying the last commit in the series and containing a signature identifying the last commit in the series and containing a signature
created with your private key. You will also have the opportunity to add a created with your private key. You will also have the opportunity to add a
changelog-style message to the tag; this is an ideal place to describe the changelog-style message to the tag; this is an ideal place to describe the
...@@ -782,14 +798,13 @@ are working from, don't forget to push the signed tag explicitly to the ...@@ -782,14 +798,13 @@ are working from, don't forget to push the signed tag explicitly to the
public tree. public tree.
When generating your pull request, use the signed tag as the target. A When generating your pull request, use the signed tag as the target. A
command like this will do the trick: command like this will do the trick::
git request-pull master git://my.public.tree/linux.git my-signed-tag git request-pull master git://my.public.tree/linux.git my-signed-tag
---------------------- REFERENCES
SECTION 2 - REFERENCES **********
----------------------
Andrew Morton, "The perfect patch" (tpp). Andrew Morton, "The perfect patch" (tpp).
<http://www.ozlabs.org/~akpm/stuff/tpp.txt> <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
...@@ -799,23 +814,28 @@ Jeff Garzik, "Linux kernel patch submission format". ...@@ -799,23 +814,28 @@ Jeff Garzik, "Linux kernel patch submission format".
Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
<http://www.kroah.com/log/linux/maintainer.html> <http://www.kroah.com/log/linux/maintainer.html>
<http://www.kroah.com/log/linux/maintainer-02.html> <http://www.kroah.com/log/linux/maintainer-02.html>
<http://www.kroah.com/log/linux/maintainer-03.html> <http://www.kroah.com/log/linux/maintainer-03.html>
<http://www.kroah.com/log/linux/maintainer-04.html> <http://www.kroah.com/log/linux/maintainer-04.html>
<http://www.kroah.com/log/linux/maintainer-05.html> <http://www.kroah.com/log/linux/maintainer-05.html>
<http://www.kroah.com/log/linux/maintainer-06.html> <http://www.kroah.com/log/linux/maintainer-06.html>
NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
<https://lkml.org/lkml/2005/7/11/336> <https://lkml.org/lkml/2005/7/11/336>
Kernel Documentation/CodingStyle: Kernel Documentation/CodingStyle:
<Documentation/CodingStyle> :ref:`Documentation/CodingStyle <codingstyle>`
Linus Torvalds's mail on the canonical patch format: Linus Torvalds's mail on the canonical patch format:
<http://lkml.org/lkml/2005/4/7/183> <http://lkml.org/lkml/2005/4/7/183>
Andi Kleen, "On submitting kernel patches" Andi Kleen, "On submitting kernel patches"
Some strategies to get difficult or controversial changes in. Some strategies to get difficult or controversial changes in.
http://halobates.de/on-submitting-patches.pdf http://halobates.de/on-submitting-patches.pdf
--
Documentation/applying-patches.txt
View file @ 02bafd96
.. _applying_patches:
Applying Patches To The Linux Kernel Applying Patches To The Linux Kernel
------------------------------------ ++++++++++++++++++++++++++++++++++++
Original by: Jesper Juhl, August 2005 Original by:
Last update: 2006-01-05 Jesper Juhl, August 2005
Last update:
2016-09-14
A frequently asked question on the Linux Kernel Mailing List is how to apply A frequently asked question on the Linux Kernel Mailing List is how to apply
...@@ -17,10 +21,12 @@ their specific patches) is also provided. ...@@ -17,10 +21,12 @@ their specific patches) is also provided.
What is a patch? What is a patch?
--- ================
A patch is a small text document containing a delta of changes between two
different versions of a source tree. Patches are created with the `diff' A patch is a small text document containing a delta of changes between two
different versions of a source tree. Patches are created with the ``diff``
program. program.
To correctly apply a patch you need to know what base it was generated from To correctly apply a patch you need to know what base it was generated from
and what new version the patch will change the source tree into. These and what new version the patch will change the source tree into. These
should both be present in the patch file metadata or be possible to deduce should both be present in the patch file metadata or be possible to deduce
...@@ -28,8 +34,9 @@ from the filename. ...@@ -28,8 +34,9 @@ from the filename.
How do I apply or revert a patch? How do I apply or revert a patch?
--- =================================
You apply a patch with the `patch' program. The patch program reads a diff
You apply a patch with the ``patch`` program. The patch program reads a diff
(or patch) file and makes the changes to the source tree described in it. (or patch) file and makes the changes to the source tree described in it.
Patches for the Linux kernel are generated relative to the parent directory Patches for the Linux kernel are generated relative to the parent directory
...@@ -38,26 +45,33 @@ holding the kernel source dir. ...@@ -38,26 +45,33 @@ holding the kernel source dir.
This means that paths to files inside the patch file contain the name of the This means that paths to files inside the patch file contain the name of the
kernel source directories it was generated against (or some other directory kernel source directories it was generated against (or some other directory
names like "a/" and "b/"). names like "a/" and "b/").
Since this is unlikely to match the name of the kernel source dir on your Since this is unlikely to match the name of the kernel source dir on your
local machine (but is often useful info to see what version an otherwise local machine (but is often useful info to see what version an otherwise
unlabeled patch was generated against) you should change into your kernel unlabeled patch was generated against) you should change into your kernel
source directory and then strip the first element of the path from filenames source directory and then strip the first element of the path from filenames
in the patch file when applying it (the -p1 argument to `patch' does this). in the patch file when applying it (the ``-p1`` argument to ``patch`` does
this).
To revert a previously applied patch, use the -R argument to patch. To revert a previously applied patch, use the -R argument to patch.
So, if you applied a patch like this: So, if you applied a patch like this::
patch -p1 < ../patch-x.y.z patch -p1 < ../patch-x.y.z
You can revert (undo) it like this: You can revert (undo) it like this::
patch -R -p1 < ../patch-x.y.z patch -R -p1 < ../patch-x.y.z
How do I feed a patch/diff file to `patch'? How do I feed a patch/diff file to ``patch``?
--- =============================================
This (as usual with Linux and other UNIX like operating systems) can be
This (as usual with Linux and other UNIX like operating systems) can be
done in several different ways. done in several different ways.
In all the examples below I feed the file (in uncompressed form) to patch In all the examples below I feed the file (in uncompressed form) to patch
via stdin using the following syntax: via stdin using the following syntax::
patch -p1 < path/to/patch-x.y.z patch -p1 < path/to/patch-x.y.z
If you just want to be able to follow the examples below and don't want to If you just want to be able to follow the examples below and don't want to
...@@ -65,35 +79,40 @@ know of more than one way to use patch, then you can stop reading this ...@@ -65,35 +79,40 @@ know of more than one way to use patch, then you can stop reading this
section here. section here.
Patch can also get the name of the file to use via the -i argument, like Patch can also get the name of the file to use via the -i argument, like
this: this::
patch -p1 -i path/to/patch-x.y.z patch -p1 -i path/to/patch-x.y.z
If your patch file is compressed with gzip or bzip2 and you don't want to If your patch file is compressed with gzip or xz and you don't want to
uncompress it before applying it, then you can feed it to patch like this uncompress it before applying it, then you can feed it to patch like this
instead: instead::
zcat path/to/patch-x.y.z.gz | patch -p1
bzcat path/to/patch-x.y.z.bz2 | patch -p1 xzcat path/to/patch-x.y.z.xz | patch -p1
bzcat path/to/patch-x.y.z.gz | patch -p1
If you wish to uncompress the patch file by hand first before applying it If you wish to uncompress the patch file by hand first before applying it
(what I assume you've done in the examples below), then you simply run (what I assume you've done in the examples below), then you simply run
gunzip or bunzip2 on the file -- like this: gunzip or xz on the file -- like this::
gunzip patch-x.y.z.gz gunzip patch-x.y.z.gz
bunzip2 patch-x.y.z.bz2 xz -d patch-x.y.z.xz
Which will leave you with a plain text patch-x.y.z file that you can feed to Which will leave you with a plain text patch-x.y.z file that you can feed to
patch via stdin or the -i argument, as you prefer. patch via stdin or the ``-i`` argument, as you prefer.
A few other nice arguments for patch are -s which causes patch to be silent A few other nice arguments for patch are ``-s`` which causes patch to be silent
except for errors which is nice to prevent errors from scrolling out of the except for errors which is nice to prevent errors from scrolling out of the
screen too fast, and --dry-run which causes patch to just print a listing of screen too fast, and ``--dry-run`` which causes patch to just print a listing of
what would happen, but doesn't actually make any changes. Finally --verbose what would happen, but doesn't actually make any changes. Finally ``--verbose``
tells patch to print more information about the work being done. tells patch to print more information about the work being done.
Common errors when patching Common errors when patching
--- ===========================
When patch applies a patch file it attempts to verify the sanity of the
When patch applies a patch file it attempts to verify the sanity of the
file in different ways. file in different ways.
Checking that the file looks like a valid patch file and checking the code Checking that the file looks like a valid patch file and checking the code
around the bits being modified matches the context provided in the patch are around the bits being modified matches the context provided in the patch are
just two of the basic sanity checks patch does. just two of the basic sanity checks patch does.
...@@ -111,13 +130,13 @@ everything looks good it has just moved up or down a bit, and patch will ...@@ -111,13 +130,13 @@ everything looks good it has just moved up or down a bit, and patch will
usually adjust the line numbers and apply the patch. usually adjust the line numbers and apply the patch.
Whenever patch applies a patch that it had to modify a bit to make it fit Whenever patch applies a patch that it had to modify a bit to make it fit
it'll tell you about it by saying the patch applied with 'fuzz'. it'll tell you about it by saying the patch applied with **fuzz**.
You should be wary of such changes since even though patch probably got it You should be wary of such changes since even though patch probably got it
right it doesn't /always/ get it right, and the result will sometimes be right it doesn't /always/ get it right, and the result will sometimes be
wrong. wrong.
When patch encounters a change that it can't fix up with fuzz it rejects it When patch encounters a change that it can't fix up with fuzz it rejects it
outright and leaves a file with a .rej extension (a reject file). You can outright and leaves a file with a ``.rej`` extension (a reject file). You can
read this file to see exactly what change couldn't be applied, so you can read this file to see exactly what change couldn't be applied, so you can
go fix it up by hand if you wish. go fix it up by hand if you wish.
...@@ -132,43 +151,47 @@ to start with a fresh tree downloaded in full from kernel.org. ...@@ -132,43 +151,47 @@ to start with a fresh tree downloaded in full from kernel.org.
Let's look a bit more at some of the messages patch can produce. Let's look a bit more at some of the messages patch can produce.
If patch stops and presents a "File to patch:" prompt, then patch could not If patch stops and presents a ``File to patch:`` prompt, then patch could not
find a file to be patched. Most likely you forgot to specify -p1 or you are find a file to be patched. Most likely you forgot to specify -p1 or you are
in the wrong directory. Less often, you'll find patches that need to be in the wrong directory. Less often, you'll find patches that need to be
applied with -p0 instead of -p1 (reading the patch file should reveal if applied with ``-p0`` instead of ``-p1`` (reading the patch file should reveal if
this is the case -- if so, then this is an error by the person who created this is the case -- if so, then this is an error by the person who created
the patch but is not fatal). the patch but is not fatal).
If you get "Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines)." or a If you get ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).`` or a
message similar to that, then it means that patch had to adjust the location message similar to that, then it means that patch had to adjust the location
of the change (in this example it needed to move 7 lines from where it of the change (in this example it needed to move 7 lines from where it
expected to make the change to make it fit). expected to make the change to make it fit).
The resulting file may or may not be OK, depending on the reason the file The resulting file may or may not be OK, depending on the reason the file
was different than expected. was different than expected.
This often happens if you try to apply a patch that was generated against a This often happens if you try to apply a patch that was generated against a
different kernel version than the one you are trying to patch. different kernel version than the one you are trying to patch.
If you get a message like "Hunk #3 FAILED at 2387.", then it means that the If you get a message like ``Hunk #3 FAILED at 2387.``, then it means that the
patch could not be applied correctly and the patch program was unable to patch could not be applied correctly and the patch program was unable to
fuzz its way through. This will generate a .rej file with the change that fuzz its way through. This will generate a ``.rej`` file with the change that
caused the patch to fail and also a .orig file showing you the original caused the patch to fail and also a ``.orig`` file showing you the original
content that couldn't be changed. content that couldn't be changed.
If you get "Reversed (or previously applied) patch detected! Assume -R? [n]" If you get ``Reversed (or previously applied) patch detected! Assume -R? [n]``
then patch detected that the change contained in the patch seems to have then patch detected that the change contained in the patch seems to have
already been made. already been made.
If you actually did apply this patch previously and you just re-applied it If you actually did apply this patch previously and you just re-applied it
in error, then just say [n]o and abort this patch. If you applied this patch in error, then just say [n]o and abort this patch. If you applied this patch
previously and actually intended to revert it, but forgot to specify -R, previously and actually intended to revert it, but forgot to specify -R,
then you can say [y]es here to make patch revert it for you. then you can say [**y**]es here to make patch revert it for you.
This can also happen if the creator of the patch reversed the source and This can also happen if the creator of the patch reversed the source and
destination directories when creating the patch, and in that case reverting destination directories when creating the patch, and in that case reverting
the patch will in fact apply it. the patch will in fact apply it.
A message similar to "patch: **** unexpected end of file in patch" or "patch A message similar to ``patch: **** unexpected end of file in patch`` or
unexpectedly ends in middle of line" means that patch could make no sense of ``patch unexpectedly ends in middle of line`` means that patch could make no
the file you fed to it. Either your download is broken, you tried to feed sense of the file you fed to it. Either your download is broken, you tried to
patch a compressed patch file without uncompressing it first, or the patch feed patch a compressed patch file without uncompressing it first, or the patch
file that you are using has been mangled by a mail client or mail transfer file that you are using has been mangled by a mail client or mail transfer
agent along the way somewhere, e.g., by splitting a long line into two lines. agent along the way somewhere, e.g., by splitting a long line into two lines.
Often these warnings can easily be fixed by joining (concatenating) the Often these warnings can easily be fixed by joining (concatenating) the
...@@ -182,28 +205,32 @@ to start over with a fresh download of a full kernel tree and the patch you ...@@ -182,28 +205,32 @@ to start over with a fresh download of a full kernel tree and the patch you
wish to apply. wish to apply.
Are there any alternatives to `patch'? Are there any alternatives to ``patch``?
--- ========================================
Yes there are alternatives.
You can use the `interdiff' program (http://cyberelk.net/tim/patchutils/) to
Yes there are alternatives.
You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to
generate a patch representing the differences between two patches and then generate a patch representing the differences between two patches and then
apply the result. apply the result.
This will let you move from something like 2.6.12.2 to 2.6.12.3 in a single
This will let you move from something like 4.7.2 to 4.7.3 in a single
step. The -z flag to interdiff will even let you feed it patches in gzip or step. The -z flag to interdiff will even let you feed it patches in gzip or
bzip2 compressed form directly without the use of zcat or bzcat or manual bzip2 compressed form directly without the use of zcat or bzcat or manual
decompression. decompression.
Here's how you'd go from 2.6.12.2 to 2.6.12.3 in a single step: Here's how you'd go from 4.7.2 to 4.7.3 in a single step::
interdiff -z ../patch-2.6.12.2.bz2 ../patch-2.6.12.3.gz | patch -p1
interdiff -z ../patch-4.7.2.gz ../patch-4.7.3.gz | patch -p1
Although interdiff may save you a step or two you are generally advised to Although interdiff may save you a step or two you are generally advised to
do the additional steps since interdiff can get things wrong in some cases. do the additional steps since interdiff can get things wrong in some cases.
Another alternative is `ketchup', which is a python script for automatic Another alternative is ``ketchup``, which is a python script for automatic
downloading and applying of patches (http://www.selenic.com/ketchup/). downloading and applying of patches (http://www.selenic.com/ketchup/).
Other nice tools are diffstat, which shows a summary of changes made by a Other nice tools are diffstat, which shows a summary of changes made by a
patch; lsdiff, which displays a short listing of affected files in a patch patch; lsdiff, which displays a short listing of affected files in a patch
file, along with (optionally) the line numbers of the start of each patch; file, along with (optionally) the line numbers of the start of each patch;
and grepdiff, which displays a list of the files modified by a patch where and grepdiff, which displays a list of the files modified by a patch where
...@@ -211,99 +238,103 @@ the patch contains a given regular expression. ...@@ -211,99 +238,103 @@ the patch contains a given regular expression.
Where can I download the patches? Where can I download the patches?
--- =================================
The patches are available at http://kernel.org/
The patches are available at http://kernel.org/
Most recent patches are linked from the front page, but they also have Most recent patches are linked from the front page, but they also have
specific homes. specific homes.
The 2.6.x.y (-stable) and 2.6.x patches live at The 4.x.y (-stable) and 4.x patches live at
ftp://ftp.kernel.org/pub/linux/kernel/v2.6/
The -rc patches live at ftp://ftp.kernel.org/pub/linux/kernel/v4.x/
ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/
The -git patches live at The -rc patches live at
ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/
The -mm kernels live at ftp://ftp.kernel.org/pub/linux/kernel/v4.x/testing/
ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/
In place of ftp.kernel.org you can use ftp.cc.kernel.org, where cc is a In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a
country code. This way you'll be downloading from a mirror site that's most country code. This way you'll be downloading from a mirror site that's most
likely geographically closer to you, resulting in faster downloads for you, likely geographically closer to you, resulting in faster downloads for you,
less bandwidth used globally and less load on the main kernel.org servers -- less bandwidth used globally and less load on the main kernel.org servers --
these are good things, so do use mirrors when possible. these are good things, so do use mirrors when possible.
The 2.6.x kernels The 4.x kernels
--- ===============
These are the base stable releases released by Linus. The highest numbered
These are the base stable releases released by Linus. The highest numbered
release is the most recent. release is the most recent.
If regressions or other serious flaws are found, then a -stable fix patch If regressions or other serious flaws are found, then a -stable fix patch
will be released (see below) on top of this base. Once a new 2.6.x base will be released (see below) on top of this base. Once a new 4.x base
kernel is released, a patch is made available that is a delta between the kernel is released, a patch is made available that is a delta between the
previous 2.6.x kernel and the new one. previous 4.x kernel and the new one.
To apply a patch moving from 4.6 to 4.7, you'd do the following (note
that such patches do **NOT** apply on top of 4.x.y kernels but on top of the
base 4.x kernel -- if you need to move from 4.x.y to 4.x+1 you need to
first revert the 4.x.y patch).
Here are some examples::
To apply a patch moving from 2.6.11 to 2.6.12, you'd do the following (note # moving from 4.6 to 4.7
that such patches do *NOT* apply on top of 2.6.x.y kernels but on top of the
base 2.6.x kernel -- if you need to move from 2.6.x.y to 2.6.x+1 you need to
first revert the 2.6.x.y patch).
Here are some examples: $ cd ~/linux-4.6 # change to kernel source dir
$ patch -p1 < ../patch-4.7 # apply the 4.7 patch
$ cd ..
$ mv linux-4.6 linux-4.7 # rename source dir
# moving from 2.6.11 to 2.6.12 # moving from 4.6.1 to 4.7
$ cd ~/linux-2.6.11 # change to kernel source dir
$ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch
$ cd ..
$ mv linux-2.6.11 linux-2.6.12 # rename source dir
# moving from 2.6.11.1 to 2.6.12 $ cd ~/linux-4.6.1 # change to kernel source dir
$ cd ~/linux-2.6.11.1 # change to kernel source dir $ patch -p1 -R < ../patch-4.6.1 # revert the 4.6.1 patch
$ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch # source dir is now 4.6
# source dir is now 2.6.11 $ patch -p1 < ../patch-4.7 # apply new 4.7 patch
$ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch $ cd ..
$ cd .. $ mv linux-4.6.1 linux-4.7 # rename source dir
$ mv linux-2.6.11.1 linux-2.6.12 # rename source dir
The 2.6.x.y kernels The 4.x.y kernels
--- =================
Kernels with 4-digit versions are -stable kernels. They contain small(ish)
Kernels with 3-digit versions are -stable kernels. They contain small(ish)
critical fixes for security problems or significant regressions discovered critical fixes for security problems or significant regressions discovered
in a given 2.6.x kernel. in a given 4.x kernel.
This is the recommended branch for users who want the most recent stable This is the recommended branch for users who want the most recent stable
kernel and are not interested in helping test development/experimental kernel and are not interested in helping test development/experimental
versions. versions.
If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is If no 4.x.y kernel is available, then the highest numbered 4.x kernel is
the current stable kernel. the current stable kernel.
note: the -stable team usually do make incremental patches available as well .. note::
The -stable team usually do make incremental patches available as well
as patches against the latest mainline release, but I only cover the as patches against the latest mainline release, but I only cover the
non-incremental ones below. The incremental ones can be found at non-incremental ones below. The incremental ones can be found at
ftp://ftp.kernel.org/pub/linux/kernel/v2.6/incr/ ftp://ftp.kernel.org/pub/linux/kernel/v4.x/incr/
These patches are not incremental, meaning that for example the 2.6.12.3 These patches are not incremental, meaning that for example the 4.7.3
patch does not apply on top of the 2.6.12.2 kernel source, but rather on top patch does not apply on top of the 4.7.2 kernel source, but rather on top
of the base 2.6.12 kernel source . of the base 4.7 kernel source.
So, in order to apply the 2.6.12.3 patch to your existing 2.6.12.2 kernel
source you have to first back out the 2.6.12.2 patch (so you are left with a
base 2.6.12 kernel source) and then apply the new 2.6.12.3 patch.
Here's a small example: So, in order to apply the 4.7.3 patch to your existing 4.7.2 kernel
source you have to first back out the 4.7.2 patch (so you are left with a
base 4.7 kernel source) and then apply the new 4.7.3 patch.
$ cd ~/linux-2.6.12.2 # change into the kernel source dir Here's a small example::
$ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch
$ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch
$ cd ..
$ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir
$ cd ~/linux-4.7.2 # change to the kernel source dir
$ patch -p1 -R < ../patch-4.7.2 # revert the 4.7.2 patch
$ patch -p1 < ../patch-4.7.3 # apply the new 4.7.3 patch
$ cd ..
$ mv linux-4.7.2 linux-4.7.3 # rename the kernel source dir
The -rc kernels The -rc kernels
--- ===============
These are release-candidate kernels. These are development kernels released
These are release-candidate kernels. These are development kernels released
by Linus whenever he deems the current git (the kernel's source management by Linus whenever he deems the current git (the kernel's source management
tool) tree to be in a reasonably sane state adequate for testing. tool) tree to be in a reasonably sane state adequate for testing.
...@@ -317,39 +348,44 @@ This is a good branch to run for people who want to help out testing ...@@ -317,39 +348,44 @@ This is a good branch to run for people who want to help out testing
development kernels but do not want to run some of the really experimental development kernels but do not want to run some of the really experimental
stuff (such people should see the sections about -git and -mm kernels below). stuff (such people should see the sections about -git and -mm kernels below).
The -rc patches are not incremental, they apply to a base 2.6.x kernel, just The -rc patches are not incremental, they apply to a base 4.x kernel, just
like the 2.6.x.y patches described above. The kernel version before the -rcN like the 4.x.y patches described above. The kernel version before the -rcN
suffix denotes the version of the kernel that this -rc kernel will eventually suffix denotes the version of the kernel that this -rc kernel will eventually
turn into. turn into.
So, 2.6.13-rc5 means that this is the fifth release candidate for the 2.6.13
kernel and the patch should be applied on top of the 2.6.12 kernel source.
Here are 3 examples of how to apply these patches: So, 4.8-rc5 means that this is the fifth release candidate for the 4.8
kernel and the patch should be applied on top of the 4.7 kernel source.
# first an example of moving from 2.6.12 to 2.6.13-rc3 Here are 3 examples of how to apply these patches::
$ cd ~/linux-2.6.12 # change into the 2.6.12 source dir
$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch
$ cd ..
$ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir
# now let's move from 2.6.13-rc3 to 2.6.13-rc5 # first an example of moving from 4.7 to 4.8-rc3
$ cd ~/linux-2.6.13-rc3 # change into the 2.6.13-rc3 dir
$ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch
$ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch
$ cd ..
$ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir
# finally let's try and move from 2.6.12.3 to 2.6.13-rc5 $ cd ~/linux-4.7 # change to the 4.7 source dir
$ cd ~/linux-2.6.12.3 # change to the kernel source dir $ patch -p1 < ../patch-4.8-rc3 # apply the 4.8-rc3 patch
$ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch $ cd ..
$ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch $ mv linux-4.7 linux-4.8-rc3 # rename the source dir
$ cd ..
$ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir # now let's move from 4.8-rc3 to 4.8-rc5
$ cd ~/linux-4.8-rc3 # change to the 4.8-rc3 dir
$ patch -p1 -R < ../patch-4.8-rc3 # revert the 4.8-rc3 patch
$ patch -p1 < ../patch-4.8-rc5 # apply the new 4.8-rc5 patch
$ cd ..
$ mv linux-4.8-rc3 linux-4.8-rc5 # rename the source dir
# finally let's try and move from 4.7.3 to 4.8-rc5
$ cd ~/linux-4.7.3 # change to the kernel source dir
$ patch -p1 -R < ../patch-4.7.3 # revert the 4.7.3 patch
$ patch -p1 < ../patch-4.8-rc5 # apply new 4.8-rc5 patch
$ cd ..
$ mv linux-4.7.3 linux-4.8-rc5 # rename the kernel source dir
The -git kernels The -git kernels
--- ================
These are daily snapshots of Linus' kernel tree (managed in a git
These are daily snapshots of Linus' kernel tree (managed in a git
repository, hence the name). repository, hence the name).
These patches are usually released daily and represent the current state of These patches are usually released daily and represent the current state of
...@@ -357,91 +393,66 @@ Linus's tree. They are more experimental than -rc kernels since they are ...@@ -357,91 +393,66 @@ Linus's tree. They are more experimental than -rc kernels since they are
generated automatically without even a cursory glance to see if they are generated automatically without even a cursory glance to see if they are
sane. sane.
-git patches are not incremental and apply either to a base 2.6.x kernel or -git patches are not incremental and apply either to a base 4.x kernel or
a base 2.6.x-rc kernel -- you can see which from their name. a base 4.x-rc kernel -- you can see which from their name.
A patch named 2.6.12-git1 applies to the 2.6.12 kernel source and a patch A patch named 4.7-git1 applies to the 4.7 kernel source and a patch
named 2.6.13-rc3-git2 applies to the source of the 2.6.13-rc3 kernel. named 4.8-rc3-git2 applies to the source of the 4.8-rc3 kernel.
Here are some examples of how to apply these patches: Here are some examples of how to apply these patches::
# moving from 2.6.12 to 2.6.12-git1 # moving from 4.7 to 4.7-git1
$ cd ~/linux-2.6.12 # change to the kernel source dir
$ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch $ cd ~/linux-4.7 # change to the kernel source dir
$ cd .. $ patch -p1 < ../patch-4.7-git1 # apply the 4.7-git1 patch
$ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir $ cd ..
$ mv linux-4.7 linux-4.7-git1 # rename the kernel source dir
# moving from 2.6.12-git1 to 2.6.13-rc2-git3
$ cd ~/linux-2.6.12-git1 # change to the kernel source dir # moving from 4.7-git1 to 4.8-rc2-git3
$ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch
# we now have a 2.6.12 kernel $ cd ~/linux-4.7-git1 # change to the kernel source dir
$ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch $ patch -p1 -R < ../patch-4.7-git1 # revert the 4.7-git1 patch
# the kernel is now 2.6.13-rc2 # we now have a 4.7 kernel
$ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch $ patch -p1 < ../patch-4.8-rc2 # apply the 4.8-rc2 patch
# the kernel is now 2.6.13-rc2-git3 # the kernel is now 4.8-rc2
$ cd .. $ patch -p1 < ../patch-4.8-rc2-git3 # apply the 4.8-rc2-git3 patch
$ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir # the kernel is now 4.8-rc2-git3
$ cd ..
$ mv linux-4.7-git1 linux-4.8-rc2-git3 # rename source dir
The -mm kernels
---
These are experimental kernels released by Andrew Morton. The -mm patches and the linux-next tree
=======================================
The -mm tree serves as a sort of proving ground for new features and other
experimental patches. The -mm patches are experimental patches released by Andrew Morton.
Once a patch has proved its worth in -mm for a while Andrew pushes it on to
Linus for inclusion in mainline. In the past, -mm tree were used to also test subsystem patches, but this
function is now done via the
Although it's encouraged that patches flow to Linus via the -mm tree, this :ref:`linux-next <https://www.kernel.org/doc/man-pages/linux-next.html>`
is not always enforced. tree. The Subsystem maintainers push their patches first to linux-next,
Subsystem maintainers (or individuals) sometimes push their patches directly and, during the merge window, sends them directly to Linus.
to Linus, even though (or after) they have been merged and tested in -mm (or
sometimes even without prior testing in -mm). The -mm patches serve as a sort of proving ground for new features and other
experimental patches that aren't merged via a subsystem tree.
You should generally strive to get your patches into mainline via -mm to Once such patches has proved its worth in -mm for a while Andrew pushes
ensure maximum testing. it on to Linus for inclusion in mainline.
This branch is in constant flux and contains many experimental features, a The linux-next tree is daily updated, and includes the -mm patches.
Both are in constant flux and contains many experimental features, a
lot of debugging patches not appropriate for mainline etc., and is the most lot of debugging patches not appropriate for mainline etc., and is the most
experimental of the branches described in this document. experimental of the branches described in this document.
These kernels are not appropriate for use on systems that are supposed to be These patches are not appropriate for use on systems that are supposed to be
stable and they are more risky to run than any of the other branches (make stable and they are more risky to run than any of the other branches (make
sure you have up-to-date backups -- that goes for any experimental kernel but sure you have up-to-date backups -- that goes for any experimental kernel but
even more so for -mm kernels). even more so for -mm patches or using a Kernel from the linux-next tree).
These kernels in addition to all the other experimental patches they contain Testing of -mm patches and linux-next is greatly appreciated since the whole
usually also contain any changes in the mainline -git kernels available at point of those are to weed out regressions, crashes, data corruption bugs,
the time of release. build breakage (and any other bug in general) before changes are merged into
the more stable mainline Linus tree.
Testing of -mm kernels is greatly appreciated since the whole point of the
tree is to weed out regressions, crashes, data corruption bugs, build But testers of -mm and linux-next should be aware that breakages are
breakage (and any other bug in general) before changes are merged into the more common than in any other tree.
more stable mainline Linus tree.
But testers of -mm should be aware that breakage in this tree is more common
than in any other tree.
The -mm kernels are not released on a fixed schedule, but usually a few -mm
kernels are released in between each -rc kernel (1 to 3 is common).
The -mm kernels apply to either a base 2.6.x kernel (when no -rc kernels
have been released yet) or to a Linus -rc kernel.
Here are some examples of applying the -mm patches:
# moving from 2.6.12 to 2.6.12-mm1
$ cd ~/linux-2.6.12 # change to the 2.6.12 source dir
$ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch
$ cd ..
$ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately
# moving from 2.6.12-mm1 to 2.6.13-rc3-mm3
$ cd ~/linux-2.6.12-mm1
$ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch
# we now have a 2.6.12 source
$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch
# we now have a 2.6.13-rc3 source
$ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch
$ cd ..
$ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir
This concludes this list of explanations of the various kernel trees. This concludes this list of explanations of the various kernel trees.
......
Documentation/arm/sunxi/README
View file @ 02bafd96
...@@ -73,4 +73,13 @@ SunXi family ...@@ -73,4 +73,13 @@ SunXi family
* Octa ARM Cortex-A7 based SoCs * Octa ARM Cortex-A7 based SoCs
- Allwinner A83T - Allwinner A83T
+ Datasheet + Datasheet
http://dl.linux-sunxi.org/A83T/A83T_datasheet_Revision_1.1.pdf https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_Datasheet_v1.3_20150510.pdf
+ User Manual
https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_User_Manual_v1.5.1_20150513.pdf
* Quad ARM Cortex-A53 based SoCs
- Allwinner A64
+ Datasheet
http://dl.linux-sunxi.org/A64/A64_Datasheet_V1.1.pdf
+ User Manual
http://dl.linux-sunxi.org/A64/Allwinner%20A64%20User%20Manual%20v1.0.pdf
Documentation/clk.txt
View file @ 02bafd96
...@@ -31,24 +31,25 @@ serve as a convenient shorthand for the implementation of the ...@@ -31,24 +31,25 @@ serve as a convenient shorthand for the implementation of the
hardware-specific bits for the hypothetical "foo" hardware. hardware-specific bits for the hypothetical "foo" hardware.
Tying the two halves of this interface together is struct clk_hw, which Tying the two halves of this interface together is struct clk_hw, which
is defined in struct clk_foo and pointed to within struct clk. This is defined in struct clk_foo and pointed to within struct clk_core. This
allows for easy navigation between the two discrete halves of the common allows for easy navigation between the two discrete halves of the common
clock interface. clock interface.
Part 2 - common data structures and api Part 2 - common data structures and api
Below is the common struct clk definition from Below is the common struct clk_core definition from
include/linux/clk-private.h, modified for brevity: drivers/clk/clk.c, modified for brevity:
struct clk { struct clk_core {
const char *name; const char *name;
const struct clk_ops *ops; const struct clk_ops *ops;
struct clk_hw *hw; struct clk_hw *hw;
char **parent_names; struct module *owner;
struct clk **parents; struct clk_core *parent;
struct clk *parent; const char **parent_names;
struct hlist_head children; struct clk_core **parents;
struct hlist_node child_node; u8 num_parents;
u8 new_parent_index;
... ...
}; };
...@@ -56,16 +57,19 @@ The members above make up the core of the clk tree topology. The clk ...@@ -56,16 +57,19 @@ The members above make up the core of the clk tree topology. The clk
api itself defines several driver-facing functions which operate on api itself defines several driver-facing functions which operate on
struct clk. That api is documented in include/linux/clk.h. struct clk. That api is documented in include/linux/clk.h.
Platforms and devices utilizing the common struct clk use the struct Platforms and devices utilizing the common struct clk_core use the struct
clk_ops pointer in struct clk to perform the hardware-specific parts of clk_ops pointer in struct clk_core to perform the hardware-specific parts of
the operations defined in clk.h: the operations defined in clk-provider.h:
struct clk_ops { struct clk_ops {
int (*prepare)(struct clk_hw *hw); int (*prepare)(struct clk_hw *hw);
void (*unprepare)(struct clk_hw *hw); void (*unprepare)(struct clk_hw *hw);
int (*is_prepared)(struct clk_hw *hw);
void (*unprepare_unused)(struct clk_hw *hw);
int (*enable)(struct clk_hw *hw); int (*enable)(struct clk_hw *hw);
void (*disable)(struct clk_hw *hw); void (*disable)(struct clk_hw *hw);
int (*is_enabled)(struct clk_hw *hw); int (*is_enabled)(struct clk_hw *hw);
void (*disable_unused)(struct clk_hw *hw);
unsigned long (*recalc_rate)(struct clk_hw *hw, unsigned long (*recalc_rate)(struct clk_hw *hw,
unsigned long parent_rate); unsigned long parent_rate);
long (*round_rate)(struct clk_hw *hw, long (*round_rate)(struct clk_hw *hw,
...@@ -84,6 +88,8 @@ the operations defined in clk.h: ...@@ -84,6 +88,8 @@ the operations defined in clk.h:
u8 index); u8 index);
unsigned long (*recalc_accuracy)(struct clk_hw *hw, unsigned long (*recalc_accuracy)(struct clk_hw *hw,
unsigned long parent_accuracy); unsigned long parent_accuracy);
int (*get_phase)(struct clk_hw *hw);
int (*set_phase)(struct clk_hw *hw, int degrees);
void (*init)(struct clk_hw *hw); void (*init)(struct clk_hw *hw);
int (*debug_init)(struct clk_hw *hw, int (*debug_init)(struct clk_hw *hw,
struct dentry *dentry); struct dentry *dentry);
...@@ -91,7 +97,7 @@ the operations defined in clk.h: ...@@ -91,7 +97,7 @@ the operations defined in clk.h:
Part 3 - hardware clk implementations Part 3 - hardware clk implementations
The strength of the common struct clk comes from its .ops and .hw pointers The strength of the common struct clk_core comes from its .ops and .hw pointers
which abstract the details of struct clk from the hardware-specific bits, and which abstract the details of struct clk from the hardware-specific bits, and
vice versa. To illustrate consider the simple gateable clk implementation in vice versa. To illustrate consider the simple gateable clk implementation in
drivers/clk/clk-gate.c: drivers/clk/clk-gate.c:
...@@ -107,7 +113,7 @@ struct clk_gate contains struct clk_hw hw as well as hardware-specific ...@@ -107,7 +113,7 @@ struct clk_gate contains struct clk_hw hw as well as hardware-specific
knowledge about which register and bit controls this clk's gating. knowledge about which register and bit controls this clk's gating.
Nothing about clock topology or accounting, such as enable_count or Nothing about clock topology or accounting, such as enable_count or
notifier_count, is needed here. That is all handled by the common notifier_count, is needed here. That is all handled by the common
framework code and struct clk. framework code and struct clk_core.
Let's walk through enabling this clk from driver code: Let's walk through enabling this clk from driver code:
...@@ -139,22 +145,18 @@ static void clk_gate_set_bit(struct clk_gate *gate) ...@@ -139,22 +145,18 @@ static void clk_gate_set_bit(struct clk_gate *gate)
Note that to_clk_gate is defined as: Note that to_clk_gate is defined as:
#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, clk) #define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw)
This pattern of abstraction is used for every clock hardware This pattern of abstraction is used for every clock hardware
representation. representation.
Part 4 - supporting your own clk hardware Part 4 - supporting your own clk hardware
When implementing support for a new type of clock it only necessary to When implementing support for a new type of clock it is only necessary to
include the following header: include the following header:
#include <linux/clk-provider.h> #include <linux/clk-provider.h>
include/linux/clk.h is included within that header and clk-private.h
must never be included from the code which implements the operations for
a clock. More on that below in Part 5.
To construct a clk hardware structure for your platform you must define To construct a clk hardware structure for your platform you must define
the following: the following:
......
Documentation/conf.py
View file @ 02bafd96
...@@ -14,11 +14,17 @@ ...@@ -14,11 +14,17 @@
import sys import sys
import os import os
import sphinx
# Get Sphinx version
major, minor, patch = map(int, sphinx.__version__.split("."))
# If extensions (or modules to document with autodoc) are in another directory, # If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the # add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here. # documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('sphinx')) sys.path.insert(0, os.path.abspath('sphinx'))
from load_config import loadConfig
# -- General configuration ------------------------------------------------ # -- General configuration ------------------------------------------------
...@@ -28,14 +34,13 @@ sys.path.insert(0, os.path.abspath('sphinx')) ...@@ -28,14 +34,13 @@ sys.path.insert(0, os.path.abspath('sphinx'))
# Add any Sphinx extension module names here, as strings. They can be # Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones. # ones.
extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include'] extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain']
# Gracefully handle missing rst2pdf. # The name of the math extension changed on Sphinx 1.4
try: if minor > 3:
import rst2pdf extensions.append("sphinx.ext.imgmath")
extensions += ['rst2pdf.pdfbuilder'] else:
except ImportError: extensions.append("sphinx.ext.pngmath")
pass
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
...@@ -252,23 +257,90 @@ htmlhelp_basename = 'TheLinuxKerneldoc' ...@@ -252,23 +257,90 @@ htmlhelp_basename = 'TheLinuxKerneldoc'
latex_elements = { latex_elements = {
# The paper size ('letterpaper' or 'a4paper'). # The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper', 'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt'). # The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt', 'pointsize': '8pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Latex figure (float) alignment # Latex figure (float) alignment
#'figure_align': 'htbp', #'figure_align': 'htbp',
# Don't mangle with UTF-8 chars
'inputenc': '',
'utf8extra': '',
# Additional stuff for the LaTeX preamble.
'preamble': '''
% Adjust margins
\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}
% Allow generate some pages in landscape
\\usepackage{lscape}
% Put notes in color and let them be inside a table
\\definecolor{NoteColor}{RGB}{204,255,255}
\\definecolor{WarningColor}{RGB}{255,204,204}
\\definecolor{AttentionColor}{RGB}{255,255,204}
\\definecolor{OtherColor}{RGB}{204,204,204}
\\newlength{\\mynoticelength}
\\makeatletter\\newenvironment{coloredbox}[1]{%
\\setlength{\\fboxrule}{1pt}
\\setlength{\\fboxsep}{7pt}
\\setlength{\\mynoticelength}{\\linewidth}
\\addtolength{\\mynoticelength}{-2\\fboxsep}
\\addtolength{\\mynoticelength}{-2\\fboxrule}
\\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\mynoticelength}}{\\end{minipage}\\end{lrbox}%
\\ifthenelse%
{\\equal{\\py@noticetype}{note}}%
{\\colorbox{NoteColor}{\\usebox{\\@tempboxa}}}%
{%
\\ifthenelse%
{\\equal{\\py@noticetype}{warning}}%
{\\colorbox{WarningColor}{\\usebox{\\@tempboxa}}}%
{%
\\ifthenelse%
{\\equal{\\py@noticetype}{attention}}%
{\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
{\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
}%
}%
}\\makeatother
\\makeatletter
\\renewenvironment{notice}[2]{%
\\def\\py@noticetype{#1}
\\begin{coloredbox}{#1}
\\bf\\it
\\par\\strong{#2}
\\csname py@noticestart@#1\\endcsname
}
{
\\csname py@noticeend@\\py@noticetype\\endcsname
\\end{coloredbox}
}
\\makeatother
% Use some font with UTF-8 support with XeLaTeX
\\usepackage{fontspec}
\\setsansfont{DejaVu Serif}
\\setromanfont{DejaVu Sans}
\\setmonofont{DejaVu Sans Mono}
% To allow adjusting table sizes
\\usepackage{adjustbox}
'''
} }
# Grouping the document tree into LaTeX files. List of tuples # Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, # (source start file, target name, title,
# author, documentclass [howto, manual, or own class]). # author, documentclass [howto, manual, or own class]).
latex_documents = [ latex_documents = [
(master_doc, 'TheLinuxKernel.tex', 'The Linux Kernel Documentation', ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
'The kernel development community', 'manual'),
('development-process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
'The kernel development community', 'manual'),
('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
'The kernel development community', 'manual'), 'The kernel development community', 'manual'),
] ]
...@@ -419,3 +491,9 @@ pdf_documents = [ ...@@ -419,3 +491,9 @@ pdf_documents = [
# line arguments. # line arguments.
kerneldoc_bin = '../scripts/kernel-doc' kerneldoc_bin = '../scripts/kernel-doc'
kerneldoc_srctree = '..' kerneldoc_srctree = '..'
# ------------------------------------------------------------------------------
# Since loadConfig overwrites settings from the global namespace, it has to be
# the last statement in the conf.py file
# ------------------------------------------------------------------------------
loadConfig(globals())
Documentation/coccinelle.txt → Documentation/dev-tools/coccinelle.rst
View file @ 02bafd96
Copyright 2010 Nicolas Palix <npalix@diku.dk> .. Copyright 2010 Nicolas Palix <npalix@diku.dk>
Copyright 2010 Julia Lawall <julia@diku.dk> .. Copyright 2010 Julia Lawall <julia@diku.dk>
Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr> .. Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr>
.. highlight:: none
Getting Coccinelle Coccinelle
~~~~~~~~~~~~~~~~~~~~ ==========
Coccinelle is a tool for pattern matching and text transformation that has
many uses in kernel development, including the application of complex,
tree-wide patches and detection of problematic programming patterns.
Getting Coccinelle
-------------------
The semantic patches included in the kernel use features and options The semantic patches included in the kernel use features and options
which are provided by Coccinelle version 1.0.0-rc11 and above. which are provided by Coccinelle version 1.0.0-rc11 and above.
...@@ -22,24 +30,23 @@ of many distributions, e.g. : ...@@ -22,24 +30,23 @@ of many distributions, e.g. :
- NetBSD - NetBSD
- FreeBSD - FreeBSD
You can get the latest version released from the Coccinelle homepage at You can get the latest version released from the Coccinelle homepage at
http://coccinelle.lip6.fr/ http://coccinelle.lip6.fr/
Information and tips about Coccinelle are also provided on the wiki Information and tips about Coccinelle are also provided on the wiki
pages at http://cocci.ekstranet.diku.dk/wiki/doku.php pages at http://cocci.ekstranet.diku.dk/wiki/doku.php
Once you have it, run the following command: Once you have it, run the following command::
./configure ./configure
make make
as a regular user, and install it with as a regular user, and install it with::
sudo make install sudo make install
Supplemental documentation Supplemental documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
For supplemental documentation refer to the wiki: For supplemental documentation refer to the wiki:
...@@ -47,49 +54,52 @@ https://bottest.wiki.kernel.org/coccicheck ...@@ -47,49 +54,52 @@ https://bottest.wiki.kernel.org/coccicheck
The wiki documentation always refers to the linux-next version of the script. The wiki documentation always refers to the linux-next version of the script.
Using Coccinelle on the Linux kernel Using Coccinelle on the Linux kernel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------
A Coccinelle-specific target is defined in the top level A Coccinelle-specific target is defined in the top level
Makefile. This target is named 'coccicheck' and calls the 'coccicheck' Makefile. This target is named ``coccicheck`` and calls the ``coccicheck``
front-end in the 'scripts' directory. front-end in the ``scripts`` directory.
Four basic modes are defined: patch, report, context, and org. The mode to Four basic modes are defined: ``patch``, ``report``, ``context``, and
use is specified by setting the MODE variable with 'MODE=<mode>'. ``org``. The mode to use is specified by setting the MODE variable with
``MODE=<mode>``.
'patch' proposes a fix, when possible. - ``patch`` proposes a fix, when possible.
'report' generates a list in the following format: - ``report`` generates a list in the following format:
file:line:column-column: message file:line:column-column: message
'context' highlights lines of interest and their context in a - ``context`` highlights lines of interest and their context in a
diff-like style.Lines of interest are indicated with '-'. diff-like style.Lines of interest are indicated with ``-``.
'org' generates a report in the Org mode format of Emacs. - ``org`` generates a report in the Org mode format of Emacs.
Note that not all semantic patches implement all modes. For easy use Note that not all semantic patches implement all modes. For easy use
of Coccinelle, the default mode is "report". of Coccinelle, the default mode is "report".
Two other modes provide some common combinations of these modes. Two other modes provide some common combinations of these modes.
'chain' tries the previous modes in the order above until one succeeds. - ``chain`` tries the previous modes in the order above until one succeeds.
- ``rep+ctxt`` runs successively the report mode and the context mode.
It should be used with the C option (described later)
which checks the code on a file basis.
'rep+ctxt' runs successively the report mode and the context mode. Examples
It should be used with the C option (described later) ~~~~~~~~
which checks the code on a file basis.
Examples: To make a report for every semantic patch, run the following command::
To make a report for every semantic patch, run the following command:
make coccicheck MODE=report make coccicheck MODE=report
To produce patches, run: To produce patches, run::
make coccicheck MODE=patch make coccicheck MODE=patch
The coccicheck target applies every semantic patch available in the The coccicheck target applies every semantic patch available in the
sub-directories of 'scripts/coccinelle' to the entire Linux kernel. sub-directories of ``scripts/coccinelle`` to the entire Linux kernel.
For each semantic patch, a commit message is proposed. It gives a For each semantic patch, a commit message is proposed. It gives a
description of the problem being checked by the semantic patch, and description of the problem being checked by the semantic patch, and
...@@ -99,15 +109,15 @@ As any static code analyzer, Coccinelle produces false ...@@ -99,15 +109,15 @@ As any static code analyzer, Coccinelle produces false
positives. Thus, reports must be carefully checked, and patches positives. Thus, reports must be carefully checked, and patches
reviewed. reviewed.
To enable verbose messages set the V= variable, for example: To enable verbose messages set the V= variable, for example::
make coccicheck MODE=report V=1 make coccicheck MODE=report V=1
Coccinelle parallelization Coccinelle parallelization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
By default, coccicheck tries to run as parallel as possible. To change By default, coccicheck tries to run as parallel as possible. To change
the parallelism, set the J= variable. For example, to run across 4 CPUs: the parallelism, set the J= variable. For example, to run across 4 CPUs::
make coccicheck MODE=report J=4 make coccicheck MODE=report J=4
...@@ -115,44 +125,47 @@ As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, ...@@ -115,44 +125,47 @@ As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization,
if support for this is detected you will benefit from parmap parallelization. if support for this is detected you will benefit from parmap parallelization.
When parmap is enabled coccicheck will enable dynamic load balancing by using When parmap is enabled coccicheck will enable dynamic load balancing by using
'--chunksize 1' argument, this ensures we keep feeding threads with work ``--chunksize 1`` argument, this ensures we keep feeding threads with work
one by one, so that we avoid the situation where most work gets done by only one by one, so that we avoid the situation where most work gets done by only
a few threads. With dynamic load balancing, if a thread finishes early we keep a few threads. With dynamic load balancing, if a thread finishes early we keep
feeding it more work. feeding it more work.
When parmap is enabled, if an error occurs in Coccinelle, this error When parmap is enabled, if an error occurs in Coccinelle, this error
value is propagated back, the return value of the 'make coccicheck' value is propagated back, the return value of the ``make coccicheck``
captures this return value. captures this return value.
Using Coccinelle with a single semantic patch Using Coccinelle with a single semantic patch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------------
The optional make variable COCCI can be used to check a single The optional make variable COCCI can be used to check a single
semantic patch. In that case, the variable must be initialized with semantic patch. In that case, the variable must be initialized with
the name of the semantic patch to apply. the name of the semantic patch to apply.
For instance: For instance::
make coccicheck COCCI=<my_SP.cocci> MODE=patch make coccicheck COCCI=<my_SP.cocci> MODE=patch
or
or::
make coccicheck COCCI=<my_SP.cocci> MODE=report make coccicheck COCCI=<my_SP.cocci> MODE=report
Controlling Which Files are Processed by Coccinelle Controlling Which Files are Processed by Coccinelle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------------------
By default the entire kernel source tree is checked. By default the entire kernel source tree is checked.
To apply Coccinelle to a specific directory, M= can be used. To apply Coccinelle to a specific directory, ``M=`` can be used.
For example, to check drivers/net/wireless/ one may write: For example, to check drivers/net/wireless/ one may write::
make coccicheck M=drivers/net/wireless/ make coccicheck M=drivers/net/wireless/
To apply Coccinelle on a file basis, instead of a directory basis, the To apply Coccinelle on a file basis, instead of a directory basis, the
following command may be used: following command may be used::
make C=1 CHECK="scripts/coccicheck" make C=1 CHECK="scripts/coccicheck"
To check only newly edited code, use the value 2 for the C flag, i.e. To check only newly edited code, use the value 2 for the C flag, i.e.::
make C=2 CHECK="scripts/coccicheck" make C=2 CHECK="scripts/coccicheck"
...@@ -166,8 +179,8 @@ semantic patch as shown in the previous section. ...@@ -166,8 +179,8 @@ semantic patch as shown in the previous section.
The "report" mode is the default. You can select another one with the The "report" mode is the default. You can select another one with the
MODE variable explained above. MODE variable explained above.
Debugging Coccinelle SmPL patches Debugging Coccinelle SmPL patches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------
Using coccicheck is best as it provides in the spatch command line Using coccicheck is best as it provides in the spatch command line
include options matching the options used when we compile the kernel. include options matching the options used when we compile the kernel.
...@@ -177,8 +190,8 @@ manually run Coccinelle with debug options added. ...@@ -177,8 +190,8 @@ manually run Coccinelle with debug options added.
Alternatively you can debug running Coccinelle against SmPL patches Alternatively you can debug running Coccinelle against SmPL patches
by asking for stderr to be redirected to stderr, by default stderr by asking for stderr to be redirected to stderr, by default stderr
is redirected to /dev/null, if you'd like to capture stderr you is redirected to /dev/null, if you'd like to capture stderr you
can specify the DEBUG_FILE="file.txt" option to coccicheck. For can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
instance: instance::
rm -f cocci.err rm -f cocci.err
make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err
...@@ -186,7 +199,7 @@ instance: ...@@ -186,7 +199,7 @@ instance:
You can use SPFLAGS to add debugging flags, for instance you may want to You can use SPFLAGS to add debugging flags, for instance you may want to
add both --profile --show-trying to SPFLAGS when debugging. For instance add both --profile --show-trying to SPFLAGS when debugging. For instance
you may want to use: you may want to use::
rm -f err.log rm -f err.log
export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci
...@@ -198,24 +211,24 @@ work. ...@@ -198,24 +211,24 @@ work.
DEBUG_FILE support is only supported when using coccinelle >= 1.2. DEBUG_FILE support is only supported when using coccinelle >= 1.2.
.cocciconfig support .cocciconfig support
~~~~~~~~~~~~~~~~~~~~~~ --------------------
Coccinelle supports reading .cocciconfig for default Coccinelle options that Coccinelle supports reading .cocciconfig for default Coccinelle options that
should be used every time spatch is spawned, the order of precedence for should be used every time spatch is spawned, the order of precedence for
variables for .cocciconfig is as follows: variables for .cocciconfig is as follows:
o Your current user's home directory is processed first - Your current user's home directory is processed first
o Your directory from which spatch is called is processed next - Your directory from which spatch is called is processed next
o The directory provided with the --dir option is processed last, if used - The directory provided with the --dir option is processed last, if used
Since coccicheck runs through make, it naturally runs from the kernel Since coccicheck runs through make, it naturally runs from the kernel
proper dir, as such the second rule above would be implied for picking up a proper dir, as such the second rule above would be implied for picking up a
.cocciconfig when using 'make coccicheck'. .cocciconfig when using ``make coccicheck``.
'make coccicheck' also supports using M= targets.If you do not supply ``make coccicheck`` also supports using M= targets.If you do not supply
any M= target, it is assumed you want to target the entire kernel. any M= target, it is assumed you want to target the entire kernel.
The kernel coccicheck script has: The kernel coccicheck script has::
if [ "$KBUILD_EXTMOD" = "" ] ; then if [ "$KBUILD_EXTMOD" = "" ] ; then
OPTIONS="--dir $srctree $COCCIINCLUDE" OPTIONS="--dir $srctree $COCCIINCLUDE"
...@@ -235,12 +248,12 @@ override any of the kernel's .coccicheck's settings using SPFLAGS. ...@@ -235,12 +248,12 @@ override any of the kernel's .coccicheck's settings using SPFLAGS.
We help Coccinelle when used against Linux with a set of sensible defaults We help Coccinelle when used against Linux with a set of sensible defaults
options for Linux with our own Linux .cocciconfig. This hints to coccinelle options for Linux with our own Linux .cocciconfig. This hints to coccinelle
git can be used for 'git grep' queries over coccigrep. A timeout of 200 git can be used for ``git grep`` queries over coccigrep. A timeout of 200
seconds should suffice for now. seconds should suffice for now.
The options picked up by coccinelle when reading a .cocciconfig do not appear The options picked up by coccinelle when reading a .cocciconfig do not appear
as arguments to spatch processes running on your system, to confirm what as arguments to spatch processes running on your system, to confirm what
options will be used by Coccinelle run: options will be used by Coccinelle run::
spatch --print-options-only spatch --print-options-only
...@@ -252,219 +265,227 @@ carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if ...@@ -252,219 +265,227 @@ carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if
desired. See below section "Additional flags" for more details on how to use desired. See below section "Additional flags" for more details on how to use
idutils. idutils.
Additional flags Additional flags
~~~~~~~~~~~~~~~~~~ ----------------
Additional flags can be passed to spatch through the SPFLAGS Additional flags can be passed to spatch through the SPFLAGS
variable. This works as Coccinelle respects the last flags variable. This works as Coccinelle respects the last flags
given to it when options are in conflict. given to it when options are in conflict. ::
make SPFLAGS=--use-glimpse coccicheck make SPFLAGS=--use-glimpse coccicheck
Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. Coccinelle supports idutils as well but requires coccinelle >= 1.0.6.
When no ID file is specified coccinelle assumes your ID database file When no ID file is specified coccinelle assumes your ID database file
is in the file .id-utils.index on the top level of the kernel, coccinelle is in the file .id-utils.index on the top level of the kernel, coccinelle
carries a script scripts/idutils_index.sh which creates the database with carries a script scripts/idutils_index.sh which creates the database with::
mkid -i C --output .id-utils.index mkid -i C --output .id-utils.index
If you have another database filename you can also just symlink with this If you have another database filename you can also just symlink with this
name. name. ::
make SPFLAGS=--use-idutils coccicheck make SPFLAGS=--use-idutils coccicheck
Alternatively you can specify the database filename explicitly, for Alternatively you can specify the database filename explicitly, for
instance: instance::
make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck
See spatch --help to learn more about spatch options. See ``spatch --help`` to learn more about spatch options.
Note that the '--use-glimpse' and '--use-idutils' options Note that the ``--use-glimpse`` and ``--use-idutils`` options
require external tools for indexing the code. None of them is require external tools for indexing the code. None of them is
thus active by default. However, by indexing the code with thus active by default. However, by indexing the code with
one of these tools, and according to the cocci file used, one of these tools, and according to the cocci file used,
spatch could proceed the entire code base more quickly. spatch could proceed the entire code base more quickly.
SmPL patch specific options SmPL patch specific options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
SmPL patches can have their own requirements for options passed SmPL patches can have their own requirements for options passed
to Coccinelle. SmPL patch specific options can be provided by to Coccinelle. SmPL patch specific options can be provided by
providing them at the top of the SmPL patch, for instance: providing them at the top of the SmPL patch, for instance::
// Options: --no-includes --include-headers // Options: --no-includes --include-headers
SmPL patch Coccinelle requirements SmPL patch Coccinelle requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------
As Coccinelle features get added some more advanced SmPL patches As Coccinelle features get added some more advanced SmPL patches
may require newer versions of Coccinelle. If an SmPL patch requires may require newer versions of Coccinelle. If an SmPL patch requires
at least a version of Coccinelle, this can be specified as follows, at least a version of Coccinelle, this can be specified as follows,
as an example if requiring at least Coccinelle >= 1.0.5: as an example if requiring at least Coccinelle >= 1.0.5::
// Requires: 1.0.5 // Requires: 1.0.5
Proposing new semantic patches Proposing new semantic patches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
New semantic patches can be proposed and submitted by kernel New semantic patches can be proposed and submitted by kernel
developers. For sake of clarity, they should be organized in the developers. For sake of clarity, they should be organized in the
sub-directories of 'scripts/coccinelle/'. sub-directories of ``scripts/coccinelle/``.
Detailed description of the 'report' mode Detailed description of the ``report`` mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------
``report`` generates a list in the following format::
'report' generates a list in the following format:
file:line:column-column: message file:line:column-column: message
Example: Example
~~~~~~~
Running Running::
make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci
will execute the following part of the SmPL script. will execute the following part of the SmPL script::
<smpl> <smpl>
@r depends on !context && !patch && (org || report)@ @r depends on !context && !patch && (org || report)@
expression x; expression x;
position p; position p;
@@ @@
ERR_PTR@p(PTR_ERR(x)) ERR_PTR@p(PTR_ERR(x))
@script:python depends on report@ @script:python depends on report@
p << r.p; p << r.p;
x << r.x; x << r.x;
@@ @@
msg="ERR_CAST can be used with %s" % (x) msg="ERR_CAST can be used with %s" % (x)
coccilib.report.print_report(p[0], msg) coccilib.report.print_report(p[0], msg)
</smpl> </smpl>
This SmPL excerpt generates entries on the standard output, as This SmPL excerpt generates entries on the standard output, as
illustrated below: illustrated below::
/home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg
/home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth
/home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg
Detailed description of the 'patch' mode Detailed description of the ``patch`` mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------
When the 'patch' mode is available, it proposes a fix for each problem When the ``patch`` mode is available, it proposes a fix for each problem
identified. identified.
Example: Example
~~~~~~~
Running::
Running
make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
will execute the following part of the SmPL script. will execute the following part of the SmPL script::
<smpl> <smpl>
@ depends on !context && patch && !org && !report @ @ depends on !context && patch && !org && !report @
expression x; expression x;
@@ @@
- ERR_PTR(PTR_ERR(x)) - ERR_PTR(PTR_ERR(x))
+ ERR_CAST(x) + ERR_CAST(x)
</smpl> </smpl>
This SmPL excerpt generates patch hunks on the standard output, as This SmPL excerpt generates patch hunks on the standard output, as
illustrated below: illustrated below::
diff -u -p a/crypto/ctr.c b/crypto/ctr.c diff -u -p a/crypto/ctr.c b/crypto/ctr.c
--- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200
+++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200
@@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct
alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
CRYPTO_ALG_TYPE_MASK); CRYPTO_ALG_TYPE_MASK);
if (IS_ERR(alg)) if (IS_ERR(alg))
- return ERR_PTR(PTR_ERR(alg)); - return ERR_PTR(PTR_ERR(alg));
+ return ERR_CAST(alg); + return ERR_CAST(alg);
/* Block size must be >= 4 bytes. */ /* Block size must be >= 4 bytes. */
err = -EINVAL; err = -EINVAL;
Detailed description of the 'context' mode Detailed description of the ``context`` mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------
'context' highlights lines of interest and their context ``context`` highlights lines of interest and their context
in a diff-like style. in a diff-like style.
NOTE: The diff-like output generated is NOT an applicable patch. The **NOTE**: The diff-like output generated is NOT an applicable patch. The
intent of the 'context' mode is to highlight the important lines intent of the ``context`` mode is to highlight the important lines
(annotated with minus, '-') and gives some surrounding context (annotated with minus, ``-``) and gives some surrounding context
lines around. This output can be used with the diff mode of lines around. This output can be used with the diff mode of
Emacs to review the code. Emacs to review the code.
Example: Example
~~~~~~~
Running::
Running
make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci
will execute the following part of the SmPL script. will execute the following part of the SmPL script::
<smpl> <smpl>
@ depends on context && !patch && !org && !report@ @ depends on context && !patch && !org && !report@
expression x; expression x;
@@ @@
* ERR_PTR(PTR_ERR(x)) * ERR_PTR(PTR_ERR(x))
</smpl> </smpl>
This SmPL excerpt generates diff hunks on the standard output, as This SmPL excerpt generates diff hunks on the standard output, as
illustrated below: illustrated below::
diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing
--- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200
+++ /tmp/nothing +++ /tmp/nothing
@@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct
alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
CRYPTO_ALG_TYPE_MASK); CRYPTO_ALG_TYPE_MASK);
if (IS_ERR(alg)) if (IS_ERR(alg))
- return ERR_PTR(PTR_ERR(alg)); - return ERR_PTR(PTR_ERR(alg));
/* Block size must be >= 4 bytes. */ /* Block size must be >= 4 bytes. */
err = -EINVAL; err = -EINVAL;
Detailed description of the 'org' mode Detailed description of the ``org`` mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------
``org`` generates a report in the Org mode format of Emacs.
'org' generates a report in the Org mode format of Emacs. Example
~~~~~~~
Example: Running::
Running
make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci
will execute the following part of the SmPL script. will execute the following part of the SmPL script::
<smpl> <smpl>
@r depends on !context && !patch && (org || report)@ @r depends on !context && !patch && (org || report)@
expression x; expression x;
position p; position p;
@@ @@
ERR_PTR@p(PTR_ERR(x)) ERR_PTR@p(PTR_ERR(x))
@script:python depends on org@ @script:python depends on org@
p << r.p; p << r.p;
x << r.x; x << r.x;
@@ @@
msg="ERR_CAST can be used with %s" % (x) msg="ERR_CAST can be used with %s" % (x)
msg_safe=msg.replace("[","@(").replace("]",")") msg_safe=msg.replace("[","@(").replace("]",")")
coccilib.org.print_todo(p[0], msg_safe) coccilib.org.print_todo(p[0], msg_safe)
</smpl> </smpl>
This SmPL excerpt generates Org entries on the standard output, as This SmPL excerpt generates Org entries on the standard output, as
illustrated below: illustrated below::
* TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]]
* TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]]
* TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]]
Documentation/gcov.txt → Documentation/dev-tools/gcov.rst
View file @ 02bafd96
Using gcov with the Linux kernel Using gcov with the Linux kernel
================================ ================================
1. Introduction
2. Preparation
3. Customization
4. Files
5. Modules
6. Separated build and test machines
7. Troubleshooting
Appendix A: sample script: gather_on_build.sh
Appendix B: sample script: gather_on_test.sh
1. Introduction
===============
gcov profiling kernel support enables the use of GCC's coverage testing gcov profiling kernel support enables the use of GCC's coverage testing
tool gcov [1] with the Linux kernel. Coverage data of a running kernel tool gcov_ with the Linux kernel. Coverage data of a running kernel
is exported in gcov-compatible format via the "gcov" debugfs directory. is exported in gcov-compatible format via the "gcov" debugfs directory.
To get coverage data for a specific file, change to the kernel build To get coverage data for a specific file, change to the kernel build
directory and use gcov with the -o option as follows (requires root): directory and use gcov with the ``-o`` option as follows (requires root)::
# cd /tmp/linux-out # cd /tmp/linux-out
# gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c
This will create source code files annotated with execution counts This will create source code files annotated with execution counts
in the current directory. In addition, graphical gcov front-ends such in the current directory. In addition, graphical gcov front-ends such
as lcov [2] can be used to automate the process of collecting data as lcov_ can be used to automate the process of collecting data
for the entire kernel and provide coverage overviews in HTML format. for the entire kernel and provide coverage overviews in HTML format.
Possible uses: Possible uses:
...@@ -36,25 +22,23 @@ Possible uses: ...@@ -36,25 +22,23 @@ Possible uses:
* minimizing kernel configurations (do I need this option if the * minimizing kernel configurations (do I need this option if the
associated code is never run?) associated code is never run?)
-- .. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php
[1] http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
[2] http://ltp.sourceforge.net/coverage/lcov.php
2. Preparation Preparation
============== -----------
Configure the kernel with: Configure the kernel with::
CONFIG_DEBUG_FS=y CONFIG_DEBUG_FS=y
CONFIG_GCOV_KERNEL=y CONFIG_GCOV_KERNEL=y
select the gcc's gcov format, default is autodetect based on gcc version: select the gcc's gcov format, default is autodetect based on gcc version::
CONFIG_GCOV_FORMAT_AUTODETECT=y CONFIG_GCOV_FORMAT_AUTODETECT=y
and to get coverage data for the entire kernel: and to get coverage data for the entire kernel::
CONFIG_GCOV_PROFILE_ALL=y CONFIG_GCOV_PROFILE_ALL=y
...@@ -63,58 +47,62 @@ larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported ...@@ -63,58 +47,62 @@ larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported
on all architectures. on all architectures.
Profiling data will only become accessible once debugfs has been Profiling data will only become accessible once debugfs has been
mounted: mounted::
mount -t debugfs none /sys/kernel/debug mount -t debugfs none /sys/kernel/debug
3. Customization Customization
================ -------------
To enable profiling for specific files or directories, add a line To enable profiling for specific files or directories, add a line
similar to the following to the respective kernel Makefile: similar to the following to the respective kernel Makefile:
For a single file (e.g. main.o): - For a single file (e.g. main.o)::
GCOV_PROFILE_main.o := y
For all files in one directory: GCOV_PROFILE_main.o := y
GCOV_PROFILE := y
- For all files in one directory::
GCOV_PROFILE := y
To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL
is specified, use: is specified, use::
GCOV_PROFILE_main.o := n
GCOV_PROFILE_main.o := n and::
and:
GCOV_PROFILE := n GCOV_PROFILE := n
Only files which are linked to the main kernel image or are compiled as Only files which are linked to the main kernel image or are compiled as
kernel modules are supported by this mechanism. kernel modules are supported by this mechanism.
4. Files Files
======== -----
The gcov kernel support creates the following files in debugfs: The gcov kernel support creates the following files in debugfs:
/sys/kernel/debug/gcov ``/sys/kernel/debug/gcov``
Parent directory for all gcov-related files. Parent directory for all gcov-related files.
/sys/kernel/debug/gcov/reset ``/sys/kernel/debug/gcov/reset``
Global reset file: resets all coverage data to zero when Global reset file: resets all coverage data to zero when
written to. written to.
/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda``
The actual gcov data file as understood by the gcov The actual gcov data file as understood by the gcov
tool. Resets file coverage data to zero when written to. tool. Resets file coverage data to zero when written to.
/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno``
Symbolic link to a static data file required by the gcov Symbolic link to a static data file required by the gcov
tool. This file is generated by gcc when compiling with tool. This file is generated by gcc when compiling with
option -ftest-coverage. option ``-ftest-coverage``.
5. Modules Modules
========== -------
Kernel modules may contain cleanup code which is only run during Kernel modules may contain cleanup code which is only run during
module unload time. The gcov mechanism provides a means to collect module unload time. The gcov mechanism provides a means to collect
...@@ -124,7 +112,7 @@ Once the module is loaded again, the associated coverage counters are ...@@ -124,7 +112,7 @@ Once the module is loaded again, the associated coverage counters are
initialized with the data from its previous instantiation. initialized with the data from its previous instantiation.
This behavior can be deactivated by specifying the gcov_persist kernel This behavior can be deactivated by specifying the gcov_persist kernel
parameter: parameter::
gcov_persist=0 gcov_persist=0
...@@ -132,8 +120,8 @@ At run-time, a user can also choose to discard data for an unloaded ...@@ -132,8 +120,8 @@ At run-time, a user can also choose to discard data for an unloaded
module by writing to its data file or the global reset file. module by writing to its data file or the global reset file.
6. Separated build and test machines Separated build and test machines
==================================== ---------------------------------
The gcov kernel profiling infrastructure is designed to work out-of-the The gcov kernel profiling infrastructure is designed to work out-of-the
box for setups where kernels are built and run on the same machine. In box for setups where kernels are built and run on the same machine. In
...@@ -142,116 +130,127 @@ must be made, depending on where the gcov tool is used: ...@@ -142,116 +130,127 @@ must be made, depending on where the gcov tool is used:
a) gcov is run on the TEST machine a) gcov is run on the TEST machine
The gcov tool version on the test machine must be compatible with the The gcov tool version on the test machine must be compatible with the
gcc version used for kernel build. Also the following files need to be gcc version used for kernel build. Also the following files need to be
copied from build to test machine: copied from build to test machine:
from the source tree: from the source tree:
- all C source files + headers - all C source files + headers
from the build tree: from the build tree:
- all C source files + headers - all C source files + headers
- all .gcda and .gcno files - all .gcda and .gcno files
- all links to directories - all links to directories
It is important to note that these files need to be placed into the It is important to note that these files need to be placed into the
exact same file system location on the test machine as on the build exact same file system location on the test machine as on the build
machine. If any of the path components is symbolic link, the actual machine. If any of the path components is symbolic link, the actual
directory needs to be used instead (due to make's CURDIR handling). directory needs to be used instead (due to make's CURDIR handling).
b) gcov is run on the BUILD machine b) gcov is run on the BUILD machine
The following files need to be copied after each test case from test The following files need to be copied after each test case from test
to build machine: to build machine:
from the gcov directory in sysfs:
- all .gcda files
- all links to .gcno files
These files can be copied to any location on the build machine. gcov
must then be called with the -o option pointing to that directory.
from the gcov directory in sysfs: Example directory setup on the build machine::
- all .gcda files
- all links to .gcno files
These files can be copied to any location on the build machine. gcov /tmp/linux: kernel source tree
must then be called with the -o option pointing to that directory. /tmp/out: kernel build directory as specified by make O=
/tmp/coverage: location of the files copied from the test machine
Example directory setup on the build machine: [user@build] cd /tmp/out
[user@build] gcov -o /tmp/coverage/tmp/out/init main.c
/tmp/linux: kernel source tree
/tmp/out: kernel build directory as specified by make O=
/tmp/coverage: location of the files copied from the test machine
[user@build] cd /tmp/out Troubleshooting
[user@build] gcov -o /tmp/coverage/tmp/out/init main.c ---------------
Problem
Compilation aborts during linker step.
7. Troubleshooting Cause
================== Profiling flags are specified for source files which are not
linked to the main kernel or which are linked by a custom
linker procedure.
Problem: Compilation aborts during linker step. Solution
Cause: Profiling flags are specified for source files which are not Exclude affected source files from profiling by specifying
linked to the main kernel or which are linked by a custom ``GCOV_PROFILE := n`` or ``GCOV_PROFILE_basename.o := n`` in the
linker procedure. corresponding Makefile.
Solution: Exclude affected source files from profiling by specifying
GCOV_PROFILE := n or GCOV_PROFILE_basename.o := n in the
corresponding Makefile.
Problem: Files copied from sysfs appear empty or incomplete. Problem
Cause: Due to the way seq_file works, some tools such as cp or tar Files copied from sysfs appear empty or incomplete.
may not correctly copy files from sysfs.
Solution: Use 'cat' to read .gcda files and 'cp -d' to copy links. Cause
Alternatively use the mechanism shown in Appendix B. Due to the way seq_file works, some tools such as cp or tar
may not correctly copy files from sysfs.
Solution
Use ``cat``' to read ``.gcda`` files and ``cp -d`` to copy links.
Alternatively use the mechanism shown in Appendix B.
Appendix A: gather_on_build.sh Appendix A: gather_on_build.sh
============================== ------------------------------
Sample script to gather coverage meta files on the build machine Sample script to gather coverage meta files on the build machine
(see 6a): (see 6a)::
#!/bin/bash
#!/bin/bash
KSRC=$1 KSRC=$1
KOBJ=$2 KOBJ=$2
DEST=$3 DEST=$3
if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then
echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2 echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2
exit 1 exit 1
fi fi
KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \
-perm /u+r,g+r | tar cfz $DEST -P -T - -perm /u+r,g+r | tar cfz $DEST -P -T -
if [ $? -eq 0 ] ; then if [ $? -eq 0 ] ; then
echo "$DEST successfully created, copy to test system and unpack with:" echo "$DEST successfully created, copy to test system and unpack with:"
echo " tar xfz $DEST -P" echo " tar xfz $DEST -P"
else else
echo "Could not create file $DEST" echo "Could not create file $DEST"
fi fi
Appendix B: gather_on_test.sh Appendix B: gather_on_test.sh
============================= -----------------------------
Sample script to gather coverage data files on the test machine Sample script to gather coverage data files on the test machine
(see 6b): (see 6b)::
#!/bin/bash -e #!/bin/bash -e
DEST=$1 DEST=$1
GCDA=/sys/kernel/debug/gcov GCDA=/sys/kernel/debug/gcov
if [ -z "$DEST" ] ; then if [ -z "$DEST" ] ; then
echo "Usage: $0 <output.tar.gz>" >&2 echo "Usage: $0 <output.tar.gz>" >&2
exit 1 exit 1
fi fi
TEMPDIR=$(mktemp -d) TEMPDIR=$(mktemp -d)
echo Collecting data.. echo Collecting data..
find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \;
find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \;
find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \;
tar czf $DEST -C $TEMPDIR sys tar czf $DEST -C $TEMPDIR sys
rm -rf $TEMPDIR rm -rf $TEMPDIR
echo "$DEST successfully created, copy to build system and unpack with:" echo "$DEST successfully created, copy to build system and unpack with:"
echo " tar xfz $DEST" echo " tar xfz $DEST"
Documentation/gdb-kernel-debugging.txt → Documentation/dev-tools/gdb-kernel-debugging.rst
View file @ 02bafd96
.. highlight:: none
Debugging kernel and modules via gdb Debugging kernel and modules via gdb
==================================== ====================================
...@@ -13,54 +15,58 @@ be transferred to the other gdb stubs as well. ...@@ -13,54 +15,58 @@ be transferred to the other gdb stubs as well.
Requirements Requirements
------------ ------------
o gdb 7.2+ (recommended: 7.4+) with python support enabled (typically true - gdb 7.2+ (recommended: 7.4+) with python support enabled (typically true
for distributions) for distributions)
Setup Setup
----- -----
o Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and - Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and
www.qemu.org for more details). For cross-development, www.qemu.org for more details). For cross-development,
http://landley.net/aboriginal/bin keeps a pool of machine images and http://landley.net/aboriginal/bin keeps a pool of machine images and
toolchains that can be helpful to start from. toolchains that can be helpful to start from.
o Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave - Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave
CONFIG_DEBUG_INFO_REDUCED off. If your architecture supports CONFIG_DEBUG_INFO_REDUCED off. If your architecture supports
CONFIG_FRAME_POINTER, keep it enabled. CONFIG_FRAME_POINTER, keep it enabled.
o Install that kernel on the guest. - Install that kernel on the guest.
Alternatively, QEMU allows to boot the kernel directly using -kernel,
-append, -initrd command line switches. This is generally only useful if
you do not depend on modules. See QEMU documentation for more details on
this mode.
Alternatively, QEMU allows to boot the kernel directly using -kernel, - Enable the gdb stub of QEMU/KVM, either
-append, -initrd command line switches. This is generally only useful if
you do not depend on modules. See QEMU documentation for more details on
this mode.
o Enable the gdb stub of QEMU/KVM, either
- at VM startup time by appending "-s" to the QEMU command line - at VM startup time by appending "-s" to the QEMU command line
or
or
- during runtime by issuing "gdbserver" from the QEMU monitor - during runtime by issuing "gdbserver" from the QEMU monitor
console console
o cd /path/to/linux-build - cd /path/to/linux-build
o Start gdb: gdb vmlinux - Start gdb: gdb vmlinux
Note: Some distros may restrict auto-loading of gdb scripts to known safe Note: Some distros may restrict auto-loading of gdb scripts to known safe
directories. In case gdb reports to refuse loading vmlinux-gdb.py, add directories. In case gdb reports to refuse loading vmlinux-gdb.py, add::
add-auto-load-safe-path /path/to/linux-build add-auto-load-safe-path /path/to/linux-build
to ~/.gdbinit. See gdb help for more details. to ~/.gdbinit. See gdb help for more details.
- Attach to the booted guest::
o Attach to the booted guest:
(gdb) target remote :1234 (gdb) target remote :1234
Examples of using the Linux-provided gdb helpers Examples of using the Linux-provided gdb helpers
------------------------------------------------ ------------------------------------------------
o Load module (and main kernel) symbols: - Load module (and main kernel) symbols::
(gdb) lx-symbols (gdb) lx-symbols
loading vmlinux loading vmlinux
scanning for modules in /home/user/linux/build scanning for modules in /home/user/linux/build
...@@ -72,17 +78,20 @@ Examples of using the Linux-provided gdb helpers ...@@ -72,17 +78,20 @@ Examples of using the Linux-provided gdb helpers
... ...
loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko
o Set a breakpoint on some not yet loaded module function, e.g.: - Set a breakpoint on some not yet loaded module function, e.g.::
(gdb) b btrfs_init_sysfs (gdb) b btrfs_init_sysfs
Function "btrfs_init_sysfs" not defined. Function "btrfs_init_sysfs" not defined.
Make breakpoint pending on future shared library load? (y or [n]) y Make breakpoint pending on future shared library load? (y or [n]) y
Breakpoint 1 (btrfs_init_sysfs) pending. Breakpoint 1 (btrfs_init_sysfs) pending.
o Continue the target - Continue the target::
(gdb) c (gdb) c
o Load the module on the target and watch the symbols being loaded as well as - Load the module on the target and watch the symbols being loaded as well as
the breakpoint hit: the breakpoint hit::
loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko
loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko
loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko
...@@ -91,7 +100,8 @@ Examples of using the Linux-provided gdb helpers ...@@ -91,7 +100,8 @@ Examples of using the Linux-provided gdb helpers
Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36 Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36
36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj); 36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj);
o Dump the log buffer of the target kernel: - Dump the log buffer of the target kernel::
(gdb) lx-dmesg (gdb) lx-dmesg
[ 0.000000] Initializing cgroup subsys cpuset [ 0.000000] Initializing cgroup subsys cpuset
[ 0.000000] Initializing cgroup subsys cpu [ 0.000000] Initializing cgroup subsys cpu
...@@ -102,19 +112,22 @@ Examples of using the Linux-provided gdb helpers ...@@ -102,19 +112,22 @@ Examples of using the Linux-provided gdb helpers
[ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved [ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved
.... ....
o Examine fields of the current task struct: - Examine fields of the current task struct::
(gdb) p $lx_current().pid (gdb) p $lx_current().pid
$1 = 4998 $1 = 4998
(gdb) p $lx_current().comm (gdb) p $lx_current().comm
$2 = "modprobe\000\000\000\000\000\000\000" $2 = "modprobe\000\000\000\000\000\000\000"
o Make use of the per-cpu function for the current or a specified CPU: - Make use of the per-cpu function for the current or a specified CPU::
(gdb) p $lx_per_cpu("runqueues").nr_running (gdb) p $lx_per_cpu("runqueues").nr_running
$3 = 1 $3 = 1
(gdb) p $lx_per_cpu("runqueues", 2).nr_running (gdb) p $lx_per_cpu("runqueues", 2).nr_running
$4 = 0 $4 = 0
o Dig into hrtimers using the container_of helper: - Dig into hrtimers using the container_of helper::
(gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next (gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next
(gdb) p *$container_of($next, "struct hrtimer", "node") (gdb) p *$container_of($next, "struct hrtimer", "node")
$5 = { $5 = {
...@@ -144,7 +157,7 @@ List of commands and functions ...@@ -144,7 +157,7 @@ List of commands and functions
------------------------------ ------------------------------
The number of commands and convenience functions may evolve over the time, The number of commands and convenience functions may evolve over the time,
this is just a snapshot of the initial version: this is just a snapshot of the initial version::
(gdb) apropos lx (gdb) apropos lx
function lx_current -- Return current task function lx_current -- Return current task
......
Documentation/kasan.txt → Documentation/dev-tools/kasan.rst
View file @ 02bafd96
KernelAddressSanitizer (KASAN) The Kernel Address Sanitizer (KASAN)
============================== ====================================
0. Overview Overview
=========== --------
KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides
a fast and comprehensive solution for finding use-after-free and out-of-bounds a fast and comprehensive solution for finding use-after-free and out-of-bounds
...@@ -12,12 +12,12 @@ KASAN uses compile-time instrumentation for checking every memory access, ...@@ -12,12 +12,12 @@ KASAN uses compile-time instrumentation for checking every memory access,
therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is
required for detection of out-of-bounds accesses to stack or global variables. required for detection of out-of-bounds accesses to stack or global variables.
Currently KASAN is supported only for x86_64 architecture. Currently KASAN is supported only for the x86_64 and arm64 architectures.
1. Usage Usage
======== -----
To enable KASAN configure kernel with: To enable KASAN configure kernel with::
CONFIG_KASAN = y CONFIG_KASAN = y
...@@ -32,89 +32,91 @@ For better bug detection and nicer reporting, enable CONFIG_STACKTRACE. ...@@ -32,89 +32,91 @@ For better bug detection and nicer reporting, enable CONFIG_STACKTRACE.
To disable instrumentation for specific files or directories, add a line To disable instrumentation for specific files or directories, add a line
similar to the following to the respective kernel Makefile: similar to the following to the respective kernel Makefile:
For a single file (e.g. main.o): - For a single file (e.g. main.o)::
KASAN_SANITIZE_main.o := n
KASAN_SANITIZE_main.o := n
For all files in one directory:
KASAN_SANITIZE := n - For all files in one directory::
1.1 Error reports KASAN_SANITIZE := n
=================
Error reports
A typical out of bounds access report looks like this: ~~~~~~~~~~~~~
================================================================== A typical out of bounds access report looks like this::
BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3
Write of size 1 by task modprobe/1689 ==================================================================
============================================================================= BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3
BUG kmalloc-128 (Not tainted): kasan error Write of size 1 by task modprobe/1689
----------------------------------------------------------------------------- =============================================================================
BUG kmalloc-128 (Not tainted): kasan error
Disabling lock debugging due to kernel taint -----------------------------------------------------------------------------
INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689
__slab_alloc+0x4b4/0x4f0 Disabling lock debugging due to kernel taint
kmem_cache_alloc_trace+0x10b/0x190 INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689
kmalloc_oob_right+0x3d/0x75 [test_kasan] __slab_alloc+0x4b4/0x4f0
init_module+0x9/0x47 [test_kasan] kmem_cache_alloc_trace+0x10b/0x190
do_one_initcall+0x99/0x200 kmalloc_oob_right+0x3d/0x75 [test_kasan]
load_module+0x2cb3/0x3b20 init_module+0x9/0x47 [test_kasan]
SyS_finit_module+0x76/0x80 do_one_initcall+0x99/0x200
system_call_fastpath+0x12/0x17 load_module+0x2cb3/0x3b20
INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080 SyS_finit_module+0x76/0x80
INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720 system_call_fastpath+0x12/0x17
INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080
Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720
Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ
Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk. Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc ........ Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk.
CPU: 0 PID: 1689 Comm: modprobe Tainted: G B 3.18.0-rc1-mm1+ #98 Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc ........
Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014 Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ
ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78 CPU: 0 PID: 1689 Comm: modprobe Tainted: G B 3.18.0-rc1-mm1+ #98
ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8 Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014
ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558 ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78
Call Trace: ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8
[<ffffffff81cc68ae>] dump_stack+0x46/0x58 ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558
[<ffffffff811fd848>] print_trailer+0xf8/0x160 Call Trace:
[<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] [<ffffffff81cc68ae>] dump_stack+0x46/0x58
[<ffffffff811ff0f5>] object_err+0x35/0x40 [<ffffffff811fd848>] print_trailer+0xf8/0x160
[<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan] [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan]
[<ffffffff8120b9fa>] kasan_report_error+0x38a/0x3f0 [<ffffffff811ff0f5>] object_err+0x35/0x40
[<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40 [<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan]
[<ffffffff8120b344>] ? kasan_unpoison_shadow+0x14/0x40 [<ffffffff8120b9fa>] kasan_report_error+0x38a/0x3f0
[<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40 [<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40
[<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] [<ffffffff8120b344>] ? kasan_unpoison_shadow+0x14/0x40
[<ffffffff8120a995>] __asan_store1+0x75/0xb0 [<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40
[<ffffffffa0002601>] ? kmem_cache_oob+0x1d/0xc3 [test_kasan] [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan]
[<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan] [<ffffffff8120a995>] __asan_store1+0x75/0xb0
[<ffffffffa0002065>] kmalloc_oob_right+0x65/0x75 [test_kasan] [<ffffffffa0002601>] ? kmem_cache_oob+0x1d/0xc3 [test_kasan]
[<ffffffffa00026b0>] init_module+0x9/0x47 [test_kasan] [<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan]
[<ffffffff810002d9>] do_one_initcall+0x99/0x200 [<ffffffffa0002065>] kmalloc_oob_right+0x65/0x75 [test_kasan]
[<ffffffff811e4e5c>] ? __vunmap+0xec/0x160 [<ffffffffa00026b0>] init_module+0x9/0x47 [test_kasan]
[<ffffffff81114f63>] load_module+0x2cb3/0x3b20 [<ffffffff810002d9>] do_one_initcall+0x99/0x200
[<ffffffff8110fd70>] ? m_show+0x240/0x240 [<ffffffff811e4e5c>] ? __vunmap+0xec/0x160
[<ffffffff81115f06>] SyS_finit_module+0x76/0x80 [<ffffffff81114f63>] load_module+0x2cb3/0x3b20
[<ffffffff81cd3129>] system_call_fastpath+0x12/0x17 [<ffffffff8110fd70>] ? m_show+0x240/0x240
Memory state around the buggy address: [<ffffffff81115f06>] SyS_finit_module+0x76/0x80
ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc [<ffffffff81cd3129>] system_call_fastpath+0x12/0x17
ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc Memory state around the buggy address:
ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc
ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00 ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
>ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00
>ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc
^ ^
ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb
ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb
ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb
================================================================== ==================================================================
The header of the report discribe what kind of bug happened and what kind of The header of the report discribe what kind of bug happened and what kind of
access caused it. It's followed by the description of the accessed slub object access caused it. It's followed by the description of the accessed slub object
...@@ -137,8 +139,8 @@ In the report above the arrows point to the shadow byte 03, which means that ...@@ -137,8 +139,8 @@ In the report above the arrows point to the shadow byte 03, which means that
the accessed address is partially accessible. the accessed address is partially accessible.
2. Implementation details Implementation details
========================= ----------------------
From a high level, our approach to memory error detection is similar to that From a high level, our approach to memory error detection is similar to that
of kmemcheck: use shadow memory to record whether each byte of memory is safe of kmemcheck: use shadow memory to record whether each byte of memory is safe
...@@ -150,15 +152,15 @@ AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory ...@@ -150,15 +152,15 @@ AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory
offset to translate a memory address to its corresponding shadow address. offset to translate a memory address to its corresponding shadow address.
Here is the function which translates an address to its corresponding shadow Here is the function which translates an address to its corresponding shadow
address: address::
static inline void *kasan_mem_to_shadow(const void *addr) static inline void *kasan_mem_to_shadow(const void *addr)
{ {
return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT)
+ KASAN_SHADOW_OFFSET; + KASAN_SHADOW_OFFSET;
} }
where KASAN_SHADOW_SCALE_SHIFT = 3. where ``KASAN_SHADOW_SCALE_SHIFT = 3``.
Compile-time instrumentation used for checking memory accesses. Compiler inserts Compile-time instrumentation used for checking memory accesses. Compiler inserts
function calls (__asan_load*(addr), __asan_store*(addr)) before each memory function calls (__asan_load*(addr), __asan_store*(addr)) before each memory
......
Documentation/kcov.txt → Documentation/dev-tools/kcov.rst
View file @ 02bafd96
...@@ -12,38 +12,38 @@ To achieve this goal it does not collect coverage in soft/hard interrupts ...@@ -12,38 +12,38 @@ To achieve this goal it does not collect coverage in soft/hard interrupts
and instrumentation of some inherently non-deterministic parts of kernel is and instrumentation of some inherently non-deterministic parts of kernel is
disbled (e.g. scheduler, locking). disbled (e.g. scheduler, locking).
Usage: Usage
====== -----
Configure kernel with: Configure the kernel with::
CONFIG_KCOV=y CONFIG_KCOV=y
CONFIG_KCOV requires gcc built on revision 231296 or later. CONFIG_KCOV requires gcc built on revision 231296 or later.
Profiling data will only become accessible once debugfs has been mounted: Profiling data will only become accessible once debugfs has been mounted::
mount -t debugfs none /sys/kernel/debug mount -t debugfs none /sys/kernel/debug
The following program demonstrates kcov usage from within a test program: The following program demonstrates kcov usage from within a test program::
#include <stdio.h> #include <stdio.h>
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
#include <stdlib.h> #include <stdlib.h>
#include <sys/types.h> #include <sys/types.h>
#include <sys/stat.h> #include <sys/stat.h>
#include <sys/ioctl.h> #include <sys/ioctl.h>
#include <sys/mman.h> #include <sys/mman.h>
#include <unistd.h> #include <unistd.h>
#include <fcntl.h> #include <fcntl.h>
#define KCOV_INIT_TRACE _IOR('c', 1, unsigned long) #define KCOV_INIT_TRACE _IOR('c', 1, unsigned long)
#define KCOV_ENABLE _IO('c', 100) #define KCOV_ENABLE _IO('c', 100)
#define KCOV_DISABLE _IO('c', 101) #define KCOV_DISABLE _IO('c', 101)
#define COVER_SIZE (64<<10) #define COVER_SIZE (64<<10)
int main(int argc, char **argv) int main(int argc, char **argv)
{ {
int fd; int fd;
unsigned long *cover, n, i; unsigned long *cover, n, i;
...@@ -83,24 +83,24 @@ int main(int argc, char **argv) ...@@ -83,24 +83,24 @@ int main(int argc, char **argv)
if (close(fd)) if (close(fd))
perror("close"), exit(1); perror("close"), exit(1);
return 0; return 0;
} }
After piping through addr2line output of the program looks as follows: After piping through addr2line output of the program looks as follows::
SyS_read SyS_read
fs/read_write.c:562 fs/read_write.c:562
__fdget_pos __fdget_pos
fs/file.c:774 fs/file.c:774
__fget_light __fget_light
fs/file.c:746 fs/file.c:746
__fget_light __fget_light
fs/file.c:750 fs/file.c:750
__fget_light __fget_light
fs/file.c:760 fs/file.c:760
__fdget_pos __fdget_pos
fs/file.c:784 fs/file.c:784
SyS_read SyS_read
fs/read_write.c:562 fs/read_write.c:562
If a program needs to collect coverage from several threads (independently), If a program needs to collect coverage from several threads (independently),
it needs to open /sys/kernel/debug/kcov in each thread separately. it needs to open /sys/kernel/debug/kcov in each thread separately.
......
Documentation/kmemcheck.txt → Documentation/dev-tools/kmemcheck.rst
View file @ 02bafd96
GETTING STARTED WITH KMEMCHECK Getting started with kmemcheck
============================== ==============================
Vegard Nossum <vegardno@ifi.uio.no> Vegard Nossum <vegardno@ifi.uio.no>
Contents Introduction
======== ------------
0. Introduction
1. Downloading
2. Configuring and compiling
3. How to use
3.1. Booting
3.2. Run-time enable/disable
3.3. Debugging
3.4. Annotating false positives
4. Reporting errors
5. Technical description
0. Introduction
===============
kmemcheck is a debugging feature for the Linux Kernel. More specifically, it kmemcheck is a debugging feature for the Linux Kernel. More specifically, it
is a dynamic checker that detects and warns about some uses of uninitialized is a dynamic checker that detects and warns about some uses of uninitialized
...@@ -40,21 +26,20 @@ as much memory as normal. For this reason, kmemcheck is strictly a debugging ...@@ -40,21 +26,20 @@ as much memory as normal. For this reason, kmemcheck is strictly a debugging
feature. feature.
1. Downloading Downloading
============== -----------
As of version 2.6.31-rc1, kmemcheck is included in the mainline kernel. As of version 2.6.31-rc1, kmemcheck is included in the mainline kernel.
2. Configuring and compiling Configuring and compiling
============================ -------------------------
kmemcheck only works for the x86 (both 32- and 64-bit) platform. A number of kmemcheck only works for the x86 (both 32- and 64-bit) platform. A number of
configuration variables must have specific settings in order for the kmemcheck configuration variables must have specific settings in order for the kmemcheck
menu to even appear in "menuconfig". These are: menu to even appear in "menuconfig". These are:
o CONFIG_CC_OPTIMIZE_FOR_SIZE=n - ``CONFIG_CC_OPTIMIZE_FOR_SIZE=n``
This option is located under "General setup" / "Optimize for size". This option is located under "General setup" / "Optimize for size".
Without this, gcc will use certain optimizations that usually lead to Without this, gcc will use certain optimizations that usually lead to
...@@ -63,13 +48,11 @@ menu to even appear in "menuconfig". These are: ...@@ -63,13 +48,11 @@ menu to even appear in "menuconfig". These are:
16 bits. kmemcheck sees only the 32-bit load, and may trigger a 16 bits. kmemcheck sees only the 32-bit load, and may trigger a
warning for the upper 16 bits (if they're uninitialized). warning for the upper 16 bits (if they're uninitialized).
o CONFIG_SLAB=y or CONFIG_SLUB=y - ``CONFIG_SLAB=y`` or ``CONFIG_SLUB=y``
This option is located under "General setup" / "Choose SLAB This option is located under "General setup" / "Choose SLAB
allocator". allocator".
o CONFIG_FUNCTION_TRACER=n - ``CONFIG_FUNCTION_TRACER=n``
This option is located under "Kernel hacking" / "Tracers" / "Kernel This option is located under "Kernel hacking" / "Tracers" / "Kernel
Function Tracer" Function Tracer"
...@@ -80,12 +63,11 @@ menu to even appear in "menuconfig". These are: ...@@ -80,12 +63,11 @@ menu to even appear in "menuconfig". These are:
modifies memory that was tracked by kmemcheck, the result is an modifies memory that was tracked by kmemcheck, the result is an
endless recursive page fault. endless recursive page fault.
o CONFIG_DEBUG_PAGEALLOC=n - ``CONFIG_DEBUG_PAGEALLOC=n``
This option is located under "Kernel hacking" / "Memory Debugging" This option is located under "Kernel hacking" / "Memory Debugging"
/ "Debug page memory allocations". / "Debug page memory allocations".
In addition, I highly recommend turning on CONFIG_DEBUG_INFO=y. This is also In addition, I highly recommend turning on ``CONFIG_DEBUG_INFO=y``. This is also
located under "Kernel hacking". With this, you will be able to get line number located under "Kernel hacking". With this, you will be able to get line number
information from the kmemcheck warnings, which is extremely valuable in information from the kmemcheck warnings, which is extremely valuable in
debugging a problem. This option is not mandatory, however, because it slows debugging a problem. This option is not mandatory, however, because it slows
...@@ -95,12 +77,10 @@ Now the kmemcheck menu should be visible (under "Kernel hacking" / "Memory ...@@ -95,12 +77,10 @@ Now the kmemcheck menu should be visible (under "Kernel hacking" / "Memory
Debugging" / "kmemcheck: trap use of uninitialized memory"). Here follows Debugging" / "kmemcheck: trap use of uninitialized memory"). Here follows
a description of the kmemcheck configuration variables: a description of the kmemcheck configuration variables:
o CONFIG_KMEMCHECK - ``CONFIG_KMEMCHECK``
This must be enabled in order to use kmemcheck at all... This must be enabled in order to use kmemcheck at all...
o CONFIG_KMEMCHECK_[DISABLED | ENABLED | ONESHOT]_BY_DEFAULT - ``CONFIG_KMEMCHECK_``[``DISABLED`` | ``ENABLED`` | ``ONESHOT``]``_BY_DEFAULT``
This option controls the status of kmemcheck at boot-time. "Enabled" This option controls the status of kmemcheck at boot-time. "Enabled"
will enable kmemcheck right from the start, "disabled" will boot the will enable kmemcheck right from the start, "disabled" will boot the
kernel as normal (but with the kmemcheck code compiled in, so it can kernel as normal (but with the kmemcheck code compiled in, so it can
...@@ -125,8 +105,7 @@ a description of the kmemcheck configuration variables: ...@@ -125,8 +105,7 @@ a description of the kmemcheck configuration variables:
time overhead is not incurred, and the kernel will be almost as fast time overhead is not incurred, and the kernel will be almost as fast
as normal. as normal.
o CONFIG_KMEMCHECK_QUEUE_SIZE - ``CONFIG_KMEMCHECK_QUEUE_SIZE``
Select the maximum number of error reports to store in an internal Select the maximum number of error reports to store in an internal
(fixed-size) buffer. Since errors can occur virtually anywhere and in (fixed-size) buffer. Since errors can occur virtually anywhere and in
any context, we need a temporary storage area which is guaranteed not any context, we need a temporary storage area which is guaranteed not
...@@ -147,8 +126,7 @@ a description of the kmemcheck configuration variables: ...@@ -147,8 +126,7 @@ a description of the kmemcheck configuration variables:
will get lost in that way instead. Try setting this to 10 or so on will get lost in that way instead. Try setting this to 10 or so on
such a setup. such a setup.
o CONFIG_KMEMCHECK_SHADOW_COPY_SHIFT - ``CONFIG_KMEMCHECK_SHADOW_COPY_SHIFT``
Select the number of shadow bytes to save along with each entry of the Select the number of shadow bytes to save along with each entry of the
error-report queue. These bytes indicate what parts of an allocation error-report queue. These bytes indicate what parts of an allocation
are initialized, uninitialized, etc. and will be displayed when an are initialized, uninitialized, etc. and will be displayed when an
...@@ -161,8 +139,7 @@ a description of the kmemcheck configuration variables: ...@@ -161,8 +139,7 @@ a description of the kmemcheck configuration variables:
The default value should be fine for debugging most problems. It also The default value should be fine for debugging most problems. It also
fits nicely within 80 columns. fits nicely within 80 columns.
o CONFIG_KMEMCHECK_PARTIAL_OK - ``CONFIG_KMEMCHECK_PARTIAL_OK``
This option (when enabled) works around certain GCC optimizations that This option (when enabled) works around certain GCC optimizations that
produce 32-bit reads from 16-bit variables where the upper 16 bits are produce 32-bit reads from 16-bit variables where the upper 16 bits are
thrown away afterwards. thrown away afterwards.
...@@ -171,8 +148,7 @@ a description of the kmemcheck configuration variables: ...@@ -171,8 +148,7 @@ a description of the kmemcheck configuration variables:
some real errors, but disabling it would probably produce a lot of some real errors, but disabling it would probably produce a lot of
false positives. false positives.
o CONFIG_KMEMCHECK_BITOPS_OK - ``CONFIG_KMEMCHECK_BITOPS_OK``
This option silences warnings that would be generated for bit-field This option silences warnings that would be generated for bit-field
accesses where not all the bits are initialized at the same time. This accesses where not all the bits are initialized at the same time. This
may also hide some real bugs. may also hide some real bugs.
...@@ -184,36 +160,36 @@ a description of the kmemcheck configuration variables: ...@@ -184,36 +160,36 @@ a description of the kmemcheck configuration variables:
Now compile the kernel as usual. Now compile the kernel as usual.
3. How to use How to use
============= ----------
3.1. Booting Booting
============ ~~~~~~~
First some information about the command-line options. There is only one First some information about the command-line options. There is only one
option specific to kmemcheck, and this is called "kmemcheck". It can be used option specific to kmemcheck, and this is called "kmemcheck". It can be used
to override the default mode as chosen by the CONFIG_KMEMCHECK_*_BY_DEFAULT to override the default mode as chosen by the ``CONFIG_KMEMCHECK_*_BY_DEFAULT``
option. Its possible settings are: option. Its possible settings are:
o kmemcheck=0 (disabled) - ``kmemcheck=0`` (disabled)
o kmemcheck=1 (enabled) - ``kmemcheck=1`` (enabled)
o kmemcheck=2 (one-shot mode) - ``kmemcheck=2`` (one-shot mode)
If SLUB debugging has been enabled in the kernel, it may take precedence over If SLUB debugging has been enabled in the kernel, it may take precedence over
kmemcheck in such a way that the slab caches which are under SLUB debugging kmemcheck in such a way that the slab caches which are under SLUB debugging
will not be tracked by kmemcheck. In order to ensure that this doesn't happen will not be tracked by kmemcheck. In order to ensure that this doesn't happen
(even though it shouldn't by default), use SLUB's boot option "slub_debug", (even though it shouldn't by default), use SLUB's boot option ``slub_debug``,
like this: slub_debug=- like this: ``slub_debug=-``
In fact, this option may also be used for fine-grained control over SLUB vs. In fact, this option may also be used for fine-grained control over SLUB vs.
kmemcheck. For example, if the command line includes "kmemcheck=1 kmemcheck. For example, if the command line includes
slub_debug=,dentry", then SLUB debugging will be used only for the "dentry" ``kmemcheck=1 slub_debug=,dentry``, then SLUB debugging will be used only
slab cache, and with kmemcheck tracking all the other caches. This is advanced for the "dentry" slab cache, and with kmemcheck tracking all the other
usage, however, and is not generally recommended. caches. This is advanced usage, however, and is not generally recommended.
3.2. Run-time enable/disable Run-time enable/disable
============================ ~~~~~~~~~~~~~~~~~~~~~~~
When the kernel has booted, it is possible to enable or disable kmemcheck at When the kernel has booted, it is possible to enable or disable kmemcheck at
run-time. WARNING: This feature is still experimental and may cause false run-time. WARNING: This feature is still experimental and may cause false
...@@ -221,48 +197,48 @@ positive warnings to appear. Therefore, try not to use this. If you find that ...@@ -221,48 +197,48 @@ positive warnings to appear. Therefore, try not to use this. If you find that
it doesn't work properly (e.g. you see an unreasonable amount of warnings), I it doesn't work properly (e.g. you see an unreasonable amount of warnings), I
will be happy to take bug reports. will be happy to take bug reports.
Use the file /proc/sys/kernel/kmemcheck for this purpose, e.g.: Use the file ``/proc/sys/kernel/kmemcheck`` for this purpose, e.g.::
$ echo 0 > /proc/sys/kernel/kmemcheck # disables kmemcheck $ echo 0 > /proc/sys/kernel/kmemcheck # disables kmemcheck
The numbers are the same as for the kmemcheck= command-line option. The numbers are the same as for the ``kmemcheck=`` command-line option.
3.3. Debugging Debugging
============== ~~~~~~~~~
A typical report will look something like this: A typical report will look something like this::
WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024)
80000000000000000000000000000000000000000088ffff0000000000000000 80000000000000000000000000000000000000000088ffff0000000000000000
i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u
^ ^
Pid: 1856, comm: ntpdate Not tainted 2.6.29-rc5 #264 945P-A Pid: 1856, comm: ntpdate Not tainted 2.6.29-rc5 #264 945P-A
RIP: 0010:[<ffffffff8104ede8>] [<ffffffff8104ede8>] __dequeue_signal+0xc8/0x190 RIP: 0010:[<ffffffff8104ede8>] [<ffffffff8104ede8>] __dequeue_signal+0xc8/0x190
RSP: 0018:ffff88003cdf7d98 EFLAGS: 00210002 RSP: 0018:ffff88003cdf7d98 EFLAGS: 00210002
RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009
RDX: ffff88003e5d6018 RSI: ffff88003e5d6024 RDI: ffff88003cdf7e84 RDX: ffff88003e5d6018 RSI: ffff88003e5d6024 RDI: ffff88003cdf7e84
RBP: ffff88003cdf7db8 R08: ffff88003e5d6000 R09: 0000000000000000 RBP: ffff88003cdf7db8 R08: ffff88003e5d6000 R09: 0000000000000000
R10: 0000000000000080 R11: 0000000000000000 R12: 000000000000000e R10: 0000000000000080 R11: 0000000000000000 R12: 000000000000000e
R13: ffff88003cdf7e78 R14: ffff88003d530710 R15: ffff88003d5a98c8 R13: ffff88003cdf7e78 R14: ffff88003d530710 R15: ffff88003d5a98c8
FS: 0000000000000000(0000) GS:ffff880001982000(0063) knlGS:00000 FS: 0000000000000000(0000) GS:ffff880001982000(0063) knlGS:00000
CS: 0010 DS: 002b ES: 002b CR0: 0000000080050033 CS: 0010 DS: 002b ES: 002b CR0: 0000000080050033
CR2: ffff88003f806ea0 CR3: 000000003c036000 CR4: 00000000000006a0 CR2: ffff88003f806ea0 CR3: 000000003c036000 CR4: 00000000000006a0
DR0: 0000000000000000 DR1: 0000000000000000 DR2: 0000000000000000 DR0: 0000000000000000 DR1: 0000000000000000 DR2: 0000000000000000
DR3: 0000000000000000 DR6: 00000000ffff4ff0 DR7: 0000000000000400 DR3: 0000000000000000 DR6: 00000000ffff4ff0 DR7: 0000000000000400
[<ffffffff8104f04e>] dequeue_signal+0x8e/0x170 [<ffffffff8104f04e>] dequeue_signal+0x8e/0x170
[<ffffffff81050bd8>] get_signal_to_deliver+0x98/0x390 [<ffffffff81050bd8>] get_signal_to_deliver+0x98/0x390
[<ffffffff8100b87d>] do_notify_resume+0xad/0x7d0 [<ffffffff8100b87d>] do_notify_resume+0xad/0x7d0
[<ffffffff8100c7b5>] int_signal+0x12/0x17 [<ffffffff8100c7b5>] int_signal+0x12/0x17
[<ffffffffffffffff>] 0xffffffffffffffff [<ffffffffffffffff>] 0xffffffffffffffff
The single most valuable information in this report is the RIP (or EIP on 32- The single most valuable information in this report is the RIP (or EIP on 32-
bit) value. This will help us pinpoint exactly which instruction that caused bit) value. This will help us pinpoint exactly which instruction that caused
the warning. the warning.
If your kernel was compiled with CONFIG_DEBUG_INFO=y, then all we have to do If your kernel was compiled with ``CONFIG_DEBUG_INFO=y``, then all we have to do
is give this address to the addr2line program, like this: is give this address to the addr2line program, like this::
$ addr2line -e vmlinux -i ffffffff8104ede8 $ addr2line -e vmlinux -i ffffffff8104ede8
arch/x86/include/asm/string_64.h:12 arch/x86/include/asm/string_64.h:12
...@@ -270,76 +246,78 @@ is give this address to the addr2line program, like this: ...@@ -270,76 +246,78 @@ is give this address to the addr2line program, like this:
kernel/signal.c:380 kernel/signal.c:380
kernel/signal.c:410 kernel/signal.c:410
The "-e vmlinux" tells addr2line which file to look in. IMPORTANT: This must The "``-e vmlinux``" tells addr2line which file to look in. **IMPORTANT:**
be the vmlinux of the kernel that produced the warning in the first place! If This must be the vmlinux of the kernel that produced the warning in the
not, the line number information will almost certainly be wrong. first place! If not, the line number information will almost certainly be
wrong.
The "-i" tells addr2line to also print the line numbers of inlined functions.
In this case, the flag was very important, because otherwise, it would only The "``-i``" tells addr2line to also print the line numbers of inlined
have printed the first line, which is just a call to memcpy(), which could be functions. In this case, the flag was very important, because otherwise,
called from a thousand places in the kernel, and is therefore not very useful. it would only have printed the first line, which is just a call to
These inlined functions would not show up in the stack trace above, simply ``memcpy()``, which could be called from a thousand places in the kernel, and
because the kernel doesn't load the extra debugging information. This is therefore not very useful. These inlined functions would not show up in
technique can of course be used with ordinary kernel oopses as well. the stack trace above, simply because the kernel doesn't load the extra
debugging information. This technique can of course be used with ordinary
In this case, it's the caller of memcpy() that is interesting, and it can be kernel oopses as well.
found in include/asm-generic/siginfo.h, line 287:
In this case, it's the caller of ``memcpy()`` that is interesting, and it can be
281 static inline void copy_siginfo(struct siginfo *to, struct siginfo *from) found in ``include/asm-generic/siginfo.h``, line 287::
282 {
283 if (from->si_code < 0) 281 static inline void copy_siginfo(struct siginfo *to, struct siginfo *from)
284 memcpy(to, from, sizeof(*to)); 282 {
285 else 283 if (from->si_code < 0)
286 /* _sigchld is currently the largest know union member */ 284 memcpy(to, from, sizeof(*to));
287 memcpy(to, from, __ARCH_SI_PREAMBLE_SIZE + sizeof(from->_sifields._sigchld)); 285 else
288 } 286 /* _sigchld is currently the largest know union member */
287 memcpy(to, from, __ARCH_SI_PREAMBLE_SIZE + sizeof(from->_sifields._sigchld));
288 }
Since this was a read (kmemcheck usually warns about reads only, though it can Since this was a read (kmemcheck usually warns about reads only, though it can
warn about writes to unallocated or freed memory as well), it was probably the warn about writes to unallocated or freed memory as well), it was probably the
"from" argument which contained some uninitialized bytes. Following the chain "from" argument which contained some uninitialized bytes. Following the chain
of calls, we move upwards to see where "from" was allocated or initialized, of calls, we move upwards to see where "from" was allocated or initialized,
kernel/signal.c, line 380: ``kernel/signal.c``, line 380::
359 static void collect_signal(int sig, struct sigpending *list, siginfo_t *info) 359 static void collect_signal(int sig, struct sigpending *list, siginfo_t *info)
360 { 360 {
... ...
367 list_for_each_entry(q, &list->list, list) { 367 list_for_each_entry(q, &list->list, list) {
368 if (q->info.si_signo == sig) { 368 if (q->info.si_signo == sig) {
369 if (first) 369 if (first)
370 goto still_pending; 370 goto still_pending;
371 first = q; 371 first = q;
... ...
377 if (first) { 377 if (first) {
378 still_pending: 378 still_pending:
379 list_del_init(&first->list); 379 list_del_init(&first->list);
380 copy_siginfo(info, &first->info); 380 copy_siginfo(info, &first->info);
381 __sigqueue_free(first); 381 __sigqueue_free(first);
... ...
392 } 392 }
393 } 393 }
Here, it is &first->info that is being passed on to copy_siginfo(). The Here, it is ``&first->info`` that is being passed on to ``copy_siginfo()``. The
variable "first" was found on a list -- passed in as the second argument to variable ``first`` was found on a list -- passed in as the second argument to
collect_signal(). We continue our journey through the stack, to figure out ``collect_signal()``. We continue our journey through the stack, to figure out
where the item on "list" was allocated or initialized. We move to line 410: where the item on "list" was allocated or initialized. We move to line 410::
395 static int __dequeue_signal(struct sigpending *pending, sigset_t *mask, 395 static int __dequeue_signal(struct sigpending *pending, sigset_t *mask,
396 siginfo_t *info) 396 siginfo_t *info)
397 { 397 {
... ...
410 collect_signal(sig, pending, info); 410 collect_signal(sig, pending, info);
... ...
414 } 414 }
Now we need to follow the "pending" pointer, since that is being passed on to Now we need to follow the ``pending`` pointer, since that is being passed on to
collect_signal() as "list". At this point, we've run out of lines from the ``collect_signal()`` as ``list``. At this point, we've run out of lines from the
"addr2line" output. Not to worry, we just paste the next addresses from the "addr2line" output. Not to worry, we just paste the next addresses from the
kmemcheck stack dump, i.e.: kmemcheck stack dump, i.e.::
[<ffffffff8104f04e>] dequeue_signal+0x8e/0x170 [<ffffffff8104f04e>] dequeue_signal+0x8e/0x170
[<ffffffff81050bd8>] get_signal_to_deliver+0x98/0x390 [<ffffffff81050bd8>] get_signal_to_deliver+0x98/0x390
[<ffffffff8100b87d>] do_notify_resume+0xad/0x7d0 [<ffffffff8100b87d>] do_notify_resume+0xad/0x7d0
[<ffffffff8100c7b5>] int_signal+0x12/0x17 [<ffffffff8100c7b5>] int_signal+0x12/0x17
$ addr2line -e vmlinux -i ffffffff8104f04e ffffffff81050bd8 \ $ addr2line -e vmlinux -i ffffffff8104f04e ffffffff81050bd8 \
ffffffff8100b87d ffffffff8100c7b5 ffffffff8100b87d ffffffff8100c7b5
...@@ -351,198 +329,199 @@ kmemcheck stack dump, i.e.: ...@@ -351,198 +329,199 @@ kmemcheck stack dump, i.e.:
Remember that since these addresses were found on the stack and not as the Remember that since these addresses were found on the stack and not as the
RIP value, they actually point to the _next_ instruction (they are return RIP value, they actually point to the _next_ instruction (they are return
addresses). This becomes obvious when we look at the code for line 446: addresses). This becomes obvious when we look at the code for line 446::
422 int dequeue_signal(struct task_struct *tsk, sigset_t *mask, siginfo_t *info) 422 int dequeue_signal(struct task_struct *tsk, sigset_t *mask, siginfo_t *info)
423 { 423 {
... ...
431 signr = __dequeue_signal(&tsk->signal->shared_pending, 431 signr = __dequeue_signal(&tsk->signal->shared_pending,
432 mask, info); 432 mask, info);
433 /* 433 /*
434 * itimer signal ? 434 * itimer signal ?
435 * 435 *
436 * itimers are process shared and we restart periodic 436 * itimers are process shared and we restart periodic
437 * itimers in the signal delivery path to prevent DoS 437 * itimers in the signal delivery path to prevent DoS
438 * attacks in the high resolution timer case. This is 438 * attacks in the high resolution timer case. This is
439 * compliant with the old way of self restarting 439 * compliant with the old way of self restarting
440 * itimers, as the SIGALRM is a legacy signal and only 440 * itimers, as the SIGALRM is a legacy signal and only
441 * queued once. Changing the restart behaviour to 441 * queued once. Changing the restart behaviour to
442 * restart the timer in the signal dequeue path is 442 * restart the timer in the signal dequeue path is
443 * reducing the timer noise on heavy loaded !highres 443 * reducing the timer noise on heavy loaded !highres
444 * systems too. 444 * systems too.
445 */ 445 */
446 if (unlikely(signr == SIGALRM)) { 446 if (unlikely(signr == SIGALRM)) {
... ...
489 } 489 }
So instead of looking at 446, we should be looking at 431, which is the line So instead of looking at 446, we should be looking at 431, which is the line
that executes just before 446. Here we see that what we are looking for is that executes just before 446. Here we see that what we are looking for is
&tsk->signal->shared_pending. ``&tsk->signal->shared_pending``.
Our next task is now to figure out which function that puts items on this Our next task is now to figure out which function that puts items on this
"shared_pending" list. A crude, but efficient tool, is git grep: ``shared_pending`` list. A crude, but efficient tool, is ``git grep``::
$ git grep -n 'shared_pending' kernel/ $ git grep -n 'shared_pending' kernel/
... ...
kernel/signal.c:828: pending = group ? &t->signal->shared_pending : &t->pending; kernel/signal.c:828: pending = group ? &t->signal->shared_pending : &t->pending;
kernel/signal.c:1339: pending = group ? &t->signal->shared_pending : &t->pending; kernel/signal.c:1339: pending = group ? &t->signal->shared_pending : &t->pending;
... ...
There were more results, but none of them were related to list operations, There were more results, but none of them were related to list operations,
and these were the only assignments. We inspect the line numbers more closely and these were the only assignments. We inspect the line numbers more closely
and find that this is indeed where items are being added to the list: and find that this is indeed where items are being added to the list::
816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t, 816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t,
817 int group) 817 int group)
818 { 818 {
... ...
828 pending = group ? &t->signal->shared_pending : &t->pending; 828 pending = group ? &t->signal->shared_pending : &t->pending;
... ...
851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && 851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN &&
852 (is_si_special(info) || 852 (is_si_special(info) ||
853 info->si_code >= 0))); 853 info->si_code >= 0)));
854 if (q) { 854 if (q) {
855 list_add_tail(&q->list, &pending->list); 855 list_add_tail(&q->list, &pending->list);
... ...
890 } 890 }
and: and::
1309 int send_sigqueue(struct sigqueue *q, struct task_struct *t, int group) 1309 int send_sigqueue(struct sigqueue *q, struct task_struct *t, int group)
1310 { 1310 {
.... ....
1339 pending = group ? &t->signal->shared_pending : &t->pending; 1339 pending = group ? &t->signal->shared_pending : &t->pending;
1340 list_add_tail(&q->list, &pending->list); 1340 list_add_tail(&q->list, &pending->list);
.... ....
1347 } 1347 }
In the first case, the list element we are looking for, "q", is being returned In the first case, the list element we are looking for, ``q``, is being
from the function __sigqueue_alloc(), which looks like an allocation function. returned from the function ``__sigqueue_alloc()``, which looks like an
Let's take a look at it: allocation function. Let's take a look at it::
187 static struct sigqueue *__sigqueue_alloc(struct task_struct *t, gfp_t flags, 187 static struct sigqueue *__sigqueue_alloc(struct task_struct *t, gfp_t flags,
188 int override_rlimit) 188 int override_rlimit)
189 { 189 {
190 struct sigqueue *q = NULL; 190 struct sigqueue *q = NULL;
191 struct user_struct *user; 191 struct user_struct *user;
192 192
193 /* 193 /*
194 * We won't get problems with the target's UID changing under us 194 * We won't get problems with the target's UID changing under us
195 * because changing it requires RCU be used, and if t != current, the 195 * because changing it requires RCU be used, and if t != current, the
196 * caller must be holding the RCU readlock (by way of a spinlock) and 196 * caller must be holding the RCU readlock (by way of a spinlock) and
197 * we use RCU protection here 197 * we use RCU protection here
198 */ 198 */
199 user = get_uid(__task_cred(t)->user); 199 user = get_uid(__task_cred(t)->user);
200 atomic_inc(&user->sigpending); 200 atomic_inc(&user->sigpending);
201 if (override_rlimit || 201 if (override_rlimit ||
202 atomic_read(&user->sigpending) <= 202 atomic_read(&user->sigpending) <=
203 t->signal->rlim[RLIMIT_SIGPENDING].rlim_cur) 203 t->signal->rlim[RLIMIT_SIGPENDING].rlim_cur)
204 q = kmem_cache_alloc(sigqueue_cachep, flags); 204 q = kmem_cache_alloc(sigqueue_cachep, flags);
205 if (unlikely(q == NULL)) { 205 if (unlikely(q == NULL)) {
206 atomic_dec(&user->sigpending); 206 atomic_dec(&user->sigpending);
207 free_uid(user); 207 free_uid(user);
208 } else { 208 } else {
209 INIT_LIST_HEAD(&q->list); 209 INIT_LIST_HEAD(&q->list);
210 q->flags = 0; 210 q->flags = 0;
211 q->user = user; 211 q->user = user;
212 } 212 }
213 213
214 return q; 214 return q;
215 } 215 }
We see that this function initializes q->list, q->flags, and q->user. It seems We see that this function initializes ``q->list``, ``q->flags``, and
that now is the time to look at the definition of "struct sigqueue", e.g.: ``q->user``. It seems that now is the time to look at the definition of
``struct sigqueue``, e.g.::
14 struct sigqueue {
15 struct list_head list; 14 struct sigqueue {
16 int flags; 15 struct list_head list;
17 siginfo_t info; 16 int flags;
18 struct user_struct *user; 17 siginfo_t info;
19 }; 18 struct user_struct *user;
19 };
And, you might remember, it was a memcpy() on &first->info that caused the
warning, so this makes perfect sense. It also seems reasonable to assume that And, you might remember, it was a ``memcpy()`` on ``&first->info`` that
it is the caller of __sigqueue_alloc() that has the responsibility of filling caused the warning, so this makes perfect sense. It also seems reasonable
out (initializing) this member. to assume that it is the caller of ``__sigqueue_alloc()`` that has the
responsibility of filling out (initializing) this member.
But just which fields of the struct were uninitialized? Let's look at But just which fields of the struct were uninitialized? Let's look at
kmemcheck's report again: kmemcheck's report again::
WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024)
80000000000000000000000000000000000000000088ffff0000000000000000 80000000000000000000000000000000000000000088ffff0000000000000000
i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u
^ ^
These first two lines are the memory dump of the memory object itself, and the These first two lines are the memory dump of the memory object itself, and
shadow bytemap, respectively. The memory object itself is in this case the shadow bytemap, respectively. The memory object itself is in this case
&first->info. Just beware that the start of this dump is NOT the start of the ``&first->info``. Just beware that the start of this dump is NOT the start
object itself! The position of the caret (^) corresponds with the address of of the object itself! The position of the caret (^) corresponds with the
the read (ffff88003e4a2024). address of the read (ffff88003e4a2024).
The shadow bytemap dump legend is as follows: The shadow bytemap dump legend is as follows:
i - initialized - i: initialized
u - uninitialized - u: uninitialized
a - unallocated (memory has been allocated by the slab layer, but has not - a: unallocated (memory has been allocated by the slab layer, but has not
yet been handed off to anybody) yet been handed off to anybody)
f - freed (memory has been allocated by the slab layer, but has been freed - f: freed (memory has been allocated by the slab layer, but has been freed
by the previous owner) by the previous owner)
In order to figure out where (relative to the start of the object) the In order to figure out where (relative to the start of the object) the
uninitialized memory was located, we have to look at the disassembly. For uninitialized memory was located, we have to look at the disassembly. For
that, we'll need the RIP address again: that, we'll need the RIP address again::
RIP: 0010:[<ffffffff8104ede8>] [<ffffffff8104ede8>] __dequeue_signal+0xc8/0x190 RIP: 0010:[<ffffffff8104ede8>] [<ffffffff8104ede8>] __dequeue_signal+0xc8/0x190
$ objdump -d --no-show-raw-insn vmlinux | grep -C 8 ffffffff8104ede8: $ objdump -d --no-show-raw-insn vmlinux | grep -C 8 ffffffff8104ede8:
ffffffff8104edc8: mov %r8,0x8(%r8) ffffffff8104edc8: mov %r8,0x8(%r8)
ffffffff8104edcc: test %r10d,%r10d ffffffff8104edcc: test %r10d,%r10d
ffffffff8104edcf: js ffffffff8104ee88 <__dequeue_signal+0x168> ffffffff8104edcf: js ffffffff8104ee88 <__dequeue_signal+0x168>
ffffffff8104edd5: mov %rax,%rdx ffffffff8104edd5: mov %rax,%rdx
ffffffff8104edd8: mov $0xc,%ecx ffffffff8104edd8: mov $0xc,%ecx
ffffffff8104eddd: mov %r13,%rdi ffffffff8104eddd: mov %r13,%rdi
ffffffff8104ede0: mov $0x30,%eax ffffffff8104ede0: mov $0x30,%eax
ffffffff8104ede5: mov %rdx,%rsi ffffffff8104ede5: mov %rdx,%rsi
ffffffff8104ede8: rep movsl %ds:(%rsi),%es:(%rdi) ffffffff8104ede8: rep movsl %ds:(%rsi),%es:(%rdi)
ffffffff8104edea: test $0x2,%al ffffffff8104edea: test $0x2,%al
ffffffff8104edec: je ffffffff8104edf0 <__dequeue_signal+0xd0> ffffffff8104edec: je ffffffff8104edf0 <__dequeue_signal+0xd0>
ffffffff8104edee: movsw %ds:(%rsi),%es:(%rdi) ffffffff8104edee: movsw %ds:(%rsi),%es:(%rdi)
ffffffff8104edf0: test $0x1,%al ffffffff8104edf0: test $0x1,%al
ffffffff8104edf2: je ffffffff8104edf5 <__dequeue_signal+0xd5> ffffffff8104edf2: je ffffffff8104edf5 <__dequeue_signal+0xd5>
ffffffff8104edf4: movsb %ds:(%rsi),%es:(%rdi) ffffffff8104edf4: movsb %ds:(%rsi),%es:(%rdi)
ffffffff8104edf5: mov %r8,%rdi ffffffff8104edf5: mov %r8,%rdi
ffffffff8104edf8: callq ffffffff8104de60 <__sigqueue_free> ffffffff8104edf8: callq ffffffff8104de60 <__sigqueue_free>
As expected, it's the "rep movsl" instruction from the memcpy() that causes As expected, it's the "``rep movsl``" instruction from the ``memcpy()``
the warning. We know about REP MOVSL that it uses the register RCX to count that causes the warning. We know about ``REP MOVSL`` that it uses the register
the number of remaining iterations. By taking a look at the register dump ``RCX`` to count the number of remaining iterations. By taking a look at the
again (from the kmemcheck report), we can figure out how many bytes were left register dump again (from the kmemcheck report), we can figure out how many
to copy: bytes were left to copy::
RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009
By looking at the disassembly, we also see that %ecx is being loaded with the By looking at the disassembly, we also see that ``%ecx`` is being loaded
value $0xc just before (ffffffff8104edd8), so we are very lucky. Keep in mind with the value ``$0xc`` just before (ffffffff8104edd8), so we are very
that this is the number of iterations, not bytes. And since this is a "long" lucky. Keep in mind that this is the number of iterations, not bytes. And
operation, we need to multiply by 4 to get the number of bytes. So this means since this is a "long" operation, we need to multiply by 4 to get the
that the uninitialized value was encountered at 4 * (0xc - 0x9) = 12 bytes number of bytes. So this means that the uninitialized value was encountered
from the start of the object. at 4 * (0xc - 0x9) = 12 bytes from the start of the object.
We can now try to figure out which field of the "struct siginfo" that was not We can now try to figure out which field of the "``struct siginfo``" that
initialized. This is the beginning of the struct: was not initialized. This is the beginning of the struct::
40 typedef struct siginfo { 40 typedef struct siginfo {
41 int si_signo; 41 int si_signo;
42 int si_errno; 42 int si_errno;
43 int si_code; 43 int si_code;
44 44
45 union { 45 union {
.. ..
92 } _sifields; 92 } _sifields;
93 } siginfo_t; 93 } siginfo_t;
On 64-bit, the int is 4 bytes long, so it must the union member that has On 64-bit, the int is 4 bytes long, so it must the union member that has
not been initialized. We can verify this using gdb: not been initialized. We can verify this using gdb::
$ gdb vmlinux $ gdb vmlinux
... ...
...@@ -550,82 +529,83 @@ not been initialized. We can verify this using gdb: ...@@ -550,82 +529,83 @@ not been initialized. We can verify this using gdb:
$1 = (union {...} *) 0x10 $1 = (union {...} *) 0x10
Actually, it seems that the union member is located at offset 0x10 -- which Actually, it seems that the union member is located at offset 0x10 -- which
means that gcc has inserted 4 bytes of padding between the members si_code means that gcc has inserted 4 bytes of padding between the members ``si_code``
and _sifields. We can now get a fuller picture of the memory dump: and ``_sifields``. We can now get a fuller picture of the memory dump::
_----------------------------=> si_code _----------------------------=> si_code
/ _--------------------=> (padding) / _--------------------=> (padding)
| / _------------=> _sifields(._kill._pid) | / _------------=> _sifields(._kill._pid)
| | / _----=> _sifields(._kill._uid) | | / _----=> _sifields(._kill._uid)
| | | / | | | /
-------|-------|-------|-------| -------|-------|-------|-------|
80000000000000000000000000000000000000000088ffff0000000000000000 80000000000000000000000000000000000000000088ffff0000000000000000
i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u
This allows us to realize another important fact: si_code contains the value This allows us to realize another important fact: ``si_code`` contains the
0x80. Remember that x86 is little endian, so the first 4 bytes "80000000" are value 0x80. Remember that x86 is little endian, so the first 4 bytes
really the number 0x00000080. With a bit of research, we find that this is "80000000" are really the number 0x00000080. With a bit of research, we
actually the constant SI_KERNEL defined in include/asm-generic/siginfo.h: find that this is actually the constant ``SI_KERNEL`` defined in
``include/asm-generic/siginfo.h``::
144 #define SI_KERNEL 0x80 /* sent by the kernel from somewhere */
144 #define SI_KERNEL 0x80 /* sent by the kernel from somewhere */
This macro is used in exactly one place in the x86 kernel: In send_signal()
in kernel/signal.c: This macro is used in exactly one place in the x86 kernel: In ``send_signal()``
in ``kernel/signal.c``::
816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t,
817 int group) 816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t,
818 { 817 int group)
... 818 {
828 pending = group ? &t->signal->shared_pending : &t->pending; ...
... 828 pending = group ? &t->signal->shared_pending : &t->pending;
851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && ...
852 (is_si_special(info) || 851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN &&
853 info->si_code >= 0))); 852 (is_si_special(info) ||
854 if (q) { 853 info->si_code >= 0)));
855 list_add_tail(&q->list, &pending->list); 854 if (q) {
856 switch ((unsigned long) info) { 855 list_add_tail(&q->list, &pending->list);
... 856 switch ((unsigned long) info) {
865 case (unsigned long) SEND_SIG_PRIV: ...
866 q->info.si_signo = sig; 865 case (unsigned long) SEND_SIG_PRIV:
867 q->info.si_errno = 0; 866 q->info.si_signo = sig;
868 q->info.si_code = SI_KERNEL; 867 q->info.si_errno = 0;
869 q->info.si_pid = 0; 868 q->info.si_code = SI_KERNEL;
870 q->info.si_uid = 0; 869 q->info.si_pid = 0;
871 break; 870 q->info.si_uid = 0;
... 871 break;
890 } ...
890 }
Not only does this match with the .si_code member, it also matches the place
Not only does this match with the ``.si_code`` member, it also matches the place
we found earlier when looking for where siginfo_t objects are enqueued on the we found earlier when looking for where siginfo_t objects are enqueued on the
"shared_pending" list. ``shared_pending`` list.
So to sum up: It seems that it is the padding introduced by the compiler So to sum up: It seems that it is the padding introduced by the compiler
between two struct fields that is uninitialized, and this gets reported when between two struct fields that is uninitialized, and this gets reported when
we do a memcpy() on the struct. This means that we have identified a false we do a ``memcpy()`` on the struct. This means that we have identified a false
positive warning. positive warning.
Normally, kmemcheck will not report uninitialized accesses in memcpy() calls Normally, kmemcheck will not report uninitialized accesses in ``memcpy()`` calls
when both the source and destination addresses are tracked. (Instead, we copy when both the source and destination addresses are tracked. (Instead, we copy
the shadow bytemap as well). In this case, the destination address clearly the shadow bytemap as well). In this case, the destination address clearly
was not tracked. We can dig a little deeper into the stack trace from above: was not tracked. We can dig a little deeper into the stack trace from above::
arch/x86/kernel/signal.c:805 arch/x86/kernel/signal.c:805
arch/x86/kernel/signal.c:871 arch/x86/kernel/signal.c:871
arch/x86/kernel/entry_64.S:694 arch/x86/kernel/entry_64.S:694
And we clearly see that the destination siginfo object is located on the And we clearly see that the destination siginfo object is located on the
stack: stack::
782 static void do_signal(struct pt_regs *regs) 782 static void do_signal(struct pt_regs *regs)
783 { 783 {
784 struct k_sigaction ka; 784 struct k_sigaction ka;
785 siginfo_t info; 785 siginfo_t info;
... ...
804 signr = get_signal_to_deliver(&info, &ka, regs, NULL); 804 signr = get_signal_to_deliver(&info, &ka, regs, NULL);
... ...
854 } 854 }
And this &info is what eventually gets passed to copy_siginfo() as the And this ``&info`` is what eventually gets passed to ``copy_siginfo()`` as the
destination argument. destination argument.
Now, even though we didn't find an actual error here, the example is still a Now, even though we didn't find an actual error here, the example is still a
...@@ -633,31 +613,30 @@ good one, because it shows how one would go about to find out what the report ...@@ -633,31 +613,30 @@ good one, because it shows how one would go about to find out what the report
was all about. was all about.
3.4. Annotating false positives Annotating false positives
=============================== ~~~~~~~~~~~~~~~~~~~~~~~~~~
There are a few different ways to make annotations in the source code that There are a few different ways to make annotations in the source code that
will keep kmemcheck from checking and reporting certain allocations. Here will keep kmemcheck from checking and reporting certain allocations. Here
they are: they are:
o __GFP_NOTRACK_FALSE_POSITIVE - ``__GFP_NOTRACK_FALSE_POSITIVE``
This flag can be passed to ``kmalloc()`` or ``kmem_cache_alloc()``
This flag can be passed to kmalloc() or kmem_cache_alloc() (therefore (therefore also to other functions that end up calling one of
also to other functions that end up calling one of these) to indicate these) to indicate that the allocation should not be tracked
that the allocation should not be tracked because it would lead to because it would lead to a false positive report. This is a "big
a false positive report. This is a "big hammer" way of silencing hammer" way of silencing kmemcheck; after all, even if the false
kmemcheck; after all, even if the false positive pertains to positive pertains to particular field in a struct, for example, we
particular field in a struct, for example, we will now lose the will now lose the ability to find (real) errors in other parts of
ability to find (real) errors in other parts of the same struct. the same struct.
Example: Example::
/* No warnings will ever trigger on accessing any part of x */ /* No warnings will ever trigger on accessing any part of x */
x = kmalloc(sizeof *x, GFP_KERNEL | __GFP_NOTRACK_FALSE_POSITIVE); x = kmalloc(sizeof *x, GFP_KERNEL | __GFP_NOTRACK_FALSE_POSITIVE);
o kmemcheck_bitfield_begin(name)/kmemcheck_bitfield_end(name) and - ``kmemcheck_bitfield_begin(name)``/``kmemcheck_bitfield_end(name)`` and
kmemcheck_annotate_bitfield(ptr, name) ``kmemcheck_annotate_bitfield(ptr, name)``
The first two of these three macros can be used inside struct The first two of these three macros can be used inside struct
definitions to signal, respectively, the beginning and end of a definitions to signal, respectively, the beginning and end of a
bitfield. Additionally, this will assign the bitfield a name, which bitfield. Additionally, this will assign the bitfield a name, which
...@@ -667,7 +646,7 @@ they are: ...@@ -667,7 +646,7 @@ they are:
kmemcheck_annotate_bitfield() at the point of allocation, to indicate kmemcheck_annotate_bitfield() at the point of allocation, to indicate
which parts of the allocation is part of a bitfield. which parts of the allocation is part of a bitfield.
Example: Example::
struct foo { struct foo {
int x; int x;
...@@ -685,13 +664,13 @@ they are: ...@@ -685,13 +664,13 @@ they are:
/* No warnings will trigger on accessing the bitfield of x */ /* No warnings will trigger on accessing the bitfield of x */
kmemcheck_annotate_bitfield(x, flags); kmemcheck_annotate_bitfield(x, flags);
Note that kmemcheck_annotate_bitfield() can be used even before the Note that ``kmemcheck_annotate_bitfield()`` can be used even before the
return value of kmalloc() is checked -- in other words, passing NULL return value of ``kmalloc()`` is checked -- in other words, passing NULL
as the first argument is legal (and will do nothing). as the first argument is legal (and will do nothing).
4. Reporting errors Reporting errors
=================== ----------------
As we have seen, kmemcheck will produce false positive reports. Therefore, it As we have seen, kmemcheck will produce false positive reports. Therefore, it
is not very wise to blindly post kmemcheck warnings to mailing lists and is not very wise to blindly post kmemcheck warnings to mailing lists and
...@@ -710,8 +689,8 @@ available) are of course a great help too. ...@@ -710,8 +689,8 @@ available) are of course a great help too.
Happy hacking! Happy hacking!
5. Technical description Technical description
======================== ---------------------
kmemcheck works by marking memory pages non-present. This means that whenever kmemcheck works by marking memory pages non-present. This means that whenever
somebody attempts to access the page, a page fault is generated. The page somebody attempts to access the page, a page fault is generated. The page
......
Documentation/kmemleak.txt → Documentation/dev-tools/kmemleak.rst
View file @ 02bafd96
Kernel Memory Leak Detector Kernel Memory Leak Detector
=========================== ===========================
Introduction
------------
Kmemleak provides a way of detecting possible kernel memory leaks in a Kmemleak provides a way of detecting possible kernel memory leaks in a
way similar to a tracing garbage collector way similar to a tracing garbage collector
(https://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29#Tracing_garbage_collectors), (https://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29#Tracing_garbage_collectors),
with the difference that the orphan objects are not freed but only with the difference that the orphan objects are not freed but only
reported via /sys/kernel/debug/kmemleak. A similar method is used by the reported via /sys/kernel/debug/kmemleak. A similar method is used by the
Valgrind tool (memcheck --leak-check) to detect the memory leaks in Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in
user-space applications. user-space applications.
Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390, metag and tile. Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390, metag and tile.
...@@ -19,20 +16,20 @@ Usage ...@@ -19,20 +16,20 @@ Usage
CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel
thread scans the memory every 10 minutes (by default) and prints the thread scans the memory every 10 minutes (by default) and prints the
number of new unreferenced objects found. To display the details of all number of new unreferenced objects found. To display the details of all
the possible memory leaks: the possible memory leaks::
# mount -t debugfs nodev /sys/kernel/debug/ # mount -t debugfs nodev /sys/kernel/debug/
# cat /sys/kernel/debug/kmemleak # cat /sys/kernel/debug/kmemleak
To trigger an intermediate memory scan: To trigger an intermediate memory scan::
# echo scan > /sys/kernel/debug/kmemleak # echo scan > /sys/kernel/debug/kmemleak
To clear the list of all current possible memory leaks: To clear the list of all current possible memory leaks::
# echo clear > /sys/kernel/debug/kmemleak # echo clear > /sys/kernel/debug/kmemleak
New leaks will then come up upon reading /sys/kernel/debug/kmemleak New leaks will then come up upon reading ``/sys/kernel/debug/kmemleak``
again. again.
Note that the orphan objects are listed in the order they were allocated Note that the orphan objects are listed in the order they were allocated
...@@ -40,22 +37,31 @@ and one object at the beginning of the list may cause other subsequent ...@@ -40,22 +37,31 @@ and one object at the beginning of the list may cause other subsequent
objects to be reported as orphan. objects to be reported as orphan.
Memory scanning parameters can be modified at run-time by writing to the Memory scanning parameters can be modified at run-time by writing to the
/sys/kernel/debug/kmemleak file. The following parameters are supported: ``/sys/kernel/debug/kmemleak`` file. The following parameters are supported:
off - disable kmemleak (irreversible) - off
stack=on - enable the task stacks scanning (default) disable kmemleak (irreversible)
stack=off - disable the tasks stacks scanning - stack=on
scan=on - start the automatic memory scanning thread (default) enable the task stacks scanning (default)
scan=off - stop the automatic memory scanning thread - stack=off
scan=<secs> - set the automatic memory scanning period in seconds disable the tasks stacks scanning
(default 600, 0 to stop the automatic scanning) - scan=on
scan - trigger a memory scan start the automatic memory scanning thread (default)
clear - clear list of current memory leak suspects, done by - scan=off
marking all current reported unreferenced objects grey, stop the automatic memory scanning thread
or free all kmemleak objects if kmemleak has been disabled. - scan=<secs>
dump=<addr> - dump information about the object found at <addr> set the automatic memory scanning period in seconds
(default 600, 0 to stop the automatic scanning)
Kmemleak can also be disabled at boot-time by passing "kmemleak=off" on - scan
trigger a memory scan
- clear
clear list of current memory leak suspects, done by
marking all current reported unreferenced objects grey,
or free all kmemleak objects if kmemleak has been disabled.
- dump=<addr>
dump information about the object found at <addr>
Kmemleak can also be disabled at boot-time by passing ``kmemleak=off`` on
the kernel command line. the kernel command line.
Memory may be allocated or freed before kmemleak is initialised and Memory may be allocated or freed before kmemleak is initialised and
...@@ -63,13 +69,14 @@ these actions are stored in an early log buffer. The size of this buffer ...@@ -63,13 +69,14 @@ these actions are stored in an early log buffer. The size of this buffer
is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option. is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option.
If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is
disabled by default. Passing "kmemleak=on" on the kernel command disabled by default. Passing ``kmemleak=on`` on the kernel command
line enables the function. line enables the function.
Basic Algorithm Basic Algorithm
--------------- ---------------
The memory allocations via kmalloc, vmalloc, kmem_cache_alloc and The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
:c:func:`kmem_cache_alloc` and
friends are traced and the pointers, together with additional friends are traced and the pointers, together with additional
information like size and stack trace, are stored in a rbtree. information like size and stack trace, are stored in a rbtree.
The corresponding freeing function calls are tracked and the pointers The corresponding freeing function calls are tracked and the pointers
...@@ -113,13 +120,13 @@ when doing development. To work around these situations you can use the ...@@ -113,13 +120,13 @@ when doing development. To work around these situations you can use the
you can find new unreferenced objects; this should help with testing you can find new unreferenced objects; this should help with testing
specific sections of code. specific sections of code.
To test a critical section on demand with a clean kmemleak do: To test a critical section on demand with a clean kmemleak do::
# echo clear > /sys/kernel/debug/kmemleak # echo clear > /sys/kernel/debug/kmemleak
... test your kernel or modules ... ... test your kernel or modules ...
# echo scan > /sys/kernel/debug/kmemleak # echo scan > /sys/kernel/debug/kmemleak
Then as usual to get your report with: Then as usual to get your report with::
# cat /sys/kernel/debug/kmemleak # cat /sys/kernel/debug/kmemleak
...@@ -131,7 +138,7 @@ disabled by the user or due to an fatal error, internal kmemleak objects ...@@ -131,7 +138,7 @@ disabled by the user or due to an fatal error, internal kmemleak objects
won't be freed when kmemleak is disabled, and those objects may occupy won't be freed when kmemleak is disabled, and those objects may occupy
a large part of physical memory. a large part of physical memory.
In this situation, you may reclaim memory with: In this situation, you may reclaim memory with::
# echo clear > /sys/kernel/debug/kmemleak # echo clear > /sys/kernel/debug/kmemleak
...@@ -140,20 +147,20 @@ Kmemleak API ...@@ -140,20 +147,20 @@ Kmemleak API
See the include/linux/kmemleak.h header for the functions prototype. See the include/linux/kmemleak.h header for the functions prototype.
kmemleak_init - initialize kmemleak - ``kmemleak_init`` - initialize kmemleak
kmemleak_alloc - notify of a memory block allocation - ``kmemleak_alloc`` - notify of a memory block allocation
kmemleak_alloc_percpu - notify of a percpu memory block allocation - ``kmemleak_alloc_percpu`` - notify of a percpu memory block allocation
kmemleak_free - notify of a memory block freeing - ``kmemleak_free`` - notify of a memory block freeing
kmemleak_free_part - notify of a partial memory block freeing - ``kmemleak_free_part`` - notify of a partial memory block freeing
kmemleak_free_percpu - notify of a percpu memory block freeing - ``kmemleak_free_percpu`` - notify of a percpu memory block freeing
kmemleak_update_trace - update object allocation stack trace - ``kmemleak_update_trace`` - update object allocation stack trace
kmemleak_not_leak - mark an object as not a leak - ``kmemleak_not_leak`` - mark an object as not a leak
kmemleak_ignore - do not scan or report an object as leak - ``kmemleak_ignore`` - do not scan or report an object as leak
kmemleak_scan_area - add scan areas inside a memory block - ``kmemleak_scan_area`` - add scan areas inside a memory block
kmemleak_no_scan - do not scan a memory block - ``kmemleak_no_scan`` - do not scan a memory block
kmemleak_erase - erase an old value in a pointer variable - ``kmemleak_erase`` - erase an old value in a pointer variable
kmemleak_alloc_recursive - as kmemleak_alloc but checks the recursiveness - ``kmemleak_alloc_recursive`` - as kmemleak_alloc but checks the recursiveness
kmemleak_free_recursive - as kmemleak_free but checks the recursiveness - ``kmemleak_free_recursive`` - as kmemleak_free but checks the recursiveness
Dealing with false positives/negatives Dealing with false positives/negatives
-------------------------------------- --------------------------------------
......
Documentation/sparse.txt → Documentation/dev-tools/sparse.rst
View file @ 02bafd96
Copyright 2004 Linus Torvalds .. Copyright 2004 Linus Torvalds
Copyright 2004 Pavel Machek <pavel@ucw.cz> .. Copyright 2004 Pavel Machek <pavel@ucw.cz>
Copyright 2006 Bob Copeland <me@bobcopeland.com> .. Copyright 2006 Bob Copeland <me@bobcopeland.com>
Sparse
======
Sparse is a semantic checker for C programs; it can be used to find a
number of potential problems with kernel code. See
https://lwn.net/Articles/689907/ for an overview of sparse; this document
contains some kernel-specific sparse information.
Using sparse for typechecking Using sparse for typechecking
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------
"__bitwise" is a type attribute, so you have to do something like this: "__bitwise" is a type attribute, so you have to do something like this::
typedef int __bitwise pm_request_t; typedef int __bitwise pm_request_t;
...@@ -20,13 +29,13 @@ but in this case we really _do_ want to force the conversion). And because ...@@ -20,13 +29,13 @@ but in this case we really _do_ want to force the conversion). And because
the enum values are all the same type, now "enum pm_request" will be that the enum values are all the same type, now "enum pm_request" will be that
type too. type too.
And with gcc, all the __bitwise/__force stuff goes away, and it all ends And with gcc, all the "__bitwise"/"__force stuff" goes away, and it all
up looking just like integers to gcc. ends up looking just like integers to gcc.
Quite frankly, you don't need the enum there. The above all really just Quite frankly, you don't need the enum there. The above all really just
boils down to one special "int __bitwise" type. boils down to one special "int __bitwise" type.
So the simpler way is to just do So the simpler way is to just do::
typedef int __bitwise pm_request_t; typedef int __bitwise pm_request_t;
...@@ -50,7 +59,7 @@ __bitwise - noisy stuff; in particular, __le*/__be* are that. We really ...@@ -50,7 +59,7 @@ __bitwise - noisy stuff; in particular, __le*/__be* are that. We really
don't want to drown in noise unless we'd explicitly asked for it. don't want to drown in noise unless we'd explicitly asked for it.
Using sparse for lock checking Using sparse for lock checking
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------
The following macros are undefined for gcc and defined during a sparse The following macros are undefined for gcc and defined during a sparse
run to use the "context" tracking feature of sparse, applied to run to use the "context" tracking feature of sparse, applied to
...@@ -69,22 +78,22 @@ annotation is needed. The tree annotations above are for cases where ...@@ -69,22 +78,22 @@ annotation is needed. The tree annotations above are for cases where
sparse would otherwise report a context imbalance. sparse would otherwise report a context imbalance.
Getting sparse Getting sparse
~~~~~~~~~~~~~~ --------------
You can get latest released versions from the Sparse homepage at You can get latest released versions from the Sparse homepage at
https://sparse.wiki.kernel.org/index.php/Main_Page https://sparse.wiki.kernel.org/index.php/Main_Page
Alternatively, you can get snapshots of the latest development version Alternatively, you can get snapshots of the latest development version
of sparse using git to clone.. of sparse using git to clone::
git://git.kernel.org/pub/scm/devel/sparse/sparse.git git://git.kernel.org/pub/scm/devel/sparse/sparse.git
DaveJ has hourly generated tarballs of the git tree available at.. DaveJ has hourly generated tarballs of the git tree available at::
http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ http://www.codemonkey.org.uk/projects/git-snapshots/sparse/
Once you have it, just do Once you have it, just do::
make make
make install make install
...@@ -92,7 +101,7 @@ Once you have it, just do ...@@ -92,7 +101,7 @@ Once you have it, just do
as a regular user, and it will install sparse in your ~/bin directory. as a regular user, and it will install sparse in your ~/bin directory.
Using sparse Using sparse
~~~~~~~~~~~~ ------------
Do a kernel make with "make C=1" to run sparse on all the C files that get Do a kernel make with "make C=1" to run sparse on all the C files that get
recompiled, or use "make C=2" to run sparse on the files whether they need to recompiled, or use "make C=2" to run sparse on the files whether they need to
...@@ -101,7 +110,7 @@ have already built it. ...@@ -101,7 +110,7 @@ have already built it.
The optional make variable CF can be used to pass arguments to sparse. The The optional make variable CF can be used to pass arguments to sparse. The
build system passes -Wbitwise to sparse automatically. To perform endianness build system passes -Wbitwise to sparse automatically. To perform endianness
checks, you may define __CHECK_ENDIAN__: checks, you may define __CHECK_ENDIAN__::
make C=2 CF="-D__CHECK_ENDIAN__" make C=2 CF="-D__CHECK_ENDIAN__"
......
Documentation/dev-tools/tools.rst 0 → 100644
View file @ 02bafd96
================================
Development tools for the kernel
================================
This document is a collection of documents about development tools that can
be used to work on the kernel. For now, the documents have been pulled
together without any significant effot to integrate them into a coherent
whole; patches welcome!
.. class:: toc-title
Table of contents
.. toctree::
:maxdepth: 2
coccinelle
sparse
kcov
gcov
kasan
ubsan
kmemleak
kmemcheck
gdb-kernel-debugging
Documentation/ubsan.txt → Documentation/dev-tools/ubsan.rst
View file @ 02bafd96
Undefined Behavior Sanitizer - UBSAN The Undefined Behavior Sanitizer - UBSAN
========================================
Overview
--------
UBSAN is a runtime undefined behaviour checker. UBSAN is a runtime undefined behaviour checker.
...@@ -10,11 +8,13 @@ Compiler inserts code that perform certain kinds of checks before operations ...@@ -10,11 +8,13 @@ Compiler inserts code that perform certain kinds of checks before operations
that may cause UB. If check fails (i.e. UB detected) __ubsan_handle_* that may cause UB. If check fails (i.e. UB detected) __ubsan_handle_*
function called to print error message. function called to print error message.
GCC has that feature since 4.9.x [1] (see -fsanitize=undefined option and GCC has that feature since 4.9.x [1_] (see ``-fsanitize=undefined`` option and
its suboptions). GCC 5.x has more checkers implemented [2]. its suboptions). GCC 5.x has more checkers implemented [2_].
Report example Report example
--------------- --------------
::
================================================================================ ================================================================================
UBSAN: Undefined behaviour in ../include/linux/bitops.h:110:33 UBSAN: Undefined behaviour in ../include/linux/bitops.h:110:33
...@@ -47,29 +47,33 @@ Report example ...@@ -47,29 +47,33 @@ Report example
Usage Usage
----- -----
To enable UBSAN configure kernel with: To enable UBSAN configure kernel with::
CONFIG_UBSAN=y CONFIG_UBSAN=y
and to check the entire kernel: and to check the entire kernel::
CONFIG_UBSAN_SANITIZE_ALL=y CONFIG_UBSAN_SANITIZE_ALL=y
To enable instrumentation for specific files or directories, add a line To enable instrumentation for specific files or directories, add a line
similar to the following to the respective kernel Makefile: similar to the following to the respective kernel Makefile:
For a single file (e.g. main.o): - For a single file (e.g. main.o)::
UBSAN_SANITIZE_main.o := y
UBSAN_SANITIZE_main.o := y
For all files in one directory: - For all files in one directory::
UBSAN_SANITIZE := y
UBSAN_SANITIZE := y
To exclude files from being instrumented even if To exclude files from being instrumented even if
CONFIG_UBSAN_SANITIZE_ALL=y, use: ``CONFIG_UBSAN_SANITIZE_ALL=y``, use::
UBSAN_SANITIZE_main.o := n
and::
UBSAN_SANITIZE_main.o := n UBSAN_SANITIZE := n
and:
UBSAN_SANITIZE := n
Detection of unaligned accesses controlled through the separate option - Detection of unaligned accesses controlled through the separate option -
CONFIG_UBSAN_ALIGNMENT. It's off by default on architectures that support CONFIG_UBSAN_ALIGNMENT. It's off by default on architectures that support
...@@ -80,5 +84,5 @@ reports. ...@@ -80,5 +84,5 @@ reports.
References References
---------- ----------
[1] - https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html .. _1: https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html
[2] - https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html .. _2: https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html
Documentation/development-process/1.Intro → Documentation/development-process/1.Intro.rst
View file @ 02bafd96
1: A GUIDE TO THE KERNEL DEVELOPMENT PROCESS Introdution
===========
The purpose of this document is to help developers (and their managers) Executive summary
work with the development community with a minimum of frustration. It is -----------------
an attempt to document how this community works in a way which is
accessible to those who are not intimately familiar with Linux kernel
development (or, indeed, free software development in general). While
there is some technical material here, this is very much a process-oriented
discussion which does not require a deep knowledge of kernel programming to
understand.
1.1: EXECUTIVE SUMMARY
The rest of this section covers the scope of the kernel development process The rest of this section covers the scope of the kernel development process
and the kinds of frustrations that developers and their employers can and the kinds of frustrations that developers and their employers can
...@@ -20,41 +12,41 @@ availability to users, community support in many forms, and the ability to ...@@ -20,41 +12,41 @@ availability to users, community support in many forms, and the ability to
influence the direction of kernel development. Code contributed to the influence the direction of kernel development. Code contributed to the
Linux kernel must be made available under a GPL-compatible license. Linux kernel must be made available under a GPL-compatible license.
Section 2 introduces the development process, the kernel release cycle, and :ref:`development_process` introduces the development process, the kernel
the mechanics of the merge window. The various phases in the patch release cycle, and the mechanics of the merge window. The various phases in
development, review, and merging cycle are covered. There is some the patch development, review, and merging cycle are covered. There is some
discussion of tools and mailing lists. Developers wanting to get started discussion of tools and mailing lists. Developers wanting to get started
with kernel development are encouraged to track down and fix bugs as an with kernel development are encouraged to track down and fix bugs as an
initial exercise. initial exercise.
Section 3 covers early-stage project planning, with an emphasis on :ref:`development_early_stage` covers early-stage project planning, with an
involving the development community as soon as possible. emphasis on involving the development community as soon as possible.
Section 4 is about the coding process; several pitfalls which have been :ref:`development_coding` is about the coding process; several pitfalls which
encountered by other developers are discussed. Some requirements for have been encountered by other developers are discussed. Some requirements for
patches are covered, and there is an introduction to some of the tools patches are covered, and there is an introduction to some of the tools
which can help to ensure that kernel patches are correct. which can help to ensure that kernel patches are correct.
Section 5 talks about the process of posting patches for review. To be :ref:`development_posting` talks about the process of posting patches for
taken seriously by the development community, patches must be properly review. To be taken seriously by the development community, patches must be
formatted and described, and they must be sent to the right place. properly formatted and described, and they must be sent to the right place.
Following the advice in this section should help to ensure the best Following the advice in this section should help to ensure the best
possible reception for your work. possible reception for your work.
Section 6 covers what happens after posting patches; the job is far from :ref:`development_followthrough` covers what happens after posting patches; the
done at that point. Working with reviewers is a crucial part of the job is far from done at that point. Working with reviewers is a crucial part
development process; this section offers a number of tips on how to avoid of the development process; this section offers a number of tips on how to
problems at this important stage. Developers are cautioned against avoid problems at this important stage. Developers are cautioned against
assuming that the job is done when a patch is merged into the mainline. assuming that the job is done when a patch is merged into the mainline.
Section 7 introduces a couple of "advanced" topics: managing patches with :ref:`development_advancedtopics` introduces a couple of "advanced" topics:
git and reviewing patches posted by others. managing patches with git and reviewing patches posted by others.
Section 8 concludes the document with pointers to sources for more
information on kernel development.
:ref:`development_conclusion` concludes the document with pointers to sources
for more information on kernel development.
1.2: WHAT THIS DOCUMENT IS ABOUT What this document is about
---------------------------
The Linux kernel, at over 8 million lines of code and well over 1000 The Linux kernel, at over 8 million lines of code and well over 1000
contributors to each release, is one of the largest and most active free contributors to each release, is one of the largest and most active free
...@@ -108,8 +100,8 @@ community is always in need of developers who will help to make the kernel ...@@ -108,8 +100,8 @@ community is always in need of developers who will help to make the kernel
better; the following text should help you - or those who work for you - better; the following text should help you - or those who work for you -
join our community. join our community.
Credits
1.3: CREDITS -------
This document was written by Jonathan Corbet, corbet@lwn.net. It has been This document was written by Jonathan Corbet, corbet@lwn.net. It has been
improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
...@@ -120,8 +112,8 @@ Jochen Voß. ...@@ -120,8 +112,8 @@ Jochen Voß.
This work was supported by the Linux Foundation; thanks especially to This work was supported by the Linux Foundation; thanks especially to
Amanda McPherson, who saw the value of this effort and made it all happen. Amanda McPherson, who saw the value of this effort and made it all happen.
The importance of getting code into the mainline
1.4: THE IMPORTANCE OF GETTING CODE INTO THE MAINLINE ------------------------------------------------
Some companies and developers occasionally wonder why they should bother Some companies and developers occasionally wonder why they should bother
learning how to work with the kernel community and get their code into the learning how to work with the kernel community and get their code into the
...@@ -233,8 +225,8 @@ commercial life, after which a new version must be released. At that ...@@ -233,8 +225,8 @@ commercial life, after which a new version must be released. At that
point, vendors whose code is in the mainline and well maintained will be point, vendors whose code is in the mainline and well maintained will be
much better positioned to get the new product ready for market quickly. much better positioned to get the new product ready for market quickly.
Licensing
1.5: LICENSING ---------
Code is contributed to the Linux kernel under a number of licenses, but all Code is contributed to the Linux kernel under a number of licenses, but all
code must be compatible with version 2 of the GNU General Public License code must be compatible with version 2 of the GNU General Public License
......
Documentation/development-process/2.Process → Documentation/development-process/2.Process.rst
View file @ 02bafd96
2: HOW THE DEVELOPMENT PROCESS WORKS .. _development_process:
How the development process works
=================================
Linux kernel development in the early 1990's was a pretty loose affair, Linux kernel development in the early 1990's was a pretty loose affair,
with relatively small numbers of users and developers involved. With a with relatively small numbers of users and developers involved. With a
...@@ -7,19 +10,21 @@ course of one year, the kernel has since had to evolve a number of ...@@ -7,19 +10,21 @@ course of one year, the kernel has since had to evolve a number of
processes to keep development happening smoothly. A solid understanding of processes to keep development happening smoothly. A solid understanding of
how the process works is required in order to be an effective part of it. how the process works is required in order to be an effective part of it.
The big picture
2.1: THE BIG PICTURE ---------------
The kernel developers use a loosely time-based release process, with a new The kernel developers use a loosely time-based release process, with a new
major kernel release happening every two or three months. The recent major kernel release happening every two or three months. The recent
release history looks like this: release history looks like this:
====== =================
2.6.38 March 14, 2011 2.6.38 March 14, 2011
2.6.37 January 4, 2011 2.6.37 January 4, 2011
2.6.36 October 20, 2010 2.6.36 October 20, 2010
2.6.35 August 1, 2010 2.6.35 August 1, 2010
2.6.34 May 15, 2010 2.6.34 May 15, 2010
2.6.33 February 24, 2010 2.6.33 February 24, 2010
====== =================
Every 2.6.x release is a major kernel release with new features, internal Every 2.6.x release is a major kernel release with new features, internal
API changes, and more. A typical 2.6 release can contain nearly 10,000 API changes, and more. A typical 2.6 release can contain nearly 10,000
...@@ -68,6 +73,7 @@ At that point the whole process starts over again. ...@@ -68,6 +73,7 @@ At that point the whole process starts over again.
As an example, here is how the 2.6.38 development cycle went (all dates in As an example, here is how the 2.6.38 development cycle went (all dates in
2011): 2011):
============== ===============================
January 4 2.6.37 stable release January 4 2.6.37 stable release
January 18 2.6.38-rc1, merge window closes January 18 2.6.38-rc1, merge window closes
January 21 2.6.38-rc2 January 21 2.6.38-rc2
...@@ -78,6 +84,7 @@ As an example, here is how the 2.6.38 development cycle went (all dates in ...@@ -78,6 +84,7 @@ As an example, here is how the 2.6.38 development cycle went (all dates in
March 1 2.6.38-rc7 March 1 2.6.38-rc7
March 7 2.6.38-rc8 March 7 2.6.38-rc8
March 14 2.6.38 stable release March 14 2.6.38 stable release
============== ===============================
How do the developers decide when to close the development cycle and create How do the developers decide when to close the development cycle and create
the stable release? The most significant metric used is the list of the stable release? The most significant metric used is the list of
...@@ -105,11 +112,13 @@ next development kernel. Kernels will typically receive stable updates for ...@@ -105,11 +112,13 @@ next development kernel. Kernels will typically receive stable updates for
a little more than one development cycle past their initial release. So, a little more than one development cycle past their initial release. So,
for example, the 2.6.36 kernel's history looked like: for example, the 2.6.36 kernel's history looked like:
============== ===============================
October 10 2.6.36 stable release October 10 2.6.36 stable release
November 22 2.6.36.1 November 22 2.6.36.1
December 9 2.6.36.2 December 9 2.6.36.2
January 7 2.6.36.3 January 7 2.6.36.3
February 17 2.6.36.4 February 17 2.6.36.4
============== ===============================
2.6.36.4 was the final stable update for the 2.6.36 release. 2.6.36.4 was the final stable update for the 2.6.36 release.
...@@ -117,9 +126,11 @@ Some kernels are designated "long term" kernels; they will receive support ...@@ -117,9 +126,11 @@ Some kernels are designated "long term" kernels; they will receive support
for a longer period. As of this writing, the current long term kernels for a longer period. As of this writing, the current long term kernels
and their maintainers are: and their maintainers are:
====== ====================== ===========================
2.6.27 Willy Tarreau (Deep-frozen stable kernel) 2.6.27 Willy Tarreau (Deep-frozen stable kernel)
2.6.32 Greg Kroah-Hartman 2.6.32 Greg Kroah-Hartman
2.6.35 Andi Kleen (Embedded flag kernel) 2.6.35 Andi Kleen (Embedded flag kernel)
====== ====================== ===========================
The selection of a kernel for long-term support is purely a matter of a The selection of a kernel for long-term support is purely a matter of a
maintainer having the need and the time to maintain that release. There maintainer having the need and the time to maintain that release. There
...@@ -127,7 +138,8 @@ are no known plans for long-term support for any specific upcoming ...@@ -127,7 +138,8 @@ are no known plans for long-term support for any specific upcoming
release. release.
2.2: THE LIFECYCLE OF A PATCH The lifecycle of a patch
------------------------
Patches do not go directly from the developer's keyboard into the mainline Patches do not go directly from the developer's keyboard into the mainline
kernel. There is, instead, a somewhat involved (if somewhat informal) kernel. There is, instead, a somewhat involved (if somewhat informal)
...@@ -195,8 +207,8 @@ is to try to cut the process down to a single "merging into the mainline" ...@@ -195,8 +207,8 @@ is to try to cut the process down to a single "merging into the mainline"
step. This approach invariably leads to frustration for everybody step. This approach invariably leads to frustration for everybody
involved. involved.
How patches get into the Kernel
2.3: HOW PATCHES GET INTO THE KERNEL -------------------------------
There is exactly one person who can merge patches into the mainline kernel There is exactly one person who can merge patches into the mainline kernel
repository: Linus Torvalds. But, of the over 9,500 patches which went repository: Linus Torvalds. But, of the over 9,500 patches which went
...@@ -242,7 +254,8 @@ finding the right maintainer. Sending patches directly to Linus is not ...@@ -242,7 +254,8 @@ finding the right maintainer. Sending patches directly to Linus is not
normally the right way to go. normally the right way to go.
2.4: NEXT TREES Next trees
----------
The chain of subsystem trees guides the flow of patches into the kernel, The chain of subsystem trees guides the flow of patches into the kernel,
but it also raises an interesting question: what if somebody wants to look but it also raises an interesting question: what if somebody wants to look
...@@ -294,7 +307,8 @@ all patches merged during a given merge window should really have found ...@@ -294,7 +307,8 @@ all patches merged during a given merge window should really have found
their way into linux-next some time before the merge window opens. their way into linux-next some time before the merge window opens.
2.4.1: STAGING TREES Staging trees
-------------
The kernel source tree contains the drivers/staging/ directory, where The kernel source tree contains the drivers/staging/ directory, where
many sub-directories for drivers or filesystems that are on their way to many sub-directories for drivers or filesystems that are on their way to
...@@ -322,7 +336,8 @@ staging drivers. So staging is, at best, a stop on the way toward becoming ...@@ -322,7 +336,8 @@ staging drivers. So staging is, at best, a stop on the way toward becoming
a proper mainline driver. a proper mainline driver.
2.5: TOOLS Tools
-----
As can be seen from the above text, the kernel development process depends As can be seen from the above text, the kernel development process depends
heavily on the ability to herd collections of patches in various heavily on the ability to herd collections of patches in various
...@@ -368,7 +383,8 @@ upstream. For the management of certain kinds of trees (-mm, for example), ...@@ -368,7 +383,8 @@ upstream. For the management of certain kinds of trees (-mm, for example),
quilt is the best tool for the job. quilt is the best tool for the job.
2.6: MAILING LISTS Mailing lists
-------------
A great deal of Linux kernel development work is done by way of mailing A great deal of Linux kernel development work is done by way of mailing
lists. It is hard to be a fully-functioning member of the community lists. It is hard to be a fully-functioning member of the community
...@@ -436,7 +452,8 @@ filesystem, etc. subsystems. The best place to look for mailing lists is ...@@ -436,7 +452,8 @@ filesystem, etc. subsystems. The best place to look for mailing lists is
in the MAINTAINERS file packaged with the kernel source. in the MAINTAINERS file packaged with the kernel source.
2.7: GETTING STARTED WITH KERNEL DEVELOPMENT Getting started with Kernel development
---------------------------------------
Questions about how to get started with the kernel development process are Questions about how to get started with the kernel development process are
common - from both individuals and companies. Equally common are missteps common - from both individuals and companies. Equally common are missteps
...@@ -463,6 +480,8 @@ they wish for by these means. ...@@ -463,6 +480,8 @@ they wish for by these means.
Andrew Morton gives this advice for aspiring kernel developers Andrew Morton gives this advice for aspiring kernel developers
::
The #1 project for all kernel beginners should surely be "make sure The #1 project for all kernel beginners should surely be "make sure
that the kernel runs perfectly at all times on all machines which that the kernel runs perfectly at all times on all machines which
you can lay your hands on". Usually the way to do this is to work you can lay your hands on". Usually the way to do this is to work
......
Documentation/development-process/3.Early-stage → Documentation/development-process/3.Early-stage.rst
View file @ 02bafd96
3: EARLY-STAGE PLANNING .. _development_early_stage:
Early-stage planning
====================
When contemplating a Linux kernel development project, it can be tempting When contemplating a Linux kernel development project, it can be tempting
to jump right in and start coding. As with any significant project, to jump right in and start coding. As with any significant project,
...@@ -7,7 +10,8 @@ line of code is written. Some time spent in early planning and ...@@ -7,7 +10,8 @@ line of code is written. Some time spent in early planning and
communication can save far more time later on. communication can save far more time later on.
3.1: SPECIFYING THE PROBLEM Specifying the problem
----------------------
Like any engineering project, a successful kernel enhancement starts with a Like any engineering project, a successful kernel enhancement starts with a
clear description of the problem to be solved. In some cases, this step is clear description of the problem to be solved. In some cases, this step is
...@@ -64,7 +68,8 @@ answers to a short set of questions: ...@@ -64,7 +68,8 @@ answers to a short set of questions:
Only then does it make sense to start considering possible solutions. Only then does it make sense to start considering possible solutions.
3.2: EARLY DISCUSSION Early discussion
----------------
When planning a kernel development project, it makes great sense to hold When planning a kernel development project, it makes great sense to hold
discussions with the community before launching into implementation. Early discussions with the community before launching into implementation. Early
...@@ -117,7 +122,8 @@ In each of these cases, a great deal of pain and extra work could have been ...@@ -117,7 +122,8 @@ In each of these cases, a great deal of pain and extra work could have been
avoided with some early discussion with the kernel developers. avoided with some early discussion with the kernel developers.
3.3: WHO DO YOU TALK TO? Who do you talk to?
-------------------
When developers decide to take their plans public, the next question will When developers decide to take their plans public, the next question will
be: where do we start? The answer is to find the right mailing list(s) and be: where do we start? The answer is to find the right mailing list(s) and
...@@ -141,6 +147,8 @@ development project. ...@@ -141,6 +147,8 @@ development project.
The task of finding the right maintainer is sometimes challenging enough The task of finding the right maintainer is sometimes challenging enough
that the kernel developers have added a script to ease the process: that the kernel developers have added a script to ease the process:
::
.../scripts/get_maintainer.pl .../scripts/get_maintainer.pl
This script will return the current maintainer(s) for a given file or This script will return the current maintainer(s) for a given file or
...@@ -155,7 +163,8 @@ If all else fails, talking to Andrew Morton can be an effective way to ...@@ -155,7 +163,8 @@ If all else fails, talking to Andrew Morton can be an effective way to
track down a maintainer for a specific piece of code. track down a maintainer for a specific piece of code.
3.4: WHEN TO POST? When to post?
-------------
If possible, posting your plans during the early stages can only be If possible, posting your plans during the early stages can only be
helpful. Describe the problem being solved and any plans that have been helpful. Describe the problem being solved and any plans that have been
...@@ -179,7 +188,8 @@ idea. The best thing to do in this situation is to proceed, keeping the ...@@ -179,7 +188,8 @@ idea. The best thing to do in this situation is to proceed, keeping the
community informed as you go. community informed as you go.
3.5: GETTING OFFICIAL BUY-IN Getting official buy-in
-----------------------
If your work is being done in a corporate environment - as most Linux If your work is being done in a corporate environment - as most Linux
kernel work is - you must, obviously, have permission from suitably kernel work is - you must, obviously, have permission from suitably
......
Documentation/development-process/4.Coding → Documentation/development-process/4.Coding.rst
View file @ 02bafd96
4: GETTING THE CODE RIGHT .. _development_coding:
Getting the code right
======================
While there is much to be said for a solid and community-oriented design While there is much to be said for a solid and community-oriented design
process, the proof of any kernel development project is in the resulting process, the proof of any kernel development project is in the resulting
...@@ -12,9 +15,11 @@ will shift toward doing things right and the tools which can help in that ...@@ -12,9 +15,11 @@ will shift toward doing things right and the tools which can help in that
quest. quest.
4.1: PITFALLS Pitfalls
---------
* Coding style Coding style
************
The kernel has long had a standard coding style, described in The kernel has long had a standard coding style, described in
Documentation/CodingStyle. For much of that time, the policies described Documentation/CodingStyle. For much of that time, the policies described
...@@ -54,7 +59,8 @@ style (a line which becomes far less readable if split to fit within the ...@@ -54,7 +59,8 @@ style (a line which becomes far less readable if split to fit within the
80-column limit, for example), just do it. 80-column limit, for example), just do it.
* Abstraction layers Abstraction layers
******************
Computer Science professors teach students to make extensive use of Computer Science professors teach students to make extensive use of
abstraction layers in the name of flexibility and information hiding. abstraction layers in the name of flexibility and information hiding.
...@@ -87,7 +93,8 @@ implement that functionality at a higher level. There is no value in ...@@ -87,7 +93,8 @@ implement that functionality at a higher level. There is no value in
replicating the same code throughout the kernel. replicating the same code throughout the kernel.
* #ifdef and preprocessor use in general #ifdef and preprocessor use in general
**************************************
The C preprocessor seems to present a powerful temptation to some C The C preprocessor seems to present a powerful temptation to some C
programmers, who see it as a way to efficiently encode a great deal of programmers, who see it as a way to efficiently encode a great deal of
...@@ -113,7 +120,8 @@ easier to read, do not evaluate their arguments multiple times, and allow ...@@ -113,7 +120,8 @@ easier to read, do not evaluate their arguments multiple times, and allow
the compiler to perform type checking on the arguments and return value. the compiler to perform type checking on the arguments and return value.
* Inline functions Inline functions
****************
Inline functions present a hazard of their own, though. Programmers can Inline functions present a hazard of their own, though. Programmers can
become enamored of the perceived efficiency inherent in avoiding a function become enamored of the perceived efficiency inherent in avoiding a function
...@@ -137,7 +145,8 @@ placement of "inline" keywords may not just be excessive; it could also be ...@@ -137,7 +145,8 @@ placement of "inline" keywords may not just be excessive; it could also be
irrelevant. irrelevant.
* Locking Locking
*******
In May, 2006, the "Devicescape" networking stack was, with great In May, 2006, the "Devicescape" networking stack was, with great
fanfare, released under the GPL and made available for inclusion in the fanfare, released under the GPL and made available for inclusion in the
...@@ -151,7 +160,7 @@ This code showed a number of signs of having been developed behind ...@@ -151,7 +160,7 @@ This code showed a number of signs of having been developed behind
corporate doors. But one large problem in particular was that it was not corporate doors. But one large problem in particular was that it was not
designed to work on multiprocessor systems. Before this networking stack designed to work on multiprocessor systems. Before this networking stack
(now called mac80211) could be merged, a locking scheme needed to be (now called mac80211) could be merged, a locking scheme needed to be
retrofitted onto it. retrofitted onto it.
Once upon a time, Linux kernel code could be developed without thinking Once upon a time, Linux kernel code could be developed without thinking
about the concurrency issues presented by multiprocessor systems. Now, about the concurrency issues presented by multiprocessor systems. Now,
...@@ -169,7 +178,8 @@ enough to pick the right tool for the job. Code which shows a lack of ...@@ -169,7 +178,8 @@ enough to pick the right tool for the job. Code which shows a lack of
attention to concurrency will have a difficult path into the mainline. attention to concurrency will have a difficult path into the mainline.
* Regressions Regressions
***********
One final hazard worth mentioning is this: it can be tempting to make a One final hazard worth mentioning is this: it can be tempting to make a
change (which may bring big improvements) which causes something to break change (which may bring big improvements) which causes something to break
...@@ -185,6 +195,8 @@ change if it brings new functionality to ten systems for each one it ...@@ -185,6 +195,8 @@ change if it brings new functionality to ten systems for each one it
breaks? The best answer to this question was expressed by Linus in July, breaks? The best answer to this question was expressed by Linus in July,
2007: 2007:
::
So we don't fix bugs by introducing new problems. That way lies So we don't fix bugs by introducing new problems. That way lies
madness, and nobody ever knows if you actually make any real madness, and nobody ever knows if you actually make any real
progress at all. Is it two steps forwards, one step back, or one progress at all. Is it two steps forwards, one step back, or one
...@@ -201,8 +213,8 @@ reason, a great deal of thought, clear documentation, and wide review for ...@@ -201,8 +213,8 @@ reason, a great deal of thought, clear documentation, and wide review for
user-space interfaces is always required. user-space interfaces is always required.
Code checking tools
4.2: CODE CHECKING TOOLS -------------------
For now, at least, the writing of error-free code remains an ideal that few For now, at least, the writing of error-free code remains an ideal that few
of us can reach. What we can hope to do, though, is to catch and fix as of us can reach. What we can hope to do, though, is to catch and fix as
...@@ -250,7 +262,7 @@ testing purposes. In particular, you should turn on: ...@@ -250,7 +262,7 @@ testing purposes. In particular, you should turn on:
There are quite a few other debugging options, some of which will be There are quite a few other debugging options, some of which will be
discussed below. Some of them have a significant performance impact and discussed below. Some of them have a significant performance impact and
should not be used all of the time. But some time spent learning the should not be used all of the time. But some time spent learning the
available options will likely be paid back many times over in short order. available options will likely be paid back many times over in short order.
One of the heavier debugging tools is the locking checker, or "lockdep." One of the heavier debugging tools is the locking checker, or "lockdep."
This tool will track the acquisition and release of every lock (spinlock or This tool will track the acquisition and release of every lock (spinlock or
...@@ -263,7 +275,7 @@ occasion, deadlock. This kind of problem can be painful (for both ...@@ -263,7 +275,7 @@ occasion, deadlock. This kind of problem can be painful (for both
developers and users) in a deployed system; lockdep allows them to be found developers and users) in a deployed system; lockdep allows them to be found
in an automated manner ahead of time. Code with any sort of non-trivial in an automated manner ahead of time. Code with any sort of non-trivial
locking should be run with lockdep enabled before being submitted for locking should be run with lockdep enabled before being submitted for
inclusion. inclusion.
As a diligent kernel programmer, you will, beyond doubt, check the return As a diligent kernel programmer, you will, beyond doubt, check the return
status of any operation (such as a memory allocation) which can fail. The status of any operation (such as a memory allocation) which can fail. The
...@@ -300,7 +312,7 @@ Documentation/coccinelle.txt for more information. ...@@ -300,7 +312,7 @@ Documentation/coccinelle.txt for more information.
Other kinds of portability errors are best found by compiling your code for Other kinds of portability errors are best found by compiling your code for
other architectures. If you do not happen to have an S/390 system or a other architectures. If you do not happen to have an S/390 system or a
Blackfin development board handy, you can still perform the compilation Blackfin development board handy, you can still perform the compilation
step. A large set of cross compilers for x86 systems can be found at step. A large set of cross compilers for x86 systems can be found at
http://www.kernel.org/pub/tools/crosstool/ http://www.kernel.org/pub/tools/crosstool/
...@@ -308,7 +320,8 @@ Some time spent installing and using these compilers will help avoid ...@@ -308,7 +320,8 @@ Some time spent installing and using these compilers will help avoid
embarrassment later. embarrassment later.
4.3: DOCUMENTATION Documentation
-------------
Documentation has often been more the exception than the rule with kernel Documentation has often been more the exception than the rule with kernel
development. Even so, adequate documentation will help to ease the merging development. Even so, adequate documentation will help to ease the merging
...@@ -364,7 +377,8 @@ out. Anything which might tempt a code janitor to make an incorrect ...@@ -364,7 +377,8 @@ out. Anything which might tempt a code janitor to make an incorrect
"cleanup" needs a comment saying why it is done the way it is. And so on. "cleanup" needs a comment saying why it is done the way it is. And so on.
4.4: INTERNAL API CHANGES Internal API changes
--------------------
The binary interface provided by the kernel to user space cannot be broken The binary interface provided by the kernel to user space cannot be broken
except under the most severe circumstances. The kernel's internal except under the most severe circumstances. The kernel's internal
......
Documentation/development-process/5.Posting → Documentation/development-process/5.Posting.rst
View file @ 02bafd96
5: POSTING PATCHES .. _development_posting:
Posting patches
===============
Sooner or later, the time comes when your work is ready to be presented to Sooner or later, the time comes when your work is ready to be presented to
the community for review and, eventually, inclusion into the mainline the community for review and, eventually, inclusion into the mainline
...@@ -11,7 +14,8 @@ SubmittingDrivers, and SubmitChecklist in the kernel documentation ...@@ -11,7 +14,8 @@ SubmittingDrivers, and SubmitChecklist in the kernel documentation
directory. directory.
5.1: WHEN TO POST When to post
------------
There is a constant temptation to avoid posting patches before they are There is a constant temptation to avoid posting patches before they are
completely "ready." For simple patches, that is not a problem. If the completely "ready." For simple patches, that is not a problem. If the
...@@ -27,7 +31,8 @@ patches which are known to be half-baked, but those who do will come in ...@@ -27,7 +31,8 @@ patches which are known to be half-baked, but those who do will come in
with the idea that they can help you drive the work in the right direction. with the idea that they can help you drive the work in the right direction.
5.2: BEFORE CREATING PATCHES Before creating patches
-----------------------
There are a number of things which should be done before you consider There are a number of things which should be done before you consider
sending patches to the development community. These include: sending patches to the development community. These include:
...@@ -52,7 +57,8 @@ As a general rule, putting in some extra thought before posting code almost ...@@ -52,7 +57,8 @@ As a general rule, putting in some extra thought before posting code almost
always pays back the effort in short order. always pays back the effort in short order.
5.3: PATCH PREPARATION Patch preparation
-----------------
The preparation of patches for posting can be a surprising amount of work, The preparation of patches for posting can be a surprising amount of work,
but, once again, attempting to save time here is not generally advisable but, once again, attempting to save time here is not generally advisable
...@@ -122,7 +128,8 @@ which takes quite a bit of time and thought after the "real work" has been ...@@ -122,7 +128,8 @@ which takes quite a bit of time and thought after the "real work" has been
done. When done properly, though, it is time well spent. done. When done properly, though, it is time well spent.
5.4: PATCH FORMATTING AND CHANGELOGS Patch formatting and changelogs
-------------------------------
So now you have a perfect series of patches for posting, but the work is So now you have a perfect series of patches for posting, but the work is
not done quite yet. Each patch needs to be formatted into a message which not done quite yet. Each patch needs to be formatted into a message which
...@@ -140,6 +147,8 @@ that end, each patch will be composed of the following: ...@@ -140,6 +147,8 @@ that end, each patch will be composed of the following:
subsystem name first, followed by the purpose of the patch. For subsystem name first, followed by the purpose of the patch. For
example: example:
::
gpio: fix build on CONFIG_GPIO_SYSFS=n gpio: fix build on CONFIG_GPIO_SYSFS=n
- A blank line followed by a detailed description of the contents of the - A blank line followed by a detailed description of the contents of the
...@@ -192,6 +201,8 @@ been associated with the development of this patch. They are described in ...@@ -192,6 +201,8 @@ been associated with the development of this patch. They are described in
detail in the SubmittingPatches document; what follows here is a brief detail in the SubmittingPatches document; what follows here is a brief
summary. Each of these lines has the format: summary. Each of these lines has the format:
::
tag: Full Name <email address> optional-other-stuff tag: Full Name <email address> optional-other-stuff
The tags in common use are: The tags in common use are:
...@@ -225,7 +236,8 @@ Be careful in the addition of tags to your patches: only Cc: is appropriate ...@@ -225,7 +236,8 @@ Be careful in the addition of tags to your patches: only Cc: is appropriate
for addition without the explicit permission of the person named. for addition without the explicit permission of the person named.
5.5: SENDING THE PATCH Sending the patch
-----------------
Before you mail your patches, there are a couple of other things you should Before you mail your patches, there are a couple of other things you should
take care of: take care of:
...@@ -287,6 +299,8 @@ obvious maintainer, Andrew Morton is often the patch target of last resort. ...@@ -287,6 +299,8 @@ obvious maintainer, Andrew Morton is often the patch target of last resort.
Patches need good subject lines. The canonical format for a patch line is Patches need good subject lines. The canonical format for a patch line is
something like: something like:
::
[PATCH nn/mm] subsys: one-line description of the patch [PATCH nn/mm] subsys: one-line description of the patch
where "nn" is the ordinal number of the patch, "mm" is the total number of where "nn" is the ordinal number of the patch, "mm" is the total number of
......
Documentation/development-process/6.Followthrough → Documentation/development-process/6.Followthrough.rst
View file @ 02bafd96
6: FOLLOWTHROUGH .. _development_followthrough:
Followthrough
=============
At this point, you have followed the guidelines given so far and, with the At this point, you have followed the guidelines given so far and, with the
addition of your own engineering skills, have posted a perfect series of addition of your own engineering skills, have posted a perfect series of
...@@ -16,7 +19,8 @@ standards. A failure to participate in this process is quite likely to ...@@ -16,7 +19,8 @@ standards. A failure to participate in this process is quite likely to
prevent the inclusion of your patches into the mainline. prevent the inclusion of your patches into the mainline.
6.1: WORKING WITH REVIEWERS Working with reviewers
----------------------
A patch of any significance will result in a number of comments from other A patch of any significance will result in a number of comments from other
developers as they review the code. Working with reviewers can be, for developers as they review the code. Working with reviewers can be, for
...@@ -97,7 +101,8 @@ though, and not before all other alternatives have been explored. And bear ...@@ -97,7 +101,8 @@ though, and not before all other alternatives have been explored. And bear
in mind, of course, that he may not agree with you either. in mind, of course, that he may not agree with you either.
6.2: WHAT HAPPENS NEXT What happens next
-----------------
If a patch is considered to be a good thing to add to the kernel, and once If a patch is considered to be a good thing to add to the kernel, and once
most of the review issues have been resolved, the next step is usually most of the review issues have been resolved, the next step is usually
...@@ -177,7 +182,8 @@ it with the assumption that you will not be around to maintain it ...@@ -177,7 +182,8 @@ it with the assumption that you will not be around to maintain it
afterward. afterward.
6.3: OTHER THINGS THAT CAN HAPPEN Other things that can happen
-----------------------------
One day, you may open your mail client and see that somebody has mailed you One day, you may open your mail client and see that somebody has mailed you
a patch to your code. That is one of the advantages of having your code a patch to your code. That is one of the advantages of having your code
......
Documentation/development-process/7.AdvancedTopics → Documentation/development-process/7.AdvancedTopics.rst
View file @ 02bafd96
7: ADVANCED TOPICS .. _development_advancedtopics:
Advanced topics
===============
At this point, hopefully, you have a handle on how the development process At this point, hopefully, you have a handle on how the development process
works. There is still more to learn, however! This section will cover a works. There is still more to learn, however! This section will cover a
number of topics which can be helpful for developers wanting to become a number of topics which can be helpful for developers wanting to become a
regular part of the Linux kernel development process. regular part of the Linux kernel development process.
7.1: MANAGING PATCHES WITH GIT Managing patches with git
-------------------------
The use of distributed version control for the kernel began in early 2002, The use of distributed version control for the kernel began in early 2002,
when Linus first started playing with the proprietary BitKeeper when Linus first started playing with the proprietary BitKeeper
...@@ -114,6 +118,8 @@ radar. Kernel developers tend to get unhappy when they see that kind of ...@@ -114,6 +118,8 @@ radar. Kernel developers tend to get unhappy when they see that kind of
thing happening; putting up a git tree with unreviewed or off-topic patches thing happening; putting up a git tree with unreviewed or off-topic patches
can affect your ability to get trees pulled in the future. Quoting Linus: can affect your ability to get trees pulled in the future. Quoting Linus:
::
You can send me patches, but for me to pull a git patch from you, I You can send me patches, but for me to pull a git patch from you, I
need to know that you know what you're doing, and I need to be able need to know that you know what you're doing, and I need to be able
to trust things *without* then having to go and check every to trust things *without* then having to go and check every
...@@ -141,7 +147,8 @@ format the request as other developers expect, and will also check to be ...@@ -141,7 +147,8 @@ format the request as other developers expect, and will also check to be
sure that you have remembered to push those changes to the public server. sure that you have remembered to push those changes to the public server.
7.2: REVIEWING PATCHES Reviewing patches
-----------------
Some readers will certainly object to putting this section with "advanced Some readers will certainly object to putting this section with "advanced
topics" on the grounds that even beginning kernel developers should be topics" on the grounds that even beginning kernel developers should be
......
Documentation/development-process/8.Conclusion → Documentation/development-process/8.Conclusion.rst
View file @ 02bafd96
8: FOR MORE INFORMATION .. _development_conclusion:
For more information
====================
There are numerous sources of information on Linux kernel development and There are numerous sources of information on Linux kernel development and
related topics. First among those will always be the Documentation related topics. First among those will always be the Documentation
...@@ -47,7 +50,8 @@ Documentation for git can be found at: ...@@ -47,7 +50,8 @@ Documentation for git can be found at:
http://www.kernel.org/pub/software/scm/git/docs/user-manual.html http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
9: CONCLUSION Conclusion
==========
Congratulations to anybody who has made it through this long-winded Congratulations to anybody who has made it through this long-winded
document. Hopefully it has provided a helpful understanding of how the document. Hopefully it has provided a helpful understanding of how the
......
Documentation/development-process/conf.py 0 → 100644
View file @ 02bafd96
# -*- coding: utf-8; mode: python -*-
project = 'Linux Kernel Development Documentation'
tags.add("subproject")
latex_documents = [
('index', 'development-process.tex', 'Linux Kernel Development Documentation',
'The kernel development community', 'manual'),
]
Documentation/development-process/development-process.rst 0 → 100644
View file @ 02bafd96
.. _development_process_main:
A guide to the Kernel Development Process
=========================================
Contents:
.. toctree::
:numbered:
:maxdepth: 2
1.Intro
2.Process
3.Early-stage
4.Coding
5.Posting
6.Followthrough
7.AdvancedTopics
8.Conclusion
The purpose of this document is to help developers (and their managers)
work with the development community with a minimum of frustration. It is
an attempt to document how this community works in a way which is
accessible to those who are not intimately familiar with Linux kernel
development (or, indeed, free software development in general). While
there is some technical material here, this is very much a process-oriented
discussion which does not require a deep knowledge of kernel programming to
understand.
Documentation/development-process/index.rst 0 → 100644
View file @ 02bafd96
Linux Kernel Development Documentation
======================================
Contents:
.. toctree::
:maxdepth: 2
development-process
Documentation/docutils.conf 0 → 100644
View file @ 02bafd96
# -*- coding: utf-8 mode: conf-colon -*-
#
# docutils configuration file
# http://docutils.sourceforge.net/docs/user/config.html
[general]
halt_level: severe
\ No newline at end of file
Documentation/driver-api/basics.rst 0 → 100644
View file @ 02bafd96
Driver Basics
=============
Driver Entry and Exit points
----------------------------
.. kernel-doc:: include/linux/init.h
:internal:
Atomic and pointer manipulation
-------------------------------
.. kernel-doc:: arch/x86/include/asm/atomic.h
:internal:
Delaying, scheduling, and timer routines
----------------------------------------
.. kernel-doc:: include/linux/sched.h
:internal:
.. kernel-doc:: kernel/sched/core.c
:export:
.. kernel-doc:: kernel/sched/cpupri.c
:internal:
.. kernel-doc:: kernel/sched/fair.c
:internal:
.. kernel-doc:: include/linux/completion.h
:internal:
.. kernel-doc:: kernel/time/timer.c
:export:
Wait queues and Wake events
---------------------------
.. kernel-doc:: include/linux/wait.h
:internal:
.. kernel-doc:: kernel/sched/wait.c
:export:
High-resolution timers
----------------------
.. kernel-doc:: include/linux/ktime.h
:internal:
.. kernel-doc:: include/linux/hrtimer.h
:internal:
.. kernel-doc:: kernel/time/hrtimer.c
:export:
Workqueues and Kevents
----------------------
.. kernel-doc:: include/linux/workqueue.h
:internal:
.. kernel-doc:: kernel/workqueue.c
:export:
Internal Functions
------------------
.. kernel-doc:: kernel/exit.c
:internal:
.. kernel-doc:: kernel/signal.c
:internal:
.. kernel-doc:: include/linux/kthread.h
:internal:
.. kernel-doc:: kernel/kthread.c
:export:
Kernel objects manipulation
---------------------------
.. kernel-doc:: lib/kobject.c
:export:
Kernel utility functions
------------------------
.. kernel-doc:: include/linux/kernel.h
:internal:
.. kernel-doc:: kernel/printk/printk.c
:export:
.. kernel-doc:: kernel/panic.c
:export:
.. kernel-doc:: kernel/sys.c
:export:
.. kernel-doc:: kernel/rcu/srcu.c
:export:
.. kernel-doc:: kernel/rcu/tree.c
:export:
.. kernel-doc:: kernel/rcu/tree_plugin.h
:export:
.. kernel-doc:: kernel/rcu/update.c
:export:
Device Resource Management
--------------------------
.. kernel-doc:: drivers/base/devres.c
:export:
Documentation/driver-api/frame-buffer.rst 0 → 100644
View file @ 02bafd96
Frame Buffer Library
====================
The frame buffer drivers depend heavily on four data structures. These
structures are declared in include/linux/fb.h. They are fb_info,
fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. The last
three can be made available to and from userland.
fb_info defines the current state of a particular video card. Inside
fb_info, there exists a fb_ops structure which is a collection of
needed functions to make fbdev and fbcon work. fb_info is only visible
to the kernel.
fb_var_screeninfo is used to describe the features of a video card
that are user defined. With fb_var_screeninfo, things such as depth
and the resolution may be defined.
The next structure is fb_fix_screeninfo. This defines the properties
of a card that are created when a mode is set and can't be changed
otherwise. A good example of this is the start of the frame buffer
memory. This "locks" the address of the frame buffer memory, so that it
cannot be changed or moved.
The last structure is fb_monospecs. In the old API, there was little
importance for fb_monospecs. This allowed for forbidden things such as
setting a mode of 800x600 on a fix frequency monitor. With the new API,
fb_monospecs prevents such things, and if used correctly, can prevent a
monitor from being cooked. fb_monospecs will not be useful until
kernels 2.5.x.
Frame Buffer Memory
-------------------
.. kernel-doc:: drivers/video/fbdev/core/fbmem.c
:export:
Frame Buffer Colormap
---------------------
.. kernel-doc:: drivers/video/fbdev/core/fbcmap.c
:export:
Frame Buffer Video Mode Database
--------------------------------
.. kernel-doc:: drivers/video/fbdev/core/modedb.c
:internal:
.. kernel-doc:: drivers/video/fbdev/core/modedb.c
:export:
Frame Buffer Macintosh Video Mode Database
------------------------------------------
.. kernel-doc:: drivers/video/fbdev/macmodes.c
:export:
Frame Buffer Fonts
------------------
Refer to the file lib/fonts/fonts.c for more information.
Documentation/hsi.txt → Documentation/driver-api/hsi.rst
View file @ 02bafd96
HSI - High-speed Synchronous Serial Interface High Speed Synchronous Serial Interface (HSI)
=============================================
1. Introduction Introduction
~~~~~~~~~~~~~~~ ---------------
High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol,
that is optimized for die-level interconnect between an Application Processor that is optimized for die-level interconnect between an Application Processor
...@@ -17,25 +18,27 @@ signal can be used to wakeup the chips from standby modes. The signals are ...@@ -17,25 +18,27 @@ signal can be used to wakeup the chips from standby modes. The signals are
commonly prefixed by AC for signals going from the application die to the commonly prefixed by AC for signals going from the application die to the
cellular die and CA for signals going the other way around. cellular die and CA for signals going the other way around.
+------------+ +---------------+ ::
| Cellular | | Application |
| Die | | Die | +------------+ +---------------+
| | - - - - - - CAWAKE - - - - - - >| | | Cellular | | Application |
| T|------------ CADATA ------------>|R | | Die | | Die |
| X|------------ CAFLAG ------------>|X | | | - - - - - - CAWAKE - - - - - - >| |
| |<----------- ACREADY ------------| | | T|------------ CADATA ------------>|R |
| | | | | X|------------ CAFLAG ------------>|X |
| | | | | |<----------- ACREADY ------------| |
| |< - - - - - ACWAKE - - - - - - -| | | | | |
| R|<----------- ACDATA -------------|T | | | | |
| X|<----------- ACFLAG -------------|X | | |< - - - - - ACWAKE - - - - - - -| |
| |------------ CAREADY ----------->| | | R|<----------- ACDATA -------------|T |
| | | | | X|<----------- ACFLAG -------------|X |
| | | | | |------------ CAREADY ----------->| |
+------------+ +---------------+ | | | |
| | | |
2. HSI Subsystem in Linux +------------+ +---------------+
~~~~~~~~~~~~~~~~~~~~~~~~~
HSI Subsystem in Linux
-------------------------
In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. In the Linux kernel the hsi subsystem is supposed to be used for HSI devices.
The hsi subsystem contains drivers for hsi controllers including support for The hsi subsystem contains drivers for hsi controllers including support for
...@@ -45,31 +48,41 @@ It also contains HSI client drivers, which make use of the generic API to ...@@ -45,31 +48,41 @@ It also contains HSI client drivers, which make use of the generic API to
implement a protocol used on the HSI interface. These client drivers can implement a protocol used on the HSI interface. These client drivers can
use an arbitrary number of channels. use an arbitrary number of channels.
3. hsi-char Device hsi-char Device
~~~~~~~~~~~~~~~~~~ ------------------
Each port automatically registers a generic client driver called hsi_char, Each port automatically registers a generic client driver called hsi_char,
which provides a charecter device for userspace representing the HSI port. which provides a charecter device for userspace representing the HSI port.
It can be used to communicate via HSI from userspace. Userspace may It can be used to communicate via HSI from userspace. Userspace may
configure the hsi_char device using the following ioctl commands: configure the hsi_char device using the following ioctl commands:
* HSC_RESET: HSC_RESET
- flush the HSI port flush the HSI port
* HSC_SET_PM HSC_SET_PM
- enable or disable the client. enable or disable the client.
* HSC_SEND_BREAK HSC_SEND_BREAK
- send break send break
* HSC_SET_RX HSC_SET_RX
- set RX configuration set RX configuration
* HSC_GET_RX HSC_GET_RX
- get RX configuration get RX configuration
* HSC_SET_TX HSC_SET_TX
- set TX configuration set TX configuration
HSC_GET_TX
get TX configuration
The kernel HSI API
------------------
.. kernel-doc:: include/linux/hsi/hsi.h
:internal:
.. kernel-doc:: drivers/hsi/hsi_core.c
:export:
* HSC_GET_TX
- get TX configuration
Documentation/driver-api/i2c.rst 0 → 100644
View file @ 02bafd96
I\ :sup:`2`\ C and SMBus Subsystem
==================================
I\ :sup:`2`\ C (or without fancy typography, "I2C") is an acronym for
the "Inter-IC" bus, a simple bus protocol which is widely used where low
data rate communications suffice. Since it's also a licensed trademark,
some vendors use another name (such as "Two-Wire Interface", TWI) for
the same bus. I2C only needs two signals (SCL for clock, SDA for data),
conserving board real estate and minimizing signal quality issues. Most
I2C devices use seven bit addresses, and bus speeds of up to 400 kHz;
there's a high speed extension (3.4 MHz) that's not yet found wide use.
I2C is a multi-master bus; open drain signaling is used to arbitrate
between masters, as well as to handshake and to synchronize clocks from
slower clients.
The Linux I2C programming interfaces support only the master side of bus
interactions, not the slave side. The programming interface is
structured around two kinds of driver, and two kinds of device. An I2C
"Adapter Driver" abstracts the controller hardware; it binds to a
physical device (perhaps a PCI device or platform_device) and exposes a
:c:type:`struct i2c_adapter <i2c_adapter>` representing each
I2C bus segment it manages. On each I2C bus segment will be I2C devices
represented by a :c:type:`struct i2c_client <i2c_client>`.
Those devices will be bound to a :c:type:`struct i2c_driver
<i2c_driver>`, which should follow the standard Linux driver
model. (At this writing, a legacy model is more widely used.) There are
functions to perform various I2C protocol operations; at this writing
all such functions are usable only from task context.
The System Management Bus (SMBus) is a sibling protocol. Most SMBus
systems are also I2C conformant. The electrical constraints are tighter
for SMBus, and it standardizes particular protocol messages and idioms.
Controllers that support I2C can also support most SMBus operations, but
SMBus controllers don't support all the protocol options that an I2C
controller will. There are functions to perform various SMBus protocol
operations, either using I2C primitives or by issuing SMBus commands to
i2c_adapter devices which don't support those I2C operations.
.. kernel-doc:: include/linux/i2c.h
:internal:
.. kernel-doc:: drivers/i2c/i2c-boardinfo.c
:functions: i2c_register_board_info
.. kernel-doc:: drivers/i2c/i2c-core.c
:export:
Documentation/driver-api/index.rst 0 → 100644
View file @ 02bafd96
========================================
The Linux driver implementer's API guide
========================================
The kernel offers a wide variety of interfaces to support the development
of device drivers. This document is an only somewhat organized collection
of some of those interfaces — it will hopefully get better over time! The
available subsections can be seen below.
.. class:: toc-title
Table of contents
.. toctree::
:maxdepth: 2
basics
infrastructure
message-based
sound
frame-buffer
input
spi
i2c
hsi
miscellaneous
Documentation/driver-api/infrastructure.rst 0 → 100644
View file @ 02bafd96
Device drivers infrastructure
=============================
The Basic Device Driver-Model Structures
----------------------------------------
.. kernel-doc:: include/linux/device.h
:internal:
Device Drivers Base
-------------------
.. kernel-doc:: drivers/base/init.c
:internal:
.. kernel-doc:: drivers/base/driver.c
:export:
.. kernel-doc:: drivers/base/core.c
:export:
.. kernel-doc:: drivers/base/syscore.c
:export:
.. kernel-doc:: drivers/base/class.c
:export:
.. kernel-doc:: drivers/base/node.c
:internal:
.. kernel-doc:: drivers/base/firmware_class.c
:export:
.. kernel-doc:: drivers/base/transport_class.c
:export:
.. kernel-doc:: drivers/base/dd.c
:export:
.. kernel-doc:: include/linux/platform_device.h
:internal:
.. kernel-doc:: drivers/base/platform.c
:export:
.. kernel-doc:: drivers/base/bus.c
:export:
Buffer Sharing and Synchronization
----------------------------------
The dma-buf subsystem provides the framework for sharing buffers for
hardware (DMA) access across multiple device drivers and subsystems, and
for synchronizing asynchronous hardware access.
This is used, for example, by drm "prime" multi-GPU support, but is of
course not limited to GPU use cases.
The three main components of this are: (1) dma-buf, representing a
sg_table and exposed to userspace as a file descriptor to allow passing
between devices, (2) fence, which provides a mechanism to signal when
one device as finished access, and (3) reservation, which manages the
shared or exclusive fence(s) associated with the buffer.
dma-buf
~~~~~~~
.. kernel-doc:: drivers/dma-buf/dma-buf.c
:export:
.. kernel-doc:: include/linux/dma-buf.h
:internal:
reservation
~~~~~~~~~~~
.. kernel-doc:: drivers/dma-buf/reservation.c
:doc: Reservation Object Overview
.. kernel-doc:: drivers/dma-buf/reservation.c
:export:
.. kernel-doc:: include/linux/reservation.h
:internal:
fence
~~~~~
.. kernel-doc:: drivers/dma-buf/fence.c
:export:
.. kernel-doc:: include/linux/fence.h
:internal:
.. kernel-doc:: drivers/dma-buf/seqno-fence.c
:export:
.. kernel-doc:: include/linux/seqno-fence.h
:internal:
.. kernel-doc:: drivers/dma-buf/fence-array.c
:export:
.. kernel-doc:: include/linux/fence-array.h
:internal:
.. kernel-doc:: drivers/dma-buf/reservation.c
:export:
.. kernel-doc:: include/linux/reservation.h
:internal:
.. kernel-doc:: drivers/dma-buf/sync_file.c
:export:
.. kernel-doc:: include/linux/sync_file.h
:internal:
Device Drivers DMA Management
-----------------------------
.. kernel-doc:: drivers/base/dma-coherent.c
:export:
.. kernel-doc:: drivers/base/dma-mapping.c
:export:
Device Drivers Power Management
-------------------------------
.. kernel-doc:: drivers/base/power/main.c
:export:
Device Drivers ACPI Support
---------------------------
.. kernel-doc:: drivers/acpi/scan.c
:export:
.. kernel-doc:: drivers/acpi/scan.c
:internal:
Device drivers PnP support
--------------------------
.. kernel-doc:: drivers/pnp/core.c
:internal:
.. kernel-doc:: drivers/pnp/card.c
:export:
.. kernel-doc:: drivers/pnp/driver.c
:internal:
.. kernel-doc:: drivers/pnp/manager.c
:export:
.. kernel-doc:: drivers/pnp/support.c
:export:
Userspace IO devices
--------------------
.. kernel-doc:: drivers/uio/uio.c
:export:
.. kernel-doc:: include/linux/uio_driver.h
:internal:
Documentation/driver-api/input.rst 0 → 100644
View file @ 02bafd96
Input Subsystem
===============
Input core
----------
.. kernel-doc:: include/linux/input.h
:internal:
.. kernel-doc:: drivers/input/input.c
:export:
.. kernel-doc:: drivers/input/ff-core.c
:export:
.. kernel-doc:: drivers/input/ff-memless.c
:export:
Multitouch Library
------------------
.. kernel-doc:: include/linux/input/mt.h
:internal:
.. kernel-doc:: drivers/input/input-mt.c
:export:
Polled input devices
--------------------
.. kernel-doc:: include/linux/input-polldev.h
:internal:
.. kernel-doc:: drivers/input/input-polldev.c
:export:
Matrix keyboards/keypads
------------------------
.. kernel-doc:: include/linux/input/matrix_keypad.h
:internal:
Sparse keymap support
---------------------
.. kernel-doc:: include/linux/input/sparse-keymap.h
:internal:
.. kernel-doc:: drivers/input/sparse-keymap.c
:export:
Documentation/driver-api/message-based.rst 0 → 100644
View file @ 02bafd96
Message-based devices
=====================
Fusion message devices
----------------------
.. kernel-doc:: drivers/message/fusion/mptbase.c
:export:
.. kernel-doc:: drivers/message/fusion/mptscsih.c
:export:
Documentation/driver-api/miscellaneous.rst 0 → 100644
View file @ 02bafd96
Parallel Port Devices
=====================
.. kernel-doc:: include/linux/parport.h
:internal:
.. kernel-doc:: drivers/parport/ieee1284.c
:export:
.. kernel-doc:: drivers/parport/share.c
:export:
.. kernel-doc:: drivers/parport/daisy.c
:internal:
16x50 UART Driver
=================
.. kernel-doc:: drivers/tty/serial/serial_core.c
:export:
.. kernel-doc:: drivers/tty/serial/8250/8250_core.c
:export:
Pulse-Width Modulation (PWM)
============================
Pulse-width modulation is a modulation technique primarily used to
control power supplied to electrical devices.
The PWM framework provides an abstraction for providers and consumers of
PWM signals. A controller that provides one or more PWM signals is
registered as :c:type:`struct pwm_chip <pwm_chip>`. Providers
are expected to embed this structure in a driver-specific structure.
This structure contains fields that describe a particular chip.
A chip exposes one or more PWM signal sources, each of which exposed as
a :c:type:`struct pwm_device <pwm_device>`. Operations can be
performed on PWM devices to control the period, duty cycle, polarity and
active state of the signal.
Note that PWM devices are exclusive resources: they can always only be
used by one consumer at a time.
.. kernel-doc:: include/linux/pwm.h
:internal:
.. kernel-doc:: drivers/pwm/core.c
:export:
Documentation/driver-api/sound.rst 0 → 100644
View file @ 02bafd96
Sound Devices
=============
.. kernel-doc:: include/sound/core.h
:internal:
.. kernel-doc:: sound/sound_core.c
:export:
.. kernel-doc:: include/sound/pcm.h
:internal:
.. kernel-doc:: sound/core/pcm.c
:export:
.. kernel-doc:: sound/core/device.c
:export:
.. kernel-doc:: sound/core/info.c
:export:
.. kernel-doc:: sound/core/rawmidi.c
:export:
.. kernel-doc:: sound/core/sound.c
:export:
.. kernel-doc:: sound/core/memory.c
:export:
.. kernel-doc:: sound/core/pcm_memory.c
:export:
.. kernel-doc:: sound/core/init.c
:export:
.. kernel-doc:: sound/core/isadma.c
:export:
.. kernel-doc:: sound/core/control.c
:export:
.. kernel-doc:: sound/core/pcm_lib.c
:export:
.. kernel-doc:: sound/core/hwdep.c
:export:
.. kernel-doc:: sound/core/pcm_native.c
:export:
.. kernel-doc:: sound/core/memalloc.c
:export:
Documentation/driver-api/spi.rst 0 → 100644
View file @ 02bafd96
Serial Peripheral Interface (SPI)
=================================
SPI is the "Serial Peripheral Interface", widely used with embedded
systems because it is a simple and efficient interface: basically a
multiplexed shift register. Its three signal wires hold a clock (SCK,
often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data
line, and a "Master In, Slave Out" (MISO) data line. SPI is a full
duplex protocol; for each bit shifted out the MOSI line (one per clock)
another is shifted in on the MISO line. Those bits are assembled into
words of various sizes on the way to and from system memory. An
additional chipselect line is usually active-low (nCS); four signals are
normally used for each peripheral, plus sometimes an interrupt.
The SPI bus facilities listed here provide a generalized interface to
declare SPI busses and devices, manage them according to the standard
Linux driver model, and perform input/output operations. At this time,
only "master" side interfaces are supported, where Linux talks to SPI
peripherals and does not implement such a peripheral itself. (Interfaces
to support implementing SPI slaves would necessarily look different.)
The programming interface is structured around two kinds of driver, and
two kinds of device. A "Controller Driver" abstracts the controller
hardware, which may be as simple as a set of GPIO pins or as complex as
a pair of FIFOs connected to dual DMA engines on the other side of the
SPI shift register (maximizing throughput). Such drivers bridge between
whatever bus they sit on (often the platform bus) and SPI, and expose
the SPI side of their device as a :c:type:`struct spi_master
<spi_master>`. SPI devices are children of that master,
represented as a :c:type:`struct spi_device <spi_device>` and
manufactured from :c:type:`struct spi_board_info
<spi_board_info>` descriptors which are usually provided by
board-specific initialization code. A :c:type:`struct spi_driver
<spi_driver>` is called a "Protocol Driver", and is bound to a
spi_device using normal driver model calls.
The I/O model is a set of queued messages. Protocol drivers submit one
or more :c:type:`struct spi_message <spi_message>` objects,
which are processed and completed asynchronously. (There are synchronous
wrappers, however.) Messages are built from one or more
:c:type:`struct spi_transfer <spi_transfer>` objects, each of
which wraps a full duplex SPI transfer. A variety of protocol tweaking
options are needed, because different chips adopt very different
policies for how they use the bits transferred with SPI.
.. kernel-doc:: include/linux/spi/spi.h
:internal:
.. kernel-doc:: drivers/spi/spi.c
:functions: spi_register_board_info
.. kernel-doc:: drivers/spi/spi.c
:export:
Documentation/driver-model/device.txt
View file @ 02bafd96
...@@ -50,7 +50,7 @@ Attributes of devices can be exported by a device driver through sysfs. ...@@ -50,7 +50,7 @@ Attributes of devices can be exported by a device driver through sysfs.
Please see Documentation/filesystems/sysfs.txt for more information Please see Documentation/filesystems/sysfs.txt for more information
on how sysfs works. on how sysfs works.
As explained in Documentation/kobject.txt, device attributes must be be As explained in Documentation/kobject.txt, device attributes must be
created before the KOBJ_ADD uevent is generated. The only way to realize created before the KOBJ_ADD uevent is generated. The only way to realize
that is by defining an attribute group. that is by defining an attribute group.
......
Documentation/email-clients.txt
View file @ 02bafd96
.. _email_clients:
Email clients info for Linux Email clients info for Linux
====================================================================== ============================
Git Git
---------------------------------------------------------------------- ---
These days most developers use `git send-email` instead of regular
These days most developers use ``git send-email`` instead of regular
email clients. The man page for this is quite good. On the receiving email clients. The man page for this is quite good. On the receiving
end, maintainers use `git am` to apply the patches. end, maintainers use ``git am`` to apply the patches.
If you are new to git then send your first patch to yourself. Save it If you are new to ``git`` then send your first patch to yourself. Save it
as raw text including all the headers. Run `git am raw_email.txt` and as raw text including all the headers. Run ``git am raw_email.txt`` and
then review the changelog with `git log`. When that works then send then review the changelog with ``git log``. When that works then send
the patch to the appropriate mailing list(s). the patch to the appropriate mailing list(s).
General Preferences General Preferences
---------------------------------------------------------------------- -------------------
Patches for the Linux kernel are submitted via email, preferably as Patches for the Linux kernel are submitted via email, preferably as
inline text in the body of the email. Some maintainers accept inline text in the body of the email. Some maintainers accept
attachments, but then the attachments should have content-type attachments, but then the attachments should have content-type
"text/plain". However, attachments are generally frowned upon because ``text/plain``. However, attachments are generally frowned upon because
it makes quoting portions of the patch more difficult in the patch it makes quoting portions of the patch more difficult in the patch
review process. review process.
...@@ -25,7 +29,7 @@ Email clients that are used for Linux kernel patches should send the ...@@ -25,7 +29,7 @@ Email clients that are used for Linux kernel patches should send the
patch text untouched. For example, they should not modify or delete tabs patch text untouched. For example, they should not modify or delete tabs
or spaces, even at the beginning or end of lines. or spaces, even at the beginning or end of lines.
Don't send patches with "format=flowed". This can cause unexpected Don't send patches with ``format=flowed``. This can cause unexpected
and unwanted line breaks. and unwanted line breaks.
Don't let your email client do automatic word wrapping for you. Don't let your email client do automatic word wrapping for you.
...@@ -54,57 +58,63 @@ mailing lists. ...@@ -54,57 +58,63 @@ mailing lists.
Some email client (MUA) hints Some email client (MUA) hints
---------------------------------------------------------------------- -----------------------------
Here are some specific MUA configuration hints for editing and sending Here are some specific MUA configuration hints for editing and sending
patches for the Linux kernel. These are not meant to be complete patches for the Linux kernel. These are not meant to be complete
software package configuration summaries. software package configuration summaries.
Legend: Legend:
TUI = text-based user interface
GUI = graphical user interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - TUI = text-based user interface
- GUI = graphical user interface
Alpine (TUI) Alpine (TUI)
************
Config options: Config options:
In the "Sending Preferences" section:
- "Do Not Send Flowed Text" must be enabled In the :menuselection:`Sending Preferences` section:
- "Strip Whitespace Before Sending" must be disabled
- :menuselection:`Do Not Send Flowed Text` must be ``enabled``
- :menuselection:`Strip Whitespace Before Sending` must be ``disabled``
When composing the message, the cursor should be placed where the patch When composing the message, the cursor should be placed where the patch
should appear, and then pressing CTRL-R let you specify the patch file should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file
to insert into the message. to insert into the message.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Claws Mail (GUI) Claws Mail (GUI)
****************
Works. Some people use this successfully for patches. Works. Some people use this successfully for patches.
To insert a patch use Message->Insert File (CTRL+i) or an external editor. To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`)
or an external editor.
If the inserted patch has to be edited in the Claws composition window If the inserted patch has to be edited in the Claws composition window
"Auto wrapping" in Configuration->Preferences->Compose->Wrapping should be "Auto wrapping" in
:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be
disabled. disabled.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Evolution (GUI) Evolution (GUI)
***************
Some people use this successfully for patches. Some people use this successfully for patches.
When composing mail select: Preformat When composing mail select: Preformat
from Format->Paragraph Style->Preformatted (Ctrl-7) from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`)
or the toolbar or the toolbar
Then use: Then use:
Insert->Text File... (Alt-n x) :menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`)
to insert the patch. to insert the patch.
You can also "diff -Nru old.c new.c | xclip", select Preformat, then You can also ``diff -Nru old.c new.c | xclip``, select
paste with the middle button. :menuselection:`Preformat`, then paste with the middle button.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Kmail (GUI) Kmail (GUI)
***********
Some people use Kmail successfully for patches. Some people use Kmail successfully for patches.
...@@ -120,11 +130,12 @@ word-wrapped and you can uncheck "word wrap" without losing the existing ...@@ -120,11 +130,12 @@ word-wrapped and you can uncheck "word wrap" without losing the existing
wrapping. wrapping.
At the bottom of your email, put the commonly-used patch delimiter before At the bottom of your email, put the commonly-used patch delimiter before
inserting your patch: three hyphens (---). inserting your patch: three hyphens (``---``).
Then from the "Message" menu item, select insert file and choose your patch. Then from the :menuselection:`Message` menu item, select insert file and
choose your patch.
As an added bonus you can customise the message creation toolbar menu As an added bonus you can customise the message creation toolbar menu
and put the "insert file" icon there. and put the :menuselection:`insert file` icon there.
Make the composer window wide enough so that no lines wrap. As of Make the composer window wide enough so that no lines wrap. As of
KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending
...@@ -139,86 +150,96 @@ as inlined text will make them tricky to extract from their 7-bit encoding. ...@@ -139,86 +150,96 @@ as inlined text will make them tricky to extract from their 7-bit encoding.
If you absolutely must send patches as attachments instead of inlining If you absolutely must send patches as attachments instead of inlining
them as text, right click on the attachment and select properties, and them as text, right click on the attachment and select properties, and
highlight "Suggest automatic display" to make the attachment inlined to highlight :menuselection:`Suggest automatic display` to make the attachment
make it more viewable. inlined to make it more viewable.
When saving patches that are sent as inlined text, select the email that When saving patches that are sent as inlined text, select the email that
contains the patch from the message list pane, right click and select contains the patch from the message list pane, right click and select
"save as". You can use the whole email unmodified as a patch if it was :menuselection:`save as`. You can use the whole email unmodified as a patch
properly composed. There is no option currently to save the email when you if it was properly composed. There is no option currently to save the email
are actually viewing it in its own window -- there has been a request filed when you are actually viewing it in its own window -- there has been a request
at kmail's bugzilla and hopefully this will be addressed. Emails are saved filed at kmail's bugzilla and hopefully this will be addressed. Emails are
as read-write for user only so you will have to chmod them to make them saved as read-write for user only so you will have to chmod them to make them
group and world readable if you copy them elsewhere. group and world readable if you copy them elsewhere.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lotus Notes (GUI) Lotus Notes (GUI)
*****************
Run away from it. Run away from it.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Mutt (TUI) Mutt (TUI)
**********
Plenty of Linux developers use mutt, so it must work pretty well. Plenty of Linux developers use ``mutt``, so it must work pretty well.
Mutt doesn't come with an editor, so whatever editor you use should be Mutt doesn't come with an editor, so whatever editor you use should be
used in a way that there are no automatic linebreaks. Most editors have used in a way that there are no automatic linebreaks. Most editors have
an "insert file" option that inserts the contents of a file unaltered. an :menuselection:`insert file` option that inserts the contents of a file
unaltered.
To use ``vim`` with mutt::
To use 'vim' with mutt:
set editor="vi" set editor="vi"
If using xclip, type the command If using xclip, type the command::
:set paste :set paste
before middle button or shift-insert or use
before middle button or shift-insert or use::
:r filename :r filename
if you want to include the patch inline. if you want to include the patch inline.
(a)ttach works fine without "set paste". (a)ttach works fine without ``set paste``.
You can also generate patches with ``git format-patch`` and then use Mutt
to send them::
You can also generate patches with 'git format-patch' and then use Mutt
to send them:
$ mutt -H 0001-some-bug-fix.patch $ mutt -H 0001-some-bug-fix.patch
Config options: Config options:
It should work with default settings. It should work with default settings.
However, it's a good idea to set the "send_charset" to: However, it's a good idea to set the ``send_charset`` to::
set send_charset="us-ascii:utf-8" set send_charset="us-ascii:utf-8"
Mutt is highly customizable. Here is a minimum configuration to start Mutt is highly customizable. Here is a minimum configuration to start
using Mutt to send patches through Gmail: using Mutt to send patches through Gmail::
# .muttrc # .muttrc
# ================ IMAP ==================== # ================ IMAP ====================
set imap_user = 'yourusername@gmail.com' set imap_user = 'yourusername@gmail.com'
set imap_pass = 'yourpassword' set imap_pass = 'yourpassword'
set spoolfile = imaps://imap.gmail.com/INBOX set spoolfile = imaps://imap.gmail.com/INBOX
set folder = imaps://imap.gmail.com/ set folder = imaps://imap.gmail.com/
set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" set record="imaps://imap.gmail.com/[Gmail]/Sent Mail"
set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" set postponed="imaps://imap.gmail.com/[Gmail]/Drafts"
set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" set mbox="imaps://imap.gmail.com/[Gmail]/All Mail"
# ================ SMTP ==================== # ================ SMTP ====================
set smtp_url = "smtp://username@smtp.gmail.com:587/" set smtp_url = "smtp://username@smtp.gmail.com:587/"
set smtp_pass = $imap_pass set smtp_pass = $imap_pass
set ssl_force_tls = yes # Require encrypted connection set ssl_force_tls = yes # Require encrypted connection
# ================ Composition ==================== # ================ Composition ====================
set editor = `echo \$EDITOR` set editor = `echo \$EDITOR`
set edit_headers = yes # See the headers when editing set edit_headers = yes # See the headers when editing
set charset = UTF-8 # value of $LANG; also fallback for send_charset set charset = UTF-8 # value of $LANG; also fallback for send_charset
# Sender, email address, and sign-off line must match # Sender, email address, and sign-off line must match
unset use_domain # because joe@localhost is just embarrassing unset use_domain # because joe@localhost is just embarrassing
set realname = "YOUR NAME" set realname = "YOUR NAME"
set from = "username@gmail.com" set from = "username@gmail.com"
set use_from = yes set use_from = yes
The Mutt docs have lots more information: The Mutt docs have lots more information:
http://dev.mutt.org/trac/wiki/UseCases/Gmail http://dev.mutt.org/trac/wiki/UseCases/Gmail
http://dev.mutt.org/doc/manual.html http://dev.mutt.org/doc/manual.html
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pine (TUI) Pine (TUI)
**********
Pine has had some whitespace truncation issues in the past, but these Pine has had some whitespace truncation issues in the past, but these
should all be fixed now. should all be fixed now.
...@@ -226,12 +247,13 @@ should all be fixed now. ...@@ -226,12 +247,13 @@ should all be fixed now.
Use alpine (pine's successor) if you can. Use alpine (pine's successor) if you can.
Config options: Config options:
- quell-flowed-text is needed for recent versions
- the "no-strip-whitespace-before-send" option is needed - ``quell-flowed-text`` is needed for recent versions
- the ``no-strip-whitespace-before-send`` option is needed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sylpheed (GUI) Sylpheed (GUI)
**************
- Works well for inlining text (or using attachments). - Works well for inlining text (or using attachments).
- Allows use of an external editor. - Allows use of an external editor.
...@@ -241,50 +263,50 @@ Sylpheed (GUI) ...@@ -241,50 +263,50 @@ Sylpheed (GUI)
- Adding addresses to address book doesn't understand the display name - Adding addresses to address book doesn't understand the display name
properly. properly.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Thunderbird (GUI) Thunderbird (GUI)
*****************
Thunderbird is an Outlook clone that likes to mangle text, but there are ways Thunderbird is an Outlook clone that likes to mangle text, but there are ways
to coerce it into behaving. to coerce it into behaving.
- Allow use of an external editor: - Allow use of an external editor:
The easiest thing to do with Thunderbird and patches is to use an The easiest thing to do with Thunderbird and patches is to use an
"external editor" extension and then just use your favorite $EDITOR "external editor" extension and then just use your favorite ``$EDITOR``
for reading/merging patches into the body text. To do this, download for reading/merging patches into the body text. To do this, download
and install the extension, then add a button for it using and install the extension, then add a button for it using
View->Toolbars->Customize... and finally just click on it when in the :menuselection:`View-->Toolbars-->Customize...` and finally just click on it
Compose dialog. when in the :menuselection:`Compose` dialog.
Please note that "external editor" requires that your editor must not Please note that "external editor" requires that your editor must not
fork, or in other words, the editor must not return before closing. fork, or in other words, the editor must not return before closing.
You may have to pass additional flags or change the settings of your You may have to pass additional flags or change the settings of your
editor. Most notably if you are using gvim then you must pass the -f editor. Most notably if you are using gvim then you must pass the -f
option to gvim by putting "/usr/bin/gvim -f" (if the binary is in option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in
/usr/bin) to the text editor field in "external editor" settings. If you ``/usr/bin``) to the text editor field in :menuselection:`external editor`
are using some other editor then please read its manual to find out how settings. If you are using some other editor then please read its manual
to do this. to find out how to do this.
To beat some sense out of the internal editor, do this: To beat some sense out of the internal editor, do this:
- Edit your Thunderbird config settings so that it won't use format=flowed. - Edit your Thunderbird config settings so that it won't use ``format=flowed``.
Go to "edit->preferences->advanced->config editor" to bring up the Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up
thunderbird's registry editor. the thunderbird's registry editor.
- Set "mailnews.send_plaintext_flowed" to "false" - Set ``mailnews.send_plaintext_flowed`` to ``false``
- Set "mailnews.wraplength" from "72" to "0" - Set ``mailnews.wraplength`` from ``72`` to ``0``
- "View" > "Message Body As" > "Plain Text" - :menuselection:`View-->Message Body As-->Plain Text`
- "View" > "Character Encoding" > "Unicode (UTF-8)" - :menuselection:`View-->Character Encoding-->Unicode (UTF-8)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TkRat (GUI) TkRat (GUI)
***********
Works. Use "Insert file..." or external editor. Works. Use "Insert file..." or external editor.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gmail (Web GUI) Gmail (Web GUI)
***************
Does not work for sending patches. Does not work for sending patches.
...@@ -295,5 +317,3 @@ although tab2space problem can be solved with external editor. ...@@ -295,5 +317,3 @@ although tab2space problem can be solved with external editor.
Another problem is that Gmail will base64-encode any message that has a Another problem is that Gmail will base64-encode any message that has a
non-ASCII character. That includes things like European names. non-ASCII character. That includes things like European names.
###
Documentation/filesystems/dax.txt
View file @ 02bafd96
...@@ -123,9 +123,12 @@ The DAX code does not work correctly on architectures which have virtually ...@@ -123,9 +123,12 @@ The DAX code does not work correctly on architectures which have virtually
mapped caches such as ARM, MIPS and SPARC. mapped caches such as ARM, MIPS and SPARC.
Calling get_user_pages() on a range of user memory that has been mmaped Calling get_user_pages() on a range of user memory that has been mmaped
from a DAX file will fail as there are no 'struct page' to describe from a DAX file will fail when there are no 'struct page' to describe
those pages. This problem is being worked on. That means that O_DIRECT those pages. This problem has been addressed in some device drivers
reads/writes to those memory ranges from a non-DAX file will fail (note by adding optional struct page support for pages under the control of
that O_DIRECT reads/writes _of a DAX file_ do work, it is the memory the driver (see CONFIG_NVDIMM_PFN in drivers/nvdimm for an example of
that is being accessed that is key here). Other things that will not how to do this). In the non struct page cases O_DIRECT reads/writes to
work include RDMA, sendfile() and splice(). those memory ranges from a non-DAX file will fail (note that O_DIRECT
reads/writes _of a DAX file_ do work, it is the memory that is being
accessed that is key here). Other things that will not work in the
non struct page case include RDMA, sendfile() and splice().
Documentation/filesystems/proc.txt
View file @ 02bafd96
...@@ -145,7 +145,7 @@ Table 1-1: Process specific entries in /proc ...@@ -145,7 +145,7 @@ Table 1-1: Process specific entries in /proc
symbol the task is blocked in - or "0" if not blocked. symbol the task is blocked in - or "0" if not blocked.
pagemap Page table pagemap Page table
stack Report full stack trace, enable via CONFIG_STACKTRACE stack Report full stack trace, enable via CONFIG_STACKTRACE
smaps a extension based on maps, showing the memory consumption of smaps an extension based on maps, showing the memory consumption of
each mapping and flags associated with it each mapping and flags associated with it
numa_maps an extension based on maps, showing the memory locality and numa_maps an extension based on maps, showing the memory locality and
binding policy as well as mem usage (in pages) of each mapping. binding policy as well as mem usage (in pages) of each mapping.
......
Documentation/gpu/conf.py 0 → 100644
View file @ 02bafd96
# -*- coding: utf-8; mode: python -*-
project = "Linux GPU Driver Developer's Guide"
tags.add("subproject")
Documentation/gpu/index.rst
View file @ 02bafd96
...@@ -12,3 +12,10 @@ Linux GPU Driver Developer's Guide ...@@ -12,3 +12,10 @@ Linux GPU Driver Developer's Guide
drm-uapi drm-uapi
i915 i915
vga-switcheroo vga-switcheroo
.. only:: subproject
Indices
=======
* :ref:`genindex`
Documentation/iio/iio_configfs.txt
View file @ 02bafd96
...@@ -82,8 +82,8 @@ users to create hrtimer triggers under /config/iio/triggers/hrtimer. ...@@ -82,8 +82,8 @@ users to create hrtimer triggers under /config/iio/triggers/hrtimer.
e.g: e.g:
$ mkdir /config/triggers/hrtimer/instance1 $ mkdir /config/iio/triggers/hrtimer/instance1
$ rmdir /config/triggers/hrtimer/instance1 $ rmdir /config/iio/triggers/hrtimer/instance1
Each trigger can have one or more attributes specific to the trigger type. Each trigger can have one or more attributes specific to the trigger type.
......
Documentation/index.rst
View file @ 02bafd96
...@@ -6,22 +6,19 @@ ...@@ -6,22 +6,19 @@
Welcome to The Linux Kernel's documentation! Welcome to The Linux Kernel's documentation!
============================================ ============================================
Nothing for you to see here *yet*. Please move along.
Contents: Contents:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
kernel-documentation kernel-documentation
media/media_uapi development-process/index
media/media_kapi dev-tools/tools
media/dvb-drivers/index driver-api/index
media/v4l-drivers/index media/index
gpu/index gpu/index
Indices and tables Indices and tables
================== ==================
* :ref:`genindex` * :ref:`genindex`
* :ref:`search`
Documentation/ioctl/botching-up-ioctls.txt
View file @ 02bafd96
...@@ -34,15 +34,18 @@ will need to add a a 32-bit compat layer: ...@@ -34,15 +34,18 @@ will need to add a a 32-bit compat layer:
64-bit platforms do. So we always need padding to the natural size to get 64-bit platforms do. So we always need padding to the natural size to get
this right. this right.
* Pad the entire struct to a multiple of 64-bits - the structure size will * Pad the entire struct to a multiple of 64-bits if the structure contains
otherwise differ on 32-bit versus 64-bit. Having a different structure size 64-bit types - the structure size will otherwise differ on 32-bit versus
hurts when passing arrays of structures to the kernel, or if the kernel 64-bit. Having a different structure size hurts when passing arrays of
checks the structure size, which e.g. the drm core does. structures to the kernel, or if the kernel checks the structure size, which
e.g. the drm core does.
* Pointers are __u64, cast from/to a uintprt_t on the userspace side and * Pointers are __u64, cast from/to a uintprt_t on the userspace side and
from/to a void __user * in the kernel. Try really hard not to delay this from/to a void __user * in the kernel. Try really hard not to delay this
conversion or worse, fiddle the raw __u64 through your code since that conversion or worse, fiddle the raw __u64 through your code since that
diminishes the checking tools like sparse can provide. diminishes the checking tools like sparse can provide. The macro
u64_to_user_ptr can be used in the kernel to avoid warnings about integers
and pointres of different sizes.
Basics Basics
......
Documentation/kbuild/kconfig-language.txt
View file @ 02bafd96
...@@ -274,7 +274,44 @@ menuconfig: ...@@ -274,7 +274,44 @@ menuconfig:
This is similar to the simple config entry above, but it also gives a This is similar to the simple config entry above, but it also gives a
hint to front ends, that all suboptions should be displayed as a hint to front ends, that all suboptions should be displayed as a
separate list of options. separate list of options. To make sure all the suboptions will really
show up under the menuconfig entry and not outside of it, every item
from the <config options> list must depend on the menuconfig symbol.
In practice, this is achieved by using one of the next two constructs:
(1):
menuconfig M
if M
config C1
config C2
endif
(2):
menuconfig M
config C1
depends on M
config C2
depends on M
In the following examples (3) and (4), C1 and C2 still have the M
dependency, but will not appear under menuconfig M anymore, because
of C0, which doesn't depend on M:
(3):
menuconfig M
config C0
if M
config C1
config C2
endif
(4):
menuconfig M
config C0
config C1
depends on M
config C2
depends on M
choices: choices:
......
Documentation/kdump/kdump.txt
View file @ 02bafd96
...@@ -393,6 +393,15 @@ Notes on loading the dump-capture kernel: ...@@ -393,6 +393,15 @@ Notes on loading the dump-capture kernel:
* We generally don' have to bring up a SMP kernel just to capture the * We generally don' have to bring up a SMP kernel just to capture the
dump. Hence generally it is useful either to build a UP dump-capture dump. Hence generally it is useful either to build a UP dump-capture
kernel or specify maxcpus=1 option while loading dump-capture kernel. kernel or specify maxcpus=1 option while loading dump-capture kernel.
Note, though maxcpus always works, you had better replace it with
nr_cpus to save memory if supported by the current ARCH, such as x86.
* You should enable multi-cpu support in dump-capture kernel if you intend
to use multi-thread programs with it, such as parallel dump feature of
makedumpfile. Otherwise, the multi-thread program may have a great
performance degradation. To enable multi-cpu support, you should bring up an
SMP dump-capture kernel and specify maxcpus/nr_cpus, disable_cpu_apicid=[X]
options while loading it.
* For s390x there are two kdump modes: If a ELF header is specified with * For s390x there are two kdump modes: If a ELF header is specified with
the elfcorehdr= kernel parameter, it is used by the kdump kernel as it the elfcorehdr= kernel parameter, it is used by the kdump kernel as it
......
Documentation/kernel-docs.txt
View file @ 02bafd96
.. _kernel_docs:
Index of Documentation for People Interested in Writing and/or Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel
=============================================================================================
Understanding the Linux Kernel.
Juan-Mariano de Goyeneche <jmseyas@dit.upm.es> Juan-Mariano de Goyeneche <jmseyas@dit.upm.es>
/* The need for a document like this one became apparent in the
* The latest version of this document may be found at: linux-kernel mailing list as the same questions, asking for pointers
* http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html to information, appeared again and again.
*/
Fortunately, as more and more people get to GNU/Linux, more and more
The need for a document like this one became apparent in the get interested in the Kernel. But reading the sources is not always
linux-kernel mailing list as the same questions, asking for pointers enough. It is easy to understand the code, but miss the concepts, the
to information, appeared again and again. philosophy and design decisions behind this code.
Fortunately, as more and more people get to GNU/Linux, more and more Unfortunately, not many documents are available for beginners to
get interested in the Kernel. But reading the sources is not always start. And, even if they exist, there was no "well-known" place which
enough. It is easy to understand the code, but miss the concepts, the kept track of them. These lines try to cover this lack. All documents
philosophy and design decisions behind this code. available on line known by the author are listed, while some reference
books are also mentioned.
Unfortunately, not many documents are available for beginners to
start. And, even if they exist, there was no "well-known" place which PLEASE, if you know any paper not listed here or write a new document,
kept track of them. These lines try to cover this lack. All documents send me an e-mail, and I'll include a reference to it here. Any
available on line known by the author are listed, while some reference corrections, ideas or comments are also welcomed.
books are also mentioned.
The papers that follow are listed in no particular order. All are
PLEASE, if you know any paper not listed here or write a new document, cataloged with the following fields: the document's "Title", the
send me an e-mail, and I'll include a reference to it here. Any "Author"/s, the "URL" where they can be found, some "Keywords" helpful
corrections, ideas or comments are also welcomed. when searching for specific topics, and a brief "Description" of the
Document.
The papers that follow are listed in no particular order. All are
cataloged with the following fields: the document's "Title", the Enjoy!
"Author"/s, the "URL" where they can be found, some "Keywords" helpful
when searching for specific topics, and a brief "Description" of the .. note::
Document.
The documents on each section of this document are ordered by its
Enjoy! published date, from the newest to the oldest.
ON-LINE DOCS: Docs at the Linux Kernel tree
-----------------------------
* Title: "Linux Device Drivers, Third Edition"
Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``.
URL: http://lwn.net/Kernel/LDD3/ The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
Description: A 600-page book covering the (2.6.10) driver
programming API and kernel hacking in general. Available under the * Name: **linux/Documentation**
Creative Commons Attribution-ShareAlike 2.0 license.
:Author: Many.
* Title: "The Linux Kernel" :Location: Documentation/
Author: David A. Rusling. :Keywords: text files, Sphinx, DocBook.
URL: http://www.tldp.org/LDP/tlk/tlk.html :Description: Documentation that comes with the kernel sources,
Keywords: everything!, book. inside the Documentation directory. Some pages from this document
Description: On line, 200 pages book describing most aspects of (including this document itself) have been moved there, and might
the Linux Kernel. Probably, the first reference for beginners. be more up to date than the web version.
Lots of illustrations explaining data structures use and
relationships in the purest Richard W. Stevens' style. Contents: * Title: **The Kernel Hacking HOWTO**
"1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management,
4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI, :Author: Various Talented People, and Rusty.
7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The :Location: Documentation/DocBook/kernel-hacking.tmpl
File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules, :Keywords: HOWTO, kernel contexts, deadlock, locking, modules,
13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The symbols, return conventions.
Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU :Description: From the Introduction: "Please understand that I
General Public License, Glossary". In short: a must have. never wanted to write this document, being grossly underqualified,
but I always wanted to read it, and this was the only way. I
* Title: "Linux Device Drivers, 2nd Edition" simply explain some best practices, and give reading entry-points
Author: Alessandro Rubini and Jonathan Corbet. into the kernel sources. I avoid implementation details: that's
URL: http://www.xml.com/ldd/chapter/book/index.html what the code is for, and I ignore whole tracts of useful
Keywords: device drivers, modules, debugging, memory, hardware, routines. This document assumes familiarity with C, and an
interrupt handling, char drivers, block drivers, kmod, mmap, DMA, understanding of what the kernel is, and how it is used. It was
buses. originally written for the 2.3 kernels, but nearly all of it
Description: O'Reilly's popular book, now also on-line under the applies to 2.2 too; 2.0 is slightly different".
GNU Free Documentation License.
Notes: You can also buy it in paper-form from O'Reilly. See below * Title: **Linux Kernel Locking HOWTO**
under BOOKS (Not on-line).
:Author: Various Talented People, and Rusty.
* Title: "Conceptual Architecture of the Linux Kernel" :Location: Documentation/DocBook/kernel-locking.tmpl
Author: Ivan T. Bowman. :Keywords: locks, locking, spinlock, semaphore, atomic, race
URL: http://plg.uwaterloo.ca/ condition, bottom halves, tasklets, softirqs.
Keywords: conceptual software architecture, extracted design, :Description: The title says it all: document describing the
reverse engineering, system structure. locking system in the Linux Kernel either in uniprocessor or SMP
Description: Conceptual software architecture of the Linux kernel, systems.
automatically extracted from the source code. Very detailed. Good :Notes: "It was originally written for the later (>2.3.47) 2.3
figures. Gives good overall kernel understanding. kernels, but most of it applies to 2.2 too; 2.0 is slightly
different". Freely redistributable under the conditions of the GNU
* Title: "Concrete Architecture of the Linux Kernel" General Public License.
Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan.
URL: http://plg.uwaterloo.ca/ On-line docs
Keywords: concrete architecture, extracted design, reverse ------------
engineering, system structure, dependencies.
Description: Concrete architecture of the Linux kernel, * Title: **Linux Kernel Mailing List Glossary**
automatically extracted from the source code. Very detailed. Good
figures. Gives good overall kernel understanding. This papers :Author: various
focus on lower details than its predecessor (files, variables...). :URL: http://kernelnewbies.org/glossary/
:Date: rolling version
* Title: "Linux as a Case Study: Its Extracted Software :Keywords: glossary, terms, linux-kernel.
Architecture" :Description: From the introduction: "This glossary is intended as
Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster. a brief description of some of the acronyms and terms you may hear
URL: http://plg.uwaterloo.ca/ during discussion of the Linux kernel".
Keywords: software architecture, architecture recovery,
redocumentation. * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel**
Description: Paper appeared at ICSE'99, Los Angeles, May 16-22,
1999. A mixture of the previous two documents from the same :Author: Richard Sailer
author. :URL: https://archive.org/details/linux_kernel_data_flow_short_paper
:Date: 2016
* Title: "Overview of the Virtual File System" :Keywords: Linux Kernel Networking, TCP, tracing, ftrace
Author: Richard Gooch. :Description: A seminar paper explaining ftrace and how to use it for
URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt understanding linux kernel internals,
Keywords: VFS, File System, mounting filesystems, opening files, illustrated at tracing the way of a TCP packet through the kernel.
dentries, dcache. :Abstract: *This short paper outlines the usage of ftrace a tracing framework
Description: Brief introduction to the Linux Virtual File System. as a tool to understand a running Linux system.
What is it, how it works, operations taken when opening a file or Having obtained a trace-log a kernel hacker can read and understand
mounting a file system and description of important data source code more determined and with context.
structures explaining the purpose of each of their entries. In a detailed example this approach is demonstrated in tracing
and the way of data in a TCP Connection through the kernel.
* Title: "The Linux RAID-1, 4, 5 Code" Finally this trace-log is used as base for more a exact conceptual
Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. exploration and description of the Linux TCP/IP implementation.*
URL: http://www.linuxjournal.com/article.php?sid=2391
Keywords: RAID, MD driver. * Title: **On submitting kernel Patches**
Description: Linux Journal Kernel Korner article. Here is its
abstract: "A description of the implementation of the RAID-1, :Author: Andi Kleen
RAID-4 and RAID-5 personalities of the MD device driver in the :URL: http://halobates.de/on-submitting-kernel-patches.pdf
Linux kernel, providing users with high performance and reliable, :Date: 2008
secondary-storage capability using software". :Keywords: patches, review process, types of submissions, basic rules, case studies
:Description: This paper gives several experience values on what types of patches
* Title: "Dynamic Kernels: Modularized Device Drivers" there are and how likley they get merged.
Author: Alessandro Rubini. :Abstract:
URL: http://www.linuxjournal.com/article.php?sid=1219 [...]. This paper examines some common problems for
Keywords: device driver, module, loading/unloading modules, submitting larger changes and some strategies to avoid problems.
allocating resources.
Description: Linux Journal Kernel Korner article. Here is its * Title: **Overview of the Virtual File System**
abstract: "This is the first of a series of four articles
co-authored by Alessandro Rubini and Georg Zezchwitz which present :Author: Richard Gooch.
a practical approach to writing Linux device drivers as kernel :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt
loadable modules. This installment presents an introduction to the :Date: 2007
topic, preparing the reader to understand next month's :Keywords: VFS, File System, mounting filesystems, opening files,
installment". dentries, dcache.
:Description: Brief introduction to the Linux Virtual File System.
* Title: "Dynamic Kernels: Discovery" What is it, how it works, operations taken when opening a file or
Author: Alessandro Rubini. mounting a file system and description of important data
URL: http://www.linuxjournal.com/article.php?sid=1220 structures explaining the purpose of each of their entries.
Keywords: character driver, init_module, clean_up module,
autodetection, mayor number, minor number, file operations, * Title: **Linux Device Drivers, Third Edition**
open(), close().
Description: Linux Journal Kernel Korner article. Here is its :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
abstract: "This article, the second of four, introduces part of :URL: http://lwn.net/Kernel/LDD3/
the actual code to create custom module implementing a character :Date: 2005
device driver. It describes the code for module initialization and :Description: A 600-page book covering the (2.6.10) driver
cleanup, as well as the open() and close() system calls". programming API and kernel hacking in general. Available under the
Creative Commons Attribution-ShareAlike 2.0 license.
* Title: "The Devil's in the Details" :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere <ldd3_published>`.
Author: Georg v. Zezschwitz and Alessandro Rubini.
URL: http://www.linuxjournal.com/article.php?sid=1221 * Title: **Writing an ALSA Driver**
Keywords: read(), write(), select(), ioctl(), blocking/non
blocking mode, interrupt handler. :Author: Takashi Iwai <tiwai@suse.de>
Description: Linux Journal Kernel Korner article. Here is its :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html
abstract: "This article, the third of four on writing character :Date: 2005
device drivers, introduces concepts of reading, writing, and using :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware.
ioctl-calls". :Description: Advanced Linux Sound Architecture for developers,
both at kernel and user-level sides. ALSA is the Linux kernel
* Title: "Dissecting Interrupts and Browsing DMA" sound architecture in the 2.6 kernel version.
Author: Alessandro Rubini and Georg v. Zezschwitz.
URL: http://www.linuxjournal.com/article.php?sid=1222 * Title: **Linux PCMCIA Programmer's Guide**
Keywords: interrupts, irqs, DMA, bottom halves, task queues.
Description: Linux Journal Kernel Korner article. Here is its :Author: David Hinds.
abstract: "This is the fourth in a series of articles about :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html
writing character device drivers as loadable kernel modules. This :Date: 2003
month, we further investigate the field of interrupt handling. :Keywords: PCMCIA.
Though it is conceptually simple, practical limitations and :Description: "This document describes how to write kernel device
constraints make this an ``interesting'' part of device driver drivers for the Linux PCMCIA Card Services interface. It also
writing, and several different facilities have been provided for describes how to write user-mode utilities for communicating with
different situations. We also investigate the complex topic of Card Services.
DMA".
* Title: **Linux Kernel Module Programming Guide**
* Title: "Device Drivers Concluded"
Author: Georg v. Zezschwitz. :Author: Ori Pomerantz.
URL: http://www.linuxjournal.com/article.php?sid=1287 :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html
Keywords: address spaces, pages, pagination, page management, :Date: 2001
demand loading, swapping, memory protection, memory mapping, mmap, :Keywords: modules, GPL book, /proc, ioctls, system calls,
virtual memory areas (VMAs), vremap, PCI. interrupt handlers .
Description: Finally, the above turned out into a five articles :Description: Very nice 92 pages GPL book on the topic of modules
series. This latest one's introduction reads: "This is the last of programming. Lots of examples.
five articles about character device drivers. In this final
section, Georg deals with memory mapping devices, beginning with * Title: **Global spinlock list and usage**
an overall description of the Linux memory management concepts".
:Author: Rick Lindsley.
* Title: "Network Buffers And Memory Management" :URL: http://lse.sourceforge.net/lockhier/global-spin-lock
Author: Alan Cox. :Date: 2001
URL: http://www.linuxjournal.com/article.php?sid=1312 :Keywords: spinlock.
Keywords: sk_buffs, network devices, protocol/link layer :Description: This is an attempt to document both the existence and
variables, network devices flags, transmit, receive, usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive
configuration, multicast. list of spinlocks showing when they are used, which functions
Description: Linux Journal Kernel Korner. Here is the abstract: access them, how each lock is acquired, under what conditions it
"Writing a network device driver for Linux is fundamentally is held, whether interrupts can occur or not while it is held...
simple---most of the complexity (other than talking to the
hardware) involves managing network packets in memory". * Title: **A Linux vm README**
* Title: "Linux Kernel Hackers' Guide" :Author: Kanoj Sarcar.
Author: Michael K. Johnson. :URL: http://kos.enix.org/pub/linux-vmm.html
URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html :Date: 2001
Keywords: device drivers, files, VFS, kernel interface, character vs :Keywords: virtual memory, mm, pgd, vma, page, page flags, page
block devices, hardware interrupts, scsi, DMA, access to user memory, cache, swap cache, kswapd.
memory allocation, timers. :Description: Telegraphic, short descriptions and definitions
Description: A guide designed to help you get up to speed on the relating the Linux virtual memory implementation.
concepts that are not intuitevly obvious, and to document the internal
structures of Linux. * Title: **Video4linux Drivers, Part 1: Video-Capture Device**
* Title: "The Venus kernel interface" :Author: Alan Cox.
Author: Peter J. Braam. :URL: http://www.linux-mag.com/id/406
URL: :Date: 2000
http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html :Keywords: video4linux, driver, video capture, capture devices,
Keywords: coda, filesystem, venus, cache manager. camera driver.
Description: "This document describes the communication between :Description: The title says it all.
Venus and kernel level file system code needed for the operation
of the Coda filesystem. This version document is meant to describe * Title: **Video4linux Drivers, Part 2: Video-capture Devices**
the current interface (version 1.0) as well as improvements we
envisage". :Author: Alan Cox.
:URL: http://www.linux-mag.com/id/429
* Title: "Programming PCI-Devices under Linux" :Date: 2000
Author: Claus Schroeter. :Keywords: video4linux, driver, video capture, capture devices,
URL: camera driver, control, query capabilities, capability, facility.
ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps.gz :Description: The title says it all.
Keywords: PCI, device, busmastering.
Description: 6 pages tutorial on PCI programming under Linux. * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.**
Gives the basic concepts on the architecture of the PCI subsystem,
as long as basic functions and macros to read/write the devices :Author: Glenn Herrin.
and perform busmastering. :URL: http://www.cs.unh.edu/cnrg/gherrin
:Date: 2000
* Title: "Writing Character Device Driver for Linux" :Keywords: network, networking, protocol, IP, UDP, TCP, connection,
Author: R. Baruch and C. Schroeter. socket, receiving, transmitting, forwarding, routing, packets,
URL: modules, /proc, sk_buff, FIB, tags.
ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers.ps.gz :Description: Excellent paper devoted to the Linux IP Networking,
Keywords: character device drivers, I/O, signals, DMA, accessing explaining anything from the kernel's to the user space
ports in user space, kernel environment. configuration tools' code. Very good to get a general overview of
Description: 68 pages paper on writing character drivers. A little the kernel networking implementation and understand all steps
bit old (1.993, 1.994) although still useful. packets follow from the time they are received at the network
device till they are delivered to applications. The studied kernel
* Title: "Design and Implementation of the Second Extended code is from 2.2.14 version. Provides code for a working packet
Filesystem" dropper example.
Author: Rémy Card, Theodore Ts'o, Stephen Tweedie.
URL: http://web.mit.edu/tytso/www/linux/ext2intro.html * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh**
Keywords: ext2, linux fs history, inode, directory, link, devices,
VFS, physical structure, performance, benchmarks, ext2fs library, :Author: Paul Mackerras.
ext2fs tools, e2fsck. :URL: http://www.linux-mag.com/id/261
Description: Paper written by three of the top ext2 hackers. :Date: 1999
Covers Linux filesystems history, ext2 motivation, ext2 features, :Keywords: Mac, Power Macintosh, porting, drivers, compatibility.
design, physical structure on disk, performance, benchmarks, :Description: The title says it all.
e2fsck's passes description... A must read!
Notes: This paper was first published in the Proceedings of the * Title: **An Introduction to SCSI Drivers**
First Dutch International Symposium on Linux, ISBN 90-367-0385-9.
:Author: Alan Cox.
* Title: "Analysis of the Ext2fs structure" :URL: http://www.linux-mag.com/id/284
Author: Louis-Dominique Dubeau. :Date: 1999
URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ :Keywords: SCSI, device, driver.
Keywords: ext2, filesystem, ext2fs. :Description: The title says it all.
Description: Description of ext2's blocks, directories, inodes,
bitmaps, invariants... * Title: **Advanced SCSI Drivers And Other Tales**
* Title: "Journaling the Linux ext2fs Filesystem" :Author: Alan Cox.
Author: Stephen C. Tweedie. :URL: http://www.linux-mag.com/id/307
URL: :Date: 1999
ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz :Keywords: SCSI, device, driver, advanced.
Keywords: ext3, journaling. :Description: The title says it all.
Description: Excellent 8-pages paper explaining the journaling
capabilities added to ext2 by the author, showing different * Title: **Writing Linux Mouse Drivers**
problems faced and the alternatives chosen.
:Author: Alan Cox.
* Title: "Kernel API changes from 2.0 to 2.2" :URL: http://www.linux-mag.com/id/330
Author: Richard Gooch. :Date: 1999
URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.2.html :Keywords: mouse, driver, gpm.
Keywords: 2.2, changes. :Description: The title says it all.
Description: Kernel functions/structures/variables which changed
from 2.0.x to 2.2.x. * Title: **More on Mouse Drivers**
* Title: "Kernel API changes from 2.2 to 2.4" :Author: Alan Cox.
Author: Richard Gooch. :URL: http://www.linux-mag.com/id/356
URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.4.html :Date: 1999
Keywords: 2.4, changes. :Keywords: mouse, driver, gpm, races, asynchronous I/O.
Description: Kernel functions/structures/variables which changed :Description: The title still says it all.
from 2.2.x to 2.4.x.
* Title: **Writing Video4linux Radio Driver**
* Title: "Linux Kernel Module Programming Guide"
Author: Ori Pomerantz. :Author: Alan Cox.
URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html :URL: http://www.linux-mag.com/id/381
Keywords: modules, GPL book, /proc, ioctls, system calls, :Date: 1999
interrupt handlers . :Keywords: video4linux, driver, radio, radio devices.
Description: Very nice 92 pages GPL book on the topic of modules :Description: The title says it all.
programming. Lots of examples.
* Title: **I/O Event Handling Under Linux**
* Title: "I/O Event Handling Under Linux"
Author: Richard Gooch. :Author: Richard Gooch.
Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness :URL: http://web.mit.edu/~yandros/doc/io-events.html
event queues. :Date: 1999
Description: From the Introduction: "I/O Event handling is about :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness
how your Operating System allows you to manage a large number of event queues.
open files (file descriptors in UNIX/POSIX, or FDs) in your :Description: From the Introduction: "I/O Event handling is about
application. You want the OS to notify you when FDs become active how your Operating System allows you to manage a large number of
(have data ready to be read or are ready for writing). Ideally you open files (file descriptors in UNIX/POSIX, or FDs) in your
want a mechanism that is scalable. This means a large number of application. You want the OS to notify you when FDs become active
inactive FDs cost very little in memory and CPU time to manage". (have data ready to be read or are ready for writing). Ideally you
want a mechanism that is scalable. This means a large number of
* Title: "The Kernel Hacking HOWTO" inactive FDs cost very little in memory and CPU time to manage".
Author: Various Talented People, and Rusty.
Location: in kernel tree, Documentation/DocBook/kernel-hacking.tmpl * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.**
(must be built as "make {htmldocs | psdocs | pdfdocs})
Keywords: HOWTO, kernel contexts, deadlock, locking, modules, :Author: pragmatic/THC.
symbols, return conventions. :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html
Description: From the Introduction: "Please understand that I :Date: 1999
never wanted to write this document, being grossly underqualified, :Keywords: syscalls, intercept, hide, abuse, symbol table.
but I always wanted to read it, and this was the only way. I :Description: Interesting paper on how to abuse the Linux kernel in
simply explain some best practices, and give reading entry-points order to intercept and modify syscalls, make
into the kernel sources. I avoid implementation details: that's files/directories/processes invisible, become root, hijack ttys,
what the code is for, and I ignore whole tracts of useful write kernel modules based virus... and solutions for admins to
routines. This document assumes familiarity with C, and an avoid all those abuses.
understanding of what the kernel is, and how it is used. It was :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x
originally written for the 2.3 kernels, but nearly all of it kernels.
applies to 2.2 too; 2.0 is slightly different".
* Name: **Linux Virtual File System**
* Title: "Writing an ALSA Driver"
Author: Takashi Iwai <tiwai@suse.de> :Author: Peter J. Braam.
URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/
Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. :Date: 1998
Description: Advanced Linux Sound Architecture for developers, :Keywords: slides, VFS, inode, superblock, dentry, dcache.
both at kernel and user-level sides. ALSA is the Linux kernel :Description: Set of slides, presumably from a presentation on the
sound architecture in the 2.6 kernel version. Linux VFS layer. Covers version 2.1.x, with dentries and the
dcache.
* Title: "Programming Guide for Linux USB Device Drivers"
Author: Detlef Fliegl. * Title: **The Venus kernel interface**
URL: http://usb.in.tum.de/usbdoc/
Keywords: USB, universal serial bus. :Author: Peter J. Braam.
Description: A must-read. From the Preface: "This document should :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html
give detailed information about the current state of the USB :Date: 1998
subsystem and its API for USB device drivers. The first section :Keywords: coda, filesystem, venus, cache manager.
will deal with the basics of USB devices. You will learn about :Description: "This document describes the communication between
different types of devices and their properties. Going into detail Venus and kernel level file system code needed for the operation
you will see how USB devices communicate on the bus. The second of the Coda filesystem. This version document is meant to describe
section gives an overview of the Linux USB subsystem [2] and the the current interface (version 1.0) as well as improvements we
device driver framework. Then the API and its data structures will envisage".
be explained step by step. The last section of this document
contains a reference of all API calls and their return codes". * Title: **Design and Implementation of the Second Extended Filesystem**
Notes: Beware: the main page states: "This document may not be
published, printed or used in excerpts without explicit permission :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie.
of the author". Fortunately, it may still be read... :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html
:Date: 1998
* Title: "Linux Kernel Mailing List Glossary" :Keywords: ext2, linux fs history, inode, directory, link, devices,
Author: various VFS, physical structure, performance, benchmarks, ext2fs library,
URL: http://kernelnewbies.org/glossary/ ext2fs tools, e2fsck.
Keywords: glossary, terms, linux-kernel. :Description: Paper written by three of the top ext2 hackers.
Description: From the introduction: "This glossary is intended as Covers Linux filesystems history, ext2 motivation, ext2 features,
a brief description of some of the acronyms and terms you may hear design, physical structure on disk, performance, benchmarks,
during discussion of the Linux kernel". e2fsck's passes description... A must read!
:Notes: This paper was first published in the Proceedings of the
* Title: "Linux Kernel Locking HOWTO" First Dutch International Symposium on Linux, ISBN 90-367-0385-9.
Author: Various Talented People, and Rusty.
Location: in kernel tree, Documentation/DocBook/kernel-locking.tmpl * Title: **The Linux RAID-1, 4, 5 Code**
(must be built as "make {htmldocs | psdocs | pdfdocs})
Keywords: locks, locking, spinlock, semaphore, atomic, race :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza.
condition, bottom halves, tasklets, softirqs. :URL: http://www.linuxjournal.com/article.php?sid=2391
Description: The title says it all: document describing the :Date: 1997
locking system in the Linux Kernel either in uniprocessor or SMP :Keywords: RAID, MD driver.
systems. :Description: Linux Journal Kernel Korner article. Here is its
Notes: "It was originally written for the later (>2.3.47) 2.3 :Abstract: *A description of the implementation of the RAID-1,
kernels, but most of it applies to 2.2 too; 2.0 is slightly RAID-4 and RAID-5 personalities of the MD device driver in the
different". Freely redistributable under the conditions of the GNU Linux kernel, providing users with high performance and reliable,
General Public License. secondary-storage capability using software*.
* Title: "Global spinlock list and usage" * Title: **Linux Kernel Hackers' Guide**
Author: Rick Lindsley.
URL: http://lse.sourceforge.net/lockhier/global-spin-lock :Author: Michael K. Johnson.
Keywords: spinlock. :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html
Description: This is an attempt to document both the existence and :Date: 1997
usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive :Keywords: device drivers, files, VFS, kernel interface, character vs
list of spinlocks showing when they are used, which functions block devices, hardware interrupts, scsi, DMA, access to user memory,
access them, how each lock is acquired, under what conditions it memory allocation, timers.
is held, whether interrupts can occur or not while it is held... :Description: A guide designed to help you get up to speed on the
concepts that are not intuitevly obvious, and to document the internal
* Title: "Porting Linux 2.0 Drivers To Linux 2.2: Changes and New structures of Linux.
Features "
Author: Alan Cox. * Title: **Dynamic Kernels: Modularized Device Drivers**
URL: http://www.linux-mag.com/1999-05/gear_01.html
Keywords: ports, porting. :Author: Alessandro Rubini.
Description: Article from Linux Magazine on porting from 2.0 to :URL: http://www.linuxjournal.com/article.php?sid=1219
2.2 kernels. :Date: 1996
:Keywords: device driver, module, loading/unloading modules,
* Title: "Porting Device Drivers To Linux 2.2: part II" allocating resources.
Author: Alan Cox. :Description: Linux Journal Kernel Korner article. Here is its
URL: http://www.linux-mag.com/id/238 :Abstract: *This is the first of a series of four articles
Keywords: ports, porting. co-authored by Alessandro Rubini and Georg Zezchwitz which present
Description: Second part on porting from 2.0 to 2.2 kernels. a practical approach to writing Linux device drivers as kernel
loadable modules. This installment presents an introduction to the
* Title: "How To Make Sure Your Driver Will Work On The Power topic, preparing the reader to understand next month's
Macintosh" installment*.
Author: Paul Mackerras.
URL: http://www.linux-mag.com/id/261 * Title: **Dynamic Kernels: Discovery**
Keywords: Mac, Power Macintosh, porting, drivers, compatibility.
Description: The title says it all. :Author: Alessandro Rubini.
:URL: http://www.linuxjournal.com/article.php?sid=1220
* Title: "An Introduction to SCSI Drivers" :Date: 1996
Author: Alan Cox. :Keywords: character driver, init_module, clean_up module,
URL: http://www.linux-mag.com/id/284 autodetection, mayor number, minor number, file operations,
Keywords: SCSI, device, driver. open(), close().
Description: The title says it all. :Description: Linux Journal Kernel Korner article. Here is its
:Abstract: *This article, the second of four, introduces part of
* Title: "Advanced SCSI Drivers And Other Tales" the actual code to create custom module implementing a character
Author: Alan Cox. device driver. It describes the code for module initialization and
URL: http://www.linux-mag.com/id/307 cleanup, as well as the open() and close() system calls*.
Keywords: SCSI, device, driver, advanced.
Description: The title says it all. * Title: **The Devil's in the Details**
* Title: "Writing Linux Mouse Drivers" :Author: Georg v. Zezschwitz and Alessandro Rubini.
Author: Alan Cox. :URL: http://www.linuxjournal.com/article.php?sid=1221
URL: http://www.linux-mag.com/id/330 :Date: 1996
Keywords: mouse, driver, gpm. :Keywords: read(), write(), select(), ioctl(), blocking/non
Description: The title says it all. blocking mode, interrupt handler.
:Description: Linux Journal Kernel Korner article. Here is its
* Title: "More on Mouse Drivers" :Abstract: *This article, the third of four on writing character
Author: Alan Cox. device drivers, introduces concepts of reading, writing, and using
URL: http://www.linux-mag.com/id/356 ioctl-calls*.
Keywords: mouse, driver, gpm, races, asynchronous I/O.
Description: The title still says it all. * Title: **Dissecting Interrupts and Browsing DMA**
* Title: "Writing Video4linux Radio Driver" :Author: Alessandro Rubini and Georg v. Zezschwitz.
Author: Alan Cox. :URL: http://www.linuxjournal.com/article.php?sid=1222
URL: http://www.linux-mag.com/id/381 :Date: 1996
Keywords: video4linux, driver, radio, radio devices. :Keywords: interrupts, irqs, DMA, bottom halves, task queues.
Description: The title says it all. :Description: Linux Journal Kernel Korner article. Here is its
:Abstract: *This is the fourth in a series of articles about
* Title: "Video4linux Drivers, Part 1: Video-Capture Device" writing character device drivers as loadable kernel modules. This
Author: Alan Cox. month, we further investigate the field of interrupt handling.
URL: http://www.linux-mag.com/id/406 Though it is conceptually simple, practical limitations and
Keywords: video4linux, driver, video capture, capture devices, constraints make this an ''interesting'' part of device driver
camera driver. writing, and several different facilities have been provided for
Description: The title says it all. different situations. We also investigate the complex topic of
DMA*.
* Title: "Video4linux Drivers, Part 2: Video-capture Devices"
Author: Alan Cox. * Title: **Device Drivers Concluded**
URL: http://www.linux-mag.com/id/429
Keywords: video4linux, driver, video capture, capture devices, :Author: Georg v. Zezschwitz.
camera driver, control, query capabilities, capability, facility. :URL: http://www.linuxjournal.com/article.php?sid=1287
Description: The title says it all. :Date: 1996
:Keywords: address spaces, pages, pagination, page management,
* Title: "PCI Management in Linux 2.2" demand loading, swapping, memory protection, memory mapping, mmap,
Author: Alan Cox. virtual memory areas (VMAs), vremap, PCI.
URL: http://www.linux-mag.com/id/452 :Description: Finally, the above turned out into a five articles
Keywords: PCI, bus, bus-mastering. series. This latest one's introduction reads: "This is the last of
Description: The title says it all. five articles about character device drivers. In this final
section, Georg deals with memory mapping devices, beginning with
* Title: "Linux 2.4 Kernel Internals" an overall description of the Linux memory management concepts".
Author: Tigran Aivazian and Christoph Hellwig.
URL: http://www.moses.uklinux.net/patches/lki.html * Title: **Network Buffers And Memory Management**
Keywords: Linux, kernel, booting, SMB boot, VFS, page cache.
Description: A little book used for a short training course. :Author: Alan Cox.
Covers building the kernel image, booting (including SMP bootup), :URL: http://www.linuxjournal.com/article.php?sid=1312
process management, VFS and more. :Date: 1996
:Keywords: sk_buffs, network devices, protocol/link layer
* Title: "Linux IP Networking. A Guide to the Implementation and variables, network devices flags, transmit, receive,
Modification of the Linux Protocol Stack." configuration, multicast.
Author: Glenn Herrin. :Description: Linux Journal Kernel Korner.
URL: http://www.cs.unh.edu/cnrg/gherrin :Abstract: *Writing a network device driver for Linux is fundamentally
Keywords: network, networking, protocol, IP, UDP, TCP, connection, simple---most of the complexity (other than talking to the
socket, receiving, transmitting, forwarding, routing, packets, hardware) involves managing network packets in memory*.
modules, /proc, sk_buff, FIB, tags.
Description: Excellent paper devoted to the Linux IP Networking, * Title: **Analysis of the Ext2fs structure**
explaining anything from the kernel's to the user space
configuration tools' code. Very good to get a general overview of :Author: Louis-Dominique Dubeau.
the kernel networking implementation and understand all steps :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/
packets follow from the time they are received at the network :Date: 1994
device till they are delivered to applications. The studied kernel :Keywords: ext2, filesystem, ext2fs.
code is from 2.2.14 version. Provides code for a working packet :Description: Description of ext2's blocks, directories, inodes,
dropper example. bitmaps, invariants...
* Title: "Get those boards talking under Linux." Published books
Author: Alex Ivchenko. ---------------
URL: http://www.edn.com/article/CA46968.html
Keywords: data-acquisition boards, drivers, modules, interrupts, * Title: **Linux Treiber entwickeln**
memory allocation.
Description: Article written for people wishing to make their data :Author: Jürgen Quade, Eva-Katharina Kunst
acquisition boards work on their GNU/Linux machines. Gives a basic :Publisher: dpunkt.verlag
overview on writing drivers, from the naming of functions to :Date: Oct 2015 (4th edition)
interrupt handling. :Pages: 688
Notes: Two-parts article. Part II is at :ISBN: 978-3-86490-288-8
URL: http://www.edn.com/article/CA46998.html :Note: German. The third edition from 2011 is
much cheaper and still quite up-to-date.
* Title: "Linux PCMCIA Programmer's Guide"
Author: David Hinds. * Title: **Linux Kernel Networking: Implementation and Theory**
URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html
Keywords: PCMCIA. :Author: Rami Rosen
Description: "This document describes how to write kernel device :Publisher: Apress
drivers for the Linux PCMCIA Card Services interface. It also :Date: December 22, 2013
describes how to write user-mode utilities for communicating with :Pages: 648
Card Services. :ISBN: 978-1430261964
* Title: "The Linux Kernel NFSD Implementation" * Title: **Embedded Linux Primer: A practical Real-World Approach, 2nd Edition**
Author: Neil Brown.
URL: :Author: Christopher Hallinan
http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/nfsd.html :Publisher: Pearson
Keywords: knfsd, nfsd, NFS, RPC, lockd, mountd, statd. :Date: November, 2010
Description: The title says it all. :Pages: 656
Notes: Covers knfsd's version 1.4.7 (patch against 2.2.7 kernel). :ISBN: 978-0137017836
* Title: "A Linux vm README" * Title: **Linux Kernel Development, 3rd Edition**
Author: Kanoj Sarcar.
URL: http://kos.enix.org/pub/linux-vmm.html :Author: Robert Love
Keywords: virtual memory, mm, pgd, vma, page, page flags, page :Publisher: Addison-Wesley
cache, swap cache, kswapd. :Date: July, 2010
Description: Telegraphic, short descriptions and definitions :Pages: 440
relating the Linux virtual memory implementation. :ISBN: 978-0672329463
* Title: "(nearly) Complete Linux Loadable Kernel Modules. The * Title: **Essential Linux Device Drivers**
definitive guide for hackers, virus coders and system
administrators." :Author: Sreekrishnan Venkateswaran
Author: pragmatic/THC. :Published: Prentice Hall
URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html :Date: April, 2008
Keywords: syscalls, intercept, hide, abuse, symbol table. :Pages: 744
Description: Interesting paper on how to abuse the Linux kernel in :ISBN: 978-0132396554
order to intercept and modify syscalls, make
files/directories/processes invisible, become root, hijack ttys, .. _ldd3_published:
write kernel modules based virus... and solutions for admins to
avoid all those abuses. * Title: **Linux Device Drivers, 3rd Edition**
Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x
kernels. :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman
:Publisher: O'Reilly & Associates
BOOKS: (Not on-line) :Date: 2005
:Pages: 636
* Title: "Linux Device Drivers" :ISBN: 0-596-00590-3
Author: Alessandro Rubini. :Notes: Further information in
Publisher: O'Reilly & Associates. http://www.oreilly.com/catalog/linuxdrive3/
Date: 1998. PDF format, URL: http://lwn.net/Kernel/LDD3/
Pages: 439.
ISBN: 1-56592-292-1 * Title: **Linux Kernel Internals**
* Title: "Linux Device Drivers, 2nd Edition" :Author: Michael Beck
Author: Alessandro Rubini and Jonathan Corbet. :Publisher: Addison-Wesley
Publisher: O'Reilly & Associates. :Date: 1997
Date: 2001. :ISBN: 0-201-33143-8 (second edition)
Pages: 586.
ISBN: 0-59600-008-1 * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau**
Notes: Further information in
http://www.oreilly.com/catalog/linuxdrive2/ :Author: Remy Card, Eric Dumas, Franck Mevel
:Publisher: Eyrolles
* Title: "Linux Device Drivers, 3rd Edition" :Date: 1997
Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman :Pages: 520
Publisher: O'Reilly & Associates. :ISBN: 2-212-08932-5
Date: 2005. :Notes: French
Pages: 636.
ISBN: 0-596-00590-3 * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System**
Notes: Further information in
http://www.oreilly.com/catalog/linuxdrive3/ :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels,
PDF format, URL: http://lwn.net/Kernel/LDD3/ John S. Quarterman
:Publisher: Addison-Wesley
* Title: "Linux Kernel Internals" :Date: 1996
Author: Michael Beck. :ISBN: 0-201-54979-4
Publisher: Addison-Wesley.
Date: 1997. * Title: **Unix internals -- the new frontiers**
ISBN: 0-201-33143-8 (second edition)
:Author: Uresh Vahalia
* Title: "The Design of the UNIX Operating System" :Publisher: Prentice Hall
Author: Maurice J. Bach. :Date: 1996
Publisher: Prentice Hall. :Pages: 600
Date: 1986. :ISBN: 0-13-101908-2
Pages: 471.
ISBN: 0-13-201757-1 * Title: **Programming for the real world - POSIX.4**
* Title: "The Design and Implementation of the 4.3 BSD UNIX :Author: Bill O. Gallmeister
Operating System" :Publisher: O'Reilly & Associates, Inc
Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J. :Date: 1995
Karels, John S. Quarterman. :Pages: 552
Publisher: Addison-Wesley. :ISBN: I-56592-074-0
Date: 1989 (reprinted with corrections on October, 1990). :Notes: Though not being directly about Linux, Linux aims to be
ISBN: 0-201-06196-1 POSIX. Good reference.
* Title: "The Design and Implementation of the 4.4 BSD UNIX * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers**
Operating System"
Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, :Author: Curt Schimmel
John S. Quarterman. :Publisher: Addison Wesley
Publisher: Addison-Wesley. :Date: June, 1994
Date: 1996. :Pages: 432
ISBN: 0-201-54979-4 :ISBN: 0-201-63338-8
* Title: "Programmation Linux 2.0 API systeme et fonctionnement du * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System**
noyau"
Author: Remy Card, Eric Dumas, Franck Mevel. :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J
Publisher: Eyrolles. Karels, John S. Quarterman
Date: 1997. :Publisher: Addison-Wesley
Pages: 520. :Date: 1989 (reprinted with corrections on October, 1990)
ISBN: 2-212-08932-5 :ISBN: 0-201-06196-1
Notes: French.
* Title: **The Design of the UNIX Operating System**
* Title: "Unix internals -- the new frontiers"
Author: Uresh Vahalia. :Author: Maurice J. Bach
Publisher: Prentice Hall. :Publisher: Prentice Hall
Date: 1996. :Date: 1986
Pages: 600. :Pages: 471
ISBN: 0-13-101908-2 :ISBN: 0-13-201757-1
* Title: "Programming for the real world - POSIX.4" Miscellaneous
Author: Bill O. Gallmeister. -------------
Publisher: O'Reilly & Associates, Inc..
Date: 1995. * Name: **Cross-Referencing Linux**
Pages: ???.
ISBN: I-56592-074-0 :URL: http://lxr.free-electrons.com/
Notes: Though not being directly about Linux, Linux aims to be :Keywords: Browsing source code.
POSIX. Good reference. :Description: Another web-based Linux kernel source code browser.
Lots of cross references to variables and functions. You can see
* Title: "UNIX Systems for Modern Architectures: Symmetric where they are defined and where they are used.
Multiprocessing and Caching for Kernel Programmers"
Author: Curt Schimmel. * Name: **Linux Weekly News**
Publisher: Addison Wesley.
Date: June, 1994. :URL: http://lwn.net
Pages: 432. :Keywords: latest kernel news.
ISBN: 0-201-63338-8 :Description: The title says it all. There's a fixed kernel section
summarizing developers' work, bug fixes, new features and versions
* Title: "Linux Kernel Development, 3rd Edition" produced during the week. Published every Thursday.
Author: Robert Love
Publisher: Addison-Wesley. * Name: **The home page of Linux-MM**
Date: July, 2010
Pages: 440 :Author: The Linux-MM team.
ISBN: 978-0672329463 :URL: http://linux-mm.org/
:Keywords: memory management, Linux-MM, mm patches, TODO, docs,
MISCELLANEOUS: mailing list.
:Description: Site devoted to Linux Memory Management development.
* Name: linux/Documentation Memory related patches, HOWTOs, links, mm developers... Don't miss
Author: Many. it if you are interested in memory management development!
URL: Just look inside your kernel sources.
Keywords: anything, DocBook. * Name: **Kernel Newbies IRC Channel and Website**
Description: Documentation that comes with the kernel sources,
inside the Documentation directory. Some pages from this document :URL: http://www.kernelnewbies.org
(including this document itself) have been moved there, and might :Keywords: IRC, newbies, channel, asking doubts.
be more up to date than the web version. :Description: #kernelnewbies on irc.oftc.net.
#kernelnewbies is an IRC network dedicated to the 'newbie'
* Name: "Linux Kernel Source Reference" kernel hacker. The audience mostly consists of people who are
Author: Thomas Graichen. learning about the kernel, working on kernel projects or
URL: http://marc.info/?l=linux-kernel&m=96446640102205&w=4 professional kernel hackers that want to help less seasoned kernel
Keywords: CVS, web, cvsweb, browsing source code. people.
Description: Web interface to a CVS server with the kernel #kernelnewbies is on the OFTC IRC Network.
sources. "Here you can have a look at any file of the Linux kernel Try irc.oftc.net as your server and then /join #kernelnewbies.
sources of any version starting from 1.0 up to the (daily updated) The kernelnewbies website also hosts articles, documents, FAQs...
current version available. Also you can check the differences
between two versions of a file". * Name: **linux-kernel mailing list archives and search engines**
* Name: "Cross-Referencing Linux" :URL: http://vger.kernel.org/vger-lists.html
URL: http://lxr.free-electrons.com/ :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html
Keywords: Browsing source code. :URL: http://groups.google.com/group/mlist.linux.kernel
Description: Another web-based Linux kernel source code browser. :Keywords: linux-kernel, archives, search.
Lots of cross references to variables and functions. You can see :Description: Some of the linux-kernel mailing list archivers. If
where they are defined and where they are used. you have a better/another one, please let me know.
* Name: "Linux Weekly News" -------
URL: http://lwn.net
Keywords: latest kernel news. Document last updated on Tue 2016-Sep-20
Description: The title says it all. There's a fixed kernel section
summarizing developers' work, bug fixes, new features and versions This document is based on:
produced during the week. Published every Thursday. http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
* Name: "Kernel Traffic"
URL: http://kt.earth.li/kernel-traffic/index.html
Keywords: linux-kernel mailing list, weekly kernel news.
Description: Weekly newsletter covering the most relevant
discussions of the linux-kernel mailing list.
* Name: "CuTTiNG.eDGe.LiNuX"
URL: http://edge.kernelnotes.org
Keywords: changelist.
Description: Site which provides the changelist for every kernel
release. What's new, what's better, what's changed. Myrdraal reads
the patches and describes them. Pointers to the patches are there,
too.
* Name: "New linux-kernel Mailing List FAQ"
URL: http://www.tux.org/lkml/
Keywords: linux-kernel mailing list FAQ.
Description: linux-kernel is a mailing list for developers to
communicate. This FAQ builds on the previous linux-kernel mailing
list FAQ maintained by Frohwalt Egerer, who no longer maintains
it. Read it to see how to join the mailing list. Dozens of
interesting questions regarding the list, Linux, developers (who
is ...?), terms (what is...?) are answered here too. Just read it.
* Name: "Linux Virtual File System"
Author: Peter J. Braam.
URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/
Keywords: slides, VFS, inode, superblock, dentry, dcache.
Description: Set of slides, presumably from a presentation on the
Linux VFS layer. Covers version 2.1.x, with dentries and the
dcache.
* Name: "Gary's Encyclopedia - The Linux Kernel"
Author: Gary (I suppose...).
URL: http://slencyclopedia.berlios.de/index.html
Keywords: linux, community, everything!
Description: Gary's Encyclopedia exists to allow the rapid finding
of documentation and other information of interest to GNU/Linux
users. It has about 4000 links to external pages in 150 major
categories. This link is for kernel-specific links, documents,
sites... This list is now hosted by developer.Berlios.de,
but seems not to have been updated since sometime in 1999.
* Name: "The home page of Linux-MM"
Author: The Linux-MM team.
URL: http://linux-mm.org/
Keywords: memory management, Linux-MM, mm patches, TODO, docs,
mailing list.
Description: Site devoted to Linux Memory Management development.
Memory related patches, HOWTOs, links, mm developers... Don't miss
it if you are interested in memory management development!
* Name: "Kernel Newbies IRC Channel and Website"
URL: http://www.kernelnewbies.org
Keywords: IRC, newbies, channel, asking doubts.
Description: #kernelnewbies on irc.oftc.net.
#kernelnewbies is an IRC network dedicated to the 'newbie'
kernel hacker. The audience mostly consists of people who are
learning about the kernel, working on kernel projects or
professional kernel hackers that want to help less seasoned kernel
people.
#kernelnewbies is on the OFTC IRC Network.
Try irc.oftc.net as your server and then /join #kernelnewbies.
The kernelnewbies website also hosts articles, documents, FAQs...
* Name: "linux-kernel mailing list archives and search engines"
URL: http://vger.kernel.org/vger-lists.html
URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html
URL: http://marc.theaimsgroup.com/?l=linux-kernel
URL: http://groups.google.com/group/mlist.linux.kernel
URL: http://www.cs.helsinki.fi/linux/linux-kernel/
URL: http://www.lib.uaa.alaska.edu/linux-kernel/
Keywords: linux-kernel, archives, search.
Description: Some of the linux-kernel mailing list archivers. If
you have a better/another one, please let me know.
_________________________________________________________________
Document last updated on Sat 2005-NOV-19
Documentation/kernel-documentation.rst
View file @ 02bafd96
...@@ -107,6 +107,35 @@ Here are some specific guidelines for the kernel documentation: ...@@ -107,6 +107,35 @@ Here are some specific guidelines for the kernel documentation:
the order as encountered."), having the higher levels the same overall makes the order as encountered."), having the higher levels the same overall makes
it easier to follow the documents. it easier to follow the documents.
the C domain
------------
The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a
function prototype:
.. code-block:: rst
.. c:function:: int ioctl( int fd, int request )
The C domain of the kernel-doc has some additional features. E.g. you can
*rename* the reference name of a function with a common name like ``open`` or
``ioctl``:
.. code-block:: rst
.. c:function:: int ioctl( int fd, int request )
:name: VIDIOC_LOG_STATUS
The func-name (e.g. ioctl) remains in the output but the ref-name changed from
``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
.. code-block:: rst
:c:func:`VIDIOC_LOG_STATUS`
list tables list tables
----------- -----------
...@@ -265,6 +294,8 @@ The kernel-doc extension is included in the kernel source tree, at ...@@ -265,6 +294,8 @@ The kernel-doc extension is included in the kernel source tree, at
``scripts/kernel-doc`` script to extract the documentation comments from the ``scripts/kernel-doc`` script to extract the documentation comments from the
source. source.
.. _kernel_doc:
Writing kernel-doc comments Writing kernel-doc comments
=========================== ===========================
......
Documentation/kernel-parameters.txt
View file @ 02bafd96
...@@ -1698,7 +1698,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. ...@@ -1698,7 +1698,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
intel_idle.max_cstate= [KNL,HW,ACPI,X86] intel_idle.max_cstate= [KNL,HW,ACPI,X86]
0 disables intel_idle and fall back on acpi_idle. 0 disables intel_idle and fall back on acpi_idle.
1 to 6 specify maximum depth of C-state. 1 to 9 specify maximum depth of C-state.
intel_pstate= [X86] intel_pstate= [X86]
disable disable
...@@ -2171,10 +2171,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. ...@@ -2171,10 +2171,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
than or equal to this physical address is ignored. than or equal to this physical address is ignored.
maxcpus= [SMP] Maximum number of processors that an SMP kernel maxcpus= [SMP] Maximum number of processors that an SMP kernel
should make use of. maxcpus=n : n >= 0 limits the will bring up during bootup. maxcpus=n : n >= 0 limits
kernel to using 'n' processors. n=0 is a special case, the kernel to bring up 'n' processors. Surely after
it is equivalent to "nosmp", which also disables bootup you can bring up the other plugged cpu by executing
the IO APIC. "echo 1 > /sys/devices/system/cpu/cpuX/online". So maxcpus
only takes effect during system bootup.
While n=0 is a special case, it is equivalent to "nosmp",
which also disables the IO APIC.
max_loop= [LOOP] The number of loop block devices that get max_loop= [LOOP] The number of loop block devices that get
(loop.max_loop) unconditionally pre-created at init time. The default (loop.max_loop) unconditionally pre-created at init time. The default
...@@ -2581,8 +2584,6 @@ bytes respectively. Such letter suffixes can also be entirely omitted. ...@@ -2581,8 +2584,6 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
nodelayacct [KNL] Disable per-task delay accounting nodelayacct [KNL] Disable per-task delay accounting
nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects.
nodsp [SH] Disable hardware DSP at boot time. nodsp [SH] Disable hardware DSP at boot time.
noefi Disable EFI runtime services support. noefi Disable EFI runtime services support.
...@@ -2783,9 +2784,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. ...@@ -2783,9 +2784,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
nr_cpus= [SMP] Maximum number of processors that an SMP kernel nr_cpus= [SMP] Maximum number of processors that an SMP kernel
could support. nr_cpus=n : n >= 1 limits the kernel to could support. nr_cpus=n : n >= 1 limits the kernel to
supporting 'n' processors. Later in runtime you can not support 'n' processors. It could be larger than the
use hotplug cpu feature to put more cpu back to online. number of already plugged CPU during bootup, later in
just like you compile the kernel NR_CPUS=n runtime you can physically add extra cpu until it reaches
n. So during boot up some boot time memory for per-cpu
variables need be pre-allocated for later physical cpu
hot plugging.
nr_uarts= [SERIAL] maximum number of UARTs to be registered. nr_uarts= [SERIAL] maximum number of UARTs to be registered.
......
Documentation/kprobes.txt
View file @ 02bafd96
...@@ -103,6 +103,16 @@ Note that the probed function's args may be passed on the stack ...@@ -103,6 +103,16 @@ Note that the probed function's args may be passed on the stack
or in registers. The jprobe will work in either case, so long as the or in registers. The jprobe will work in either case, so long as the
handler's prototype matches that of the probed function. handler's prototype matches that of the probed function.
Note that in some architectures (e.g.: arm64 and sparc64) the stack
copy is not done, as the actual location of stacked parameters may be
outside of a reasonable MAX_STACK_SIZE value and because that location
cannot be determined by the jprobes code. In this case the jprobes
user must be careful to make certain the calling signature of the
function does not cause parameters to be passed on the stack (e.g.:
more than eight function arguments, an argument of more than sixteen
bytes, or more than 64 bytes of argument data, depending on
architecture).
1.3 Return Probes 1.3 Return Probes
1.3.1 How Does a Return Probe Work? 1.3.1 How Does a Return Probe Work?
......
Documentation/media/Makefile
View file @ 02bafd96
...@@ -10,7 +10,8 @@ FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \ ...@@ -10,7 +10,8 @@ FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
TARGETS := $(addprefix $(BUILDDIR)/, $(FILES)) TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
htmldocs: $(BUILDDIR) ${TARGETS} .PHONY: all
all: $(BUILDDIR) ${TARGETS}
$(BUILDDIR): $(BUILDDIR):
$(Q)mkdir -p $@ $(Q)mkdir -p $@
......
Documentation/media/conf.py 0 → 100644
View file @ 02bafd96
# -*- coding: utf-8; mode: python -*-
project = 'Linux Media Subsystem Documentation'
tags.add("subproject")
latex_documents = [
('index', 'media.tex', 'Linux Media Subsystem Documentation',
'The kernel development community', 'manual'),
]
Documentation/media/conf_nitpick.py 0 → 100644
View file @ 02bafd96
# -*- coding: utf-8; mode: python -*-
project = 'Linux Media Subsystem Documentation'
# It is possible to run Sphinx in nickpick mode with:
nitpicky = True
# within nit-picking build, do not refer to any intersphinx object
intersphinx_mapping = {}
# In nickpick mode, it will complain about lots of missing references that
#
# 1) are just typedefs like: bool, __u32, etc;
# 2) It will complain for things like: enum, NULL;
# 3) It will complain for symbols that should be on different
# books (but currently aren't ported to ReST)
#
# The list below has a list of such symbols to be ignored in nitpick mode
#
nitpick_ignore = [
("c:func", "clock_gettime"),
("c:func", "close"),
("c:func", "container_of"),
("c:func", "determine_valid_ioctls"),
("c:func", "ERR_PTR"),
("c:func", "ioctl"),
("c:func", "IS_ERR"),
("c:func", "mmap"),
("c:func", "open"),
("c:func", "pci_name"),
("c:func", "poll"),
("c:func", "PTR_ERR"),
("c:func", "read"),
("c:func", "release"),
("c:func", "set"),
("c:func", "struct fd_set"),
("c:func", "struct pollfd"),
("c:func", "usb_make_path"),
("c:func", "write"),
("c:type", "atomic_t"),
("c:type", "bool"),
("c:type", "buf_queue"),
("c:type", "device"),
("c:type", "device_driver"),
("c:type", "device_node"),
("c:type", "enum"),
("c:type", "file"),
("c:type", "i2c_adapter"),
("c:type", "i2c_board_info"),
("c:type", "i2c_client"),
("c:type", "ktime_t"),
("c:type", "led_classdev_flash"),
("c:type", "list_head"),
("c:type", "lock_class_key"),
("c:type", "module"),
("c:type", "mutex"),
("c:type", "pci_dev"),
("c:type", "pdvbdev"),
("c:type", "poll_table_struct"),
("c:type", "s32"),
("c:type", "s64"),
("c:type", "sd"),
("c:type", "spi_board_info"),
("c:type", "spi_device"),
("c:type", "spi_master"),
("c:type", "struct fb_fix_screeninfo"),
("c:type", "struct pollfd"),
("c:type", "struct timeval"),
("c:type", "struct video_capability"),
("c:type", "u16"),
("c:type", "u32"),
("c:type", "u64"),
("c:type", "u8"),
("c:type", "union"),
("c:type", "usb_device"),
("cpp:type", "boolean"),
("cpp:type", "fd"),
("cpp:type", "fd_set"),
("cpp:type", "int16_t"),
("cpp:type", "NULL"),
("cpp:type", "off_t"),
("cpp:type", "pollfd"),
("cpp:type", "size_t"),
("cpp:type", "ssize_t"),
("cpp:type", "timeval"),
("cpp:type", "__u16"),
("cpp:type", "__u32"),
("cpp:type", "__u64"),
("cpp:type", "uint16_t"),
("cpp:type", "uint32_t"),
("cpp:type", "video_system_t"),
]
Documentation/media/index.rst 0 → 100644
View file @ 02bafd96
Linux Media Subsystem Documentation
===================================
Contents:
.. toctree::
:maxdepth: 2
media_uapi
media_kapi
dvb-drivers/index
v4l-drivers/index
.. only:: subproject
Indices
=======
* :ref:`genindex`
Documentation/media/uapi/cec/cec-func-open.rst
View file @ 02bafd96
...@@ -32,7 +32,7 @@ Arguments ...@@ -32,7 +32,7 @@ Arguments
Open flags. Access mode must be ``O_RDWR``. Open flags. Access mode must be ``O_RDWR``.
When the ``O_NONBLOCK`` flag is given, the When the ``O_NONBLOCK`` flag is given, the
:ref:`CEC_RECEIVE <CEC_RECEIVE>` and :ref:`CEC_DQEVENT <CEC_DQEVENT>` ioctls :ref:`CEC_RECEIVE <CEC_RECEIVE>` and :c:func:`CEC_DQEVENT` ioctls
will return the ``EAGAIN`` error code when no message or event is available, and will return the ``EAGAIN`` error code when no message or event is available, and
ioctls :ref:`CEC_TRANSMIT <CEC_TRANSMIT>`, ioctls :ref:`CEC_TRANSMIT <CEC_TRANSMIT>`,
:ref:`CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` and :ref:`CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` and
......
Documentation/media/uapi/cec/cec-ioc-dqevent.rst
View file @ 02bafd96
...@@ -15,7 +15,8 @@ CEC_DQEVENT - Dequeue a CEC event ...@@ -15,7 +15,8 @@ CEC_DQEVENT - Dequeue a CEC event
Synopsis Synopsis
======== ========
.. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp ) .. c:function:: int ioctl( int fd, int request, struct cec_event *argp )
:name: CEC_DQEVENT
Arguments Arguments
========= =========
...@@ -36,7 +37,7 @@ Description ...@@ -36,7 +37,7 @@ Description
and is currently only available as a staging kernel module. and is currently only available as a staging kernel module.
CEC devices can send asynchronous events. These can be retrieved by CEC devices can send asynchronous events. These can be retrieved by
calling :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>`. If the file descriptor is in calling :c:func:`CEC_DQEVENT`. If the file descriptor is in
non-blocking mode and no event is pending, then it will return -1 and non-blocking mode and no event is pending, then it will return -1 and
set errno to the ``EAGAIN`` error code. set errno to the ``EAGAIN`` error code.
......
Documentation/scsi/scsi-parameters.txt
View file @ 02bafd96
...@@ -79,8 +79,6 @@ parameters may be changed at runtime by the command ...@@ -79,8 +79,6 @@ parameters may be changed at runtime by the command
ncr53c8xx= [HW,SCSI] ncr53c8xx= [HW,SCSI]
nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects.
osst= [HW,SCSI] SCSI Tape Driver osst= [HW,SCSI] SCSI Tape Driver
Format: <buffer_size>,<write_threshold> Format: <buffer_size>,<write_threshold>
See also Documentation/scsi/st.txt. See also Documentation/scsi/st.txt.
......
Documentation/serial/serial-rs485.txt
View file @ 02bafd96
...@@ -45,9 +45,8 @@ ...@@ -45,9 +45,8 @@
#include <linux/serial.h> #include <linux/serial.h>
/* RS485 ioctls: */ /* Include definition for RS485 ioctls: TIOCGRS485 and TIOCSRS485 */
#define TIOCGRS485 0x542E #include <sys/ioctl.h>
#define TIOCSRS485 0x542F
/* Open your specific device (e.g., /dev/mydevice): */ /* Open your specific device (e.g., /dev/mydevice): */
int fd = open ("/dev/mydevice", O_RDWR); int fd = open ("/dev/mydevice", O_RDWR);
......
Documentation/sphinx-static/theme_overrides.css
View file @ 02bafd96
...@@ -42,6 +42,20 @@ ...@@ -42,6 +42,20 @@
caption a.headerlink { opacity: 0; } caption a.headerlink { opacity: 0; }
caption a.headerlink:hover { opacity: 1; } caption a.headerlink:hover { opacity: 1; }
/* Menu selection and keystrokes */
span.menuselection {
color: blue;
font-family: "Courier New", Courier, monospace
}
code.kbd, code.kbd span {
color: white;
background-color: darkblue;
font-weight: bold;
font-family: "Courier New", Courier, monospace
}
/* inline literal: drop the borderbox, padding and red color */ /* inline literal: drop the borderbox, padding and red color */
code, .rst-content tt, .rst-content code { code, .rst-content tt, .rst-content code {
...@@ -55,5 +69,4 @@ ...@@ -55,5 +69,4 @@
.rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal { .rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal {
color: inherit; color: inherit;
} }
} }
Documentation/sphinx/cdomain.py 0 → 100644
View file @ 02bafd96
# -*- coding: utf-8; mode: python -*-
# pylint: disable=W0141,C0113,C0103,C0325
u"""
cdomain
~~~~~~~
Replacement for the sphinx c-domain.
:copyright: Copyright (C) 2016 Markus Heiser
:license: GPL Version 2, June 1991 see Linux/COPYING for details.
List of customizations:
* Moved the *duplicate C object description* warnings for function
declarations in the nitpicky mode. See Sphinx documentation for
the config values for ``nitpick`` and ``nitpick_ignore``.
* Add option 'name' to the "c:function:" directive. With option 'name' the
ref-name of a function can be modified. E.g.::
.. c:function:: int ioctl( int fd, int request )
:name: VIDIOC_LOG_STATUS
The func-name (e.g. ioctl) remains in the output but the ref-name changed
from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by::
* :c:func:`VIDIOC_LOG_STATUS` or
* :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3)
* Handle signatures of function-like macros well. Don't try to deduce
arguments types of function-like macros.
"""
from docutils import nodes
from docutils.parsers.rst import directives
import sphinx
from sphinx import addnodes
from sphinx.domains.c import c_funcptr_sig_re, c_sig_re
from sphinx.domains.c import CObject as Base_CObject
from sphinx.domains.c import CDomain as Base_CDomain
__version__ = '1.0'
# Get Sphinx version
major, minor, patch = map(int, sphinx.__version__.split("."))
def setup(app):
app.override_domain(CDomain)
return dict(
version = __version__,
parallel_read_safe = True,
parallel_write_safe = True
)
class CObject(Base_CObject):
"""
Description of a C language object.
"""
option_spec = {
"name" : directives.unchanged
}
def handle_func_like_macro(self, sig, signode):
u"""Handles signatures of function-like macros.
If the objtype is 'function' and the the signature ``sig`` is a
function-like macro, the name of the macro is returned. Otherwise
``False`` is returned. """
if not self.objtype == 'function':
return False
m = c_funcptr_sig_re.match(sig)
if m is None:
m = c_sig_re.match(sig)
if m is None:
raise ValueError('no match')
rettype, fullname, arglist, _const = m.groups()
arglist = arglist.strip()
if rettype or not arglist:
return False
arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup
arglist = [a.strip() for a in arglist.split(",")]
# has the first argument a type?
if len(arglist[0].split(" ")) > 1:
return False
# This is a function-like macro, it's arguments are typeless!
signode += addnodes.desc_name(fullname, fullname)
paramlist = addnodes.desc_parameterlist()
signode += paramlist
for argname in arglist:
param = addnodes.desc_parameter('', '', noemph=True)
# separate by non-breaking space in the output
param += nodes.emphasis(argname, argname)
paramlist += param
return fullname
def handle_signature(self, sig, signode):
"""Transform a C signature into RST nodes."""
fullname = self.handle_func_like_macro(sig, signode)
if not fullname:
fullname = super(CObject, self).handle_signature(sig, signode)
if "name" in self.options:
if self.objtype == 'function':
fullname = self.options["name"]
else:
# FIXME: handle :name: value of other declaration types?
pass
return fullname
def add_target_and_index(self, name, sig, signode):
# for C API items we add a prefix since names are usually not qualified
# by a module name and so easily clash with e.g. section titles
targetname = 'c.' + name
if targetname not in self.state.document.ids:
signode['names'].append(targetname)
signode['ids'].append(targetname)
signode['first'] = (not self.names)
self.state.document.note_explicit_target(signode)
inv = self.env.domaindata['c']['objects']
if (name in inv and self.env.config.nitpicky):
if self.objtype == 'function':
if ('c:func', name) not in self.env.config.nitpick_ignore:
self.state_machine.reporter.warning(
'duplicate C object description of %s, ' % name +
'other instance in ' + self.env.doc2path(inv[name][0]),
line=self.lineno)
inv[name] = (self.env.docname, self.objtype)
indextext = self.get_index_text(name)
if indextext:
if major == 1 and minor < 4:
# indexnode's tuple changed in 1.4
# https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c
self.indexnode['entries'].append(
('single', indextext, targetname, ''))
else:
self.indexnode['entries'].append(
('single', indextext, targetname, '', None))
class CDomain(Base_CDomain):
"""C language domain."""
name = 'c'
label = 'C'
directives = {
'function': CObject,
'member': CObject,
'macro': CObject,
'type': CObject,
'var': CObject,
}
Documentation/sphinx/kernel-doc.py
View file @ 02bafd96
...@@ -39,6 +39,8 @@ from docutils.parsers.rst import directives ...@@ -39,6 +39,8 @@ from docutils.parsers.rst import directives
from sphinx.util.compat import Directive from sphinx.util.compat import Directive
from sphinx.ext.autodoc import AutodocReporter from sphinx.ext.autodoc import AutodocReporter
__version__ = '1.0'
class KernelDocDirective(Directive): class KernelDocDirective(Directive):
"""Extract kernel-doc comments from the specified file""" """Extract kernel-doc comments from the specified file"""
required_argument = 1 required_argument = 1
...@@ -139,3 +141,9 @@ def setup(app): ...@@ -139,3 +141,9 @@ def setup(app):
app.add_config_value('kerneldoc_verbosity', 1, 'env') app.add_config_value('kerneldoc_verbosity', 1, 'env')
app.add_directive('kernel-doc', KernelDocDirective) app.add_directive('kernel-doc', KernelDocDirective)
return dict(
version = __version__,
parallel_read_safe = True,
parallel_write_safe = True
)
Documentation/sphinx/kernel_include.py
View file @ 02bafd96
...@@ -39,11 +39,18 @@ from docutils.parsers.rst import directives ...@@ -39,11 +39,18 @@ from docutils.parsers.rst import directives
from docutils.parsers.rst.directives.body import CodeBlock, NumberLines from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
from docutils.parsers.rst.directives.misc import Include from docutils.parsers.rst.directives.misc import Include
__version__ = '1.0'
# ============================================================================== # ==============================================================================
def setup(app): def setup(app):
# ============================================================================== # ==============================================================================
app.add_directive("kernel-include", KernelInclude) app.add_directive("kernel-include", KernelInclude)
return dict(
version = __version__,
parallel_read_safe = True,
parallel_write_safe = True
)
# ============================================================================== # ==============================================================================
class KernelInclude(Include): class KernelInclude(Include):
......
Documentation/sphinx/load_config.py 0 → 100644
View file @ 02bafd96
# -*- coding: utf-8; mode: python -*-
# pylint: disable=R0903, C0330, R0914, R0912, E0401
import os
import sys
from sphinx.util.pycompat import execfile_
# ------------------------------------------------------------------------------
def loadConfig(namespace):
# ------------------------------------------------------------------------------
u"""Load an additional configuration file into *namespace*.
The name of the configuration file is taken from the environment
``SPHINX_CONF``. The external configuration file extends (or overwrites) the
configuration values from the origin ``conf.py``. With this you are able to
maintain *build themes*. """
config_file = os.environ.get("SPHINX_CONF", None)
if (config_file is not None
and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ):
config_file = os.path.abspath(config_file)
if os.path.isfile(config_file):
sys.stdout.write("load additional sphinx-config: %s\n" % config_file)
config = namespace.copy()
config['__file__'] = config_file
execfile_(config_file, config)
del config['__file__']
namespace.update(config)
else:
sys.stderr.write("WARNING: additional sphinx-config not found: %s\n" % config_file)
Documentation/sphinx/parse-headers.pl
View file @ 02bafd96
...@@ -220,7 +220,7 @@ $data =~ s/\n\s+\n/\n\n/g; ...@@ -220,7 +220,7 @@ $data =~ s/\n\s+\n/\n\n/g;
# #
# Add escape codes for special characters # Add escape codes for special characters
# #
$data =~ s,([\_\`\*\<\>\&\\\\:\/\|]),\\$1,g; $data =~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g;
$data =~ s,DEPRECATED,**DEPRECATED**,g; $data =~ s,DEPRECATED,**DEPRECATED**,g;
......
Documentation/sphinx/rstFlatTable.py 100644 → 100755
View file @ 02bafd96
...@@ -73,6 +73,12 @@ def setup(app): ...@@ -73,6 +73,12 @@ def setup(app):
roles.register_local_role('cspan', c_span) roles.register_local_role('cspan', c_span)
roles.register_local_role('rspan', r_span) roles.register_local_role('rspan', r_span)
return dict(
version = __version__,
parallel_read_safe = True,
parallel_write_safe = True
)
# ============================================================================== # ==============================================================================
def c_span(name, rawtext, text, lineno, inliner, options=None, content=None): def c_span(name, rawtext, text, lineno, inliner, options=None, content=None):
# ============================================================================== # ==============================================================================
......
Documentation/stable_api_nonsense.txt
View file @ 02bafd96
.. _stable_api_nonsense:
The Linux Kernel Driver Interface The Linux Kernel Driver Interface
==================================
(all of your questions answered and then some) (all of your questions answered and then some)
Greg Kroah-Hartman <greg@kroah.com> Greg Kroah-Hartman <greg@kroah.com>
This is being written to try to explain why Linux does not have a binary This is being written to try to explain why Linux **does not have a binary
kernel interface, nor does it have a stable kernel interface. Please kernel interface, nor does it have a stable kernel interface**.
realize that this article describes the _in kernel_ interfaces, not the
kernel to userspace interfaces. The kernel to userspace interface is .. note::
the one that application programs use, the syscall interface. That
interface is _very_ stable over time, and will not break. I have old Please realize that this article describes the **in kernel** interfaces, not
programs that were built on a pre 0.9something kernel that still work the kernel to userspace interfaces.
just fine on the latest 2.6 kernel release. That interface is the one
that users and application programmers can count on being stable. The kernel to userspace interface is the one that application programs use,
the syscall interface. That interface is **very** stable over time, and
will not break. I have old programs that were built on a pre 0.9something
kernel that still work just fine on the latest 2.6 kernel release.
That interface is the one that users and application programmers can count
on being stable.
Executive Summary Executive Summary
...@@ -33,7 +42,7 @@ to worry about the in-kernel interfaces changing. For the majority of ...@@ -33,7 +42,7 @@ to worry about the in-kernel interfaces changing. For the majority of
the world, they neither see this interface, nor do they care about it at the world, they neither see this interface, nor do they care about it at
all. all.
First off, I'm not going to address _any_ legal issues about closed First off, I'm not going to address **any** legal issues about closed
source, hidden source, binary blobs, source wrappers, or any other term source, hidden source, binary blobs, source wrappers, or any other term
that describes kernel drivers that do not have their source code that describes kernel drivers that do not have their source code
released under the GPL. Please consult a lawyer if you have any legal released under the GPL. Please consult a lawyer if you have any legal
...@@ -51,19 +60,23 @@ Binary Kernel Interface ...@@ -51,19 +60,23 @@ Binary Kernel Interface
Assuming that we had a stable kernel source interface for the kernel, a Assuming that we had a stable kernel source interface for the kernel, a
binary interface would naturally happen too, right? Wrong. Please binary interface would naturally happen too, right? Wrong. Please
consider the following facts about the Linux kernel: consider the following facts about the Linux kernel:
- Depending on the version of the C compiler you use, different kernel - Depending on the version of the C compiler you use, different kernel
data structures will contain different alignment of structures, and data structures will contain different alignment of structures, and
possibly include different functions in different ways (putting possibly include different functions in different ways (putting
functions inline or not.) The individual function organization functions inline or not.) The individual function organization
isn't that important, but the different data structure padding is isn't that important, but the different data structure padding is
very important. very important.
- Depending on what kernel build options you select, a wide range of - Depending on what kernel build options you select, a wide range of
different things can be assumed by the kernel: different things can be assumed by the kernel:
- different structures can contain different fields - different structures can contain different fields
- Some functions may not be implemented at all, (i.e. some locks - Some functions may not be implemented at all, (i.e. some locks
compile away to nothing for non-SMP builds.) compile away to nothing for non-SMP builds.)
- Memory within the kernel can be aligned in different ways, - Memory within the kernel can be aligned in different ways,
depending on the build options. depending on the build options.
- Linux runs on a wide range of different processor architectures. - Linux runs on a wide range of different processor architectures.
There is no way that binary drivers from one architecture will run There is no way that binary drivers from one architecture will run
on another architecture properly. on another architecture properly.
...@@ -105,6 +118,7 @@ As a specific examples of this, the in-kernel USB interfaces have ...@@ -105,6 +118,7 @@ As a specific examples of this, the in-kernel USB interfaces have
undergone at least three different reworks over the lifetime of this undergone at least three different reworks over the lifetime of this
subsystem. These reworks were done to address a number of different subsystem. These reworks were done to address a number of different
issues: issues:
- A change from a synchronous model of data streams to an asynchronous - A change from a synchronous model of data streams to an asynchronous
one. This reduced the complexity of a number of drivers and one. This reduced the complexity of a number of drivers and
increased the throughput of all USB drivers such that we are now increased the throughput of all USB drivers such that we are now
...@@ -166,6 +180,7 @@ very little effort on your part. ...@@ -166,6 +180,7 @@ very little effort on your part.
The very good side effects of having your driver in the main kernel tree The very good side effects of having your driver in the main kernel tree
are: are:
- The quality of the driver will rise as the maintenance costs (to the - The quality of the driver will rise as the maintenance costs (to the
original developer) will decrease. original developer) will decrease.
- Other developers will add features to your driver. - Other developers will add features to your driver.
...@@ -175,7 +190,7 @@ are: ...@@ -175,7 +190,7 @@ are:
changes require it. changes require it.
- The driver automatically gets shipped in all Linux distributions - The driver automatically gets shipped in all Linux distributions
without having to ask the distros to add it. without having to ask the distros to add it.
As Linux supports a larger number of different devices "out of the box" As Linux supports a larger number of different devices "out of the box"
than any other operating system, and it supports these devices on more than any other operating system, and it supports these devices on more
different processor architectures than any other operating system, this different processor architectures than any other operating system, this
......
Documentation/stable_kernel_rules.txt
View file @ 02bafd96
Everything you ever wanted to know about Linux -stable releases. .. _stable_kernel_rules:
Everything you ever wanted to know about Linux -stable releases
===============================================================
Rules on what kind of patches are accepted, and which ones are not, into the Rules on what kind of patches are accepted, and which ones are not, into the
"-stable" tree: "-stable" tree:
...@@ -23,68 +26,94 @@ Rules on what kind of patches are accepted, and which ones are not, into the ...@@ -23,68 +26,94 @@ Rules on what kind of patches are accepted, and which ones are not, into the
race can be exploited is also provided. race can be exploited is also provided.
- It cannot contain any "trivial" fixes in it (spelling changes, - It cannot contain any "trivial" fixes in it (spelling changes,
whitespace cleanups, etc). whitespace cleanups, etc).
- It must follow the Documentation/SubmittingPatches rules. - It must follow the
:ref:`Documentation/SubmittingPatches <submittingpatches>`
rules.
- It or an equivalent fix must already exist in Linus' tree (upstream). - It or an equivalent fix must already exist in Linus' tree (upstream).
Procedure for submitting patches to the -stable tree: Procedure for submitting patches to the -stable tree
----------------------------------------------------
- If the patch covers files in net/ or drivers/net please follow netdev stable - If the patch covers files in net/ or drivers/net please follow netdev stable
submission guidelines as described in submission guidelines as described in
Documentation/networking/netdev-FAQ.txt Documentation/networking/netdev-FAQ.txt
- Security patches should not be handled (solely) by the -stable review - Security patches should not be handled (solely) by the -stable review
process but should follow the procedures in Documentation/SecurityBugs. process but should follow the procedures in
:ref:`Documentation/SecurityBugs <securitybugs>`.
For all other submissions, choose one of the following procedures
-----------------------------------------------------------------
.. _option_1:
For all other submissions, choose one of the following procedures: Option 1
********
--- Option 1 --- To have the patch automatically included in the stable tree, add the tag
.. code-block:: none
To have the patch automatically included in the stable tree, add the tag
Cc: stable@vger.kernel.org Cc: stable@vger.kernel.org
in the sign-off area. Once the patch is merged it will be applied to
the stable tree without anything else needing to be done by the author
or subsystem maintainer.
--- Option 2 --- in the sign-off area. Once the patch is merged it will be applied to
the stable tree without anything else needing to be done by the author
or subsystem maintainer.
.. _option_2:
After the patch has been merged to Linus' tree, send an email to Option 2
stable@vger.kernel.org containing the subject of the patch, the commit ID, ********
why you think it should be applied, and what kernel version you wish it to
be applied to.
--- Option 3 --- After the patch has been merged to Linus' tree, send an email to
stable@vger.kernel.org containing the subject of the patch, the commit ID,
why you think it should be applied, and what kernel version you wish it to
be applied to.
Send the patch, after verifying that it follows the above rules, to .. _option_3:
stable@vger.kernel.org. You must note the upstream commit ID in the
changelog of your submission, as well as the kernel version you wish
it to be applied to.
Option 1 is *strongly* preferred, is the easiest and most common. Options 2 and Option 3
3 are more useful if the patch isn't deemed worthy at the time it is applied to ********
a public git tree (for instance, because it deserves more regression testing
first). Option 3 is especially useful if the patch needs some special handling
to apply to an older kernel (e.g., if API's have changed in the meantime).
Note that for Option 3, if the patch deviates from the original upstream patch Send the patch, after verifying that it follows the above rules, to
(for example because it had to be backported) this must be very clearly stable@vger.kernel.org. You must note the upstream commit ID in the
documented and justified in the patch description. changelog of your submission, as well as the kernel version you wish
it to be applied to.
:ref:`option_1` is **strongly** preferred, is the easiest and most common.
:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed
worthy at the time it is applied to a public git tree (for instance, because
it deserves more regression testing first). :ref:`option_3` is especially
useful if the patch needs some special handling to apply to an older kernel
(e.g., if API's have changed in the meantime).
Note that for :ref:`option_3`, if the patch deviates from the original
upstream patch (for example because it had to be backported) this must be very
clearly documented and justified in the patch description.
The upstream commit ID must be specified with a separate line above the commit The upstream commit ID must be specified with a separate line above the commit
text, like this: text, like this:
.. code-block:: none
commit <sha1> upstream. commit <sha1> upstream.
Additionally, some patches submitted via Option 1 may have additional patch Additionally, some patches submitted via Option 1 may have additional patch
prerequisites which can be cherry-picked. This can be specified in the following prerequisites which can be cherry-picked. This can be specified in the following
format in the sign-off area: format in the sign-off area:
.. code-block:: none
Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic
Cc: <stable@vger.kernel.org> # 3.3.x Cc: <stable@vger.kernel.org> # 3.3.x
Signed-off-by: Ingo Molnar <mingo@elte.hu> Signed-off-by: Ingo Molnar <mingo@elte.hu>
The tag sequence has the meaning of:
.. code-block:: none
The tag sequence has the meaning of:
git cherry-pick a1f84a3 git cherry-pick a1f84a3
git cherry-pick 1b9508f git cherry-pick 1b9508f
git cherry-pick fd21073 git cherry-pick fd21073
...@@ -93,12 +122,17 @@ format in the sign-off area: ...@@ -93,12 +122,17 @@ format in the sign-off area:
Also, some patches may have kernel version prerequisites. This can be Also, some patches may have kernel version prerequisites. This can be
specified in the following format in the sign-off area: specified in the following format in the sign-off area:
.. code-block:: none
Cc: <stable@vger.kernel.org> # 3.3.x- Cc: <stable@vger.kernel.org> # 3.3.x-
The tag has the meaning of: The tag has the meaning of:
.. code-block:: none
git cherry-pick <this commit> git cherry-pick <this commit>
For each "-stable" tree starting with the specified version. For each "-stable" tree starting with the specified version.
Following the submission: Following the submission:
...@@ -109,7 +143,8 @@ Following the submission: ...@@ -109,7 +143,8 @@ Following the submission:
other developers and by the relevant subsystem maintainer. other developers and by the relevant subsystem maintainer.
Review cycle: Review cycle
------------
- When the -stable maintainers decide for a review cycle, the patches will be - When the -stable maintainers decide for a review cycle, the patches will be
sent to the review committee, and the maintainer of the affected area of sent to the review committee, and the maintainer of the affected area of
...@@ -125,17 +160,22 @@ Review cycle: ...@@ -125,17 +160,22 @@ Review cycle:
security kernel team, and not go through the normal review cycle. security kernel team, and not go through the normal review cycle.
Contact the kernel security team for more details on this procedure. Contact the kernel security team for more details on this procedure.
Trees: Trees
-----
- The queues of patches, for both completed versions and in progress - The queues of patches, for both completed versions and in progress
versions can be found at: versions can be found at:
http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git
- The finalized and tagged releases of all stable kernels can be found - The finalized and tagged releases of all stable kernels can be found
in separate branches per version at: in separate branches per version at:
http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git
Review committee: Review committee
----------------
- This is made up of a number of kernel developers who have volunteered for - This is made up of a number of kernel developers who have volunteered for
this task, and a few that haven't. this task, and a few that haven't.
Documentation/x86/x86_64/mm.txt
View file @ 02bafd96
...@@ -12,13 +12,13 @@ ffffc90000000000 - ffffe8ffffffffff (=45 bits) vmalloc/ioremap space ...@@ -12,13 +12,13 @@ ffffc90000000000 - ffffe8ffffffffff (=45 bits) vmalloc/ioremap space
ffffe90000000000 - ffffe9ffffffffff (=40 bits) hole ffffe90000000000 - ffffe9ffffffffff (=40 bits) hole
ffffea0000000000 - ffffeaffffffffff (=40 bits) virtual memory map (1TB) ffffea0000000000 - ffffeaffffffffff (=40 bits) virtual memory map (1TB)
... unused hole ... ... unused hole ...
ffffec0000000000 - fffffc0000000000 (=44 bits) kasan shadow memory (16TB) ffffec0000000000 - fffffbffffffffff (=44 bits) kasan shadow memory (16TB)
... unused hole ... ... unused hole ...
ffffff0000000000 - ffffff7fffffffff (=39 bits) %esp fixup stacks ffffff0000000000 - ffffff7fffffffff (=39 bits) %esp fixup stacks
... unused hole ... ... unused hole ...
ffffffef00000000 - ffffffff00000000 (=64 GB) EFI region mapping space ffffffef00000000 - fffffffeffffffff (=64 GB) EFI region mapping space
... unused hole ... ... unused hole ...
ffffffff80000000 - ffffffffa0000000 (=512 MB) kernel text mapping, from phys 0 ffffffff80000000 - ffffffff9fffffff (=512 MB) kernel text mapping, from phys 0
ffffffffa0000000 - ffffffffff5fffff (=1526 MB) module mapping space ffffffffa0000000 - ffffffffff5fffff (=1526 MB) module mapping space
ffffffffff600000 - ffffffffffdfffff (=8 MB) vsyscalls ffffffffff600000 - ffffffffffdfffff (=8 MB) vsyscalls
ffffffffffe00000 - ffffffffffffffff (=2 MB) unused hole ffffffffffe00000 - ffffffffffffffff (=2 MB) unused hole
......
MAINTAINERS
View file @ 02bafd96
...@@ -3139,7 +3139,7 @@ L: cocci@systeme.lip6.fr (moderated for non-subscribers) ...@@ -3139,7 +3139,7 @@ L: cocci@systeme.lip6.fr (moderated for non-subscribers)
T: git git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild.git misc T: git git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild.git misc
W: http://coccinelle.lip6.fr/ W: http://coccinelle.lip6.fr/
S: Supported S: Supported
F: Documentation/coccinelle.txt F: Documentation/dev-tools/coccinelle.rst
F: scripts/coccinelle/ F: scripts/coccinelle/
F: scripts/coccicheck F: scripts/coccicheck
...@@ -5148,7 +5148,7 @@ GCOV BASED KERNEL PROFILING ...@@ -5148,7 +5148,7 @@ GCOV BASED KERNEL PROFILING
M: Peter Oberparleiter <oberpar@linux.vnet.ibm.com> M: Peter Oberparleiter <oberpar@linux.vnet.ibm.com>
S: Maintained S: Maintained
F: kernel/gcov/ F: kernel/gcov/
F: Documentation/gcov.txt F: Documentation/dev-tools/gcov.rst
GDT SCSI DISK ARRAY CONTROLLER DRIVER GDT SCSI DISK ARRAY CONTROLLER DRIVER
M: Achim Leubner <achim_leubner@adaptec.com> M: Achim Leubner <achim_leubner@adaptec.com>
...@@ -5636,7 +5636,7 @@ M: Sebastian Reichel <sre@kernel.org> ...@@ -5636,7 +5636,7 @@ M: Sebastian Reichel <sre@kernel.org>
T: git git://git.kernel.org/pub/scm/linux/kernel/git/sre/linux-hsi.git T: git git://git.kernel.org/pub/scm/linux/kernel/git/sre/linux-hsi.git
S: Maintained S: Maintained
F: Documentation/ABI/testing/sysfs-bus-hsi F: Documentation/ABI/testing/sysfs-bus-hsi
F: Documentation/hsi.txt F: Documentation/device-drivers/serial-interfaces.rst
F: drivers/hsi/ F: drivers/hsi/
F: include/linux/hsi/ F: include/linux/hsi/
F: include/uapi/linux/hsi/ F: include/uapi/linux/hsi/
...@@ -6617,7 +6617,7 @@ L: kasan-dev@googlegroups.com ...@@ -6617,7 +6617,7 @@ L: kasan-dev@googlegroups.com
S: Maintained S: Maintained
F: arch/*/include/asm/kasan.h F: arch/*/include/asm/kasan.h
F: arch/*/mm/kasan_init* F: arch/*/mm/kasan_init*
F: Documentation/kasan.txt F: Documentation/dev-tools/kasan.rst
F: include/linux/kasan*.h F: include/linux/kasan*.h
F: lib/test_kasan.c F: lib/test_kasan.c
F: mm/kasan/ F: mm/kasan/
...@@ -6833,7 +6833,7 @@ KMEMCHECK ...@@ -6833,7 +6833,7 @@ KMEMCHECK
M: Vegard Nossum <vegardno@ifi.uio.no> M: Vegard Nossum <vegardno@ifi.uio.no>
M: Pekka Enberg <penberg@kernel.org> M: Pekka Enberg <penberg@kernel.org>
S: Maintained S: Maintained
F: Documentation/kmemcheck.txt F: Documentation/dev-tools/kmemcheck.rst
F: arch/x86/include/asm/kmemcheck.h F: arch/x86/include/asm/kmemcheck.h
F: arch/x86/mm/kmemcheck/ F: arch/x86/mm/kmemcheck/
F: include/linux/kmemcheck.h F: include/linux/kmemcheck.h
...@@ -6842,7 +6842,7 @@ F: mm/kmemcheck.c ...@@ -6842,7 +6842,7 @@ F: mm/kmemcheck.c
KMEMLEAK KMEMLEAK
M: Catalin Marinas <catalin.marinas@arm.com> M: Catalin Marinas <catalin.marinas@arm.com>
S: Maintained S: Maintained
F: Documentation/kmemleak.txt F: Documentation/dev-tools/kmemleak.rst
F: include/linux/kmemleak.h F: include/linux/kmemleak.h
F: mm/kmemleak.c F: mm/kmemleak.c
F: mm/kmemleak-test.c F: mm/kmemleak-test.c
......
Makefile
View file @ 02bafd96
...@@ -1425,7 +1425,7 @@ $(help-board-dirs): help-%: ...@@ -1425,7 +1425,7 @@ $(help-board-dirs): help-%:
# Documentation targets # Documentation targets
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
DOC_TARGETS := xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs
PHONY += $(DOC_TARGETS) PHONY += $(DOC_TARGETS)
$(DOC_TARGETS): scripts_basic FORCE $(DOC_TARGETS): scripts_basic FORCE
$(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
......
README
View file @ 02bafd96
...@@ -229,10 +229,6 @@ CONFIGURING the kernel: ...@@ -229,10 +229,6 @@ CONFIGURING the kernel:
under some circumstances lead to problems: probing for a under some circumstances lead to problems: probing for a
nonexistent controller card may confuse your other controllers nonexistent controller card may confuse your other controllers
- Compiling the kernel with "Processor type" set higher than 386
will result in a kernel that does NOT work on a 386. The
kernel will detect this on bootup, and give up.
- A kernel with math-emulation compiled in will still use the - A kernel with math-emulation compiled in will still use the
coprocessor if one is present: the math emulation will just coprocessor if one is present: the math emulation will just
never get used in that case. The kernel will be slightly larger, never get used in that case. The kernel will be slightly larger,
...@@ -289,7 +285,7 @@ COMPILING the kernel: ...@@ -289,7 +285,7 @@ COMPILING the kernel:
LOCALVERSION can be set in the "General Setup" menu. LOCALVERSION can be set in the "General Setup" menu.
- In order to boot your new kernel, you'll need to copy the kernel - In order to boot your new kernel, you'll need to copy the kernel
image (e.g. .../linux/arch/i386/boot/bzImage after compilation) image (e.g. .../linux/arch/x86/boot/bzImage after compilation)
to the place where your regular bootable kernel is found. to the place where your regular bootable kernel is found.
- Booting a kernel directly from a floppy without the assistance of a - Booting a kernel directly from a floppy without the assistance of a
...@@ -391,7 +387,7 @@ IF SOMETHING GOES WRONG: ...@@ -391,7 +387,7 @@ IF SOMETHING GOES WRONG:
- Alternatively, you can use gdb on a running kernel. (read-only; i.e. you - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you
cannot change values or set break points.) To do this, first compile the cannot change values or set break points.) To do this, first compile the
kernel with -g; edit arch/i386/Makefile appropriately, then do a "make kernel with -g; edit arch/x86/Makefile appropriately, then do a "make
clean". You'll also need to enable CONFIG_PROC_FS (via "make config"). clean". You'll also need to enable CONFIG_PROC_FS (via "make config").
After you've rebooted with the new kernel, do "gdb vmlinux /proc/kcore". After you've rebooted with the new kernel, do "gdb vmlinux /proc/kcore".
......
scripts/kernel-doc
View file @ 02bafd96
...@@ -212,6 +212,7 @@ my $anon_struct_union = 0; ...@@ -212,6 +212,7 @@ my $anon_struct_union = 0;
my $type_constant = '\%([-_\w]+)'; my $type_constant = '\%([-_\w]+)';
my $type_func = '(\w+)\(\)'; my $type_func = '(\w+)\(\)';
my $type_param = '\@(\w+)'; my $type_param = '\@(\w+)';
my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
my $type_struct = '\&((struct\s*)*[_\w]+)'; my $type_struct = '\&((struct\s*)*[_\w]+)';
my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)'; my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
my $type_env = '(\$\w+)'; my $type_env = '(\$\w+)';
...@@ -292,6 +293,7 @@ my @highlights_rst = ( ...@@ -292,6 +293,7 @@ my @highlights_rst = (
# Note: need to escape () to avoid func matching later # Note: need to escape () to avoid func matching later
[$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"], [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"],
[$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"], [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
[$type_fp_param, "**\$1\\\\(\\\\)**"],
[$type_func, "\\:c\\:func\\:`\$1()`"], [$type_func, "\\:c\\:func\\:`\$1()`"],
[$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
[$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
...@@ -412,7 +414,7 @@ my $doc_com_body = '\s*\* ?'; ...@@ -412,7 +414,7 @@ my $doc_com_body = '\s*\* ?';
my $doc_decl = $doc_com . '(\w+)'; my $doc_decl = $doc_com . '(\w+)';
# @params and a strictly limited set of supported section names # @params and a strictly limited set of supported section names
my $doc_sect = $doc_com . my $doc_sect = $doc_com .
'\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)'; '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
my $doc_content = $doc_com_body . '(.*)'; my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_inline_start = '^\s*/\*\*\s*$'; my $doc_inline_start = '^\s*/\*\*\s*$';
...@@ -1831,13 +1833,22 @@ sub output_function_rst(%) { ...@@ -1831,13 +1833,22 @@ sub output_function_rst(%) {
my %args = %{$_[0]}; my %args = %{$_[0]};
my ($parameter, $section); my ($parameter, $section);
my $oldprefix = $lineprefix; my $oldprefix = $lineprefix;
my $start; my $start = "";
print ".. c:function:: "; if ($args{'typedef'}) {
print ".. c:type:: ". $args{'function'} . "\n\n";
print_lineno($declaration_start_line);
print " **Typedef**: ";
$lineprefix = "";
output_highlight_rst($args{'purpose'});
$start = "\n\n**Syntax**\n\n ``";
} else {
print ".. c:function:: ";
}
if ($args{'functiontype'} ne "") { if ($args{'functiontype'} ne "") {
$start = $args{'functiontype'} . " " . $args{'function'} . " ("; $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
} else { } else {
$start = $args{'function'} . " ("; $start .= $args{'function'} . " (";
} }
print $start; print $start;
...@@ -1849,9 +1860,6 @@ sub output_function_rst(%) { ...@@ -1849,9 +1860,6 @@ sub output_function_rst(%) {
$count++; $count++;
$type = $args{'parametertypes'}{$parameter}; $type = $args{'parametertypes'}{$parameter};
# RST doesn't like address_space tags at function prototypes
$type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//;
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
# pointer-to-function # pointer-to-function
print $1 . $parameter . ") (" . $2; print $1 . $parameter . ") (" . $2;
...@@ -1859,11 +1867,15 @@ sub output_function_rst(%) { ...@@ -1859,11 +1867,15 @@ sub output_function_rst(%) {
print $type . " " . $parameter; print $type . " " . $parameter;
} }
} }
print ")\n\n"; if ($args{'typedef'}) {
print_lineno($declaration_start_line); print ");``\n\n";
$lineprefix = " "; } else {
output_highlight_rst($args{'purpose'}); print ")\n\n";
print "\n"; print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
print "\n";
}
print "**Parameters**\n\n"; print "**Parameters**\n\n";
$lineprefix = " "; $lineprefix = " ";
...@@ -2003,7 +2015,7 @@ sub output_struct_rst(%) { ...@@ -2003,7 +2015,7 @@ sub output_struct_rst(%) {
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
$type = $args{'parametertypes'}{$parameter}; $type = $args{'parametertypes'}{$parameter};
print_lineno($parameterdesc_start_lines{$parameter_name}); print_lineno($parameterdesc_start_lines{$parameter_name});
print "``$type $parameter``\n"; print "``" . $parameter . "``\n";
output_highlight_rst($args{'parameterdescs'}{$parameter_name}); output_highlight_rst($args{'parameterdescs'}{$parameter_name});
print "\n"; print "\n";
} }
...@@ -2193,7 +2205,9 @@ sub dump_typedef($$) { ...@@ -2193,7 +2205,9 @@ sub dump_typedef($$) {
$x =~ s@/\*.*?\*/@@gos; # strip comments. $x =~ s@/\*.*?\*/@@gos; # strip comments.
# Parse function prototypes # Parse function prototypes
if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) { if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
# Function typedefs # Function typedefs
$return_type = $1; $return_type = $1;
$declaration_name = $2; $declaration_name = $2;
...@@ -2204,6 +2218,7 @@ sub dump_typedef($$) { ...@@ -2204,6 +2218,7 @@ sub dump_typedef($$) {
output_declaration($declaration_name, output_declaration($declaration_name,
'function', 'function',
{'function' => $declaration_name, {'function' => $declaration_name,
'typedef' => 1,
'module' => $modulename, 'module' => $modulename,
'functiontype' => $return_type, 'functiontype' => $return_type,
'parameterlist' => \@parameterlist, 'parameterlist' => \@parameterlist,
...@@ -2338,6 +2353,7 @@ sub push_parameter($$$) { ...@@ -2338,6 +2353,7 @@ sub push_parameter($$$) {
if ($type eq "" && $param =~ /\.\.\.$/) if ($type eq "" && $param =~ /\.\.\.$/)
{ {
$param = "...";
if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
$parameterdescs{$param} = "variable arguments"; $parameterdescs{$param} = "variable arguments";
} }
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7