diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/ABI/README | 77 | ||||
-rw-r--r-- | Documentation/ABI/obsolete/devfs | 13 | ||||
-rw-r--r-- | Documentation/ABI/stable/syscalls | 10 | ||||
-rw-r--r-- | Documentation/ABI/stable/sysfs-module | 30 | ||||
-rw-r--r-- | Documentation/ABI/testing/sysfs-class | 16 | ||||
-rw-r--r-- | Documentation/ABI/testing/sysfs-devices | 25 |
6 files changed, 171 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 @@ | |||
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/ | ||
35 | This directory documents interfaces that are still remaining in | ||
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. | ||
39 | The file Documentation/feature-removal-schedule.txt may describe | ||
40 | some of these interfaces, giving a schedule for when they will | ||
41 | be removed. | ||
42 | |||
43 | removed/ | ||
44 | This directory contains a list of the old interfaces that have | ||
45 | been removed from the kernel. | ||
46 | |||
47 | Every file in these directories will contain the following information: | ||
48 | |||
49 | What: Short description of the interface | ||
50 | Date: Date created | ||
51 | KernelVersion: Kernel version this feature first showed up in. | ||
52 | Contact: Primary contact for this interface (may be a mailing list) | ||
53 | Description: Long description of the interface and how to use it. | ||
54 | Users: All users of this interface who wish to be notified when | ||
55 | it changes. This is very important for interfaces in | ||
56 | the "testing" stage, so that kernel developers can work | ||
57 | with userspace developers to ensure that things do not | ||
58 | break in ways that are unacceptable. It is also | ||
59 | important to get feedback for these interfaces to make | ||
60 | sure they are working in a proper way and do not need to | ||
61 | be changed further. | ||
62 | |||
63 | |||
64 | How things move between levels: | ||
65 | |||
66 | Interfaces in stable may move to obsolete, as long as the proper | ||
67 | notification is given. | ||
68 | |||
69 | Interfaces may be removed from obsolete and the kernel as long as the | ||
70 | documented amount of time has gone by. | ||
71 | |||
72 | Interfaces in the testing state can move to the stable state when the | ||
73 | developers feel they are finished. They cannot be removed from the | ||
74 | kernel tree without going through the obsolete state first. | ||
75 | |||
76 | It's up to the developer to place their interfaces in the category they | ||
77 | wish for it to start out in. | ||
diff --git a/Documentation/ABI/obsolete/devfs b/Documentation/ABI/obsolete/devfs new file mode 100644 index 000000000000..b8b87399bc8f --- /dev/null +++ b/Documentation/ABI/obsolete/devfs | |||
@@ -0,0 +1,13 @@ | |||
1 | What: devfs | ||
2 | Date: July 2005 | ||
3 | Contact: Greg Kroah-Hartman <gregkh@suse.de> | ||
4 | Description: | ||
5 | devfs has been unmaintained for a number of years, has unfixable | ||
6 | races, contains a naming policy within the kernel that is | ||
7 | against the LSB, and can be replaced by using udev. | ||
8 | The files fs/devfs/*, include/linux/devfs_fs*.h will be removed, | ||
9 | along with the the assorted devfs function calls throughout the | ||
10 | kernel tree. | ||
11 | |||
12 | Users: | ||
13 | |||
diff --git a/Documentation/ABI/stable/syscalls b/Documentation/ABI/stable/syscalls new file mode 100644 index 000000000000..c3ae3e7d6a0c --- /dev/null +++ b/Documentation/ABI/stable/syscalls | |||
@@ -0,0 +1,10 @@ | |||
1 | What: The kernel syscall interface | ||
2 | Description: | ||
3 | This interface matches much of the POSIX interface and is based | ||
4 | on it and other Unix based interfaces. It will only be added to | ||
5 | over time, and not have things removed from it. | ||
6 | |||
7 | Note that this interface is different for every architecture | ||
8 | that Linux supports. Please see the architecture-specific | ||
9 | documentation for details on the syscall numbers that are to be | ||
10 | mapped to each syscall. | ||
diff --git a/Documentation/ABI/stable/sysfs-module b/Documentation/ABI/stable/sysfs-module new file mode 100644 index 000000000000..75be43118335 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-module | |||
@@ -0,0 +1,30 @@ | |||
1 | What: /sys/module | ||
2 | Description: | ||
3 | The /sys/module tree consists of the following structure: | ||
4 | |||
5 | /sys/module/MODULENAME | ||
6 | The name of the module that is in the kernel. This | ||
7 | module name will show up either if the module is built | ||
8 | directly into the kernel, or if it is loaded as a | ||
9 | dyanmic module. | ||
10 | |||
11 | /sys/module/MODULENAME/parameters | ||
12 | This directory contains individual files that are each | ||
13 | individual parameters of the module that are able to be | ||
14 | changed at runtime. See the individual module | ||
15 | documentation as to the contents of these parameters and | ||
16 | what they accomplish. | ||
17 | |||
18 | Note: The individual parameter names and values are not | ||
19 | considered stable, only the fact that they will be | ||
20 | placed in this location within sysfs. See the | ||
21 | individual driver documentation for details as to the | ||
22 | stability of the different parameters. | ||
23 | |||
24 | /sys/module/MODULENAME/refcnt | ||
25 | If the module is able to be unloaded from the kernel, this file | ||
26 | will contain the current reference count of the module. | ||
27 | |||
28 | Note: If the module is built into the kernel, or if the | ||
29 | CONFIG_MODULE_UNLOAD kernel configuration value is not enabled, | ||
30 | this file will not be present. | ||
diff --git a/Documentation/ABI/testing/sysfs-class b/Documentation/ABI/testing/sysfs-class new file mode 100644 index 000000000000..4b0cb891e46e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class | |||
@@ -0,0 +1,16 @@ | |||
1 | What: /sys/class/ | ||
2 | Date: Febuary 2006 | ||
3 | Contact: Greg Kroah-Hartman <gregkh@suse.de> | ||
4 | Description: | ||
5 | The /sys/class directory will consist of a group of | ||
6 | subdirectories describing individual classes of devices | ||
7 | in the kernel. The individual directories will consist | ||
8 | of either subdirectories, or symlinks to other | ||
9 | directories. | ||
10 | |||
11 | All programs that use this directory tree must be able | ||
12 | to handle both subdirectories or symlinks in order to | ||
13 | work properly. | ||
14 | |||
15 | Users: | ||
16 | udev <linux-hotplug-devel@lists.sourceforge.net> | ||
diff --git a/Documentation/ABI/testing/sysfs-devices b/Documentation/ABI/testing/sysfs-devices new file mode 100644 index 000000000000..6a25671ee5f6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices | |||
@@ -0,0 +1,25 @@ | |||
1 | What: /sys/devices | ||
2 | Date: February 2006 | ||
3 | Contact: Greg Kroah-Hartman <gregkh@suse.de> | ||
4 | Description: | ||
5 | The /sys/devices tree contains a snapshot of the | ||
6 | internal state of the kernel device tree. Devices will | ||
7 | be added and removed dynamically as the machine runs, | ||
8 | and between different kernel versions, the layout of the | ||
9 | devices within this tree will change. | ||
10 | |||
11 | Please do not rely on the format of this tree because of | ||
12 | this. If a program wishes to find different things in | ||
13 | the tree, please use the /sys/class structure and rely | ||
14 | on the symlinks there to point to the proper location | ||
15 | within the /sys/devices tree of the individual devices. | ||
16 | Or rely on the uevent messages to notify programs of | ||
17 | devices being added and removed from this tree to find | ||
18 | the location of those devices. | ||
19 | |||
20 | Note that sometimes not all devices along the directory | ||
21 | chain will have emitted uevent messages, so userspace | ||
22 | programs must be able to handle such occurrences. | ||
23 | |||
24 | Users: | ||
25 | udev <linux-hotplug-devel@lists.sourceforge.net> | ||