Messages in this thread | | | Date | Thu, 27 Apr 2006 14:35:28 -0700 | From | "Randy.Dunlap" <> | Subject | Re: [RFC] Add kernel<->userspace ABI stability documentation (try 2) |
| |
On Thu, 27 Apr 2006 14:10:12 -0700 Greg KH wrote:
> In short, we really need a way to document the different interfaces that > the kernel has between userspace and kernelspace. Traditionally this > has only been with the syscall interface, and a few odd proc files and > sysctls. In recent years that interface has grown to accommodate a > variety of ram-based filesystems, and other fun ways to get data in and > out of the kernel (netlink, connector, etc.) > > This patch proposes that _all_ kernel interfaces between userspace and > the kernel be documented in some manner. Now this doesn't mean that the > man-pages for the different syscalls need to be included here, but we > really need to try to get a handle of what is changing and what will be > affected if we do change things.
Yes. Thank you.
> -------------- > > --- /dev/null > +++ gregkh-2.6/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 > +ever changing nature of Linux, and the differing maturity levels, these everchanging
> +interfaces should be used by userspace programs in different ways. > + > +We have four different levels of ABI stability, as shown by the four > +different subdirectorys in this location. Interfaces may change levels subdirectories
> +of stability according to the rules described below. > + > +The different levels of stability are: > + > + stable/ > + This directory documents the interfaces that have the developer 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 simple interfaces (like syscalls) are expected to never > + change and always be available.
IMO "Most simple interfaces" isn't explicit enough. We could argue all day on which interfaces are simple and which are not.
> + > + 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 for drop ending "for"
> + 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 states:
s/states/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 can not be removed from the
"cannot"
> +kernel tree without going through the obsolete state first. > + > +It's up to the developer to place their interface in the category they
s/their/an/ better: s/their interface/interfaces/
> +wish for it to start out in. > --- /dev/null > +++ gregkh-2.6/Documentation/ABI/obsolete/devfs > @@ -0,0 +1,13 @@ > +What: devfs > +Date: July 2005 > +Contact: Greg Kroah-Hartman <gregkh@suse.de> > +Description: > + devfs has been unmaintained for a number of years, has unfixable > + races, contains a naming policy within the kernel that is > + against the LSB, and can be replaced by using udev. > + The files fs/devfs/*, include/linux/devfs_fs*.h will be removed, > + along with the the assorted devfs function calls throughout the > + kernel tree. > + > +Users: > + > --- /dev/null > +++ gregkh-2.6/Documentation/ABI/stable/syscalls > @@ -0,0 +1,10 @@ > +What: The kernel syscall interface > +Description: > + This interface matches much of the POSIX interface and is based > + on it and other Unix based interfaces. It will only be added to > + over time, and not have things removed from it. > + > + Note that this interface is different for every architecture > + that Linux supports. Please see the arch specific documentation
"arch-specific" or "architecture-specific"
> + for details on the syscall numbers that are to be mapped to each > + syscall. > --- /dev/null > +++ gregkh-2.6/Documentation/ABI/stable/sysfs-module > @@ -0,0 +1,29 @@ > +What: /sys/module > +Description: > + The /sys/module tree consists of the following structure: > + > + /sys/module/MODULENAME > + The name of the module that is in the kernel. > + This module name will show up both if the module is built s/both/either/
> + directly into the kernel, or if it is loaded as a dyanmic > + module. > + > + /sys/module/MODULENAME/parameters > + This directory contains individual files that are each > + individual parameters into the module that are are able to be drop one "are" s/into/of/
> + changed at runtime. See the individual module documentation as > + to the contents of these parameters and what they accomplish. > + > + Note: The individual parameter names and values are not > + considered stable, only the fact that they will be placed into s/into/in/
> + this location within sysfs. See the individual driver > + documentation for details as to the stability of the different > + parameters. > + > + /sys/module/MODULENAME/refcnt > + If the module is able to be unloaded from the kernel, this file > + will contain the current reference count of the module. > + > + Note: If the module is built into the kernel, or if the > + CONFIG_MODULE_UNLOAD kernel configuration value is not enabled, > + this file will not be present. > --- /dev/null > +++ gregkh-2.6/Documentation/ABI/testing/sysfs-class > @@ -0,0 +1,16 @@ > +What: /sys/class/ > +Date: Febuary 2006 > +Contact: Greg Kroah-Hartman <gregkh@suse.de> > +Description: > + The /sys/class directory will consist of a group of > + subdirectories describing individual classes of devices > + in the kernel. The individual directories will consist > + of either subdirectories, or symlinks to other > + directories. > + > + All programs that use this directory tree must be able > + to handle both subdirectories or symlinks in order to > + work properly. > + > +Users: > + udev <linux-hotplug-devel@lists.sourceforge.net> > --- /dev/null > +++ gregkh-2.6/Documentation/ABI/testing/sysfs-devices > @@ -0,0 +1,25 @@ > +What: /sys/devices > +Date: February 2006 > +Contact: Greg Kroah-Hartman <gregkh@suse.de> > +Description: > + The /sys/devices tree contains a snapshot of the > + internal state of the kernel device tree. Devices will > + be added and removed dynamically as the machine runs, > + and between different kernel versions, the layout of the > + devices within this tree will change. > + > + Please do not rely on the format of this tree because of > + this. If a program wishes to find different things in > + the tree, please use the /sys/class structure and rely > + on the symlinks there to point to the proper location > + within the /sys/devices tree of the individual devices. > + Or rely on the uevent messages to notify programs of > + devices being added and removed from this tree to find > + the location of those devices. > + > + Note that sometimes not all devices along the directory > + chain will have emitted uevent messages, so userspace > + programs must be able to handle such occurances. "occurrences"
So where is the uevent message interface documented?
> + > +Users: > + udev <linux-hotplug-devel@lists.sourceforge.net> > -
--- ~Randy - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
| |