Lines Matching +full:in +full:- +full:between
1 .. SPDX-License-Identifier: GPL-2.0-only
7 The UAPI checker (``scripts/check-uapi.sh``) is a shell script which
8 checks UAPI header files for userspace backwards-compatibility across
14 This section will describe the options with which ``check-uapi.sh``
19 check-uapi.sh [-b BASE_REF] [-p PAST_REF] [-j N] [-l ERROR_LOG] [-i] [-q] [-v]
23 -b BASE_REF Base git reference to use for comparison. If unspecified or empty,
24 will use any dirty changes in tree to UAPI files. If there are no
26 -p PAST_REF Compare BASE_REF to PAST_REF (e.g. -p v6.1). If unspecified or empty,
29 -j JOBS Number of checks to run in parallel (default: number of CPU cores).
30 -l ERROR_LOG Write error log to file (default: no error log is generated).
31 -i Ignore ambiguous changes that may or may not break UAPI compatibility.
32 -q Quiet operation.
33 -v Verbose operation (print more information about each header being checked).
51 -----------
56 cat << 'EOF' | patch -l -p1
57 --- a/include/uapi/linux/acct.h
59 @@ -21,7 +21,9 @@
63 -/*
67 * comp_t is a 16-bit "floating" point number with a 3-bit base 8
68 * exponent and a 13-bit fraction.
69 * comp2_t is 24-bit with 5-bit base 2 exponent and 20 bit fraction
70 diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
75 % ./scripts/check-uapi.sh
76 Installing user-facing UAPI headers from dirty tree... OK
77 Installing user-facing UAPI headers from HEAD... OK
78 Checking changes to UAPI headers between HEAD and dirty tree...
83 cat << 'EOF' | patch -l -p1
84 --- a/include/uapi/linux/bpf.h
86 @@ -74,7 +74,7 @@ struct bpf_insn {
90 - __s32 imm; /* signed immediate constant */
99 % ./scripts/check-uapi.sh
100 Installing user-facing UAPI headers from dirty tree... OK
101 Installing user-facing UAPI headers from HEAD... OK
102 Checking changes to UAPI headers between HEAD and dirty tree...
103 ==== ABI differences detected in include/linux/bpf.h from HEAD -> dirty tree ====
108 typedef name changed from __s32 to __u32 at int-ll64.h:27:1
114 error - 1/912 UAPI headers compatible with x86 appear _not_ to be backwards compatible
116 In this case, the script is reporting the type change because it could
117 break a userspace program that passes in a negative number. Now, let's
119 value in ``imm``, so changing to an unsigned type there shouldn't hurt
120 anything. You can pass the ``-i`` flag to the script to ignore changes
121 in which the userspace backwards compatibility is ambiguous::
123 % ./scripts/check-uapi.sh -i
124 Installing user-facing UAPI headers from dirty tree... OK
125 Installing user-facing UAPI headers from HEAD... OK
126 Checking changes to UAPI headers between HEAD and dirty tree...
131 cat << 'EOF' | patch -l -p1
132 --- a/include/uapi/linux/bpf.h
134 @@ -71,8 +71,8 @@ enum {
138 - __u8 dst_reg:4; /* dest register */
146 Since we're re-ordering an existing struct member, there's no ambiguity,
147 and the script will report the breakage even if you pass ``-i``::
149 % ./scripts/check-uapi.sh -i
150 Installing user-facing UAPI headers from dirty tree... OK
151 Installing user-facing UAPI headers from HEAD... OK
152 Checking changes to UAPI headers between HEAD and dirty tree...
153 ==== ABI differences detected in include/linux/bpf.h from HEAD -> dirty tree ====
157 '__u8 dst_reg' offset changed from 8 to 12 (in bits) (by +4 bits)
158 '__u8 src_reg' offset changed from 12 to 8 (in bits) (by -4 bits)
161 error - 1/912 UAPI headers compatible with x86 appear _not_ to be backwards compatible
165 % git commit -m 'Breaking UAPI change' include/uapi/linux/bpf.h
167 1 file changed, 1 insertion(+), 1 deletion(-)
168 % git commit -m 'Innocuous UAPI change' include/uapi/linux/acct.h
170 1 file changed, 3 insertions(+), 1 deletion(-)
174 % ./scripts/check-uapi.sh
175 Installing user-facing UAPI headers from HEAD... OK
176 Installing user-facing UAPI headers from HEAD^1... OK
177 Checking changes to UAPI headers between HEAD^1 and HEAD...
183 use the ``-p`` option to pass a different past reference. In this case,
184 let's pass ``-p HEAD~2`` to the script so it checks UAPI changes between
187 % ./scripts/check-uapi.sh -p HEAD~2
188 Installing user-facing UAPI headers from HEAD... OK
189 Installing user-facing UAPI headers from HEAD~2... OK
190 Checking changes to UAPI headers between HEAD~2 and HEAD...
191 ==== ABI differences detected in include/linux/bpf.h from HEAD~2 -> HEAD ====
195 '__u8 dst_reg' offset changed from 8 to 12 (in bits) (by +4 bits)
196 '__u8 src_reg' offset changed from 12 to 8 (in bits) (by -4 bits)
199 error - 1/912 UAPI headers compatible with x86 appear _not_ to be backwards compatible
201 Alternatively, we could have also run with ``-b HEAD~``. This would set the
204 Architecture-specific Headers
205 -----------------------------
209 cat << 'EOF' | patch -l -p1
210 --- a/arch/arm64/include/uapi/asm/sigcontext.h
212 @@ -70,6 +70,7 @@ struct sigcontext {
222 This is a change to an arm64-specific UAPI header file. In this example, I'm
224 the script only checks x86-compatible UAPI header files::
226 % ./scripts/check-uapi.sh
227 Installing user-facing UAPI headers from dirty tree... OK
228 Installing user-facing UAPI headers from HEAD... OK
229 No changes to UAPI headers were applied between HEAD and dirty tree
231 With an x86 compiler, we can't check header files in ``arch/arm64``, so the
237 % CC=aarch64-linux-gnu-gcc ARCH=arm64 ./scripts/check-uapi.sh
238 Installing user-facing UAPI headers from dirty tree... OK
239 Installing user-facing UAPI headers from HEAD... OK
240 Checking changes to UAPI headers between HEAD and dirty tree...
241 ==== ABI differences detected in include/asm/sigcontext.h from HEAD -> dirty tree ====
243 type size changed from 64 to 96 (in bits)
245 '__u32 new_var', at offset 64 (in bits) at sigcontext.h:73:1
246 -- snip --
248 type size changed from 128 to 160 (in bits)
250 '__u16 nregs' offset changed from 64 to 96 (in bits) (by +32 bits)
251 '__u16 __reserved[3]' offset changed from 80 to 112 (in bits) (by +32 bits)
254 error - 1/884 UAPI headers compatible with arm64 appear _not_ to be backwards compatible
261 Cross-Dependency Breakages
262 --------------------------
266 cat << 'EOF' | patch -l -p1
267 --- a/include/uapi/linux/types.h
269 @@ -52,7 +52,7 @@ typedef __u32 __bitwise __wsum;
273 -typedef unsigned __bitwise __poll_t;
280 Here, we're changing a ``typedef`` in ``types.h``. This doesn't break
281 a UAPI in ``types.h``, but other UAPIs in the tree may break due to
284 % ./scripts/check-uapi.sh
285 Installing user-facing UAPI headers from dirty tree... OK
286 Installing user-facing UAPI headers from HEAD... OK
287 Checking changes to UAPI headers between HEAD and dirty tree...
288 ==== ABI differences detected in include/linux/eventpoll.h from HEAD -> dirty tree ====
290 type size changed from 96 to 80 (in bits)
295 type size changed from 32 to 16 (in bits)
296 '__u64 data' offset changed from 32 to 16 (in bits) (by -16 bits)
298 include/linux/eventpoll.h did not change between HEAD and dirty tree...
308 --------------------
312 cat << 'EOF' | patch -l -p1
313 diff --git a/include/uapi/asm-generic/Kbuild b/include/uapi/asm-generic/Kbuild
315 --- a/include/uapi/asm-generic/Kbuild
316 +++ b/include/uapi/asm-generic/Kbuild
317 @@ -31,6 +31,6 @@ mandatory-y += stat.h
318 mandatory-y += statfs.h
319 mandatory-y += swab.h
320 mandatory-y += termbits.h
321 -mandatory-y += termios.h
322 +#mandatory-y += termios.h
323 mandatory-y += types.h
324 mandatory-y += unistd.h
330 % ./scripts/check-uapi.sh
331 Installing user-facing UAPI headers from dirty tree... OK
332 Installing user-facing UAPI headers from HEAD... OK
333 Checking changes to UAPI headers between HEAD and dirty tree...
334 ==== UAPI header include/asm/termios.h was removed between HEAD and dirty tree ====
336 error - 1/912 UAPI headers compatible with x86 appear _not_ to be backwards compatible
342 ------------------------------------
344 You can use the ``-b`` and ``-p`` options to examine different chunks of your
345 git tree. For example, to check all changed UAPI header files between tags
348 % ./scripts/check-uapi.sh -b v6.1 -p v6.0
349 Installing user-facing UAPI headers from v6.1... OK
350 Installing user-facing UAPI headers from v6.0... OK
351 Checking changes to UAPI headers between v6.0 and v6.1...
353 --- snip ---
354 error - 37/907 UAPI headers compatible with x86 appear _not_ to be backwards compatible
371 ---------------------------------------
373 Sometimes drivers for very old hardware are removed, such as in this example::
375 % ./scripts/check-uapi.sh -b ba47652ba655
376 Installing user-facing UAPI headers from ba47652ba655... OK
377 Installing user-facing UAPI headers from ba47652ba655^1... OK
378 Checking changes to UAPI headers between ba47652ba655^1 and ba47652ba655...
379 ==== UAPI header include/linux/meye.h was removed between ba47652ba655^1 and ba47652ba655 ====
381 error - 1/910 UAPI headers compatible with x86 appear _not_ to be backwards compatible
386 -----------------
388 Depending on how a structure is handled in kernelspace, a change which
389 expands a struct could be non-breaking.
397 __u64 a; /* added in version 1 */
398 + __u32 b; /* added in version 2 */
399 + __u32 c; /* added in version 2 */
405 type size changed from 64 to 128 (in bits)
407 '__u32 b', at offset 64 (in bits)
408 '__u32 c', at offset 96 (in bits)
413 ``sizeof(struct foo)`` is 8. That size will be encoded in the
418 in the ioctl code that the user passed in and then use
425 struct foo my_cmd; /* size 16 in the kernel */
430 ``copy_struct_from_user`` will zero the struct in the kernel and then copy
431 only the bytes passed in from the user (leaving new members zeroized).
432 If the user passed in a larger struct, the extra members are ignored.
434 If you know this situation is accounted for in the kernel code, you can
435 pass ``-i`` to the script, and struct expansions like this will be ignored.
438 --------------------
441 still flag initial migration to flex arrays from 1-element fake flex
446 - __u32 flex[1]; /* fake flex */
453 type size changed from 64 to 32 (in bits)
464 -------
474 maintainers or automated tooling, not as the end-all authority on
476 (and ideally a unit test in userspace) to make sure your UAPI changes
477 are backwards-compatible!