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