feature-removal: add documentation for exported symbols going away
Subsystems (4)
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
@@ -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
@@ -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
@@ -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
@@ -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
Adrian Bunk
NAKQuoted 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 SeedQuoted 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 usersDocumentation/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
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 SeedQuoted 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.
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 usersDocumentation/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 SeedQuoted 20 lines · On Wed, 13 Feb 2008 14:22:06 -0800 Harvey Harrison <[email protected]>…
Signed-off-by 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 fileschanged, 36 insertions(+), 12 deletions(-)
(quoted diff) +0
-0
b/Documentation/feature-removal-schedule.txtindex 4d3aa51..b09b193 100644 ---a/Documentation/feature-removal-schedule.txt+++b/Documentation/feature-removal-schedule.txtDocumentation/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)
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 SeedQuoted 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.
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 SeedQuoted 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
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.