[MAINTAINER SUMMIT] Enforcing API deprecation

[MAINTAINER SUMMIT] Enforcing API deprecation

[Bartosz Golaszewski]

I am not sure how many other maintainers are affected by the issue I'm
about to describe but I imagine it impacts to some degree all
subsystems that have existed for a long time, have undergone
significant reworks and whose API is used ubiquitously tree-wide
across many files. Power-management and device properties/driver core
APIs come to mind as potential examples and I personally face it with
the GPIO subsystem.

Deprecating legacy programming interfaces after introducing better
alternatives is a natural result of the way the kernel is developed
and the size of the codebase. We typically cannot rework interfaces in
a single patch or series series, especially when dealing with existing
cross-tree consumers.

What we usually do is:
1. Provide an alternative solution living in parallel to the old one.
2. Mark the legacy interfaces as deprecated in their kerneldocs.
3. Slowly convert users one by one until the relevant symbols are no
longer called anywhere in the kernel.
4. Remove legacy interface.

A problem occurs when during step #3 (which may take anywhere from
several releases to many years depending on how commonly given
interface is used), developers continue to introduce new calls to the
deprecated routines. This is not always easily caught, because quite
often patches using the API of a given subsystem will not be send to
this subsystem's maintainer (Example: while GPIO core code lives under
drivers/gpio/, there are lots of provider implementations and even
more consumers spread tree-wide. I cannot possibly catch every commit
I'm not explicitly Cc'ed on and eventually some will fly under the
radar. Also: this is not a good solution if I have to manually object
every time, this should be more or less automated).

A lot of less experienced driver developers write their code by simply
copy-pasting from existing modules without checking whether given
symbols are marked as deprecated.

There are several things that look like potential solutions:
1. Use gcc's __attribute__((deprecated)) (Linus doesn't like it[1] and
with hundreds of calls to convert it wouldn't be acceptable).
2. Use keywords in MAINTAINERS entries (this sounds like an abuse of
what this file is really for and can sometimes be hard to get right.
Also: see above about it not being very efficient).
3. Make checkpatch.pl check the patches for new uses of deprecated
APIs (similarly to what it does for invalid usage of memory and log
helpers)
4. Make build bots detect it.

And probably many more I haven't thought of.

I would like to propose a discussion on how to enforce API deprecation
in a way that supports efforts to reduce technical debt, without being
hampered by developers and maintainers who mean no harm but simply
don’t know any better.

Best Regards,
Bartosz Golaszewski

[1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=771c035372a036f83353eef46dbb829780330234

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Linus Torvalds]

On Tue, 26 Aug 2025 at 12:58, Bartosz Golaszewski
<bartosz.golaszewski@linaro.org> wrote:
>
> 1. Use gcc's __attribute__((deprecated)) (Linus doesn't like it

No. Unacceptable. We do not introduce warnings that aren't immediately fixed.

And no - this isn't even getting discussed. The kernel stays
warning-free, which means that "__attribute__((deprecated))" isn't
something that "Linus doesn't like". It's simply NOT AN OPTION.

> 2. Use keywords in MAINTAINERS entries (this sounds like an abuse of
> what this file is really for and can sometimes be hard to get right.
> Also: see above about it not being very efficient).
> 3. Make checkpatch.pl check the patches for new uses of deprecated
> APIs (similarly to what it does for invalid usage of memory and log
> helpers)
> 4. Make build bots detect it.

Fine, but doesn't solve anything.

> I would like to propose a discussion on how to enforce API deprecation
> in a way that supports efforts to reduce technical debt, without being
> hampered by developers and maintainers who mean no harm but simply
> don’t know any better.

Here's the only thing that works: if you change the API, you have to
fix up all existing users.

If you are not willing to fix up all existing users, and you introduce
a parallel API, then you are the one that maintains both the old and
the new API forever.

Or at least until somebody else did the work that you weren't willing to do.

End result: the burden of new / different API's is on the person
introducing them. IOW: don't introduce new API's unless you are
willing to support them.

             Linus

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Johannes Berg]

On Tue, 2025-08-26 at 21:57 +0200, Bartosz Golaszewski wrote:
> What we usually do is:
> 1. Provide an alternative solution living in parallel to the old one.
> 2. Mark the legacy interfaces as deprecated in their kerneldocs.
> 3. Slowly convert users one by one until the relevant symbols are no
> longer called anywhere in the kernel.
> 4. Remove legacy interface.
> 
> A problem occurs when during step #3 (which may take anywhere from
> several releases to many years depending on how commonly given
> interface is used), developers continue to introduce new calls to the
> deprecated routines. This is not always easily caught, because quite
> often patches using the API of a given subsystem will not be send to
> this subsystem's maintainer (Example: while GPIO core code lives under
> drivers/gpio/, there are lots of provider implementations and even
> more consumers spread tree-wide. I cannot possibly catch every commit
> I'm not explicitly Cc'ed on and eventually some will fly under the
> radar. Also: this is not a good solution if I have to manually object
> every time, this should be more or less automated).

Once most things are converted, copy/paste will die automatically use
the right things. Sure, you might think you're almost there and then a
handful of new users are introduced, but you can actually remove the
APIs in -next and then the new ones fail to build there, if you're that
far along.

I guess you have to ask yourself how much it matters?

Is it a major hassle to keep supporting the old API? Then I guess the
effort to support the old API outweighs the effort to convert it
quickly, so do that?

If the old API just calls the new API or something simple you basically
keep the old API forever (I just looked at PCI MSI APIs which have said
it's deprecated for almost a decade, and yet is still the most commonly
used one ... I guess it didn't matter). If it doesn't matter then really
all you did was introduce an _additional_ API that might let you solve
whatever problem you were trying to solve that the old API didn't let
you solve, but isn't needed for the vast majority of cases?

More nagging etc. really won't change anything except stress maintainers
out even more, make people ignore it, etc. Whoever cares can do the
conversion, but if whoever maintains the API doesn't actually care about
converting it, why should anyone else?

johannes

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Jiri Kosina]

On Tue, 26 Aug 2025, Linus Torvalds wrote:

> > I would like to propose a discussion on how to enforce API deprecation
> > in a way that supports efforts to reduce technical debt, without being
> > hampered by developers and maintainers who mean no harm but simply
> > don’t know any better.
> 
> Here's the only thing that works: if you change the API, you have to
> fix up all existing users.
> 
> If you are not willing to fix up all existing users, and you introduce
> a parallel API, then you are the one that maintains both the old and
> the new API forever.

I don't disagree, I just feel that it's important to note that it's pretty 
much impossible to do a proper functional testing of many such 
conversions.
Especially when drivers are involved on the consuming side. Even more so 
if obscure ones (which is quite often the case in driver space).

But yes, if there are people who do care about such drivers, they will 
speak up once they get hit by the breakage, so it's not a huge problem 
either.

-- 
Jiri Kosina
SUSE Labs

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Laurent Pinchart]

