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