2.6.12 out, comments in :)

Yep, here it is............../linux-2.6.12/Documentation/stable_api_nonsense.txt


The Linux Kernel Driver Interface
(all of your questions answered and then some)

Greg Kroah-Hartman <greg@kroah.com>

This is being written to try to explain why Linux does not have a binary
kernel interface, nor does it have a stable kernel interface. Please
realize that this article describes the _in kernel_ interfaces, not the
kernel to userspace interfaces. The kernel to userspace interface is
the one that application programs use, the syscall interface. That
interface is _very_ stable over time, and will not break. I have old
programs that were built on a pre 0.9something kernel that still work
just fine on the latest 2.6 kernel release. This interface is the one
that users and application programmers can count on being stable.


Executive Summary
-----------------
You think you want a stable kernel interface, but you really do not, and
you don't even know it. What you want is a stable running driver, and
you get that only if your driver is in the main kernel tree. You also
get lots of other good benefits if your driver is in the main kernel
tree, all of which has made Linux into such a strong, stable, and mature
operating system which is the reason you are using it in the first
place.


Intro
-----

It's only the odd person who wants to write a kernel driver that needs
to worry about the in-kernel interfaces changing. For the majority of
the world, they neither see this interface, nor do they care about it at
all.

First off, I'm not going to address _any_ legal issues about closed
source, hidden source, binary blobs, source wrappers, or any other term
that describes kernel drivers that do not have their source code
released under the GPL. Please consult a lawyer if you have any legal
questions, I'm a programmer and hence, I'm just going to be describing
the technical issues here (not to make light of the legal issues, they
are real, and you do need to be aware of them at all times.)

So, there are two main topics here, binary kernel interfaces and stable
kernel source interfaces. They both depend on each other, but we will
discuss the binary stuff first to get it out of the way.


Binary Kernel Interface
-----------------------
Assuming that we had a stable kernel source interface for the kernel, a
binary interface would naturally happen too, right? Wrong. Please
consider the following facts about the Linux kernel:
- Depending on the version of the C compiler you use, different kernel
data structures will contain different alignment of structures, and
possibly include different functions in different ways (putting
functions inline or not.) The individual function organization
isn't that important, but the different data structure padding is
very important.
- Depending on what kernel build options you select, a wide range of
different things can be assumed by the kernel:
- different structures can contain different fields
- Some functions may not be implemented at all, (i.e. some locks
compile away to nothing for non-SMP builds.)
- Parameter passing of variables from function to function can be
done in different ways (the CONFIG_REGPARM option controls
this.)
- Memory within the kernel can be aligned in different ways,
depending on the build options.
- Linux runs on a wide range of different processor architectures.
There is no way that binary drivers from one architecture will run
on another architecture properly.

Now a number of these issues can be addressed by simply compiling your
module for the exact specific kernel configuration, using the same exact
C compiler that the kernel was built with. This is sufficient if you
want to provide a module for a specific release version of a specific
Linux distribution. But multiply that single build by the number of
different Linux distributions and the number of different supported
releases of the Linux distribution and you quickly have a nightmare of
different build options on different releases. Also realize that each
Linux distribution release contains a number of different kernels, all
tuned to different hardware types (different processor types and
different options), so for even a single release you will need to create
multiple versions of your module.

Trust me, you will go insane over time if you try to support this kind
of release, I learned this the hard way a long time ago...


Stable Kernel Source Interfaces
-------------------------------

This is a much more "volatile" topic if you talk to people who try to
keep a Linux kernel driver that is not in the main kernel tree up to
date over time.

Linux kernel development is continuous and at a rapid pace, never
stopping to slow down. As such, the kernel developers find bugs in
current interfaces, or figure out a better way to do things. If they do
that, they then fix the current interfaces to work better. When they do
so, function names may change, structures may grow or shrink, and
function parameters may be reworked. If this happens, all of the
instances of where this interface is used within the kernel are fixed up
at the same time, ensuring that everything continues to work properly.

As a specific examples of this, the in-kernel USB interfaces have
undergone at least three different reworks over the lifetime of this
subsystem. These reworks were done to address a number of different
issues:
- A change from a synchronous model of data streams to an asynchronous
one. This reduced the complexity of a number of drivers and
increased the throughput of all USB drivers such that we are now
running almost all USB devices at their maximum speed possible.
- A change was made in the way data packets were allocated from the
USB core by USB drivers so that all drivers now needed to provide
more information to the USB core to fix a number of documented
deadlocks.

This is in stark contrast to a number of closed source operating systems
which have had to maintain their older USB interfaces over time. This
provides the ability for new developers to accidentally use the old
interfaces and do things in improper ways, causing the stability of the
operating system to suffer.

