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