1186128f7SMauro Carvalho Chehab.. _stable_api_nonsense: 2186128f7SMauro Carvalho Chehab 3186128f7SMauro Carvalho ChehabThe Linux Kernel Driver Interface 4186128f7SMauro Carvalho Chehab================================== 5186128f7SMauro Carvalho Chehab 6186128f7SMauro Carvalho Chehab(all of your questions answered and then some) 7186128f7SMauro Carvalho Chehab 8186128f7SMauro Carvalho ChehabGreg Kroah-Hartman <greg@kroah.com> 9186128f7SMauro Carvalho Chehab 10186128f7SMauro Carvalho ChehabThis is being written to try to explain why Linux **does not have a binary 11186128f7SMauro Carvalho Chehabkernel interface, nor does it have a stable kernel interface**. 12186128f7SMauro Carvalho Chehab 13186128f7SMauro Carvalho Chehab.. note:: 14186128f7SMauro Carvalho Chehab 15186128f7SMauro Carvalho Chehab Please realize that this article describes the **in kernel** interfaces, not 16186128f7SMauro Carvalho Chehab the kernel to userspace interfaces. 17186128f7SMauro Carvalho Chehab 18186128f7SMauro Carvalho Chehab The kernel to userspace interface is the one that application programs use, 19186128f7SMauro Carvalho Chehab the syscall interface. That interface is **very** stable over time, and 20186128f7SMauro Carvalho Chehab will not break. I have old programs that were built on a pre 0.9something 21186128f7SMauro Carvalho Chehab kernel that still work just fine on the latest 2.6 kernel release. 22186128f7SMauro Carvalho Chehab That interface is the one that users and application programmers can count 23186128f7SMauro Carvalho Chehab on being stable. 24186128f7SMauro Carvalho Chehab 25186128f7SMauro Carvalho Chehab 26186128f7SMauro Carvalho ChehabExecutive Summary 27186128f7SMauro Carvalho Chehab----------------- 28186128f7SMauro Carvalho ChehabYou think you want a stable kernel interface, but you really do not, and 29186128f7SMauro Carvalho Chehabyou don't even know it. What you want is a stable running driver, and 30186128f7SMauro Carvalho Chehabyou get that only if your driver is in the main kernel tree. You also 31186128f7SMauro Carvalho Chehabget lots of other good benefits if your driver is in the main kernel 32186128f7SMauro Carvalho Chehabtree, all of which has made Linux into such a strong, stable, and mature 33186128f7SMauro Carvalho Chehaboperating system which is the reason you are using it in the first 34186128f7SMauro Carvalho Chehabplace. 35186128f7SMauro Carvalho Chehab 36186128f7SMauro Carvalho Chehab 37186128f7SMauro Carvalho ChehabIntro 38186128f7SMauro Carvalho Chehab----- 39186128f7SMauro Carvalho Chehab 40186128f7SMauro Carvalho ChehabIt's only the odd person who wants to write a kernel driver that needs 41186128f7SMauro Carvalho Chehabto worry about the in-kernel interfaces changing. For the majority of 42186128f7SMauro Carvalho Chehabthe world, they neither see this interface, nor do they care about it at 43186128f7SMauro Carvalho Chehaball. 44186128f7SMauro Carvalho Chehab 45186128f7SMauro Carvalho ChehabFirst off, I'm not going to address **any** legal issues about closed 46186128f7SMauro Carvalho Chehabsource, hidden source, binary blobs, source wrappers, or any other term 47186128f7SMauro Carvalho Chehabthat describes kernel drivers that do not have their source code 48186128f7SMauro Carvalho Chehabreleased under the GPL. Please consult a lawyer if you have any legal 49186128f7SMauro Carvalho Chehabquestions, I'm a programmer and hence, I'm just going to be describing 50186128f7SMauro Carvalho Chehabthe technical issues here (not to make light of the legal issues, they 51186128f7SMauro Carvalho Chehabare real, and you do need to be aware of them at all times.) 52186128f7SMauro Carvalho Chehab 53186128f7SMauro Carvalho ChehabSo, there are two main topics here, binary kernel interfaces and stable 54186128f7SMauro Carvalho Chehabkernel source interfaces. They both depend on each other, but we will 55186128f7SMauro Carvalho Chehabdiscuss the binary stuff first to get it out of the way. 56186128f7SMauro Carvalho Chehab 57186128f7SMauro Carvalho Chehab 58186128f7SMauro Carvalho ChehabBinary Kernel Interface 59186128f7SMauro Carvalho Chehab----------------------- 60186128f7SMauro Carvalho ChehabAssuming that we had a stable kernel source interface for the kernel, a 61186128f7SMauro Carvalho Chehabbinary interface would naturally happen too, right? Wrong. Please 62186128f7SMauro Carvalho Chehabconsider the following facts about the Linux kernel: 63186128f7SMauro Carvalho Chehab 64186128f7SMauro Carvalho Chehab - Depending on the version of the C compiler you use, different kernel 65186128f7SMauro Carvalho Chehab data structures will contain different alignment of structures, and 66186128f7SMauro Carvalho Chehab possibly include different functions in different ways (putting 67186128f7SMauro Carvalho Chehab functions inline or not.) The individual function organization 68186128f7SMauro Carvalho Chehab isn't that important, but the different data structure padding is 69186128f7SMauro Carvalho Chehab very important. 70186128f7SMauro Carvalho Chehab 71186128f7SMauro Carvalho Chehab - Depending on what kernel build options you select, a wide range of 72186128f7SMauro Carvalho Chehab different things can be assumed by the kernel: 73186128f7SMauro Carvalho Chehab 74186128f7SMauro Carvalho Chehab - different structures can contain different fields 75186128f7SMauro Carvalho Chehab - Some functions may not be implemented at all, (i.e. some locks 76186128f7SMauro Carvalho Chehab compile away to nothing for non-SMP builds.) 77186128f7SMauro Carvalho Chehab - Memory within the kernel can be aligned in different ways, 78186128f7SMauro Carvalho Chehab depending on the build options. 79186128f7SMauro Carvalho Chehab 80186128f7SMauro Carvalho Chehab - Linux runs on a wide range of different processor architectures. 81186128f7SMauro Carvalho Chehab There is no way that binary drivers from one architecture will run 82186128f7SMauro Carvalho Chehab on another architecture properly. 83186128f7SMauro Carvalho Chehab 84186128f7SMauro Carvalho ChehabNow a number of these issues can be addressed by simply compiling your 85186128f7SMauro Carvalho Chehabmodule for the exact specific kernel configuration, using the same exact 86186128f7SMauro Carvalho ChehabC compiler that the kernel was built with. This is sufficient if you 87186128f7SMauro Carvalho Chehabwant to provide a module for a specific release version of a specific 88186128f7SMauro Carvalho ChehabLinux distribution. But multiply that single build by the number of 89186128f7SMauro Carvalho Chehabdifferent Linux distributions and the number of different supported 90186128f7SMauro Carvalho Chehabreleases of the Linux distribution and you quickly have a nightmare of 91186128f7SMauro Carvalho Chehabdifferent build options on different releases. Also realize that each 92186128f7SMauro Carvalho ChehabLinux distribution release contains a number of different kernels, all 93186128f7SMauro Carvalho Chehabtuned to different hardware types (different processor types and 94186128f7SMauro Carvalho Chehabdifferent options), so for even a single release you will need to create 95186128f7SMauro Carvalho Chehabmultiple versions of your module. 96186128f7SMauro Carvalho Chehab 97186128f7SMauro Carvalho ChehabTrust me, you will go insane over time if you try to support this kind 98186128f7SMauro Carvalho Chehabof release, I learned this the hard way a long time ago... 99186128f7SMauro Carvalho Chehab 100186128f7SMauro Carvalho Chehab 101186128f7SMauro Carvalho ChehabStable Kernel Source Interfaces 102186128f7SMauro Carvalho Chehab------------------------------- 103186128f7SMauro Carvalho Chehab 104186128f7SMauro Carvalho ChehabThis is a much more "volatile" topic if you talk to people who try to 105186128f7SMauro Carvalho Chehabkeep a Linux kernel driver that is not in the main kernel tree up to 106186128f7SMauro Carvalho Chehabdate over time. 107186128f7SMauro Carvalho Chehab 108186128f7SMauro Carvalho ChehabLinux kernel development is continuous and at a rapid pace, never 109186128f7SMauro Carvalho Chehabstopping to slow down. As such, the kernel developers find bugs in 110186128f7SMauro Carvalho Chehabcurrent interfaces, or figure out a better way to do things. If they do 111186128f7SMauro Carvalho Chehabthat, they then fix the current interfaces to work better. When they do 112186128f7SMauro Carvalho Chehabso, function names may change, structures may grow or shrink, and 113186128f7SMauro Carvalho Chehabfunction parameters may be reworked. If this happens, all of the 114186128f7SMauro Carvalho Chehabinstances of where this interface is used within the kernel are fixed up 115186128f7SMauro Carvalho Chehabat the same time, ensuring that everything continues to work properly. 116186128f7SMauro Carvalho Chehab 117186128f7SMauro Carvalho ChehabAs a specific examples of this, the in-kernel USB interfaces have 118186128f7SMauro Carvalho Chehabundergone at least three different reworks over the lifetime of this 119186128f7SMauro Carvalho Chehabsubsystem. These reworks were done to address a number of different 120186128f7SMauro Carvalho Chehabissues: 121186128f7SMauro Carvalho Chehab 122186128f7SMauro Carvalho Chehab - A change from a synchronous model of data streams to an asynchronous 123186128f7SMauro Carvalho Chehab one. This reduced the complexity of a number of drivers and 124186128f7SMauro Carvalho Chehab increased the throughput of all USB drivers such that we are now 125186128f7SMauro Carvalho Chehab running almost all USB devices at their maximum speed possible. 126186128f7SMauro Carvalho Chehab - A change was made in the way data packets were allocated from the 127186128f7SMauro Carvalho Chehab USB core by USB drivers so that all drivers now needed to provide 128186128f7SMauro Carvalho Chehab more information to the USB core to fix a number of documented 129186128f7SMauro Carvalho Chehab deadlocks. 130186128f7SMauro Carvalho Chehab 131186128f7SMauro Carvalho ChehabThis is in stark contrast to a number of closed source operating systems 132186128f7SMauro Carvalho Chehabwhich have had to maintain their older USB interfaces over time. This 133186128f7SMauro Carvalho Chehabprovides the ability for new developers to accidentally use the old 134186128f7SMauro Carvalho Chehabinterfaces and do things in improper ways, causing the stability of the 135186128f7SMauro Carvalho Chehaboperating system to suffer. 136186128f7SMauro Carvalho Chehab 137186128f7SMauro Carvalho ChehabIn both of these instances, all developers agreed that these were 138186128f7SMauro Carvalho Chehabimportant changes that needed to be made, and they were made, with 139186128f7SMauro Carvalho Chehabrelatively little pain. If Linux had to ensure that it will preserve a 140186128f7SMauro Carvalho Chehabstable source interface, a new interface would have been created, and 141186128f7SMauro Carvalho Chehabthe older, broken one would have had to be maintained over time, leading 142186128f7SMauro Carvalho Chehabto extra work for the USB developers. Since all Linux USB developers do 143186128f7SMauro Carvalho Chehabtheir work on their own time, asking programmers to do extra work for no 144186128f7SMauro Carvalho Chehabgain, for free, is not a possibility. 145186128f7SMauro Carvalho Chehab 146186128f7SMauro Carvalho ChehabSecurity issues are also very important for Linux. When a 147186128f7SMauro Carvalho Chehabsecurity issue is found, it is fixed in a very short amount of time. A 148186128f7SMauro Carvalho Chehabnumber of times this has caused internal kernel interfaces to be 149186128f7SMauro Carvalho Chehabreworked to prevent the security problem from occurring. When this 150186128f7SMauro Carvalho Chehabhappens, all drivers that use the interfaces were also fixed at the 151186128f7SMauro Carvalho Chehabsame time, ensuring that the security problem was fixed and could not 152186128f7SMauro Carvalho Chehabcome back at some future time accidentally. If the internal interfaces 153186128f7SMauro Carvalho Chehabwere not allowed to change, fixing this kind of security problem and 154186128f7SMauro Carvalho Chehabinsuring that it could not happen again would not be possible. 155186128f7SMauro Carvalho Chehab 156186128f7SMauro Carvalho ChehabKernel interfaces are cleaned up over time. If there is no one using a 157186128f7SMauro Carvalho Chehabcurrent interface, it is deleted. This ensures that the kernel remains 158186128f7SMauro Carvalho Chehabas small as possible, and that all potential interfaces are tested as 159186128f7SMauro Carvalho Chehabwell as they can be (unused interfaces are pretty much impossible to 160186128f7SMauro Carvalho Chehabtest for validity.) 161186128f7SMauro Carvalho Chehab 162186128f7SMauro Carvalho Chehab 163186128f7SMauro Carvalho ChehabWhat to do 164186128f7SMauro Carvalho Chehab---------- 165186128f7SMauro Carvalho Chehab 166186128f7SMauro Carvalho ChehabSo, if you have a Linux kernel driver that is not in the main kernel 167186128f7SMauro Carvalho Chehabtree, what are you, a developer, supposed to do? Releasing a binary 168186128f7SMauro Carvalho Chehabdriver for every different kernel version for every distribution is a 169186128f7SMauro Carvalho Chehabnightmare, and trying to keep up with an ever changing kernel interface 170186128f7SMauro Carvalho Chehabis also a rough job. 171186128f7SMauro Carvalho Chehab 172*8f7e6d13SAdam BorowskiSimple, get your kernel driver into the main kernel tree (remember we are 173*8f7e6d13SAdam Borowskitalking about drivers released under a GPL-compatible license here, if your 174*8f7e6d13SAdam Borowskicode doesn't fall under this category, good luck, you are on your own here, 175*8f7e6d13SAdam Borowskiyou leech). If your driver is in the tree, and a kernel interface changes, 176*8f7e6d13SAdam Borowskiit will be fixed up by the person who did the kernel change in the first 177*8f7e6d13SAdam Borowskiplace. This ensures that your driver is always buildable, and works over 178*8f7e6d13SAdam Borowskitime, with very little effort on your part. 179186128f7SMauro Carvalho Chehab 180186128f7SMauro Carvalho ChehabThe very good side effects of having your driver in the main kernel tree 181186128f7SMauro Carvalho Chehabare: 182186128f7SMauro Carvalho Chehab 183186128f7SMauro Carvalho Chehab - The quality of the driver will rise as the maintenance costs (to the 184186128f7SMauro Carvalho Chehab original developer) will decrease. 185186128f7SMauro Carvalho Chehab - Other developers will add features to your driver. 186186128f7SMauro Carvalho Chehab - Other people will find and fix bugs in your driver. 187186128f7SMauro Carvalho Chehab - Other people will find tuning opportunities in your driver. 188186128f7SMauro Carvalho Chehab - Other people will update the driver for you when external interface 189186128f7SMauro Carvalho Chehab changes require it. 190186128f7SMauro Carvalho Chehab - The driver automatically gets shipped in all Linux distributions 191186128f7SMauro Carvalho Chehab without having to ask the distros to add it. 192186128f7SMauro Carvalho Chehab 193186128f7SMauro Carvalho ChehabAs Linux supports a larger number of different devices "out of the box" 194186128f7SMauro Carvalho Chehabthan any other operating system, and it supports these devices on more 195186128f7SMauro Carvalho Chehabdifferent processor architectures than any other operating system, this 196186128f7SMauro Carvalho Chehabproven type of development model must be doing something right :) 197186128f7SMauro Carvalho Chehab 198186128f7SMauro Carvalho Chehab 199186128f7SMauro Carvalho Chehab 200186128f7SMauro Carvalho Chehab------ 201186128f7SMauro Carvalho Chehab 202186128f7SMauro Carvalho ChehabThanks to Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder, 203186128f7SMauro Carvalho ChehabRobert Love, and Nishanth Aravamudan for their review and comments on 204186128f7SMauro Carvalho Chehabearly drafts of this paper. 205