About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / stable_api_nonsense.txt


Based on kernel version 4.9. Page generated on 2016-12-21 14:37 EST.

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 Linux **does not have a binary
11	kernel 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	
26	Executive Summary
27	-----------------
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 stable running driver, and
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 is in the main kernel
32	tree, all of which has made Linux into such a strong, stable, and mature
33	operating system which is the reason you are using it in the first
34	place.
35	
36	
37	Intro
38	-----
39	
40	It's only the odd person who wants to write a kernel driver that needs
41	to worry about the in-kernel interfaces changing.  For the majority of
42	the world, they neither see this interface, nor do they care about it at
43	all.
44	
45	First off, I'm not going to address **any** legal issues about closed
46	source, hidden source, binary blobs, source wrappers, or any other term
47	that describes kernel drivers that do not have their source code
48	released under the GPL.  Please consult a lawyer if you have any legal
49	questions, I'm a programmer and hence, I'm just going to be describing
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 at all times.)
52	
53	So, there are two main topics here, binary kernel interfaces and stable
54	kernel source interfaces.  They both depend on each other, but we will
55	discuss the binary stuff first to get it out of the way.
56	
57	
58	Binary Kernel Interface
59	-----------------------
60	Assuming that we had a stable kernel source interface for the kernel, a
61	binary interface would naturally happen too, right?  Wrong.  Please
62	consider 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	
84	Now a number of these issues can be addressed by simply compiling your
85	module for the exact specific kernel configuration, using the same exact
86	C compiler that the kernel was built with.  This is sufficient if you
87	want to provide a module for a specific release version of a specific
88	Linux distribution.  But multiply that single build by the number of
89	different Linux distributions and the number of different supported
90	releases of the Linux distribution and you quickly have a nightmare of
91	different build options on different releases.  Also realize that each
92	Linux distribution release contains a number of different kernels, all
93	tuned to different hardware types (different processor types and
94	different options), so for even a single release you will need to create
95	multiple versions of your module.
96	
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 time ago...
99	
100	
101	Stable Kernel Source Interfaces
102	-------------------------------
103	
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 main kernel tree up to
106	date over time.
107	
108	Linux kernel development is continuous and at a rapid pace, never
109	stopping to slow down.  As such, the kernel developers find bugs in
110	current interfaces, or figure out a better way to do things.  If they do
111	that, they then fix the current interfaces to work better.  When they do
112	so, function names may change, structures may grow or shrink, and
113	function parameters may be reworked.  If this happens, all of the
114	instances of where this interface is used within the kernel are fixed up
115	at the same time, ensuring that everything continues to work properly.
116	
117	As a specific examples of this, the in-kernel USB interfaces have
118	undergone at least three different reworks over the lifetime of this
119	subsystem.  These reworks were done to address a number of different
120	issues:
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	
131	This is in stark contrast to a number of closed source operating systems
132	which have had to maintain their older USB interfaces over time.  This
133	provides the ability for new developers to accidentally use the old
134	interfaces and do things in improper ways, causing the stability of the
135	operating system to suffer.
136	
137	In both of these instances, all developers agreed that these were
138	important changes that needed to be made, and they were made, with
139	relatively little pain.  If Linux had to ensure that it will preserve a
140	stable source interface, a new interface would have been created, and
141	the older, broken one would have had to be maintained over time, leading
142	to extra work for the USB developers.  Since all Linux USB developers do
143	their work on their own time, asking programmers to do extra work for no
144	gain, for free, is not a possibility.
145	
146	Security issues are also very important for Linux.  When a
147	security issue is found, it is fixed in a very short amount of time.  A
148	number of times this has caused internal kernel interfaces to be
149	reworked to prevent the security problem from occurring.  When this
150	happens, all drivers that use the interfaces were also fixed at the
151	same time, ensuring that the security problem was fixed and could not
152	come back at some future time accidentally.  If the internal interfaces
153	were not allowed to change, fixing this kind of security problem and
154	insuring that it could not happen again would not be possible.
155	
156	Kernel interfaces are cleaned up over time.  If there is no one using a
157	current interface, it is deleted.  This ensures that the kernel remains
158	as small as possible, and that all potential interfaces are tested as
159	well as they can be (unused interfaces are pretty much impossible to
160	test for validity.)
161	
162	
163	What to do
164	----------
165	
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 do?  Releasing a binary
168	driver for every different kernel version for every distribution is a
169	nightmare, and trying to keep up with an ever changing kernel interface
170	is also a rough job.
171	
172	Simple, get your kernel driver into the main kernel tree (remember we
173	are talking about GPL released drivers here, if your code doesn't fall
174	under 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
176	driver is in the tree, and a kernel interface changes, it will be fixed
177	up by the person who did the kernel change in the first place.  This
178	ensures that your driver is always buildable, and works over time, with
179	very little effort on your part.
180	
181	The very good side effects of having your driver in the main kernel tree
182	are:
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	
194	As Linux supports a larger number of different devices "out of the box"
195	than any other operating system, and it supports these devices on more
196	different processor architectures than any other operating system, this
197	proven type of development model must be doing something right :)
198	
199	
200	
201	------
202	
203	Thanks to Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder,
204	Robert Love, and Nishanth Aravamudan for their review and comments on
205	early drafts of this paper.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog