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