Browse Source

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.
 -----BEGIN PGP SIGNATURE-----
 
 iQIcBAABAgAGBQJX8st8AAoJEI3ONVYwIuV6d10P/0Zsnx3hSSx22aHxP4kVb4s/
 NTttFAienYzc2fYYD3K/wMQbSbprW8Pp7uSP1suzAbU5FGgfLyDFQHnE0AVqFNiT
 MHVc5oBWp4ZlvNcyQUeXOsKtb5Rin00XHjer2mm/T9HfgmCYR4i+C9HQuv+J94Jf
 sgeI4IimvLjlp7dDbhcIfdqCpZ+UwBSpSm9w5f7astYDjocJHrkBqyk/46Ir4qz9
 +2joNZRWMUatrQYJWMJnnvlnx8lHhkDjaL/Egy+f7ucpddEkbGvWvabGCSMtCyzS
 CKlA53Y4wS59cNFkAuxsHjun4TcQhbZn/iBIM+8aOdameO0ksC4jSoND2P6N6vKF
 dHkAkayP9ChW3k/J8D+3cGIJNFiaYevEXcgxLyShjCuh4t4yfOC9aIGUl3Ye9/mR
 tiKpMsvzmwJ+yO+kzJsxWTmRAX5wdI1Z062ltiS1dmSbl3c3NgQFpfP7V7AJSQ7c
 DzkuoUnGEqJOHm64dAZQuxL4jj6StzejjxlhH0bIjbNn1a9VlX9afwsdJaXA+kmr
 jQHJtR0wD1mLMYYdvNEiqvcCbumG+kaXmH6eUQadRxruRdZyhi1Z6Ql1CtwQGtbR
 SetC/MVxIN3fGPbZYhJ162xVjQ8OeX0ndRmRjy6SBDMoRGSKqi2IME8JAGOshxE0
 0uYAJJFZOeiR6KaPnci/
 =kGKl
 -----END PGP SIGNATURE-----

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
  ...
