From: John Moon <quic_johmoo@quicinc.com> To: Masahiro Yamada <masahiroy@kernel.org>, Nathan Chancellor <nathan@kernel.org>, Nick Desaulniers <ndesaulniers@google.com>, "Nicolas Schier" <nicolas@fjasle.eu> Cc: John Moon <quic_johmoo@quicinc.com>, <linux-kbuild@vger.kernel.org>, <linux-kernel@vger.kernel.org>, <linux-arm-kernel@lists.infradead.org>, <linux-arm-msm@vger.kernel.org>, Greg Kroah-Hartman <gregkh@linuxfoundation.org>, Randy Dunlap <rdunlap@infradead.org>, "Arnd Bergmann" <arnd@arndb.de>, Bjorn Andersson <andersson@kernel.org>, Todd Kjos <tkjos@google.com>, Matthias Maennich <maennich@google.com>, Giuliano Procida <gprocida@google.com>, <kernel-team@android.com>, <libabigail@sourceware.org>, Jordan Crouse <jorcrous@amazon.com>, Trilok Soni <quic_tsoni@quicinc.com>, Satya Durga Srinivasu Prabhala <quic_satyap@quicinc.com>, Elliot Berman <quic_eberman@quicinc.com>, "Guru Das Srinagesh" <quic_gurus@quicinc.com> Subject: [PATCH v4 0/2] Validating UAPI backwards compatibility Date: Mon, 27 Mar 2023 10:41:38 -0700 [thread overview] Message-ID: <20230327174140.8169-1-quic_johmoo@quicinc.com> (raw) 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. Our goal is to add tooling and documentation to help kernel developers maintain this stability. 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 community enforce this guarantee? As we understand it, it's enforced with thorough code review and testing. Is there any tooling outside of this being used to help the process? Also, could 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. In terms of tooling, I've attached a shell script we've been using internally to validate backwards compatibility of our UAPI headers. 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 continuous integration system to block changes that fail the check. It generates output like this when a backwards-incompatible change is made to a UAPI header: !!! ABI differences detected in include/uapi/linux/bpf.h from HEAD~1 -> HEAD !!! [C] 'struct bpf_insn' changed: type size hasn't changed 1 data member change: type of '__s32 imm' changed: typedef name changed from __s32 to __u32 at int-ll64.h:27:1 underlying type 'int' changed: type name changed from 'int' to 'unsigned int' type size hasn't changed We wanted to share this script with the community and hopefully also receive general feedback when it comes to tooling/policy surrounding this issue. Our hope is that the script will help kernel UAPI authors maintain good discipline and avoid breaking userspace. In v4, we've updated the script to operate exclusively on the trees generated by "make headers_install" at the two git references. This catches several classes of false negatives brought up in earlier revisions. Thanks for the helpful reviews of previous revs! We're looking forward to any additional feedback you may have on v4. [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@amazon.com> authored the original version of the UAPI checker script. Thanks Jordan!<Paste> John Moon (2): check-uapi: Introduce check-uapi.sh docs: dev-tools: Add UAPI checker documentation Documentation/dev-tools/checkuapi.rst | 479 +++++++++++++++++++++++++ Documentation/dev-tools/index.rst | 1 + scripts/check-uapi.sh | 490 ++++++++++++++++++++++++++ 3 files changed, 970 insertions(+) create mode 100644 Documentation/dev-tools/checkuapi.rst create mode 100755 scripts/check-uapi.sh base-commit: e76db6e50c85cce9e68c47076f8eab06189fe4db -- 2.17.1
WARNING: multiple messages have this Message-ID (diff)
From: John Moon <quic_johmoo@quicinc.com> To: Masahiro Yamada <masahiroy@kernel.org>, Nathan Chancellor <nathan@kernel.org>, Nick Desaulniers <ndesaulniers@google.com>, "Nicolas Schier" <nicolas@fjasle.eu> Cc: John Moon <quic_johmoo@quicinc.com>, <linux-kbuild@vger.kernel.org>, <linux-kernel@vger.kernel.org>, <linux-arm-kernel@lists.infradead.org>, <linux-arm-msm@vger.kernel.org>, Greg Kroah-Hartman <gregkh@linuxfoundation.org>, Randy Dunlap <rdunlap@infradead.org>, "Arnd Bergmann" <arnd@arndb.de>, Bjorn Andersson <andersson@kernel.org>, Todd Kjos <tkjos@google.com>, Matthias Maennich <maennich@google.com>, Giuliano Procida <gprocida@google.com>, <kernel-team@android.com>, <libabigail@sourceware.org>, Jordan Crouse <jorcrous@amazon.com>, Trilok Soni <quic_tsoni@quicinc.com>, Satya Durga Srinivasu Prabhala <quic_satyap@quicinc.com>, Elliot Berman <quic_eberman@quicinc.com>, "Guru Das Srinagesh" <quic_gurus@quicinc.com> Subject: [PATCH v4 0/2] Validating UAPI backwards compatibility Date: Mon, 27 Mar 2023 10:41:38 -0700 [thread overview] Message-ID: <20230327174140.8169-1-quic_johmoo@quicinc.com> (raw) 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. Our goal is to add tooling and documentation to help kernel developers maintain this stability. 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 community enforce this guarantee? As we understand it, it's enforced with thorough code review and testing. Is there any tooling outside of this being used to help the process? Also, could 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. In terms of tooling, I've attached a shell script we've been using internally to validate backwards compatibility of our UAPI headers. 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 continuous integration system to block changes that fail the check. It generates output like this when a backwards-incompatible change is made to a UAPI header: !!! ABI differences detected in include/uapi/linux/bpf.h from HEAD~1 -> HEAD !!! [C] 'struct bpf_insn' changed: type size hasn't changed 1 data member change: type of '__s32 imm' changed: typedef name changed from __s32 to __u32 at int-ll64.h:27:1 underlying type 'int' changed: type name changed from 'int' to 'unsigned int' type size hasn't changed We wanted to share this script with the community and hopefully also receive general feedback when it comes to tooling/policy surrounding this issue. Our hope is that the script will help kernel UAPI authors maintain good discipline and avoid breaking userspace. In v4, we've updated the script to operate exclusively on the trees generated by "make headers_install" at the two git references. This catches several classes of false negatives brought up in earlier revisions. Thanks for the helpful reviews of previous revs! We're looking forward to any additional feedback you may have on v4. [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@amazon.com> authored the original version of the UAPI checker script. Thanks Jordan!<Paste> John Moon (2): check-uapi: Introduce check-uapi.sh docs: dev-tools: Add UAPI checker documentation Documentation/dev-tools/checkuapi.rst | 479 +++++++++++++++++++++++++ Documentation/dev-tools/index.rst | 1 + scripts/check-uapi.sh | 490 ++++++++++++++++++++++++++ 3 files changed, 970 insertions(+) create mode 100644 Documentation/dev-tools/checkuapi.rst create mode 100755 scripts/check-uapi.sh base-commit: e76db6e50c85cce9e68c47076f8eab06189fe4db -- 2.17.1 _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
next reply other threads:[~2023-03-27 17:42 UTC|newest] Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top 2023-03-27 17:41 John Moon [this message] 2023-03-27 17:41 ` [PATCH v4 0/2] Validating UAPI backwards compatibility John Moon 2023-03-27 17:41 ` [PATCH v4 1/2] check-uapi: Introduce check-uapi.sh John Moon 2023-03-27 17:41 ` John Moon 2023-04-03 19:53 ` John Moon 2023-04-03 19:53 ` John Moon 2023-04-07 19:19 ` Masahiro Yamada 2023-04-07 19:19 ` Masahiro Yamada 2023-04-07 20:08 ` John Moon 2023-04-07 20:08 ` John Moon 2023-04-07 19:27 ` Masahiro Yamada 2023-04-07 19:27 ` Masahiro Yamada 2023-04-07 20:09 ` John Moon 2023-04-07 20:09 ` John Moon 2023-03-27 17:41 ` [PATCH v4 2/2] docs: dev-tools: Add UAPI checker documentation John Moon 2023-03-27 17:41 ` John Moon 2023-03-28 18:10 ` Nick Desaulniers 2023-03-28 18:10 ` Nick Desaulniers
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20230327174140.8169-1-quic_johmoo@quicinc.com \ --to=quic_johmoo@quicinc.com \ --cc=andersson@kernel.org \ --cc=arnd@arndb.de \ --cc=gprocida@google.com \ --cc=gregkh@linuxfoundation.org \ --cc=jorcrous@amazon.com \ --cc=kernel-team@android.com \ --cc=libabigail@sourceware.org \ --cc=linux-arm-kernel@lists.infradead.org \ --cc=linux-arm-msm@vger.kernel.org \ --cc=linux-kbuild@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=maennich@google.com \ --cc=masahiroy@kernel.org \ --cc=nathan@kernel.org \ --cc=ndesaulniers@google.com \ --cc=nicolas@fjasle.eu \ --cc=quic_eberman@quicinc.com \ --cc=quic_gurus@quicinc.com \ --cc=quic_satyap@quicinc.com \ --cc=quic_tsoni@quicinc.com \ --cc=rdunlap@infradead.org \ --cc=tkjos@google.com \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.