Documentation/stable_api_nonsense.txt

   1 The Linux Kernel Driver Interface
   2 ==================================
   3
   4 (all of your questions answered and then some)
   5
   6 Greg Kroah-Hartman <greg@kroah.com>
   7
   8 This is being written to try to explain why Linux **does not have a binary
   9 kernel interface, nor does it have a stable kernel interface**.
  10
  11 .. note::
  12
  13   Please realize that this article describes the **in kernel** interfaces, not
  14   the kernel to userspace interfaces.
  15
  16   The kernel to userspace interface is the one that application programs use,
  17   the syscall interface.  That interface is **very** stable over time, and
  18   will not break.  I have old programs that were built on a pre 0.9something
  19   kernel that still work just fine on the latest 2.6 kernel release.
  20   That interface is the one that users and application programmers can count
  21   on being stable.
  22
  23
  24 Executive Summary
  25 -----------------
  26 You think you want a stable kernel interface, but you really do not, and
  27 you don't even know it.  What you want is a stable running driver, and
  28 you get that only if your driver is in the main kernel tree.  You also
  29 get lots of other good benefits if your driver is in the main kernel
  30 tree, all of which has made Linux into such a strong, stable, and mature
  31 operating system which is the reason you are using it in the first
  32 place.
  33
  34
  35 Intro
  36 -----
  37
  38 It's only the odd person who wants to write a kernel driver that needs
  39 to worry about the in-kernel interfaces changing.  For the majority of
  40 the world, they neither see this interface, nor do they care about it at
  41 all.
  42
  43 First off, I'm not going to address **any** legal issues about closed
  44 source, hidden source, binary blobs, source wrappers, or any other term
  45 that describes kernel drivers that do not have their source code
  46 released under the GPL.  Please consult a lawyer if you have any legal
  47 questions, I'm a programmer and hence, I'm just going to be describing
  48 the technical issues here (not to make light of the legal issues, they
  49 are real, and you do need to be aware of them at all times.)
  50
  51 So, there are two main topics here, binary kernel interfaces and stable
  52 kernel source interfaces.  They both depend on each other, but we will
  53 discuss the binary stuff first to get it out of the way.
  54
  55
  56 Binary Kernel Interface
  57 -----------------------
  58 Assuming that we had a stable kernel source interface for the kernel, a
  59 binary interface would naturally happen too, right?  Wrong.  Please
  60 consider the following facts about the Linux kernel:
  61
  62   - Depending on the version of the C compiler you use, different kernel
  63     data structures will contain different alignment of structures, and
  64     possibly include different functions in different ways (putting
  65     functions inline or not.)  The individual function organization
  66     isn't that important, but the different data structure padding is
  67     very important.
  68
  69   - Depending on what kernel build options you select, a wide range of
  70     different things can be assumed by the kernel:
  71
  72       - different structures can contain different fields
  73       - Some functions may not be implemented at all, (i.e. some locks
  74         compile away to nothing for non-SMP builds.)
  75       - Memory within the kernel can be aligned in different ways,
  76         depending on the build options.
  77
  78   - Linux runs on a wide range of different processor architectures.
  79     There is no way that binary drivers from one architecture will run
  80     on another architecture properly.
  81
  82 Now a number of these issues can be addressed by simply compiling your
  83 module for the exact specific kernel configuration, using the same exact
  84 C compiler that the kernel was built with.  This is sufficient if you
  85 want to provide a module for a specific release version of a specific
  86 Linux distribution.  But multiply that single build by the number of
  87 different Linux distributions and the number of different supported
  88 releases of the Linux distribution and you quickly have a nightmare of
  89 different build options on different releases.  Also realize that each
  90 Linux distribution release contains a number of different kernels, all
  91 tuned to different hardware types (different processor types and
  92 different options), so for even a single release you will need to create
  93 multiple versions of your module.
  94
  95 Trust me, you will go insane over time if you try to support this kind
  96 of release, I learned this the hard way a long time ago...
  97
  98
  99 Stable Kernel Source Interfaces
 100 -------------------------------
 101
 102 This is a much more "volatile" topic if you talk to people who try to
 103 keep a Linux kernel driver that is not in the main kernel tree up to
 104 date over time.
 105
 106 Linux kernel development is continuous and at a rapid pace, never
 107 stopping to slow down.  As such, the kernel developers find bugs in
 108 current interfaces, or figure out a better way to do things.  If they do
 109 that, they then fix the current interfaces to work better.  When they do
 110 so, function names may change, structures may grow or shrink, and
 111 function parameters may be reworked.  If this happens, all of the
 112 instances of where this interface is used within the kernel are fixed up
 113 at the same time, ensuring that everything continues to work properly.
 114
 115 As a specific examples of this, the in-kernel USB interfaces have
 116 undergone at least three different reworks over the lifetime of this
 117 subsystem.  These reworks were done to address a number of different
 118 issues:
 119
 120   - A change from a synchronous model of data streams to an asynchronous
 121     one.  This reduced the complexity of a number of drivers and
 122     increased the throughput of all USB drivers such that we are now
 123     running almost all USB devices at their maximum speed possible.
 124   - A change was made in the way data packets were allocated from the
 125     USB core by USB drivers so that all drivers now needed to provide
 126     more information to the USB core to fix a number of documented
 127     deadlocks.
 128
 129 This is in stark contrast to a number of closed source operating systems
 130 which have had to maintain their older USB interfaces over time.  This
 131 provides the ability for new developers to accidentally use the old
 132 interfaces and do things in improper ways, causing the stability of the
 133 operating system to suffer.
 134
 135 In both of these instances, all developers agreed that these were
 136 important changes that needed to be made, and they were made, with
 137 relatively little pain.  If Linux had to ensure that it will preserve a
 138 stable source interface, a new interface would have been created, and
 139 the older, broken one would have had to be maintained over time, leading
 140 to extra work for the USB developers.  Since all Linux USB developers do
 141 their work on their own time, asking programmers to do extra work for no
 142 gain, for free, is not a possibility.
 143
 144 Security issues are also very important for Linux.  When a
 145 security issue is found, it is fixed in a very short amount of time.  A
 146 number of times this has caused internal kernel interfaces to be
 147 reworked to prevent the security problem from occurring.  When this
 148 happens, all drivers that use the interfaces were also fixed at the
 149 same time, ensuring that the security problem was fixed and could not
 150 come back at some future time accidentally.  If the internal interfaces
 151 were not allowed to change, fixing this kind of security problem and
 152 insuring that it could not happen again would not be possible.
 153
 154 Kernel interfaces are cleaned up over time.  If there is no one using a
 155 current interface, it is deleted.  This ensures that the kernel remains
 156 as small as possible, and that all potential interfaces are tested as
 157 well as they can be (unused interfaces are pretty much impossible to
 158 test for validity.)
 159
 160
 161 What to do
 162 ----------
 163
 164 So, if you have a Linux kernel driver that is not in the main kernel
 165 tree, what are you, a developer, supposed to do?  Releasing a binary
 166 driver for every different kernel version for every distribution is a
 167 nightmare, and trying to keep up with an ever changing kernel interface
 168 is also a rough job.
 169
 170 Simple, get your kernel driver into the main kernel tree (remember we
 171 are talking about GPL released drivers here, if your code doesn't fall
 172 under this category, good luck, you are on your own here, you leech
 173 <insert link to leech comment from Andrew and Linus here>.)  If your
 174 driver is in the tree, and a kernel interface changes, it will be fixed
 175 up by the person who did the kernel change in the first place.  This
 176 ensures that your driver is always buildable, and works over time, with
 177 very little effort on your part.
 178
 179 The very good side effects of having your driver in the main kernel tree
 180 are:
 181
 182   - The quality of the driver will rise as the maintenance costs (to the
 183     original developer) will decrease.
 184   - Other developers will add features to your driver.
 185   - Other people will find and fix bugs in your driver.
 186   - Other people will find tuning opportunities in your driver.
 187   - Other people will update the driver for you when external interface
 188     changes require it.
 189   - The driver automatically gets shipped in all Linux distributions
 190     without having to ask the distros to add it.
 191
 192 As Linux supports a larger number of different devices "out of the box"
 193 than any other operating system, and it supports these devices on more
 194 different processor architectures than any other operating system, this
 195 proven type of development model must be doing something right :)
 196
 197
 198
 199 ------
 200
 201 Thanks to Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder,
 202 Robert Love, and Nishanth Aravamudan for their review and comments on
 203 early drafts of this paper.