master
Linus Torvalds 5 years ago
parent
commit
02bafd96f3
  1. 264
      Documentation/Changes
  2. 2
      Documentation/CodeOfConflict
  3. 404
      Documentation/CodingStyle
  4. 8
      Documentation/DMA-API-HOWTO.txt
  5. 10
      Documentation/DocBook/Makefile
  6. 521
      Documentation/DocBook/device-drivers.tmpl
  7. 148
      Documentation/HOWTO
  8. 64
      Documentation/Makefile.sphinx
  9. 154
      Documentation/ManagementStyle
  10. 8
      Documentation/SecurityBugs
  11. 127
      Documentation/SubmitChecklist
  12. 54
      Documentation/SubmittingDrivers
  13. 312
      Documentation/SubmittingPatches
  14. 431
      Documentation/applying-patches.txt
  15. 11
      Documentation/arm/sunxi/README
  16. 42
      Documentation/clk.txt
  17. 104
      Documentation/conf.py
  18. 359
      Documentation/dev-tools/coccinelle.rst
  19. 256
      Documentation/dev-tools/gcov.rst
  20. 77
      Documentation/dev-tools/gdb-kernel-debugging.rst
  21. 173
      Documentation/dev-tools/kasan.rst
  22. 84
      Documentation/dev-tools/kcov.rst
  23. 733
      Documentation/dev-tools/kmemcheck.rst
  24. 93
      Documentation/dev-tools/kmemleak.rst
  25. 39
      Documentation/dev-tools/sparse.rst
  26. 25
      Documentation/dev-tools/tools.rst
  27. 42
      Documentation/dev-tools/ubsan.rst
  28. 68
      Documentation/development-process/1.Intro.rst
  29. 41
      Documentation/development-process/2.Process.rst
  30. 22
      Documentation/development-process/3.Early-stage.rst
  31. 46
      Documentation/development-process/4.Coding.rst
  32. 26
      Documentation/development-process/5.Posting.rst
  33. 14
      Documentation/development-process/6.Followthrough.rst
  34. 13
      Documentation/development-process/7.AdvancedTopics.rst
  35. 8
      Documentation/development-process/8.Conclusion.rst
  36. 10
      Documentation/development-process/conf.py
  37. 29
      Documentation/development-process/development-process.rst
  38. 9
      Documentation/development-process/index.rst
  39. 7
      Documentation/docutils.conf
  40. 120
      Documentation/driver-api/basics.rst
  41. 62
      Documentation/driver-api/frame-buffer.rst
  42. 88
      Documentation/driver-api/hsi.rst
  43. 46
      Documentation/driver-api/i2c.rst
  44. 26
      Documentation/driver-api/index.rst
  45. 169
      Documentation/driver-api/infrastructure.rst
  46. 51
      Documentation/driver-api/input.rst
  47. 12
      Documentation/driver-api/message-based.rst
  48. 50
      Documentation/driver-api/miscellaneous.rst
  49. 54
      Documentation/driver-api/sound.rst
  50. 53
      Documentation/driver-api/spi.rst
  51. 2
      Documentation/driver-model/device.txt
  52. 214
      Documentation/email-clients.txt
  53. 15
      Documentation/filesystems/dax.txt
  54. 2
      Documentation/filesystems/proc.txt
  55. 257
      Documentation/gcov.txt
  56. 5
      Documentation/gpu/conf.py
  57. 7
      Documentation/gpu/index.rst
  58. 75
      Documentation/hsi.txt
  59. 4
      Documentation/iio/iio_configfs.txt
  60. 11
      Documentation/index.rst
  61. 13
      Documentation/ioctl/botching-up-ioctls.txt
  62. 171
      Documentation/kasan.txt
  63. 39
      Documentation/kbuild/kconfig-language.txt
  64. 9
      Documentation/kdump/kdump.txt
  65. 1375
      Documentation/kernel-docs.txt
  66. 31
      Documentation/kernel-documentation.rst
  67. 24
      Documentation/kernel-parameters.txt
  68. 754
      Documentation/kmemcheck.txt
  69. 10
      Documentation/kprobes.txt
  70. 3
      Documentation/media/Makefile
  71. 10
      Documentation/media/conf.py
  72. 93
      Documentation/media/conf_nitpick.py
  73. 19
      Documentation/media/index.rst
  74. 2
      Documentation/media/uapi/cec/cec-func-open.rst
  75. 5
      Documentation/media/uapi/cec/cec-ioc-dqevent.rst
  76. 2
      Documentation/scsi/scsi-parameters.txt
  77. 5
      Documentation/serial/serial-rs485.txt
  78. 15
      Documentation/sphinx-static/theme_overrides.css
  79. 165
      Documentation/sphinx/cdomain.py
  80. 8
      Documentation/sphinx/kernel-doc.py
  81. 7
      Documentation/sphinx/kernel_include.py
  82. 32
      Documentation/sphinx/load_config.py
  83. 2
      Documentation/sphinx/parse-headers.pl
  84. 6
      Documentation/sphinx/rstFlatTable.py
  85. 37
      Documentation/stable_api_nonsense.txt
  86. 110
      Documentation/stable_kernel_rules.txt
  87. 6
      Documentation/x86/x86_64/mm.txt
  88. 12
      MAINTAINERS
  89. 2
      Makefile
  90. 8
      README
  91. 48
      scripts/kernel-doc

264
Documentation/Changes

