Resource API¶

此文件记录了 KUnit resource API。

大多数用户不需要直接使用此 API，高级用户可以使用它来按测试存储状态、注册自定义清理操作等等。

struct kunit_resource¶: 代表一个测试管理的资源

定义:

struct kunit_resource {
    void *data;
    const char *name;
    kunit_resource_free_t free;
};

成员

data: 供用户存储任意数据。
name: 可选名称
free: 用户提供的函数来释放资源。

描述

代表一个测试管理的资源，一个将在测试用例结束时自动清理的资源。此清理由 'free' 函数执行。如果 kfree() 分配了资源（例如，通过 kunit_alloc_resource()），则 struct kunit_resource 本身会自动使用 kfree() 释放，否则必须由用户释放。

资源是引用计数的，因此如果通过 kunit_alloc_and_get_resource() 或 kunit_find_resource() 检索资源，我们需要调用 kunit_put_resource() 来减少资源引用计数。请注意，kunit_alloc_resource() 不需要 kunit_resource_put()，因为它不检索资源本身。

struct kunit_kmalloc_params {
        size_t size;
        gfp_t gfp;
};

static int kunit_kmalloc_init(struct kunit_resource *res, void *context)
{
        struct kunit_kmalloc_params *params = context;
        res->data = kmalloc(params->size, params->gfp);

        if (!res->data)
                return -ENOMEM;

        return 0;
}

static void kunit_kmalloc_free(struct kunit_resource *res)
{
        kfree(res->data);
}

void *kunit_kmalloc(struct kunit *test, size_t size, gfp_t gfp)
{
        struct kunit_kmalloc_params params;

        params.size = size;
        params.gfp = gfp;

        return kunit_alloc_resource(test, kunit_kmalloc_init,
                kunit_kmalloc_free, gfp, &params);
}

资源也可以命名，查找/删除也在名称基础上完成。 kunit_add_named_resource()、kunit_find_named_resource() 和 kunit_destroy_named_resource()。资源名称在测试实例中必须是唯一的。

示例

void kunit_get_resource(struct kunit_resource *res)¶: 保留资源以供使用。大多数用户应该不需要使用，因为我们自动获取 kunit_find_resource*() 检索的资源。

参数

struct kunit_resource *res: 资源

void kunit_put_resource(struct kunit_resource *res)¶: 当调用者完成检索到的资源时，应调用 kunit_put_resource() 以删除引用计数。资源列表维护资源的引用计数，因此如果没有用户使用资源并且它从资源列表中删除，它将通过关联的 free 函数（如果有）释放。仅当我们 alloc_and_get() 或 find() 资源时才需要使用。

参数

struct kunit_resource *res: 资源

int __kunit_add_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, struct kunit_resource *res, void *data)¶: 添加资源的内部助手。

参数

struct kunit *test: 测试上下文对象。
kunit_resource_init_t init: 用户提供的函数来初始化结果（如果需要）。如果没有提供，则资源数据值简单地设置为 data。如果提供了 init 函数，则 data 将传递给它。
kunit_resource_free_t free: 用户提供的函数来释放资源（如果需要）。
struct kunit_resource *res: 资源。
void *data: 传递给 init 函数或在资源数据字段中设置的值。

描述

res->should_kfree 未初始化。

int kunit_add_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, struct kunit_resource *res, void *data)¶: 添加一个测试管理的资源。

参数

struct kunit *test: 测试上下文对象。
kunit_resource_init_t init: 用户提供的函数来初始化结果（如果需要）。如果没有提供，则资源数据值简单地设置为 data。如果提供了 init 函数，则 data 将传递给它。
kunit_resource_free_t free: 用户提供的函数来释放资源（如果需要）。
struct kunit_resource *res: 资源。
void *data: 传递给 init 函数或在资源数据字段中设置的值。

int kunit_add_named_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, struct kunit_resource *res, const char *name, void *data)¶: 添加一个命名的测试管理的资源。

参数

struct kunit *test: 测试上下文对象。
kunit_resource_init_t init: 用户提供的函数来初始化资源数据，如果需要。
kunit_resource_free_t free: 用户提供的函数来释放资源数据，如果需要。
struct kunit_resource *res: 资源。
const char *name: 要为资源设置的名称。
void *data: 传递给 init 函数或在资源数据字段中设置的值。

struct kunit_resource *kunit_alloc_and_get_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, gfp_t internal_gfp, void *context)¶: 分配并返回一个测试管理的资源。

参数

