Documentation/translations/zh_CN/dev-tools/kcsan.rst

Source file repositories/reference/linux-study-clean/Documentation/translations/zh_CN/dev-tools/kcsan.rst

File Facts

System
Linux kernel
Corpus path
Documentation/translations/zh_CN/dev-tools/kcsan.rst
Extension
.rst
Size
16001 bytes
Lines
321
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct foo {
        ...
        int __data_racy stats_counter;
        ...
    };

* 使用函数属性 ``__no_kcsan`` 可以对整个函数禁用数据竞争检测::

    __no_kcsan
    void foo(void) {
        ...

  为了动态限制该为哪些函数生成报告，查阅 `Debug 文件系统接口`_ 黑名单/白名单特性。

* 为特定的编译单元禁用数据竞争检测，将下列参数加入到 ``Makefile`` 中::

    KCSAN_SANITIZE_file.o := n

* 为 ``Makefile`` 中的所有编译单元禁用数据竞争检测，将下列参数添加到相应的
  ``Makefile`` 中::

    KCSAN_SANITIZE := n

.. _在 LKMM 中 "标记共享内存访问": https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/memory-model/Documentation/access-marking.txt

此外，KCSAN 可以根据偏好设置显示或隐藏整个类别的数据竞争。可以使用如下
Kconfig 参数进行更改:

* ``CONFIG_KCSAN_REPORT_VALUE_CHANGE_ONLY``: 如果启用了该参数并且通过观测点
  (watchpoint) 观测到一个有冲突的写操作，但是对应的内存地址中存储的值没有改变，
  则不会报告这起数据竞争。

* ``CONFIG_KCSAN_ASSUME_PLAIN_WRITES_ATOMIC``: 假设默认情况下，不超过字大小的简
  单对齐写入操作是原子的。假设这些写入操作不会受到不安全的编译器优化影响，从而导
  致数据竞争。该选项使 KCSAN 不报告仅由不超过字大小的简单对齐写入操作引起
  的冲突所导致的数据竞争。

* ``CONFIG_KCSAN_PERMISSIVE``: 启用额外的宽松规则来忽略某些常见类型的数据竞争。
  与上面的规则不同，这条规则更加复杂，涉及到值改变模式，访问类型和地址。这个
  选项依赖编译选项 ``CONFIG_KCSAN_REPORT_VALUE_CHANGE_ONLY=y``。请查看
  ``kernel/kcsan/permissive.h`` 获取更多细节。对于只侧重于特定子系统而不是整个
  内核报告的测试者和维护者，建议禁用该选项。

要使用尽可能严格的规则，选择 ``CONFIG_KCSAN_STRICT=y``，这将配置 KCSAN 尽可
能紧密地遵循 Linux 内核内存一致性模型（LKMM）。

Debug 文件系统接口
~~~~~~~~~~~~~~~~~~

文件 ``/sys/kernel/debug/kcsan`` 提供了如下接口：

* 读 ``/sys/kernel/debug/kcsan`` 返回不同的运行时统计数据。

* 将 ``on`` 或 ``off`` 写入 ``/sys/kernel/debug/kcsan`` 允许打开或关闭 KCSAN。

* 将 ``!some_func_name`` 写入 ``/sys/kernel/debug/kcsan`` 会将
  ``some_func_name`` 添加到报告过滤列表中，该列表（默认）会将数据竞争报告中的顶
  层堆栈帧是列表中函数的情况列入黑名单。

* 将 ``blacklist`` 或 ``whitelist`` 写入 ``/sys/kernel/debug/kcsan`` 会改变报告
  过滤行为。例如，黑名单的特性可以用来过滤掉经常发生的数据竞争。白名单特性可以帮
  助复现和修复测试。

性能调优
~~~~~~~~

影响 KCSAN 整体的性能和 bug 检测能力的核心参数是作为内核命令行参数公开的，其默认
值也可以通过相应的 Kconfig 选项更改。

* ``kcsan.skip_watch`` (``CONFIG_KCSAN_SKIP_WATCH``): 在另一个观测点设置之前每

Annotation

Implementation Notes