@ -1,8 +1,13 @@
.. _changes:
Minimal requerements to compile the Kernel
++++++++++++++++++++++++++++++++++++++++++
Intro
=====
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
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
'net).
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
running, the suggested command should tell you.
@ -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,
you probably needn't concern yourself with isdn4k-utils.
o GNU C 3.2 # gcc --version
o GNU make 3.80 # make --version
o binutils 2.12 # ld -v
o util-linux 2.10o # fdformat --version
o module-init-tools 0.9.10 # depmod -V
o e2fsprogs 1.41.4 # e2fsck -V
o jfsutils 1.1.3 # fsck.jfs -V
o reiserfsprogs 3.6.3 # reiserfsck -V
o xfsprogs 2.6.0 # xfs_db -V
o squashfs-tools 4.0 # mksquashfs -version
o btrfs-progs 0.18 # btrfsck
o pcmciautils 004 # pccardctl -V
o quota-tools 3.09 # quota -V
o PPP 2.4.0 # pppd --version
o isdn4k-utils 3.1pre1 # isdnctrl 2>&1|grep version
o nfs-utils 1.0.5 # showmount --version
o procps 3.2.0 # ps --version
o oprofile 0.9 # oprofiled --version
o udev 081 # udevd --version
o grub 0.93 # grub --version || grub-install --version
o mcelog 0.6 # mcelog --version
o iptables 1.4.2 # iptables -V
o openssl & libcrypto 1.0.0 # openssl version
o bc 1.06.95 # bc --version
====================== =============== ========================================
Program Minimal version Command to check the version
====================== =============== ========================================
GNU C 3.2 gcc --version
GNU make 3.80 make --version
binutils 2.12 ld -v
util-linux 2.10o fdformat --version
module-init-tools 0.9.10 depmod -V
e2fsprogs 1.41.4 e2fsck -V
jfsutils 1.1.3 fsck.jfs -V
reiserfsprogs 3.6.3 reiserfsck -V
xfsprogs 2.6.0 xfs_db -V
squashfs-tools 4.0 mksquashfs -version
btrfs-progs 0.18 btrfsck
pcmciautils 004 pccardctl -V
quota-tools 3.09 quota -V
PPP 2.4.0 pppd --version
isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version
nfs-utils 1.0.5 showmount --version
procps 3.2.0 ps --version
oprofile 0.9 oprofiled --version
udev 081 udevd --version
grub 0.93 grub --version || grub-install --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
==================
******************
GCC
---
@ -64,16 +75,16 @@ You will need GNU make 3.80 or later to build the kernel.
Binutils
--------
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
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
your kernel. This change does, however, mean that you need a recent
release of binutils.
Perl
----
You will need perl 5 and the following modules: Getopt::Long, Getopt::Std,
File::Basename, and File::Find to build the kernel.
You will need perl 5 and the following modules: ``Getopt::Long``,
``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel.
BC
--
@ -93,7 +104,7 @@ and higher.
System utilities
================
****************
Architectural changes
---------------------
@ -115,7 +126,7 @@ well as the desired DocBook stylesheets.
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
types, have a fdformat which works with 2.4 kernels, and similar goodies.
You'll probably want to upgrade.
@ -125,54 +136,57 @@ Ksymoops
If the unthinkable happens and your kernel oopses, you may need the
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
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
with ksymoops.
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.
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.
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.
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:
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.
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
-------------
The reiserfsprogs package should be used for reiserfs-3.6.x
(Linux kernels 2.4.x). It is a combined package and contains working
versions of mkreiserfs, resize_reiserfs, debugreiserfs and
reiserfsck. These utils work on both i386 and alpha platforms.
versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and
``reiserfsck``. These utils work on both i386 and alpha platforms.
Xfsprogs
--------
The latest version of xfsprogs contains mkfs.xfs, xfs_db, and the
xfs_repair utilities, among others, for the XFS filesystem. It is
The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the
``xfs_repair`` utilities, among others, for the XFS filesystem. It is
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
later is recommended, due to some significant improvements).
@ -180,7 +194,7 @@ later is recommended, due to some significant improvements).
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
for 16-bit PCMCIA devices if the kernel is modularized and the hotplug
subsystem is used.
@ -198,19 +212,20 @@ 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
udev you may need to:
udev you may need to::
mkdir /dev/cpu
mknod /dev/cpu/microcode c 10 184
chmod 0644 /dev/cpu/microcode
mkdir /dev/cpu
mknod /dev/cpu/microcode c 10 184
chmod 0644 /dev/cpu/microcode
as root before you can use this. You'll probably also want to
get the user-space microcode_ctl utility to use with this.
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
devices.
@ -218,10 +233,10 @@ FUSE
----
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
==========
**********
General changes
---------------
@ -243,9 +258,9 @@ enable it to operate over diverse media layers. If you use PPP,
upgrade pppd to at least 2.4.0.
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.
@ -260,22 +275,22 @@ NFS-utils
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
information would be given to the kernel by "mountd" when the client
mounted the filesystem, or by "exportfs" at system startup. exportfs
would take information about active clients from /var/lib/nfs/rmtab.
information would be given to the kernel by ``mountd`` when the client
mounted the filesystem, or by ``exportfs`` at system startup. exportfs
would take information about active clients from ``/var/lib/nfs/rmtab``.
This approach is quite fragile as it depends on rmtab being correct
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.
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
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.
To enable this new functionality, you need to:
To enable this new functionality, you need to::
mount -t nfsd nfsd /proc/fs/nfsd
@ -287,8 +302,32 @@ mcelog
------
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
by the CPU. Processing them is strongly encouraged.
events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors
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
========================
@ -298,114 +337,149 @@ Kernel compilation
gcc
---
o <ftp://ftp.gnu.org/gnu/gcc/>
- <ftp://ftp.gnu.org/gnu/gcc/>
Make
----
o <ftp://ftp.gnu.org/gnu/make/>
- <ftp://ftp.gnu.org/gnu/make/>
Binutils
--------
o <ftp://ftp.kernel.org/pub/linux/devel/binutils/>
- <ftp://ftp.kernel.org/pub/linux/devel/binutils/>
OpenSSL
-------
o <https://www.openssl.org/>
- <https://www.openssl.org/>
System utilities
****************
Util-linux
----------
o <ftp://ftp.kernel.org/pub/linux/utils/util-linux/>
- <ftp://ftp.kernel.org/pub/linux/utils/util-linux/>
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
-----------------
o <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/>
- <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/>
Mkinitrd
--------
o <https://code.launchpad.net/initrd-tools/main>
- <https://code.launchpad.net/initrd-tools/main>
E2fsprogs
---------
o <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz>
- <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz>
JFSutils
--------
o <http://jfs.sourceforge.net/>
- <http://jfs.sourceforge.net/>
Reiserfsprogs
-------------
o <http://www.kernel.org/pub/linux/utils/fs/reiserfs/>
- <http://www.kernel.org/pub/linux/utils/fs/reiserfs/>
Xfsprogs
--------
o <ftp://oss.sgi.com/projects/xfs/>
- <ftp://oss.sgi.com/projects/xfs/>
Pcmciautils
-----------
o <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/>
- <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/>
Quota-tools
----------
o <http://sourceforge.net/projects/linuxquota/>
-----------
- <http://sourceforge.net/projects/linuxquota/>
DocBook Stylesheets
-------------------
o <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
XMLTO XSLT Frontend
-------------------
o <http://cyberelk.net/tim/xmlto/>
- <http://cyberelk.net/tim/xmlto/>
Intel P6 microcode
------------------
o <https://downloadcenter.intel.com/>
- <https://downloadcenter.intel.com/>
udev
----
o <http://www.freedesktop.org/software/systemd/man/udev.html>
- <http://www.freedesktop.org/software/systemd/man/udev.html>
FUSE
----
o <http://sourceforge.net/projects/fuse>
- <http://sourceforge.net/projects/fuse>
mcelog
------
o <http://www.mcelog.org/>
- <http://www.mcelog.org/>
Networking
**********
PPP
---
o <ftp://ftp.samba.org/pub/ppp/>
- <ftp://ftp.samba.org/pub/ppp/>
Isdn4k-utils
------------
o <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
- <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
NFS-utils
---------
o <http://sourceforge.net/project/showfiles.php?group_id=14>
- <http://sourceforge.net/project/showfiles.php?group_id=14>
Iptables
--------
o <http://www.iptables.org/downloads.html>
- <http://www.iptables.org/downloads.html>
Ip-route2
---------
o <https://www.kernel.org/pub/linux/utils/net/iproute2/>
- <https://www.kernel.org/pub/linux/utils/net/iproute2/>
OProfile
--------
o <http://oprofile.sf.net/download/>
- <http://oprofile.sf.net/download/>
NFS-Utils
---------
o <http://nfs.sourceforge.net/>
- <http://nfs.sourceforge.net/>
Kernel documentation
********************
Sphinx
------
- <http://www.sphinx-doc.org/>

