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