struct kunit *test: 测试上下文对象。
kunit_resource_init_t init: 用户提供的函数来初始化资源。
kunit_resource_free_t free: 用户提供的函数来释放资源（如果需要）。
gfp_t internal_gfp: 用于内部分配的 gfp，如果不确定，请使用 GFP_KERNEL
void *context: 供用户将任意数据传递给 init 函数。

描述

分配一个测试管理的资源，一个将在测试用例结束时自动清理的资源。有关示例，请参见 struct kunit_resource。

这实际上与 kunit_alloc_resource 相同，但返回 struct kunit_resource 指针，而不仅仅是 'data' 指针。因此，它也会增加资源的 refcount，因此当您完成使用它时，应该调用 kunit_put_resource()。

注意

KUnit 需要为 kunit_resource 对象分配内存。您必须指定与资源的使用上下文兼容的 internal_gfp。

void *kunit_alloc_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, gfp_t internal_gfp, void *context)¶: 分配一个测试管理的资源。

参数

struct kunit *test: 测试上下文对象。
kunit_resource_init_t init: 用户提供的函数来初始化资源。
kunit_resource_free_t free: 用户提供的函数来释放资源（如果需要）。
gfp_t internal_gfp: 用于内部分配的 gfp，如果不确定，请使用 GFP_KERNEL
void *context: 供用户将任意数据传递给 init 函数。

描述

分配一个测试管理的资源，一个将在测试用例结束时自动清理的资源。有关示例，请参见 struct kunit_resource。

注意

KUnit 需要为 kunit_resource 对象分配内存。您必须指定与资源的使用上下文兼容的 internal_gfp。

bool kunit_resource_name_match(struct kunit *test, struct kunit_resource *res, void *match_name)¶: 匹配具有相同名称的资源。

参数

struct kunit *test: 资源所属的测试用例。
struct kunit_resource *res: 资源。
void *match_name: 要匹配的名称。

struct kunit_resource *kunit_find_resource(struct kunit *test, kunit_resource_match_t match, void *match_data)¶: 使用匹配函数/数据查找资源。

参数

struct kunit *test: 资源所属的测试用例。
kunit_resource_match_t match: 要应用于资源/匹配数据的匹配函数。
void *match_data: 用于匹配的数据。

struct kunit_resource *kunit_find_named_resource(struct kunit *test, const char *name)¶: 使用匹配名称查找资源。

参数

struct kunit *test: 资源所属的测试用例。
const char *name: 匹配名称。

int kunit_destroy_resource(struct kunit *test, kunit_resource_match_t match, void *match_data)¶: 查找 kunit_resource 并销毁它。

参数

struct kunit *test: 资源所属的测试用例。
kunit_resource_match_t match: 匹配函数。返回给定的资源是否匹配 match_data。
void *match_data: 传递到 match 中的数据。

返回

如果找到并释放了 kunit_resource，则返回 0；如果未找到，则返回 -ENOENT。

void kunit_remove_resource(struct kunit *test, struct kunit_resource *res)¶: 从与测试关联的资源列表中删除资源。

参数

struct kunit *test: 测试上下文对象。
struct kunit_resource *res: 要删除的资源。

描述

请注意，资源不会立即释放，因为调用者很可能通过 alloc_and_get() 或 find() 引用它；在这种情况下，需要最后调用 kunit_put_resource()。

KUNIT_DEFINE_ACTION_WRAPPER¶

KUNIT_DEFINE_ACTION_WRAPPER (wrapper, orig, arg_type)

包装一个函数以用作延迟操作。

参数

wrapper: 新包装函数定义的名称。
orig: 要包装的原始函数。
arg_type: orig 接受的参数类型。

描述

为接受单个指针大小参数的函数定义一个包装器。然后可以将此包装器传递给 kunit_add_action() 和类似函数。这应该优先于将函数直接强制转换为 kunit_action_t，因为强制转换函数指针会破坏控制流完整性 (CFI)，从而导致崩溃。

int kunit_add_action(struct kunit *test, kunit_action_t *action, void *ctx)¶: 在测试结束时调用一个函数。

参数

struct kunit *test: 将操作与关联的测试用例。
kunit_action_t *action: 在测试退出时运行的函数
void *ctx: 传递到 func 中的数据

描述

将函数的执行延迟到测试退出时，无论是正常退出还是由于失败。 ctx 作为附加上下文传递。使用 kunit_add_action() 注册的所有函数将以与注册顺序相反的顺序执行。

这对于清理分配的内存和资源很有用，因为即使测试由于例如断言失败而提前中止，也会调用这些函数。

另请参阅：devm_add_action()，了解 devres 等效项。

返回

成功时返回 0，如果无法延迟操作，则返回错误。

