korg/linux
0
0
Fork 0
mirror of https://mirrors.bfsu.edu.cn/git/linux.git synced 2024-12-15 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

Documentation/stable_api_nonsense.txt: convert it to ReST markup

Browse Source 
Add markups for it to be properly parsed by Sphinx.

As people browsing this document may not notice that the source
file title is "stable_api_nonsense", I opted to use bold to
the rationale for this document. I also found it better to
add a note when it says that the nonsense applies only to the
kABI/kAPI, and not to uAPI.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab 2016-09-19 08:07:50 -03:00 committed by Jonathan Corbet
parent 1d7078d4e2
commit 44f9d45e38
1 changed files with 24 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
Documentation/stable_api_nonsense.txt
View File

@ -1,17 +1,24 @@
The Linux Kernel Driver Interface
==================================
(all of your questions answered and then some)
Greg Kroah-Hartman <greg@kroah.com>
This is being written to try to explain why Linux does not have a binary
kernel interface, nor does it have a stable kernel interface. Please
realize that this article describes the _in kernel_ interfaces, not the
kernel to userspace interfaces. The kernel to userspace interface is
the one that application programs use, the syscall interface. That
interface is _very_ stable over time, and will not break. I have old
programs that were built on a pre 0.9something kernel that still work
just fine on the latest 2.6 kernel release. That interface is the one
that users and application programmers can count on being stable.
This is being written to try to explain why Linux **does not have a binary
kernel interface, nor does it have a stable kernel interface**.
.. note::
Please realize that this article describes the **in kernel** interfaces, not
the kernel to userspace interfaces.
The kernel to userspace interface is the one that application programs use,
the syscall interface. That interface is **very** stable over time, and
will not break. I have old programs that were built on a pre 0.9something
kernel that still work just fine on the latest 2.6 kernel release.
That interface is the one that users and application programmers can count
on being stable.
Executive Summary
@ -33,7 +40,7 @@ to worry about the in-kernel interfaces changing. For the majority of
the world, they neither see this interface, nor do they care about it at
all.
First off, I'm not going to address _any_ legal issues about closed
First off, I'm not going to address **any** legal issues about closed
source, hidden source, binary blobs, source wrappers, or any other term
that describes kernel drivers that do not have their source code
released under the GPL. Please consult a lawyer if you have any legal
@ -51,19 +58,23 @@ Binary Kernel Interface
Assuming that we had a stable kernel source interface for the kernel, a
binary interface would naturally happen too, right? Wrong. Please
consider the following facts about the Linux kernel:
- Depending on the version of the C compiler you use, different kernel
data structures will contain different alignment of structures, and
possibly include different functions in different ways (putting
functions inline or not.) The individual function organization
isn't that important, but the different data structure padding is
very important.
- Depending on what kernel build options you select, a wide range of
different things can be assumed by the kernel:
- different structures can contain different fields
- Some functions may not be implemented at all, (i.e. some locks
compile away to nothing for non-SMP builds.)
- Memory within the kernel can be aligned in different ways,
depending on the build options.
- Linux runs on a wide range of different processor architectures.
There is no way that binary drivers from one architecture will run
on another architecture properly.
@ -105,6 +116,7 @@ As a specific examples of this, the in-kernel USB interfaces have
undergone at least three different reworks over the lifetime of this
subsystem. These reworks were done to address a number of different
issues:
- A change from a synchronous model of data streams to an asynchronous
one. This reduced the complexity of a number of drivers and
increased the throughput of all USB drivers such that we are now
@ -166,6 +178,7 @@ very little effort on your part.
The very good side effects of having your driver in the main kernel tree
are:
- The quality of the driver will rise as the maintenance costs (to the
original developer) will decrease.
- Other developers will add features to your driver.