|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.