objtool/tests/lib.sh

# SPDX-License-Identifier: GPL-2.0
#
# Helpers for the objtool klp tests.  A test builds a fixture twice, as the
# original and (with -DPATCHED) the patched object, runs both through
# "klp checksum" and diffs them, then asserts on the result.
#
# Assertions check properties rather than compare against recorded output:
# codegen varies between compilers and golden files would report churn instead
# of regressions.

TESTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Tests live in generic/ or in an architecture directory beside it, and each
# carries its own fixtures.
FIXTURES_DIR="$(cd "$(dirname "$0")/fixtures" 2>/dev/null && pwd)"

# The kernel's convention: CROSS_COMPILE is the one knob, with per-tool
# overrides for what it does not cover.  objtool itself is always a host binary
# -- it is built with HOSTCC and only reads ELF -- so an arm64 machine can run
# the x86 tests against x86 objects given a compiler that emits them.
#
# readelf reads any target, so it rarely needs overriding, and either GNU
# readelf or llvm-readelf will do: the assertions match on fields rather than
# on columns, and where the two spell something differently -- "OS [0xff20]"
# against "OS[0xff20]" for SHN_LIVEPATCH -- they accept both.  BFD's objcopy is
# usually built for the host's target alone, and llvm-objcopy is the
# target-agnostic replacement.
CROSS_COMPILE="${CROSS_COMPILE:-}"
CC="${CC:-${CROSS_COMPILE}gcc}"
LD="${LD:-${CROSS_COMPILE}ld}"
READELF="${READELF:-${CROSS_COMPILE}readelf}"
OBJCOPY="${OBJCOPY:-${CROSS_COMPILE}objcopy}"

OBJTOOL="${OBJTOOL:-$TESTS_DIR/../objtool}"

# klp_preflight
#
# Check the environment once, before any test runs, and report what was found.
#
klp_preflight()
{
	local tmp tool cc_version arch host cc_arch

	bail() { echo "Bail out! $*" >&2; exit 1; }

	# A relative $OBJTOOL is relative to the objtool directory, not tests/.
	[ -x "$OBJTOOL" ] || [ ! -x "$TESTS_DIR/../$OBJTOOL" ] ||
		OBJTOOL="$TESTS_DIR/../$OBJTOOL"

	[ -x "$OBJTOOL" ] ||
		bail "objtool not found at '$OBJTOOL' -- build it first"

	# run_diff() runs objtool from inside the test's working directory, so
	# a relative path would resolve against that instead.
	OBJTOOL="$(realpath "$OBJTOOL")"

	"$OBJTOOL" klp 2>&1 | grep -q checksum ||
		bail "objtool was built without klp support; install libxxhash (>= 0.8) and rebuild"

	command -v "${CC%% *}" >/dev/null || bail "compiler not found: $CC"

	for tool in "$READELF" "$OBJCOPY" "$LD"; do
		command -v "${tool%% *}" >/dev/null || bail "$tool not found"
	done

	tmp="$(mktemp -d)" || bail "mktemp failed"
	echo 'int probe(void) { return 0; }' > "$tmp/probe.c"
	$CC -c -o "$tmp/probe.o" "$tmp/probe.c" 2>/dev/null ||
		{ rm -rf "$tmp"; bail "$CC cannot compile a trivial object"; }

	# $CC, $ARCH and objtool have to agree about the target, and cross runs
	# are where they stop agreeing: plain "CC=clang ARCH=x86_64" on an arm64
	# box selects the x86 tests and then builds arm64 objects, because clang
	# needs --target= to emit anything but the host's.
	#
	# Ask objtool rather than comparing machine names.  It rejects an object
	# it was not built for -- "unexpected ELF machine type" -- so one check
	# covers every way the three can disagree, and says so once instead of
	# failing every test for the same reason.
	"$OBJTOOL" klp checksum "$tmp/probe.o" >/dev/null 2>&1 ||
		{ rm -rf "$tmp"
		  bail "objtool rejects an object built by '$CC'; they target" \
		       "different architectures (set CROSS_COMPILE, or" \
		       "--target= for clang)"; }

	# BFD objcopy is usually built for the host's target alone, and
	# checksum_of() needs it to read the object under test.
	$OBJCOPY -O binary --only-section=.text "$tmp/probe.o" "$tmp/probe.bin" 2>/dev/null ||
		{ rm -rf "$tmp"
		  bail "$OBJCOPY cannot read objects built by '$CC'; install" \
		       "binutils-multiarch or set OBJCOPY=llvm-objcopy"; }
	# $ARCH only chooses which directory of tests runs, so it can disagree
	# with what $CC builds without objtool noticing -- and the result is the
	# wrong set of tests, quietly.
	case "$($READELF -hW "$tmp/probe.o" | sed -n 's/.*Machine: *//p')" in
	*X86-64*|*Intel*80386*)	cc_arch=x86 ;;
	*AArch64*)		cc_arch=arm64 ;;
	*)			cc_arch= ;;
	esac
	rm -rf "$tmp"

	# Normalize to the kernel's SRCARCH.
	case "${ARCH:-$(uname -m)}" in
	x86_64|i?86)	arch=x86 ;;
	aarch64*)	arch=arm64 ;;
	*)		arch="${ARCH:-$(uname -m)}" ;;
	esac

	case "$(uname -m)" in
	x86_64|i?86)	host=x86 ;;
	aarch64*)	host=arm64 ;;
	*)		host="$(uname -m)" ;;
	esac

	[ -z "$cc_arch" ] || [ "$cc_arch" = "$arch" ] ||
		bail "ARCH says $arch but '$CC' builds $cc_arch objects;" \
		     "the $arch tests would run against the wrong architecture"

	KLP_TEST_ARCH="$arch"
	KLP_TEST_PREFLIGHT=done
	export OBJTOOL CC KLP_TEST_ARCH KLP_TEST_PREFLIGHT

	cc_version="$($CC --version 2>/dev/null | head -1)"
	cat <<EOF
