1 .. _stable_api_nonsense:
2
3 The Linux Kernel Driver Interface
4 ==================================
5
6 (all of your questions answered and then some)
7
8 Greg Kroah-Hartman <greg@kroah.com>
9
10 This is being written to try to explain why Li
11 kernel interface, nor does it have a stable ke
12
13 .. note::
14
15 Please realize that this article describes t
16 the kernel to userspace interfaces.
17
18 The kernel to userspace interface is the one
19 the syscall interface. That interface is **
20 will not break. I have old programs that we
21 kernel that still work just fine on the late
22 That interface is the one that users and app
23 on being stable.
24
25
26 Executive Summary
27 -----------------
28 You think you want a stable kernel interface,
29 you don't even know it. What you want is a st
30 you get that only if your driver is in the mai
31 get lots of other good benefits if your driver
32 tree, all of which has made Linux into such a
33 operating system which is the reason you are u
34 place.
35
36
37 Intro
38 -----
39
40 It's only the odd person who wants to write a
41 to worry about the in-kernel interfaces changi
42 the world, they neither see this interface, no
43 all.
44
45 First off, I'm not going to address **any** le
46 source, hidden source, binary blobs, source wr
47 that describes kernel drivers that do not have
48 released under the GPL. Please consult a lawy
49 questions, I'm a programmer and hence, I'm jus
50 the technical issues here (not to make light o
51 are real, and you do need to be aware of them
52
53 So, there are two main topics here, binary ker
54 kernel source interfaces. They both depend on
55 discuss the binary stuff first to get it out o
56
57
58 Binary Kernel Interface
59 -----------------------
60 Assuming that we had a stable kernel source in
61 binary interface would naturally happen too, r
62 consider the following facts about the Linux k
63
64 - Depending on the version of the C compiler
65 data structures will contain different ali
66 possibly include different functions in di
67 functions inline or not.) The individual
68 isn't that important, but the different da
69 very important.
70
71 - Depending on what kernel build options you
72 different things can be assumed by the ker
73
74 - different structures can contain diffe
75 - Some functions may not be implemented
76 compile away to nothing for non-SMP bu
77 - Memory within the kernel can be aligne
78 depending on the build options.
79
80 - Linux runs on a wide range of different pr
81 There is no way that binary drivers from o
82 on another architecture properly.
83
84 Now a number of these issues can be addressed
85 module for the exact specific kernel configura
86 C compiler that the kernel was built with. Th
87 want to provide a module for a specific releas
88 Linux distribution. But multiply that single
89 different Linux distributions and the number o
90 releases of the Linux distribution and you qui
91 different build options on different releases.
92 Linux distribution release contains a number o
93 tuned to different hardware types (different p
94 different options), so for even a single relea
95 multiple versions of your module.
96
97 Trust me, you will go insane over time if you
98 of release, I learned this the hard way a long
99
100
101 Stable Kernel Source Interfaces
102 -------------------------------
103
104 This is a much more "volatile" topic if you ta
105 keep a Linux kernel driver that is not in the
106 date over time.
107
108 Linux kernel development is continuous and at
109 stopping to slow down. As such, the kernel de
110 current interfaces, or figure out a better way
111 that, they then fix the current interfaces to
112 so, function names may change, structures may
113 function parameters may be reworked. If this
114 instances of where this interface is used with
115 at the same time, ensuring that everything con
116
117 As a specific examples of this, the in-kernel
118 undergone at least three different reworks ove
119 subsystem. These reworks were done to address
120 issues:
121
122 - A change from a synchronous model of data
123 one. This reduced the complexity of a num
124 increased the throughput of all USB driver
125 running almost all USB devices at their ma
126 - A change was made in the way data packets
127 USB core by USB drivers so that all driver
128 more information to the USB core to fix a
129 deadlocks.
130
131 This is in stark contrast to a number of close
132 which have had to maintain their older USB int
133 provides the ability for new developers to acc
134 interfaces and do things in improper ways, cau
135 operating system to suffer.
136
137 In both of these instances, all developers agr
138 important changes that needed to be made, and
139 relatively little pain. If Linux had to ensur
140 stable source interface, a new interface would
141 the older, broken one would have had to be mai
142 to extra work for the USB developers. Since a
143 their work on their own time, asking programme
144 gain, for free, is not a possibility.
145
146 Security issues are also very important for Li
147 security issue is found, it is fixed in a very
148 number of times this has caused internal kerne
149 reworked to prevent the security problem from
150 happens, all drivers that use the interfaces w
151 same time, ensuring that the security problem
152 come back at some future time accidentally. I
153 were not allowed to change, fixing this kind o
154 insuring that it could not happen again would
155
156 Kernel interfaces are cleaned up over time. I
157 current interface, it is deleted. This ensure
158 as small as possible, and that all potential i
159 well as they can be (unused interfaces are pre
160 test for validity.)
161
162
163 What to do
164 ----------
165
166 So, if you have a Linux kernel driver that is
167 tree, what are you, a developer, supposed to d
168 driver for every different kernel version for
169 nightmare, and trying to keep up with an ever
170 is also a rough job.
171
172 Simple, get your kernel driver into the main k
173 talking about drivers released under a GPL-com
174 code doesn't fall under this category, good lu
175 you leech). If your driver is in the tree, an
176 it will be fixed up by the person who did the
177 place. This ensures that your driver is alway
178 time, with very little effort on your part.
179
180 The very good side effects of having your driv
181 are:
182
183 - The quality of the driver will rise as the
184 original developer) will decrease.
185 - Other developers will add features to your
186 - Other people will find and fix bugs in you
187 - Other people will find tuning opportunitie
188 - Other people will update the driver for yo
189 changes require it.
190 - The driver automatically gets shipped in a
191 without having to ask the distros to add i
192
193 As Linux supports a larger number of different
194 than any other operating system, and it suppor
195 different processor architectures than any oth
196 proven type of development model must be doing
197
198
199
200 ------
201
202 Thanks to Randy Dunlap, Andrew Morton, David B
203 Robert Love, and Nishanth Aravamudan for their
204 early drafts of this paper.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.