7. 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. These are kernel side, if not otherwise noted:

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. Declares an implicit, default test handle used by macros which do not provide a handle argument.
KTF_CTX_INIT() Use this instead of KTF_INIT if the tests require a context to execute. Tests will only show up as options if a context has been provided.
KTF_HANDLE_INIT(handle) Declare a named handle to associate tests and contexts with. This is an alternative to KTF_INIT() to allow the use of separate test handles for separate sets of tests.
KTF_HANDLE_CTX_INIT(handle) Equivalent of KTF_CTX_INIT for a named handle
KTF_CLEANUP() Call this in the __exit function to clean up
KTF_CONTEXT_ADD(ctx, name) Add a new context to the default handle
KTF_CONTEXT_FIND(name) Return a struct ktf_context reference to context 'name', if it exists
KTF_CONTEXT_GET(name,type) Return the structure of type 'type' containing the ktf_context named 'name', if 'name' exists.
KTF_CONTEXT_REMOVE(ctx) Remove a previously added context from KTF
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
ADD_TEST(n) Add a test previously declared with TEST or TEST_F to the default handle.
ADD_LOOP_TEST(n, from, to) Add a test to be executed repeatedly with a range of values [from,to] to the implicit variable _i
DEL_TEST(n) Remove a test previously added with ADD_TEST
KTF_ENTRY_PROBE(f, h) {...} Define function entry probe for function f with handler function h. 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, h) Enable probe on entry to kernel function f with handler h.
KTF_UNREGISTER_ENTRY_PROBE (f, h) Disable probe on entry to kernel function f which used handler h.
KTF_RETURN_PROBE(f, h) {..} Define function return probe for function f with handler h. Must be used at a global level.
KTF_RETURN_VALUE() Retrieve return value in body of return probe.
KTF_REGISTER_RETURN_PROBE (f, h) Enable probe for return of function f with handler h.
KTF_UNREGISTER_RETURN_PROBE (f, h) Disable probe for return of function f and handler h.
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.
KTF_THREAD_INIT(name, t) Initialize thread name, struct ktf_thread * t.
KTF_THREAD_RUN(t) Run initialized struct ktf_thread * t.
KTF_THREAD_STOP(t) Stop thread via kthread_stop()
KTF_THREAD_WAIT_STARTED(t) Wait for start of struct ktf_thread * t.
KTF_THREAD_WAIT_COMPLETED (t) Wait for completion of struct ktf_thread * t.
HTEST(s, n) { ... } (NB! User mode only!) Declares a hybrid test. A correspondingly named test must be declared using TEST() from kernel space for the hybrid test to be executed.
KTF_USERDATA(self, type, d) (NB! both kernel and user space!) Declare/get a pointer to user/kernel aux.data for a test that declares such extra data. Used for hybrid tests.

The KTF_INIT() macro must be called at a global level as it just defines a variable __test_handle which is referred to, and 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_TRUE_RETVAL(C, V)

fail and return V if C evaluates to false

Parameters

C
Boolean expression to evaluate
V
Value to return on failure
ASSERT_FALSE_RETVAL(C, V)

fail and return V if C evaluates to true

Parameters

C
Boolean expression to evaluate
V
Value to return on failure
ASSERT_TRUE_CONT(C)

fail and continue if C evaluates to false

Parameters

C
Boolean expression to evaluate
ASSERT_FALSE_CONT(C)

fail and continue if C evaluates to true

Parameters

C
Boolean expression to evaluate
ASSERT_TRUE_BREAK(C)

fail and break if C evaluates to false

Parameters

C
Boolean expression to evaluate
ASSERT_FALSE_BREAK(C)

fail and break if C evaluates to true

Parameters

C
Boolean expression to evaluate
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