On Tue, Aug 26, 2025 at 10:24:42PM +0200, Johannes Berg wrote:
> On Tue, 2025-08-26 at 21:57 +0200, Bartosz Golaszewski wrote:
> > What we usually do is:
> > 1. Provide an alternative solution living in parallel to the old one.
> > 2. Mark the legacy interfaces as deprecated in their kerneldocs.
> > 3. Slowly convert users one by one until the relevant symbols are no
> > longer called anywhere in the kernel.
> > 4. Remove legacy interface.
> > 
> > A problem occurs when during step #3 (which may take anywhere from
> > several releases to many years depending on how commonly given
> > interface is used), developers continue to introduce new calls to the
> > deprecated routines. This is not always easily caught, because quite
> > often patches using the API of a given subsystem will not be send to
> > this subsystem's maintainer (Example: while GPIO core code lives under
> > drivers/gpio/, there are lots of provider implementations and even
> > more consumers spread tree-wide. I cannot possibly catch every commit
> > I'm not explicitly Cc'ed on and eventually some will fly under the
> > radar. Also: this is not a good solution if I have to manually object
> > every time, this should be more or less automated).
> 
> Once most things are converted, copy/paste will die automatically use
> the right things. Sure, you might think you're almost there and then a
> handful of new users are introduced, but you can actually remove the
> APIs in -next and then the new ones fail to build there, if you're that
> far along.
> 
> I guess you have to ask yourself how much it matters?
> 
> Is it a major hassle to keep supporting the old API? Then I guess the
> effort to support the old API outweighs the effort to convert it
> quickly, so do that?
> 
> If the old API just calls the new API or something simple you basically
> keep the old API forever (I just looked at PCI MSI APIs which have said
> it's deprecated for almost a decade, and yet is still the most commonly
> used one ... I guess it didn't matter). If it doesn't matter then really
> all you did was introduce an _additional_ API that might let you solve
> whatever problem you were trying to solve that the old API didn't let
> you solve, but isn't needed for the vast majority of cases?
> 
> More nagging etc. really won't change anything except stress maintainers
> out even more, make people ignore it, etc. Whoever cares can do the
> conversion, but if whoever maintains the API doesn't actually care about
> converting it, why should anyone else?

As Bartosz mentioned, some new users of those deprecated APIs may not
even know that they should use a different API. Adding warnings to
checkpatch could help raise awareness. I don't think that would stress
out maintainers, and while some authors may ignore it, it seems worth it
to me: it's low effort, not intrusive, and can help developers who
refactor code without much drawback.

-- 
Regards,

Laurent Pinchart

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Linus Torvalds]

On Tue, 26 Aug 2025 at 13:28, Jiri Kosina <jikos@kernel.org> wrote:
>
> > If you are not willing to fix up all existing users, and you introduce
> > a parallel API, then you are the one that maintains both the old and
> > the new API forever.
>
> I don't disagree, I just feel that it's important to note that it's pretty
> much impossible to do a proper functional testing of many such
> conversions.

Yes.

And I think the takeaway from that should be "think through the API
conversion before you go wild".

If you can't automate a good 1:1 conversion that is clearly a no-op,
maybe your new API is just complete garbage.

Honestly, if a new API is not a 100% obvious proper superset of the
old one, WTF are you doing?

IOW, if you are creating a new API that doesn't express the EXACT SAME
behavior as the old API did as one part of it, I think your new API is
likely complete and utter shite.

So the starting point should be that any new API can AT LEAST express
the old API as one situation.  If you can't do that, don't even start.

And then, as a second step, think about how you express the new API so
that it's _easy_ to convert with automation.

Exactly so that you don't have to test every single conversion,
because when it comes to most drivers, that simply isn't an option
when hardware access may be very questionable.

(In some other areas, you *can* test things - at least in theory,
architecture interfaces and filesystems should be things that you can
ask people to actually test, because there are only a handful of cases
- and automating it may not be possible anyway, because some new
architecture feature may require writing some new assembly sequence
etc)

And yes, I agree that a lot of API conversions have *not* been done
with those "proper superset" and "easy conversion" steps in mind. We
obviously have had a lot of parallel API's all over the kernel, some
of them living for years.

The biggest pain points are often semantic locking issues, and the VFS
layer kept those duplicate "locked or shared" operations around for a
long time - we introduced the 'shared' directory iteration back in
2016, and the locked version *finally* went away in 2023, so it stayed
around for over seven years..

But maybe sometimes the API changes are just too damn big in the name
of "let's get it right".

Perfect is often the enemy of good. Making the new API easier to
convert to, in the name of making for a smoother development model,
may be the right thing to do, even if maybe the new API isn't then
everything you would want it to be.

I suspect Bartosz comes at this from the recent GPIO setting changes,
and honestly, I do think that could have been done with a coccinelle
script originally, instead of doing a parallel API at all.

             Linus

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Al Viro]

On Tue, Aug 26, 2025 at 03:44:13PM -0700, Linus Torvalds wrote:

> If you can't automate a good 1:1 conversion that is clearly a no-op,
> maybe your new API is just complete garbage.
> 
> Honestly, if a new API is not a 100% obvious proper superset of the
> old one, WTF are you doing?
> 
> IOW, if you are creating a new API that doesn't express the EXACT SAME
> behavior as the old API did as one part of it, I think your new API is
> likely complete and utter shite.

