On Sat, Feb 18, 2023 at 5:23 AM John Moon <quic_johmoo@xxxxxxxxxxx> wrote: > > + linux-arm-kernel and Greg KH > > Hi all, > > The kernel community has rigorously enforced a policy of backwards > compatibility in its UAPI headers for a long time. This has allowed user > applications to enjoy stability across kernel upgrades without > recompiling. > > In the vendor driver community (out-of-tree modules), there's been a > lack of discipline when it comes to maintaining UAPI backwards > compatibility. This has been a maintenance burden and limits our options > for long-term support of older devices. > > Our goal is to add tooling for vendor driver developers because the > upstream model of expert maintainer code review can be difficult to > replicate in-house. Tools may help developers catch simple UAPI > incompatibilities that could be easily overlooked by in-house review. > > We see in the kernel documentation: > "Kernel headers are backwards compatible, but not forwards compatible. > This means that a program built against a C library using older kernel > headers should run on a newer kernel (although it may not have access > to new features), but a program built against newer kernel headers may > not work on an older kernel."[1] > > How does the kernel enforce this guarantee? We would be interested to > learn about any tools or methods used by kernel developers to make sure > the above statement remains true. > > Could the documentation on UAPI maintenance (from a developer's point of > view) be expanded? Internally, we have a set of guidelines for our kernel > developers regarding UAPI compatibility techniques. If there's interest > in supplying a document on this topic with the kernel, we'd be happy to > submit a draft detailing what we have so far as a jumping off point. > > Additionally, I've attached a shell script we've been using internally > to validate changes to our UAPI headers are backwards compatible. The > script uses libabigail's[2] tool abidiff[3] to compare a modified > header's ABI before and after a patch is applied. If an existing UAPI is > modified, the script exits non-zero. We use this script in our CI system > to block changes that fail the check. > > Currently, the script works with gcc. It generates output like this when > a backwards-incompatible change is made to a UAPI header: > > !!! ABI differences detected in include/uapi/linux/acct.h (compared to > file at HEAD^1) !!! > > [C] 'struct acct' changed: > type size changed from 512 to 544 (in bits) > 1 data member insertion: > '__u32 new_val', at offset 512 (in bits) at acct.h:71:1 > > 0/1 UAPI header file changes are backwards compatible > UAPI header ABI check failed > > However, we have not had success with clang. It seems clang is more > aggressive in optimizing dead code away (no matter which options we > pass). Therefore, no ABI differences are found. > > We wanted to share with the community to receive feedback and any advice > when it comes to tooling/policy surrounding this issue. Our hope is that > the script will help all kernel UAPI authors (even those that haven't > upstreamed yet) maintain good discipline and avoid breaking userspace. > > [1] Documentation/kbuild/headers_install.rst > [2] https://sourceware.org/libabigail/manual/libabigail-overview.html > [3] https://sourceware.org/libabigail/manual/abidiff.html > > P.S. While at Qualcomm, Jordan Crouse <jorcrous@xxxxxxxxxx> authored the > original version of the UAPI checker script. Thanks Jordan! If you want to express the authorship of the original, it is possible to add the "Co-developed-by" tag, which is mentioned in Documentation/translations/sp_SP/process/submitting-patches.rst It depends on how much code you rewrote, though. > > John Moon (1): > check-uapi: Introduce check-uapi.sh > > scripts/check-uapi.sh | 245 ++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 245 insertions(+) > create mode 100755 scripts/check-uapi.sh > > > base-commit: 033c40a89f55525139fd5b6342281b09b97d05bf > -- > 2.17.1 > -- Best Regards Masahiro Yamada