2
Documentation/CodeOfConflict

@ -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
information on who is on the Technical Advisory Board and what their
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
the technical issues involved. We are all humans, and frustrations can

404
Documentation/CodingStyle

@ -1,8 +1,10 @@
.. _codingstyle:
Linux kernel coding style
Linux kernel coding style
=========================
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
able to maintain, and I'd prefer it for most other things too. Please
at least consider the points made here.
@ -13,7 +15,8 @@ and NOT read it. Burn them, it's a great symbolic gesture.
Anyway, here goes:
Chapter 1: Indentation
1) Indentation
--------------
Tabs are 8 characters, and thus indentations are also 8 characters.
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.
Heed that warning.
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
instead of "double-indenting" the "case" labels. E.g.:
to align the ``switch`` and its subordinate ``case`` labels in the same column
instead of ``double-indenting`` the ``case`` labels. E.g.:
.. code-block:: c
switch (suffix) {
case '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
something to hide:
.. code-block:: c
if (condition) do_this;
do_something_everytime;
@ -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.
Chapter 2: Breaking long lines and strings
2) Breaking long lines and strings
----------------------------------
Coding style is all about readability and maintainability using commonly
available tools.
@ -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.
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
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
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:
.. code-block:: c
if (x is true) {
we do y
}
@ -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,
while, do). E.g.:
.. code-block:: c
switch (action) {
case KOBJ_ADD:
return "add";
@ -116,6 +129,8 @@ while, do). E.g.:
However, there is one special case, namely functions: they have the
opening brace at the beginning of the next line, thus:
.. code-block:: c
int function(int x)
{
body of function
@ -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
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).
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,
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:
.. code-block:: c
do {
body of do-loop
} while (condition);
and
.. code-block:: c
if (x == y) {
..
} else if (x > y) {
@ -155,11 +174,15 @@ comments on.
Do not unnecessarily use braces where a single statement will do.
.. code-block:: c
if (condition)
action();
and
.. code-block:: none
if (condition)
do_this();
else
@ -168,6 +191,8 @@ and
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:
.. code-block:: c
if (condition) {
do_this();
do_that();
@ -175,57 +200,67 @@ statement; in the latter case use braces in both branches:
otherwise();
}
3.1: Spaces
3.1) Spaces
***********
Linux kernel style for use of spaces depends (mostly) on
function-versus-keyword usage. Use a space after (most) keywords. The
notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
somewhat like functions (and are usually used with parentheses in Linux,
although they are not required in the language, as in: "sizeof info" after
"struct fileinfo info;" is declared).
although they are not required in the language, as in: ``sizeof info`` after
``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
but not with sizeof, typeof, alignof, or __attribute__. E.g.,
.. code-block:: c
s = sizeof(struct file);
Do not add spaces around (inside) parenthesized expressions. This example is
*bad*:
**bad**:
.. code-block:: c
s = sizeof( struct file );
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:
.. code-block:: c
char *linux_banner;
unsigned long long memparse(char *ptr, char **retptr);
char *match_strdup(substring_t *s);
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
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
"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.
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,
@ -237,22 +272,23 @@ of patches, this may make later patches in the series fail by changing their
context lines.
Chapter 4: Naming
4) Naming
---------
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
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.
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.
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
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
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
makes buggy programs.
LOCAL variable names should be short, and to the point. If you have
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
being mis-understood. Similarly, "tmp" can be just about any type of
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
being mis-understood. Similarly, ``tmp`` can be just about any type of
variable that is used to hold a temporary value.
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.
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;
in the source, what does it mean?
In contrast, if it says
.. code-block:: c
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:
(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).
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.
NOTE! 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.
.. note::
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
whether it is "int" or "long".
(b) Clear integer types, where the abstraction **helps** avoid confusion
whether it is ``int`` or ``long``.
u8/u16/u32 are perfectly fine typedefs, although they fit into
category (d) better than here.
NOTE! Again - there needs to be a _reason_ for this. If something is
"unsigned long", then there's no reason to do
.. note::
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;
but if there is a clear reason for why it under certain circumstances
might be an "unsigned int" and under other configurations might be
"unsigned long", then by all means go ahead and use a typedef.
might be an ``unsigned int`` and under other configurations might be
``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.
(d) New types which are identical to standard C99 types, in certain
exceptional circumstances.
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.
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
permitted -- although they are not mandatory in new code of your
own.
@ -333,7 +379,7 @@ useful only for:
(e) Types safe for use in userspace.
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
with userspace.
@ -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.
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
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
to understand what you did 2 weeks from now.
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
function brace line. E.g.:
exported, the **EXPORT** macro for it should follow immediately after the
closing function brace line. E.g.:
.. code-block:: c
int system_is_up(void)
{
@ -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.
Chapter 7: Centralized exiting of functions
7) Centralized exiting of functions
-----------------------------------
Albeit deprecated by some people, the equivalent of the goto statement is
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
cleanup needed then just return directly.
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
using GW-BASIC names like "err1:" and "err2:". Also don't name them after the
goto location like "err_kmalloc_failed:"
example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``.
Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to
renumber them if you ever add or remove exit paths, and they make correctness
difficult to verify anyway.
The rationale for using gotos is:
- unconditional statements are easier to understand and follow
- nesting is reduced
- errors by not updating individual exit points when making
modifications are prevented
modifications are prevented
- saves the compiler work to optimize redundant code away ;)
.. code-block:: c
int fun(int a)
{
int result = 0;
@ -425,27 +478,41 @@ The rationale for using gotos is:
goto out_buffer;
}
...
out_buffer:
out_free_buffer:
kfree(buffer);
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:
kfree(foo->bar);
kfree(foo);
return ret;
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:".
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_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
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.
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.
See the files Documentation/kernel-documentation.rst and scripts/kernel-doc
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:
.. code-block:: c
/*
* This is the preferred style for multi-line
* comments in the Linux kernel source code.
@ -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)
comments is a little different.
.. code-block:: c
/* The preferred comment style for files in net/ and drivers/net
* looks like this.
*
@ -491,10 +559,11 @@ multiple data declarations). This leaves you room for a small comment on each
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
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
uses are less than desirable (in fact, they are worse than random
typing - an infinite number of monkeys typing into GNU emacs would never
@ -503,63 +572,66 @@ make a good program).
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:
(defun c-lineup-arglist-tabs-only (ignored)
"Line up argument lists by tabs, not spaces"
(let* ((anchor (c-langelem-pos c-syntactic-element))
(column (c-langelem-2nd-pos c-syntactic-element))
(offset (- (1+ column) anchor))
(steps (floor offset c-basic-offset)))
(* (max steps 1)
c-basic-offset)))
(add-hook 'c-mode-common-hook
(lambda ()
;; Add kernel style
(c-add-style
"linux-tabs-only"
'("linux" (c-offsets-alist
(arglist-cont-nonempty
c-lineup-gcc-asm-reg
c-lineup-arglist-tabs-only))))))
(add-hook 'c-mode-hook
(lambda ()
(let ((filename (buffer-file-name)))
;; Enable kernel mode for the appropriate files
(when (and filename
(string-match (expand-file-name "~/src/linux-trees")
filename))
(setq indent-tabs-mode t)
(setq show-trailing-whitespace t)
(c-set-style "linux-tabs-only")))))
.. code-block:: none
(defun c-lineup-arglist-tabs-only (ignored)
"Line up argument lists by tabs, not spaces"
(let* ((anchor (c-langelem-pos c-syntactic-element))
(column (c-langelem-2nd-pos c-syntactic-element))
(offset (- (1+ column) anchor))
(steps (floor offset c-basic-offset)))
(* (max steps 1)
c-basic-offset)))
(add-hook 'c-mode-common-hook
(lambda ()
;; Add kernel style
(c-add-style
"linux-tabs-only"
'("linux" (c-offsets-alist
(arglist-cont-nonempty
c-lineup-gcc-asm-reg
c-lineup-arglist-tabs-only))))))
(add-hook 'c-mode-hook
(lambda ()
(let ((filename (buffer-file-name)))
;; Enable kernel mode for the appropriate files
(when (and filename
(string-match (expand-file-name "~/src/linux-trees")
filename))
(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
files below ~/src/linux-trees.
files below ``~/src/linux-trees``.
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
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
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
options "-kr -i8" (stands for "K&R, 8 character indents"), or use
"scripts/Lindent", which indents in the latest style.
options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
``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
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,
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
spaces. Example:
spaces. Example::
config AUDIT
config AUDIT
bool "Auditing support"
depends on NET
help
@ -569,9 +641,9 @@ config AUDIT
auditing without CONFIG_AUDITSYSCALL.
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)"
depends on ADFS_FS
...
@ -580,41 +652,45 @@ For full documentation on the configuration files, see the file
Documentation/kbuild/kconfig-language.txt.
Chapter 11: Data structures
11) Data structures
-------------------
Data structures that have visibility outside the single-threaded
environment they are created and destroyed in should always have
reference counts. In the kernel, garbage collection doesn't exist (and
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
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
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
counting is a memory management technique. Usually both are needed, and
they are not to be confused with each other.
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
when the subclass count goes to zero.
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
filesystem code ("struct super_block": s_count and s_active).
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
filesystem code (``struct super_block``: s_count and s_active).
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.
Chapter 12: Macros, Enums and RTL
12) Macros, Enums and RTL
-------------------------
Names of macros defining constants and labels in enums are capitalized.
.. code-block:: c
#define CONSTANT 0x12345
Enums are preferred when defining several related constants.
@ -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:
#define macrofun(a, b, c) \
.. code-block:: c
#define macrofun(a, b, c) \
do { \
if (a == 5) \
do_this(b, c); \
@ -636,17 +714,21 @@ Things to avoid when using macros:
1) macros that affect control flow:
.. code-block:: c
#define FOO(x) \
do { \
if (blah(x) < 0) \
return -EBUGGERED; \
} 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.
2) macros that depend on having a local variable with a magic name:
.. code-block:: c
#define FOO(val) bar(index, val)
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.
must enclose the expression in parentheses. Beware of similar issues with
macros using parameters.
.. code-block:: c
#define CONSTANT 0x4000
#define CONSTEXP (CONSTANT | 3)
5) namespace collisions when defining local variables in macros resembling
functions:
#define FOO(x) \
({ \
typeof(x) ret; \
ret = calc_ret(x); \
(ret); \
})
.. code-block:: c
#define FOO(x) \
({ \
typeof(x) ret; \
ret = calc_ret(x); \
(ret); \
})
ret is a common name for a local variable - __foo_ret is less likely
to collide with an existing variable.
@ -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.
Chapter 13: Printing kernel messages
13) Printing kernel messages
----------------------------
Kernel developers like to be seen as literate. Do mind the spelling
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.
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
used.
Chapter 14: Allocating memory
14) Allocating memory
---------------------
The kernel provides the following general purpose memory allocators:
kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
@ -722,6 +810,8 @@ about them.
The preferred form for passing a size of a struct is the following:
.. code-block:: c
p = kmalloc(sizeof(*p), ...);
The alternative form where struct name is spelled out hurts readability and
@ -734,20 +824,25 @@ language.
The preferred form for allocating an array is the following:
.. code-block:: c
p = kmalloc_array(n, sizeof(...), ...);
The preferred form for allocating a zeroed array is the following:
.. code-block:: c
p = kcalloc(n, sizeof(...), ...);
Both forms check for overflow on the allocation size n * sizeof(...),
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
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
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
@ -771,26 +866,27 @@ appears outweighs the potential value of the hint that tells gcc to do
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
most common is a value indicating whether the function succeeded or
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).
Mixing up these two sorts of representations is a fertile source of
difficult-to-find bugs. If the C language included a strong distinction
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
convention:
convention::
If the name of a function is an action or an imperative command,
the function should return an error-code integer. If the name
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 success or -EBUSY for failure. In the same way, "PCI device present" is
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
a predicate, and the pci_dev_present() function returns 1 if it succeeds in
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
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
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
of the macro
.. code-block:: c
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
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))
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
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,
indicated with special markers. For example, emacs interprets lines marked
like this:
.. code-block:: c
-*- mode: c -*-
Or like this:
.. code-block:: c
/*
Local Variables:
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
@ -841,6 +947,8 @@ Or like this:
Vim interprets markers that look like this:
.. code-block:: c
/* vim:set sw=8 noet */
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
work correctly.
Chapter 19: Inline assembly
19) Inline assembly
-------------------
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.
@ -863,7 +972,7 @@ that inline assembly can use C parameters.
Large, non-trivial assembly functions should go in .S files, with corresponding
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
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
string, and end each string except the last with \n\t to properly indent the
next instruction in the assembly output:
.. code-block:: c
asm ("magic %reg1, #42\n\t"
"more_magic %reg2, %reg3"
: /* outputs */ : /* inputs */ : /* clobbers */);
Chapter 20: Conditional Compilation
20) Conditional Compilation
---------------------------
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,
@ -903,6 +1015,8 @@ unused, delete it.)
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:
.. code-block:: c
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),
place a comment after the #endif on the same line, noting the conditional
expression used. For instance:
.. code-block:: c
#ifdef CONFIG_SOMETHING
...
#endif /* CONFIG_SOMETHING */
Appendix I: References
Appendix I) References
----------------------
The C Programming Language, Second Edition
by Brian W. Kernighan and Dennis M. Ritchie.
@ -943,4 +1060,3 @@ language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
Kernel CodingStyle, by greg@kroah.com at OLS 2002:
http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/

