Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.32 as permitted sender) client-ip=23.128.96.32;
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>,
        Jonathan Corbet <corbet@lwn.net>
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>, <kernel@quicinc.com>,
        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>,
        Dodji Seketeli <dodji@redhat.com>,
        Trilok Soni <quic_tsoni@quicinc.com>,
        Satya Durga Srinivasu Prabhala <quic_satyap@quicinc.com>,
        Jordan Crouse <jorcrous@amazon.com>
Subject: [PATCH v6 0/3] Validating UAPI backwards compatibility
Date:   Fri, 27 Oct 2023 12:30:13 -0700
Message-ID: <20231027193016.27516-1-quic_johmoo@quicinc.com>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

The kernel community has rigorously enforced a policy of backwards
compatibility in its userspace interfaces 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.

In terms of tooling, I've attached a couple of shell scripts we've been
internally to validate backwards compatibility of our UAPI headers.

The check-uapi.sh script uses libabigail's[1] tool abidiff[2] to compare a
modified header's ABI before and after a patch is applied. If an existing
UAPI is modified in a way that's not backwards compatibile, 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
      2 data member changes:
        '__u8 dst_reg' offset changed from 8 to 12 (in bits) (by +4 bits)
        '__u8 src_reg' offset changed from 12 to 8 (in bits) (by -4 bits)

The check-module-params.sh script is quite a bit simpler. It basically
greps for module_param.* calls and compares their arguments before/after
a change is applied.

We wanted to share these scripts with the community and hopefully also
receive general feedback when it comes to tooling/policy surrounding
UAPI stability.

In the previous version of this patchset, we received feedback that there
were too many false positives flagged by the check-uapi.sh script. To
improve the situation, we've been working with Dodji Seketeli from
the libabigail team to add additional suppressions which filter out
many of the flags which were raised before. To take advantage of these
suppressions, we've raised the minimum abidiff version requirement to
2.4 which was recently released[3].

Big thanks to Dodji and the libabigail team for working on this use case
with us!

Previous discussion on v5 of this patch can be found here[4].

[1] https://sourceware.org/libabigail/manual/libabigail-overview.html
[2] https://sourceware.org/libabigail/manual/abidiff.html
[3] http://mirrors.kernel.org/sourceware/libabigail/libabigail-2.4.tar.xz
[4] https://lore.kernel.org/lkml/20230407203456.27141-1-quic_johmoo@quicinc.com/

P.S. While at Qualcomm, Jordan Crouse <jorcrous@amazon.com> authored the
original version of the UAPI checker script. Thanks Jordan!

John Moon (3):
  check-uapi: Introduce check-uapi.sh
  docs: dev-tools: Add UAPI checker documentation
  check-module-params: Introduce check-module-params.sh

 Documentation/dev-tools/checkuapi.rst | 477 +++++++++++++++++++++
 Documentation/dev-tools/index.rst     |   1 +
 scripts/check-module-params.sh        | 295 +++++++++++++
 scripts/check-uapi.sh                 | 585 ++++++++++++++++++++++++++
 4 files changed, 1358 insertions(+)
 create mode 100644 Documentation/dev-tools/checkuapi.rst
 create mode 100755 scripts/check-module-params.sh
 create mode 100755 scripts/check-uapi.sh


base-commit: fe1998aa935b44ef873193c0772c43bce74f17dc
--
2.17.1