On Fri, Feb 3, 2023 at 7:57 AM David Vernet <void@xxxxxxxxxxxxx> wrote: > > BPF kernel <-> kernel API stability has been discussed at length over > the last several weeks and months. Now that we've largely aligned over > kfuncs being the way forward, and BPF helpers being considered > functionally frozen, it's time to document the expectations for kfunc > lifecycles and stability so that everyone (BPF users, kfunc developers, > and maintainers) are all aligned, and have a crystal-clear understanding > of the expectations surrounding kfuncs. > > To do that, this patch adds that documentation to the main kfuncs > documentation page via a new 'kfunc lifecycle expectations' section. The > patch describes how decisions are made in the kernel regarding whether > to include, keep, deprecate, or change / remove a kfunc. As described > very overtly in the patch itself, but likely worth highlighting here: > > "kfunc stability" does not mean, nor ever will mean, "BPF APIs may block > development elsewhere in the kernel". > > Rather, the intention and expectation is for kfuncs to be treated like > EXPORT_SYMBOL_GPL symbols in the kernel. The goal is for kfuncs to be a > safe and valuable option for maintainers and kfunc developers to extend > the kernel, without tying anyone's hands, or imposing any kind of > restrictions on maintainers in the same way that UAPI changes do. > > In addition to the 'kfunc lifecycle expectations' section, this patch > also adds documentation for a new KF_DEPRECATED kfunc flag which kfunc > authors or maintainers can choose to add to kfuncs if and when they > decide to deprecate them. Note that as described in the patch itself, a > kfunc need not be deprecated before being changed or removed -- this > flag is simply provided as an available deprecation mechanism for those > that want to provide a deprecation story / timeline to their users. > When necessary, kfuncs may be changed or removed to accommodate changes > elsewhere in the kernel without any deprecation at all. > > Reviewed-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx> > Co-developed-by: Toke Høiland-Jørgensen <toke@xxxxxxxxxx> > Signed-off-by: David Vernet <void@xxxxxxxxxxxxx> David, Toke, Thanks a lot for writing it down. It certainly captures the main points. Applied.
