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====== 13SAS 层 14====== 15 16SAS 层是一个管理基础架构，用于管理 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 30SAS LLDD 是一种 PCI 设备驱动程序。它负责 PHY 层和 OOB（带外） 31信号的管理、厂商特定的任务，并向 SAS 层上报事件。 32 33SAS 层实现了 SAS 1.1 规范中定义的大部分 SAS 功能。 34 35sas_ha_struct 结构体用于向 SAS 层描述一个 SAS LLDD。该结构的 36大部分字段由 SAS 层使用，但其中少数字段需要由 LLDD 进行初始化。 37 38在完成硬件初始化之后，应当在驱动的 probe() 函数中调用 39sas_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 75enabled 76 - 必须设置(0/1) 77 78id 79 - 必须设置[0,MAX_PHYS)] 80 81class, proto, type, role, oob_mode, linkrate 82 - 必须设置。 83 84oob_mode 85 - 当 OOB（带外信号）完成后，设置此字段，然后通知 SAS 层。 86 87sas_addr 88 - 通常指向一个保存该 PHY 的 SAS 地址的数组，该数组可能位于 89 驱动自定义的 my_phy 结构体中。 90 91attached_sas_addr 92 - 当 LLDD 接收到 IDENTIFY 帧或 FIS 帧时，应在通知 SAS 层 93 之前设置该字段。其设计意图在于：有时 LLDD 可能需要伪造或 94 提供一个与实际不同的 SAS 地址用于该 PHY/端口，而该机制允许 95 LLDD 这样做。理想情况下，应将 SAS 地址从 IDENTIFY 帧中 96 复制过来；对于直接连接的 SATA 设备，也可以由 LLDD 生成一 97 个 SAS 地址。后续的发现过程可能会修改此字段。 98 99frame_rcvd 100 - 当接收到 IDENTIFY 或 FIS 帧时，将该帧复制到此处。正确的 101 操作流程是获取锁 → 复制数据 → 设置 frame_rcvd_size → 释 102 放锁 → 调用事件通知。该字段是一个指针，因为驱动无法精确确 103 定硬件帧的大小；因此，实际的帧数据数组应定义在驱动自定义的 104 PHY 结构体中，然后让此指针指向该数组。在持锁状态下，将帧从 105 DMA 可访问内存区域复制到该数组中。 106 107sas_prim 108 - 用于存放接收到的原语（primitive）。参见 sas.h。操作流程同 109 样是：获取锁 → 设置 primitive → 释放锁 → 通知事件。 110 111port 112 - 如果该 PHY 属于某个端口（port），此字段指向对应的 sas_port 113 结构体。LLDD 仅可读取此字段。它由 SAS 层设置，用于指向当前 114 PHY 所属的 sas_port。 115 116ha 117 - 可以由 LLDD 设置；但无论是否设置，SAS 层都会再次对其进行赋值。 118 119lldd_phy 120 - LLDD 应将此字段设置为指向自身定义的 PHY 结构体，这样当 SAS 121 层调用某个回调并传入 sas_phy 时，驱动可以快速定位自身的 PHY 122 结构体。如果 sas_phy 是嵌入式成员，也可以使用 container_of() 123 宏进行访问——两种方式均可。 124 125``struct sas_port`` 126------------------- 127 128LLDD 不应修改该结构体中的任何字段——它只能读取这些字段。这些字段的 129含义应当是不言自明的。 130 131phy_mask 为 32 位，目前这一长度已足够使用，因为尚未听说有主机适配 132器拥有超过8 个 PHY。 133 134lldd_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 155pcidev 156^^^^^^ 157 158sas_addr 159 - 由于 SAS 层不想弄乱内存分配等, 因此这指向静态分配的数 160 组中的某个位置（例如，在您的主机适配器结构中），并保存您或 161 制造商等给出的主机适配器的 SAS 地址。 162 163sas_port 164^^^^^^^^ 165 166sas_phy 167 - 指向结构体的指针数组（参见上文关于 sas_addr 的说明）。 168 这些指针必须设置。更多细节见下文说明。 169 170num_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 191SAS 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 209SAS LLDD 至少应实现上述函数中的一个。 210 211PHY 管理:: 212 213 /* PHY 管理 */ 214 int (*lldd_control_phy)(struct sas_phy *, enum phy_func); 215 216lldd_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 层发生任何情况的方式。 268LLDD 没有其他方法可以告知 SAS 层其内部或 SAS 域中发生的事件。 269 270Phy 事件:: 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 288SAS LLDD 应能够生成以下事件:: 289 290 - 来自 C 组的至少一个事件（可选）， 291 - 标记为 M（必需）的事件为必需事件（至少一种）； 292 - 若希望 SAS 层处理域重新验证（domain revalidation），则 293 应生成标记为 E（扩展器）的事件（仅需一种）； 294 - 未标记的事件为可选事件。 295 296含义 297 298HAE_RESET 299 - 当 HA 发生内部错误并被复位时。 300 301PORTE_BYTES_DMAED 302 - 在接收到 IDENTIFY/FIS 帧时。 303 304PORTE_BROADCAST_RCVD 305 - 在接收到一个原语时。 306 307PORTE_LINK_RESET_ERR 308 - 定时器超时、信号丢失、丢失 DWS 等情况。 [1]_ 309 310PORTE_TIMER_EVENT 311 - DWS 复位超时定时器到期时。[1]_ 312 313PORTE_HARD_RESET 314 - 收到 Hard Reset 原语。 315 316PHYE_LOSS_OF_SIGNAL 317 - 设备已断开连接。 [1]_ 318 319PHYE_OOB_DONE 320 - OOB 过程成功完成，oob_mode 有效。 321 322PHYE_OOB_ERROR 323 - 执行 OOB 过程中出现错误，设备可能已断开。 [1]_ 324 325PHYE_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 363sysfs 树有以下用途:: 364 365 a) 它显示当前时刻 SAS 域的物理布局，即展示当前物理世界中 366 域的实际结构。 367 b) 显示某些设备的参数。 _at_discovery_time_. 368 369下面是一个指向 tree(1) 程序的链接，该工具在查看 SAS 域时非常 370有用： 371ftp://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 端口），用户空间程序可以通过它发送 395SMP 请求并接收 SMP 响应。 396 397该功能的实现方式看起来非常简单: 398 3991. 构建要发送的 SMP 帧。其格式和布局在 SAS 规范中有说明。保持 400 CRC 字段为 0。 401 402open(2) 403 4042. 以读写模式打开该扩展器的 SMP portal sysfs 文件。 405 406write(2) 407 4083. 将第 1 步中构建的帧写入文件。 409 410read(2) 411 4124. 读取与所构建帧预期返回长度相同的数据量。如果读取的数据量与 413 预期不符，则表示发生了某种错误。 414 415close(2) 416 417整个过程在 "expander_conf.c" 文件中的函数 do_smp_func() 418及其调用者中有详细展示。 419 420对应的内核实现位于 "sas_expander.c" 文件中。 421 422程序 "expander_conf.c" 实现了上述逻辑。它接收一个参数——扩展器 423SMP portal 的 sysfs 文件名，并输出扩展器的信息，包括路由表内容。 424 425SMP portal 赋予了你对扩展器的完全控制权，因此请谨慎操作。 426