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¶

託管裝置¶