Documentation/dev-tools/checkuapi.rst

Source file repositories/reference/linux-study-clean/Documentation/dev-tools/checkuapi.rst

File Facts

System
Linux kernel
Corpus path
Documentation/dev-tools/checkuapi.rst
Extension
.rst
Size
18983 bytes
Lines
478
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct bpf_insn {
            __u8    code;           /* opcode */
    -       __u8    dst_reg:4;      /* dest register */
            __u8    src_reg:4;      /* source register */
    +       __u8    dst_reg:4;      /* dest register */
            __s16   off;            /* signed offset */
            __s32   imm;            /* signed immediate constant */
     };
    EOF

Since we're re-ordering an existing struct member, there's no ambiguity,
and the script will report the breakage even if you pass ``-i``::

    % ./scripts/check-uapi.sh -i
    Installing user-facing UAPI headers from dirty tree... OK
    Installing user-facing UAPI headers from HEAD... OK
    Checking changes to UAPI headers between HEAD and dirty tree...
    ==== ABI differences detected in include/linux/bpf.h from HEAD -> dirty tree ====
        [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)
    ==================================================================================

    error - 1/912 UAPI headers compatible with x86 appear _not_ to be backwards compatible

Let's commit the breaking change, then commit the innocuous change::

    % git commit -m 'Breaking UAPI change' include/uapi/linux/bpf.h
    [detached HEAD f758e574663a] Breaking UAPI change
     1 file changed, 1 insertion(+), 1 deletion(-)
    % git commit -m 'Innocuous UAPI change' include/uapi/linux/acct.h
    [detached HEAD 2e87df769081] Innocuous UAPI change
     1 file changed, 3 insertions(+), 1 deletion(-)

Now, let's run the script again with no arguments::

    % ./scripts/check-uapi.sh
    Installing user-facing UAPI headers from HEAD... OK
    Installing user-facing UAPI headers from HEAD^1... OK
    Checking changes to UAPI headers between HEAD^1 and HEAD...
    All 912 UAPI headers compatible with x86 appear to be backwards compatible

It doesn't catch any breaking change because, by default, it only
compares ``HEAD`` to ``HEAD^1``. The breaking change was committed on
``HEAD~2``. If we wanted the search scope to go back further, we'd have to
use the ``-p`` option to pass a different past reference. In this case,
let's pass ``-p HEAD~2`` to the script so it checks UAPI changes between
``HEAD~2`` and ``HEAD``::

    % ./scripts/check-uapi.sh -p HEAD~2
    Installing user-facing UAPI headers from HEAD... OK
    Installing user-facing UAPI headers from HEAD~2... OK
    Checking changes to UAPI headers between HEAD~2 and HEAD...
    ==== ABI differences detected in include/linux/bpf.h from HEAD~2 -> 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)
    ==============================================================================

    error - 1/912 UAPI headers compatible with x86 appear _not_ to be backwards compatible

Alternatively, we could have also run with ``-b HEAD~``. This would set the
base reference to ``HEAD~`` so then the script would compare it to ``HEAD~^1``.

Architecture-specific Headers
-----------------------------

Annotation

Implementation Notes