[mirror_ubuntu-jammy-kernel.git] / Documentation / ABI / README

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.
Commit	Line	Data
c18f6365 GKH	1	This directory attempts to document the ABI between the Linux kernel and
	2	userspace, and the relative stability of these interfaces. Due to the
	3	everchanging nature of Linux, and the differing maturity levels, these
	4	interfaces should be used by userspace programs in different ways.
	5
	6	We have four different levels of ABI stability, as shown by the four
	7	different subdirectories in this location. Interfaces may change levels
	8	of stability according to the rules described below.
	9
	10	The different levels of stability are:
	11
	12	stable/
	13	This directory documents the interfaces that the developer has
	14	defined to be stable. Userspace programs are free to use these
	15	interfaces with no restrictions, and backward compatibility for
	16	them will be guaranteed for at least 2 years. Most interfaces
	17	(like syscalls) are expected to never change and always be
	18	available.
	19
	20	testing/
	21	This directory documents interfaces that are felt to be stable,
	22	as the main development of this interface has been completed.
	23	The interface can be changed to add new features, but the
	24	current interface will not break by doing this, unless grave
	25	errors or security problems are found in them. Userspace
	26	programs can start to rely on these interfaces, but they must be
	27	aware of changes that can occur before these interfaces move to
	28	be marked stable. Programs that use these interfaces are
	29	strongly encouraged to add their name to the description of
	30	these interfaces, so that the kernel developers can easily
	31	notify them if any changes occur (see the description of the
	32	layout of the files below for details on how to do this.)
	33
	34	obsolete/
c7e45ea4	35	This directory documents interfaces that are still remaining in
c18f6365 GKH	36	the kernel, but are marked to be removed at some later point in
	37	time. The description of the interface will document the reason
	38	why it is obsolete and when it can be expected to be removed.
c18f6365 GKH	39
	40	removed/
	41	This directory contains a list of the old interfaces that have
	42	been removed from the kernel.
	43
	44	Every file in these directories will contain the following information:
	45
	46	What: Short description of the interface
	47	Date: Date created
	48	KernelVersion: Kernel version this feature first showed up in.
	49	Contact: Primary contact for this interface (may be a mailing list)
	50	Description: Long description of the interface and how to use it.
	51	Users: All users of this interface who wish to be notified when
	52	it changes. This is very important for interfaces in
	53	the "testing" stage, so that kernel developers can work
	54	with userspace developers to ensure that things do not
	55	break in ways that are unacceptable. It is also
	56	important to get feedback for these interfaces to make
	57	sure they are working in a proper way and do not need to
	58	be changed further.
	59
	60
c7e45ea4 MCC	61	Note:
	62	The fields should be use a simple notation, compatible with ReST markup.
	63	Also, the file should not have a top-level index, like::
	64
	65	===
	66	foo
	67	===
	68
c18f6365 GKH	69	How things move between levels:
	70
	71	Interfaces in stable may move to obsolete, as long as the proper
	72	notification is given.
	73
	74	Interfaces may be removed from obsolete and the kernel as long as the
	75	documented amount of time has gone by.
	76
	77	Interfaces in the testing state can move to the stable state when the
	78	developers feel they are finished. They cannot be removed from the
	79	kernel tree without going through the obsolete state first.
	80
	81	It's up to the developer to place their interfaces in the category they
	82	wish for it to start out in.
ee2f51dc JT	83
	84
	85	Notable bits of non-ABI, which should not under any circumstances be considered
	86	stable:
	87
	88	- Kconfig. Userspace should not rely on the presence or absence of any
	89	particular Kconfig symbol, in /proc/config.gz, in the copy of .config
	90	commonly installed to /boot, or in any invocation of the kernel build
	91	process.
	92
	93	- Kernel-internal symbols. Do not rely on the presence, absence, location, or
	94	type of any kernel symbol, either in System.map files or the kernel binary
8c27ceff	95	itself. See Documentation/process/stable-api-nonsense.rst.