[PATCH] Add kernel<->userspace ABI stability documentation

Signed-off-by: Kay Sievers <kay.sievers@suse.de>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

1 files changed, 77 insertions, 0 deletions

diff --git a/Documentation/ABI/README b/Documentation/ABI/README
new file mode 100644
index 000000000000..9feaf16f1617
--- /dev/null
+++ b/Documentation/ABI/README
@@ -0,0 +1,77 @@
+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.
+        The file Documentation/feature-removal-schedule.txt may describe
+        some of these interfaces, giving a schedule for when they will
+        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.
+
+
+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.