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.
0005
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.
0009
0010 The different levels of stability are:
0011
0012 stable/
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
0018 available.
0019
0020 testing/
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.)
0033
0034 obsolete/
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.
0039
0040 removed/
0041 This directory contains a list of the old interfaces that have
0042 been removed from the kernel.
0043
0044 Every file in these directories will contain the following information:
0045
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.
0059
0060
0061 Note:
0062 The fields should be use a simple notation, compatible with ReST markup.
0063 Also, the file **should not** have a top-level index, like::
0064
0065 ===
0066 foo
0067 ===
0068
0069 How things move between levels:
0070
0071 Interfaces in stable may move to obsolete, as long as the proper
0072 notification is given.
0073
0074 Interfaces may be removed from obsolete and the kernel as long as the
0075 documented amount of time has gone by.
0076
0077 Interfaces in the testing state can move to the stable state when the
0078 developers feel they are finished. They cannot be removed from the
0079 kernel tree without going through the obsolete state first.
0080
0081 It's up to the developer to place their interfaces in the category they
0082 wish for it to start out in.
0083
0084
0085 Notable bits of non-ABI, which should not under any circumstances be considered
0086 stable:
0087
0088 - Kconfig. Userspace should not rely on the presence or absence of any
0089 particular Kconfig symbol, in /proc/config.gz, in the copy of .config
0090 commonly installed to /boot, or in any invocation of the kernel build
0091 process.
0092
0093 - Kernel-internal symbols. Do not rely on the presence, absence, location, or
0094 type of any kernel symbol, either in System.map files or the kernel binary
0095 itself. See Documentation/process/stable-api-nonsense.rst.
