UAPI Checker

UAPI checker와 option

SPDX 라이선스 식별자: GPL-2.0-only

UAPI Checker

UAPI checker(`scripts/check-uapi.sh`)는 Git tree 전체에서 UAPI header file의 user space backward compatibility를 검사하는 shell script입니다.

Option

이 절은 `check-uapi.sh`를 실행할 때 사용할 수 있는 option을 설명합니다.

사용법:

check-uapi.sh [-b BASE_REF] [-p PAST_REF] [-j N] [-l ERROR_LOG] [-i] [-q] [-v]

사용 가능한 option:

-b BASE_REF    Base git reference to use for comparison. If unspecified or empty,
               will use any dirty changes in tree to UAPI files. If there are no
               dirty changes, HEAD will be used.
-p PAST_REF    Compare BASE_REF to PAST_REF (e.g. -p v6.1). If unspecified or empty,
               will use BASE_REF^1. Must be an ancestor of BASE_REF. Only headers
               that exist on PAST_REF will be checked for compatibility.
-j JOBS        Number of checks to run in parallel (default: number of CPU cores).
-l ERROR_LOG   Write error log to file (default: no error log is generated).
-i             Ignore ambiguous changes that may or may not break UAPI compatibility.
-q             Quiet operation.
-v             Verbose operation (print more information about each header being checked).

`-b BASE_REF`는 비교 기준 Git reference를 지정합니다. 비어 있으면 UAPI file의 dirty change를 사용하고, dirty change가 없으면 HEAD를 사용합니다. `-p PAST_REF`는 `BASE_REF`와 비교할 과거 reference를 지정하며 기본값은 `BASE_REF^1`입니다. 이는 `BASE_REF`의 ancestor여야 하고 `PAST_REF`에 존재하는 header만 검사합니다.

`-j JOBS`는 parallel check 수, `-l ERROR_LOG`는 error log file, `-i`는 compatibility 파괴 여부가 모호한 변경 무시, `-q`는 quiet, `-v`는 header별 상세 출력을 지정합니다.

environment argument:

ABIDIFF  Custom path to abidiff binary
CC       C compiler (default is "gcc")
ARCH     Target architecture of C compiler (default is host arch)

`ABIDIFF`는 custom `abidiff` binary path, `CC`는 C compiler(기본 `gcc`), `ARCH`는 compiler의 target architecture(기본 host architecture)를 지정합니다.

exit code:

0) Success
1) ABI difference detected
2) Prerequisite not met

기본 사용과 모호한 ABI 변경

예제

기본 사용

먼저 user space를 확실히 깨뜨리지 않는 변경을 UAPI header file에 적용해 봅니다.

cat << 'EOF' | patch -l -p1
--- a/include/uapi/linux/acct.h
+++ b/include/uapi/linux/acct.h
@@ -21,7 +21,9 @@
 #include <asm/param.h>
 #include <asm/byteorder.h>

-/*
+#define FOO
+
+/*
  *  comp_t is a 16-bit "floating" point number with a 3-bit base 8
  *  exponent and a 13-bit fraction.
  *  comp2_t is 24-bit with 5-bit base 2 exponent and 20 bit fraction
diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
EOF

script로 검증합니다.

% ./scripts/check-uapi.sh
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...
All 912 UAPI headers compatible with x86 appear to be backwards compatible

이번에는 user space를 깨뜨릴 수도 있는 변경을 하나 더 추가합니다.

cat << 'EOF' | patch -l -p1
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -74,7 +74,7 @@ struct bpf_insn {
        __u8    dst_reg:4;      /* dest register */
        __u8    src_reg:4;      /* source register */
        __s16   off;            /* signed offset */
-       __s32   imm;            /* signed immediate constant */
+       __u32   imm;            /* unsigned immediate constant */
 };

 /* Key of an a BPF_MAP_TYPE_LPM_TRIE entry */
EOF

script가 이 변경을 탐지합니다.

% ./scripts/check-uapi.sh
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
      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
==================================================================================

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

