Skip to contentSkip to conversation

feature-removal: add documentation for exported symbols going away

RFC PATCH NAK Harvey Harrison 6 participants 12 messages Feb 13, 2008 – Feb 15, 2008

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 feature-removal: add documentation for exported symbols going away

---
 Documentation/feature-removal-schedule.txt         |   10 ------
 Documentation/feature-removal/exported-symbols.txt |   34 ++++++++++++++++++++
 arch/x86/kernel/io_delay.c                         |    2 +-
 net/ipv4/inet_hashtables.c                         |    2 +-
 4 files changed, 36 insertions(+), 12 deletions(-)
Documentation/feature-removal-schedule.txt +0 -10
index 4d3aa51..b09b193 100644
@@ -118,16 +118,6 @@ Who:    Adrian Bunk <[email protected]>
 
 ---------------------------
 
-What:	Unused EXPORT_SYMBOL/EXPORT_SYMBOL_GPL exports
-	(temporary transition config option provided until then)
-	The transition config option will also be removed at the same time.
-When:	before 2.6.19
-Why:	Unused symbols are both increasing the size of the kernel binary
-	and are often a sign of "wrong API"
-Who:	Arjan van de Ven <[email protected]>
-
----------------------------
-
 What:	vm_ops.nopage
 When:	Soon, provided in-kernel callers have been converted
 Why:	This interface is replaced by vm_ops.fault, but it has been around
Documentation/feature-removal/exported-symbols.txt new file +34 -0
new file mode 100644
index 0000000..c847792
@@ -0,0 +1,34 @@
+The following is a list of symbols whose exports are unused in the kernel
+tree and will be removed.  Unused symbols are both increasing the size of
+the kernel binary and are often a sign of a "wrong API"
+
+When adding a symbol, change to EXPORT_UNUSED_SYMBOL{_GPL} in the source
+and schedule for removal in the first stable version the unused symbol is
+marked in + 3.  This will give out of tree code ~9 months to stop using the
+export or make a case why the export should be kept.
+
+CONFIG_UNUSED_SYMBOLS is provided to enable unused symbol exports.
+
+Please include the following:
+
+What:	the_symbol
+Where:	filename the symbol is exported from
+When:	next stable version+3
+Why:	a reason would be nice
+
+---------------------------
+
+What:	__inet_hash_connect
+Where:	net/ipv4/inet_hashtables.c
+When:	2.6.28
+Why:	No in tree users
+
+---------------------------
+
+What:	io_delay_type
+Where:	arch/x86/kernel/io_delay.c
+When:	2.6.28
+Why:	No in tree users
+
+---------------------------
+
arch/x86/kernel/io_delay.c +1 -1
index bd49321..a7b8dfb 100644
@@ -13,7 +13,7 @@
 #include <asm/io.h>
 
 int io_delay_type __read_mostly = CONFIG_DEFAULT_IO_DELAY_TYPE;
-EXPORT_SYMBOL_GPL(io_delay_type);
+EXPORT_UNUSED_SYMBOL_GPL(io_delay_type);
 
 static int __initdata io_delay_override;
 
net/ipv4/inet_hashtables.c +1 -1
index 9cac6c0..66d354f 100644
@@ -494,7 +494,7 @@ out:
 		return ret;
 	}
 }