int kunit_add_action_or_reset(struct kunit *test, kunit_action_t *action, void *ctx)¶: 在测试结束时调用一个函数。

参数

struct kunit *test: 将操作与关联的测试用例。
kunit_action_t *action: 在测试退出时运行的函数
void *ctx: 传递到 func 中的数据

描述

将函数的执行延迟到测试退出时，无论是正常退出还是由于失败。 ctx 作为附加上下文传递。使用 kunit_add_action() 注册的所有函数将以与注册顺序相反的顺序执行。

这对于清理分配的内存和资源很有用，因为即使测试由于例如断言失败而提前中止，也会调用这些函数。

如果无法创建操作（例如，由于系统内存不足），则将立即调用 action(ctx)，并且将返回错误。

另请参阅：devm_add_action_or_reset()，了解 devres 等效项。

返回

成功时返回 0，如果无法延迟操作，则返回错误。

void kunit_remove_action(struct kunit *test, kunit_action_t *action, void *ctx)¶: 取消匹配的延迟操作。

参数

struct kunit *test: 操作与之关联的测试用例。
kunit_action_t *action: 要取消的延迟函数。
void *ctx: 传递给延迟函数以触发的上下文。

描述

防止通过 kunit_add_action() 延迟的操作在测试终止时执行。

如果函数/上下文对被延迟多次，则只会取消最近的一个。

另请参阅：devm_remove_action()，了解 devres 等效项。

void kunit_release_action(struct kunit *test, kunit_action_t *action, void *ctx)¶: 立即运行匹配的操作调用。

参数

struct kunit *test: 操作与之关联的测试用例。
kunit_action_t *action: 要触发的延迟函数。
void *ctx: 传递给延迟函数以触发的上下文。

描述

立即执行通过 kunit_add_action() 延迟的函数，而不是在测试结束时执行。

如果函数/上下文对被延迟多次，则只会在此处执行一次。最近的延迟将不再在测试结束时执行。

kunit_release_action(test, func, ctx); 等效于 func(ctx); kunit_remove_action(test, func, ctx);

另请参阅：devm_release_action()，了解 devres 等效项。

托管设备¶

用于使用 KUnit 托管的 struct device 和 struct device_driver 的函数。包括 kunit/device.h 以使用这些函数。

struct device_driver *kunit_driver_create(struct kunit *test, const char *name)¶: 创建一个附加到 kunit_bus 的 struct device_driver

参数

struct kunit *test: 测试上下文对象。
const char *name: 为创建的驱动程序指定的名称。

描述

创建一个附加到 kunit_bus 的 struct device_driver，名称为 name。此驱动程序将在测试退出时自动清理。

返回

一个由 KUnit 管理的桩 struct device_driver，名称为 name。

struct device *kunit_device_register(struct kunit *test, const char *name)¶: 创建一个 struct device 以在 KUnit 测试中使用

参数

struct kunit *test: 测试上下文对象。
const char *name: 为创建的设备指定的名称。

描述

创建一个具有给定名称的 struct kunit_device（它是 struct device）和一个相应的驱动程序。设备和驱动程序将在测试退出时或调用 kunit_device_unregister 时清理。如果您希望提供自己的 struct device_driver，另请参阅 kunit_device_register_with_driver。

返回

指向 struct device 的指针，该指针将在测试退出时清理，或者如果无法分配或注册设备，则返回错误指针。

struct device *kunit_device_register_with_driver(struct kunit *test, const char *name, const struct device_driver *drv)¶: 创建一个 struct device 以在 KUnit 测试中使用

参数

struct kunit *test: 测试上下文对象。
const char *name: 为创建的设备指定的名称。
const struct device_driver *drv: 与设备关联的 struct device_driver。

描述

创建一个 struct kunit_device (它是一个 struct device) ，具有给定的名称和驱动程序。设备将在测试退出时或调用 kunit_device_unregister 时清理。另请参见 kunit_device_register，如果您希望 KUnit 为您创建和管理驱动程序。

返回

指向 struct device 的指针，该指针将在测试退出时清理，或者如果无法分配或注册设备，则返回错误指针。

void kunit_device_unregister(struct kunit *test, struct device *dev)¶: 注销 KUnit 管理的设备

参数

struct kunit *test: 创建设备的测试上下文对象
struct device *dev: 设备。

描述

注销并销毁使用 kunit_device_register 或 kunit_device_register_with_driver 创建的 struct device。如果 KUnit 创建了一个驱动程序，也会清理它。

Linux 内核

目录

本页

Resource API¶

托管设备¶