Something went wrong. Try again.
(I'm so sorry!) Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
11 kB · 266 lines
at master
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267.. SPDX-License-Identifier: GPL-2.0
=====================================Writing a test for objtool's klp code=====================================
Instructions for adding a test to tools/objtool/tests/. Readklp-test-design.txt first if you need to know how the harness works; thisdocument is the procedure and the rules.
Two kinds of request bring you here:
* *"write a test for commit <sha>"* -- a fix went in without one.* *"port the test at <location>, written against another harness"* -- a case exists elsewhere and should live in tree.
Both follow the same procedure.
The one rule that matters=========================
**A test is not finished until you have watched it fail.**
Break the thing it guards -- revert the fix, or sabotage the exact line -- andconfirm the test fails. Then restore and confirm it passes. A test that hasnever failed is not known to test anything, and this suite has producedseveral that passed against deliberately broken code:
* an alternatives fixture whose empty entry pointed at its own end label rather than the neighbour's replacement, so the bug it guarded made no difference;* a sympos fixture where symbol-table order and address order agreed, so counting and reading the linked image gave the same answer;* a string fixture using a named ``char[]``, which never reached the contents-hashing path because that keys on ``SHF_STRINGS``;* a static array the compiler proved constant, folded to zero, and emitted no relocation for -- so the two builds were byte-identical.
Every one looked correct. Say in the commit message how you verified, and ifyou could not isolate the behaviour to a single line, **say that too** ratherthan implying otherwise.
Procedure=========
1. **Read the fix.** What input reaches the broken line? What is observable in the output object when it misbehaves -- a missing section, a relocation naming the wrong symbol, an unchanged checksum, a rejected build? If nothing is observable, stop and say so; see `When to give up`_.
2. **Decide where it lives.** ``generic/`` unless the fixture needs architecture-specific assembly or the behaviour is architecture-specific, in which case ``x86/`` (or a new directory named for the architecture).
3. **Write the fixture** in the same directory's ``fixtures/``. Reuse an existing one if it already produces the shape; add a ``-D`` knob rather than copying a fixture to change one line.
4. **Write the test.** Assert the *premise* before the result -- see `State the premise`_.
5. **Verify by breaking the code.** Then restore.
6. **Run the whole suite under both compilers**::
make -C tools/objtool tests CC=clang make -C tools/objtool tests
7. **Commit** the test and its fixture together, alone. One test per commit.
Writing the fixture===================
Fixtures are freestanding C. No kernel headers -- write out the kernelstructure by hand if you need one, as the existing special-section fixtures do.
Every fixture needs a ``.modinfo`` name, because klp diff reads the object'smodule name from it::
static const char __modinfo[] __attribute__((section(".modinfo"), used, aligned(1))) = "\0name=vmlinux";
Use ``MODNAME`` if the test needs to vary it. Note that most fixtures hardcode``vmlinux``: passing ``-DMODNAME`` to one that does silently does nothing andthe test quietly becomes a vmlinux test.
The patched build is selected with ``-DPATCHED``. For a fixture with severalvariants, gate each on both, so the original is always the baseline::
#if defined(PATCHED) && defined(WHICH_CALL) r = callee_b(x); #else r = callee_a(x); #endif
and select one per build: ``build_pair foo.c -DWHICH_CALL``. Without the``defined(PATCHED)`` the flag applies to *both* builds and nothing differs.
Traps that have bitten before-----------------------------
* **The compiler optimises your fixture away.** A static never written is proved constant, its reads folded, and no relocation emitted. Add a writer the compiler cannot see through.* **String literals versus named arrays.** The contents-hashing path keys on ``SHF_STRINGS``, which the compiler sets on the mergeable section a *literal* lands in, not on a ``char[]`` given a section of its own.* **Per-function sections hide movement.** With the default ``-ffunction-sections`` every function sits at offset 0 of its own section, so nothing ever moves. A test about position needs ``build_pair foo.c -fno-function-sections``.* **Special sections need boundaries.** Either an entsize on the section or an ``ANNOTATE_DATA_SPECIAL`` annotation, or klp diff reports "missing special section entsize or annotations". Their targets need real (global) symbols, or it reports "failed to convert reloc sym".* **Prefer letting objtool generate what objtool generates.** ``.static_call_sites``, ``.mcount_loc``, ``.ibt_endbr_seal`` and ORC come from its check pass. Call ``run_objtool_check --mcount`` and let it build them; a hand-written copy tests your reading of the format, not the format.
Write one by hand only when the test needs a shape objtool will not produce, and say so in the fixture. generic/fixtures/static_call.c does: objtool emits the site but not the ``ANNOTATE_DATA_SPECIAL`` that describes its boundaries -- those come from the kernel's macros -- so a fixture which has to vary whether the annotation is there writes both itself.
Writing the test================
Start from the shortest existing test, generic/test-basic.sh.
State the premise-----------------
A test which asserts only on the output passes when the compiler never emittedthe construct in the first place, and reads as coverage it does not have. Saywhat the input must contain::
assert_input_section __jump_table # the fixture must produce it -> fail require_input_section .kcfi_traps # this compiler may not -> skip
Prefer ``assert_*``. Reach for ``require_*`` only where absence genuinelydepends on compiler version or flags, and follow it with somethingunconditional so the test can never be entirely vacuous.
Where a test would otherwise duplicate a sibling, assert what makes itdifferent. ``test-jump-label-module-static-key`` checks that the key really isreached through its section symbol -- without that it is a second copy of``test-jump-label-module-key``.
Assert both directions----------------------
Check that the right thing happened *and* that the wrong thing did not. A klpdiff which clones everything is as wrong as one which clones nothing::
assert_patched changed assert_not_patched untouched
Skips-----
* ``gcc_only``/``clang_only`` -- a settled fact about the compiler. Declared, so it reads as expected forever.* ``probe_skip`` -- this toolchain did not produce the construct. Include what to do about it if there is anything::
probe_skip "no matching clang/lld pair for a ThinLTO link; set THIN_CC and THIN_LD to one"
* A bare ``skip`` is **counted as a failure**. Never use it.
Standing in for a kernel configuration--------------------------------------
``FIXTURE_CFLAGS`` is what a fixture is built with. Since objtool reads no``.config``, changing these flags is how a test covers a configuration withoutbuilding a kernel. Two ways:
* trailing arguments to ``build_pair``/``build_one``, which win, and cover anything expressible as a negation::
build_pair foo.c -fno-function-sections
* otherwise assign ``FIXTURE_CFLAGS`` before building.
Either way **say in a comment which kernel configuration the change stands infor**. A flag with no stated motive is indistinguishable from a mistake.
What the test's comment must say================================
The comment at the top is the test's justification. It should let a readerdecide, without archaeology, whether a skip or a failure matters. Include:
* **what breaks** in the running kernel if the behaviour regresses -- not the mechanism, the consequence;* **why it is not caught otherwise**, which is usually "nothing fails at build time";* **the fix commit** it guards, if there is one;* **anything load-bearing about the fixture** that is not obvious, especially anything you got wrong first.
That last point is the one people skip. If the fixture has to be built withoutper-function sections, or the static must not be named ``__warned``, or the keymust be file-local -- write it down, or the next person will simplify it away.
Porting a test from another harness===================================
Read the original's *case*, not its code. The other harness probably builds areal kernel module; here you write freestanding C. A transliteration willusually test something else.
* Work out which objtool behaviour the case exercises, then produce that shape the cheapest way here.* Verify by breaking the code, exactly as for a new test -- a port is not correct because the original was.* If the original names a fix commit, cite it.* Credit the source in the commit message with the trailers the original carried, followed by your own.
Sometimes the port shows the case is already covered, and sometimes it showsthe case cannot be reproduced here. Both are results; report them rather thancommitting something that passes vacuously.
When to give up===============
Some behaviour cannot be reached from a compiled fixture. Say so, with whatyou tried, instead of committing a test that passes either way. Examples thatwere genuinely abandoned:
* a memory leak -- needs valgrind, not an assertion on ELF;* ``mkstemp`` with long paths, and other I/O edge cases;* a NULL dereference reachable only through a debug path;* changes made redundant by a fallback: removing the code changes no output because something else already handles the case;* a fix whose code has since been rewritten, so there is nothing left to revert.
Also stop when the behaviour depends on something outside the fixture'scontrol -- an ELF library's handling of empty sections, or a compiler version'snaming of anonymous data. A test which passes for you and skips for everyoneelse is worse than none.
Checklist=========
Before committing:
* the test fails with the code broken, and passes with it fixed* the whole suite passes under **both** gcc and clang* the premise is asserted, not assumed* both directions are asserted where that applies* no bare ``skip``* the fixture is in the same directory as the test* the comment names the consequence, the fix commit, and anything load-bearing* the commit contains one test and its fixtures, and nothing else* the commit message says how you verified it