Lines Matching +full:t +full:- +full:head
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,
25 dirty changes, HEAD will be used.
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 -----------
54 won't break userspace::
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 ====
105 type size hasn't changed
108 typedef name changed from __s32 to __u32 at int-ll64.h:27:1
111 type size hasn't changed
114 error - 1/912 UAPI headers compatible with x86 appear _not_ to be backwards compatible
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
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 ====
155 type size hasn't changed
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
166 [detached HEAD f758e574663a] Breaking UAPI change
167 1 file changed, 1 insertion(+), 1 deletion(-)
168 % git commit -m 'Innocuous UAPI change' include/uapi/linux/acct.h
169 [detached HEAD 2e87df769081] Innocuous UAPI change
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...
180 It doesn't catch any breaking change because, by default, it only
181 compares ``HEAD`` to ``HEAD^1``. The breaking change was committed on
182 ``HEAD~2``. If we wanted the search scope to go back further, we'd have to
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
185 ``HEAD~2`` and ``HEAD``::
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 ====
193 type size hasn't changed
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
202 base reference to ``HEAD~`` so then the script would compare it to ``HEAD~^1``.
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
232 script doesn't even try.
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 ====
246 -- snip --
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
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 ====
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
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
353 --- snip ---
354 error - 37/907 UAPI headers compatible with x86 appear _not_ to be backwards compatible
371 ---------------------------------------
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
381 error - 1/910 UAPI headers compatible with x86 appear _not_ to be backwards compatible
386 -----------------
389 expands a struct could be non-breaking.
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 */
464 -------
474 maintainers or automated tooling, not as the end-all authority on
477 are backwards-compatible!