Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Merge tag 'Chinese-docs-6.19' of gitolite.kernel.org:pub/scm/linux/kernel/git/alexs/linux into tmp
Chinese translation docs for 6.19
This is the Chinese translation subtree for 6.19. It includes
the following changes:
- Add block part translations
- Update kbuild.rst translations
- Add more scsi translations and fixes
Above patches are tested by 'make htmldocs'
Signed-off-by: Alex Shi <alexs@kernel.org>
+851
-14
+130
Documentation/translations/zh_CN/block/blk-mq.rst
+130
Documentation/translations/zh_CN/block/blk-mq.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
.. include:: ../disclaimer-zh_CN.rst
3
+
4
+
:Original: Documentation/block/blk-mq.rst
5
+
6
+
:翻译:
7
+
8
+
柯子杰 kezijie <kezijie@leap-io-kernel.com>
9
+
10
+
:校译:
11
+
12
+
13
+
14
+
================================================
15
+
多队列块设备 I/O 排队机制 (blk-mq)
16
+
================================================
17
+
18
+
多队列块设备 I/O 排队机制提供了一组 API，使高速存储设备能够同时在多个队列中
19
+
处理并发的 I/O 请求并将其提交到块设备，从而实现极高的每秒输入/输出操作次数
20
+
(IOPS)，充分发挥现代存储设备的并行能力。
21
+
22
+
介绍
23
+
====
24
+
25
+
背景
26
+
----
27
+
28
+
磁盘从 Linux 内核开发初期就已成为事实上的标准。块 I/O 子系统的目标是尽可能
29
+
为此类设备提供最佳性能，因为它们在进行随机访问时代价极高，性能瓶颈主要在机械
30
+
运动部件上，其速度远低于存储栈中其他任何层。其中一个软件优化例子是根据硬盘磁
31
+
头当前的位置重新排序读/写请求。
32
+
33
+
然而，随着固态硬盘和非易失性存储的发展，它们没有机械部件，也不存在随机访问代
34
+
码，并能够进行高速并行访问，存储栈的瓶颈从存储设备转移到了操作系统。为了充分
35
+
利用这些设备设计中的并行性，引入了多队列机制。
36
+
37
+
原来的设计只有一个队列来存储块设备 I/O 请求，并且只使用一个锁。由于缓存中的
38
+
脏数据和多处理器共享单锁的瓶颈，这种设计在 SMP 系统中扩展性不佳。当不同进程
39
+
（或同一进程在不同 CPU 上）同时执行块设备 I/O 时，该单队列模型还会出现严重
40
+
的拥塞问题。为了解决这些问题，blk-mq API 引入了多个队列，每个队列在本地 CPU
41
+
上拥有独立的入口点，从而消除了对全局锁的需求。关于其具体工作机制的更深入说明，
42
+
请参见下一节（ `工作原理`_ ）。
43
+
44
+
工作原理
45
+
--------
46
+
47
+
当用户空间执行对块设备的 I/O（例如读写文件）时，blk-mq 便会介入：它将存储和
48
+
管理发送到块设备的 I/O 请求，充当用户空间（文件系统，如果存在的话）与块设备驱
49
+
动之间的中间层。
50
+
51
+
blk-mq 由两组队列组成：软件暂存队列和硬件派发队列。当请求到达块层时，它会尝
52
+
试最短路径：直接发送到硬件队列。然而，有两种情况下可能不会这样做：如果该层有
53
+
IO 调度器或者是希望合并请求。在这两种情况下，请求将被发送到软件队列。
54
+
55
+
随后，在软件队列中的请求被处理后，请求会被放置到硬件队列。硬件队列是第二阶段
56
+
的队列，硬件可以直接访问并处理这些请求。然而，如果硬件没有足够的资源来接受更
57
+
多请求，blk-mq 会将请求放置在临时队列中，待硬件资源充足时再发送。
58
+
59
+
软件暂存队列
60
+
~~~~~~~~~~~~
61
+
62
+
在这些请求未直接发送到驱动时，块设备 I/O 子系统会将请求添加到软件暂存队列中
63
+
（由 struct blk_mq_ctx 表示）。一个请求可能包含一个或多个 BIO。它们通过 struct bio
64
+
数据结构到达块层。块层随后会基于这些 BIO 构建新的结构体 struct request，用于
65
+
与设备驱动通信。每个队列都有自己的锁，队列数量由每个 CPU 和每个 node 为基础
66
+
来决定。
67
+
68
+
暂存队列可用于合并相邻扇区的请求。例如，对扇区3-6、6-7、7-9的请求可以合并
69
+
为对扇区3-9的一个请求。即便 SSD 或 NVM 的随机访问和顺序访问响应时间相同，
70
+
合并顺序访问的请求仍可减少单独请求的数量。这种合并请求的技术称为 plugging。
71
+
72
+
此外，I/O 调度器还可以对请求进行重新排序以确保系统资源的公平性（例如防止某
73
+
个应用出现“饥饿”现象）或是提高 I/O 性能。
74
+
75
+
I/O 调度器
76
+
^^^^^^^^^^
77
+
78
+
块层实现了多种调度器，每种调度器都遵循一定启发式规则以提高 I/O 性能。它们是
79
+
“可插拔”的(plug and play)，可在运行时通过 sysfs 选择。你可以在这里阅读更
80
+
多关于 Linux IO 调度器知识 `here
81
+
<https://www.kernel.org/doc/html/latest/block/index.html>`_。调度只发
82
+
生在同一队列内的请求之间，因此无法合并不同队列的请求，否则会造成缓存冲突并需
83
+
要为每个队列加锁。调度后，请求即可发送到硬件。可能选择的调度器之一是 NONE 调
84
+
度器，这是最直接的调度器：它只将请求放到进程所在的软件队列，不进行重新排序。
85
+
当设备开始处理硬件队列中的请求时（运行硬件队列），映射到该硬件队列的软件队列
86
+
会按映射顺序依次清空。
87
+
88
+
硬件派发队列
89
+
~~~~~~~~~~~~~
90
+
91
+
硬件队列（由 struct blk_mq_hw_ctx 表示）是设备驱动用来映射设备提交队列
92
+
（或设备 DMA 环缓存）的结构体，它是块层提交路径在底层设备驱动接管请求之前的
93
+
最后一个阶段。运行此队列时，块层会从相关软件队列中取出请求，并尝试派发到硬件。
94
+
95
+
如果请求无法直接发送到硬件，它们会被加入到请求的链表(``hctx->dispatch``) 中。
96
+
随后，当块层下次运行该队列时，会优先发送位于 ``dispatch`` 链表中的请求，
97
+
以确保那些最早准备好发送的请求能够得到公平调度。硬件队列的数量取决于硬件及
98
+
其设备驱动所支持的硬件上下文数，但不会超过系统的CPU核心数。在这个阶段不
99
+
会发生重新排序，每个软件队列都有一组硬件队列来用于提交请求。
100
+
101
+
.. note::
102
+
103
+
块层和设备协议都不保证请求完成顺序。此问题需由更高层处理，例如文件系统。
104
+
105
+
基于标识的完成机制
106
+
~~~~~~~~~~~~~~~~~~~
107
+
108
+
为了指示哪一个请求已经完成，每个请求都会被分配一个整数标识，该标识的取值范围
109
+
是从0到分发队列的大小。这个标识由块层生成，并在之后由设备驱动使用，从而避
110
+
免了为每个请求再单独创建冗余的标识符。当请求在驱动中完成时，驱动会将该标识返
111
+
回给块层，以通知该请求已完成。这样，块层就无需再进行线性搜索来确定是哪一个
112
+
I/O 请求完成了。
113
+
114
+
更多阅读
115
+
--------
116
+
117
+
- `Linux 块 I/O：多队列 SSD 并发访问简介 <http://kernel.dk/blk-mq.pdf>`_
118
+
119
+
- `NOOP 调度器 <https://en.wikipedia.org/wiki/Noop_scheduler>`_
120
+
121
+
- `Null 块设备驱动程序 <https://www.kernel.org/doc/html/latest/block/null_blk.html>`_
122
+
123
+
源代码
124
+
======
125
+
126
+
该API在以下内核代码中:
127
+
128
+
include/linux/blk-mq.h
129
+
130
+
block/blk-mq.c
+192
Documentation/translations/zh_CN/block/data-integrity.rst
+192
Documentation/translations/zh_CN/block/data-integrity.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
.. include:: ../disclaimer-zh_CN.rst
3
+
4
+
:Original: Documentation/block/data-integrity.rst
5
+
6
+
:翻译:
7
+
8
+
柯子杰 kezijie <kezijie@leap-io-kernel.com>
9
+
10
+
:校译:
11
+
12
+
==========
13
+
数据完整性
14
+
==========
15
+
16
+
1. 引言
17
+
=======
18
+
19
+
现代文件系统对数据和元数据都进行了校验和保护以防止数据损坏。然而，这种损坏的
20
+
检测是在读取时才进行，这可能发生在数据写入数月之后。到那时，应用程序尝试写入
21
+
的原始数据很可能已经丢失。
22
+
23
+
解决方案是确保磁盘实际存储的内容就是应用程序想存储的。SCSI 协议族（如 SBC
24
+
数据完整性字段、SCC 保护提案）以及 SATA/T13（外部路径保护）最近新增的功能，
25
+
通过在 I/O 中附加完整性元数据的方式，试图解决这一问题。完整性元数据（在
26
+
SCSI 术语中称为保护信息）包括每个扇区的校验和，以及一个递增计数器，用于确保
27
+
各扇区按正确顺序被写入盘。在某些保护方案中，还能保证 I/O 写入磁盘的正确位置。
28
+
29
+
当前的存储控制器和设备实现了多种保护措施，例如校验和和数据清理。但这些技术通
30
+
常只在各自的独立域内工作，或最多仅在 I/O 路径的相邻节点之间发挥作用。DIF 及
31
+
其它数据完整性拓展有意思的点在于保护格式定义明确，I/O 路径上的每个节点都可以
32
+
验证 I/O 的完整性，如检测到损坏可直接拒绝。这不仅可以防止数据损坏，还能够隔
33
+
离故障点。
34
+
35
+
2. 数据完整性拓展
36
+
=================
37
+
38
+
如上所述，这些协议扩展只保护控制器与存储设备之间的路径。然而，许多控制器实际
39
+
上允许操作系统与完整性元数据(IMD)交互。我们一直与多家 FC/SAS HBA 厂商合作，
40
+
使保护信息能够在其控制器与操作系统之间传输。
41
+
42
+
SCSI 数据完整性字段通过在每个扇区后附加8字节的保护信息来实现。数据 + 完整
43
+
性元数据存储在磁盘的520字节扇区中。数据 + IMD 在控制器与目标设备之间传输
44
+
时是交错组合在一起的。T13 提案的方式类似。
45
+
46
+
由于操作系统处理520字节（甚至 4104 字节）扇区非常不便，我们联系了多家 HBA
47
+
厂商，并鼓励它们分离数据与完整性元数据的 scatter-gather lists。
48
+
49
+
控制器在写入时会将数据缓冲区和完整性元数据缓冲区的数据交错在一起，并在读取时
50
+
会拆分它们。这样，Linux 就能直接通过 DMA 将数据缓冲区传输到主机内存或从主机
51
+
内存读取，而无需修改页缓存。
52
+
53
+
此外，SCSI 与 SATA 规范要求的16位 CRC 校验在软件中计算代价较高。基准测试发
54
+
现，计算此校验在高负载情形下显著影响系统性能。一些控制器允许在操作系统接口处
55
+
使用轻量级校验。例如 Emulex 支持 TCP/IP 校验。操作系统提供的 IP 校验在写入
56
+
时会转换为16位 CRC，读取时则相反。这允许 Linux 或应用程序以极低的开销生成
57
+
完整性元数据（与软件 RAID5 相当）。
58
+
59
+
IP 校验在检测位错误方面比 CRC 弱，但关键在于数据缓冲区与完整性元数据缓冲区
60
+
的分离。只有这两个不同的缓冲区匹配，I/O 才能完成。
61
+
62
+
数据与完整性元数据缓冲区的分离以及校验选择被称为数据完整性扩展。由于这些扩展
63
+
超出了协议主体(T10、T13)的范围，Oracle 及其合作伙伴正尝试在存储网络行业协
64
+
会内对其进行标准化。
65
+
66
+
3. 内核变更
67
+
===========
68
+
69
+
Linux 中的数据完整性框架允许将保护信息固定到 I/O 上，并在支持该功能的控制器
70
+
之间发送和接收。
71
+
72
+
SCSI 和 SATA 中完整性扩展的优势在于，它们能够保护从应用程序到存储设备的整个
73
+
路径。然而，这同时也是最大的劣势。这意味着保护信息必须采用磁盘可以理解的格式。
74
+
75
+
通常，Linux/POSIX 应用程序并不关心所访问存储设备的具体细节。虚拟文件系统层
76
+
和块层会让硬件扇区大小和传输协议对应用程序完全透明。
77
+
78
+
然而，在准备发送到磁盘的保护信息时，就需要这种细节。因此，端到端保护方案的概
79
+
念实际上违反了层次结构。应用程序完全不应该知道它访问的是 SCSI 还是 SATA 磁盘。
80
+
81
+
Linux 中实现的数据完整性支持尝试将这些细节对应用程序隐藏。就应用程序（以及在
82
+
某种程度上内核）而言，完整性元数据是附加在 I/O 上的不透明信息。
83
+
84
+
当前实现允许块层自动为任何 I/O 生成保护信息。最终目标是将用户数据的完整性元
85
+
数据计算移至用户空间。内核中产生的元数据和其他 I/O 仍将使用自动生成接口。
86
+
87
+
一些存储设备允许为每个硬件扇区附加一个16位的标识值。这个标识空间的所有者是
88
+
块设备的所有者，也就是在多数情况下由文件系统掌控。文件系统可以利用这额外空间
89
+
按需为扇区附加标识。由于标识空间有限，块接口允许通过交错方式对更大的数据块标
90
+
识。这样，8*16位的信息可以附加到典型的 4KB 文件系统块上。
91
+
92
+
这也意味着诸如 fsck 和 mkfs 等应用程序需要能够从用户空间访问并操作这些标记。
93
+
为此，正在开发一个透传接口。
94
+
95
+
4. 块层实现细节
96
+
===============
97
+
98
+
4.1 Bio
99
+
--------
100
+
101
+
当启用 CONFIG_BLK_DEV_INTEGRITY 时，数据完整性补丁会在 struct bio 中添加
102
+
一个新字段。调用 bio_integrity(bio) 会返回一个指向 struct bip 的指针，该
103
+
结构体包含了该 bio 的完整性负载。本质上，bip 是一个精简版的 struct bio，其
104
+
中包含一个 bio_vec，用于保存完整性元数据以及所需的维护信息（bvec 池、向量计
105
+
数等）。
106
+
107
+
内核子系统可以通过调用 bio_integrity_alloc(bio) 来为某个 bio 启用数据完整
108
+
性保护。该函数会分配并附加一个 bip 到该 bio 上。
109
+
110
+
随后使用 bio_integrity_add_page() 将包含完整性元数据的单独页面附加到该 bio。
111
+
112
+
调用 bio_free() 会自动释放bip。
113
+
114
+
4.2 块设备
115
+
-----------
116
+
117
+
块设备可以在 queue_limits 结构中的 integrity 子结构中设置完整性信息。
118
+
119
+
对于分层块设备，需要选择一个适用于所有子设备的完整性配置文件。可以使用
120
+
queue_limits_stack_integrity() 来协助完成该操作。目前，DM 和 MD linear、
121
+
RAID0 和 RAID1 已受支持。而RAID4/5/6因涉及应用标签仍需额外的开发工作。
122
+
123
+
5.0 块层完整性API
124
+
==================
125
+
126
+
5.1 普通文件系统
127
+
-----------------
128
+
129
+
普通文件系统并不知道其下层块设备具备发送或接收完整性元数据的能力。
130
+
在执行写操作时，块层会在调用 submit_bio() 时自动生成完整性元数据。
131
+
在执行读操作时，I/O 完成后会触发完整性验证。
132
+
133
+
IMD 的生成与验证行为可以通过以下开关控制::
134
+
135
+
/sys/block/<bdev>/integrity/write_generate
136
+
137
+
and::
138
+
139
+
/sys/block/<bdev>/integrity/read_verify
140
+
141
+
flags.
142
+
143
+
5.2 具备完整性感知的文件系统
144
+
----------------------------
145
+
146
+
具备完整性感知能力的文件系统可以在准备 I/O 时附加完整性元数据，
147
+
并且如果底层块设备支持应用标签空间，也可以加以利用。
148
+
149
+
150
+
`bool bio_integrity_prep(bio);`
151
+
152
+
要为写操作生成完整性元数据或为读操作设置缓冲区，文件系统必须调用
153
+
bio_integrity_prep(bio)。
154
+
155
+
在调用此函数之前，必须先设置好 bio 的数据方向和起始扇区，并确
156
+
保该 bio 已经添加完所有的数据页。调用者需要自行保证，在 I/O 进行
157
+
期间 bio 不会被修改。如果由于某种原因准备失败，则应当以错误状态
158
+
完成该 bio。
159
+
160
+
5.3 传递已有的完整性元数据
161
+
--------------------------
162
+
163
+
能够自行生成完整性元数据或可以从用户空间传输完整性元数据的文件系统，
164
+
可以使用如下接口：
165
+
166
+
167
+
`struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);`
168
+
169
+
为 bio 分配完整性负载并挂载到 bio 上。nr_pages 表示需要在
170
+
integrity bio_vec list 中存储多少页保护数据（类似 bio_alloc）。
171
+
172
+
完整性负载将在 bio_free() 被调用时释放。
173
+
174
+
175
+
`int bio_integrity_add_page(bio, page, len, offset);`
176
+
177
+
将包含完整性元数据的一页附加到已有的 bio 上。该 bio 必须已有 bip，
178
+
即必须先调用 bio_integrity_alloc()。对于写操作，页中的完整
179
+
性元数据必须采用目标设备可识别的格式，但有一个例外，当请求在 I/O 栈
180
+
中传递时，扇区号会被重新映射。这意味着通过此接口添加的页在 I/O 过程
181
+
中可能会被修改！完整性元数据中的第一个引用标签必须等于 bip->bip_sector。
182
+
183
+
只要 bip bio_vec array（nr_pages）有空间，就可以继续通过
184
+
bio_integrity_add_page()添加页。
185
+
186
+
当读操作完成后，附加的页将包含从存储设备接收到的完整性元数据。
187
+
接收方需要处理这些元数据，并在操作完成时验证数据完整性
188
+
189
+
190
+
----------------------------------------------------------------------
191
+
192
+
2007-12-24 Martin K. Petersen <martin.petersen@oracle.com>
+35
Documentation/translations/zh_CN/block/index.rst
+35
Documentation/translations/zh_CN/block/index.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
.. include:: ../disclaimer-zh_CN.rst
3
+
4
+
:Original: Documentation/block/index.rst
5
+
6
+
:翻译:
7
+
8
+
柯子杰 ke zijie <kezijie@leap-io-kernel.com>
9
+
10
+
:校译:
11
+
12
+
=====
13
+
Block
14
+
=====
15
+
16
+
.. toctree::
17
+
:maxdepth: 1
18
+
19
+
blk-mq
20
+
data-integrity
21
+
22
+
TODOList:
23
+
* bfq-iosched
24
+
* biovecs
25
+
* cmdline-partition
26
+
* deadline-iosched
27
+
* inline-encryption
28
+
* ioprio
29
+
* kyber-iosched
30
+
* null_blk
31
+
* pr
32
+
* stat
33
+
* switching-sched
34
+
* writeback_cache_control
35
+
* ublk
+24
-3
Documentation/translations/zh_CN/kbuild/kbuild.rst
+24
-3
Documentation/translations/zh_CN/kbuild/kbuild.rst
···
93
93
-------------
94
94
在构建主机程序时传递给 $(HOSTRUSTC) 的额外标志。
95
95
96
+
PROCMACROLDFLAGS
97
+
----------------
98
+
用于链接 Rust 过程宏的标志。由于过程宏是由 rustc 在构建时加载的，
99
+
因此必须以与当前使用的 rustc 工具链兼容的方式进行链接。
100
+
101
+
例如，当 rustc 使用的 C 库与用户希望用于主机程序的 C 库不同时，
102
+
此设置会非常有用。
103
+
104
+
如果未设置，则默认使用链接主机程序时传递的标志。
105
+
96
106
HOSTLDFLAGS
97
107
-----------
98
108
链接主机程序时传递的额外选项。
···
145
135
指定内核构建的输出目录。
146
136
147
137
在单独的构建目录中为预构建内核构建外部模块时，这个变量也可以指向内核输出目录。请注意，
148
-
这并不指定外部模块本身的输出目录。
138
+
这并不指定外部模块本身的输出目录(使用 KBUILD_EXTMOD_OUTPUT 来达到这个目的)。
149
139
150
140
输出目录也可以使用 "O=..." 指定。
151
141
152
142
设置 "O=..." 优先于 KBUILD_OUTPUT。
143
+
144
+
KBUILD_EXTMOD_OUTPUT
145
+
--------------------
146
+
指定外部模块的输出目录
147
+
148
+
设置 "MO=..." 优先于 KBUILD_EXTMOD_OUTPUT.
153
149
154
150
KBUILD_EXTRA_WARN
155
151
-----------------
···
306
290
KBUILD_BUILD_TIMESTAMP
307
291
----------------------
308
292
将该环境变量设置为日期字符串，可以覆盖在 UTS_VERSION 定义中使用的时间戳
309
-
（运行内核时的 uname -v）。该值必须是一个可以传递给 date -d 的字符串。默认值是
310
-
内核构建某个时刻的 date 命令输出。
293
+
(运行内核时的 uname -v) 。该值必须是一个可以传递给 date -d 的字符串。例如::
294
+
295
+
$ KBUILD_BUILD_TIMESTAMP="Mon Oct 13 00:00:00 UTC 2025" make
296
+
297
+
默认值是内核构建某个时刻的 date 命令输出。如果提供该时戳，它还用于任何 initramfs 归
298
+
档文件中的 mtime 字段。 Initramfs mtimes 是 32 位的，因此早于 Unix 纪元 1970 年，或
299
+
晚于协调世界时 (UTC) 2106 年 2 月 7 日 6 时 28 分 15 秒的日期是无效的。
311
300
312
301
KBUILD_BUILD_USER, KBUILD_BUILD_HOST
313
302
------------------------------------
+2
-2
Documentation/translations/zh_CN/scsi/index.rst
+2
-2
Documentation/translations/zh_CN/scsi/index.rst
···
50
50
.. toctree::
51
51
:maxdepth: 1
52
52
53
+
libsas
53
54
sd-parameters
55
+
wd719x
54
56
55
57
Todolist:
56
58
···
73
71
* g_NCR5380
74
72
* hpsa
75
73
* hptiop
76
-
* libsas
77
74
* lpfc
78
75
* megaraid
79
76
* ncr53c8xx
···
88
87
* sym53c8xx_2
89
88
* tcm_qla2xxx
90
89
* ufs
91
-
* wd719x
92
90
93
91
* scsi_transport_srp/figures
+425
Documentation/translations/zh_CN/scsi/libsas.rst
+425
Documentation/translations/zh_CN/scsi/libsas.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
.. include:: ../disclaimer-zh_CN.rst
3
+
4
+
:Original: Documentation/scsi/libsas.rst
5
+
6
+
:翻译:
7
+
8
+
张钰杰 Yujie Zhang <yjzhang@leap-io-kernel.com>
9
+
10
+
:校译:
11
+
12
+
======
13
+
SAS 层
14
+
======
15
+
16
+
SAS 层是一个管理基础架构，用于管理 SAS LLDD。它位于 SCSI Core
17
+
与 SAS LLDD 之间。 体系结构如下: SCSI Core 关注的是 SAM/SPC 相
18
+
关的问题；SAS LLDD 及其序列控制器负责 PHY 层、OOB 信号以及链路
19
+
管理；而 SAS 层则负责以下任务::
20
+
21
+
* SAS Phy、Port 和主机适配器（HA）事件管理（事件由 LLDD
22
+
生成，由 SAS 层处理）；
23
+
* SAS 端口的管理（创建与销毁）；
24
+
* SAS 域的发现与重新验证；
25
+
* SAS 域内设备的管理；
26
+
* SCSI 主机的注册与注销；
27
+
* 将设备注册到 SCSI Core（SAS 设备）或 libata（SATA 设备）；
28
+
* 扩展器的管理，并向用户空间导出扩展器控制接口。
29
+
30
+
SAS LLDD 是一种 PCI 设备驱动程序。它负责 PHY 层和 OOB（带外）
31
+
信号的管理、厂商特定的任务，并向 SAS 层上报事件。
32
+
33
+
SAS 层实现了 SAS 1.1 规范中定义的大部分 SAS 功能。
34
+
35
+
sas_ha_struct 结构体用于向 SAS 层描述一个 SAS LLDD。该结构的
36
+
大部分字段由 SAS 层使用，但其中少数字段需要由 LLDD 进行初始化。
37
+
38
+
在完成硬件初始化之后，应当在驱动的 probe() 函数中调用
39
+
sas_register_ha()。该函数会将 LLDD 注册到 SCSI 子系统中，创
40
+
建一个对应的 SCSI 主机，并将你的 SAS 驱动程序注册到其在 sysfs
41
+
下创建的 SAS 设备树中。随后该函数将返回。接着，你需要使能 PHY，
42
+
以启动实际的 OOB（带外）过程；此时驱动将开始调用 notify_* 系
43
+
列事件回调函数。
44
+
45
+
结构体说明
46
+
==========
47
+
48
+
``struct sas_phy``
49
+
------------------
50
+
51
+
通常情况下，该结构体会被静态地嵌入到驱动自身定义的 PHY 结构体中,
52
+
例如::
53
+
54
+
struct my_phy {
55
+
blah;
56
+
struct sas_phy sas_phy;
57
+
bleh;
58
+
}
59
+
60
+
随后，在主机适配器（HA）的结构体中，所有的 PHY 通常以 my_phy
61
+
数组的形式存在（如下文所示）。
62
+
63
+
在初始化各个 PHY 时，除了初始化驱动自定义的 PHY 结构体外，还
64
+
需要同时初始化其中的 sas_phy 结构体。
65
+
66
+
一般来说，PHY 的管理由 LLDD 负责，而端口（port）的管理由 SAS
67
+
层负责。因此，PHY 的初始化与更新由 LLDD 完成，而端口的初始化与
68
+
更新则由 SAS 层完成。系统设计中规定，某些字段可由 LLDD 进行读
69
+
写，而 SAS 层只能读取这些字段；反之亦然。其设计目的是为了避免不
70
+
必要的锁操作。
71
+
72
+
在该设计中，某些字段可由 LLDD 进行读写（RW），而 SAS 层仅可读
73
+
取这些字段；反之亦然。这样设计的目的在于避免不必要的锁操作。
74
+
75
+
enabled
76
+
- 必须设置(0/1)
77
+
78
+
id
79
+
- 必须设置[0,MAX_PHYS)]
80
+
81
+
class, proto, type, role, oob_mode, linkrate
82
+
- 必须设置。
83
+
84
+
oob_mode
85
+
- 当 OOB（带外信号）完成后，设置此字段，然后通知 SAS 层。
86
+
87
+
sas_addr
88
+
- 通常指向一个保存该 PHY 的 SAS 地址的数组，该数组可能位于
89
+
驱动自定义的 my_phy 结构体中。
90
+
91
+
attached_sas_addr
92
+
- 当 LLDD 接收到 IDENTIFY 帧或 FIS 帧时，应在通知 SAS 层
93
+
之前设置该字段。其设计意图在于：有时 LLDD 可能需要伪造或
94
+
提供一个与实际不同的 SAS 地址用于该 PHY/端口，而该机制允许
95
+
LLDD 这样做。理想情况下，应将 SAS 地址从 IDENTIFY 帧中
96
+
复制过来；对于直接连接的 SATA 设备，也可以由 LLDD 生成一
97
+
个 SAS 地址。后续的发现过程可能会修改此字段。
98
+
99
+
frame_rcvd
100
+
- 当接收到 IDENTIFY 或 FIS 帧时，将该帧复制到此处。正确的
101
+
操作流程是获取锁 → 复制数据 → 设置 frame_rcvd_size → 释
102
+
放锁 → 调用事件通知。该字段是一个指针，因为驱动无法精确确
103
+
定硬件帧的大小；因此，实际的帧数据数组应定义在驱动自定义的
104
+
PHY 结构体中，然后让此指针指向该数组。在持锁状态下，将帧从
105
+
DMA 可访问内存区域复制到该数组中。
106
+
107
+
sas_prim
108
+
- 用于存放接收到的原语（primitive）。参见 sas.h。操作流程同
109
+
样是：获取锁 → 设置 primitive → 释放锁 → 通知事件。
110
+
111
+
port
112
+
- 如果该 PHY 属于某个端口（port），此字段指向对应的 sas_port
113
+
结构体。LLDD 仅可读取此字段。它由 SAS 层设置，用于指向当前
114
+
PHY 所属的 sas_port。
115
+
116
+
ha
117
+
- 可以由 LLDD 设置；但无论是否设置，SAS 层都会再次对其进行赋值。
118
+
119
+
lldd_phy
120
+
- LLDD 应将此字段设置为指向自身定义的 PHY 结构体，这样当 SAS
121
+
层调用某个回调并传入 sas_phy 时，驱动可以快速定位自身的 PHY
122
+
结构体。如果 sas_phy 是嵌入式成员，也可以使用 container_of()
123
+
宏进行访问——两种方式均可。
124
+
125
+
``struct sas_port``
126
+
-------------------
127
+
128
+
LLDD 不应修改该结构体中的任何字段——它只能读取这些字段。这些字段的
129
+
含义应当是不言自明的。
130
+
131
+
phy_mask 为 32 位，目前这一长度已足够使用，因为尚未听说有主机适配
132
+
器拥有超过8 个 PHY。
133
+
134
+
lldd_port
135
+
- 目前尚无明确用途。不过，对于那些希望在 LLDD 内部维护自身端
136
+
口表示的驱动，实现时可以利用该字段。
137
+
138
+
``struct sas_ha_struct``
139
+
------------------------
140
+
141
+
它通常静态声明在你自己的 LLDD 结构中，用于描述您的适配器::
142
+
143
+
struct my_sas_ha {
144
+
blah;
145
+
struct sas_ha_struct sas_ha;
146
+
struct my_phy phys[MAX_PHYS];
147
+
struct sas_port sas_ports[MAX_PHYS]; /* (1) */
148
+
bleh;
149
+
};
150
+
151
+
(1) 如果你的 LLDD 没有自己的端口表示
152
+
153
+
需要初始化（示例函数如下所示）。
154
+
155
+
pcidev
156
+
^^^^^^
157
+
158
+
sas_addr
159
+
- 由于 SAS 层不想弄乱内存分配等, 因此这指向静态分配的数
160
+
组中的某个位置（例如，在您的主机适配器结构中），并保存您或
161
+
制造商等给出的主机适配器的 SAS 地址。
162
+
163
+
sas_port
164
+
^^^^^^^^
165
+
166
+
sas_phy
167
+
- 指向结构体的指针数组（参见上文关于 sas_addr 的说明）。
168
+
这些指针必须设置。更多细节见下文说明。
169
+
170
+
num_phys
171
+
- 表示 sas_phy 数组中 PHY 的数量，同时也表示 sas_port
172
+
数组中的端口数量。一个端口最多对应一个 PHY，因此最大端口数
173
+
等于 num_phys。因此，结构中不再单独使用 num_ports 字段，
174
+
而仅使用 num_phys。
175
+
176
+
事件接口::
177
+
178
+
/* LLDD 调用以下函数来通知 SAS 类层发生事件 */
179
+
void sas_notify_port_event(struct sas_phy *, enum port_event, gfp_t);
180
+
void sas_notify_phy_event(struct sas_phy *, enum phy_event, gfp_t);
181
+
182
+
端口事件通知::
183
+
184
+
/* SAS 类层调用以下回调来通知 LLDD 端口事件 */
185
+
void (*lldd_port_formed)(struct sas_phy *);
186
+
void (*lldd_port_deformed)(struct sas_phy *);
187
+
188
+
如果 LLDD 希望在端口形成或解散时接收通知，则应将上述回调指针设
189
+
置为符合函数类型定义的处理函数。
190
+
191
+
SAS LLDD 还应至少实现 SCSI 协议中定义的一种任务管理函数（TMFs）::
192
+
193
+
/* 任务管理函数. 必须在进程上下文中调用 */
194
+
int (*lldd_abort_task)(struct sas_task *);
195
+
int (*lldd_abort_task_set)(struct domain_device *, u8 *lun);
196
+
int (*lldd_clear_task_set)(struct domain_device *, u8 *lun);
197
+
int (*lldd_I_T_nexus_reset)(struct domain_device *);
198
+
int (*lldd_lu_reset)(struct domain_device *, u8 *lun);
199
+
int (*lldd_query_task)(struct sas_task *);
200
+
201
+
如需更多信息，请参考 T10.org。
202
+
203
+
端口与适配器管理::
204
+
205
+
/* 端口与适配器管理 */
206
+
int (*lldd_clear_nexus_port)(struct sas_port *);
207
+
int (*lldd_clear_nexus_ha)(struct sas_ha_struct *);
208
+
209
+
SAS LLDD 至少应实现上述函数中的一个。
210
+
211
+
PHY 管理::
212
+
213
+
/* PHY 管理 */
214
+
int (*lldd_control_phy)(struct sas_phy *, enum phy_func);
215
+
216
+
lldd_ha
217
+
- 应设置为指向驱动的主机适配器（HA）结构体的指针。如果 sas_ha_struct
218
+
被嵌入到更大的结构体中，也可以通过 container_of() 宏来获取。
219
+
220
+
一个示例的初始化与注册函数可以如下所示：（该函数应在 probe()
221
+
函数的最后调用）但必须在使能 PHY 执行 OOB 之前调用::
222
+
223
+
static int register_sas_ha(struct my_sas_ha *my_ha)
224
+
{
225
+
int i;
226
+
static struct sas_phy *sas_phys[MAX_PHYS];
227
+
static struct sas_port *sas_ports[MAX_PHYS];
228
+
229
+
my_ha->sas_ha.sas_addr = &my_ha->sas_addr[0];
230
+
231
+
for (i = 0; i < MAX_PHYS; i++) {
232
+
sas_phys[i] = &my_ha->phys[i].sas_phy;
233
+
sas_ports[i] = &my_ha->sas_ports[i];
234
+
}
235
+
236
+
my_ha->sas_ha.sas_phy = sas_phys;
237
+
my_ha->sas_ha.sas_port = sas_ports;
238
+
my_ha->sas_ha.num_phys = MAX_PHYS;
239
+
240
+
my_ha->sas_ha.lldd_port_formed = my_port_formed;
241
+
242
+
my_ha->sas_ha.lldd_dev_found = my_dev_found;
243
+
my_ha->sas_ha.lldd_dev_gone = my_dev_gone;
244
+
245
+
my_ha->sas_ha.lldd_execute_task = my_execute_task;
246
+
247
+
my_ha->sas_ha.lldd_abort_task = my_abort_task;
248
+
my_ha->sas_ha.lldd_abort_task_set = my_abort_task_set;
249
+
my_ha->sas_ha.lldd_clear_task_set = my_clear_task_set;
250
+
my_ha->sas_ha.lldd_I_T_nexus_reset= NULL; (2)
251
+
my_ha->sas_ha.lldd_lu_reset = my_lu_reset;
252
+
my_ha->sas_ha.lldd_query_task = my_query_task;
253
+
254
+
my_ha->sas_ha.lldd_clear_nexus_port = my_clear_nexus_port;
255
+
my_ha->sas_ha.lldd_clear_nexus_ha = my_clear_nexus_ha;
256
+
257
+
my_ha->sas_ha.lldd_control_phy = my_control_phy;
258
+
259
+
return sas_register_ha(&my_ha->sas_ha);
260
+
}
261
+
262
+
(2) SAS 1.1 未定义 I_T Nexus Reset TMF（任务管理功能）。
263
+
264
+
事件
265
+
====
266
+
267
+
事件是 SAS LLDD 唯一的通知 SAS 层发生任何情况的方式。
268
+
LLDD 没有其他方法可以告知 SAS 层其内部或 SAS 域中发生的事件。
269
+
270
+
Phy 事件::
271
+
272
+
PHYE_LOSS_OF_SIGNAL, (C)
273
+
PHYE_OOB_DONE,
274
+
PHYE_OOB_ERROR, (C)
275
+
PHYE_SPINUP_HOLD.
276
+
277
+
端口事件，通过 _phy_ 传递::
278
+
279
+
PORTE_BYTES_DMAED, (M)
280
+
PORTE_BROADCAST_RCVD, (E)
281
+
PORTE_LINK_RESET_ERR, (C)
282
+
PORTE_TIMER_EVENT, (C)
283
+
PORTE_HARD_RESET.
284
+
285
+
主机适配器事件：
286
+
HAE_RESET
287
+
288
+
SAS LLDD 应能够生成以下事件::
289
+
290
+
- 来自 C 组的至少一个事件（可选），
291
+
- 标记为 M（必需）的事件为必需事件（至少一种）；
292
+
- 若希望 SAS 层处理域重新验证（domain revalidation），则
293
+
应生成标记为 E（扩展器）的事件（仅需一种）；
294
+
- 未标记的事件为可选事件。
295
+
296
+
含义
297
+
298
+
HAE_RESET
299
+
- 当 HA 发生内部错误并被复位时。
300
+
301
+
PORTE_BYTES_DMAED
302
+
- 在接收到 IDENTIFY/FIS 帧时。
303
+
304
+
PORTE_BROADCAST_RCVD
305
+
- 在接收到一个原语时。
306
+
307
+
PORTE_LINK_RESET_ERR
308
+
- 定时器超时、信号丢失、丢失 DWS 等情况。 [1]_
309
+
310
+
PORTE_TIMER_EVENT
311
+
- DWS 复位超时定时器到期时。[1]_
312
+
313
+
PORTE_HARD_RESET
314
+
- 收到 Hard Reset 原语。
315
+
316
+
PHYE_LOSS_OF_SIGNAL
317
+
- 设备已断开连接。 [1]_
318
+
319
+
PHYE_OOB_DONE
320
+
- OOB 过程成功完成，oob_mode 有效。
321
+
322
+
PHYE_OOB_ERROR
323
+
- 执行 OOB 过程中出现错误，设备可能已断开。 [1]_
324
+
325
+
PHYE_SPINUP_HOLD
326
+
- 检测到 SATA 设备，但未发送 COMWAKE 信号。
327
+
328
+
.. [1] 应设置或清除 phy 中相应的字段，或者从 tasklet 中调用
329
+
内联函数 sas_phy_disconnected()，该函数只是一个辅助函数。
330
+
331
+
执行命令 SCSI RPC::
332
+
333
+
int (*lldd_execute_task)(struct sas_task *, gfp_t gfp_flags);
334
+
335
+
用于将任务排队提交给 SAS LLDD，@task 为要执行的任务，@gfp_mask
336
+
为定义调用者上下文的 gfp 掩码。
337
+
338
+
此函数应实现 执行 SCSI RPC 命令。
339
+
340
+
也就是说，当调用 lldd_execute_task() 时，命令应当立即在传输
341
+
层发出。SAS LLDD 中在任何层级上都不应再进行队列排放。
342
+
343
+
返回值::
344
+
345
+
* 返回 -SAS_QUEUE_FULL 或 -ENOMEM 表示未排入队列；
346
+
* 返回 0 表示任务已成功排入队列。
347
+
348
+
::
349
+
350
+
struct sas_task {
351
+
dev —— 此任务目标设备；
352
+
task_proto —— 协议类型，为 enum sas_proto 中的一种；
353
+
scatter —— 指向散布/聚集（SG）列表数组的指针；
354
+
num_scatter —— SG 列表元素数量；
355
+
total_xfer_len —— 预计传输的总字节数；
356
+
data_dir —— 数据传输方向(PCI_DMA_*)；
357
+
task_done —— 任务执行完成时的回调函数。
358
+
};
359
+
360
+
发现
361
+
====
362
+
363
+
sysfs 树有以下用途::
364
+
365
+
a) 它显示当前时刻 SAS 域的物理布局，即展示当前物理世界中
366
+
域的实际结构。
367
+
b) 显示某些设备的参数。 _at_discovery_time_.
368
+
369
+
下面是一个指向 tree(1) 程序的链接，该工具在查看 SAS 域时非常
370
+
有用：
371
+
ftp://mama.indstate.edu/linux/tree/
372
+
373
+
我期望用户空间的应用程序最终能够为此创建一个图形界面。
374
+
375
+
也就是说，sysfs 域树不会显示或保存某些状态变化，例如，如果你更
376
+
改了 READY LED 含义的设置，sysfs 树不会反映这种状态变化；但它
377
+
确实会显示域设备的当前连接状态。
378
+
379
+
维护内部设备状态变化的职责由上层（命令集驱动）和用户空间负责。
380
+
381
+
当某个设备或多个设备从域中拔出时，这一变化会立即反映在 sysfs
382
+
树中，并且这些设备会从系统中移除。
383
+
384
+
结构体 domain_device 描述了 SAS 域中的任意设备。它完全由 SAS
385
+
层管理。一个任务会指向某个域设备，SAS LLDD 就是通过这种方式知
386
+
道任务应发送到何处。SAS LLDD 只读取 domain_device 结构的内容，
387
+
但不会创建或销毁它。
388
+
389
+
用户空间中的扩展器管理
390
+
======================
391
+
392
+
在 sysfs 中的每个扩展器目录下，都有一个名为 "smp_portal" 的
393
+
文件。这是一个二进制的 sysfs 属性文件，它实现了一个 SMP 入口
394
+
（注意：这并不是一个 SMP 端口），用户空间程序可以通过它发送
395
+
SMP 请求并接收 SMP 响应。
396
+
397
+
该功能的实现方式看起来非常简单:
398
+
399
+
1. 构建要发送的 SMP 帧。其格式和布局在 SAS 规范中有说明。保持
400
+
CRC 字段为 0。
401
+
402
+
open(2)
403
+
404
+
2. 以读写模式打开该扩展器的 SMP portal sysfs 文件。
405
+
406
+
write(2)
407
+
408
+
3. 将第 1 步中构建的帧写入文件。
409
+
410
+
read(2)
411
+
412
+
4. 读取与所构建帧预期返回长度相同的数据量。如果读取的数据量与
413
+
预期不符，则表示发生了某种错误。
414
+
415
+
close(2)
416
+
417
+
整个过程在 "expander_conf.c" 文件中的函数 do_smp_func()
418
+
及其调用者中有详细展示。
419
+
420
+
对应的内核实现位于 "sas_expander.c" 文件中。
421
+
422
+
程序 "expander_conf.c" 实现了上述逻辑。它接收一个参数——扩展器
423
+
SMP portal 的 sysfs 文件名，并输出扩展器的信息，包括路由表内容。
424
+
425
+
SMP portal 赋予了你对扩展器的完全控制权，因此请谨慎操作。
+8
-8
Documentation/translations/zh_CN/scsi/scsi-parameters.rst
+8
-8
Documentation/translations/zh_CN/scsi/scsi-parameters.rst
···
31
31
请查阅 drivers/scsi/advansys.c 文件头部。
32
32
33
33
aha152x= [HW,SCSI]
34
-
请查阅 Documentation/translations/zh_CN/scsi/aha152x.rst。
34
+
请查阅 Documentation/scsi/aha152x.rst。
35
35
36
36
aha1542= [HW,SCSI]
37
37
格式：<portbase>[,<buson>,<busoff>[,<dmaspeed>]]
38
38
39
39
aic7xxx= [HW,SCSI]
40
-
请查阅 Documentation/translations/zh_CN/scsi/aic7xxx.rst。
40
+
请查阅 Documentation/scsi/aic7xxx.rst。
41
41
42
42
aic79xx= [HW,SCSI]
43
-
请查阅 Documentation/translations/zh_CN/scsi/aic79xx.rst。
43
+
请查阅 Documentation/scsi/aic79xx.rst。
44
44
45
45
atascsi= [HW,SCSI]
46
46
请查阅 drivers/scsi/atari_scsi.c。
···
69
69
请查阅 drivers/scsi/NCR_D700.c 文件头部。
70
70
71
71
ncr5380= [HW,SCSI]
72
-
请查阅 Documentation/translations/zh_CN/scsi/g_NCR5380.rst。
72
+
请查阅 Documentation/scsi/g_NCR5380.rst。
73
73
74
74
ncr53c400= [HW,SCSI]
75
-
请查阅 Documentation/translations/zh_CN/scsi/g_NCR5380.rst。
75
+
请查阅 Documentation/scsi/g_NCR5380.rst。
76
76
77
77
ncr53c400a= [HW,SCSI]
78
-
请查阅 Documentation/translations/zh_CN/scsi/g_NCR5380.rst。
78
+
请查阅 Documentation/scsi/g_NCR5380.rst。
79
79
80
80
ncr53c8xx= [HW,SCSI]
81
81
82
82
osst= [HW,SCSI] SCSI磁带驱动
83
83
格式：<buffer_size>,<write_threshold>
84
-
另请查阅 Documentation/translations/zh_CN/scsi/st.rst。
84
+
另请查阅 Documentation/scsi/st.rst。
85
85
86
86
scsi_debug_*= [SCSI]
87
87
请查阅 drivers/scsi/scsi_debug.c。
···
112
112
请查阅 drivers/scsi/sim710.c 文件头部。
113
113
114
114
st= [HW,SCSI] SCSI磁带参数（缓冲区大小等）
115
-
请查阅 Documentation/translations/zh_CN/scsi/st.rst。
115
+
请查阅 Documentation/scsi/st.rst。
116
116
117
117
wd33c93= [HW,SCSI]
118
118
请查阅 drivers/scsi/wd33c93.c 文件头部。
+35
Documentation/translations/zh_CN/scsi/wd719x.rst
+35
Documentation/translations/zh_CN/scsi/wd719x.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
.. include:: ../disclaimer-zh_CN.rst
3
+
4
+
:Original: Documentation/scsi/libsas.rst
5
+
6
+
:翻译:
7
+
8
+
张钰杰 Yujie Zhang <yjzhang@leap-io-kernel.com>
9
+
10
+
:校译:
11
+
12
+
====================================================
13
+
Western Digital WD7193, WD7197 和 WD7296 SCSI 卡驱动
14
+
====================================================
15
+
16
+
这些卡需要加载固件。固件可从 WD 提供下载的 Windows NT 驱动程
17
+
序中提取。地址如下：
18
+
19
+
http://support.wdc.com/product/download.asp?groupid=801&sid=27&lang=en
20
+
21
+
该文件或网页上都未包含任何许可声明，因此该固件可能无法被收录到
22
+
linux-firmware 项目中。
23
+
24
+
提供的脚本可用于下载并提取固件，生成 wd719x-risc.bin 和
25
+
wd719x-wcs.bin 文件。请将它们放置在 /lib/firmware/ 目录下。
26
+
脚本内容如下：
27
+
28
+
#!/bin/sh
29
+
wget http://support.wdc.com/download/archive/pciscsi.exe
30
+
lha xi pciscsi.exe pci-scsi.exe
31
+
lha xi pci-scsi.exe nt/wd7296a.sys
32
+
rm pci-scsi.exe
33
+
dd if=wd7296a.sys of=wd719x-risc.bin bs=1 skip=5760 count=14336
34
+
dd if=wd7296a.sys of=wd719x-wcs.bin bs=1 skip=20096 count=514
35
+
rm wd7296a.sys