# preflight
#   objtool   $OBJTOOL (klp: yes)
#   compiler  $cc_version
#   arch      $KLP_TEST_ARCH$([ "$arch" = "$host" ] || echo "  (host $host, cross)")
EOF
}

[ -n "${KLP_TEST_PREFLIGHT:-}" ] || klp_preflight

# klp-build compiles the kernel this way; klp diff needs per-symbol sections to
# extract individual functions.
FIXTURE_CFLAGS="-c -O2 -ffunction-sections -fdata-sections -fno-asynchronous-unwind-tables"

test_name="$(basename "$0" .sh)"
workdir=

pass() { echo "ok - $test_name${1:+: $1}"; exit 0; }
fail() { echo "not ok - $test_name: $1"; exit 1; }

# Two kinds of skip, and the runner tells them apart.
#
#   declared_skip  the test said in advance it does not apply here, e.g.
#                  gcc_only on a clang run.  Expected indefinitely.
#   probe_skip     the construct did not turn up in the built object this
#                  time.  Weaker: it may appear on another compiler version,
#                  and one which becomes permanent is a fixture that quietly
#                  stopped testing anything.
#
# A bare skip() is neither, and the runner counts it as a failure: a test which
# gives up for a reason it never declared is a hole, not an outcome.
declared_skip() { echo "ok - $test_name # SKIP (declared) $*"; exit 0; }
probe_skip()    { echo "ok - $test_name # SKIP (probe) $*"; exit 0; }
skip()          { echo "ok - $test_name # SKIP $*"; exit 0; }

# TAP directives.  A test which is known to fail reports it rather than being
# commented out and forgotten, and one which starts passing again says so
# instead of quietly going green: the expectation has to be removed by hand,
# which is the point.
xfail()
{
	echo "not ok - $test_name${1:+: $1} # TODO known failure"
	exit 0
}

xpass()
{
	echo "ok - $test_name${1:+: $1} # TODO expected failure, but passed"
	exit 1
}

cleanup() { [ -n "$workdir" ] && rm -rf "$workdir"; }

# setup [exported symbol...]
setup()
{
	# The environment was checked once when this file was sourced, so there
	# is nothing to verify here: objtool exists at the resolved path, has
	# klp support, and $CC works.
	workdir="$(mktemp -d)" || fail "mktemp failed"
	trap cleanup EXIT

	export_syms "$@"
}

# export_syms [symbol...]
#
# Rewrite Module.symvers so exactly these symbols are exported by vmlinux.
# Whether a symbol is listed decides between an ordinary relocation and a klp
# relocation, so tests flip it to cover both.
export_syms()
{
	: > "$workdir/Module.symvers"
	for sym in "$@"; do
		printf '0x00000000\t%s\tvmlinux\tEXPORT_SYMBOL\t\n' \
			"$sym" >> "$workdir/Module.symvers"
	done
}

# gcc_only / clang_only <reason>
gcc_only()
{
	case "$($CC --version 2>/dev/null | head -1)" in
	*[Gg][Cc][Cc]*)	return 0 ;;
	esac
	declared_skip "gcc only${1:+: $1}"
}

