Orange Pi5 kernel

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