archive mirror
 help / color / mirror / Atom feed
From: John Moon <>
To: Masahiro Yamada <>,
	Nathan Chancellor <>,
	Nick Desaulniers <>,
	"Nicolas Schier" <>
Cc: John Moon <>,
	<>, <>,
	Greg Kroah-Hartman <>,
	Randy Dunlap <>,
	"Arnd Bergmann" <>,
	Bjorn Andersson <>,
	Todd Kjos <>,
	Matthias Maennich <>,
	Giuliano Procida <>, <>,
	<>, Jordan Crouse <>,
	Trilok Soni <>,
	Satya Durga Srinivasu Prabhala <>,
	Elliot Berman <>,
	"Guru Das Srinagesh" <>
Subject: [PATCH v5 0/2] Validating UAPI backwards compatibility
Date: Fri, 7 Apr 2023 13:34:54 -0700	[thread overview]
Message-ID: <> (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

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 v5, we've made a few code quality improvements based on review
feedback. Thanks!

[1] Documentation/kbuild/headers_install.rst

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

John Moon (2):
  check-uapi: Introduce
  docs: dev-tools: Add UAPI checker documentation

 Documentation/dev-tools/checkuapi.rst | 480 +++++++++++++++++++++++++
 Documentation/dev-tools/index.rst     |   1 +
 scripts/                 | 489 ++++++++++++++++++++++++++
 3 files changed, 970 insertions(+)
 create mode 100644 Documentation/dev-tools/checkuapi.rst
 create mode 100755 scripts/

base-commit: f2afccfefe7be1f7346564fe619277110d341f9b

             reply	other threads:[~2023-04-07 20:36 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-04-07 20:34 John Moon [this message]
2023-04-07 20:34 ` [PATCH v5 1/2] check-uapi: Introduce John Moon
2023-04-10 10:03   ` Masahiro Yamada
2023-04-10 18:45     ` Greg Kroah-Hartman
2023-04-10 23:32       ` John Moon
2023-04-11  6:34         ` Greg Kroah-Hartman
2023-04-11 18:36           ` John Moon
2023-04-12  6:14             ` Greg Kroah-Hartman
2023-04-12 16:37               ` John Moon
2023-04-12 16:43                 ` Greg Kroah-Hartman
2023-04-13 17:07                   ` John Moon
2023-04-13 18:22                     ` Greg Kroah-Hartman
2023-04-13 14:37                 ` Mark Wielaard
2023-04-13 17:12                   ` Giuliano Procida
2023-04-13 17:15                   ` John Moon
2023-04-13 17:03     ` Nicolas Schier
2023-04-13 17:33       ` John Moon
2023-07-20 16:10   ` [PATCH] scripts/ add stgdiff support Giuliano Procida
2023-07-22 19:40     ` Trilok Soni
2023-04-07 20:34 ` [PATCH v5 2/2] docs: dev-tools: Add UAPI checker documentation John Moon

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:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).