尧图网站建设 
Linux 内核基于作用域的清理助手Scope-based Cleanup Helpers完整指南【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linux本文是 Linux 内核源码树本仓库中 Documentation/core-api/cleanup.rst 文档的深度技术解读。该文档的正文由kernel-doc直接引用 include/linux/cleanup.h 中的DOC: scope-based cleanup helpers注释块生成因此本文以该头文件为核心骨架结合仓库中DEFINE_FREE()、DEFINE_GUARD()等宏的真实定义与 PCI、mutex、spinlock 等子系统中的实际用法展开。读完本文你将掌握用编译器辅助的__free()、guard()、scoped_guard()、ACQUIRE()等机制消灭传统 goto error 样板代码写出自动、按 LIFO 顺序清理资源且不易泄漏的内核代码。一、为什么需要 cleanup helpersgoto error 模式的痛点在引入这些宏之前内核代码处理多资源、多退出条件的经典方式是 goto error 模式。该模式为人诟病已久每当在已经包含若干 unwind 条件的代码路径中新增一个资源获取约束都需要小心翼翼地补上对应的释放语句过程繁琐且极易出错是资源泄漏的温床。cleanup.h中提供的 cleanup helpers 的核心思想是让编译器替开发者完成这些繁琐工作借助 GCC/Clang 的__attribute__((__cleanup__(...)))机制为自动变量注册一个离开作用域时自动执行的清理函数。同时由于清理函数的执行顺序严格遵循变量定义顺序的逆序LIFO它还能帮助维护正确的后进先出last in first out解卷顺序避免误释放或乱序释放导致的隐患。这些宏定义全部位于 include/linux/cleanup.h分为两大家族资源指针家族DEFINE_FREE()__free()负责在变量出作用域时自动释放资源如pci_dev_put()、kfree()锁/类家族DEFINE_CLASS()/DEFINE_GUARD()guard()、scoped_guard()、ACQUIRE()负责在作用域结束时自动解锁或调用析构函数。二、DEFINE_FREE 与 __free变量的自动资源释放2.1 基本用法DEFINE_FREE()用于为一个类型定义一个离开作用域即释放的包装函数__free()则把这个清理函数以变量属性的方式挂到具体变量上。以文档中的 PCI 驱动场景为例目标是把那些在返回前用 goto 跳转去调用pci_dev_put()释放设备引用、或用pci_dev_unlock()解锁的代码自动化DEFINE_FREE(pci_dev_put, struct pci_dev *, if (_T) pci_dev_put(_T)) ... struct pci_dev *dev __free(pci_dev_put) pci_get_slot(parent, PCI_DEVFN(0, 0));当dev离开其自动变量作用域时若其值非 NULLpci_dev_put()会被自动调用。这条宏定义在仓库中的真实位置是 include/linux/pci.hDEFINE_FREE(pci_dev_put, struct pci_dev *, if (_T) pci_dev_put(_T))DEFINE_FREE的宏签名与语义如下见 include/linux/cleanup.h#define DEFINE_FREE(_name, _type, _free) \ static __always_inline void __free_##_name(void *p) { _type _T *(_type *)p; _free; } #define __free(_name) __cleanup(__free_##_name)_name清理函数的名字后缀最终生成__free_##_name_type被管理变量的类型_free一段表达式通过占位符_T访问变量值通常应包含 NULL 判断再调用释放函数__free(_name)展开为__cleanup(__free_##_name)即 GCC 的 cleanup 属性把清理函数绑定到变量上。2.2 no_free_ptr 与 return_ptr成功时交出资源如果函数在出错时要自动调用pci_dev_put()但在成功时却要把dev返回给调用方即不释放则必须显式地剥夺变量的清理职责。文档给出两种等价写法return no_free_ptr(dev); // 等价于 return_ptr(dev);no_free_ptr(var)的语义是类似非原子的xchg(var, NULL)把变量置 NULL 从而抑制清理函数——前提是清理函数能妥善处理 NULL 值这也是上文强调_free必须带 NULL 判断的原因。其实现见 include/linux/cleanup.h值得注意的两点它带__must_check语义通过__must_check_fn强制目的是防止开发者捡了芝麻丢西瓜——比如写了no_free_ptr(p)却忘记用它的返回值导致资源既被交出又被清理造成双重释放隐患return_ptr(p)只是return no_free_ptr(p)的简写糖。2.3 关于 NULL 判断与死代码消除的编译器魔法文档特别用kfree举例解释为什么_free表达式必须带 NULL 测试即使kfree(NULL)本身是安全的DEFINE_FREE(kfree, void *, if (_T) kfree(_T)) void *alloc_obj(...) { struct obj *p __free(kfree) kmalloc(...); if (!p) return NULL; if (!init_obj(p)) return NULL; return_ptr(p); }带上 NULL 判断后编译器眼中这个函数的结尾变成tmp p; p NULL; if (p) kfree(p); return tmp;经过值传播value-propagation与死代码消除dead-code-elimination实际编译结果是return p;清理调用被完全优化掉。而如果去掉 NULL 判断编译器就无法做这种优化生成一堆看起来是清理、实际用不上的冗余代码。2.4 retain_and_null_ptr把资源移交给其他函数与no_free_ptr()类似的还有 include/linux/cleanup.h 中的retain_and_null_ptr(p)它专门用于分配的资源在成功路径上被交给另一个函数消费的场景。典型模式struct foo *f __free(kfree) kzalloc(sizeof(*f), GFP_KERNEL); setup(f); if (some_condition) return -EINVAL; ... ret bar(f); if (!ret) retain_and_null_ptr(f); // 移交成功f 被置 NULL return ret;调用retain_and_null_ptr(f)之后f已为 NULL不可再被解引用从而避免bar()消费资源后、作用域结束时又被__free二次释放。2.5 仓库中的真实用例在 drivers/pci/pci.c 中有struct pci_dev *child __free(pci_dev_put) NULL;drivers/pci/tsm.c 中则在循环里配合pci_get_slot()使用struct pci_dev *pf __free(pci_dev_put) pci_get_slot(...); ... struct pci_dev *vf __free(pci_dev_put) ...drivers/pci/hotplug/pciehp_hpc.c 同样是struct pci_dev *pdev __free(pci_dev_put) NULL;的用法。这些代码点共同印证了文档中的说法驱动是内核代码库的大头而 PCI 子系统正是__free()最早、最典型的落地场景之一。三、DEFINE_CLASS 与 CLASS类型级的构造/析构封装DEFINE_FREE只处理出作用域时释放这一件事DEFINE_CLASS更进一步同时定义类型的构造器与析构器include/linux/cleanup.hDEFINE_CLASS(name, type, exit, init, init_args...): 为类型定义析构与构造函数。 exit 是一个使用 _T 的表达式类似 DEFINE_FREE 的 free。 init 是使用 init_args 计算得到 type 的表达式。 EXTEND_CLASS(name, ext, init, init_args...): 在类 name 基础上扩展出新类 nameext并给出新构造器。 CLASS(name, var)(args...): 声明变量 var 为该命名类的一个实例自动调用构造函数。 CLASS_INIT(name, var, init_expr): 声明变量 var 为该命名类的一个实例但使用自定义初始化表达式。文档给出的经典示例是对struct fd的封装DEFINE_CLASS(fdget, struct fd, fdput(_T), fdget(fd), int fd) CLASS(fdget, f)(fd); if (fd_empty(f)) return -EBADF; // 放心使用 f出作用域自动 fdput()CLASS(fdget, f)(fd)展开后等价于用fdget(fd)初始化变量f并挂上fdput析构器。EXTEND_CLASS与EXTEND_CLASS_COND后者多一个条件参数条件为真时跳过析构则用于在基类上派生变体这正是下文条件锁的实现基础。四、DEFINE_GUARD 与 guard锁的作用域化4.1 基本用法DEFINE_GUARD()是DEFINE_CLASS()针对锁的专用薄封装include/linux/cleanup.hDEFINE_GUARD(name, type, lock, unlock): 定义进入作用域上锁、出作用域解锁的守卫类。 guard(name): 该守卫类的一个匿名实例对条件锁不推荐使用。 scoped_guard(name, args...) { }: 与 CLASS(name, scope)(args) 类似区别在于变量固定名为 scope被声明在 for 循环中其作用域被绑定到紧随其后的 复合语句。对条件锁而言当锁获取失败时循环体被跳过。 scoped_cond_guard(name, fail, args...) { }: 与 scoped_guard() 类似区别在于锁获取失败时会执行 fail。 仅适用于条件锁。 ACQUIRE(name, var): 守卫类的一个命名实例适合配合 ACQUIRE_ERR() 用于条件锁。 ACQUIRE_ERR(name, var): 本质上是对守卫指针做 PTR_ERR() 式转换的辅助宏 锁获取成功返回 0否则返回负错误码。文档以 PCI 设备锁为例DEFINE_GUARD(pci_dev, struct pci_dev *, pci_dev_lock(_T), pci_dev_unlock(_T)) ... guard(pci_dev)(dev);这条定义位于 include/linux/pci.h与上文DEFINE_FREE(pci_dev_put, ...)正好组成 PCI 子系统的释放 解锁双件套。4.2 guard 的生命周期跟随声明所在的作用域guard()获得的锁其生命周期跟随自动变量声明所在的作用域而不是整个函数。文档用嵌套块示例说明func(...) { if (...) { ... guard(pci_dev)(dev); // 此处调用 pci_dev_lock() ... } // - 此处隐式触发 pci_dev_unlock() }观察锁只在整个if ()块内持有而不是func()的剩余部分。这与传统的函数开头加锁、函数末尾解锁完全不同是作用域化清理的核心收益——锁的粒度精确到代码块出错概率显著下降。4.3 条件锁DEFINE_GUARD_COND 与 ACQUIRE/ACQUIRE_ERRguard()面向必然成功的非条件锁对于trylock、lock_interruptible这类可能失败的条件锁需要用DEFINE_GUARD_COND()派生条件变体再用ACQUIRE()ACQUIRE_ERR()显式处理失败DEFINE_GUARD_COND(pci_dev, _try, pci_dev_trylock(_T)) ... ACQUIRE(pci_dev_try, lock)(dev); rc ACQUIRE_ERR(pci_dev_try, lock); if (rc) return rc; // 走到这里说明 lock 已被持有ACQUIRE_ERR()的实现见 include/linux/cleanup.h会把守卫指针转为错误码成功返回 0失败返回负的 errno如-EBUSY。其内部通过__DEFINE_GUARD_LOCK_PTR生成的class_##_name##_lock_ptr/class_##_name##_lock_err两个辅助函数工作。4.4 scoped_guard 与 scoped_cond_guardscoped_guard()用for循环技巧把锁的作用域精确限制在紧随其后的复合语句内include/linux/cleanup.hscoped_guard(mutex, lock) { // 临界区进入即持锁出花括号自动解锁 }其实现要点是循环条件__guard_ptr(_name)(scope) || !__is_cond_ptr(_name)——对非条件锁即使编译器无法证明指针非空也会因!__is_cond_ptr恒为真而保证循环体即临界区必然执行对条件锁则依赖__guard_ptr判定是否真的拿到了锁拿不到就跳过循环体。scoped_cond_guard()则不同它面向条件锁获取失败时执行_fail语句并break且用BUILD_BUG_ON(!__is_cond_ptr(_name))在编译期强制只能用于条件锁scoped_cond_guard(mutex_intr, return -EINTR, lock) { // 只有成功持有锁才会执行到这里 }五、DEFINE_LOCK_GUARD为无类型锁与 fat pointer 锁定制守卫前文DEFINE_GUARD要求锁本身有可赋值的类型。但内核里还有两类特殊锁include/linux/cleanup.h没有原生类型的锁如 RCU、preempt 禁用以外的概念性锁需要 fat pointer 的锁如spin_lock_irqsave()解锁时除了锁指针还要恢复 flags。为此提供了DEFINE_LOCK_GUARD_0/DEFINE_LOCK_GUARD_1/DEFINE_LOCK_GUARD_1_COND。它们会生成如下结构体类型typedef struct { type *lock; // _0 变体中 type 为 void __VA_ARGS__; // 额外的状态字段如 irqsave 的 flags } class_##name##_t;_lock与_unlock都是语句且此时_T是指向上述结构体的指针。以spin_lock_irqsave为例仓库 include/linux/spinlock.h 中的定义DEFINE_LOCK_GUARD_1(spinlock_irqsave, spinlock_t, spin_lock_irqsave(_T-lock, _T-flags), spin_unlock_irqrestore(_T-lock, _T-flags), unsigned long flags)flags作为额外的结构体字段被保存出作用域时spin_unlock_irqrestore()能拿到正确的中断状态——这正是fat pointer方案的用途。同一头文件还定义了spinlock、spinlock_irq、spinlock_bh、spinlock_init以及各自的_try条件变体include/linux/spinlock.h。mutex 家族则位于 include/linux/mutex.hDEFINE_LOCK_GUARD_1(mutex, struct mutex, mutex_lock(_T-lock), mutex_unlock(_T-lock)) DEFINE_LOCK_GUARD_1_COND(mutex, _try, mutex_trylock(_T-lock)) DEFINE_LOCK_GUARD_1_COND(mutex, _intr, mutex_lock_interruptible(_T-lock), _RET 0) DEFINE_LOCK_GUARD_1_COND(mutex, _kill, mutex_lock_killable(_T-lock), _RET 0)注意_intr/_kill变体比_try多一个条件参数_RET 0mutex_lock_interruptible()返回 0 才算成功其余返回负 errno 视为失败——这就是DEFINE_GUARD_COND_4中默认二元条件为成功与自定义条件两种形态的区分include/linux/cleanup.h。仓库中的实际调用随处可见例如 drivers/opp/core.c 与 drivers/opp/of.c 中的scoped_guard(mutex, opp_table-lock) { ... }以及 drivers/i2c/busses/i2c-gpio.c 的scoped_guard(mutex, i2c_gpio_scl_list_lock) { ... }均以块级作用域替代了手写的 lock/unlock 配对。另外针对内核的 Context Analysis__acquires/__releases稀疏注解支持include/linux/cleanup.h 还提供了DECLARE_LOCK_GUARD_1_ATTRS与WITH_LOCK_GUARD_1_ATTRS前者声明带_lock/_unlock属性的构造/析构后者在构造时额外创建一个用__cleanup挂上空壳清理函数的别名变量让编译器在不做跨过程分析的情况下也能看到作用域结束时的释放语义。六、LIFO 清理顺序与经典陷阱6.1 GCC 的保证当一个作用域内多个变量都带 cleanup 属性时执行顺序由编译器保证。文档原文引用 GCC 文档When multiple variables in the same scope have cleanup attributes, at exit from the scope their associated cleanup functions are run in reverse order of definition (last defined, first cleanup).即定义顺序的逆序执行清理后定义的先清理。当解卷顺序很重要时就必须把变量声明放在函数中途的作用域里而不是全部堆在函数顶部。6.2 一个真实的反面教材文档给出了一个含 bug 的示例函数同时使用__free(remove_free)与guard(mutex)但变量在函数顶部就位、锁在其后才获取LIST_HEAD(list); DEFINE_MUTEX(lock); struct object { struct list_head node; }; static struct object *alloc_add(void) { struct object *obj; lockdep_assert_held(lock); obj kzalloc(sizeof(*obj), GFP_KERNEL); if (obj) { LIST_HEAD_INIT(obj-node); list_add(obj-node, list); } return obj; } static void remove_free(struct object *obj) { lockdep_assert_held(lock); list_del(obj-node); kfree(obj); } DEFINE_FREE(remove_free, struct object *, if (_T) remove_free(_T)) static int init(void) { struct object *obj __free(remove_free) NULL; int err; guard(mutex)(lock); // 锁在 obj 之后获取 obj alloc_add(); if (!obj) return -ENOMEM; err other_init(obj); if (err) return err; // 出作用域时 remove_free() 在无锁状态下被调用 no_free_ptr(obj); return 0; }obj先定义、guard(mutex)后定义按 LIFO 规则出作用域时先执行remove_free()obj 的清理再解锁——于是remove_free()里的list_del()在锁被释放之后才执行lockdep_assert_held(lock)会直接报警。6.3 修复就地定义并赋值修复方法是把guard()与obj的定义 初始化按正确的先后顺序排列guard(mutex)(lock); struct object *obj __free(remove_free) alloc_add();这样一来出作用域时先解锁guard 后定义先清理、再执行remove_free()顺序正确。由此文档给出两条硬性建议不要用__free(...) NULL这种函数顶部先占位、后面再赋值的写法——它天然制造上述依赖顺序问题只要用了__free()就应该把变量的定义与赋值合并为一条语句就地声明在需要使用它的作用域中。七、使用边界不要在同一函数中混用 goto 与 cleanup helpers文档最后给出一个重要的工程约定既然使用 cleanup helpers 的初衷就是消灭 goto而goto本身可以跨作用域跳转会破坏 cleanup 属性严格的作用域语义那么在同一个函数里绝不要混用 goto 与 cleanup helpers。对于某个例程要么把所有需要 goto 清理的资源全部改为基于作用域的清理要么一个都不改。这条约定保证了代码风格的一致性也避免了部分资源自动清理、部分资源 goto 手动清理这种割裂且容易出错的状态。八、总结与阅读指引Scope-based Cleanup Helpers 是内核在资源管理上的一次系统性改进DEFINE_FREE/__free负责指针型资源的自动释放DEFINE_GUARD/guard/scoped_guard/ACQUIRE负责锁的块级获取与释放DEFINE_LOCK_GUARD_0/1则补齐了 RCU、preempt 与spin_lock_irqsave这类特殊锁的支持DECLARE_LOCK_GUARD_1_ATTRS等宏进一步让这些写法与稀疏的 Context Analysis 兼容。建议的继续阅读路径核心宏定义全文include/linux/cleanup.hPCI 子系统的配对定义include/linux/pci.h、include/linux/pci.hPCI 实际使用drivers/pci/pci.c、drivers/pci/tsm.c、drivers/pci/hotplug/pciehp_hpc.cmutex / spinlock 守卫家族include/linux/mutex.h、include/linux/spinlock.hscoped_guard(mutex, ...)的驱动侧应用drivers/opp/core.c、drivers/i2c/busses/i2c-gpio.c写内核驱动或内核子系统代码时优先用这些助手替换手写的 goto 清理与 lock/unlock 配对能让代码更短、更安全也让 lockdep、稀疏等静态检查工具更容易替你守住资源与锁的正确性。【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linux创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Linux 内核基于作用域的清理助手（Scope-based Cleanup Helpers）完整指南
Linux 内核基于作用域的清理助手Scope-based Cleanup Helpers完整指南【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linux本文是 Linux 内核源码树本仓库中 Documentation/core-api/cleanup.rst 文档的深度技术解读。该文档的正文由kernel-doc直接引用 include/linux/cleanup.h 中的DOC: scope-based cleanup helpers注释块生成因此本文以该头文件为核心骨架结合仓库中DEFINE_FREE()、DEFINE_GUARD()等宏的真实定义与 PCI、mutex、spinlock 等子系统中的实际用法展开。读完本文你将掌握用编译器辅助的__free()、guard()、scoped_guard()、ACQUIRE()等机制消灭传统 goto error 样板代码写出自动、按 LIFO 顺序清理资源且不易泄漏的内核代码。一、为什么需要 cleanup helpersgoto error 模式的痛点在引入这些宏之前内核代码处理多资源、多退出条件的经典方式是 goto error 模式。该模式为人诟病已久每当在已经包含若干 unwind 条件的代码路径中新增一个资源获取约束都需要小心翼翼地补上对应的释放语句过程繁琐且极易出错是资源泄漏的温床。cleanup.h中提供的 cleanup helpers 的核心思想是让编译器替开发者完成这些繁琐工作借助 GCC/Clang 的__attribute__((__cleanup__(...)))机制为自动变量注册一个离开作用域时自动执行的清理函数。同时由于清理函数的执行顺序严格遵循变量定义顺序的逆序LIFO它还能帮助维护正确的后进先出last in first out解卷顺序避免误释放或乱序释放导致的隐患。这些宏定义全部位于 include/linux/cleanup.h分为两大家族资源指针家族DEFINE_FREE()__free()负责在变量出作用域时自动释放资源如pci_dev_put()、kfree()锁/类家族DEFINE_CLASS()/DEFINE_GUARD()guard()、scoped_guard()、ACQUIRE()负责在作用域结束时自动解锁或调用析构函数。二、DEFINE_FREE 与 __free变量的自动资源释放2.1 基本用法DEFINE_FREE()用于为一个类型定义一个离开作用域即释放的包装函数__free()则把这个清理函数以变量属性的方式挂到具体变量上。以文档中的 PCI 驱动场景为例目标是把那些在返回前用 goto 跳转去调用pci_dev_put()释放设备引用、或用pci_dev_unlock()解锁的代码自动化DEFINE_FREE(pci_dev_put, struct pci_dev *, if (_T) pci_dev_put(_T)) ... struct pci_dev *dev __free(pci_dev_put) pci_get_slot(parent, PCI_DEVFN(0, 0));当dev离开其自动变量作用域时若其值非 NULLpci_dev_put()会被自动调用。这条宏定义在仓库中的真实位置是 include/linux/pci.hDEFINE_FREE(pci_dev_put, struct pci_dev *, if (_T) pci_dev_put(_T))DEFINE_FREE的宏签名与语义如下见 include/linux/cleanup.h#define DEFINE_FREE(_name, _type, _free) \ static __always_inline void __free_##_name(void *p) { _type _T *(_type *)p; _free; } #define __free(_name) __cleanup(__free_##_name)_name清理函数的名字后缀最终生成__free_##_name_type被管理变量的类型_free一段表达式通过占位符_T访问变量值通常应包含 NULL 判断再调用释放函数__free(_name)展开为__cleanup(__free_##_name)即 GCC 的 cleanup 属性把清理函数绑定到变量上。2.2 no_free_ptr 与 return_ptr成功时交出资源如果函数在出错时要自动调用pci_dev_put()但在成功时却要把dev返回给调用方即不释放则必须显式地剥夺变量的清理职责。文档给出两种等价写法return no_free_ptr(dev); // 等价于 return_ptr(dev);no_free_ptr(var)的语义是类似非原子的xchg(var, NULL)把变量置 NULL 从而抑制清理函数——前提是清理函数能妥善处理 NULL 值这也是上文强调_free必须带 NULL 判断的原因。其实现见 include/linux/cleanup.h值得注意的两点它带__must_check语义通过__must_check_fn强制目的是防止开发者捡了芝麻丢西瓜——比如写了no_free_ptr(p)却忘记用它的返回值导致资源既被交出又被清理造成双重释放隐患return_ptr(p)只是return no_free_ptr(p)的简写糖。2.3 关于 NULL 判断与死代码消除的编译器魔法文档特别用kfree举例解释为什么_free表达式必须带 NULL 测试即使kfree(NULL)本身是安全的DEFINE_FREE(kfree, void *, if (_T) kfree(_T)) void *alloc_obj(...) { struct obj *p __free(kfree) kmalloc(...); if (!p) return NULL; if (!init_obj(p)) return NULL; return_ptr(p); }带上 NULL 判断后编译器眼中这个函数的结尾变成tmp p; p NULL; if (p) kfree(p); return tmp;经过值传播value-propagation与死代码消除dead-code-elimination实际编译结果是return p;清理调用被完全优化掉。而如果去掉 NULL 判断编译器就无法做这种优化生成一堆看起来是清理、实际用不上的冗余代码。2.4 retain_and_null_ptr把资源移交给其他函数与no_free_ptr()类似的还有 include/linux/cleanup.h 中的retain_and_null_ptr(p)它专门用于分配的资源在成功路径上被交给另一个函数消费的场景。典型模式struct foo *f __free(kfree) kzalloc(sizeof(*f), GFP_KERNEL); setup(f); if (some_condition) return -EINVAL; ... ret bar(f); if (!ret) retain_and_null_ptr(f); // 移交成功f 被置 NULL return ret;调用retain_and_null_ptr(f)之后f已为 NULL不可再被解引用从而避免bar()消费资源后、作用域结束时又被__free二次释放。2.5 仓库中的真实用例在 drivers/pci/pci.c 中有struct pci_dev *child __free(pci_dev_put) NULL;drivers/pci/tsm.c 中则在循环里配合pci_get_slot()使用struct pci_dev *pf __free(pci_dev_put) pci_get_slot(...); ... struct pci_dev *vf __free(pci_dev_put) ...drivers/pci/hotplug/pciehp_hpc.c 同样是struct pci_dev *pdev __free(pci_dev_put) NULL;的用法。这些代码点共同印证了文档中的说法驱动是内核代码库的大头而 PCI 子系统正是__free()最早、最典型的落地场景之一。三、DEFINE_CLASS 与 CLASS类型级的构造/析构封装DEFINE_FREE只处理出作用域时释放这一件事DEFINE_CLASS更进一步同时定义类型的构造器与析构器include/linux/cleanup.hDEFINE_CLASS(name, type, exit, init, init_args...): 为类型定义析构与构造函数。 exit 是一个使用 _T 的表达式类似 DEFINE_FREE 的 free。 init 是使用 init_args 计算得到 type 的表达式。 EXTEND_CLASS(name, ext, init, init_args...): 在类 name 基础上扩展出新类 nameext并给出新构造器。 CLASS(name, var)(args...): 声明变量 var 为该命名类的一个实例自动调用构造函数。 CLASS_INIT(name, var, init_expr): 声明变量 var 为该命名类的一个实例但使用自定义初始化表达式。文档给出的经典示例是对struct fd的封装DEFINE_CLASS(fdget, struct fd, fdput(_T), fdget(fd), int fd) CLASS(fdget, f)(fd); if (fd_empty(f)) return -EBADF; // 放心使用 f出作用域自动 fdput()CLASS(fdget, f)(fd)展开后等价于用fdget(fd)初始化变量f并挂上fdput析构器。EXTEND_CLASS与EXTEND_CLASS_COND后者多一个条件参数条件为真时跳过析构则用于在基类上派生变体这正是下文条件锁的实现基础。四、DEFINE_GUARD 与 guard锁的作用域化4.1 基本用法DEFINE_GUARD()是DEFINE_CLASS()针对锁的专用薄封装include/linux/cleanup.hDEFINE_GUARD(name, type, lock, unlock): 定义进入作用域上锁、出作用域解锁的守卫类。 guard(name): 该守卫类的一个匿名实例对条件锁不推荐使用。 scoped_guard(name, args...) { }: 与 CLASS(name, scope)(args) 类似区别在于变量固定名为 scope被声明在 for 循环中其作用域被绑定到紧随其后的 复合语句。对条件锁而言当锁获取失败时循环体被跳过。 scoped_cond_guard(name, fail, args...) { }: 与 scoped_guard() 类似区别在于锁获取失败时会执行 fail。 仅适用于条件锁。 ACQUIRE(name, var): 守卫类的一个命名实例适合配合 ACQUIRE_ERR() 用于条件锁。 ACQUIRE_ERR(name, var): 本质上是对守卫指针做 PTR_ERR() 式转换的辅助宏 锁获取成功返回 0否则返回负错误码。文档以 PCI 设备锁为例DEFINE_GUARD(pci_dev, struct pci_dev *, pci_dev_lock(_T), pci_dev_unlock(_T)) ... guard(pci_dev)(dev);这条定义位于 include/linux/pci.h与上文DEFINE_FREE(pci_dev_put, ...)正好组成 PCI 子系统的释放 解锁双件套。4.2 guard 的生命周期跟随声明所在的作用域guard()获得的锁其生命周期跟随自动变量声明所在的作用域而不是整个函数。文档用嵌套块示例说明func(...) { if (...) { ... guard(pci_dev)(dev); // 此处调用 pci_dev_lock() ... } // - 此处隐式触发 pci_dev_unlock() }观察锁只在整个if ()块内持有而不是func()的剩余部分。这与传统的函数开头加锁、函数末尾解锁完全不同是作用域化清理的核心收益——锁的粒度精确到代码块出错概率显著下降。4.3 条件锁DEFINE_GUARD_COND 与 ACQUIRE/ACQUIRE_ERRguard()面向必然成功的非条件锁对于trylock、lock_interruptible这类可能失败的条件锁需要用DEFINE_GUARD_COND()派生条件变体再用ACQUIRE()ACQUIRE_ERR()显式处理失败DEFINE_GUARD_COND(pci_dev, _try, pci_dev_trylock(_T)) ... ACQUIRE(pci_dev_try, lock)(dev); rc ACQUIRE_ERR(pci_dev_try, lock); if (rc) return rc; // 走到这里说明 lock 已被持有ACQUIRE_ERR()的实现见 include/linux/cleanup.h会把守卫指针转为错误码成功返回 0失败返回负的 errno如-EBUSY。其内部通过__DEFINE_GUARD_LOCK_PTR生成的class_##_name##_lock_ptr/class_##_name##_lock_err两个辅助函数工作。4.4 scoped_guard 与 scoped_cond_guardscoped_guard()用for循环技巧把锁的作用域精确限制在紧随其后的复合语句内include/linux/cleanup.hscoped_guard(mutex, lock) { // 临界区进入即持锁出花括号自动解锁 }其实现要点是循环条件__guard_ptr(_name)(scope) || !__is_cond_ptr(_name)——对非条件锁即使编译器无法证明指针非空也会因!__is_cond_ptr恒为真而保证循环体即临界区必然执行对条件锁则依赖__guard_ptr判定是否真的拿到了锁拿不到就跳过循环体。scoped_cond_guard()则不同它面向条件锁获取失败时执行_fail语句并break且用BUILD_BUG_ON(!__is_cond_ptr(_name))在编译期强制只能用于条件锁scoped_cond_guard(mutex_intr, return -EINTR, lock) { // 只有成功持有锁才会执行到这里 }五、DEFINE_LOCK_GUARD为无类型锁与 fat pointer 锁定制守卫前文DEFINE_GUARD要求锁本身有可赋值的类型。但内核里还有两类特殊锁include/linux/cleanup.h没有原生类型的锁如 RCU、preempt 禁用以外的概念性锁需要 fat pointer 的锁如spin_lock_irqsave()解锁时除了锁指针还要恢复 flags。为此提供了DEFINE_LOCK_GUARD_0/DEFINE_LOCK_GUARD_1/DEFINE_LOCK_GUARD_1_COND。它们会生成如下结构体类型typedef struct { type *lock; // _0 变体中 type 为 void __VA_ARGS__; // 额外的状态字段如 irqsave 的 flags } class_##name##_t;_lock与_unlock都是语句且此时_T是指向上述结构体的指针。以spin_lock_irqsave为例仓库 include/linux/spinlock.h 中的定义DEFINE_LOCK_GUARD_1(spinlock_irqsave, spinlock_t, spin_lock_irqsave(_T-lock, _T-flags), spin_unlock_irqrestore(_T-lock, _T-flags), unsigned long flags)flags作为额外的结构体字段被保存出作用域时spin_unlock_irqrestore()能拿到正确的中断状态——这正是fat pointer方案的用途。同一头文件还定义了spinlock、spinlock_irq、spinlock_bh、spinlock_init以及各自的_try条件变体include/linux/spinlock.h。mutex 家族则位于 include/linux/mutex.hDEFINE_LOCK_GUARD_1(mutex, struct mutex, mutex_lock(_T-lock), mutex_unlock(_T-lock)) DEFINE_LOCK_GUARD_1_COND(mutex, _try, mutex_trylock(_T-lock)) DEFINE_LOCK_GUARD_1_COND(mutex, _intr, mutex_lock_interruptible(_T-lock), _RET 0) DEFINE_LOCK_GUARD_1_COND(mutex, _kill, mutex_lock_killable(_T-lock), _RET 0)注意_intr/_kill变体比_try多一个条件参数_RET 0mutex_lock_interruptible()返回 0 才算成功其余返回负 errno 视为失败——这就是DEFINE_GUARD_COND_4中默认二元条件为成功与自定义条件两种形态的区分include/linux/cleanup.h。仓库中的实际调用随处可见例如 drivers/opp/core.c 与 drivers/opp/of.c 中的scoped_guard(mutex, opp_table-lock) { ... }以及 drivers/i2c/busses/i2c-gpio.c 的scoped_guard(mutex, i2c_gpio_scl_list_lock) { ... }均以块级作用域替代了手写的 lock/unlock 配对。另外针对内核的 Context Analysis__acquires/__releases稀疏注解支持include/linux/cleanup.h 还提供了DECLARE_LOCK_GUARD_1_ATTRS与WITH_LOCK_GUARD_1_ATTRS前者声明带_lock/_unlock属性的构造/析构后者在构造时额外创建一个用__cleanup挂上空壳清理函数的别名变量让编译器在不做跨过程分析的情况下也能看到作用域结束时的释放语义。六、LIFO 清理顺序与经典陷阱6.1 GCC 的保证当一个作用域内多个变量都带 cleanup 属性时执行顺序由编译器保证。文档原文引用 GCC 文档When multiple variables in the same scope have cleanup attributes, at exit from the scope their associated cleanup functions are run in reverse order of definition (last defined, first cleanup).即定义顺序的逆序执行清理后定义的先清理。当解卷顺序很重要时就必须把变量声明放在函数中途的作用域里而不是全部堆在函数顶部。6.2 一个真实的反面教材文档给出了一个含 bug 的示例函数同时使用__free(remove_free)与guard(mutex)但变量在函数顶部就位、锁在其后才获取LIST_HEAD(list); DEFINE_MUTEX(lock); struct object { struct list_head node; }; static struct object *alloc_add(void) { struct object *obj; lockdep_assert_held(lock); obj kzalloc(sizeof(*obj), GFP_KERNEL); if (obj) { LIST_HEAD_INIT(obj-node); list_add(obj-node, list); } return obj; } static void remove_free(struct object *obj) { lockdep_assert_held(lock); list_del(obj-node); kfree(obj); } DEFINE_FREE(remove_free, struct object *, if (_T) remove_free(_T)) static int init(void) { struct object *obj __free(remove_free) NULL; int err; guard(mutex)(lock); // 锁在 obj 之后获取 obj alloc_add(); if (!obj) return -ENOMEM; err other_init(obj); if (err) return err; // 出作用域时 remove_free() 在无锁状态下被调用 no_free_ptr(obj); return 0; }obj先定义、guard(mutex)后定义按 LIFO 规则出作用域时先执行remove_free()obj 的清理再解锁——于是remove_free()里的list_del()在锁被释放之后才执行lockdep_assert_held(lock)会直接报警。6.3 修复就地定义并赋值修复方法是把guard()与obj的定义 初始化按正确的先后顺序排列guard(mutex)(lock); struct object *obj __free(remove_free) alloc_add();这样一来出作用域时先解锁guard 后定义先清理、再执行remove_free()顺序正确。由此文档给出两条硬性建议不要用__free(...) NULL这种函数顶部先占位、后面再赋值的写法——它天然制造上述依赖顺序问题只要用了__free()就应该把变量的定义与赋值合并为一条语句就地声明在需要使用它的作用域中。七、使用边界不要在同一函数中混用 goto 与 cleanup helpers文档最后给出一个重要的工程约定既然使用 cleanup helpers 的初衷就是消灭 goto而goto本身可以跨作用域跳转会破坏 cleanup 属性严格的作用域语义那么在同一个函数里绝不要混用 goto 与 cleanup helpers。对于某个例程要么把所有需要 goto 清理的资源全部改为基于作用域的清理要么一个都不改。这条约定保证了代码风格的一致性也避免了部分资源自动清理、部分资源 goto 手动清理这种割裂且容易出错的状态。八、总结与阅读指引Scope-based Cleanup Helpers 是内核在资源管理上的一次系统性改进DEFINE_FREE/__free负责指针型资源的自动释放DEFINE_GUARD/guard/scoped_guard/ACQUIRE负责锁的块级获取与释放DEFINE_LOCK_GUARD_0/1则补齐了 RCU、preempt 与spin_lock_irqsave这类特殊锁的支持DECLARE_LOCK_GUARD_1_ATTRS等宏进一步让这些写法与稀疏的 Context Analysis 兼容。建议的继续阅读路径核心宏定义全文include/linux/cleanup.hPCI 子系统的配对定义include/linux/pci.h、include/linux/pci.hPCI 实际使用drivers/pci/pci.c、drivers/pci/tsm.c、drivers/pci/hotplug/pciehp_hpc.cmutex / spinlock 守卫家族include/linux/mutex.h、include/linux/spinlock.hscoped_guard(mutex, ...)的驱动侧应用drivers/opp/core.c、drivers/i2c/busses/i2c-gpio.c写内核驱动或内核子系统代码时优先用这些助手替换手写的 goto 清理与 lock/unlock 配对能让代码更短、更安全也让 lockdep、稀疏等静态检查工具更容易替你守住资源与锁的正确性。【免费下载链接】linuxLinux kernel source tree项目地址: https://gitcode.com/GitHub_Trending/li/linux创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考