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

kunit: Add APIs for managing devices 



Tests for drivers often require a struct device to pass to other
functions. While it's possible to create these with
root_device_register(), or to use something like a platform device, this
is both a misuse of those APIs, and can be difficult to clean up after,
for example, a failed assertion.

Add some KUnit-specific functions for registering and unregistering a
struct device:
- kunit_device_register()
- kunit_device_register_with_driver()
- kunit_device_unregister()

These helpers allocate a on a 'kunit' bus which will either probe the
driver passed in (kunit_device_register_with_driver), or will create a
stub driver (kunit_device_register) which is cleaned up on test shutdown.

Devices are automatically unregistered on test shutdown, but can be
manually unregistered earlier with kunit_device_unregister() in order
to, for example, test device release code.

Reviewed-by: default avatarMatti Vaittinen <mazziesaccount@gmail.com>
Reviewed-by: default avatarMaxime Ripard <mripard@kernel.org>
Signed-off-by: default avatarDavid Gow <davidgow@google.com>
Reviewed-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: default avatarShuah Khan <skhan@linuxfoundation.org>
parent e9f0e21c

Documentation/dev-tools/kunit/api/resource.rst

+9 −0
Original line number Diff line number Diff line
@@ -11,3 +11,12 @@ state on a per-test basis, register custom cleanup actions, and more. 


.. kernel-doc:: include/kunit/resource.h

   :internal:



Managed Devices

---------------



Functions for using KUnit-managed struct device and struct device_driver.

Include ``kunit/device.h`` to use these.



.. kernel-doc:: include/kunit/device.h

   :internal:

Documentation/dev-tools/kunit/usage.rst

+50 −0
Original line number Diff line number Diff line
@@ -797,3 +797,53 @@ structures as shown below: 
KUnit is not enabled, or if no test is running in the current task, it will do

nothing. This compiles down to either a no-op or a static key check, so will

have a negligible performance impact when no test is running.



Managing Fake Devices and Drivers

---------------------------------



When testing drivers or code which interacts with drivers, many functions will

require a ``struct device`` or ``struct device_driver``. In many cases, setting

up a real device is not required to test any given function, so a fake device

can be used instead.



KUnit provides helper functions to create and manage these fake devices, which

are internally of type ``struct kunit_device``, and are attached to a special

``kunit_bus``. These devices support managed device resources (devres), as

described in Documentation/driver-api/driver-model/devres.rst



To create a KUnit-managed ``struct device_driver``, use ``kunit_driver_create()``,

which will create a driver with the given name, on the ``kunit_bus``. This driver

will automatically be destroyed when the corresponding test finishes, but can also

be manually destroyed with ``driver_unregister()``.



To create a fake device, use the ``kunit_device_register()``, which will create

and register a device, using a new KUnit-managed driver created with ``kunit_driver_create()``.

To provide a specific, non-KUnit-managed driver, use ``kunit_device_register_with_driver()``

instead. Like with managed drivers, KUnit-managed fake devices are automatically

cleaned up when the test finishes, but can be manually cleaned up early with

``kunit_device_unregister()``.



The KUnit devices should be used in preference to ``root_device_register()``, and

instead of ``platform_device_register()`` in cases where the device is not otherwise

a platform device.



For example:



.. code-block:: c



	#include <kunit/device.h>



	static void test_my_device(struct kunit *test)

	{

		struct device *fake_device;

		const char *dev_managed_string;



		// Create a fake device.

		fake_device = kunit_device_register(test, "my_device");

		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, fake_device)



		// Pass it to functions which need a device.

		dev_managed_string = devm_kstrdup(fake_device, "Hello, World!");



		// Everything is cleaned up automatically when the test ends.

	}
 
 No newline at end of file

include/kunit/device.h

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

/*

 * KUnit basic device implementation

 *

 * Helpers for creating and managing fake devices for KUnit tests.

 *

 * Copyright (C) 2023, Google LLC.

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

 */



#ifndef _KUNIT_DEVICE_H

#define _KUNIT_DEVICE_H



#if IS_ENABLED(CONFIG_KUNIT)



#include <kunit/test.h>



struct device;

struct device_driver;



/**

 * kunit_driver_create() - Create a struct device_driver attached to the kunit_bus

 * @test: The test context object.

 * @name: The name to give the created driver.

 *

 * Creates a struct device_driver attached to the kunit_bus, with the name @name.

 * This driver will automatically be cleaned up on test exit.

 *

 * Return: a stub struct device_driver, managed by KUnit, with the name @name.

 */

struct device_driver *kunit_driver_create(struct kunit *test, const char *name);



/**

 * kunit_device_register() - Create a struct device for use in KUnit tests

 * @test: The test context object.

 * @name: The name to give the created device.

 *

 * Creates a struct kunit_device (which is a struct device) with the given name,

 * and a corresponding driver. The device and driver will be cleaned up on test

 * exit, or when kunit_device_unregister is called. See also

 * kunit_device_register_with_driver, if you wish to provide your own

 * struct device_driver.

 *

 * Return: a pointer to a struct device which will be cleaned up when the test

 * exits, or an error pointer if the device could not be allocated or registered.

 */

struct device *kunit_device_register(struct kunit *test, const char *name);



/**

 * kunit_device_register_with_driver() - Create a struct device for use in KUnit tests

 * @test: The test context object.

 * @name: The name to give the created device.

 * @drv: The struct device_driver to associate with the device.

 *

 * Creates a struct kunit_device (which is a struct device) with the given

 * name, and driver. The device will be cleaned up on test exit, or when

 * kunit_device_unregister is called. See also kunit_device_register, if you

 * wish KUnit to create and manage a driver for you.

 *

 * Return: a pointer to a struct device which will be cleaned up when the test

 * exits, or an error pointer if the device could not be allocated or registered.

 */

struct device *kunit_device_register_with_driver(struct kunit *test,

						 const char *name,

						 const struct device_driver *drv);



/**

 * kunit_device_unregister() - Unregister a KUnit-managed device

 * @test: The test context object which created the device

 * @dev: The device.

 *

 * Unregisters and destroys a struct device which was created with

 * kunit_device_register or kunit_device_register_with_driver. If KUnit created

 * a driver, cleans it up as well.

 */

void kunit_device_unregister(struct kunit *test, struct device *dev);



#endif



#endif

lib/kunit/Makefile

+2 −1
Original line number Diff line number Diff line
@@ -7,7 +7,8 @@ kunit-objs += test.o \ 
					assert.o \

					try-catch.o \

					executor.o \

					attributes.o

					attributes.o \

					device.o



ifeq ($(CONFIG_KUNIT_DEBUGFS),y)

kunit-objs +=				debugfs.o

lib/kunit/device-impl.h

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

/*

 * KUnit internal header for device helpers

 *

 * Header for KUnit-internal driver / bus management.

 *

 * Copyright (C) 2023, Google LLC.

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

 */



#ifndef _KUNIT_DEVICE_IMPL_H

#define _KUNIT_DEVICE_IMPL_H



// For internal use only -- registers the kunit_bus.

int kunit_bus_init(void);



#endif //_KUNIT_DEVICE_IMPL_H