In both of these instances, all developers agreed that these were
important changes that needed to be made, and they were made, with
relatively little pain. If Linux had to ensure that it preserve a
stable source interface, a new interface would have been created, and
the older, broken one would have had to be maintained over time, leading
to extra work for the USB developers. Since all Linux USB developers do
their work on their own time, asking programmers to do extra work for no
gain, for free, is not a possibility.

Security issues are also a very important for Linux. When a
security issue is found, it is fixed in a very short amount of time. A
number of times this has caused internal kernel interfaces to be
reworked to prevent the security problem from occurring. When this
happens, all drivers that use the interfaces were also fixed at the
same time, ensuring that the security problem was fixed and could not
come back at some future time accidentally. If the internal interfaces
were not allowed to change, fixing this kind of security problem and
insuring that it could not happen again would not be possible.

Kernel interfaces are cleaned up over time. If there is no one using a
current interface, it is deleted. This ensures that the kernel remains
as small as possible, and that all potential interfaces are tested as
well as they can be (unused interfaces are pretty much impossible to
test for validity.)


What to do
----------

So, if you have a Linux kernel driver that is not in the main kernel
tree, what are you, a developer, supposed to do? Releasing a binary
driver for every different kernel version for every distribution is a
nightmare, and trying to keep up with an ever changing kernel interface
is also a rough job.

Simple, get your kernel driver into the main kernel tree (remember we
are talking about GPL released drivers here, if your code doesn't fall
under this category, good luck, you are on your own here, you leech
<insert link to leech comment from Andrew and Linus here>.) If your
driver is in the tree, and a kernel interface changes, it will be fixed
up by the person who did the kernel change in the first place. This
ensures that your driver is always buildable, and works over time, with
very little effort on your part.

The very good side effects of having your driver in the main kernel tree
are:
- The quality of the driver will rise as the maintenance costs (to the
original developer) will decrease.
- Other developers will add features to your driver.
- Other people will find and fix bugs in your driver.
- Other people will find tuning opportunities in your driver.
- Other people will update the driver for you when external interface
changes require it.
- The driver automatically gets shipped in all Linux distributions
without having to ask the distros to add it.

As Linux supports a larger number of different devices "out of the box"
than any other operating system, and it supports these devices on more
different processor architectures than any other operating system, this
proven type of development model must be doing something right



------

Thanks to Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder,
Robert Love, and Nishanth Aravamudan for their review and comments on
early drafts of this paper.

"It's only the odd person who wants to write a kernel driver that needs
to worry about the in-kernel interfaces changing"

Odd person? You mean nvidia, vmware, winmodems, wireless driverloader and countless others that I use on my box?

Yea, it's a good arguement but a little one-sided... They're assuming everything run on linux is open source. Well, not really. They just say your SOL if the driver is closed source. Until the kernel has inhouse driver equivalents to their colsed source counterparts, the 2.6 development model doesn't make for an easy time... For the developer of software or the user of said software that requires modules...

Originally posted by Chinaman It might look like this is _pointed_ at monz, but really, it's not at him only, but something for all of us to consider.

No offence taken, this is merely a Good Discussion..

Read /linux-2.6.12/Documentation/stable_api_nonsense.txt in the kernel sources.

Yeah, just read it; for some reason I hadn't noticed it before..
Sure, the author is right, taken the current way of doing development into consideration.
However, it all depends upon having just about everything within the kernel tree, which I totally agree with as a Good Thing.

But... I can understand why, say nVidia as an example, doesn't want to open their source for a product in a highly competetive area.
And then again, thinking back quite some yeas, the endless problems with Adaptec SCSI controllers, because they wouldn't open their documentation.
This is two examples of both pro et con to keeping a driver binary vs opensource.

Then gain, ATI opensourced their driver. No idea how well it works or performs.
I -think- i've heard quite a lot about problems getting it working well. Comments?

I dunno... I like to have it all in the kernel tree, but sometimes I need a driver that just happens to be closed binary.
When that happens, I would prefer the stable/dev arrangement, as it makes it possible for a closedsource vendor to say 'this driver for that kernel'.

So, we'll have to accept the current kernel approach.
Right now, the nVidia video drivers are one of the most annoying problems. How do we apply ample pressure upon nVidia to open their driver?
We've previously seen signature collections on nforcershq to have nVidia reintroduce Soundstorm (ehm, only partly, I know..).
Could we do this as a unified work, linuxquestions + nforcershq, to apply pressure upon nVidia?

I'll say to y'll, this is one of the better threads

Originally posted by uselpa And I wonder what impact it will have on Slack; Patrick might have a hard time finding a stable kernel for the 11.0 release.

2.4.x is very stable these days.. and used by many still.

But Pat stated that 11.0 will have a 2.6 default kernel, not a 2.4 anymore.

