Commit e047c5ea authored by David Gow's avatar David Gow Committed by Shuah Khan
Browse files

kunit: Expose 'static stub' API to redirect functions 



Add a simple way of redirecting calls to functions by including a
special prologue in the "real" function which checks to see if the
replacement function should be called (and, if so, calls it).

To redirect calls to a function, make the first (non-declaration) line
of the function:

	KUNIT_STATIC_STUB_REDIRECT(function_name, [function arguments]);

(This will compile away to nothing if KUnit is not enabled, otherwise it
will check if a redirection is active, call the replacement function,
and return. This check is protected by a static branch, so has very
little overhead when there are no KUnit tests running.)

Calls to the real function can be redirected to a replacement using:

	kunit_activate_static_stub(test, real_fn, replacement_fn);

The redirection will only affect calls made from within the kthread of
the current test, and will be automatically disabled when the test
completes. It can also be manually disabled with
kunit_deactivate_static_stub().

The 'example' KUnit test suite has a more complete example.

Co-developed-by: default avatarDaniel Latypov <dlatypov@google.com>
Signed-off-by: default avatarDaniel Latypov <dlatypov@google.com>
Signed-off-by: default avatarDavid Gow <davidgow@google.com>
Reviewed-by: default avatarBrendan Higgins <brendanhiggins@google.com>
Signed-off-by: default avatarShuah Khan <skhan@linuxfoundation.org>
parent 7170b7ed

include/kunit/static_stub.h

0 → 100644
+113 −0
Original line number Diff line number Diff line 
/* SPDX-License-Identifier: GPL-2.0 */

/*

 * KUnit function redirection (static stubbing) API.

 *

 * Copyright (C) 2022, Google LLC.

 * Author: David Gow <davidgow@google.com>

 */

#ifndef _KUNIT_STATIC_STUB_H

#define _KUNIT_STATIC_STUB_H



#if !IS_ENABLED(CONFIG_KUNIT)



/* If CONFIG_KUNIT is not enabled, these stubs quietly disappear. */

#define KUNIT_TRIGGER_STATIC_STUB(real_fn_name, args...) do {} while (0)



#else



#include <kunit/test.h>

#include <kunit/test-bug.h>



#include <linux/compiler.h> /* for {un,}likely() */

#include <linux/sched.h> /* for task_struct */





/**

 * KUNIT_STATIC_STUB_REDIRECT() - call a replacement 'static stub' if one exists

 * @real_fn_name: The name of this function (as an identifier, not a string)

 * @args: All of the arguments passed to this function

 *

 * This is a function prologue which is used to allow calls to the current

 * function to be redirected by a KUnit test. KUnit tests can call

 * kunit_activate_static_stub() to pass a replacement function in. The

 * replacement function will be called by KUNIT_TRIGGER_STATIC_STUB(), which

 * will then return from the function. If the caller is not in a KUnit context,

 * the function will continue execution as normal.

 *

 * Example:

 *

 * .. code-block:: c

 *

 *	int real_func(int n)

 *	{

 *		KUNIT_STATIC_STUB_REDIRECT(real_func, n);

 *		return 0;

 *	}

 *

 *	int replacement_func(int n)

 *	{

 *		return 42;

 *	}

 *

 *	void example_test(struct kunit *test)

 *	{

 *		kunit_activate_static_stub(test, real_func, replacement_func);

 *		KUNIT_EXPECT_EQ(test, real_func(1), 42);

 *	}

 *

 */

#define KUNIT_STATIC_STUB_REDIRECT(real_fn_name, args...)		\

do {									\

	typeof(&real_fn_name) replacement;				\

	struct kunit *current_test = kunit_get_current_test();		\

									\

	if (likely(!current_test))					\

		break;							\

									\

	replacement = kunit_hooks.get_static_stub_address(current_test,	\

							&real_fn_name);	\

									\

	if (unlikely(replacement))					\

		return replacement(args);				\

} while (0)



/* Helper function for kunit_activate_static_stub(). The macro does

 * typechecking, so use it instead.

 */

void __kunit_activate_static_stub(struct kunit *test,

				  void *real_fn_addr,

				  void *replacement_addr);



/**

 * kunit_activate_static_stub() - replace a function using static stubs.

 * @test: A pointer to the 'struct kunit' test context for the current test.

 * @real_fn_addr: The address of the function to replace.

 * @replacement_addr: The address of the function to replace it with.

 *

 * When activated, calls to real_fn_addr from within this test (even if called

 * indirectly) will instead call replacement_addr. The function pointed to by

 * real_fn_addr must begin with the static stub prologue in

 * KUNIT_TRIGGER_STATIC_STUB() for this to work. real_fn_addr and

 * replacement_addr must have the same type.

 *

 * The redirection can be disabled again with kunit_deactivate_static_stub().

 */

