scsi_mid_low_api.rst

   1.. SPDX-License-Identifier: GPL-2.0
   2.. include:: ../disclaimer-zh_CN.rst
   3
   4:Original: Documentation/scsi/scsi_mid_low_api.rst
   5
   6:翻译:
   7
   8 郝栋栋 doubled <doubled@leap-io-kernel.com>
   9
  10:校译:
  11
  12
  13
  14=========================
  15SCSI中间层 — 底层驱动接口
  16=========================
  17
  18简介
  19====
  20本文档概述了Linux SCSI中间层与SCSI底层驱动之间的接口。底层
  21驱动（LLD）通常被称为主机总线适配器（HBA）驱动或主机驱动
  22（HD）。在该上下文中，“主机”指的是计算机IO总线（例如：PCI总
  23线或ISA总线）与SCSI传输层中单个SCSI启动器端口之间的桥梁。
  24“启动器”端口（SCSI术语，参考SAM-3：http://www.t10.org）向
  25“目标”SCSI端口（例如：磁盘）发送SCSI命令。在一个运行的系统
  26中存在多种底层驱动（LLDs），但每种硬件类型仅对应一种底层驱动
  27（LLD）。大多数底层驱动可以控制一个或多个SCSI HBA。部分HBA
  28内部集成多个主机控制器。
  29
  30在某些情况下，SCSI传输层本身是已存在于Linux中的外部总线子系
  31统（例如：USB和ieee1394）。在此类场景下，SCSI子系统的底层驱
  32动将作为与其他驱动子系统的软件桥接层。典型示例包括
  33usb-storage驱动（位于drivers/usb/storage目录）以
  34及ieee1394/sbp2驱动（位于 drivers/ieee1394 目录）。
  35
  36例如，aic7xxx底层驱动负责控制基于Adaptec公司7xxx芯片系列的
  37SCSI并行接口（SPI）控制器。aic7xxx底层驱动可以内建到内核中
  38或作为模块加载。一个Linux系统中只能运行一个aic7xxx底层驱动
  39程序，但他可能控制多个主机总线适配器（HBA）。这些HBA可能位于
  40PCI扩展卡或内置于主板中（或两者兼有）。某些基于aic7xxx的HBA
  41采用双控制器设计，因此会呈现为两个SCSI主机适配器。与大多数现
  42代HBA相同，每个aic7xxx控制器都拥有其独立的PCI设备地址。[SCSI
  43主机与PCI设备之间一一对应虽然常见，但并非强制要求（例如ISA适
  44配器就不适用此规则）。]
  45
  46SCSI中间层将SCSI底层驱动（LLD）与其他层（例如SCSI上层驱动以
  47及块层）隔离开来。
  48
  49本文档的版本大致与Linux内核2.6.8相匹配。
  50
  51文档
  52====
  53内核源码树中设有专用的SCSI文档目录，通常位于
  54Documentation/scsi目录下。大多数文档采用
  55reStructuredText格式。本文档名为
  56scsi_mid_low_api.rst，可在该目录中找到。该文档的最新版本可
  57以访问 https://docs.kernel.org/scsi/scsi_mid_low_api.html
  58查阅。许多底层驱动（LLD）的文档也位于Documentation/scsi目录
  59下（例如aic7xxx.rst）。SCSI中间层的简要说明见scsi.rst文件，
  60该文档包含指向Linux Kernel 2.4系列SCSI子系统的文档链接。此
  61外还收录了两份SCSI上层驱动文档：st.rst（SCSI磁带驱动）与
  62scsi-generic.rst（用通用SCSI（sg）驱动）。
  63
  64部分底层驱动的文档（或相关URL）可能嵌在C源代码文件或与其
  65源码同位于同一目录下。例如，USB大容量存储驱动的文档链接可以在
  66目录/usr/src/linux/drivers/usb/storage下找到。
  67
  68驱动程序结构
  69============
  70传统上，SCSI子系统的底层驱动（LLD）至少包含drivers/scsi
  71目录下的两个文件。例如，一个名为“xyz”的驱动会包含一个头文件
  72xyz.h和一个源文件xyz.c。[实际上所有代码完全可以合并为单个
  73文件，头文件并非必需的。] 部分需要跨操作系统移植的底层驱动会
  74采用更复杂的文件结构。例如，aic7xxx驱动，就为通用代码与操作
  75系统专用代码（如FreeBSD和Linux）分别创建了独立的文件。此类
  76驱动通常会在drivers/scsi目录下拥有自己单独的子目录。
  77
  78当需要向Linux内核添加新的底层驱动（LLD）时，必须留意
  79drivers/scsi目录下的两个文件：Makefile以及Kconfig。建议参
  80考现有底层驱动的代码组织方式。
  81
  82随着Linux内核2.5开发内核逐步演进为2.6系列的生产版本，该接口
  83也引入了一些变化。以驱动初始化代码为例，现有两种模型可用。其
  84中旧模型与Linux内核2.4的实现相似，他基于在加载HBA驱动时检测
  85到的主机，被称为“被动（passive）”初始化模型。而新的模型允许
  86在底层驱动（LLD）的生命周期内动态拔插HBA，这种方式被称为“热
  87插拔（hotplug）”初始化模型。推荐使用新的模型，因为他既能处理
  88传统的永久连接SCSI设备，也能处理现代支持热插拔的类SCSI设备
  89（例如通过USB或IEEE 1394连接的数码相机）。这两种初始化模型将
  90在后续的章节中分别讨论。
  91
  92SCSI底层驱动（LLD）通过以下3种方式与SCSI子系统进行交互：
  93
  94  a) 直接调用由SCSI中间层提供的接口函数
  95  b) 将一组函数指针传递给中间层提供的注册函数，中间层将在
  96     后续运行的某个时刻调用这些函数。这些函数由LLD实现。
  97  c) 直接访问中间层维护的核心数据结构
  98
  99a）组中所涉及的所有函数，均列于下文“中间层提供的函数”章节中。
 100
 101b）组中涉及的所有函数均列于下文名为“接口函数”的章节中。这些
 102函数指针位于结构体struct scsi_host_template中，该结构体实
 103例会被传递给scsi_host_alloc()。对于LLD未实现的接口函数，应
 104对struct scsi_host_template中的对应成员赋NULL。如果在文件
 105作用域定义一个struct scsi_host_template的实例，没有显式初
 106始化的函数指针成员将自动设置为NULL。
 107
 108c）组中提到的用法在“热插拔”环境中尤其需要谨慎处理。LLD必须
 109明确知晓这些与中间层及其他层级共享的数据结构的生命周期。
 110
 111LLD中定义的所有函数以及在文件作用域内定义的所有数据都应声明
 112为static。例如，在一个名为“xxx”的LLD中的sdev_init()函数定
 113义如下：
 114``static int xxx_sdev_init(struct scsi_device * sdev) { /* code */ }``
 115
 116热插拔初始化模型
 117================
 118在该模型中，底层驱动（LLD）控制SCSI主机适配器在子系统中的注
 119册与注销时机。主机最早可以在驱动初始化阶段被注册，最晚可以在
 120驱动卸载时被移除。通常，驱动会响应来自sysfs probe()的回调，
 121表示已检测到一个主机总线适配器（HBA）。在确认该新设备是LLD的
 122目标设备后，LLD初始化HBA，并将一个新的SCSI主机适配器注册到
 123SCSI中间层。
 124
 125在LLD初始化过程中，驱动应当向其期望发现HBA的IO总线（例如PCI
 126总线）进行注册。该操作通常可以通过sysfs完成。任何驱动参数（
 127特别是那些在驱动加载后仍可修改的参数）也可以在此时通过sysfs
 128注册。当LLD注册其首个HBA时，SCSI中间层首次感受到该LLD的存在。
 129
 130在稍后的某个时间点，当LLD检测到新的HBA时，接下来在LLD与SCSI
 131中间层之间会发生一系列典型的调用过程。该示例展示了中间层如何
 132扫描新引入的HBA，在该过程中发现了3个SCSI设备，其中只有前两个
 133设备有响应::
 134
 135	HBA探测：假设在扫描中发现2个SCSI设备
 136    底层驱动               中间层               底层驱动
 137    =======---------------======---------------=======
 138    scsi_host_alloc()  -->
 139    scsi_add_host()  ---->
 140    scsi_scan_host()  -------+
 141			    |
 142			sdev_init()
 143			sdev_configure() -->  scsi_change_queue_depth()
 144			    |
 145			sdev_init()
 146			sdev_configure()
 147			    |
 148			sdev_init()   ***
 149			sdev_destroy() ***
 150
 151
 152    *** 对于SCSI中间层尝试扫描但未响应的SCSI设备，系统调用
 153	sdev_init()和sdev_destroy()函数对。
 154
 155如果LLD期望调整默认队列设置，可以在其sdev_configure()例程
 156中调用scsi_change_queue_depth()。
 157
 158当移除一个HBA时，可能是由于卸载LLD模块相关的有序关闭（例如通
 159过rmmod命令），也可能是由于sysfs的remove()回调而触发的“热拔
 160插”事件。无论哪种情况，其执行顺序都是相同的::
 161
 162	    HBA移除：假设连接了2个SCSI设备
 163    底层驱动                     中间层                 底层驱动
 164    =======---------------------======-----------------=======
 165    scsi_remove_host() ---------+
 166				|
 167			sdev_destroy()
 168			sdev_destroy()
 169    scsi_host_put()
 170
 171LLD用于跟踪struct Scsi_Host的实例可能会非常有用
 172（scsi_host_alloc()返回的指针）。这些实例由中间层“拥有”。
 173当引用计数为零时，struct Scsi_Host实例会被
 174scsi_host_put()释放。
 175
 176HBA的热插拔是一个特殊的场景，特别是当HBA下的磁盘正在处理已挂
 177载文件系统上的SCSI命令时。为了应对其中的诸多问题，中间层引入
 178了引用计数逻辑。具体内容参考下文关于引用计数的章节。
 179
 180热插拔概念同样适用于SCSI设备。目前，当添加HBA时，
 181scsi_scan_host() 函数会扫描该HBA所属SCSI传输通道上的设备。在
 182新型SCSI传输协议中，HBA可能在扫描完成后才检测到新的SCSI设备。
 183LLD可通过以下步骤通知中间层新SCSI设备的存在::
 184
 185		    SCSI设备热插拔
 186    底层驱动                   中间层                 底层驱动
 187    =======-------------------======-----------------=======
 188    scsi_add_device()  ------+
 189			    |
 190			sdev_init()
 191			sdev_configure()   [--> scsi_change_queue_depth()]
 192
 193类似的，LLD可能会感知到某个SCSI设备已经被移除（拔出）或与他的连
 194接已中断。某些现有的SCSI传输协议（例如SPI）可能直到后续SCSI命令
 195执行失败时才会发现设备已经被移除，中间层会将该设备设置为离线状态。
 196若LLD检测到SCSI设备已经被移除，可通过以下流程触发上层对该设备的
 197移除操作::
 198
 199		    SCSI设备热拔插
 200    底层驱动                   中间层                 底层驱动
 201    =======-------------------======-----------------=======
 202    scsi_remove_device() -------+
 203				|
 204			sdev_destroy()
 205
 206对于LLD而言，跟踪struct scsi_device实例可能会非常有用（该结构
 207的指针会作为参数传递给sdev_init()和sdev_configure()回调函数）。
 208这些实例的所有权归属于中间层（mid-level）。struct scsi_device
 209实例在sdev_destroy()执行后释放。
 210
 211引用计数
 212========
 213Scsi_Host结构体已引入引用计数机制。该机制将struct Scsi_Host
 214实例的所有权分散到使用他的各SCSI层，而此前这类实例完全由中间
 215层独占管理。底层驱动（LLD）通常无需直接操作这些引用计数，仅在
 216某些特定场景下可能需要介入。
 217
 218与struct Scsi_Host相关的引用计数函数主要有以下3种：
 219
 220  - scsi_host_alloc():
 221	返回指向新实例的指针，该实例的引用计数被设置为1。
 222
 223  - scsi_host_get():
 224	给定实例的引用计数加1。
 225
 226  - scsi_host_put():
 227	给定实例的引用计数减1。如果引用计数减少到0，则释放该实例。
 228
 229scsi_device结构体现已引入引用计数机制。该机制将
 230struct scsi_device实例的所有权分散到使用他的各SCSI层，而此
 231前这类实例完全由中间层独占管理。相关访问函数声明详见
 232include/scsi/scsi_device.h文件末尾部分。若LLD需要保留
 233scsi_device实例的指针副本，则应调用scsi_device_get()增加其
 234引用计数；不再需要该指针时，可通过scsi_device_put()递减引用
 235计数（该操作可能会导致该实例被释放）。
 236
 237.. Note::
 238
 239	struct Scsi_Host实际上包含两个并行维护的引用计数器，该引
 240	用计数由这些函数共同操作。
 241
 242编码规范
 243========
 244
 245首先，Linus Torvalds关于C语言编码风格的观点可以在
 246Documentation/process/coding-style.rst文件中找到。
 247
 248此外，在相关gcc编译器支持的前提下，鼓励使用大多数C99标准的增强
 249特性。因此，在适当的情况下鼓励使用C99风格的结构体和数组初始化
 250方式。但不要过度使用，目前对可变长度数组（VLA）的支持还待完善。
 251一个例外是 ``//`` 风格的注释；在Linux中倾向于使
 252用 ``/*...*/`` 注释格式。
 253
 254对于编写良好、经过充分测试且有完整文档的代码不需要重新格式化
 255以符合上述规范。例如，aic7xxx驱动是从FreeBSD和Adaptec代码库
 256移植到Linux的。毫无疑问，FreeBSD和Adaptec遵循其原有的编码规
 257范。
 258
 259
 260中间层提供的函数
 261================
 262这些函数由SCSI中间层提供，供底层驱动（LLD）调用。这些函数的名
 263称（即入口点）均已导出，因此作为模块加载的LLD可以访问他们。内
 264核会确保在任何LLD初始化之前，SCSI中间层已先行加载并完成初始化。
 265下文按字母顺序列出这些函数，其名称均以 ``scsi_`` 开头。
 266
 267摘要：
 268
 269  - scsi_add_device - 创建新的SCSI逻辑单元（LU）设备实例
 270  - scsi_add_host - 执行sysfs注册并设置传输类
 271  - scsi_change_queue_depth - 调整SCSI设备队列深度
 272  - scsi_bios_ptable - 返回块设备分区表的副本
 273  - scsi_block_requests - 阻止向指定主机提交新命令
 274  - scsi_host_alloc - 分配引用计数为1的新SCSI主机适配器实例scsi_host
 275  - scsi_host_get - 增加SCSI主机适配器实例的引用计数
 276  - scsi_host_put - 减少SCSI主机适配器的引用计数（归零时释放）
 277  - scsi_remove_device - 卸载并移除SCSI设备
 278  - scsi_remove_host - 卸载并移除主机控制器下的所有SCSI设备
 279  - scsi_report_bus_reset - 报告检测到的SCSI总线复位事件
 280  - scsi_scan_host - 执行SCSI总线扫描
 281  - scsi_track_queue_full - 跟踪连续出现的队列满事件
 282  - scsi_unblock_requests - 恢复向指定主机提交命令
 283
 284详细信息::
 285
 286    /**
 287    * scsi_add_device - 创建新的SCSI逻辑单元（LU）设备实例
 288    * @shost:   指向SCSI主机适配器实例的指针
 289    * @channel: 通道号（通常为0）
 290    * @id:      目标ID号
 291    * @lun:     逻辑单元号（LUN）
 292    *
 293    *      返回指向新的struct scsi_device实例的指针，
 294    *      如果出现异常（例如在给定地址没有设备响应），则返
 295    *      回ERR_PTR(-ENODEV)
 296    *
 297    *      是否阻塞：是
 298    *
 299    *      注意事项：本函数通常在添加HBA的SCSI总线扫描过程
 300    *      中由系统内部调用（即scsi_scan_host()执行期间）。因此，
 301    *      仅应在以下情况调用：HBA在scsi_scan_host()完成扫描后，
 302    *      又检测到新的SCSI设备（逻辑单元）。若成功执行，本次调用
 303    *      可能会触发LLD的以下回调函数：sdev_init()以及
 304    *      sdev_configure()
 305    *
 306    *      函数定义：drivers/scsi/scsi_scan.c
 307    **/
 308    struct scsi_device * scsi_add_device(struct Scsi_Host *shost,
 309                                        unsigned int channel,
 310                                        unsigned int id, unsigned int lun)
 311
 312
 313    /**
 314    * scsi_add_host - 执行sysfs注册并设置传输类
 315    * @shost:   指向SCSI主机适配器实例的指针
 316    * @dev:     指向scsi类设备结构体（struct device）的指针
 317    *
 318    *      成功返回0，失败返回负的errno（例如：-ENOMEM）
 319    *
 320    *      是否阻塞：否
 321    *
 322    *      注意事项：仅在“热插拔初始化模型”中需要调用，且必须在
 323    *      scsi_host_alloc()成功执行后调用。该函数不会扫描总线；
 324    *      总线扫描可通过调用scsi_scan_host()或其他传输层特定的
 325    *      方法完成。在调用该函数之前，LLD必须先设置好传输模板，
 326    *      并且只能在调用该函数之后才能访问传输类
 327    *      （transport class）相关的数据结构。
 328    *
 329    *      函数定义：drivers/scsi/hosts.c
 330    **/
 331    int scsi_add_host(struct Scsi_Host *shost, struct device * dev)
 332
 333
 334    /**
 335    * scsi_change_queue_depth - 调整SCSI设备队列深度
 336    * @sdev:       指向要更改队列深度的SCSI设备的指针
 337    * @tags        如果启用了标记队列，则表示允许的标记数，
 338    *              或者在非标记模式下，LLD可以排队的命令
 339    *              数（如 cmd_per_lun）。
 340    *
 341    *      无返回
 342    *
 343    *      是否阻塞：否
 344    *
 345    *      注意事项：可以在任何时刻调用该函数，只要该SCSI设备受该LLD控
 346    *      制。[具体来说，可以在sdev_configure()执行期间或之后，且在
 347    *      sdev_destroy()执行之前调用。] 该函数可安全地在中断上下文中
 348    *      调用。
 349    *
 350    *      函数定义：drivers/scsi/scsi.c [更多注释请参考源代码]
 351    **/
 352    int scsi_change_queue_depth(struct scsi_device *sdev, int tags)
 353
 354
 355    /**
 356    * scsi_bios_ptable - 返回块设备分区表的副本
 357    * @dev:        指向块设备的指针
 358    *
 359    *      返回指向分区表的指针，失败返回NULL
 360    *
 361    *      是否阻塞：是
 362    *
 363    *      注意事项：调用方负责释放返回的内存（通过 kfree() 释放）
 364    *
 365    *      函数定义：drivers/scsi/scsicam.c
 366    **/
 367    unsigned char *scsi_bios_ptable(struct block_device *dev)
 368
 369
 370    /**
 371    * scsi_block_requests - 阻止向指定主机提交新命令
 372    *
 373    * @shost: 指向特定主机的指针，用于阻止命令的发送
 374    *
 375    *      无返回
 376    *
 377    *      是否阻塞：否
 378    *
 379    *      注意事项：没有定时器或其他任何机制可以解除阻塞，唯一的方式
 380    *      是由LLD调用scsi_unblock_requests()方可恢复。
 381    *
 382    *      函数定义：drivers/scsi/scsi_lib.c
 383    **/
 384    void scsi_block_requests(struct Scsi_Host * shost)
 385
 386
 387    /**
 388    * scsi_host_alloc - 创建SCSI主机适配器实例并执行基础初始化
 389    * @sht:        指向SCSI主机模板的指针
 390    * @privsize:   在hostdata数组中分配的额外字节数（该数组是返
 391    *              回的Scsi_Host实例的最后一个成员）
 392    *
 393    *      返回指向新的Scsi_Host实例的指针，失败返回NULL
 394    *
 395    *      是否阻塞：是
 396    *
 397    *      注意事项：当此调用返回给LLD时，该主机适配器上的
 398    *      SCSI总线扫描尚未进行。hostdata数组（默认长度为
 399    *      零）是LLD专属的每主机私有区域，供LLD独占使用。
 400    *      两个相关的引用计数都被设置为1。完整的注册（位于
 401    *      sysfs）与总线扫描由scsi_add_host()和
 402    *      scsi_scan_host()稍后执行。
 403    *      函数定义：drivers/scsi/hosts.c
 404    **/
 405    struct Scsi_Host * scsi_host_alloc(const struct scsi_host_template * sht,
 406                                       int privsize)
 407
 408
 409    /**
 410    * scsi_host_get - 增加SCSI主机适配器实例的引用计数
 411    * @shost:   指向Scsi_Host实例的指针
 412    *
 413    *      无返回
 414    *
 415    *      是否阻塞：目前可能会阻塞，但可能迭代为不阻塞
 416    *
 417    *      注意事项：会同时增加struct Scsi_Host中两个子对
 418    *      象的引用计数
 419    *
 420    *      函数定义：drivers/scsi/hosts.c
 421    **/
 422    void scsi_host_get(struct Scsi_Host *shost)
 423
 424
 425    /**
 426    * scsi_host_put - 减少SCSI主机适配器实例的引用计数
 427    *                 （归零时释放）
 428    * @shost:   指向Scsi_Host实例的指针
 429    *
 430    *      无返回
 431    *
 432    *      是否阻塞：当前可能会阻塞，但可能会改为不阻塞
 433    *
 434    *      注意事项：实际会递减两个子对象中的计数。当后一个引用
 435    *      计数归零时系统会自动释放Scsi_Host实例。
 436    *      LLD 无需关注Scsi_Host实例的具体释放时机，只要在平衡
 437    *      引用计数使用后不再访问该实例即可。
 438    *      函数定义：drivers/scsi/hosts.c
 439    **/
 440    void scsi_host_put(struct Scsi_Host *shost)
 441
 442
 443    /**
 444    * scsi_remove_device - 卸载并移除SCSI设备
 445    * @sdev:      指向SCSI设备实例的指针
 446    *
 447    *      返回值：成功返回0，若设备未连接，则返回-EINVAL
 448    *
 449    *      是否阻塞：是
 450    *
 451    *      如果LLD发现某个SCSI设备（逻辑单元，lu）已经被移除，
 452    *      但其主机适配器实例依旧存在，则可以请求移除该SCSI设备。
 453    *      如果该调用成功将触发sdev_destroy()回调函数的执行。调
 454    *      用完成后，sdev将变成一个无效的指针。
 455    *
 456    *      函数定义：drivers/scsi/scsi_sysfs.c
 457    **/
 458    int scsi_remove_device(struct scsi_device *sdev)
 459
 460
 461    /**
 462    * scsi_remove_host - 卸载并移除主机控制器下的所有SCSI设备
 463    * @shost:      指向SCSI主机适配器实例的指针
 464    *
 465    *      返回值：成功返回0，失败返回1（例如：LLD正忙？？）
 466    *
 467    *      是否阻塞：是
 468    *
 469    *      注意事项：仅在使用“热插拔初始化模型”时调用。应在调用
 470    *      scsi_host_put()前调用。
 471    *
 472    *      函数定义：drivers/scsi/hosts.c
 473    **/
 474    int scsi_remove_host(struct Scsi_Host *shost)
 475
 476
 477    /**
 478    * scsi_report_bus_reset - 报告检测到的SCSI总线复位事件
 479    * @shost: 指向关联的SCSI主机适配器的指针
 480    * @channel: 发生SCSI总线复位的通道号
 481    *
 482    *      返回值：无
 483    *
 484    *      是否阻塞：否
 485    *
 486    *      注意事项：仅当复位来自未知来源时才需调用此函数。
 487    *      由SCSI中间层发起的复位无需调用，但调用也不会导
 488    *      致副作用。此函数的主要作用是确保系统能正确处理
 489    *      CHECK_CONDITION状态。
 490    *
 491    *      函数定义：drivers/scsi/scsi_error.c
 492    **/
 493    void scsi_report_bus_reset(struct Scsi_Host * shost, int channel)
 494
 495
 496    /**
 497    * scsi_scan_host - 执行SCSI总线扫描
 498    * @shost: 指向SCSI主机适配器实例的指针
 499    *
 500    *      是否阻塞：是
 501    *
 502    *      注意事项：应在调用scsi_add_host()后调用
 503    *
 504    *      函数定义：drivers/scsi/scsi_scan.c
 505    **/
 506    void scsi_scan_host(struct Scsi_Host *shost)
 507
 508
 509    /**
 510    * scsi_track_queue_full - 跟踪指定设备上连续的QUEUE_FULL
 511    *                         事件，以判断是否需要及何时调整
 512    *                         该设备的队列深度。
 513    * @sdev:  指向SCSI设备实例的指针
 514    * @depth: 当前该设备上未完成的SCSI命令数量（不包括返回
 515    *         QUEUE_FULL的命令）
 516    *
 517    *      返回值：0  - 当前队列深度无需调整
 518    *              >0 - 需要将队列深度调整为此返回值指定的新深度
 519    *              -1 - 需要回退到非标记操作模式，并使用
 520    *                   host->cmd_per_lun作为非标记命令队列的
 521    *                   深度限制
 522    *
 523    *      是否阻塞：否
 524    *
 525    *      注意事项：LLD可以在任意时刻调用该函数。系统将自动执行“正确
 526	*               的处理流程”；该函数支持在中断上下文中安全地调用
 527    *
 528    *      函数定义：drivers/scsi/scsi.c
 529    **/
 530    int scsi_track_queue_full(struct scsi_device *sdev, int depth)
 531
 532
 533    /**
 534    * scsi_unblock_requests - 恢复向指定主机适配器提交命令
 535    *
 536    * @shost: 指向要解除阻塞的主机适配器的指针
 537    *
 538    *      返回值：无
 539    *
 540    *      是否阻塞：否
 541    *
 542    *      函数定义：drivers/scsi/scsi_lib.c
 543    **/
 544    void scsi_unblock_requests(struct Scsi_Host * shost)
 545
 546
 547
 548接口函数
 549========
 550接口函数由底层驱动（LLD）定义实现，其函数指针保存在
 551struct scsi_host_template实例中，并将该实例传递给
 552scsi_host_alloc()。
 553部分接口函数为必选实现项。所有
 554接口函数都应声明为static，约定俗成的命名规则如下，
 555驱动“xyz”应将其sdev_configure()函数声明为::
 556
 557	static int xyz_sdev_configure(struct scsi_device * sdev);
 558
 559其余接口函数的命名规范均依此类推。
 560
 561需将该函数指针赋值给“struct scsi_host_template”实例
 562的‘sdev_configure’成员变量中，并将该结构体实例指针传
 563递到中间层的scsi_host_alloc()函数。
 564
 565各个接口函数的详细说明可参考include/scsi/scsi_host.h
 566文件，具体描述位于“struct scsi_host_template”结构体
 567各个成员的上方。在某些情况下，scsi_host.h头文件中的描
 568述比本文提供的更为详尽。
 569
 570以下按字母顺序列出所有接口函数及其说明。
 571
 572摘要：
 573
 574  - bios_param - 获取磁盘的磁头/扇区/柱面参数
 575  - eh_timed_out - SCSI命令超时回调
 576  - eh_abort_handler - 中止指定的SCSI命令
 577  - eh_bus_reset_handler - 触发SCSI总线复位
 578  - eh_device_reset_handler - 执行SCSI设备复位
 579  - eh_host_reset_handler - 复位主机（主机总线适配器）
 580  - info - 提供指定主机适配器的相关信息
 581  - ioctl - 驱动可响应ioctl控制命令
 582  - proc_info - 支持/proc/scsi/{驱动名}/{主机号}文件节点的读写操作
 583  - queuecommand - 将SCSI命令提交到主机控制器，命令执行完成后调用‘done’回调
 584  - sdev_init - 在向新设备发送SCSI命令前的初始化
 585  - sdev_configure - 设备挂载后的精细化微调
 586  - sdev_destroy - 设备即将被移除前的清理
 587
 588
 589详细信息::
 590
 591    /**
 592    *      bios_param - 获取磁盘的磁头/扇区/柱面参数
 593    *      @sdev: 指向SCSI设备实例的指针（定义于
 594    *             include/scsi/scsi_device.h中）
 595    *      @bdev: 指向块设备实例的指针（定义于fs.h中）
 596    *      @capacity: 设备容量（以512字节扇区为单位）
 597    *      @params: 三元数组用于保存输出结果：
 598    *              params[0]：磁头数量（最大255）
 599    *              params[1]：扇区数量（最大63）
 600    *              params[2]：柱面数量
 601    *
 602    *      返回值：被忽略
 603    *
 604    *      并发安全声明: 无锁
 605    *
 606    *      调用上下文说明: 进程上下文（sd）
 607    *
 608    *      注意事项: 若未提供此函数，系统将基于READ CAPACITY
 609    *      使用默认几何参数。params数组已预初始化伪值，防止函
 610    *      数无输出。
 611    *
 612    *      可选实现说明：由LLD选择性定义
 613    **/
 614    int bios_param(struct scsi_device * sdev, struct block_device *bdev,
 615		    sector_t capacity, int params[3])
 616
 617
 618    /**
 619    *      eh_timed_out - SCSI命令超时回调
 620    *      @scp: 标识超时的命令
 621    *
 622    *      返回值:
 623    *
 624    *      EH_HANDLED:             我已修复该错误，请继续完成该命令
 625    *      EH_RESET_TIMER:         我需要更多时间，请重置定时器并重新开始计时
 626    *      EH_NOT_HANDLED          开始正常的错误恢复流程
 627    *
 628    *      并发安全声明: 无锁
 629    *
 630    *      调用上下文说明: 中断上下文
 631    *
 632    *      注意事项: 该回调函数为LLD提供一个机会进行本地
 633    *      错误恢复处理。此处的恢复仅限于判断该未完成的命
 634    *      令是否还有可能完成。此回调中不允许中止或重新启
 635    *      动该命令。
 636    *
 637    *      可选实现说明：由LLD选择性定义
 638    **/
 639    int eh_timed_out(struct scsi_cmnd * scp)
 640
 641
 642    /**
 643    *      eh_abort_handler - 中止指定的SCSI命令
 644    *      @scp: 标识要中止的命令
 645    *
 646    *      返回值：如果命令成功中止，则返回SUCCESS，否则返回FAILED
 647    *
 648    *      并发安全声明: 无锁
 649    *
 650    *      调用上下文说明: 内核线程
 651    *
 652    *      注意事项: 该函数仅在命令超时时才被调用。
 653    *
 654    *      可选实现说明：由LLD选择性定义
 655    **/
 656    int eh_abort_handler(struct scsi_cmnd * scp)
 657
 658
 659    /**
 660    *      eh_bus_reset_handler -  发起SCSI总线复位
 661    *      @scp: 包含该设备的SCSI总线应进行重置
 662    *
 663    *      返回值：重置成功返回SUCCESS；否则返回FAILED
 664    *
 665    *      并发安全声明: 无锁
 666    *
 667    *      调用上下文说明: 内核线程
 668    *
 669    *      注意事项: 由SCSI错误处理线程（scsi_eh）调用。
 670    *      在错误处理期间，当前主机适配器的所有IO请求均
 671    *      被阻塞。
 672    *
 673    *      可选实现说明：由LLD选择性定义
 674    **/
 675    int eh_bus_reset_handler(struct scsi_cmnd * scp)
 676
 677
 678    /**
 679    *      eh_device_reset_handler - 发起SCSI设备复位
 680    *      @scp: 指定将被重置的SCSI设备
 681    *
 682    *      返回值：如果命令成功中止返回SUCCESS，否则返回FAILED
 683    *
 684    *      并发安全声明: 无锁
 685    *
 686    *      调用上下文说明: 内核线程
 687    *
 688    *      注意事项: 由SCSI错误处理线程（scsi_eh）调用。
 689    *      在错误处理期间，当前主机适配器的所有IO请求均
 690    *      被阻塞。
 691    *
 692    *      可选实现说明：由LLD选择性定义
 693    **/
 694    int eh_device_reset_handler(struct scsi_cmnd * scp)
 695
 696
 697    /**
 698    *      eh_host_reset_handler - 复位主机（主机总线适配器）
 699    *      @scp: 管理该设备的SCSI主机适配器应该被重置
 700    *
 701    *      返回值：如果命令成功中止返回SUCCESS，否则返回FAILED
 702    *
 703    *      并发安全声明: 无锁
 704    *
 705    *      调用上下文说明: 内核线程
 706    *
 707    *      注意事项: 由SCSI错误处理线程（scsi_eh）调用。
 708    *      在错误处理期间，当前主机适配器的所有IO请求均
 709    *      被阻塞。当使用默认的eh_strategy策略时，如果
 710    *      _abort_、_device_reset_、_bus_reset_和该处
 711    *      理函数均未定义（或全部返回FAILED），系统强制
 712    *      该故障设备处于离线状态
 713    *
 714    *      可选实现说明：由LLD选择性定义
 715    **/
 716    int eh_host_reset_handler(struct scsi_cmnd * scp)
 717
 718
 719    /**
 720    *      info - 提供给定主机适配器的详细信息：驱动程序名称
 721    *             以及用于区分不同主机适配器的数据结构
 722    *      @shp: 指向目标主机的struct Scsi_Host实例
 723    *
 724    *      返回值：返回以NULL结尾的ASCII字符串。[驱动
 725    *      负责管理返回的字符串所在内存并确保其在整个
 726    *      主机适配器生命周期内有效。]
 727    *
 728    *      并发安全声明: 无锁
 729    *
 730    *      调用上下文说明: 进程上下文
 731    *
 732    *      注意事项: 通常提供诸如I/O地址或中断号
 733    *      等PCI或ISA信息。如果未实现该函数，则
 734    *      默认使用struct Scsi_Host::name 字段。
 735    *      返回的字符串应为单行（即不包含换行符）。
 736    *      通过SCSI_IOCTL_PROBE_HOST ioctl可获
 737    *      取该函数返回的字符串，如果该函数不可用，
 738    *      则ioctl返回struct Scsi_Host::name中
 739    *      的字符串。
 740
 741    *
 742    *      可选实现说明：由LLD选择性定义
 743    **/
 744    const char * info(struct Scsi_Host * shp)
 745
 746
 747    /**
 748    *      ioctl - 驱动可响应ioctl控制命令
 749    *      @sdp: ioctl操作针对的SCSI设备
 750    *      @cmd: ioctl命令号
 751    *      @arg: 指向用户空间读写数据的指针。由于他指向用
 752    *            户空间，必须使用适当的内核函数
 753    *            （如 copy_from_user()）。按照Unix的风
 754    *            格，该参数也可以视为unsigned long 类型。
 755    *
 756    *      返回值：如果出错则返回负的“errno”值。返回0或正值表
 757    *      示成功，并将返回值传递给用户空间。
 758    *
 759    *      并发安全声明：无锁
 760    *
 761    *      调用上下文说明：进程上下文
 762    *
 763    *      注意事项：SCSI子系统使用“逐层下传
 764    *      （trickle down）”的ioctl模型。
 765    *      用户层会对上层驱动设备节点
 766    *      （例如/dev/sdc）发起ioctl()调用，
 767    *      如果上层驱动无法识别该命令，则将其
 768    *      传递给SCSI中间层，若中间层也无法识
 769    *      别，则再传递给控制该设备的LLD。
 770    *      根据最新的Unix标准，对于不支持的
 771    *      ioctl()命令，应返回-ENOTTY。
 772    *
 773    *      可选实现说明：由LLD选择性定义
 774    **/
 775    int ioctl(struct scsi_device *sdp, int cmd, void *arg)
 776
 777
 778    /**
 779    *      proc_info - 支持/proc/scsi/{驱动名}/{主机号}文件节点的读写操作
 780    *      @buffer: 输入或出的缓冲区锚点（writeto1_read0==0表示向buffer写
 781    *               入，writeto1_read0==1表示由buffer读取）
 782    *      @start: 当writeto1_read0==0时，用于指定驱动实际填充的起始位置；
 783    *              当writeto1_read0==1时被忽略。
 784    *      @offset: 当writeto1_read0==0时，表示用户关注的数据在缓冲区中的
 785    *               偏移。当writeto1_read0==1时忽略。
 786    *      @length: 缓冲区的最大（或实际使用）长度
 787    *      @host_no: 目标SCSI Host的编号（struct Scsi_Host::host_no）
 788    *      @writeto1_read0: 1 -> 表示数据从用户空间写入驱动
 789    *                        （例如，“echo some_string > /proc/scsi/xyz/2”）
 790    *                       0 -> 表示用户从驱动读取数据
 791    *                        （例如，“cat /proc/scsi/xyz/2”）
 792    *
 793    *      返回值：当writeto1_read0==1时返回写入长度。否则，
 794    *      返回从offset偏移开始输出到buffer的字符数。
 795    *
 796    *      并发安全声明：无锁
 797    *
 798    *      调用上下文说明：进程上下文
 799    *
 800    *      注意事项：该函数由scsi_proc.c驱动，与proc_fs交互。
 801    *      当前SCSI子系统可移除对proc_fs的支持，相关配置选。
 802    *
 803    *      可选实现说明：由LLD选择性定义
 804    **/
 805    int proc_info(char * buffer, char ** start, off_t offset,
 806                  int length, int host_no, int writeto1_read0)
 807
 808
 809    /**
 810    *      queuecommand - 将SCSI命令提交到主机控制器，命令执行完成后调用scp->scsi_done回调函数
 811    *      @shost: 指向目标SCSI主机控制器
 812    *      @scp: 指向待处理的SCSI命令
 813    *
 814    *      返回值：成功返回0。
 815    *
 816    *      如果发生错误，则返回：
 817    *
 818    *      SCSI_MLQUEUE_DEVICE_BUSY表示设备队列满，
 819    *      SCSI_MLQUEUE_HOST_BUSY表示整个主机队列满
 820    *
 821    *      在这两种情况下，中间层将自动重新提交该I/O请求
 822    *
 823    *      - 若返回SCSI_MLQUEUE_DEVICE_BUSY，则仅暂停该
 824    *      特定设备的命令处理，当该设备的某个命令完成返回
 825    *      时（或在短暂延迟后如果没有其他未完成命令）将恢
 826    *      复其处理。其他设备的命令仍正常继续处理。
 827    *
 828    *      - 若返回SCSI_MLQUEUE_HOST_BUSY，将暂停该主机
 829    *      的所有I/O操作，当任意命令从该主机返回时（或在
 830    *      短暂延迟后如果没有其他未完成命令）将恢复处理。
 831    *
 832    *      为了与早期的queuecommand兼容，任何其他返回值
 833    *      都被视作SCSI_MLQUEUE_HOST_BUSY。
 834    *
 835    *      对于其他可立即检测到的错误，可通过以下流程处
 836    *      理：设置scp->result为适当错误值，调用scp->scsi_done
 837    *      回调函数，然后该函数返回0。若该命令未立即执行（LLD
 838    *      正在启动或将要启动该命令），则应将scp->result置0并
 839    *      返回0。
 840    *
 841    *      命令所有权说明：若驱动返回0，则表示驱动获得该命令的
 842    *      所有权，
 843    *      并必须确保最终执行scp->scsi_done回调函数。注意：驱动
 844    *      可以在返回0之前调用scp->scsi_done，但一旦调用该回
 845    *      调函数后，就只能返回0。若驱动返回非零值，则禁止在任何时
 846    *      刻执行该命令的scsi_done回调函数。
 847    *
 848    *      并发安全声明：在2.6.36及更早的内核版本中，调用该函数时持有
 849    *      struct Scsi_Host::host_lock锁（通过“irqsave”获取中断安全的自旋锁），
 850    *      并且返回时仍需保持该锁；从Linux 2.6.37开始，queuecommand
 851    *      将在无锁状态下被调用。
 852    *
 853    *      调用上下文说明：在中断（软中断）或进程上下文中
 854    *
 855    *      注意事项：该函数执行应当非常快速，通常不会等待I/O
 856    *      完成。因此scp->scsi_done回调函数通常会在该函数返
 857    *      回后的某个时刻被调用（经常直接从中断服务例程中调用）。
 858    *      某些情况下（如模拟SCSI INQUIRY响应的伪适配器驱动），
 859    *      scp->scsi_done回调可能在该函数返回前就被调用。
 860    *      若scp->scsi_done回调函数未在指定时限内被调用，SCSI中
 861    *      间层将启动错误处理流程。当调用scp->scsi_done回调函数
 862    *      时，若“result”字段被设置为CHECK CONDITION，
 863    *      则LLD应执行自动感知并填充
 864    *      struct scsi_cmnd::sense_buffer数组。在中间层将
 865    *      命令加入LLD队列之前前，scsi_cmnd::sense_buffer数组
 866    *      会被清零。
 867    *
 868    *      可选实现说明：LLD必须实现
 869    **/
 870    int queuecommand(struct Scsi_Host *shost, struct scsi_cmnd * scp)
 871
 872
 873    /**
 874    *      sdev_init - 在向新设备发送任何SCSI命令前（即开始扫描
 875    *                  之前）调用该函数
 876    *      @sdp: 指向即将被扫描的新设备的指针
 877    *
 878    *      返回值：返回0表示正常。返回其他值表示出错，
 879    *      该设备将被忽略。
 880    *
 881    *      并发安全声明：无锁
 882    *
 883    *      调用上下文说明：进程上下文
 884    *
 885    *      注意事项：该函数允许LLD在设备首次扫描前分配所需的资源。
 886    *      对应的SCSI设备可能尚未真正存在，但SCSI中间层即将对其进
 887    *      行扫描（例如发送INQUIRY命令等）。如果设备存在，将调用
 888    *      sdev_configure()进行配置；如果设备不存在，则调用
 889    *      sdev_destroy()销毁。更多细节请参考
 890    *      include/scsi/scsi_host.h文件。
 891    *
 892    *      可选实现说明：由LLD选择性定义
 893    **/
 894    int sdev_init(struct scsi_device *sdp)
 895
 896
 897    /**
 898    *      sdev_configure - 在设备首次完成扫描（即已成功响应INQUIRY
 899    *                       命令）之后，LDD可调用该函数对设备进行进一步配置
 900    *      @sdp: 已连接的设备
 901    *
 902    *      返回值：返回0表示成功。任何其他返回值都被视为错误，此时
 903    *      设备将被标记为离线。[被标记离线的设备不会调用sdev_destroy()，
 904    *      因此需要LLD主动清理资源。]
 905    *
 906    *      并发安全声明：无锁
 907    *
 908    *      调用上下文说明：进程上下文
 909    *
 910    *      注意事项：该接口允许LLD查看设备扫描代码所发出的初始INQUIRY
 911    *      命令的响应，并采取对应操作。具体实现细节请参阅
 912    *      include/scsi/scsi_host.h文件。
 913    *
 914    *      可选实现说明：由LLD选择性定义
 915    **/
 916    int sdev_configure(struct scsi_device *sdp)
 917
 918
 919    /**
 920    *      sdev_destroy - 当指定设备即将被关闭时调用。此时该设备
 921    *                     上的所有I/O活动均已停止。
 922    *      @sdp: 即将关闭的设备
 923    *
 924    *      返回值：无
 925    *
 926    *      并发安全声明：无锁
 927    *
 928    *      调用上下文说明：进程上下文
 929    *
 930    *      注意事项：该设备的中间层数据结构仍然存在
 931    *      但即将被销毁。驱动程序此时应当释放为该设
 932    *      备分配的所有专属资源。系统将不再向此sdp
 933    *      实例发送任何命令。[但该设备可能在未来被
 934    *      重新连接，届时将通过新的struct scsi_device
 935    *      实例，并触发后续的sdev_init()和
 936    *      sdev_configure()调用过程。]
 937    *
 938    *      可选实现说明：由LLD选择性定义
 939    **/
 940    void sdev_destroy(struct scsi_device *sdp)
 941
 942
 943
 944数据结构
 945========
 946struct scsi_host_template
 947-------------------------
 948每个LLD对应一个“struct scsi_host_template”
 949实例 [#]_。该结构体通常被初始化为驱动头文件中的静
 950态全局变量，此方式可确保未显式初始化的成员自动置零
 951（0或NULL）。关键成员变量说明如下：
 952
 953    name
 954		 - 驱动程序的名称（可以包含空格，请限制在80个字符以内）
 955
 956    proc_name
 957		 - 在“/proc/scsi/<proc_name>/<host_no>”
 958		   和sysfs的“drivers”目录中使用的名称。因此
 959		   “proc_name”应仅包含Unix文件名中可接受
 960		   的字符。
 961
 962    ``(*queuecommand)()``
 963		 - 中间层使用的主要回调函数，用于将SCSI命令
 964		   提交到LLD。
 965
 966    vendor_id
 967		 - 该字段是一个唯一标识值，用于确认提供
 968		   Scsi_Host LLD的供应商，最常用于
 969		   验证供应商特定的消息请求。该值由标识符类型
 970		   和供应商特定值组成，有效格式描述请参阅
 971		   scsi_netlink.h头文件。
 972
 973该结构体的完整定义及详细注释请参阅 ``include/scsi/scsi_host.h``。
 974
 975.. [#] 在极端情况下，单个驱动需要控制多种不同类型的硬件时，驱动可
 976       能包含多个实例，（例如某个LLD驱动同时处理ISA和PCI两种类型
 977       的适配卡，并为每种硬件类型维护独立的
 978       struct scsi_host_template实例）。
 979
 980struct Scsi_Host
 981----------------
 982每个由LLD控制的主机适配器对应一个struct Scsi_Host实例。
 983该结构体与struct scsi_host_template具有多个相同成员。
 984当创建struct Scsi_Host实例时（通过hosts.c中的
 985scsi_host_alloc()函数），这些通用成员会从LLD的
 986struct scsi_host_template实例初始化而来。关键成员说明
 987如下：
 988
 989    host_no
 990		 - 系统范围内唯一的主机标识号，按升序从0开始分配
 991    can_queue
 992		 - 必须大于0，表示适配器可处理的最大并发命令数，禁
 993		   止向适配器发送超过此数值的命令数
 994    this_id
 995		 - 主机适配器的SCSI ID（SCSI启动器标识），若未知则
 996		   设置为-1
 997    sg_tablesize
 998		 - 主机适配器支持的最大散列表（scatter-gather）元素
 999		   数。设置为SG_ALL或更小的值可避免使用链式SG列表，
1000		   且最小值必须为1
1001    max_sectors
1002		 - 单个SCSI命令中允许的最大扇区数（通常为512字节/
1003		   扇区）。默认值为0，此时会使用
1004		   SCSI_DEFAULT_MAX_SECTORS（在scsi_host.h中定义），
1005		   当前该值为1024。因此，如果未定义max_sectors，则磁盘的
1006		   最大传输大小为512KB。注意：这个大小可能不足以支持
1007		   磁盘固件上传。
1008    cmd_per_lun
1009		 - 主机适配器的设备上，每个LUN可排队的最大命令数。
1010		   此值可通过LLD调用scsi_change_queue_depth()进行
1011		   调整。
1012    hostt
1013		 - 指向LLD struct scsi_host_template实例的指针，
1014		   当前struct Scsi_Host实例正是由此模板生成。
1015    hostt->proc_name
1016		 - LLD的名称，sysfs使用的驱动名。
1017    transportt
1018		 - 指向LLD struct scsi_transport_template实例的指
1019		   针（如果存在）。当前支持FC与SPI传输协议。
1020    hostdata[0]
1021		 - 为LLD在struct Scsi_Host结构体末尾预留的区域，大小由
1022		   scsi_host_alloc()的第二个参数(privsize)决定。
1023
1024scsi_host结构体的完整定义详见include/scsi/scsi_host.h。
1025
1026struct scsi_device
1027------------------
1028通常而言，每个SCSI逻辑单元（Logical Unit）对应一个该结构
1029的实例。连接到主机适配器的SCSI设备通过三个要素唯一标识：通
1030道号（Channel Number）、目标ID（Target ID）和逻辑单元号
1031（LUN）。
1032该结构体完整定义于include/scsi/scsi_device.h。
1033
1034struct scsi_cmnd
1035----------------
1036该结构体实例用于在LLD与SCSI中间层之间传递SCSI命令
1037及其响应。SCSI中间层会确保：提交到LLD的命令数不超过
1038scsi_change_queue_depth()（或struct Scsi_Host::cmd_per_lun）
1039设定的上限，且每个SCSI设备至少分配一个struct scsi_cmnd实例。
1040关键成员说明如下：
1041
1042    cmnd
1043		 - 包含SCSI命令的数组
1044    cmd_len
1045		 - SCSI命令的长度（字节为单位）
1046    sc_data_direction
1047		 - 数据的传输方向。请参考
1048		   include/linux/dma-mapping.h中的
1049		   “enum dma_data_direction”。
1050    result
1051		 - LLD在调用“done”之前设置该值。值为0表示命令成功
1052		   完成（并且所有数据（如果有）已成功在主机与SCSI
1053		   目标设备之间完成传输）。“result”是一个32位无符
1054		   号整数，可以视为2个相关字节。SCSI状态值位于最
1055		   低有效位。请参考include/scsi/scsi.h中的
1056		   status_byte()与host_byte()宏以及其相关常量。
1057    sense_buffer
1058		 - 这是一个数组（最大长度为SCSI_SENSE_BUFFERSIZE
1059		   字节），当SCSI状态（“result”的最低有效位）设为
1060		   CHECK_CONDITION（2）时，该数组由LLD填写。若
1061		   CHECK_CONDITION被置位，且sense_buffer[0]的高
1062		   半字节值为7，则中间层会认为sense_buffer数组
1063		   包含有效的SCSI感知数据；否则，中间层会发送
1064		   REQUEST_SENSE SCSI命令来获取感知数据。由于命令
1065		   排队的存在，后一种方式容易出错，因此建议LLD始终
1066		   支持“自动感知”。
1067    device
1068		 - 指向与该命令关联的scsi_device对象的指针。
1069    resid_len (通过调用scsi_set_resid() / scsi_get_resid()访问)
1070		 - LLD应将此无符号整数设置为请求的传输长度（即
1071		   “request_bufflen”）减去实际传输的字节数。“resid_len”
1072		   默认设置为0，因此如果LLD无法检测到数据欠载（不能报告溢出），
1073		   则可以忽略它。LLD应在调用“done”之前设置
1074		   “resid_len”。
1075    underflow
1076		 - 如果实际传输的字节数小于该字段值，LLD应将
1077		   DID_ERROR << 16赋值给“result”。并非所有
1078		   LLD都实现此项检查，部分LLD仅将错误信息输出
1079		   到日志，而未真正报告DID_ERROR。更推荐
1080		   的做法是由LLD实现“resid_len”的支持。
1081
1082建议LLD在从SCSI目标设备进行数据传输时设置“resid_len”字段
1083（例如READ操作）。当这些数据传输的感知码是MEDIUM ERROR或
1084HARDWARE ERROR（有时也包括RECOVERED ERROR）时设置
1085resid_len尤为重要。在这种情况下，如果LLD无法确定接收了多
1086少数据，那么最安全的做法是表示没有接收到任何数据。例如：
1087为了表明没有接收到任何有效数据，LLD可以使用如下辅助函数::
1088
1089    scsi_set_resid(SCpnt, scsi_bufflen(SCpnt));
1090
1091其中SCpnt是一个指向scsi_cmnd对象的指针。如果表示仅接收到
1092三个512字节的数据块，可以这样设置resid_len::
1093
1094    scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512));
1095
1096scsi_cmnd结构体定义在 include/scsi/scsi_cmnd.h文件中。
1097
1098
1099锁
1100===
1101每个struct Scsi_Host实例都有一个名为default_lock
1102的自旋锁（spin_lock），它在scsi_host_alloc()函数
1103中初始化（该函数定义在hosts.c文件中）。在同一个函数
1104中，struct Scsi_Host::host_lock指针会被初始化为指
1105向default_lock。此后，SCSI中间层执行的加
1106锁和解锁操作都会使用host_lock指针。过去，驱动程序可
1107以重写host_lock指针，但现在不再允许这样做。
1108
1109
1110自动感知
1111========
1112自动感知（Autosense或auto-sense）在SAM-2规范中被定
1113义为：当SCSI命令完成状态为CHECK CONDITION时，“自动
1114将感知数据（sense data）返回给应用程序客户端”。底层
1115驱动（LLD）应当执行自动感知。当LLD检测到
1116CHECK CONDITION状态时，可通过以下任一方式完成：
1117
1118	a) 要求SCSI协议（例如SCSI并行接口（SPI））在此
1119	   类响应中执行一次额外的数据传输
1120
1121	b) 或由LLD主动发起REQUEST SENSE命令获取感知数据
1122
1123无论采用哪种方式，当检测到CHECK CONDITION状态时，中
1124间层通过检查结构体scsi_cmnd::sense_buffer[0]的值来
1125判断LLD是否已执行自动感知。若该字节的高半字节为7
1126（或 0xf），则认为已执行自动感知；若该字节为其他值
1127（且此字节在每条命令执行前会被初始化为0），则中间层将
1128主动发起REQUEST SENSE命令。
1129
1130在存在命令队列的场景下，保存失败命令感知数据的“nexus”
1131可能会在等待REQUEST SENSE命令期间变得不同步。因此，
1132最佳实践是由LLD执行自动感知。
1133
1134
1135自Linux内核2.4以来的变更
1136========================
1137io_request_lock已被多个细粒度锁替代。与底层驱动
1138（LLD）相关的锁是struct Scsi_Host::host_lock，且每
1139个SCSI主机都独立拥有一个该锁。
1140
1141旧的错误处理机制已经被移除。这意味着LLD的接口函数
1142abort()与reset()已经被删除。
1143struct scsi_host_template::use_new_eh_code标志
1144也已经被移除。
1145
1146在Linux内核2.4中，SCSI子系统的配置描述与其他Linux子系
1147统的配置描述集中存放在Documentation/Configure.help
1148文件中。在Linux内核2.6中，SCSI子系统拥有独立的配置文
1149件drivers/scsi/Kconfig（体积更小），同时包含配置信息
1150与帮助信息。
1151
1152struct SHT已重命名为struct scsi_host_template。
1153
1154新增“热插拔初始化模型”以及许多用于支持该功能的额外函数。
1155
1156
1157致谢
1158====
1159以下人员对本文档做出了贡献：
1160
1161	- Mike Anderson <andmike at us dot ibm dot com>
1162	- James Bottomley <James dot Bottomley at hansenpartnership dot com>
1163	- Patrick Mansfield <patmans at us dot ibm dot com>
1164	- Christoph Hellwig <hch at infradead dot org>
1165	- Doug Ledford <dledford at redhat dot com>
1166	- Andries Brouwer <Andries dot Brouwer at cwi dot nl>
1167	- Randy Dunlap <rdunlap at xenotime dot net>
1168	- Alan Stern <stern at rowland dot harvard dot edu>
1169
1170
1171Douglas Gilbert
1172dgilbert at interlog dot com
1173
11742004年9月21日