He did?

That's my only gripe with Slackware.

2.4 Kernel Headers.

Then to some it's not a big deal, maybe to most not a big deal.

But I for one would like my Pentium 4 system to have 2.6 headers without the headache of redoing lots of crap and taking risks.

2.6 by default would make my day!!!

I'm not an expert on the subject but I am under the impression that I have the 2.6 kernel headers:

pu@slackw:/var/log/packages$ v *kernel*
-rw-r--r--  1 root root     948 2005-05-29 14:17 kernel-generic-2.6.10-i486-1
-rw-r--r--  1 root root   25738 2005-02-12 10:02 kernel-headers-2.4.29-i386-1
-rw-r--r--  1 root root   34966 2005-05-29 14:17 kernel-headers-2.6.10-i386-1
-rw-r--r--  1 root root     857 2005-02-12 09:56 kernel-ide-2.4.29-i486-1
-rw-r--r--  1 root root   60038 2005-02-12 09:56 kernel-modules-2.4.29-i486-1
-rw-r--r--  1 root root   73781 2005-05-29 14:17 kernel-modules-2.6.10-i486-1
-rw-r--r--  1 root root  836657 2005-02-12 10:06 kernel-source-2.4.29-noarch-1
-rw-r--r--  1 root root 1038901 2005-05-29 14:18 kernel-source-2.6.10-noarch-1

pu@slackw:/var/log/packages$ uname -r
2.6.10

So I am running the 2.6.10 kernel from the Slackware 10.1 CDs and when I compile kernel modules, they work with that kernel.

But in the following site

slackware-current/testing/packages/linux-2.6.11.11/kernel-headers.WARNING

ftp://ftp.slackware.com/pub/slackwar...eaders.WARNING

Patrick states.......

This package of 2.6.x based /usr/include/linux and /usr/include/asm headers
is being provided by request for some people who need it in order to compile
ASDL modem drivers for 2.6.x. As a general rule, installing kernel headers
that are newer than the kernel glibc was compiled with *may* cause problems,
so unless you need these for a particular reason it's best to stick with the
2.4.x kernel-headers package for now.

Note -- if you compile with NPTL then you might want to use these headers,
and glibc's NPTL was compiled using 2.6 headers, so all should be well.
In that case, specify using NPTL libs and headers with these compile
options:

-I/usr/include/nptl -L/usr/lib/nptl

Good luck!

-P.

Originally posted by mianve [B] As a general rule, installing kernel headers that are newer than the kernel glibc was compiled with *may* cause problems, so unless you need these for a particular reason it's best to stick with the 2.4.x kernel-headers package for now.

I see, but I have had no problem up to now with the kernel modules I compiled. Maybe it was sheer luck

Originally posted by uselpa But Pat stated that 11.0 will have a 2.6 default kernel, not a 2.4 anymore.

I understand that, I'm just stating if he ends up having a hard time choosing one, there's always 2.4.x... depending on 2.6.x progress, I'd probably roll back to 2.4.x but most of the time my machines are kept up to date with current but only with the 2.4.x kernel still from kernel.org.. None of my own machines need the 2.6.x kernel for any reason. Run just fine with what I have now.

Originally posted by uselpa I see, but I have had no problem up to now with the kernel modules I compiled. Maybe it was sheer luck

when you compile modules ( or a kernel ) the headers that come
with the kernel sources are used.
problems might arise when you compile programs.
and maybe just the fact that you have a 2.4 and a 2.6 headerset installed
in /usr/include will give you prob's.

egag

So then following Patricks advice

Note -- if you compile with NPTL then you might want to use these headers, and glibc's NPTL was compiled using 2.6 headers, so all should be well. In that case, specify using NPTL libs and headers with these compile options: -I/usr/include/nptl -L/usr/lib/nptl

could possibly eliminate problems compiling things other than the kernel itself?

yip, it sais so...
the new nptl-glibc compiled with 2.6 headers is the first step to Slack11,
witch will have them standard.

egag

Originally posted by egag when you compile modules ( or a kernel ) the headers that come with the kernel sources are used. problems might arise when you compile programs. and maybe just the fact that you have a 2.4 and a 2.6 headerset installed in /usr/include will give you prob's.

I fail to see which problems can occur when compiling either the kernel from it's source with accompaning headers, or any programs outside the kernel space.
If the links pointing to the currently used kernelversion are set correctly in /usr/src, the right set of headers will be used.
If some obscure program is specifically designed to -want- some other (2.4.x) headers, it's time to upgrade that program anyway, IMHO.

Sounds like Slack 11 will be very interesting indeed.

And it shouldn't be terribly far away either, maybe 2-3 months I would guess.

Damn, that does sound like a long time

I'm sure it will be worth it though.