Depends... An example of a bad API: dma_buf_fd().  It grabs a descriptor and
attaches an opened file associated with dmabuf to it;  lifetime of dmabuf
is that of the file in question, so the reference is consumed on success
and left to caller on failure.  Users (and that's after fixing a bunch of
broken ones during the last couple of cycles):

dma_heap_buffer_alloc():
	...
        fd = dma_buf_fd(dmabuf, fd_flags);
        if (fd < 0) {
                dma_buf_put(dmabuf);
                /* just return, as put will call release and that will free */
        }
        return fd;

udmabuf_create():
	...
        ret = dma_buf_fd(dmabuf, flags);
        if (ret < 0)
                dma_buf_put(dmabuf);

kfd_ioctl_export_dmabuf():
	...
        ret = dma_buf_fd(dmabuf, args->flags);
        if (ret < 0) {
                dma_buf_put(dmabuf);
                goto err_out;
        }
	...

intel_vgpu_get_dmabuf():
	...
        ret = dma_buf_fd(dmabuf, DRM_CLOEXEC | DRM_RDWR);
        if (ret < 0) {
                gvt_vgpu_err("create dma-buf fd failed ret:%d\n", ret);
                goto out_free_dmabuf;
        }
	...
out_free_dmabuf:
        dma_buf_put(dmabuf);

ttm_prime_handle_to_fd():
        ret = dma_buf_fd(dma_buf, flags);
        if (ret >= 0) {
                *prime_fd = ret;
                ret = 0;
        } else
                dma_buf_put(dma_buf);

vb2_core_expbuf():
        ret = dma_buf_fd(dbuf, flags & ~O_ACCMODE);
        if (ret < 0) {
                dprintk(q, 3, "buffer %d, plane %d failed to export (%d)\n",
                        vb->index, plane, ret);
                dma_buf_put(dbuf);
                return ret;
        }

fastrpc_dmabuf_alloc():
        bp.fd = dma_buf_fd(buf->dmabuf, O_ACCMODE);
        if (bp.fd < 0) {
                dma_buf_put(buf->dmabuf);
                return -EINVAL;
        }

... and in samples/video-mdev/mbochs.c:mbochs_get_gfx_dmabuf()
	...
        return dma_buf_fd(dmabuf->buf, 0);