clang_only()
{
	case "$($CC --version 2>/dev/null | head -1)" in
	*clang*)	return 0 ;;
	esac
	declared_skip "clang only${1:+: $1}"
}

# build_pair <fixture.c> [cflags...]
build_pair()
{
	local fixture="$FIXTURES_DIR/$1"; shift

	[ -f "$fixture" ] || fail "missing fixture $fixture"

	$CC $FIXTURE_CFLAGS "$@" -o "$workdir/orig.o" "$fixture" 2>"$workdir/cc.log" ||
		probe_skip "fixture does not build here: $(tail -1 "$workdir/cc.log")"
	$CC $FIXTURE_CFLAGS "$@" -DPATCHED -o "$workdir/patched.o" "$fixture" 2>"$workdir/cc.log" ||
		probe_skip "fixture does not build here: $(tail -1 "$workdir/cc.log")"
}

# run_diff [expected exit status]
run_diff()
{
	local expect="${1:-0}" rc=0

	# Checksums live in the objects, so only generate them once even when a
	# test diffs the same pair again with a different Module.symvers.
	if [ ! -e "$workdir/.checksummed" ]; then
		"$OBJTOOL" klp checksum "$workdir/orig.o" ||
			fail "klp checksum orig.o failed"
		"$OBJTOOL" klp checksum "$workdir/patched.o" ||
			fail "klp checksum patched.o failed"
		touch "$workdir/.checksummed"
	fi

	# klp diff looks for Module.symvers relative to the working directory.
	( cd "$workdir" && "$OBJTOOL" klp diff orig.o patched.o out.o ) \
		> "$workdir/diff.log" 2>&1 || rc=$?

	[ "$rc" = "$expect" ] ||
		fail "klp diff exited $rc, expected $expect: $(tail -2 "$workdir/diff.log")"
}

cc_supports()
{
	echo 'int f(void) { return 0; }' > "$workdir/flagtest.c"
	$CC $1 -c "$workdir/flagtest.c" -o "$workdir/flagtest.o" 2>/dev/null
}

# partial_link <output> <object...>
#
# "ld -r" through the compiler driver so the link targets the same
# architecture as the objects.
partial_link()
{
	local out="$1"; shift

	$CC -r -nostdlib -o "$out" "$@" 2>/dev/null ||
		$CC -r -nostdlib -fuse-ld=lld -o "$out" "$@" 2>/dev/null
}

# find_thinlto_toolchain
#
# Set $THIN_LD to an lld from the same LLVM release as $CC (or THIN_CC).  A
# mismatched pair fails with "Invalid summary version", which reads like a
# broken test rather than a broken environment.
#
# ThinLTO is clang-only; callers must use clang_only before calling this.
# Only $CC (or an explicit THIN_CC override) is consulted -- the harness does
# not search for a second compiler beside a gcc $CC.
find_thinlto_toolchain()
{
	local cc ver ld

	for cc in "${THIN_CC:-}" "$CC"; do
		[ -n "$cc" ] || continue
		command -v "${cc%% *}" >/dev/null 2>&1 || return 1

		ver=$($cc -dumpversion 2>/dev/null | cut -d. -f1)

		for ld in "${THIN_LD:-}" "ld.lld-$ver" ld.lld; do
			[ -n "$ld" ] || continue
			command -v "$ld" >/dev/null 2>&1 || continue

			echo 'int probe(void) { return 0; }' > "$workdir/probe.c"
			$cc -flto=thin -O2 -c "$workdir/probe.c" \
				-o "$workdir/probe.o" 2>/dev/null || continue
			"$ld" -r "$workdir/probe.o" -o "$workdir/probe.elf" \
				2>/dev/null || continue

			THIN_CC="$cc"
			THIN_LD="$ld"
			return 0
		done
	done

	return 1
}

out_sections() { $READELF -S -W "$workdir/out.o" 2>/dev/null; }
out_relocs()   { $READELF -r -W "$workdir/out.o" 2>/dev/null; }
out_symbols()  { $READELF -s -W "$workdir/out.o" 2>/dev/null; }
diff_log()     { cat "$workdir/diff.log"; }

assert_section()
{
	out_sections | grep -q "[[:space:]]$1[[:space:]]" ||
		fail "expected section '$1' in output"
}

assert_patched()
{
	assert_section ".text.$1"
}

assert_not_patched()
{
	out_sections | grep -q "[[:space:]].text.$1[[:space:]]" &&
		fail "function '$1' should not have been cloned"
	return 0
}