Messages in this thread | | | Date | Thu, 27 Apr 2006 15:01:22 -0700 | From | Greg KH <> | Subject | Re: [RFC] Add kernel<->userspace ABI stability documentation (try 2) |
| |
On Thu, Apr 27, 2006 at 02:35:28PM -0700, Randy.Dunlap wrote: > 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
Fixed.
> > +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
Fixed.
> > +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
Fixed.
> > + 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.
Great point, I've dropped the "simple" word now.
> > +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"
Dropped.
> > + 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/
Changed.
> > +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"
Fixed.
> > +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/
I like the "better" change.
> > --- /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"
Fixed.
> > --- /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/
Fixed.
> > + 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/
Fixed.
> > + 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/
Fixed.
> > --- /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"
Fixed.
> So where is the uevent message interface documented?
It will go into Documentation/ABI/stable/uevent when this tree is set up :)
thanks a lot for the fixes.
greg k-h - 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/
| |