Back to home page

LXR

 
 

    


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 How things move between levels:
0062 
0063 Interfaces in stable may move to obsolete, as long as the proper
0064 notification is given.
0065 
0066 Interfaces may be removed from obsolete and the kernel as long as the
0067 documented amount of time has gone by.
0068 
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.
0072 
0073 It's up to the developer to place their interfaces in the category they
0074 wish for it to start out in.
0075 
0076 
0077 Notable bits of non-ABI, which should not under any circumstances be considered
0078 stable:
0079 
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
0083   process.
0084 
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.