Which leaks on failure, and samples/* is not a good place for that,
since it invites copying the leak back into drivers.

IMO that thing has wrong calling conventions.  I have not done anything
besides fixing the obvious bugs in users (and leaks were not even close
to the worst problems - try to access dmabuf after _success_ and you
get a UAF since another thread can guess the descriptor and close(2)
it) since I'm not involved in any of the areas where it's used, and when
asking opinions re changing the calling conventions got zero reaction...
*shrug*

I still think that saner replacement should consume the reference passed
to it both on success and on failure.  Theoretically, you can express
the original through that (bump refcount of file associated with dmabuf,
call that "saner replacement", then do dma_buf_put() only in case
of success), but at that point I'd say that original API is shite and
simulating it is just plain wrong.  _If_ we go for eliminating it,
that is - another approach is to grep through the tree once in a while
and watch out of new bugs cropping up in the callers.  Up to the
folks maintaining that area, really...

A similar thing around fs/* would have all in-tree users replaced, with
description placed in Documentation/filesystems/porting.rst ("recommended:
if you are using sucky_API(), see if you have run afoul of such and such
scenario.  Convert to replacement_API() in such and such way", basically)
and either taken out immediately (with s/recommended/mandatory/) or left
alone for a cycle or two, then ripped out.

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Bartosz Golaszewski]

On Tue, 26 Aug 2025 at 22:12, Linus Torvalds
<torvalds@linux-foundation.org> wrote:
>
> On Tue, 26 Aug 2025 at 12:58, Bartosz Golaszewski
> <bartosz.golaszewski@linaro.org> wrote:
> >

[snip]

> > 4. Make build bots detect it.
>
> Fine, but doesn't solve anything.
>

How so? The developer gets an email telling them they used a legacy
API, the maintainer sees a build bot report and knows to ignore the
patch. That's already better than what we (don't) have currently.

> > I would like to propose a discussion on how to enforce API deprecation
> > in a way that supports efforts to reduce technical debt, without being
> > hampered by developers and maintainers who mean no harm but simply
> > don’t know any better.
>
> Here's the only thing that works: if you change the API, you have to
> fix up all existing users.
>
> If you are not willing to fix up all existing users, and you introduce
> a parallel API, then you are the one that maintains both the old and
> the new API forever.
>
> Or at least until somebody else did the work that you weren't willing to do.
>

That sounds great in theory but in practice, one may be willing to do
the work and it will still take years (as is the case with GPIO) where
there were thousands of calls to the legacy API and - due to the
nature of the differences between the old and new one - the
conversions are far from trivial.

I'm not advocating a policy change, I'm trying to bring up the subject
of making the effort easier for those who participate in the tree-wide
refactoring.

> End result: the burden of new / different API's is on the person
> introducing them. IOW: don't introduce new API's unless you are
> willing to support them.
>

I would assume, kernel developers in general and maintainers in
particular want to make linux better. An old API may have been
introduced long ago in times where we didn't know what we didn't know
(or even implemented by completely different people altogether) and
the new one, implemented later, is objectively better.

Sometimes a new API is close enough to the old one, that it can simply
be wrapped in backward compatible inline functions and the
implementation is the same for both. That's awesome and supporting the
legacy interface is not a big problem in this case. However, in other
cases, the underlying change in philosophy can be so fundamental that
we effectively end up with two intertwined implementations where a lot
of code could simply be removed once we unify all the users. In our
case, the work IS happening and several people are contributing. My
point is: this effort is commendable and should be supported rather
than brushed off with a "that's the API's author problem". I'm sure I
don't have to even name the advantages of having less code to
maintain.

And to address your last sentence on a personal note: thing's arent
always so black and white - for me: I inherited the GPIO subsystem
with both the old and the new API already present tree-wide and am
just trying to improve the pre-existing situation.

Thanks,
Bartosz

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Julia Lawall]

[-- Attachment #1: Type: text/plain, Size: 3428 bytes --]



On Wed, 27 Aug 2025, Bartosz Golaszewski wrote:

> On Tue, 26 Aug 2025 at 22:12, Linus Torvalds
> <torvalds@linux-foundation.org> wrote:
> >
> > On Tue, 26 Aug 2025 at 12:58, Bartosz Golaszewski
> > <bartosz.golaszewski@linaro.org> wrote:
> > >
>
> [snip]
>
> > > 4. Make build bots detect it.
> >
> > Fine, but doesn't solve anything.
> >
>
> How so? The developer gets an email telling them they used a legacy
> API, the maintainer sees a build bot report and knows to ignore the
> patch. That's already better than what we (don't) have currently.
>
> > > I would like to propose a discussion on how to enforce API deprecation
> > > in a way that supports efforts to reduce technical debt, without being
> > > hampered by developers and maintainers who mean no harm but simply
> > > don’t know any better.
> >
> > Here's the only thing that works: if you change the API, you have to
> > fix up all existing users.
> >
> > If you are not willing to fix up all existing users, and you introduce
> > a parallel API, then you are the one that maintains both the old and
> > the new API forever.
> >
> > Or at least until somebody else did the work that you weren't willing to do.
> >
>
> That sounds great in theory but in practice, one may be willing to do
> the work and it will still take years (as is the case with GPIO) where
> there were thousands of calls to the legacy API and - due to the
> nature of the differences between the old and new one - the
> conversions are far from trivial.
>
> I'm not advocating a policy change, I'm trying to bring up the subject
> of making the effort easier for those who participate in the tree-wide
> refactoring.
>
> > End result: the burden of new / different API's is on the person
> > introducing them. IOW: don't introduce new API's unless you are
> > willing to support them.
> >
>
> I would assume, kernel developers in general and maintainers in
> particular want to make linux better. An old API may have been
> introduced long ago in times where we didn't know what we didn't know
> (or even implemented by completely different people altogether) and
> the new one, implemented later, is objectively better.
>
> Sometimes a new API is close enough to the old one, that it can simply
> be wrapped in backward compatible inline functions and the
> implementation is the same for both. That's awesome and supporting the
> legacy interface is not a big problem in this case. However, in other
> cases, the underlying change in philosophy can be so fundamental that
> we effectively end up with two intertwined implementations where a lot
> of code could simply be removed once we unify all the users. In our
> case, the work IS happening and several people are contributing. My
> point is: this effort is commendable and should be supported rather
> than brushed off with a "that's the API's author problem". I'm sure I
> don't have to even name the advantages of having less code to
> maintain.
>
> And to address your last sentence on a personal note: thing's arent
> always so black and white - for me: I inherited the GPIO subsystem
> with both the old and the new API already present tree-wide and am
> just trying to improve the pre-existing situation.

Is there some centralized place listing what APis need attention and
giving some hints about what should be done?  Hints could be text or
change examples or pointers to commits where the change has been done.

julia

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Bartosz Golaszewski]

On Wed, 27 Aug 2025 at 00:44, Linus Torvalds
<torvalds@linux-foundation.org> wrote:
>

[snip]

>
> Perfect is often the enemy of good. Making the new API easier to
> convert to, in the name of making for a smoother development model,
> may be the right thing to do, even if maybe the new API isn't then
> everything you would want it to be.
>
> I suspect Bartosz comes at this from the recent GPIO setting changes,
> and honestly, I do think that could have been done with a coccinelle
> script originally, instead of doing a parallel API at all.
>

No, not at all, that was super easy as the conversions were - for most
part - trivial and while I did catch some new incoming code with the
old callbacks, the whole conversion took 2 or 3 cycles so that wasn't
an issue.

I'm mostly referring to the conversion from global GPIO numbers to
GPIO descriptors. This change is so profound that the two APIs don't
even have much in common (including their implementations) so most of
your points above don't apply: there's a fundamental difference
between requesting a global GPIO number that's a magic value defined
somewhere and getting it through device property accessors. We do, of
course, have a compatibility layer for that but it's janky at best.

This is the conversion that's really challenging and taking years and
the progress is slow because you have to functionally test these
changes. This cannot be automated or coccinelled away because it
touches on providers, consumers and firmware nodes.

And in the process: even really experienced developers (I won't point
fingers :) ) sometimes submit patches using the legacy API which is
something I'd like to avoid, hence this proposal.

Bartosz

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Bartosz Golaszewski]

On Wed, 27 Aug 2025 at 16:58, Julia Lawall <julia.lawall@inria.fr> wrote:
>

[snip]

> >
> > And to address your last sentence on a personal note: thing's arent
> > always so black and white - for me: I inherited the GPIO subsystem
> > with both the old and the new API already present tree-wide and am
> > just trying to improve the pre-existing situation.
>
> Is there some centralized place listing what APis need attention and
> giving some hints about what should be done?  Hints could be text or
> change examples or pointers to commits where the change has been done.
>
> julia

There's a TODO entry[1], a talk where I described the heaps of
technical debt we're dealing with[2] and lots of patches on the list
called typically something like "convert to GPIO descriptors" and
which look like this[3] or this[4] so quite different depending on
circumstances.

Bartosz

[1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/gpio/TODO#n6
[2] https://www.youtube.com/watch?v=BR41Yg69c9Y
[3] https://lore.kernel.org/all/20250808151822.536879-18-arnd@kernel.org/
[4] https://lore.kernel.org/all/20240423-gpio-leds-v1-3-799c2f6bc61c@linaro.org/

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Rob Herring]

On Wed, Aug 27, 2025 at 10:34 AM Bartosz Golaszewski
<bartosz.golaszewski@linaro.org> wrote:
>
> On Wed, 27 Aug 2025 at 00:44, Linus Torvalds
> <torvalds@linux-foundation.org> wrote:
> >
>
> [snip]
>
> >
> > Perfect is often the enemy of good. Making the new API easier to
> > convert to, in the name of making for a smoother development model,
> > may be the right thing to do, even if maybe the new API isn't then
> > everything you would want it to be.
> >
> > I suspect Bartosz comes at this from the recent GPIO setting changes,
> > and honestly, I do think that could have been done with a coccinelle
> > script originally, instead of doing a parallel API at all.
> >
>
> No, not at all, that was super easy as the conversions were - for most
> part - trivial and while I did catch some new incoming code with the
> old callbacks, the whole conversion took 2 or 3 cycles so that wasn't
> an issue.
>
> I'm mostly referring to the conversion from global GPIO numbers to
> GPIO descriptors. This change is so profound that the two APIs don't
> even have much in common (including their implementations) so most of
> your points above don't apply: there's a fundamental difference
> between requesting a global GPIO number that's a magic value defined
> somewhere and getting it through device property accessors. We do, of
> course, have a compatibility layer for that but it's janky at best.
>
> This is the conversion that's really challenging and taking years and
> the progress is slow because you have to functionally test these
> changes. This cannot be automated or coccinelled away because it
> touches on providers, consumers and firmware nodes.
>
> And in the process: even really experienced developers (I won't point
> fingers :) ) sometimes submit patches using the legacy API which is
> something I'd like to avoid, hence this proposal.

I have a similar situation with DT APIs. It's a bit more nuanced than
the GPIO case. There's old APIs which are "don't add new users" or
"think twice before you add a new user". We may never get rid of the
APIs because a) no one wants to fix PPC and Sparc and b) there's
sometimes a need for these lower level functions. It's similar to
using devm_ APIs vs. the non devm_ variants.

Rob

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Linus Torvalds]

On Wed, 27 Aug 2025 at 09:42, Rob Herring <robherring2@gmail.com> wrote:
>
> I have a similar situation with DT APIs. It's a bit more nuanced than
> the GPIO case. There's old APIs which are "don't add new users" or
> "think twice before you add a new user". We may never get rid of the
> APIs because a) no one wants to fix PPC and Sparc and b) there's
> sometimes a need for these lower level functions. It's similar to
> using devm_ APIs vs. the non devm_ variants.

Having parallel APIs for different use cases is perfectly fine.
Normal, even, and not something that we should worry about or even
strive to avoid.

The devm_xyz() vs just plain xyz() is a good example of that. They are
parallel for good reasons, and they will remain forever.

All I'm saying is that people who do new API's should either just
accept that, or just convert between the two. None of this "deprecate"
garbage. None of this "blame other developers because they use the old
interface".

That's the basic tenet here: if you are too lazy to convert all users,
you also do not have the moral right to complain about - or expect -
others not doing the work you didn't do for you.

               Linus

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Bartosz Golaszewski]

On Wed, 27 Aug 2025 at 18:58, Linus Torvalds
<torvalds@linux-foundation.org> wrote:
>
> All I'm saying is that people who do new API's should either just
> accept that, or just convert between the two. None of this "deprecate"
> garbage. None of this "blame other developers because they use the old
> interface".
>

How about "let developers know, people are actively working to replace
this old, bad* API with a better alternative so at least don't
(unknowingly) sabotage their efforts"?

> That's the basic tenet here: if you are too lazy to convert all users,
> you also do not have the moral right to complain about - or expect -
> others not doing the work you didn't do for you.
>

That's just being mean for no reason. I already said it elsewhere in
this thread but let me reiterate: sometimes a new (surely not lazy)
developer shows up and wants to improve an already messy situation
(for instance: remove the cruft resulting from having two APIs that
could be unified with some effort). They may very well not be
responsible for the problem at all. Don't they have the moral right to
at least steer the subsequent development from others in the right
direction if they're willing to do the heavy lifting? No complaining
and no blaming: just advice on how to use a given subsystem. Like, I
don't know, telling user-space to not use sysctl() (the system call)
back in the day because it's bad and was replaced by the /proc/sys
alternative?

And what is it with this "all or nothing" approach? What if it's not
feasible (too many places to fix at once)? I'm not sure telling
someone who wants to improve 1% of the code-base that they "either fix
100% or go away" is a good approach. If the kernel looks better after
this hypothetical conversion, then isn't it worth supporting? Telling
users not to use a specific set of functions and instead go with a
different one isn't really a big issue, is it?

Bartosz

* - The API may have looked good when it was introduced but things
change and new use-cases come up. GPIO would have never needed the big
locking overhaul we did a couple cycles back, had we just kept only
supporting MMIO chips. But things do evolve...

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Krzysztof Kozlowski]

On 27/08/2025 16:47, Bartosz Golaszewski wrote:
> On Tue, 26 Aug 2025 at 22:12, Linus Torvalds
> <torvalds@linux-foundation.org> wrote:
>>
>> On Tue, 26 Aug 2025 at 12:58, Bartosz Golaszewski
>> <bartosz.golaszewski@linaro.org> wrote:
>>>
> 
> [snip]
> 
>>> 4. Make build bots detect it.
>>
>> Fine, but doesn't solve anything.
>>
> 
> How so? The developer gets an email telling them they used a legacy
> API, the maintainer sees a build bot report and knows to ignore the
> patch. That's already better than what we (don't) have currently.

I think build-time warnings or emails from LKP about using deprecated
API do solve the problem, in the very long term. Why? We do remove old
platforms, so even if we do not convert in-tree users from deprecated
API, these warnings would reduce amount of new code coming to the
kernel. Eventually at some point we just drop old architectures, old
platforms or drivers and that might be the last user of the deprecated API.


> 
>>> I would like to propose a discussion on how to enforce API deprecation
>>> in a way that supports efforts to reduce technical debt, without being
>>> hampered by developers and maintainers who mean no harm but simply
>>> don’t know any better.
>>
>> Here's the only thing that works: if you change the API, you have to
>> fix up all existing users.
>>
>> If you are not willing to fix up all existing users, and you introduce
>> a parallel API, then you are the one that maintains both the old and
>> the new API forever.

Sure, I don't think anyone questions that part. So imagine we maintain
both APIs, but we do not want the old one to grow?

>>
>> Or at least until somebody else did the work that you weren't willing to do.
>>
> 
> That sounds great in theory but in practice, one may be willing to do
> the work and it will still take years (as is the case with GPIO) where
> there were thousands of calls to the legacy API and - due to the
> nature of the differences between the old and new one - the
> conversions are far from trivial.
> 
> I'm not advocating a policy change, I'm trying to bring up the subject
> of making the effort easier for those who participate in the tree-wide
> refactoring.

How about sparse attributes for the old API as deprecated and in the
same time all existing users as "ignore-that-sparse-warning"? We already
have a few drivers doing:
	#ifdef __CHECKER__
to avoid many false positives (e.g. handling inlines). Also few for
skipping locking (drivers/scsi/qla2xxx/qla_nx.c), but this feels rather
like anti-pattern.

We also have cases of:
	#ifdef CONFIG_CC_IS_GCC
	#pragma GCC diagnostic ignored "-Wsuggest-attribute=format"
	#endif


Best regards,
Krzysztof

Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Eric W. Biederman]

Bartosz Golaszewski <bartosz.golaszewski@linaro.org> writes:

> On Wed, 27 Aug 2025 at 18:58, Linus Torvalds
> <torvalds@linux-foundation.org> wrote:
>>
>> All I'm saying is that people who do new API's should either just
>> accept that, or just convert between the two. None of this "deprecate"
>> garbage. None of this "blame other developers because they use the old
>> interface".
>>
>
> How about "let developers know, people are actively working to replace
> this old, bad* API with a better alternative so at least don't
> (unknowingly) sabotage their efforts"?

Perhaps the old API could be hidden in the header files unless
an appropriate macro is defined before including the headers.
Something like:

#define I_REALLY_REALLY_WANT_TO_USE_THIS_OLD_JANKY_API

Everything can be mass converted to that safely, and any random
stragglers can be updated quickly.

At which point any new uses will be at least give people a hint
that something else is going on.  There would still be a lot of
cat herding involved to get the conversion done.

Finding uses of the old api would be a simple as grepping for the
define, or changing the define in the header and doing a complete
kernel build.

Eric