Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1482103

[PATCH v2 12/20] stable_api_nonsense.rst: convert it to ReST markup

Show all headers | View raw

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>
---
 .../development-process/stable_api_nonsense.rst    | 33 +++++++++++++++-------
 1 file changed, 23 insertions(+), 10 deletions(-)

diff --git a/Documentation/development-process/stable_api_nonsense.rst b/Documentation/development-process/stable_api_nonsense.rst
index db3be892afb2..0d375c115b0c 100644
--- a/Documentation/development-process/stable_api_nonsense.rst
+++ b/Documentation/development-process/stable_api_nonsense.rst
@@ -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
@@ -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.
@@ -175,7 +188,7 @@ are:
     changes require it.
   - The driver automatically gets shipped in all Linux distributions
     without having to ask the distros to add it.
-    
+
 As Linux supports a larger number of different devices "out of the box"
 than any other operating system, and it supports these devices on more
 different processor architectures than any other operating system, this
-- 
2.7.4

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH v2 00/20] Create a book for Kernel development Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:20 +0200
  [PATCH v2 18/20] doc: development-process: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:20 +0200
  [PATCH v2 17/20] doc: development-process: rename files to rst Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:20 +0200
  [PATCH v2 11/20] SecurityBugs.rst: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:20 +0200
  [PATCH v2 14/20] SubmittingDrivers.rst: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:20 +0200
  [PATCH v2 01/20] docs-rst: move HOWTO and mentioned documents to a separate dir Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:30 +0200
  [PATCH v2 16/20] HOWTO.rst: add cross-references to other documents Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:30 +0200
  [PATCH v2 13/20] stable_kernel_rules.rst: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:30 +0200
  [PATCH v2 02/20] docs-rst: HOWTO.rst: convert to ReST notation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:30 +0200
  [PATCH v2 12/20] stable_api_nonsense.rst: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:30 +0200
  [PATCH v2 04/20] docs-rst: Changes.rst: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:30 +0200
  [PATCH v2 10/20] ManagementStyle.rst: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:30 +0200
  [PATCH v2 06/20] CodingStyle.rst: use the proper tag for verbatim font Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:30 +0200
  [PATCH v2 05/20] docs-rst: CodingStyle.rst: Convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:30 +0200
    Re: [PATCH v2 05/20] docs-rst: CodingStyle.rst: Convert to ReST  markup Joe Perches <joe@perches.com> - 2016-09-13 05:00 +0200
      Re: [PATCH v2 05/20] docs-rst: CodingStyle.rst: Convert to ReST  markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 10:50 +0200
  [PATCH v2 07/20] CodingStyle.rst: replace underline markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:30 +0200
  [PATCH v2 03/20] docs-rst: applying-patches.rst: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-13 04:30 +0200

csiph-web