[PATCH] Documentation/ABI: Document the non-ABI status of Kconfig and symbols

[PATCH] Documentation/ABI: Document the non-ABI status of Kconfig and symbols

[Josh Triplett]

Discussion at Kernel Summit made it clear that the presence or absence
of specific Kconfig symbols are not considered ABI, and that no
userspace (or bootloader, etc) should rely on them.

In addition, kernel-internal symbols are well established as non-ABI,
per Documentation/stable_api_nonsense.txt.

Document both of these in Documentation/ABI/README, in a new section for
notable bits of non-ABI.

Signed-off-by: Josh Triplett <josh@joshtriplett.org>
---
 Documentation/ABI/README | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/ABI/README b/Documentation/ABI/README
index 1006982..1fafc4b 100644
--- a/Documentation/ABI/README
+++ b/Documentation/ABI/README
@@ -72,3 +72,16 @@ kernel tree without going through the obsolete state first.
 
 It's up to the developer to place their interfaces in the category they
 wish for it to start out in.
+
+
+Notable bits of non-ABI, which should not under any circumstances be considered
+stable:
+
+- Kconfig.  Userspace should not rely on the presence or absence of any
+  particular Kconfig symbol, in /proc/config.gz, in the copy of .config
+  commonly installed to /boot, or in any invocation of the kernel build
+  process.
+
+- Kernel-internal symbols.  Do not rely on the presence, absence, location, or
+  type of any kernel symbol, either in System.map files or the kernel binary
+  itself.  See Documentation/stable_api_nonsense.txt.
-- 
1.8.4.rc3

Re: [PATCH] Documentation/ABI: Document the non-ABI status of Kconfig and symbols

[H. Peter Anvin]

On 10/24/2013 09:41 AM, Josh Triplett wrote:
> Discussion at Kernel Summit made it clear that the presence or absence
> of specific Kconfig symbols are not considered ABI, and that no
> userspace (or bootloader, etc) should rely on them.
> 
> In addition, kernel-internal symbols are well established as non-ABI,
> per Documentation/stable_api_nonsense.txt.
> 
> Document both of these in Documentation/ABI/README, in a new section for
> notable bits of non-ABI.
> 
> Signed-off-by: Josh Triplett <josh@joshtriplett.org>

Good initiative.

Acked-by: H. Peter Anvin <hpa@zytor.com>

Re: [PATCH] Documentation/ABI: Document the non-ABI status of Kconfig and symbols

[Richard Weinberger]

On Thu, Oct 24, 2013 at 10:41 AM, Josh Triplett <josh@joshtriplett.org> wrote:
> Discussion at Kernel Summit made it clear that the presence or absence
> of specific Kconfig symbols are not considered ABI, and that no
> userspace (or bootloader, etc) should rely on them.
>
> In addition, kernel-internal symbols are well established as non-ABI,
> per Documentation/stable_api_nonsense.txt.
>
> Document both of these in Documentation/ABI/README, in a new section for
> notable bits of non-ABI.
>
> Signed-off-by: Josh Triplett <josh@joshtriplett.org>
> ---
>  Documentation/ABI/README | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
>
> diff --git a/Documentation/ABI/README b/Documentation/ABI/README
> index 1006982..1fafc4b 100644
> --- a/Documentation/ABI/README
> +++ b/Documentation/ABI/README
> @@ -72,3 +72,16 @@ kernel tree without going through the obsolete state first.
>
>  It's up to the developer to place their interfaces in the category they
>  wish for it to start out in.
> +
> +
> +Notable bits of non-ABI, which should not under any circumstances be considered
> +stable:
> +
> +- Kconfig.  Userspace should not rely on the presence or absence of any
> +  particular Kconfig symbol, in /proc/config.gz, in the copy of .config
> +  commonly installed to /boot, or in any invocation of the kernel build
> +  process.
> +
> +- Kernel-internal symbols.  Do not rely on the presence, absence, location, or
> +  type of any kernel symbol, either in System.map files or the kernel binary
> +  itself.  See Documentation/stable_api_nonsense.txt.

And what about the kernel make "interface", is it considered also as non-ABI?

E.g.
Before ffee0de (x86: Default to ARCH=x86 to avoid overriding CONFIG_64BIT)
"make defconfig ARCH=x86" produced a i386 defconfig. Now it produces a
x86_64 defconfig.
I'm sure some build scripted failed badly.


-- 
Thanks,
//richard

Re: [PATCH] Documentation/ABI: Document the non-ABI status of Kconfig and symbols