-EXPORT_SYMBOL_GPL(__inet_hash_connect);
+EXPORT_UNUSED_SYMBOL_GPL(__inet_hash_connect);
 
 /*
  * Bind a port for a connect operation and hash it.
Signature · 1 line
1.5.4.1.1278.gc75be
#1 lore raw
Quoted 28 lines · Harvey Harrison

...

Documentation/feature-removal/exported-symbols.txt new file +24 -0
@@ -0,0 +1,34 @@
+The following is a list of symbols whose exports are unused in the kernel
+tree and will be removed.  Unused symbols are both increasing the size of
+the kernel binary and are often a sign of a "wrong API"
+
+When adding a symbol, change to EXPORT_UNUSED_SYMBOL{_GPL} in the source
+and schedule for removal in the first stable version the unused symbol is
+marked in + 3.  This will give out of tree code ~9 months to stop using the
+export or make a case why the export should be kept.
+
+CONFIG_UNUSED_SYMBOLS is provided to enable unused symbol exports.
+
+Please include the following:
+
+What:	the_symbol
+Where:	filename the symbol is exported from
+When:	next stable version+3
+Why:	a reason would be nice
+
+---------------------------
+
+What:	__inet_hash_connect
+Where:	net/ipv4/inet_hashtables.c
+When:	2.6.28
+Why:	No in tree users

Documentation/feature-removal/exported-symbols.txt line 33

Quoted 10 lines
Documentation/feature-removal/exported-symbols.txt new file +9 -0
+
+---------------------------
+
+What:	io_delay_type
+Where:	arch/x86/kernel/io_delay.c
+When:	2.6.28
+Why:	No in tree users
+
+---------------------------
...

NAK.

It's a well-known and documented fact that we not have a stable API for modules.

And as long as we anyway break the modules API in so many other cases with each kernel release there's simply no point in not removing exports immediately.

Oh, and for increasing the amount of nonsense even further, you should explain why unused exports that just sneaked into 2.6.25-rc1 must be shipped in 4 stable kernels before they can be removed.

cu
Adrian

Signature · 4 lines
       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed
#2 lore raw
Quoted 22 lines · Adrian Bunk
Quoted 5 lines · Harvey Harrison
Documentation/feature-removal/exported-symbols.txt new file +5 -0
+
+What:	__inet_hash_connect
+Where:	net/ipv4/inet_hashtables.c
+When:	2.6.28
+Why:	No in tree users

Documentation/feature-removal/exported-symbols.txt line 33

Quoted 10 lines
Documentation/feature-removal/exported-symbols.txt new file +9 -0
+
+---------------------------
+
+What:	io_delay_type
+Where:	arch/x86/kernel/io_delay.c
+When:	2.6.28
+Why:	No in tree users
+
+---------------------------
...

NAK.

It's a well-known and documented fact that we not have a stable API for modules.

Quoted 8 lines

And as long as we anyway break the modules API in so many other cases with each kernel release there's simply no point in not removing exports immediately.

Oh, and for increasing the amount of nonsense even further, you should explain why unused exports that just sneaked into 2.6.25-rc1 must be shipped in 4 stable kernels before they can be removed.

Without comment on the validity of the exports themselves, I was more interested in the principle of announcing these removals, and if it was wanted.

Cheers,

Harvey

#4 lore raw
In reply to Adrian Bunk

BTW:

Sorry and it's not your fault if my answer was a bit harsh.

Your patch forces a nonsense that until now only Andrew tried to enforce (which BTW made me avoiding him whenever possible and never looking at -mm anymore).

There's simply no point in treating the removal of exports differently from the many other API breaks we have in each release.

cu
Adrian

Signature · 4 lines
       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed
#5 lore raw
Quoted 2 lines · On Thu, 14 Feb 2008 00:43:08 +0200 Adrian Bunk <[email protected]> wrote:

There's simply no point in treating the removal of exports differently from the many other API breaks we have in each release.

I have repeatedly and relatively patiently explained to you what the point is. Simply saying that there isn't one doesn't actually make it go away.

#3 lore raw
In reply to Harvey Harrison
Quoted 27 lines · Harvey Harrison
Quoted 26 lines · Adrian Bunk
Quoted 5 lines · Harvey Harrison
Documentation/feature-removal/exported-symbols.txt new file +5 -0
+
+What:	__inet_hash_connect
+Where:	net/ipv4/inet_hashtables.c
+When:	2.6.28
+Why:	No in tree users

Documentation/feature-removal/exported-symbols.txt line 33

Quoted 10 lines
Documentation/feature-removal/exported-symbols.txt new file +9 -0
+
+---------------------------
+
+What:	io_delay_type
+Where:	arch/x86/kernel/io_delay.c
+When:	2.6.28
+Why:	No in tree users
+
+---------------------------
...

NAK.

It's a well-known and documented fact that we not have a stable API for modules.

And as long as we anyway break the modules API in so many other cases with each kernel release there's simply no point in not removing exports immediately.

Quoted 7 lines
Quoted 3 lines

Oh, and for increasing the amount of nonsense even further, you should explain why unused exports that just sneaked into 2.6.25-rc1 must be shipped in 4 stable kernels before they can be removed.

Without comment on the validity of the exports themselves, I was more interested in the principle of announcing these removals, and if it was wanted.

Sorry again for being too harsh (see my other email).

Every kernel release has a big amount of API changes that have not been announced previously, and that's a fact that is rooted in the kernel development model.

Otherwise everyone also had to announce now if he wanted to e.g. change a function prototype or a struct in 2.6.28.

Quoted 3 lines

Cheers,

Harvey

cu
Adrian

Signature · 4 lines
       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed
#10 lore raw
In reply to Harvey Harrison
Quoted 20 lines · On Wed, 13 Feb 2008 14:22:06 -0800 Harvey Harrison <[email protected]>…
---
 Documentation/feature-removal-schedule.txt         |   10 ------
 Documentation/feature-removal/exported-symbols.txt |   34
++++++++++++++++++++
arch/x86/kernel/io_delay.c                         |    2 +-
net/ipv4/inet_hashtables.c                         |    2 +- 4 files

changed, 36 insertions(+), 12 deletions(-)

(quoted diff) +0 -0

b/Documentation/feature-removal-schedule.txt index 4d3aa51..b09b193 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt

Documentation/feature-removal-schedule.txt +0 -3
@@ -118,16 +118,6 @@ Who:    Adrian Bunk <[email protected]>
 
 ---------------------------
 
-What:	Unused EXPORT_SYMBOL/EXPORT_SYMBOL_GPL exports
-	(temporary transition config option provided until then)
-	The transition config option will also be removed at the
Quoted 1 line

same time. -When: before 2.6.19

3 releases is too long imo
1 release is plenty (esp since it's really 1 release + one devel cycle)

#6 lore raw
In reply to Andrew Morton
Quoted 9 lines · Andrew Morton
Quoted 2 lines · On Thu, 14 Feb 2008 00:43:08 +0200 Adrian Bunk <[email protected]> wrote:

There's simply no point in treating the removal of exports differently from the many other API breaks we have in each release.

I have repeatedly and relatively patiently explained to you what the point is. Simply saying that there isn't one doesn't actually make it go away.

Yes, we had this when you insisted on the deprecation period for sys_open which still brings me to explosion each time such topics come up and brought you _very_ near at being the first person ever in my killfile.

I don't get your point why bigger API changes should still be allowed without any advance warning while removing an export should require deprecation periods.

If you want to offer a stable API for external modules then please do it completely and with all consequences.

cu
Adrian

Signature · 4 lines
       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed
#7 lore raw
Quoted 3 lines · On Thu, 14 Feb 2008 01:22:48 +0200 Adrian Bunk <[email protected]> wrote:

I don't get your point why bigger API changes should still be allowed without any advance warning while removing an export should require deprecation periods.

Because the cost to us of giving people a few months warning is miniscule, and doing so a) is courteous to our users and b) possibly avoids driving away testers.

otoh the cost to us of avoiding large API changes is much much higher, so the tradeoff has a different outcome.

Quoted 2 lines

If you want to offer a stable API for external modules then please do it completely and with all consequences.

Sorry, but you have this belief that if we do X in one case then we should rigorously do X in all cases. That everything we do sets precedents which must be forever and in all cases followed. That it is all about rules and sticking to them. That if you can catch person A taking action B then you can trap that person into doing B in all cases for ever more.

Well it doesn't work like that. Each case is different and each case has pros and cons and each one needs to be weighed according to those pros and cons.

#8 lore raw
Quoted 10 lines · Andrew Morton
Quoted 3 lines · On Thu, 14 Feb 2008 01:22:48 +0200 Adrian Bunk <[email protected]> wrote:

I don't get your point why bigger API changes should still be allowed without any advance warning while removing an export should require deprecation periods.

Because the cost to us of giving people a few months warning is miniscule, and doing so a) is courteous to our users and b) possibly avoids driving away testers.

The miniscule cost is my spare time and my nerves.

These unexport discussions are _the_ thing that have turned kernel development from having been fun into creating anger for me. If your goal is to bring me to quitting kernel development and spending my spare time differently you've already gotten quite near to reaching your goal.

Quoted 12 lines

otoh the cost to us of avoiding large API changes is much much higher, so the tradeoff has a different outcome.

Quoted 2 lines

If you want to offer a stable API for external modules then please do it completely and with all consequences.

Sorry, but you have this belief that if we do X in one case then we should rigorously do X in all cases. That everything we do sets precedents which must be forever and in all cases followed. That it is all about rules and sticking to them. That if you can catch person A taking action B then you can trap that person into doing B in all cases for ever more.

Quoted 3 lines

Well it doesn't work like that. Each case is different and each case has pros and cons and each one needs to be weighed according to those pros and cons.

Unexports are done immediately when there's a subsystem maintainer taking a patch and deprecation periods are required when a patch has to go through you...

cu
Adrian

Signature · 4 lines
       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed
#9 lore raw
Quoted 3 lines

Unexports are done immediately when there's a subsystem maintainer taking a patch and deprecation periods are required when a patch has to go through you...

Agreed - with the expect of stuff which is used in tree or forms part of a logical exported API we should just throw them out without messing. The only exceptions I can see that make sense are

- Where a subsystem maintainer says not to
- Where we know that a commonly used out of tree module needs it

Most of the excess symbols should thus just go away. Its pretty unlikely that they are being used.

Alan

#11 lore raw
In reply to Harvey Harrison

Documentation/feature-removal/exported-symbols.txt line 31

Quoted 6 lines · Harvey Harrison

+---------------------------

Documentation/feature-removal/exported-symbols.txt new file +5 -0
+
+What:	io_delay_type
+Where:	arch/x86/kernel/io_delay.c
+When:	2.6.28
+Why:	No in tree users

The entirety of io_delay.c should be gone long before .28. It's a short term thing till the port 0x80 problems have been dealt with.

Rene.