8
Documentation/DMA-API-HOWTO.txt

@ -699,7 +699,7 @@ to use the dma_sync_*() interfaces.
dma_addr_t mapping;
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,
* delay and try again later or
@ -931,10 +931,8 @@ to "Closing".
1) Struct scatterlist requirements.
Don't invent the architecture specific struct scatterlist; just use
<asm-generic/scatterlist.h>. You need to enable
CONFIG_NEED_SG_DMA_LENGTH if the architecture supports IOMMUs
(including software IOMMU).
You need to enable CONFIG_NEED_SG_DMA_LENGTH if the architecture
supports IOMMUs (including software IOMMU).
2) ARCH_DMA_MINALIGN

10
Documentation/DocBook/Makefile

@ -6,7 +6,7 @@
# To add a new book the only step required is to add the book to the
# list of DOCBOOKS.
DOCBOOKS := z8530book.xml device-drivers.xml \
DOCBOOKS := z8530book.xml \
kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
writing_usb_driver.xml networking.xml \
kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
@ -22,9 +22,15 @@ ifeq ($(DOCBOOKS),)
# Skip DocBook build if the user explicitly requested no DOCBOOKS.
.DEFAULT:
@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
###
# The build process is as follows (targets):
# (xmldocs) [by docproc]
@ -66,6 +72,7 @@ installmandocs: mandocs
# no-op for the DocBook toolchain
epubdocs:
latexdocs:
###
#External programs used
@ -221,6 +228,7 @@ silent_gen_xml = :
echo "</programlisting>") > $@
endif # DOCBOOKS=""
endif # SPHINDIR=...
###
# Help targets as used by the top-level makefile

521
Documentation/DocBook/device-drivers.tmpl

@ -1,521 +0,0 @@
<?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>
</