1.. SPDX-License-Identifier: GPL-2.0
  2
  3========================
  4Function Redirection API
  5========================
  6
  7Overview
  8========
  9
 10When writing unit tests, it's important to be able to isolate the code being
 11tested from other parts of the kernel. This ensures the reliability of the test
 12(it won't be affected by external factors), reduces dependencies on specific
 13hardware or config options (making the test easier to run), and protects the
 14stability of the rest of the system (making it less likely for test-specific
 15state to interfere with the rest of the system).
 16
 17While for some code (typically generic data structures, helpers, and other
 18"pure functions") this is trivial, for others (like device drivers,
 19filesystems, core subsystems) the code is heavily coupled with other parts of
 20the kernel.
 21
 22This coupling is often due to global state in some way: be it a global list of
 23devices, the filesystem, or some hardware state. Tests need to either carefully
 24manage, isolate, and restore state, or they can avoid it altogether by
 25replacing access to and mutation of this state with a "fake" or "mock" variant.
 26
 27By refactoring access to such state, such as by introducing a layer of
 28indirection which can use or emulate a separate set of test state. However,
 29such refactoring comes with its own costs (and undertaking significant
 30refactoring before being able to write tests is suboptimal).
 31
 32A simpler way to intercept and replace some of the function calls is to use
 33function redirection via static stubs.
 34
 35
 36Static Stubs
 37============
 38
 39Static stubs are a way of redirecting calls to one function (the "real"
 40function) to another function (the "replacement" function).
 41
 42It works by adding a macro to the "real" function which checks to see if a test
 43is running, and if a replacement function is available. If so, that function is
 44called in place of the original.
 45
 46Using static stubs is pretty straightforward:
 47
 481. Add the KUNIT_STATIC_STUB_REDIRECT() macro to the start of the "real"
 49   function.
 50
 51   This should be the first statement in the function, after any variable
 52   declarations. KUNIT_STATIC_STUB_REDIRECT() takes the name of the
 53   function, followed by all of the arguments passed to the real function.
 54
 55   For example:
 56
 57   .. code-block:: c
 58
 59	void send_data_to_hardware(const char *str)
 60	{
 61		KUNIT_STATIC_STUB_REDIRECT(send_data_to_hardware, str);
 62		/* real implementation */
 63	}
 64
 652. Write one or more replacement functions.
 66
 67   These functions should have the same function signature as the real function.
 68   In the event they need to access or modify test-specific state, they can use
 69   kunit_get_current_test() to get a struct kunit pointer. This can then
 70   be passed to the expectation/assertion macros, or used to look up KUnit
 71   resources.
 72
 73   For example:
 74
 75   .. code-block:: c
 76
 77	void fake_send_data_to_hardware(const char *str)
 78	{
 79		struct kunit *test = kunit_get_current_test();
 80		KUNIT_EXPECT_STREQ(test, str, "Hello World!");
 81	}
 82
 833. Activate the static stub from your test.
 84
 85   From within a test, the redirection can be enabled with
 86   kunit_activate_static_stub(), which accepts a struct kunit pointer,
 87   the real function, and the replacement function. You can call this several
 88   times with different replacement functions to swap out implementations of the
 89   function.
 90
 91   In our example, this would be
 92
 93   .. code-block:: c
 94
 95	kunit_activate_static_stub(test,
 96				   send_data_to_hardware,
 97				   fake_send_data_to_hardware);
 98
 994. Call (perhaps indirectly) the real function.
100
101   Once the redirection is activated, any call to the real function will call
102   the replacement function instead. Such calls may be buried deep in the
103   implementation of another function, but must occur from the test's kthread.
104
105   For example:
106
107   .. code-block:: c
108
109	send_data_to_hardware("Hello World!"); /* Succeeds */
110	send_data_to_hardware("Something else"); /* Fails the test. */
111
1125. (Optionally) disable the stub.
113
114   When you no longer need it, disable the redirection (and hence resume the
115   original behaviour of the 'real' function) using
116   kunit_deactivate_static_stub(). Otherwise, it will be automatically disabled
117   when the test exits.
118
119   For example:
120
121   .. code-block:: c
122
123	kunit_deactivate_static_stub(test, send_data_to_hardware);
124
125
126It's also possible to use these replacement functions to test to see if a
127function is called at all, for example:
128
129.. code-block:: c
130
131	void send_data_to_hardware(const char *str)
132	{
133		KUNIT_STATIC_STUB_REDIRECT(send_data_to_hardware, str);
134		/* real implementation */
135	}
136
137	/* In test file */
138	int times_called = 0;
139	void fake_send_data_to_hardware(const char *str)
140	{
141		times_called++;
142	}
143	...
144	/* In the test case, redirect calls for the duration of the test */
145	kunit_activate_static_stub(test, send_data_to_hardware, fake_send_data_to_hardware);
146
147	send_data_to_hardware("hello");
148	KUNIT_EXPECT_EQ(test, times_called, 1);
149
150	/* Can also deactivate the stub early, if wanted */
151	kunit_deactivate_static_stub(test, send_data_to_hardware);
152
153	send_data_to_hardware("hello again");
154	KUNIT_EXPECT_EQ(test, times_called, 1);
155
156
157
158API Reference
159=============
160
161.. kernel-doc:: include/kunit/static_stub.h
162   :internal: