mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
synced 2026-08-31 09:20:13 -04:00
docs/zh_CN: Update rust/general-information.rst translation
Update Documentation/rust/general-information.rst translation.
Update the translation through commit 86c5d1c674
("docs: rust: general-information: use real example")
Reviewed-by: Gary Guo <gary@garyguo.net>
Reviewed-by: Dongliang Mu <dzm91@hust.edu.cn>
Signed-off-by: Ben Guo <ben.guo@openatom.club>
Signed-off-by: Alex Shi <alexs@kernel.org>
This commit is contained in:
@@ -13,6 +13,14 @@
|
||||
|
||||
本文档包含了在内核中使用Rust支持时需要了解的有用信息。
|
||||
|
||||
``no_std``
|
||||
----------
|
||||
|
||||
内核中的 Rust 支持只能链接 `core <https://doc.rust-lang.org/core/>`_,
|
||||
而不能链接 `std <https://doc.rust-lang.org/std/>`_。供内核使用的 crate
|
||||
必须使用 ``#![no_std]`` 属性选择这种行为。
|
||||
|
||||
|
||||
.. _rust_code_documentation_zh_cn:
|
||||
|
||||
代码文档
|
||||
@@ -20,10 +28,18 @@
|
||||
|
||||
Rust内核代码使用其内置的文档生成器 ``rustdoc`` 进行记录。
|
||||
|
||||
生成的HTML文档包括集成搜索、链接项(如类型、函数、常量)、源代码等。它们可以在以下地址阅读
|
||||
(TODO:当在主线中时链接,与其他文档一起生成):
|
||||
生成的 HTML 文档包括集成搜索、链接项(如类型、函数、常量)、源代码等。
|
||||
它们可以在以下地址阅读:
|
||||
|
||||
http://kernel.org/
|
||||
https://rust.docs.kernel.org
|
||||
|
||||
对于 linux-next,请参阅:
|
||||
|
||||
https://rust.docs.kernel.org/next/
|
||||
|
||||
每个主要版本也有对应的标签,例如:
|
||||
|
||||
https://rust.docs.kernel.org/6.10/
|
||||
|
||||
这些文档也可以很容易地在本地生成和阅读。这相当快(与编译代码本身的顺序相同),而且不需要特
|
||||
殊的工具或环境。这有一个额外的好处,那就是它们将根据所使用的特定内核配置进行定制。要生成它
|
||||
@@ -62,6 +78,58 @@ Rust内核代码使用其内置的文档生成器 ``rustdoc`` 进行记录。
|
||||
模块(例如,驱动程序)不应该直接使用C语言的绑定。相反,子系统应该根据需要提供尽可能安
|
||||
全的抽象。
|
||||
|
||||
.. code-block::
|
||||
|
||||
rust/bindings/
|
||||
(rust/helpers/)
|
||||
|
||||
include/ -----+ <-+
|
||||
| |
|
||||
drivers/ rust/kernel/ +----------+ <-+ |
|
||||
fs/ | bindgen | |
|
||||
.../ +-------------------+ +----------+ --+ |
|
||||
| Abstractions | | |
|
||||
+---------+ | +------+ +------+ | +----------+ | |
|
||||
| my_foo | -----> | | foo | | bar | | -------> | Bindings | <-+ |
|
||||
| driver | Safe | | sub- | | sub- | | Unsafe | | |
|
||||
+---------+ | |system| |system| | | bindings | <-----+
|
||||
| | +------+ +------+ | | crate | |
|
||||
| | kernel crate | +----------+ |
|
||||
| +-------------------+ |
|
||||
| |
|
||||
+------------------# FORBIDDEN #--------------------------------+
|
||||
|
||||
主要思想是将所有与内核 C API 的直接交互封装到经过仔细审查和文档化的抽象
|
||||
中。这样,只要满足以下条件,这些抽象的用户就不能引入未定义行为
|
||||
(undefined behavior,UB):
|
||||
|
||||
#. 抽象是正确的("可靠")。
|
||||
#. 任何 ``unsafe`` 块都遵守调用块内操作所需的安全契约。类似地,任何
|
||||
``unsafe impl`` 都遵守实现该特性所需的安全契约。
|
||||
|
||||
绑定
|
||||
~~~~
|
||||
|
||||
通过从 ``include/`` 中将 C 头文件包含到
|
||||
``rust/bindings/bindings_helper.h``, ``bindgen`` 工具将为所包含的子系统
|
||||
自动生成绑定。构建后,请查看 ``rust/bindings/`` 目录中的
|
||||
``*_generated.rs`` 输出文件。
|
||||
|
||||
对于 ``bindgen`` 不会自动生成的 C 头文件部分,例如 C ``inline`` 函数或
|
||||
非平凡宏,可以在 ``rust/helpers/`` 中添加一个小型包装函数,使其也可供
|
||||
Rust 端使用。
|
||||
|
||||
抽象
|
||||
~~~~
|
||||
|
||||
抽象是绑定和内核内用户之间的层。它们位于 ``rust/kernel/`` 中,其作用是
|
||||
将对绑定的不安全访问封装到尽可能安全并暴露给用户的 API 中。抽象的用户
|
||||
包括用 Rust 编写的驱动程序或文件系统等。
|
||||
|
||||
除了安全方面,这些抽象还应该易于使用,也就是说,把 C 接口转换为符合
|
||||
Rust 惯例的代码。基本示例包括将 C 的资源获取和释放转换为 Rust 的初始化
|
||||
和清理模式,或者将 C 整数错误码转换为 Rust 的 ``Result``。
|
||||
|
||||
|
||||
有条件的编译
|
||||
------------
|
||||
@@ -74,3 +142,11 @@ Rust代码可以访问基于内核配置的条件性编译:
|
||||
#[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`)
|
||||
#[cfg(CONFIG_X="m")] // Enabled as a module (`m`)
|
||||
#[cfg(not(CONFIG_X))] // Disabled
|
||||
|
||||
对于 Rust 的 ``cfg`` 不支持的其他条件,例如带有数值比较的表达式,可以
|
||||
定义一个新的 Kconfig 符号:
|
||||
|
||||
.. code-block:: kconfig
|
||||
|
||||
config RUSTC_HAS_SPAN_FILE
|
||||
def_bool RUSTC_VERSION >= 108800
|
||||
|
||||
Reference in New Issue
Block a user