[PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[Luis R. Rodriguez]

From: "Luis R. Rodriguez" <mcgrof@suse.com>

Current documentation over use case for EXPORT_SYMBOL_GPL()
only acknowledges functions which are "an internal implementation
issue, and not really an interface". In practice these days
though we have some maintainers taking on preferences to require
all new functionality go in with EXPORT_SYMBOL_GPL().

A maintainer asking developers to use EXPORT_SYMBOL_GPL()
for new functionality tends to be a well accepted and understood
position that maintainers can take and typically requires the
maintainers educating contributing developers on their own
positions and requirements.

Developers who submit code to maintainers not familiar with
these preferences as optional for new functionality need explicit
guidence though as existing documentation does not acknowledge
this as a valid possibility. Without this being documented some
maintainers are reluctant to accept new functionality with
EXPORT_SYMBOL_GPL().

This extends the use case documentation for EXPORT_SYMBOL_GPL()
to acknowledge acceptance for new functionality.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Signed-off-by: Luis R. Rodriguez <mcgrof@suse.com>
---
 Documentation/DocBook/kernel-hacking.tmpl | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl
index e84f094..19e0c88 100644
--- a/Documentation/DocBook/kernel-hacking.tmpl
+++ b/Documentation/DocBook/kernel-hacking.tmpl
@@ -954,6 +954,8 @@ printk(KERN_INFO "my ip: %pI4\n", &amp;ipaddress);
     <function>MODULE_LICENSE()</function> that specifies a GPL
     compatible license.  It implies that the function is considered
     an internal implementation issue, and not really an interface.
+    Some maintainers and developers may however have a preference to
+    require EXPORT_SYMBOL_GPL() when adding any new APIs or functionality.
    </para>
   </sect1>
  </chapter>
-- 
2.3.2.209.gd67f9d5.dirty

Re: [PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[Jonathan Corbet]

On Thu, 28 May 2015 11:56:01 -0700
"Luis R. Rodriguez" <mcgrof@do-not-panic.com> wrote:

> +    Some maintainers and developers may however have a preference to
> +    require EXPORT_SYMBOL_GPL() when adding any new APIs or functionality.

As a nit, I would take out "have a preference to".

>From what I can tell, there are developers who think this position makes
little sense and, perhaps, risks diluting the value of EXPORT_SYMBOL_GPL()
by attaching it to everything.  My inclination, though, would be to accept
this change as documentation of clear existing practice; whether that
practice should change is, I think, a separate discussion.

jon

Re: [PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[Luis R. Rodriguez]

On Thu, May 28, 2015 at 01:09:23PM -0600, Jonathan Corbet wrote:
> On Thu, 28 May 2015 11:56:01 -0700
> "Luis R. Rodriguez" <mcgrof@do-not-panic.com> wrote:
> 
> > +    Some maintainers and developers may however have a preference to
> > +    require EXPORT_SYMBOL_GPL() when adding any new APIs or functionality.
> 
> As a nit, I would take out "have a preference to".

Fine by me, do you need a new submission on my part of can you amend yourself?

> From what I can tell, there are developers who think this position makes
> little sense and, perhaps, risks diluting the value of EXPORT_SYMBOL_GPL()
> by attaching it to everything.  My inclination, though, would be to accept
> this change as documentation of clear existing practice; whether that
> practice should change is, I think, a separate discussion.

Great, thanks.

  Luis

Re: [PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[Jonathan Corbet]

On Thu, 28 May 2015 21:18:44 +0200
"Luis R. Rodriguez" <mcgrof@suse.com> wrote:

> > As a nit, I would take out "have a preference to".  
> 
> Fine by me, do you need a new submission on my part of can you amend yourself?

I can tweak it on the way in.

Thanks,

jon

Re: [PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[Al Viro]

On Thu, May 28, 2015 at 11:56:01AM -0700, Luis R. Rodriguez wrote:
> From: "Luis R. Rodriguez" <mcgrof@suse.com>
> 
> Current documentation over use case for EXPORT_SYMBOL_GPL()
> only acknowledges functions which are "an internal implementation
> issue, and not really an interface". In practice these days
> though we have some maintainers taking on preferences to require
> all new functionality go in with EXPORT_SYMBOL_GPL().
> 
> A maintainer asking developers to use EXPORT_SYMBOL_GPL()
> for new functionality tends to be a well accepted and understood
> position that maintainers can take and typically requires the
> maintainers educating contributing developers on their own
> positions and requirements.
> 
> Developers who submit code to maintainers not familiar with
> these preferences as optional for new functionality need explicit
> guidence though as existing documentation does not acknowledge
> this as a valid possibility. Without this being documented some
> maintainers are reluctant to accept new functionality with
> EXPORT_SYMBOL_GPL().
> 
> This extends the use case documentation for EXPORT_SYMBOL_GPL()
> to acknowledge acceptance for new functionality.
 
... while some of us consider that as pointless posturing and will refuse
to merge such exports regardless.  It's _NOT_ a universal default; please,
do not attempt to imply otherwise.  In particular, for fs/*.c I will not
accept that as valid grounds for use of EXPORT_SYMBOL_GPL.

Re: [PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[Luis R. Rodriguez]

On Thu, May 28, 2015 at 09:07:49PM +0100, Al Viro wrote:
> On Thu, May 28, 2015 at 11:56:01AM -0700, Luis R. Rodriguez wrote:
> > From: "Luis R. Rodriguez" <mcgrof@suse.com>
> > 
> > Current documentation over use case for EXPORT_SYMBOL_GPL()
> > only acknowledges functions which are "an internal implementation
> > issue, and not really an interface". In practice these days
> > though we have some maintainers taking on preferences to require
> > all new functionality go in with EXPORT_SYMBOL_GPL().
> > 
> > A maintainer asking developers to use EXPORT_SYMBOL_GPL()
> > for new functionality tends to be a well accepted and understood
> > position that maintainers can take and typically requires the
> > maintainers educating contributing developers on their own
> > positions and requirements.
> > 
> > Developers who submit code to maintainers not familiar with
> > these preferences as optional for new functionality need explicit
> > guidence though as existing documentation does not acknowledge
> > this as a valid possibility. Without this being documented some
> > maintainers are reluctant to accept new functionality with
> > EXPORT_SYMBOL_GPL().
> > 
> > This extends the use case documentation for EXPORT_SYMBOL_GPL()
> > to acknowledge acceptance for new functionality.
>  
> ... while some of us consider that as pointless posturing and will refuse
> to merge such exports regardless.

Can you elaborate why, for those maintainers not aware of such positions?

> It's _NOT_ a universal default; please, do not attempt to imply otherwise.

Indeed, the documentation does not try to do that.

>  In particular, for fs/*.c I will not
> accept that as valid grounds for use of EXPORT_SYMBOL_GPL.

Understood.

  Luis

Re: [PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[Al Viro]

On Thu, May 28, 2015 at 11:17:36PM +0200, Luis R. Rodriguez wrote:
> > ... while some of us consider that as pointless posturing and will refuse
> > to merge such exports regardless.
> 
> Can you elaborate why, for those maintainers not aware of such positions?

*shrug*

Either one states that all modules are derivative works of the kernel,
period (in which case attaching _GPL to specific exports is completely
pointless), or it's a claim that this specific export is something
special on its own, which is a fairly strong claim, completely unfounded
more often than not.  In the worst cases it's the former being misrepresented
as the latter.  That only serves to weaken our position in case of copyright
violations, IMO.  When obviously BS claims like "encoding and decoding
of UIDs between the numeric values as seen by userland and stored on
filesystem and opaque pointers as used by the userns stuff is so special
that its use alone is sufficient to change whether the code is derivative
of the kernel or not" are thrown around, we end up with weaker protection,
not stronger one.  If something like _that_ makes the difference between
derived and non-derived, the former can't be worth much...

Re: [PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[Luis R. Rodriguez]

On Thu, May 28, 2015 at 10:56:19PM +0100, Al Viro wrote:
> On Thu, May 28, 2015 at 11:17:36PM +0200, Luis R. Rodriguez wrote:
> > > ... while some of us consider that as pointless posturing and will refuse
> > > to merge such exports regardless.
> > 
> > Can you elaborate why, for those maintainers not aware of such positions?
> 
> *shrug*
> 
> Either one states that all modules are derivative works of the kernel,
> period (in which case attaching _GPL to specific exports is completely
> pointless), or it's a claim that this specific export is something
> special on its own, which is a fairly strong claim, completely unfounded
> more often than not.  In the worst cases it's the former being misrepresented
> as the latter.  That only serves to weaken our position in case of copyright
> violations, IMO.  When obviously BS claims like "encoding and decoding
> of UIDs between the numeric values as seen by userland and stored on
> filesystem and opaque pointers as used by the userns stuff is so special
> that its use alone is sufficient to change whether the code is derivative
> of the kernel or not" are thrown around, we end up with weaker protection,
> not stronger one.  If something like _that_ makes the difference between
> derived and non-derived, the former can't be worth much...

Great, thanks. This seems to be in alignment with those who have all along said
they've used EXPORT_SYMBOL() to mean what EXPORT_SYMBOL_GPL() users now use it
for. Nevertheless -- maintainers should know that some stubborn developers use
EXPORT_SYMBOL_GPL() for its technical merit should violators abuse those
symbols.

  Luis

Re: [PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[Rob Landley]

On Thu, May 28, 2015 at 1:56 PM, Luis R. Rodriguez
<mcgrof@do-not-panic.com> wrote:
> From: "Luis R. Rodriguez" <mcgrof@suse.com>
>
> Current documentation over use case for EXPORT_SYMBOL_GPL()
> only acknowledges functions which are "an internal implementation
> issue, and not really an interface".

I.E. a statement of intent that this symbol is not intended as a
stable API that external users can program to regardless of underlying
implementation, and thus should not be viewed as a barrier to "derived
work" status for copyright purposes.

(If you get a book out of the library and program to its APIs, you're
not a derived work of an implementation not contained in that book.)

> In practice these days
> though we have some maintainers taking on preferences to require
> all new functionality go in with EXPORT_SYMBOL_GPL().

Ah, so they're predicting that Oracle will win the new "Apple vs
Franklin" case extending copyright to render whole new areas of
software proprietary, I.E. that APIs will be declared copyrightable
putting Wine and Samba and such out of business, and probably LEON's
ability to clone Sparc, and so on.

https://lwn.net/Articles/646160/

(And of course that TPP, which is now fast-tracked, will let us impose
this upon the rest of the world without appeal.)

Clearly, you want us to be on the side of Oracle, because GPL is
Freedom by definition no matter what the side effects everywhere else.

Bravo.

Rob

Re: [PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[Christoph Hellwig]

On Fri, May 29, 2015 at 01:10:44AM +0200, Luis R. Rodriguez wrote:
> Great, thanks. This seems to be in alignment with those who have all along said
> they've used EXPORT_SYMBOL() to mean what EXPORT_SYMBOL_GPL() users now use it
> for. Nevertheless -- maintainers should know that some stubborn developers use
> EXPORT_SYMBOL_GPL() for its technical merit should violators abuse those
> symbols.

FYI, I think the naming here is really unfortunate.  If if was named
EXPORT_SYMBOL_INTERNAL as just a kernel export for specific uses we'd
be much better off in being able to explain what it actually does.

Even better would e a system were we have specific export groups, e.g.
symbols would be "core" "mm", "vfs", or "legacy_hack_for_drm" and any
consumer would specificly declare which symbol they pull in.

This would have a couple advantages:

 - anyone adding an export needs to think hard into which category
   it falls, and think again if exporting really makes sense
 - it's reasy to review modules to see if they pull in anything
   unexpected.

Re: [PATCH] Documentation: extend use case for EXPORT_SYMBOL_GPL()

[Luis R. Rodriguez]

On Thu, May 28, 2015 at 10:00:09PM -0700, Christoph Hellwig wrote:
> On Fri, May 29, 2015 at 01:10:44AM +0200, Luis R. Rodriguez wrote:
> > Great, thanks. This seems to be in alignment with those who have all along said
> > they've used EXPORT_SYMBOL() to mean what EXPORT_SYMBOL_GPL() users now use it
> > for. Nevertheless -- maintainers should know that some stubborn developers use
> > EXPORT_SYMBOL_GPL() for its technical merit should violators abuse those
> > symbols.
> 
> FYI, I think the naming here is really unfortunate.  If if was named
> EXPORT_SYMBOL_INTERNAL as just a kernel export for specific uses we'd
> be much better off in being able to explain what it actually does.

This can be decided and if so, a simple SmPL patch can deal with any merge
conflicts easily these days. But I am not sure if its worth to bother.

Probably not.

> Even better would e a system were we have specific export groups, e.g.
> symbols would be "core" "mm", "vfs", or "legacy_hack_for_drm" and any
> consumer would specificly declare which symbol they pull in.
> 
> This would have a couple advantages:
> 
>  - anyone adding an export needs to think hard into which category
>    it falls, and think again if exporting really makes sense
>  - it's reasy to review modules to see if they pull in anything
>    unexpected.

*Iff* we wanted this, Andy Kleen's old Module Namespaces [0] could be used for
this from what I gather.  I also recently thought that this would come in handy
for limiting the module tainting export for instance, when working on firmware
PKCS#7 firmware ignature support [1]. These both aligns with Andi's original
intent, which was:

  There are roughly two classes of exported symbols:

    - Generally usable, well designed, interfaces intended to be used by
      multiple modules (e.g. functions for drivers to register themselves or
      library functions)
    - Special purpose exports that are only really for a single module, but are
      not intended as a general interface. These interfaces are usually not
      really clean and reusable.

   The idea was to mark the later special purpose exports with the name of the
   module that is supposed to them. They wouldn't be available to everybody else
   and wouldn't become part of the general kernel module API.

Obviously I've been tracking possible use cases for it on the backports project
as it can help there as well as documented on the wiki [0].

[0] https://backports.wiki.kernel.org/index.php/Documentation/backports/hacking/todo#Module_namespaces
[1] https://lkml.org/lkml/2015/5/13/728

  Luis