signed type을 unsigned type으로 바꾸면 음수를 전달하는 user space program을 깨뜨릴 수 있어 script가 type 변경을 보고합니다. `imm`에 음수가 절대 들어오지 않아 안전하다고 판단한다면 `-i` flag로 backward compatibility가 모호한 변경을 무시할 수 있습니다.

% ./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...
All 912 UAPI headers compatible with x86 appear to be backwards compatible

명확한 파괴와 reference 범위

이번에는 user space를 확실히 깨뜨리는 비슷한 변경을 만듭니다.

cat << 'EOF' | patch -l -p1
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -71,8 +71,8 @@ enum {

 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

기존 struct member 순서를 바꾸는 변경에는 모호함이 없으므로 `-i`를 전달해도 script가 breakage를 보고합니다.

% ./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

파괴적인 변경을 commit한 다음 무해한 변경을 commit합니다.

% 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(-)

argument 없이 script를 다시 실행합니다.

% ./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

기본적으로 HEAD와 `HEAD^1`만 비교하므로 `HEAD~2`에 commit한 파괴적 변경은 잡지 못합니다. 더 이전까지 검색하려면 `-p`로 다른 과거 reference를 전달합니다. 여기서는 `-p HEAD~2`로 `HEAD~2`와 HEAD 사이의 UAPI 변경을 검사합니다.

% ./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

대신 `-b HEAD~`를 사용할 수도 있습니다. 이 경우 base reference가 `HEAD~`가 되고 script는 이를 `HEAD~^1`과 비교합니다.

architecture-specific header

Architecture-specific Header

다음 변경을 생각해 봅니다.

cat << 'EOF' | patch -l -p1
--- a/arch/arm64/include/uapi/asm/sigcontext.h
+++ b/arch/arm64/include/uapi/asm/sigcontext.h
@@ -70,6 +70,7 @@ struct sigcontext {
 struct _aarch64_ctx {
        __u32 magic;
        __u32 size;
+       __u32 new_var;
 };

 #define FPSIMD_MAGIC   0x46508001
EOF

이는 arm64-specific UAPI header 변경입니다. 이 예제는 x86 compiler가 있는 x86 machine에서 실행하므로 기본적으로 x86-compatible UAPI header만 검사합니다.

% ./scripts/check-uapi.sh
Installing user-facing UAPI headers from dirty tree... OK
Installing user-facing UAPI headers from HEAD... OK
No changes to UAPI headers were applied between HEAD and dirty tree

x86 compiler로는 `arch/arm64`의 header를 검사할 수 없어 script가 시도하지도 않습니다. 검사하려면 arm64 compiler를 사용하고 `ARCH`를 맞게 설정해야 합니다.

% CC=aarch64-linux-gnu-gcc ARCH=arm64 ./scripts/check-uapi.sh
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/asm/sigcontext.h from HEAD -> dirty tree ====
    [C] 'struct _aarch64_ctx' changed:
      type size changed from 64 to 96 (in bits)
      1 data member insertion:
        '__u32 new_var', at offset 64 (in bits) at sigcontext.h:73:1
    -- snip --
    [C] 'struct zt_context' changed:
      type size changed from 128 to 160 (in bits)
      2 data member changes (1 filtered):
        '__u16 nregs' offset changed from 64 to 96 (in bits) (by +32 bits)
        '__u16 __reserved[3]' offset changed from 80 to 112 (in bits) (by +32 bits)
=======================================================================================

error - 1/884 UAPI headers compatible with arm64 appear _not_ to be backwards compatible

`ARCH`와 `CC`를 file에 맞게 설정하면 ABI 변경이 올바르게 보고됩니다. arm64 platform에 설치되는 header 수가 x86과 다르므로 검사한 전체 UAPI header 수가 달라지는 점도 확인할 수 있습니다.

cross-dependency breakage

Cross-Dependency Breakage

다음 변경을 생각해 봅니다.

cat << 'EOF' | patch -l -p1
--- a/include/uapi/linux/types.h
+++ b/include/uapi/linux/types.h
@@ -52,7 +52,7 @@ typedef __u32 __bitwise __wsum;
 #define __aligned_be64 __be64 __attribute__((aligned(8)))
 #define __aligned_le64 __le64 __attribute__((aligned(8)))

-typedef unsigned __bitwise __poll_t;
+typedef unsigned short __bitwise __poll_t;

 #endif /*  __ASSEMBLY__ */
 #endif /* _UAPI_LINUX_TYPES_H */
EOF

`types.h`의 `typedef`를 바꾸는 변경은 `types.h` 자체 UAPI를 깨뜨리지는 않지만 tree 안의 다른 UAPI를 깨뜨릴 수 있습니다.

% ./scripts/check-uapi.sh
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/eventpoll.h from HEAD -> dirty tree ====
    [C] 'struct epoll_event' changed:
      type size changed from 96 to 80 (in bits)
      2 data member changes:
        type of '__poll_t events' changed:
          underlying type 'unsigned int' changed:
            type name changed from 'unsigned int' to 'unsigned short int'
            type size changed from 32 to 16 (in bits)
        '__u64 data' offset changed from 32 to 16 (in bits) (by -16 bits)
========================================================================================
include/linux/eventpoll.h did not change between HEAD and dirty tree...
It's possible a change to one of the headers it includes caused this error:
#include <linux/fcntl.h>
#include <linux/types.h>

script는 실패한 header file 자체가 바뀌지 않았음을 알아내고 include한 header 중 하나가 breakage를 일으켰다고 추정합니다. 실제로 `eventpoll.h`가 `linux/types.h`를 사용합니다.

UAPI header 제거

UAPI Header Removal

다음 변경을 생각해 봅니다.

cat << 'EOF' | patch -l -p1
diff --git a/include/uapi/asm-generic/Kbuild b/include/uapi/asm-generic/Kbuild
index ebb180aac74e..a9c88b0a8b3b 100644
--- a/include/uapi/asm-generic/Kbuild
+++ b/include/uapi/asm-generic/Kbuild
@@ -31,6 +31,6 @@ mandatory-y += stat.h
 mandatory-y += statfs.h
 mandatory-y += swab.h
 mandatory-y += termbits.h
-mandatory-y += termios.h
+#mandatory-y += termios.h
 mandatory-y += types.h
 mandatory-y += unistd.h
EOF

이 변경은 install 목록에서 UAPI header file을 제거합니다. script를 실행합니다.

% ./scripts/check-uapi.sh
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...
==== UAPI header include/asm/termios.h was removed between HEAD and dirty tree ====

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

UAPI header 제거는 breaking change로 간주되며 script가 이를 표시합니다.

과거 UAPI compatibility 검사

과거 UAPI Compatibility 검사

`-b`와 `-p` option으로 Git tree의 서로 다른 구간을 조사할 수 있습니다. 예를 들어 v6.0과 v6.1 tag 사이에서 바뀐 모든 UAPI header를 검사하려면 다음과 같이 실행합니다.

% ./scripts/check-uapi.sh -b v6.1 -p v6.0
Installing user-facing UAPI headers from v6.1... OK
Installing user-facing UAPI headers from v6.0... OK
Checking changes to UAPI headers between v6.0 and v6.1...

--- snip ---
error - 37/907 UAPI headers compatible with x86 appear _not_ to be backwards compatible

참고: v5.3 이전에는 script에 필요한 header file이 없으므로 그 이전 변경은 검사할 수 없습니다.

script는 backward compatible하지 않은 UAPI 변경을 많이 탐지합니다. kernel UAPI가 영구히 안정적이어야 한다는 점을 생각하면 놀라운 결과이며, 다음 caveat 절에서 이유를 다룹니다.

caveat와 의도적 제거

Caveat

UAPI checker는 작성자의 의도를 가정하지 않으므로 일부 변경은 의도적으로 UAPI를 깨뜨렸더라도 flag될 수 있습니다.

refactoring 또는 deprecation을 위한 제거

아주 오래된 hardware의 driver를 제거하는 경우가 있습니다. 다음이 그 예입니다.

% ./scripts/check-uapi.sh -b ba47652ba655
Installing user-facing UAPI headers from ba47652ba655... OK
Installing user-facing UAPI headers from ba47652ba655^1... OK
Checking changes to UAPI headers between ba47652ba655^1 and ba47652ba655...
==== UAPI header include/linux/meye.h was removed between ba47652ba655^1 and ba47652ba655 ====

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

script는 의도적인 경우에도 제거를 항상 flag합니다.

struct 확장

Struct Expansion

kernel space에서 structure를 처리하는 방식에 따라 struct를 확장하는 변경이 compatibility를 깨뜨리지 않을 수도 있습니다.

struct를 ioctl argument로 사용한다면 kernel driver는 모든 크기의 ioctl command를 처리할 수 있어야 합니다. user data를 copy할 때도 주의해야 합니다. 예를 들어 `struct foo`를 다음처럼 바꿉니다.

struct foo {
    __u64 a; /* added in version 1 */
+   __u32 b; /* added in version 2 */
+   __u32 c; /* added in version 2 */
}

기본적으로 script는 이 변경을 추가 검토 대상으로 flag합니다.

[C] 'struct foo' changed:
  type size changed from 64 to 128 (in bits)
  2 data member insertions:
    '__u32 b', at offset 64 (in bits)
    '__u32 c', at offset 96 (in bits)

하지만 안전하게 만든 변경일 수 있습니다. version 1로 build한 user space program은 `sizeof(struct foo)`를 8로 알고 그 크기를 kernel에 보내는 ioctl 값에 encode합니다. version 2 kernel은 같은 크기를 16으로 봅니다.

kernel은 `_IOC_SIZE` macro로 user가 전달한 ioctl code에 encode된 크기를 얻고 `copy_struct_from_user()`로 값을 안전하게 copy할 수 있습니다.

int handle_ioctl(unsigned long cmd, unsigned long arg)
{
    switch _IOC_NR(cmd) {
    0x01: {
        struct foo my_cmd;  /* size 16 in the kernel */

        ret = copy_struct_from_user(&my_cmd, arg, sizeof(struct foo), _IOC_SIZE(cmd));
        ...

`copy_struct_from_user`는 kernel의 struct를 0으로 채운 뒤 user가 전달한 byte만 copy해 새 member를 0으로 남깁니다. user가 더 큰 struct를 전달하면 추가 member는 무시합니다. kernel code가 이 상황을 처리한다고 확신한다면 `-i`를 전달해 이런 struct expansion을 무시할 수 있습니다.

flex array migration

Flex Array Migration

script는 기존 flex array 확장을 처리하지만 1-element fake flex array에서 실제 flex array로 처음 migration하는 변경은 여전히 flag합니다. 예:

struct foo {
      __u32 x;
-     __u32 flex[1]; /* fake flex */
+     __u32 flex[];  /* real flex */
};

script는 이 변경을 다음과 같이 flag합니다.

[C] 'struct foo' changed:
  type size changed from 64 to 32 (in bits)
  1 data member change:
    type of '__u32 flex[1]' changed:
      type name changed from '__u32[1]' to '__u32[]'
      array type size changed from 32 to 'unknown'
      array type subrange 1 changed length from 1 to 'unknown'

현재는 이런 변경 type을 filter할 방법이 없으므로 발생 가능한 false positive에 유의해야 합니다.

요약

요약

script가 많은 false positive type을 걸러 내지만 UAPI를 깨뜨리지 않는 변경을 flag하는 경우가 있을 수 있습니다. 반대로 user space를 깨뜨리는 변경을 잡지 못할 수도 있습니다. kernel history 상당 부분에서 실행했지만 아직 처리하지 못한 corner case가 남아 있을 수 있습니다.

이 script는 maintainer 또는 automated tooling을 위한 빠른 검사 수단이지 patch compatibility의 최종 권위가 아닙니다. 최선의 판단과 가능하면 user space unit test를 사용해 UAPI 변경의 backward compatibility를 확인해야 합니다.