[Josh Triplett]

On Thu, Oct 24, 2013 at 10:57:11AM +0200, Richard Weinberger wrote:
> On Thu, Oct 24, 2013 at 10:41 AM, Josh Triplett <josh@joshtriplett.org> wrote:
> > Discussion at Kernel Summit made it clear that the presence or absence
> > of specific Kconfig symbols are not considered ABI, and that no
> > userspace (or bootloader, etc) should rely on them.
> >
> > In addition, kernel-internal symbols are well established as non-ABI,
> > per Documentation/stable_api_nonsense.txt.
> >
> > Document both of these in Documentation/ABI/README, in a new section for
> > notable bits of non-ABI.
> >
> > Signed-off-by: Josh Triplett <josh@joshtriplett.org>
> > ---
> >  Documentation/ABI/README | 13 +++++++++++++
> >  1 file changed, 13 insertions(+)
> >
> > diff --git a/Documentation/ABI/README b/Documentation/ABI/README
> > index 1006982..1fafc4b 100644
> > --- a/Documentation/ABI/README
> > +++ b/Documentation/ABI/README
> > @@ -72,3 +72,16 @@ kernel tree without going through the obsolete state first.
> >
> >  It's up to the developer to place their interfaces in the category they
> >  wish for it to start out in.
> > +
> > +
> > +Notable bits of non-ABI, which should not under any circumstances be considered
> > +stable:
> > +
> > +- Kconfig.  Userspace should not rely on the presence or absence of any
> > +  particular Kconfig symbol, in /proc/config.gz, in the copy of .config
> > +  commonly installed to /boot, or in any invocation of the kernel build
> > +  process.
> > +
> > +- Kernel-internal symbols.  Do not rely on the presence, absence, location, or
> > +  type of any kernel symbol, either in System.map files or the kernel binary
> > +  itself.  See Documentation/stable_api_nonsense.txt.
> 
> And what about the kernel make "interface", is it considered also as non-ABI?
> 
> E.g.
> Before ffee0de (x86: Default to ARCH=x86 to avoid overriding CONFIG_64BIT)
> "make defconfig ARCH=x86" produced a i386 defconfig. Now it produces a
> x86_64 defconfig.
> I'm sure some build scripted failed badly.

I seriously considered including that, but I could imagine that some
parts of that interface might be considered more stable than others (the
names of targets, for instance), and I wanted to stick to completely
uncontroversial items.  If there's consensus that part or all of the
invocation of "make" to build the kernel is non-ABI, we can easily
enough add that to the non-ABI list, but let's start with Kconfig and
symbols.

- Josh Triplett

Re: [PATCH] Documentation/ABI: Document the non-ABI status of Kconfig and symbols

[H. Peter Anvin]

On 10/24/2013 09:57 AM, Richard Weinberger wrote:
> 
> And what about the kernel make "interface", is it considered also as non-ABI?
> 
> E.g.
> Before ffee0de (x86: Default to ARCH=x86 to avoid overriding CONFIG_64BIT)
> "make defconfig ARCH=x86" produced a i386 defconfig. Now it produces a
> x86_64 defconfig.
> I'm sure some build scripted failed badly.
> 
> 

Definitely not ABI, although obviously not a completely "break blindly"
either.

	-hpa

Re: [PATCH] Documentation/ABI: Document the non-ABI status of Kconfig and symbols

[Rob Landley]

On 10/24/2013 04:08:30 AM, Josh Triplett wrote:
> On Thu, Oct 24, 2013 at 10:57:11AM +0200, Richard Weinberger wrote:
> > On Thu, Oct 24, 2013 at 10:41 AM, Josh Triplett  
> <josh@joshtriplett.org> wrote:
> > > Discussion at Kernel Summit made it clear that the presence or  
> absence
> > > of specific Kconfig symbols are not considered ABI, and that no
> > > userspace (or bootloader, etc) should rely on them.
> > >
> > > In addition, kernel-internal symbols are well established as  
> non-ABI,
> > > per Documentation/stable_api_nonsense.txt.
> > >
> > > Document both of these in Documentation/ABI/README, in a new  
> section for
> > > notable bits of non-ABI.
> > >
> > > Signed-off-by: Josh Triplett <josh@joshtriplett.org>
> > > ---
> > >  Documentation/ABI/README | 13 +++++++++++++
> > >  1 file changed, 13 insertions(+)

Should I grab this, or is it already going in through somebody else's  
tree?

Rob