6. KTF programming reference

KTF itself contains no tests but provides primitives and data structures to allow tests to be maintained and written in separate test modules that depend on the KTF APIs.

KTF API Overview

For reference, the following table lists a few terms and classes of abstractions provided by KTF:

Item	description
Test module	A kernel object file (.ko) with ktf tests in it
struct ktf_handle	At least 1 per test module. Use macros KTF_INIT() and KTF_CLEANUP() to set up and tear down handles.
struct ktf_context	0-n per test module - test module specific context for the test, such as eg. a device or another kernel object.
KTF_INIT()	Call this at the global level in the main file for each test module.
KTF_CLEANUP()	Call this in the __exit function to clean up
EXPECT_*	non-fatal assertions
ASSERT_*	“fatal” assertions that would cause return/goto
TEST(s, n) {...}	Define a simple test named ‘s.n’ with implicit arguments ‘ctx’ and ‘_i’ for context/iteration.
DECLARE_F(f) {...}	Declare a new test fixture named ‘f’ with additional data structure
SETUP_F(f, s) {...}	Define setup function for the fixture
TEARDOWN_F(f, t) {...}	Define teardown function for the fixture
INIT_F(f, s, t) {...}	Declare the setup and tear down functions for the fixture
TEST_F(s, f, n) {...}	Define a test named ‘s.n’ operating in fixture f
KTF_ENTRY_PROBE (f, r, ...) {...}	Define function entry probe for function f with return value r. Arguments following r must match function arguments. Must be used at global level.
KTF_ENTRY_PROBE_RETURN(r)	Return from probed function with return value r. Must be called within KTF_ENTRY_PROBE().
KTF_REGISTER_ENTRY_PROBE(f)	Enable probe on entry to kernel function f.
KTF_UNREGISTER_ENTRY_PROBE	Disable probe on entry to kernel function f.
KTF_RETURN_PROBE(f) {...}	Define function return probe for function f. Must be used at a global level.
KTF_RETURN_VALUE()	Retrieve return value in body of return probe.
KTF_REGISTER_RETURN_PROBE	Enable probe for return of function f.
KTF_UNREGISTER_RETURN_PROBE	Disable probe for return of function f.
ktf_cov_enable(m, flags)	Enable coverage analytics for module m. Flag must be either 0 or KTF_COV_OPT_MEM.
ktf_cov_disable(m)	Disable coverage analytics for module m.

The KTF_INIT() macro must be called at a global level as it just defines a variable __test_handle which is referred to which existence is assumed to continue until the call to KTF_CLEANUP(), typically done in the __exit function of the test module.

Assertions

Below is example documentation for some of the available assertion macros. For a full overview, see kernel/ktf.h

ASSERT_TRUE(C)

fail and return if C evaluates to false

Parameters

C

Boolean expression to evaluate

ASSERT_FALSE(C)

fail and return if C evaluates to true

Parameters

C

Boolean expression to evaluate

ASSERT_TRUE_GOTO(C, _lbl)

fail and jump to _lbl if C evaluates to false

Parameters

C

Boolean expression to evaluate

_lbl

Label to jump to in case of failure

ASSERT_FALSE_GOTO(C, _lbl)

fail and jump to _lbl if C evaluates to true

Parameters

C

Boolean expression to evaluate

_lbl

Label to jump to in case of failure

ASSERT_LONG_EQ(X, Y)

compare two longs, fail and return if X != Y

Parameters

X

Expected value

Y

Actual value

ASSERT_LONG_EQ_GOTO(X, Y, _lbl)

compare two longs, jump to _lbl if X != Y

Parameters

X

Expected value

Y

Actual value

_lbl

Label to jump to in case of failure

EXPECT_TRUE(C)

fail if C evaluates to false but allow test to continue

Parameters

C

Boolean expression to evaluate