#define kunit_activate_static_stub(test, real_fn_addr, replacement_addr) do {	\

	typecheck_fn(typeof(&real_fn_addr), replacement_addr);			\

	__kunit_activate_static_stub(test, real_fn_addr, replacement_addr);	\

} while (0)





/**

 * kunit_deactivate_static_stub() - disable a function redirection

 * @test: A pointer to the 'struct kunit' test context for the current test.

 * @real_fn_addr: The address of the function to no-longer redirect

 *

 * Deactivates a redirection configured with kunit_activate_static_stub(). After

 * this function returns, calls to real_fn_addr() will execute the original

 * real_fn, not any previously-configured replacement.

 */

void kunit_deactivate_static_stub(struct kunit *test, void *real_fn_addr);



#endif

#endif

include/kunit/test-bug.h

+1 −0
Original line number Diff line number Diff line
@@ -20,6 +20,7 @@ DECLARE_STATIC_KEY_FALSE(kunit_running); 
/* Hooks table: a table of function pointers filled in when kunit loads */

extern struct kunit_hooks_table {

	__printf(3, 4) void (*fail_current_test)(const char*, int, const char*, ...);

	void *(*get_static_stub_address)(struct kunit *test, void *real_fn_addr);

} kunit_hooks;



/**

lib/kunit/Makefile

+1 −0
Original line number Diff line number Diff line
@@ -2,6 +2,7 @@ obj-$(CONFIG_KUNIT) += kunit.o 


kunit-objs +=				test.o \

					resource.o \

					static_stub.o \

					string-stream.o \

					assert.o \

					try-catch.o \

lib/kunit/hooks-impl.h

+2 −0
Original line number Diff line number Diff line
@@ -16,12 +16,14 @@ 


/* List of declarations. */

void __kunit_fail_current_test_impl(const char *file, int line, const char *fmt, ...);

void *__kunit_get_static_stub_address_impl(struct kunit *test, void *real_fn_addr);



/* Code to set all of the function pointers. */

static inline void kunit_install_hooks(void)

{

	/* Install the KUnit hook functions. */

	kunit_hooks.fail_current_test = __kunit_fail_current_test_impl;

	kunit_hooks.get_static_stub_address = __kunit_get_static_stub_address_impl;

}



#endif /* _KUNIT_HOOKS_IMPL_H */

lib/kunit/kunit-example-test.c

+38 −0
Original line number Diff line number Diff line
@@ -7,6 +7,7 @@ 
 */



#include <kunit/test.h>

#include <kunit/static_stub.h>



/*

 * This is the most fundamental element of KUnit, the test case. A test case
@@ -130,6 +131,42 @@ static void example_all_expect_macros_test(struct kunit *test) 
	KUNIT_ASSERT_GT_MSG(test, sizeof(int), 0, "Your ints are 0-bit?!");

}



/* This is a function we'll replace with static stubs. */

static int add_one(int i)

{

	/* This will trigger the stub if active. */

	KUNIT_STATIC_STUB_REDIRECT(add_one, i);



	return i + 1;

}



/* This is used as a replacement for the above function. */

static int subtract_one(int i)

{

	/* We don't need to trigger the stub from the replacement. */



	return i - 1;

}



/*

 * This test shows the use of static stubs.

 */

static void example_static_stub_test(struct kunit *test)

{

	/* By default, function is not stubbed. */

	KUNIT_EXPECT_EQ(test, add_one(1), 2);



	/* Replace add_one() with subtract_one(). */

	kunit_activate_static_stub(test, add_one, subtract_one);



	/* add_one() is now replaced. */

	KUNIT_EXPECT_EQ(test, add_one(1), 0);



	/* Return add_one() to normal. */

	kunit_deactivate_static_stub(test, add_one);

	KUNIT_EXPECT_EQ(test, add_one(1), 2);

}



/*

 * Here we make a list of all the test cases we want to add to the test suite

 * below.
@@ -145,6 +182,7 @@ static struct kunit_case example_test_cases[] = { 
	KUNIT_CASE(example_skip_test),

	KUNIT_CASE(example_mark_skipped_test),

	KUNIT_CASE(example_all_expect_macros_test),

	KUNIT_CASE(example_static_stub_test),

	{}

};