summaryrefslogtreecommitdiffstats
path: root/Documentation/ABI/README
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--Documentation/ABI/README95
1 files changed, 95 insertions, 0 deletions
diff --git a/Documentation/ABI/README b/Documentation/ABI/README
new file mode 100644
index 000000000..8bac9cb09
--- /dev/null
+++ b/Documentation/ABI/README
@@ -0,0 +1,95 @@
+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:
+
+ stable/
+ 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
+ available.
+
+ testing/
+ 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.)
+
+ obsolete/
+ 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.
+
+ 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.
+
+
+Note:
+ The fields should be use a simple notation, compatible with ReST markup.
+ Also, the file **should not** have a top-level index, like::
+
+ ===
+ foo
+ ===
+
+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.
+
+
+Notable bits of non-ABI, which should not under any circumstances be considered
+stable:
+
+- Kconfig. Userspace should not rely on the presence or absence of any
+ particular Kconfig symbol, in /proc/config.gz, in the copy of .config
+ commonly installed to /boot, or in any invocation of the kernel build
+ process.
+
+- Kernel-internal symbols. Do not rely on the presence, absence, location, or
+ type of any kernel symbol, either in System.map files or the kernel binary
+ itself. See Documentation/process/stable-api-nonsense.rst.