0001 This directory attempts to document the ABI between the Linux kernel and
0002 userspace, and the relative stability of these interfaces. Due to the
0003 everchanging nature of Linux, and the differing maturity levels, these
0004 interfaces should be used by userspace programs in different ways.
0006 We have four different levels of ABI stability, as shown by the four
0007 different subdirectories in this location. Interfaces may change levels
0008 of stability according to the rules described below.
0010 The different levels of stability are:
0013 This directory documents the interfaces that the developer has
0014 defined to be stable. Userspace programs are free to use these
0015 interfaces with no restrictions, and backward compatibility for
0016 them will be guaranteed for at least 2 years. Most interfaces
0017 (like syscalls) are expected to never change and always be
0021 This directory documents interfaces that are felt to be stable,
0022 as the main development of this interface has been completed.
0023 The interface can be changed to add new features, but the
0024 current interface will not break by doing this, unless grave
0025 errors or security problems are found in them. Userspace
0026 programs can start to rely on these interfaces, but they must be
0027 aware of changes that can occur before these interfaces move to
0028 be marked stable. Programs that use these interfaces are
0029 strongly encouraged to add their name to the description of
0030 these interfaces, so that the kernel developers can easily
0031 notify them if any changes occur (see the description of the
0032 layout of the files below for details on how to do this.)
0035 This directory documents interfaces that are still remaining in
0036 the kernel, but are marked to be removed at some later point in
0037 time. The description of the interface will document the reason
0038 why it is obsolete and when it can be expected to be removed.
0041 This directory contains a list of the old interfaces that have
0042 been removed from the kernel.
0044 Every file in these directories will contain the following information:
0046 What: Short description of the interface
0047 Date: Date created
0048 KernelVersion: Kernel version this feature first showed up in.
0049 Contact: Primary contact for this interface (may be a mailing list)
0050 Description: Long description of the interface and how to use it.
0051 Users: All users of this interface who wish to be notified when
0052 it changes. This is very important for interfaces in
0053 the "testing" stage, so that kernel developers can work
0054 with userspace developers to ensure that things do not
0055 break in ways that are unacceptable. It is also
0056 important to get feedback for these interfaces to make
0057 sure they are working in a proper way and do not need to
0058 be changed further.
0061 How things move between levels:
0063 Interfaces in stable may move to obsolete, as long as the proper
0064 notification is given.
0066 Interfaces may be removed from obsolete and the kernel as long as the
0067 documented amount of time has gone by.
0069 Interfaces in the testing state can move to the stable state when the
0070 developers feel they are finished. They cannot be removed from the
0071 kernel tree without going through the obsolete state first.
0073 It's up to the developer to place their interfaces in the category they
0074 wish for it to start out in.
0077 Notable bits of non-ABI, which should not under any circumstances be considered
0080 - Kconfig. Userspace should not rely on the presence or absence of any
0081 particular Kconfig symbol, in /proc/config.gz, in the copy of .config
0082 commonly installed to /boot, or in any invocation of the kernel build
0085 - Kernel-internal symbols. Do not rely on the presence, absence, location, or
0086 type of any kernel symbol, either in System.map files or the kernel binary
0087 itself. See Documentation/process/stable-api-nonsense.rst.