Diffstat (limited to 'Documentation')
1893 files changed, 392333 insertions, 0 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
new file mode 100644
@@ -0,0 +1,352 @@
+This is a brief list of all the files in ./linux/Documentation and what
+they contain. If you add a documentation file, please list it here in
+alphabetical order as well, or risk being hunted down like a rabid dog.
+Please try and keep the descriptions small enough to fit on one line.
+ Thanks -- Paul G.
+Following translations are available on the WWW:
+ - Japanese, maintained by the JF Project (JF@linux.or.jp), at
+ - this file.
+ - info on kernel <-> userspace ABI and relative interface stability.
+ - brute force method of doing binary search of patches to find bug.
+ - list of changes that break older software packages.
+ - how the boss likes the C code in the kernel to look.
+ - An extended tutorial on how to work with the kernel development
+ - DMA API, pci_ API & extensions for non-consistent memory machines.
+ - How to do DMA with ISA (and LPC) devices.
+ - directory with DocBook templates etc. for kernel documentation.
+ - the process and procedures of how to do Linux kernel development.
+ - info on Linux Intelligent Platform Management Interface (IPMI) Driver.
+ - how to select which CPU(s) handle which interrupt events on SMP.
+ - description of what an IRQ is.
+ - how to (attempt to) manage kernel hackers.
+ - directory with info on RCU (read-copy update).
+ - info on Secure Attention Keys.
+ - Silicon Motion SM501 multimedia companion chip
+ - procedure for reporting security bugs found in the kernel.
+ - Linux kernel patch submission checklist.
+ - procedure to get a new driver source included into the kernel tree.
+ - procedure to get a source patch included into the kernel tree.
+ - how to change your VGA cursor from a blinking underscore.
+ - documentation on accounting and taskstats.
+ - info on ACPI-specific hooks in the kernel.
+ - description of AoE (ATA over Ethernet) along with config examples.
+ - description of various trees and how to apply their patches.
+ - directory with info about Linux on the ARM architecture.
+ - semantics and behavior of atomic and bitmask operations.
+ - misc. LCD driver documentation (cfag12864b, ks0108).
+ - basic instructions for those who wants to profile Linux kernel.
+ - info on the kernel support for extra binary formats.
+ - directory with documentation for the Blackfin arch.
+ - info on the Block I/O (BIO) layer.
+ - info on block devices & drivers
+ - info on Marvell Bluetooth driver usage.
+ - how to access I/O mapped memory from within device drivers.
+ - describes the cache/TLB flushing interfaces Linux uses.
+ - directory with information on the CD-ROM drivers that Linux has.
+ - cgroups features, including cpusets and memory controller.
+ - docs on the netlink based userspace<->kernel space communication mod.
+ - documentation on Linux console drivers.
+ - info on CPU frequency and voltage scaling.
+ - document describing CPU hotplug support in the Linux kernel.
+ - document describing how CPU load statistics are collected.
+ - info on CPU_IDLE, CPU idle state management subsystem.
+ - documentation on how CPU topology info is exported via sysfs.
+ - directory with info about Linux on CRIS architecture.
+ - directory with info on the Crypto API.
+ - information on the Dell Systems Management Base Driver.
+ - some notes on debugging modules after Linux 2.6.3.
+ - document demonstrating the use of the Dell Remote BIOS Update driver.
+ - directory with info on Device Mapper.
+ - plain ASCII listing of all the nodes in /dev/ with major minor #'s.
+ - file containing a list of files that should never be diff'ed.
+ - directory with info about Linux driver model.
+ - info on Linux Digital Video Broadcast (DVB) subsystem.
+ - info about initramfs, klibc, and userspace early during boot.
+ - information on EDAC - Error Detection And Correction
+ - info on EISA bus support.
+ - dir with docs about the fault injection capabilities infrastructure.
+ - directory with info on the frame buffer graphics abstraction layer.
+ - list of files and features that are going to be removed.
+ - info on the vfs and the various filesystems that Linux supports.
+ - request_firmware() hotplug interface info.
+ - Fujitsu FR-V Linux documentation.
+ - overview of GPIO (General Purpose Input/Output) access conventions.
+ - notes on the change from 16 bit to 32 bit user/group IDs.
+ - info on the timer related topics
+ - info on Linux support for random number generator in i8xx chipsets.
+ - directory with docs on various hardware monitoring drivers.
+ - directory with info about the I2C bus/protocol (2 wire, kHz speed).
+ - directory with info about the Linux I2O subsystem.
+ - directory with info about Linux on Intel 32 bit architecture.
+ - directory with info about Linux on Intel 64 bit architecture.
+ - directory with documents concerning Linux InfiniBand support.
+ - how to use the RAM disk as an initial/temporary root filesystem.
+ - info on Linux input device support.
+ - description of io_mapping functions in linux/io-mapping.h
+ - info on ordering I/O writes to memory-mapped addresses.
+ - directory with documents describing various IOCTL calls.
+ - info on I/O statistics Linux kernel provides.
+ - how to use the irq-flags tracing feature.
+ - info on Linux ISA Plug & Play support.
+ - directory with info on the Linux ISDN support, and supported cards.
+ - info on the in-kernel binary support for Java(tm).
+ - directory with info about the kernel build process.
+ - directory with mini HowTo on getting the crash dump code to work.
+ - mini HowTo on generation and location of kernel documentation files.
+ - listing of various WWW + books that document kernel internals.
+ - summary listing of command line / boot prompt args for the kernel.
+ - info of the kobject infrastructure of the Linux kernel.
+ - documents the kernel probes debugging feature.
+ - docs on adding reference counters (krefs) to kernel objects.
+ - directory with laptop related info and laptop driver documentation.
+ - a brief description of LDM (Windows Dynamic Disks).
+ - directory with info about LED handling under Linux.
+ - semantics and behavior of local atomic operations.
+ - documentation on the runtime locking correctness validator.
+ - full colour GIF image of Linux logo (penguin - Tux).
+ - info on creator of above logo & site to get additional images from.
+ - directory with info about Linux on Motorola 68k architecture.
+ - list of magic numbers used to mark/protect kernel data structures.
+ - info on supporting Micro Channel Architecture (e.g. PS/2) systems.
+ - info on boot arguments for the multiple devices driver.
+ - info on Linux kernel memory barriers.
+ - Hotpluggable memory support, how to use and current status.
+ - info on typical Linux memory problems.
+ - directory with info about Linux on MIPS architecture.
+ - directory with info about the MMC subsystem
+ - how to execute Mono-based .NET binaries with the help of BINFMT_MISC.
+ - info on the generic mutex subsystem.
+ - directory with various information about namespaces
+ - directory with information on the NetLabel subsystem.
+ - directory with info on various aspects of networking with Linux.
+ - info on NMI watchdog for SMP systems.
+ - documentation about no-mmu memory mapping support.
+ - info on how to read Numa policy hit/miss statistics in sysfs.
+ - how to decode those nasty internal kernel error dump messages.
+ - An introduction to the "padata" parallel execution API
+ - directory with info on using Linux on PA-RISC architecture.
+ - how to use the parallel-port driver.
+ - description and usage of the low level parallel port functions.
+ - info on the Linux PCMCIA driver.
+ - documentation on lightweight PI-futexes.
+ - Linux Plug and Play documentation.
+ - directory with info on Linux PCI power management.
+ - directory with info on using Linux with the PowerPC.
+ - info on locking under a preemptive kernel.
+ - how to get printk format specifiers right
+ - info on radix-priority-search-tree use for indexing vmas.
+ - documentation of the ramoops oops/panic logging module.
+ - info on what red-black trees are and what they are for.
+ - documentation of the robust futex ABI.
+ - a description of what robust futexes are.
+ - description of the RealTime mutex implementation design.
+ - desc. of RT-mutex subsystem with PI (Priority Inheritance) support.
+ - notes on how to use the Real Time Clock (aka CMOS clock) driver.
+ - directory with info on using Linux on the IBM S390.
+ - directory with info on the scheduler.
+ - directory with info on Linux scsi support.
+ - directory that contains security-related info
+ - directory with info on the low level serial API.
+ - how to set up Linux with a serial line console as the default.
+ - description of the SGI IOC4 PCI (multi function) device.
+ - short blurb on the SGI Visual Workstations.
+ - directory with info on porting Linux to a new architecture.
+ - directory with info on sound card support.
+ - directory with info on using Linux on Sparc architecture.
+ - info on how to obtain and use the sparse tool for typechecking.
+ - overview of Linux kernel Serial Peripheral Interface (SPI) support.
+ - info on using spinlocks to provide exclusive access in kernel.
+ - info on why the kernel does not have a stable in-kernel api or abi.
+ - rules and procedures for the -stable kernel releases.
+ - short guide on selecting video modes at boot via VGA BIOS.
+ - How not to use sysfs.
+ - directory with info on the /proc/sys/* files.
+ - info on the magic SysRq key.
+ - directory with info on telephony (e.g. voice over IP) support.
+ - info on the Unicode character/font mapping used in Linux.
+ - description of the Linux unshare system call.
+ - directory with info regarding the Universal Serial Bus.
+ - sysfs class driver interface to enable/disable a video output device.
+ - directory with info regarding video/TV/radio cards and linux.
+ - directory with info on the Linux vm code.
+ - Why the "volatile" type class should not be used
+ - directory with documents regarding the 1-wire (w1) subsystem.
+ - how to auto-reboot Linux if it has "fallen and can't get up". ;-)
+ - directory with info on Linux support for AMD x86-64 (Hammer) machines.
+ - info on writing drivers for Zorro bus devices found on Amigas.
diff --git a/Documentation/ABI/README b/Documentation/ABI/README
new file mode 100644
@@ -0,0 +1,77 @@
+This directory attempts to document the ABI between the Linux kernel and
+userspace, and the relative stability of these interfaces. Due to the
+everchanging nature of Linux, and the differing maturity levels, these
+interfaces should be used by userspace programs in different ways.
+We have four different levels of ABI stability, as shown by the four
+different subdirectories in this location. Interfaces may change levels
+of stability according to the rules described below.
+The different levels of stability are:
+ This directory documents the interfaces that the developer has
+ defined to be stable. Userspace programs are free to use these
+ interfaces with no restrictions, and backward compatibility for
+ them will be guaranteed for at least 2 years. Most interfaces
+ (like syscalls) are expected to never change and always be
+ This directory documents interfaces that are felt to be stable,
+ as the main development of this interface has been completed.
+ The interface can be changed to add new features, but the
+ current interface will not break by doing this, unless grave
+ errors or security problems are found in them. Userspace
+ programs can start to rely on these interfaces, but they must be
+ aware of changes that can occur before these interfaces move to
+ be marked stable. Programs that use these interfaces are
+ strongly encouraged to add their name to the description of
+ these interfaces, so that the kernel developers can easily
+ notify them if any changes occur (see the description of the
+ layout of the files below for details on how to do this.)
+ This directory documents interfaces that are still remaining in
+ the kernel, but are marked to be removed at some later point in
+ time. The description of the interface will document the reason
+ why it is obsolete and when it can be expected to be removed.
+ The file Documentation/feature-removal-schedule.txt may describe
+ some of these interfaces, giving a schedule for when they will
+ be removed.
+ This directory contains a list of the old interfaces that have
+ been removed from the kernel.
+Every file in these directories will contain the following information:
+What: Short description of the interface
+Date: Date created
+KernelVersion: Kernel version this feature first showed up in.
+Contact: Primary contact for this interface (may be a mailing list)
+Description: Long description of the interface and how to use it.
+Users: All users of this interface who wish to be notified when
+ it changes. This is very important for interfaces in
+ the "testing" stage, so that kernel developers can work
+ with userspace developers to ensure that things do not
+ break in ways that are unacceptable. It is also
+ important to get feedback for these interfaces to make
+ sure they are working in a proper way and do not need to
+ be changed further.
+How things move between levels:
+Interfaces in stable may move to obsolete, as long as the proper
+notification is given.
+Interfaces may be removed from obsolete and the kernel as long as the
+documented amount of time has gone by.
+Interfaces in the testing state can move to the stable state when the
+developers feel they are finished. They cannot be removed from the
+kernel tree without going through the obsolete state first.
+It's up to the developer to place their interfaces in the category they
+wish for it to start out in.
diff --git a/Documentation/ABI/obsolete/proc-pid-oom_adj b/Documentation/ABI/obsolete/proc-pid-oom_adj
new file mode 100644
@@ -0,0 +1,22 @@
+When: August 2012
+Why: /proc/<pid>/oom_adj allows userspace to influence the oom killer's
+ badness heuristic used to determine which task to kill when the kernel
+ is out of memory.
+ The badness heuristic has since been rewritten since the introduction of
+ this tunable such that its meaning is deprecated. The value was
+ implemented as a bitshift on a score generated by the badness()
+ function that did not have any precise units of measure. With the
+ rewrite, the score is given as a proportion of available memory to the
+ task allocating pages, so using a bitshift which grows the score
+ exponentially is, thus, impossible to tune with fine granularity.
+ A much more powerful interface, /proc/<pid>/oom_score_adj, was
+ introduced with the oom killer rewrite that allows users to increase or
+ decrease the badness score linearly. This interface will replace
+ A warning will be emitted to the kernel log if an application uses this
+ deprecated interface. After it is printed once, future warnings will be
+ suppressed until the kernel is rebooted.
diff --git a/Documentation/ABI/obsolete/sysfs-bus-usb b/Documentation/ABI/obsolete/sysfs-bus-usb
new file mode 100644
@@ -0,0 +1,31 @@
+Date: March 2007
+Contact: Alan Stern <firstname.lastname@example.org>
+ Each USB device directory will contain a file named
+ power/level. This file holds a power-level setting for
+ the device, either "on" or "auto".
+ "on" means that the device is not allowed to autosuspend,
+ although normal suspends for system sleep will still
+ be honored. "auto" means the device will autosuspend
+ and autoresume in the usual manner, according to the
+ capabilities of its driver.
+ During normal use, devices should be left in the "auto"
+ level. The "on" level is meant for administrative uses.
+ If you want to suspend a device immediately but leave it
+ free to wake up in response to I/O requests, you should
+ write "0" to power/autosuspend.
+ Device not capable of proper suspend and resume should be
+ left in the "on" level. Although the USB spec requires
+ devices to support suspend/resume, many of them do not.
+ In fact so many don't that by default, the USB core
+ initializes all non-hub devices in the "on" level. Some
+ drivers may change this setting when they are bound.
+ This file is deprecated and will be removed after 2010.
+ Use the power/control file instead; it does exactly the
+ same thing.
diff --git a/Documentation/ABI/obsolete/sysfs-class-rfkill b/Documentation/ABI/obsolete/sysfs-class-rfkill
new file mode 100644
@@ -0,0 +1,29 @@
+rfkill - radio frequency (RF) connector kill switch support
+For details to this subsystem look at Documentation/rfkill.txt.
+Description: Current state of the transmitter.
+ This file is deprecated and sheduled to be removed in 2014,
+ because its not possible to express the 'soft and hard block'
+ state of the rfkill driver.
+Values: A numeric value.
+ 0: RFKILL_STATE_SOFT_BLOCKED
+ transmitter is turned off by software
+ 1: RFKILL_STATE_UNBLOCKED
+ transmitter is (potentially) active
+ 2: RFKILL_STATE_HARD_BLOCKED
+ transmitter is forced off by something outside of
+ the driver's control.
+Description: This file is deprecated because there no longer is a way to
+ claim just control over a single rfkill instance.
+ This file is scheduled to be removed in 2012.
+Values: 0: Kernel handles events
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus
new file mode 100644
@@ -0,0 +1,10 @@
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/startup_profile
+Date: October 2010
+Contact: Stefan Achatz <email@example.com>
+Description: The integer value of this attribute ranges from 0-4.
+ When read, this attribute returns the number of the actual
+ profile. This value is persistent, so its equivalent to the
+ profile that's active when the mouse is powered on next time.
+ When written, this file sets the number of the startup profile
+ and the mouse activates this profile immediately.
+ Please use actual_profile, it does the same thing.
diff --git a/Documentation/ABI/removed/devfs b/Documentation/ABI/removed/devfs
new file mode 100644
@@ -0,0 +1,12 @@
+Date: July 2005 (scheduled), finally removed in kernel v2.6.18
+Contact: Greg Kroah-Hartman <firstname.lastname@example.org>
+ devfs has been unmaintained for a number of years, has unfixable
+ races, contains a naming policy within the kernel that is
+ against the LSB, and can be replaced by using udev.
+ The files fs/devfs/*, include/linux/devfs_fs*.h were removed,
+ along with the assorted devfs function calls throughout the
+ kernel tree.
diff --git a/Documentation/ABI/removed/dv1394 b/Documentation/ABI/removed/dv1394
new file mode 100644
@@ -0,0 +1,14 @@
+What: dv1394 (a.k.a. "OHCI-DV I/O support" for FireWire)
+Date: May 2010 (scheduled), finally removed in kernel v2.6.37
+ /dev/dv1394/* were character device files, one for each FireWire
+ controller and for NTSC and PAL respectively, from which DV data
+ could be received by read() or transmitted by write(). A few
+ ioctl()s allowed limited control.
+ This special-purpose interface has been superseded by libraw1394 +
+ libiec61883 which are functionally equivalent, support HDV, and
+ transparently work on top of the newer firewire kernel drivers.
+ ffmpeg/libavformat (if configured for DV1394)
diff --git a/Documentation/ABI/removed/o2cb b/Documentation/ABI/removed/o2cb
new file mode 100644
@@ -0,0 +1,10 @@
+What: /sys/o2cb symlink
+Date: May 2011
+Description: This is a symlink: /sys/o2cb to /sys/fs/o2cb. The symlink is
+ removed when new versions of ocfs2-tools which know to look
+ in /sys/fs/o2cb are sufficiently prevalent. Don't code new
+ software to look here, it should try /sys/fs/o2cb instead.
+Users: ocfs2-tools. It's sufficient to mail proposed changes to