This patch introduces the Chinese translation
of the following SCSI subsystem documentation
files:
../scsi/index.rst
../scsi/link_power_management_policy.rst
../scsi/scsi_eh.rst
../scsi/scsi_mid_low_api.rst
../scsi/scsi-parameters.rst
../scsi/scsi.rst
../scsi/sd-parameters.rst
Signed-off-by: haodongdong <doubled@xxxxxxxxxxx>
---
.../translations/zh_CN/scsi/index.rst | 92 ++
.../scsi/link_power_management_policy.rst | 32 +
.../zh_CN/scsi/scsi-parameters.rst | 118 ++
.../translations/zh_CN/scsi/scsi.rst | 48 +
.../translations/zh_CN/scsi/scsi_eh.rst | 482 +++++++
.../zh_CN/scsi/scsi_mid_low_api.rst | 1174 +++++++++++++++++
.../translations/zh_CN/scsi/sd-parameters.rst | 38 +
.../translations/zh_CN/subsystem-apis.rst | 2 +-
8 files changed, 1985 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/scsi/index.rst
create mode 100644 Documentation/translations/zh_CN/scsi/link_power_management_policy.rst
create mode 100644 Documentation/translations/zh_CN/scsi/scsi-parameters.rst
create mode 100644 Documentation/translations/zh_CN/scsi/scsi.rst
create mode 100644 Documentation/translations/zh_CN/scsi/scsi_eh.rst
create mode 100644 Documentation/translations/zh_CN/scsi/scsi_mid_low_api.rst
create mode 100644 Documentation/translations/zh_CN/scsi/sd-parameters.rst
diff --git a/Documentation/translations/zh_CN/scsi/index.rst b/Documentation/translations/zh_CN/scsi/index.rst
new file mode 100644
index 000000000000..0ee76039118b
--- /dev/null
+++ b/Documentation/translations/zh_CN/scsi/index.rst
@@ -0,0 +1,92 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/scsi/index.rst
+
+:翻译:
+
+ 郝栋栋 Dongdong Hao <doubled@xxxxxxxxxxx>
+
+:校译:
+
+
+
+==========
+SCSI子系统
+==========
+
+.. toctree::
+ :maxdepth: 1
+
+简介
+====
+
+.. toctree::
+ :maxdepth: 1
+
+ scsi
+
+SCSI驱动接口
+============
+
+.. toctree::
+ :maxdepth: 1
+
+ scsi_mid_low_api
+ scsi_eh
+
+SCSI驱动参数
+============
+
+.. toctree::
+ :maxdepth: 1
+
+ scsi-parameters
+ link_power_management_policy
+
+SCSI主机适配器驱动
+==================
+
+.. toctree::
+ :maxdepth: 1
+
+ sd-parameters
+
+Todolist:
+
+* 53c700
+* aacraid
+* advansys
+* aha152x
+* aic79xx
+* aic7xxx
+* arcmsr_spec
+* bfa
+* bnx2fc
+* BusLogic
+* cxgb3i
+* dc395x
+* dpti
+* FlashPoint
+* g_NCR5380
+* hpsa
+* hptiop
+* libsas
+* lpfc
+* megaraid
+* ncr53c8xx
+* NinjaSCSI
+* ppa
+* qlogicfas
+* scsi-changer
+* scsi_fc_transport
+* scsi-generic
+* smartpqi
+* st
+* sym53c500_cs
+* sym53c8xx_2
+* tcm_qla2xxx
+* ufs
+* wd719x
+
+* scsi_transport_srp/figures
diff --git a/Documentation/translations/zh_CN/scsi/link_power_management_policy.rst b/Documentation/translations/zh_CN/scsi/link_power_management_policy.rst
new file mode 100644
index 000000000000..67382a6a9b5f
--- /dev/null
+++ b/Documentation/translations/zh_CN/scsi/link_power_management_policy.rst
@@ -0,0 +1,32 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/scsi/link_power_management_policy.rst
+
+:翻译:
+
+ 郝栋栋 Dongdong Hao <doubled@xxxxxxxxxxx>
+
+:校译:
+
+
+
+================
+链路电源管理策略
+================
+
+该参数允许用户设置链路（接口）的电源管理模式。
+共计三类可选项：
+
+===================== =====================================================
+选项 作用
+===================== =====================================================
+min_power 指示控制器在可能的情况下尽量使链路处于最低功耗。
+ 这可能会牺牲一定的性能，因为从低功耗状态恢复时会增加延迟。
+
+max_performance 通常，这意味着不进行电源管理。指示
+ 控制器优先考虑性能而非电源管理。
+
+medium_power 指示控制器在可能的情况下进入较低功耗状态，
+ 而非最低功耗状态，从而改善min_power模式下的延迟。
+===================== =====================================================
\ No newline at end of file
diff --git a/Documentation/translations/zh_CN/scsi/scsi-parameters.rst b/Documentation/translations/zh_CN/scsi/scsi-parameters.rst
new file mode 100644
index 000000000000..7fb4dfee4ac3
--- /dev/null
+++ b/Documentation/translations/zh_CN/scsi/scsi-parameters.rst
@@ -0,0 +1,118 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/scsi/scsi-parameters.rst
+
+:翻译:
+
+ 郝栋栋 Dongdong Hao <doubled@xxxxxxxxxxx>
+
+:校译:
+
+
+
+============
+SCSI内核参数
+============
+
+请查阅Documentation/admin-guide/kernel-parameters.rst以获取
+指定模块参数相关的通用信息。
+
+当前文档可能不完全是最新和全面的。命令 ``modinfo -p ${modulename}``
+显示了可加载模块的参数列表。可加载模块被加载到内核中后，也会在
+/sys/module/${modulename}/parameters/ 目录下显示其参数。其
+中某些参数可以通过命令
+``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``
+在运行时修改。
+
+::
+
+ advansys= [HW,SCSI]
+ 请查阅 drivers/scsi/advansys.c 文件头部。
+
+ aha152x= [HW,SCSI]
+ 请查阅 Documentation/translations/zh_CN/scsi/aha152x.rst。
+
+ aha1542= [HW,SCSI]
+ 格式：<portbase>[,<buson>,<busoff>[,<dmaspeed>]]
+
+ aic7xxx= [HW,SCSI]
+ 请查阅 Documentation/translations/zh_CN/scsi/aic7xxx.rst。
+
+ aic79xx= [HW,SCSI]
+ 请查阅 Documentation/translations/zh_CN/scsi/aic79xx.rst。
+
+ atascsi= [HW,SCSI]
+ 请查阅 drivers/scsi/atari_scsi.c。
+
+ BusLogic= [HW,SCSI]
+ 请查阅 drivers/scsi/BusLogic.c 文件中
+ BusLogic_ParseDriverOptions()函数前的注释。
+
+ gvp11= [HW,SCSI]
+
+ ips= [HW,SCSI] Adaptec / IBM ServeRAID 控制器
+ 请查阅 drivers/scsi/ips.c 文件头部。
+
+ mac5380= [HW,SCSI]
+ 请查阅 drivers/scsi/mac_scsi.c。
+
+ scsi_mod.max_luns=
+ [SCSI] 最大可探测LUN数。
+ 取值范围为 1 到 2^32-1。
+
+ scsi_mod.max_report_luns=
+ [SCSI] 接收到的最大LUN数。
+ 取值范围为 1 到 16384。
+
+ NCR_D700= [HW,SCSI]
+ 请查阅 drivers/scsi/NCR_D700.c 文件头部。
+
+ ncr5380= [HW,SCSI]
+ 请查阅 Documentation/translations/zh_CN/scsi/g_NCR5380.rst。
+
+ ncr53c400= [HW,SCSI]
+ 请查阅 Documentation/translations/zh_CN/scsi/g_NCR5380.rst。
+
+ ncr53c400a= [HW,SCSI]
+ 请查阅 Documentation/translations/zh_CN/scsi/g_NCR5380.rst。
+
+ ncr53c8xx= [HW,SCSI]
+
+ osst= [HW,SCSI] SCSI磁带驱动
+ 格式：<buffer_size>,<write_threshold>
+ 另请查阅 Documentation/translations/zh_CN/scsi/st.rst。
+
+ scsi_debug_*= [SCSI]
+ 请查阅 drivers/scsi/scsi_debug.c。
+
+ scsi_mod.default_dev_flags=
+ [SCSI] SCSI默认设备标志
+ 格式：<integer>
+
+ scsi_mod.dev_flags=
+ [SCSI] 厂商和型号的黑/白名单条目
+ 格式：<vendor>:<model>:<flags>
+ （flags 为整数值）
+
+ scsi_mod.scsi_logging_level=
+ [SCSI] 日志级别的位掩码
+ 位的定义请查阅 drivers/scsi/scsi_logging.h。
+ 此参数也可以通过sysctl对dev.scsi.logging_level
+ 进行设置（/proc/sys/dev/scsi/logging_level）。
+ 此外，S390-tools软件包提供了一个便捷的
+ ‘scsi_logging_level’ 脚本，可以从以下地址下载：
+ https://github.com/ibm-s390-linux/s390-tools/blob/master/scripts/scsi_logging_level
+
+ scsi_mod.scan= [SCSI] sync（默认）在发现SCSI总线过程中
+ 同步扫描。async在内核线程中异步扫描，允许系统继续
+ 启动流程。none忽略扫描，预期由用户空间完成扫描。
+
+ sim710= [SCSI,HW]
+ 请查阅 drivers/scsi/sim710.c 文件头部。
+
+ st= [HW,SCSI] SCSI磁带参数（缓冲区大小等）
+ 请查阅 Documentation/translations/zh_CN/scsi/st.rst。
+
+ wd33c93= [HW,SCSI]
+ 请查阅 drivers/scsi/wd33c93.c 文件头部。
diff --git a/Documentation/translations/zh_CN/scsi/scsi.rst b/Documentation/translations/zh_CN/scsi/scsi.rst
new file mode 100644
index 000000000000..874ad34ae8aa
--- /dev/null
+++ b/Documentation/translations/zh_CN/scsi/scsi.rst
@@ -0,0 +1,48 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/scsi/scsi.rst
+
+:翻译:
+
+ 郝栋栋 Dongdong Hao <doubled@xxxxxxxxxxx>
+
+:校译:
+
+
+
+==============
+SCSI子系统文档
+==============
+
+Linux文档项目（LDP）维护了一份描述Linux内核（lk） 2.4中SCSI
+子系统的文档。请参考：
+https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO 。LDP提供单页和
+多页的HTML版本，以及PostScript与PDF格式的文档。
+
+在SCSI子系统中使用模块的注意事项
+================================
+Linux内核中的SCSI支持可以根据终端用户的需求以不同的方式模块
+化。为了理解你的选择，我们首先需要定义一些术语。
+
+scsi-core（也被称为“中间层”）包含SCSI支持的核心。没有他你将
+无法使用任何其他SCSI驱动程序。SCSI核心支持可以是一个模块（
+scsi_mod.o），也可以编译进内核。如果SCSI核心是一个模块，那么
+他必须是第一个被加载的SCSI模块，如果你将卸载该模块，那么他必
+须是最后一个被卸载的模块。实际上，modprobe和rmmod命令将确保
+SCSI子系统中模块加载与卸载的正确顺序。
+
+一旦SCSI核心存在于内核中（无论是编译进内核还是作为模块加载），
+独立的上层驱动和底层驱动可以按照任意顺序加载。磁盘驱动程序
+（sd_mod.o）、光盘驱动程序（sr_mod.o）、磁带驱动程序 [1]_
+（st.o）以及SCSI通用驱动程序（sg.o）代表了上层驱动，用于控制
+相应的各种设备。例如，你可以加载磁带驱动程序来使用磁带驱动器，
+然后在不需要该驱动程序时卸载他（并释放相关内存）。
+
+底层驱动程序用于支持您所运行硬件平台支持的不同主机卡。这些不同
+的主机卡通常被称为主机总线适配器（HBAs）。例如，aic7xxx.o驱动
+程序被用于控制Adaptec所属的所有最新的SCSI控制器。几乎所有的底
+层驱动都可以被编译为模块或直接编译进内核。
+
+.. [1] 磁带驱动程序有一个变种用于控制OnStream磁带设备。其模块
+ 名称为osst.o 。
\ No newline at end of file
diff --git a/Documentation/translations/zh_CN/scsi/scsi_eh.rst b/Documentation/translations/zh_CN/scsi/scsi_eh.rst
new file mode 100644
index 000000000000..60649a2497b2
--- /dev/null
+++ b/Documentation/translations/zh_CN/scsi/scsi_eh.rst
@@ -0,0 +1,482 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/scsi/scsi_eh.rst
+
+:翻译:
+
+ 郝栋栋 Dongdong Hao <doubled@xxxxxxxxxxx>
+
+:校译:
+
+
+===================
+SCSI 中间层错误处理
+===================
+
+本文档描述了SCSI中间层（mid layer）的错误处理基础架构。
+关于SCSI中间层的更多信息，请参阅：
+Documentation/scsi/scsi_mid_low_api.rst。
+
+.. 目录
+
+ [1] SCSI 命令如何通过中间层传递并进入错误处理（EH）
+ [1-1] scsi_cmnd（SCSI命令）结构体
+ [1-2] scmd（SCSI 命令）是如何完成的？
+ [1-2-1] 通过scsi_done完成scmd
+ [1-2-2] 通过超时机制完成scmd
+ [1-3] 错误处理模块如何接管流程
+ [2] SCSI错误处理机制工作原理
+ [2-1] 基于细粒度回调的错误处理
+ [2-1-1] 概览
+ [2-1-2] scmd在错误处理流程中的传递路径
+ [2-1-3] 控制流分析
+ [2-2] 通过transportt->eh_strategy_handler()实现的错误处理
+ [2-2-1] transportt->eh_strategy_handler()调用前的中间层状态
+ [2-2-2] transportt->eh_strategy_handler()调用后的中间层状态
+ [2-2-3] 注意事项
+
+
+1. SCSI命令在中间层及错误处理中的传递流程
+=========================================
+
+1.1 scsi_cmnd结构体
+-------------------
+
+每个SCSI命令都由struct scsi_cmnd（简称scmd）结构体
+表示。scmd包含两个list_head类型的链表节点：scmd->list
+与scmd->eh_entry。其中scmd->list是用于空闲链表或设备
+专属的scmd分配链表，与错误处理讨论关联不大。而
+scmd->eh_entry则是专用于命令完成和错误处理链表，除非
+特别说明，本文讨论中所有scmd的链表操作均通过
+scmd->eh_entry实现。
+
+
+1.2 scmd是如何完成的？
+----------------------
+
+底层设备驱动（LLDD）在获取SCSI命令（scmd）后，存在两种
+完成路径：底层驱动可通过调用hostt->queuecommand()时从
+中间层传递的scsi_done回调函数主动完成命令，或者当命令未
+及时完成时由块层（block layer）触发超时处理机制。
+
+
+1.2.1 通过scsi_done回调完成SCSI命令
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+对于所有非错误处理（EH）命令，scsi_done()是其完成回调
+函数。它只调用blk_mq_complete_request()来删除块层的
+定时器并触发块设备软中断（BLOCK_SOFTIRQ）。
+
+BLOCK_SOFTIRQ会间接调用scsi_complete()，进而调用
+scsi_decide_disposition()来决定如何处理该命令。
+scsi_decide_disposition()会查看scmd->result值和感
+应码数据来决定如何处理命令。
+
+ - SUCCESS
+
+ 调用scsi_finish_command()来处理该命令。该函数会
+ 执行一些维护操作，然后调用scsi_io_completion()来
+ 完成I/O操作。scsi_io_completion()会通过调用
+ blk_end_request及其相关函数来通知块层该请求已完成，
+ 如果发生错误，还会判断如何处理剩余的数据。
+
+ - NEEDS_RETRY
+
+ - ADD_TO_MLQUEUE
+
+ scmd被重新加入到块设备队列中。
+
+ - otherwise
+
+ 调用scsi_eh_scmd_add(scmd)来处理该命令。
+ 关于此函数的详细信息，请参见 [1-3]。
+
+
+1.2.2 scmd超时完成机制
+^^^^^^^^^^^^^^^^^^^^^^
+
+SCSI命令超时处理机制由scsi_timeout()函数实现。
+当发生超时事件时，该函数
+
+ 1. 首先调用可选的hostt->eh_timed_out()回调函数。
+ 返回值可能是以下3种情况之一：
+
+ - ``SCSI_EH_RESET_TIMER``
+ 表示需要延长命令执行时间并重启计时器。
+
+ - ``SCSI_EH_NOT_HANDLED``
+ 表示eh_timed_out()未处理该命令。
+ 此时将执行第2步的处理流程。
+
+ - ``SCSI_EH_DONE``
+ 表示eh_timed_out()已完成该命令。
+
+ 2. 若未通过回调函数解决，系统将调用
+ scsi_abort_command()发起异步中止操作，该操作最多
+ 可执行scmd->allowed + 1次。但存在三种例外情况会跳
+ 过异步中止而直接进入第3步处理：当检测到
+ SCSI_EH_ABORT_SCHEDULED标志位已置位（表明该命令先
+ 前已被中止过一次且当前重试仍失败）、当重试次数已达上
+ 限、或当错误处理时限已到期时。在这些情况下，系统将跳
+ 过异步中止流程而直接执行第3步处理方案。
+
+ 3. 最终未解决的命令会通过scsi_eh_scmd_add(scmd)移交给
+ 错误处理子系统，具体流程详见[1-4]章节说明。
+
+1.3 异步命令中止机制
+--------------------
+
+当命令超时触发后，系统会通过scsi_abort_command()调度异
+步中止操作。若中止操作执行成功，则根据重试次数决定后续处
+理：若未达最大重试限制，命令将重新下发执行；若重试次数已
+耗尽，则命令最终以DID_TIME_OUT状态终止。当中止操作失败
+时，系统会调用scsi_eh_scmd_add()将该命令移交错误处理子
+系统，具体处理流程详见[1-4]。
+
+1.4 错误处理(EH)接管机制
+------------------------
+
+SCSI命令通过scsi_eh_scmd_add()函数进入错误处理流程，该函
+数执行以下操作：
+
+ 1. 将scmd->eh_entry链接到shost->eh_cmd_q
+
+ 2. 在shost->shost_state中设置SHOST_RECOVERY状态位
+
+ 3. 递增shost->host_failed失败计数器
+
+ 4. 当检测到shost->host_busy == shost->host_failed
+ 时（即所有进行中命令均已失败）立即唤醒SCSI错误处理
+ 线程。
+
+如上所述，当任一scmd被加入到shost->eh_cmd_q队列时，系统
+会立即置位shost_state中的SHOST_RECOVERY状态标志位，该操
+作将阻止块层向对应主机控制器下发任何新的SCSI命令。在此状
+态下，主机控制器上所有正在处理的scmd最终会进入以下三种状
+态之一：正常完成、失败后被移入到eh_cmd_q队列、或因超时被
+添加到shost->eh_cmd_q队列。
+
+如果所有的SCSI命令都已经完成或失败，系统中正在执行的命令
+数量与失败命令数量相等（
+即shost->host_busy == shost->host_failed），此时将唤
+醒SCSI错误处理线程。SCSI错误处理线程一旦被唤醒，就可以确
+保所有未完成命令均已标记为失败状态，并且已经被链接到
+shost->eh_cmd_q队列中。
+
+需要特别说明的是，这并不意味着底层处理流程完全静止。当底层
+驱动以错误状态完成某个scmd时，底层驱动及其下层组件会立刻遗
+忘该命令的所有关联状态。但对于超时命令，除非
+hostt->eh_timed_out()回调函数已经明确通知底层驱动丢弃该
+命令（当前所有底层驱动均未实现此功能），否则从底层驱动视角
+看该命令仍处于活跃状态，理论上仍可能在某时刻完成。当然，由
+于超时计时器早已触发，所有此类延迟完成都将被系统直接忽略。
+
+我们将在后续章节详细讨论关于SCSI错误处理如何执行中止操作（
+即强制底层驱动丢弃已超时SCSI命令）。
+
+
+2. SCSI错误处理机制详解
+=======================
+
+SCSI底层驱动可以通过以下两种方式之一来实现SCSI错误处理。
+
+ - 细粒度的错误处理回调机制
+ 底层驱动可选择实现细粒度的错误处理回调函数，由SCSI中间层
+ 主导错误恢复流程并自动调用对应的回调函数。此实现模式的详
+ 细设计规范在[2-1]节中展开讨论。
+
+ - eh_strategy_handler()回调函数
+ 该回调函数作为统一的错误处理入口，需要完整实现所有的恢复
+ 操作。具体而言，它必须涵盖SCSI中间层在常规恢复过程中执行
+ 的全部处理流程，相关实现将在[2-2]节中详细描述。
+
+当错误恢复流程完成后，SCSI错误处理系统通过调用
+scsi_restart_operations()函数恢复正常运行，该函数按顺序执行
+以下操作：
+
+ 1. 验证是否需要执行驱动器安全门锁定机制
+
+ 2. 清除shost_state中的SHOST_RECOVERY状态标志位
+
+ 3. 唤醒所有在shost->host_wait上等待的任务。如果有人调用了
+ scsi_block_when_processing_errors()则会发生这种情况。
+ （疑问：由于错误处理期间块层队列已被阻塞，为何仍需显式
+ 唤醒？）
+
+ 4. 强制激活该主机控制器下所有设备的I/O队列
+
+
+2.1 基于细粒度回调的错误处理机制
+--------------------------------
+
+2.1.1 概述
+^^^^^^^^^^^
+
+如果不存在eh_strategy_handler()，SCSI中间层将负责驱动的
+错误处理。错误处理（EH）的目标有两个：一是让底层驱动程序、
+主机和设备不再维护已超时的SCSI命令（scmd）；二是使他们准备
+好接收新命令。当一个SCSI命令（scmd）被底层遗忘且底层已准备
+好再次处理或拒绝该命令时，即可认为该scmd已恢复。
+
+为实现这些目标，错误处理（EH）会逐步执行严重性递增的恢复
+操作。部分操作通过下发SCSI命令完成，而其他操作则通过调用
+以下细粒度的错误处理回调函数实现。这些回调函数可以省略，
+若被省略则默认始终视为执行失败。
+
+::
+
+ int (* eh_abort_handler)(struct scsi_cmnd *);
+ int (* eh_device_reset_handler)(struct scsi_cmnd *);
+ int (* eh_bus_reset_handler)(struct scsi_cmnd *);
+ int (* eh_host_reset_handler)(struct scsi_cmnd *);
+
+只有在低级别的错误恢复操作无法恢复部分失败的SCSI命令
+（scmd）时，才会采取更高级别的恢复操作。如果最高级别的错误
+处理失败，就意味着整个错误恢复（EH）过程失败，所有未能恢复
+的设备被强制下线。
+
+在恢复过程中，需遵循以下规则：
+
+ - 错误恢复操作针对待处理列表eh_work_q中的失败的scmds执
+ 行。如果某个恢复操作成功恢复了一个scmd，那么该scmd会
+ 从eh_work_q链表中移除。
+
+ 需要注意的是，对某个scmd执行的单个恢复操作可能会恢复
+ 多个scmd。例如，对某个设备执行复位操作可能会恢复该设
+ 备上所有失败的scmd。
+
+ - 仅当低级别的恢复操作完成且eh_work_q仍然非空时，才会
+ 触发更高级别的操作
+
+ - SCSI错误恢复机制会重用失败的scmd来发送恢复命令。对于
+ 超时的scmd，SCSI错误处理机制会确保底层驱动在重用scmd
+ 前已不再维护该命令。
+
+当一个SCSI命令（scmd）被成功恢复后，错误处理逻辑会通过
+scsi_eh_finish_cmd()将其从待处理队列（eh_work_q）移
+至错误处理的本地完成队列（eh_done_q）。当所有scmd均恢
+复完成（即eh_work_q为空时），错误处理逻辑会调用
+scsi_eh_flush_done_q()对这些已恢复的scmd进行处理，即
+重新尝试或错误总终止（向上层通知失败）。
+
+SCSI命令仅在满足以下全部条件时才会被重试：对应的SCSI设
+备仍处于在线状态，未设置REQ_FAILFAST标志或递增后的
+scmd->retries值仍小于scmd->allowed。
+
+2.1.2 SCSI命令在错误处理过程中的流转路径
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ 1. 错误完成/超时
+
+ :处理: 调用scsi_eh_scmd_add()处理scmd
+
+ - 将scmd添加到shost->eh_cmd_q
+ - 设置SHOST_RECOVERY标记位
+ - shost->host_failed++
+
+ :锁要求: shost->host_lock
+
+ 2. 启动错误处理（EH）
+
+ :操作: 将所有scmd移动到EH本地eh_work_q队列，并
+ 清空 shost->eh_cmd_q。
+
+ :锁要求: shost->host_lock（非严格必需，仅为保持一致性）
+
+ 3. scmd恢复
+
+ :操作: 调用scsi_eh_finish_cmd()完成scmd的EH
+
+ - 将scmd从本地eh_work_q队列移至本地eh_done_q队列
+
+ :锁要求: 无
+
+ :并发控制: 每个独立的eh_work_q至多一个线程，确保无锁
+ 队列的访问
+
+ 4. EH完成
+
+ :操作: 调用scsi_eh_flush_done_q()重试scmd或通知上层处理
+ 失败。此函数可以被并发调用，但每个独立的eh_work_q队
+ 列至多一个线程，以确保无锁队列的访问。
+
+ - 从eh_done_q队列中移除scmd，清除scmd->eh_entry
+ - 如果需要重试，调用scsi_queue_insert()重新入队scmd
+ - 否则，调用scsi_finish_command()完成scmd
+ - 将shost->host_failed置为零
+
+ :锁要求: 队列或完成函数会执行适当的加锁操作
+
+
+2.1.3 控制流
+^^^^^^^^^^^^
+
+ 通过细粒度回调机制执行的SCSI错误处理（EH）是从
+ scsi_unjam_host()函数开始的
+
+``scsi_unjam_host``
+
+ 1. 持有shost->host_lock锁，将shost->eh_cmd_q中的命令移动
+ 到本地的eh_work_q队里中，并释放host_lock锁。注意，这一步
+ 会清空shost->eh_cmd_q。
+
+ 2. 调用scsi_eh_get_sense函数。
+
+ ``scsi_eh_get_sense``
+
+ 该操作针对没有有效感知数据的错误完成命令。大部分SCSI传输协议
+ 或底层驱动在命令失败时会自动获取感知数据（自动感知）。出于性
+ 能原因，建议使用自动感知，推荐使用自动感知机制，因为它不仅有
+ 助于提升性能，还能避免从发生CHECK CONDITION到执行本操作之间，
+ 感知信息出现不同步的问题。
+
+ 注意，如果不支持自动感知，那么在使用scsi_done()以错误状态完成
+ scmd 时，scmd->sense_buffer将包含无效感知数据。在这种情况下，
+ scsi_decide_disposition()总是返回FAILED从而触发SCSI错误处理
+ （EH）。当该scmd执行到这里时，会重新获取感知数据，并再次调用
+ scsi_decide_disposition()进行处理。
+
+ 1. 调用scsi_request_sense()发送REQUEST_SENSE命令。如果失败，
+ 则不采取任何操作。请注意，不采取任何操作会导致对该scmd执行
+ 更高级别的恢复操作。
+
+ 2. 调用scsi_decide_disposition()处理scmd
+
+ - SUCCESS
+ scmd->retries被设置为scmd->allowed以防止
+ scsi_eh_flush_done_q()重试该scmd，并调用
+ scsi_eh_finish_cmd()。
+
+ - NEEDS_RETRY
+ 调用scsi_eh_finish_cmd()
+
+ - 其他情况
+ 无操作。
+
+ 4. 如果!list_empty(&eh_work_q)，则调用scsi_eh_ready_devs()。
+
+ ``scsi_eh_ready_devs``
+
+ 该函数采取四种逐步增强的措施，使失败的设备准备好处理新的命令。
+
+ 1. 调用scsi_eh_stu()
+
+ ``scsi_eh_stu``
+
+ 对于每个具有有效感知数据且scsi_check_sense()判断为失败的
+ scmd发送START STOP UNIT（STU）命令且将start置1。注意，由
+ 于我们明确选择错误完成的scmd，可以确定底层驱动已不再维护该
+ scmd，我们可以重用它进行STU。
+
+ 如果STU操作成功且sdev处于离线或就绪状态，所有在sdev上失败的
+ scmd都会通过scsi_eh_finish_cmd()完成。
+
+ *注意* 如果hostt->eh_abort_handler()未实现或返回失败，可能
+ 此时仍有超时的scmd，此时STU不会导致底层驱动不再维护scmd。但
+ 是，如果STU执行成功，该函数会通过scsi_eh_finish_cmd()来完成
+ sdev上的所有scmd，这会导致底层驱动处于不一致的状态。看来STU
+ 操作应仅在sdev不包含超时scmd时进行。
+
+ 2. 如果!list_empty(&eh_work_q)，调用scsi_eh_bus_device_reset()。
+
+ ``scsi_eh_bus_device_reset``
+
+ 此操作与scsi_eh_stu()非常相似，区别在于使用
+ hostt->eh_device_reset_handler()替代STU命令。此外，由于我们
+ 没有发送SCSI命令且重置会清空该sdev上所有的scmd，所以无需筛选错
+ 误完成的scmd。
+
+ 3. 如果!list_empty(&eh_work_q)，调用scsi_eh_bus_reset()。
+
+ ``scsi_eh_bus_reset``
+
+ 对于每个包含失败scmd的SCSI通道调用
+ hostt->eh_bus_reset_handler()。如果总线重置成功，那么该通道上
+ 所有准备就绪或离线状态sdev上的失败scmd都会被处理处理完成。
+
+ 4. 如果!list_empty(&eh_work_q)，调用scsi_eh_host_reset()。
+
+ ``scsi_eh_host_reset``
+
+ 调用hostt->eh_host_reset_handler()是最终的手段。如果SCSI主机
+ 重置成功，主机上所有就绪或离线sdev上的失败scmd都会通过错误处理
+ 完成。
+
+ 5. 如果!list_empty(&eh_work_q)，调用scsi_eh_offline_sdevs()。
+
+ ``scsi_eh_offline_sdevs``
+
+ 离线所有包含未恢复scmd的所有sdev，并通过
+ scsi_eh_finish_cmd()完成这些scmd。
+
+ 5. 调用scsi_eh_flush_done_q()。
+
+ ``scsi_eh_flush_done_q``
+
+ 此时所有的scmd都已经恢复（或放弃），并通过
+ scsi_eh_finish_cmd()函数加入eh_done_q队列。该函数通过
+ 重试或显示通知上层scmd的失败来刷新eh_done_q。
+
+
+2.2 基于transportt->eh_strategy_handler()的错误处理机制
+-------------------------------------------------------------
+
+在该机制中，transportt->eh_strategy_handler()替代
+scsi_unjam_host()的被调用，并负责整个错误恢复过程。该处理
+函数完成后应该确保底层驱动不再维护任何失败的scmd并且将设备
+设置为就绪（准备接收新命令）或离线状态。此外，该函数还应该
+执行SCSI错误处理的维护任务，以维护SCSI中间层的数据完整性。
+换句话说，eh_strategy_handler()必须实现[2-1-2]中除第1步
+外的所有步骤。
+
+
+2.2.1 transportt->eh_strategy_handler()调用前的SCSI中间层状态
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ 进入该处理函数时，以下条件成立。
+
+ - 每个失败的scmd的eh_flags字段已正确设置。
+
+ - 每个失败的scmd通过scmd->eh_entry链接到scmd->eh_cmd_q队列。
+
+ - 已设置SHOST_RECOVERY标志。
+
+ - `shost->host_failed == shost->host_busy`。
+
+2.2.2 transportt->eh_strategy_handler()调用后的SCSI中间层状态
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ 从该处理函数退出时，以下条件成立。
+
+ - shost->host_failed为零。
+
+ - shost->eh_cmd_q被清空。
+
+ - 每个scmd->eh_entry被清空。
+
+ - 对每个scmd必须调用scsi_queue_insert()或scsi_finish_command()。
+ 注意，该处理程序可以使用scmd->retries（剩余重试次数）和
+ scmd->allowed（允许重试次数）限制重试次数。
+
+
+2.2.3 注意事项
+^^^^^^^^^^^^^^
+
+ - 需明确已超时的scmd在底层仍处于活跃状态，因此在操作这些
+ scmd前，必须确保底层已彻底不再维护。
+
+ - 访问或修改shost数据结构时，必须持有shost->host_lock锁
+ 以维持数据一致性。
+
+ - 错误处理完成后，每个故障设备必须彻底清除所有活跃SCSI命
+ 令（scmd）的关联状态。
+
+ - 错误处理完成后，每个故障设备必须被设置为就绪（准备接收
+ 新命令）或离线状态。
+
+
+Tejun Heo
+htejun@xxxxxxxxx
+
+11th September 2005
diff --git a/Documentation/translations/zh_CN/scsi/scsi_mid_low_api.rst b/Documentation/translations/zh_CN/scsi/scsi_mid_low_api.rst
new file mode 100644
index 000000000000..cedd90b3fec1
--- /dev/null
+++ b/Documentation/translations/zh_CN/scsi/scsi_mid_low_api.rst
@@ -0,0 +1,1174 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/scsi/scsi_mid_low_api.rst
+
+:翻译:
+
+ 郝栋栋 Dongdong Hao <doubled@xxxxxxxxxxx>
+
+:校译:
+
+
+
+=========================
+SCSI中间层 — 底层驱动接口
+=========================
+
+简介
+====
+本文档概述了Linux SCSI中间层与SCSI底层驱动之间的接口。底层
+驱动（LLD）通常被称为主机总线适配器（HBA）驱动或主机驱动
+（HD）。在该上下文中，“主机”指的是计算机IO总线（例如：PCI总
+线或ISA总线）与SCSI传输层中单个SCSI启动器端口之间的桥梁。
+“启动器”端口（SCSI术语，参考SAM-3：http://www.t10.org）向;
+“目标”SCSI端口（例如：磁盘）发送SCSI命令。在一个运行的系统
+中存在多种底层驱动（LLDs），但每种硬件类型仅对应一种底层驱动
+（LLD）。大多数底层驱动可以控制一个或多个SCSI HBA。部分HBA
+内部集成多个主机控制器。
+
+在某些情况下，SCSI传输层本身是已存在于Linux中的外部总线子系
+统（例如：USB和ieee1394）。在此类场景下，SCSI子系统的底层驱
+动将作为与其他驱动子系统的软件桥接层。典型示例包括
+usb-storage驱动（位于drivers/usb/storage目录）以
+及ieee1394/sbp2驱动（位于 drivers/ieee1394 目录）。
+
+例如，aic7xxx底层驱动负责控制基于Adaptec公司7xxx芯片系列的
+SCSI并行接口（SPI）控制器。aic7xxx底层驱动可以内建到内核中
+或作为模块加载。一个Linux系统中只能运行一个aic7xxx底层驱动
+程序，但他可能控制多个主机总线适配器（HBA）。这些HBA可能位于
+PCI扩展卡或内置于主板中（或两者兼有）。某些基于aic7xxx的HBA
+采用双控制器设计，因此会呈现为两个SCSI主机适配器。与大多数现
+代HBA相同，每个aic7xxx控制器都拥有其独立的PCI设备地址。[SCSI
+主机与PCI设备之间一一对应虽然常见，但并非强制要求（例如ISA适
+配器就不适用此规则）。]
+
+SCSI中间层将SCSI底层驱动（LLD）与其他层（例如SCSI上层驱动以
+及块层）隔离开来。
+
+本文档的版本大致与Linux内核2.6.8相匹配。
+
+文档
+====
+内核源码树中设有专用的SCSI文档目录，通常位于
+Documentation/scsi目录下。大多数文档采用
+reStructuredText格式。本文档名为
+scsi_mid_low_api.rst，可在该目录中找到。该文档的最新版本可
+以访问 https://docs.kernel.org/scsi/scsi_mid_low_api.html
+查阅。许多底层驱动（LLD）的文档也位于Documentation/scsi目录
+下（例如aic7xxx.rst）。SCSI中间层的简要说明见scsi.rst文件，
+该文档包含指向Linux Kernel 2.4系列SCSI子系统的文档链接。此
+外还收录了两份SCSI上层驱动文档：st.rst（SCSI磁带驱动）与
+scsi-generic.rst（用通用SCSI（sg）驱动）。
+
+部分底层驱动的文档（或相关URL）可能嵌在C源代码文件或与其
+源码同位于同一目录下。例如，USB大容量存储驱动的文档链接可以在
+目录/usr/src/linux/drivers/usb/storage下找到。
+
+驱动程序结构
+============
+传统上，SCSI子系统的底层驱动（LLD）至少包含drivers/scsi
+目录下的两个文件。例如，一个名为“xyz”的驱动会包含一个头文件
+xyz.h和一个源文件xyz.c。[实际上所有代码完全可以合并为单个
+文件，头文件并非必需的。] 部分需要跨操作系统移植的底层驱动会
+采用更复杂的文件结构。例如，aic7xxx驱动，就为通用代码与操作
+系统专用代码（如FreeBSD和Linux）分别创建了独立的文件。此类
+驱动通常会在drivers/scsi目录下拥有自己单独的子目录。
+
+当需要向Linux内核添加新的底层驱动（LLD）时，必须留意
+drivers/scsi目录下的两个文件：Makefile以及Kconfig。建议参
+考现有底层驱动的代码组织方式。
+
+随着Linux内核2.5开发内核逐步演进为2.6系列的生产版本，该接口
+也引入了一些变化。以驱动初始化代码为例，现有两种模型可用。其
+中旧模型与Linux内核2.4的实现相似，他基于在加载HBA驱动时检测
+到的主机，被称为“被动（passive）”初始化模型。而新的模型允许
+在底层驱动（LLD）的生命周期内动态拔插HBA，这种方式被称为“热
+插拔（hotplug）”初始化模型。推荐使用新的模型，因为他既能处理
+传统的永久连接SCSI设备，也能处理现代支持热插拔的类SCSI设备
+（例如通过USB或IEEE 1394连接的数码相机）。这两种初始化模型将
+在后续的章节中分别讨论。
+
+SCSI底层驱动（LLD）通过以下3种方式与SCSI子系统进行交互：
+
+ a) 直接调用由SCSI中间层提供的接口函数
+ b) 将一组函数指针传递给中间层提供的注册函数，中间层将在
+ 后续运行的某个时刻调用这些函数。这些函数由LLD实现。
+ c) 直接访问中间层维护的核心数据结构
+
+a）组中所涉及的所有函数，均列于下文“中间层提供的函数”章节中。
+
+b）组中涉及的所有函数均列于下文名为“接口函数”的章节中。这些
+函数指针位于结构体struct scsi_host_template中，该结构体实
+例会被传递给scsi_host_alloc()。对于LLD未实现的接口函数，应
+对struct scsi_host_template中的对应成员赋NULL。如果在文件
+作用域定义一个struct scsi_host_template的实例，没有显式初
+始化的函数指针成员将自动设置为NULL。
+
+c）组中提到的用法在“热插拔”环境中尤其需要谨慎处理。LLD必须
+明确知晓这些与中间层及其他层级共享的数据结构的生命周期。
+
+LLD中定义的所有函数以及在文件作用域内定义的所有数据都应声明
+为static。例如，在一个名为“xxx”的LLD中的sdev_init()函数定
+义如下：
+``static int xxx_sdev_init(struct scsi_device * sdev) { /* code */ }``
+
+热插拔初始化模型
+================
+在该模型中，底层驱动（LLD）控制SCSI主机适配器在子系统中的注
+册与注销时机。主机最早可以在驱动初始化阶段被注册，最晚可以在
+驱动卸载时被移除。通常，驱动会响应来自sysfs probe()的回调，
+表示已检测到一个主机总线适配器（HBA）。在确认该新设备是LLD的
+目标设备后，LLD初始化HBA，并将一个新的SCSI主机适配器注册到
+SCSI中间层。
+
+在LLD初始化过程中，驱动应当向其期望发现HBA的IO总线（例如PCI
+总线）进行注册。该操作通常可以通过sysfs完成。任何驱动参数（
+特别是那些在驱动加载后仍可修改的参数）也可以在此时通过sysfs
+注册。当LLD注册其首个HBA时，SCSI中间层首次感受到该LLD的存在。
+
+在稍后的某个时间点，当LLD检测到新的HBA时，接下来在LLD与SCSI
+中间层之间会发生一系列典型的调用过程。该示例展示了中间层如何
+扫描新引入的HBA，在该过程中发现了3个SCSI设备，其中只有前两个
+设备有响应::
+
+ HBA探测：假设在扫描中发现2个SCSI设备
+ 底层驱动 中间层 底层驱动
+ =======---------------======---------------=======
+ scsi_host_alloc() -->
+ scsi_add_host() ---->
+ scsi_scan_host() -------+
+ |
+ sdev_init()
+ sdev_configure() --> scsi_change_queue_depth()
+ |
+ sdev_init()
+ sdev_configure()
+ |
+ sdev_init() ***
+ sdev_destroy() ***
+
+
+ *** 对于SCSI中间层尝试扫描但未响应的SCSI设备，系统调用
+ sdev_init()和sdev_destroy()函数对。
+
+如果LLD期望调整默认队列设置，可以在其sdev_configure()例程
+中调用scsi_change_queue_depth()。
+
+当移除一个HBA时，可能是由于卸载LLD模块相关的有序关闭（例如通
+过rmmod命令），也可能是由于sysfs的remove()回调而触发的“热拔
+插”事件。无论哪种情况，其执行顺序都是相同的::
+
+ HBA移除：假设连接了2个SCSI设备
+ 底层驱动 中间层 底层驱动
+ =======---------------------======-----------------=======
+ scsi_remove_host() ---------+
+ |
+ sdev_destroy()
+ sdev_destroy()
+ scsi_host_put()
+
+LLD用于跟踪struct Scsi_Host的实例可能会非常有用
+（scsi_host_alloc()返回的指针）。这些实例由中间层“拥有”。
+当引用计数为零时，struct Scsi_Host实例会被
+scsi_host_put()释放。
+
+HBA的热插拔是一个特殊的场景，特别是当HBA下的磁盘正在处理已挂
+载文件系统上的SCSI命令时。为了应对其中的诸多问题，中间层引入
+了引用计数逻辑。具体内容参考下文关于引用计数的章节。
+
+热插拔概念同样适用于SCSI设备。目前，当添加HBA时，
+scsi_scan_host() 函数会扫描该HBA所属SCSI传输通道上的设备。在
+新型SCSI传输协议中，HBA可能在扫描完成后才检测到新的SCSI设备。
+LLD可通过以下步骤通知中间层新SCSI设备的存在::
+
+ SCSI设备热插拔
+ 底层驱动 中间层 底层驱动
+ =======-------------------======-----------------=======
+ scsi_add_device() ------+
+ |
+ sdev_init()
+ sdev_configure() [--> scsi_change_queue_depth()]
+
+类似的，LLD可能会感知到某个SCSI设备已经被移除（拔出）或与他的连
+接已中断。某些现有的SCSI传输协议（例如SPI）可能直到后续SCSI命令
+执行失败时才会发现设备已经被移除，中间层会将该设备设置为离线状态。
+若LLD检测到SCSI设备已经被移除，可通过以下流程触发上层对该设备的
+移除操作::
+
+ SCSI设备热拔插
+ 底层驱动 中间层 底层驱动
+ =======-------------------======-----------------=======
+ scsi_remove_device() -------+
+ |
+ sdev_destroy()
+
+对于LLD而言，跟踪struct scsi_device实例可能会非常有用（该结构
+的指针会作为参数传递给sdev_init()和sdev_configure()回调函数）。
+这些实例的所有权归属于中间层（mid-level）。struct scsi_device
+实例在sdev_destroy()执行后释放。
+
+引用计数
+========
+Scsi_Host结构体已引入引用计数机制。该机制将struct Scsi_Host
+实例的所有权分散到使用他的各SCSI层，而此前这类实例完全由中间
+层独占管理。底层驱动（LLD）通常无需直接操作这些引用计数，仅在
+某些特定场景下可能需要介入。
+
+与struct Scsi_Host相关的引用计数函数主要有以下3种：
+
+ - scsi_host_alloc():
+ 返回指向新实例的指针，该实例的引用计数被设置为1。
+
+ - scsi_host_get():
+ 给定实例的引用计数加1。
+
+ - scsi_host_put():
+ 给定实例的引用计数减1。如果引用计数减少到0，则释放该实例。
+
+scsi_device结构体现已引入引用计数机制。该机制将
+struct scsi_device实例的所有权分散到使用他的各SCSI层，而此
+前这类实例完全由中间层独占管理。相关访问函数声明详见
+include/scsi/scsi_device.h文件末尾部分。若LLD需要保留
+scsi_device实例的指针副本，则应调用scsi_device_get()增加其
+引用计数；不再需要该指针时，可通过scsi_device_put()递减引用
+计数（该操作可能会导致该实例被释放）。
+
+.. Note::
+
+ struct Scsi_Host实际上包含两个并行维护的引用计数器，该引
+ 用计数由这些函数共同操作。
+
+编码规范
+========
+
+首先，Linus Torvalds关于C语言编码风格的观点可以在
+Documentation/process/coding-style.rst文件中找到。
+
+此外，在相关gcc编译器支持的前提下，鼓励使用大多数C99标准的增强
+特性。因此，在适当的情况下鼓励使用C99风格的结构体和数组初始化
+方式。但不要过度使用，目前对可变长度数组（VLA）的支持还待完善。
+一个例外是 ``//`` 风格的注释；在Linux中倾向于使
+用 ``/*...*/`` 注释格式。
+
+对于编写良好、经过充分测试且有完整文档的代码不需要重新格式化
+以符合上述规范。例如，aic7xxx驱动是从FreeBSD和Adaptec代码库
+移植到Linux的。毫无疑问，FreeBSD和Adaptec遵循其原有的编码规
+范。
+
+
+中间层提供的函数
+================
+这些函数由SCSI中间层提供，供底层驱动（LLD）调用。这些函数的名
+称（即入口点）均已导出，因此作为模块加载的LLD可以访问他们。内
+核会确保在任何LLD初始化之前，SCSI中间层已先行加载并完成初始化。
+下文按字母顺序列出这些函数，其名称均以 ``scsi_`` 开头。
+
+摘要：
+
+ - scsi_add_device - 创建新的SCSI逻辑单元（LU）设备实例
+ - scsi_add_host - 执行sysfs注册并设置传输类
+ - scsi_change_queue_depth - 调整SCSI设备队列深度
+ - scsi_bios_ptable - 返回块设备分区表的副本
+ - scsi_block_requests - 阻止向指定主机提交新命令
+ - scsi_host_alloc - 分配引用计数为1的新SCSI主机适配器实例scsi_host
+ - scsi_host_get - 增加SCSI主机适配器实例的引用计数
+ - scsi_host_put - 减少SCSI主机适配器的引用计数（归零时释放）
+ - scsi_remove_device - 卸载并移除SCSI设备
+ - scsi_remove_host - 卸载并移除主机控制器下的所有SCSI设备
+ - scsi_report_bus_reset - 报告检测到的SCSI总线复位事件
+ - scsi_scan_host - 执行SCSI总线扫描
+ - scsi_track_queue_full - 跟踪连续出现的队列满事件
+ - scsi_unblock_requests - 恢复向指定主机提交命令
+
+详细信息::
+
+ /**
+ * scsi_add_device - 创建新的SCSI逻辑单元（LU）设备实例
+ * @shost: 指向SCSI主机适配器实例的指针
+ * @channel: 通道号（通常为0）
+ * @id: 目标ID号
+ * @lun: 逻辑单元号（LUN）
+ *
+ * 返回指向新的struct scsi_device实例的指针，
+ * 如果出现异常（例如在给定地址没有设备响应），则返
+ * 回ERR_PTR(-ENODEV)
+ *
+ * 是否阻塞：是
+ *
+ * 注意事项：本函数通常在添加HBA的SCSI总线扫描过程
+ * 中由系统内部调用（即scsi_scan_host()执行期间）。因此，
+ * 仅应在以下情况调用：HBA在scsi_scan_host()完成扫描后，
+ * 又检测到新的SCSI设备（逻辑单元）。若成功执行，本次调用
+ * 可能会触发LLD的以下回调函数：sdev_init()以及
+ * sdev_configure()
+ *
+ * 函数定义：drivers/scsi/scsi_scan.c
+ **/
+ struct scsi_device * scsi_add_device(struct Scsi_Host *shost,
+ unsigned int channel,
+ unsigned int id, unsigned int lun)
+
+
+ /**
+ * scsi_add_host - 执行sysfs注册并设置传输类
+ * @shost: 指向SCSI主机适配器实例的指针
+ * @dev: 指向scsi类设备结构体（struct device）的指针
+ *
+ * 成功返回0，失败返回负的errno（例如：-ENOMEM）
+ *
+ * 是否阻塞：否
+ *
+ * 注意事项：仅在“热插拔初始化模型”中需要调用，且必须在
+ * scsi_host_alloc()成功执行后调用。该函数不会扫描总线；
+ * 总线扫描可通过调用scsi_scan_host()或其他传输层特定的
+ * 方法完成。在调用该函数之前，LLD必须先设置好传输模板，
+ * 并且只能在调用该函数之后才能访问传输类
+ * （transport class）相关的数据结构。
+ *
+ * 函数定义：drivers/scsi/hosts.c
+ **/
+ int scsi_add_host(struct Scsi_Host *shost, struct device * dev)
+
+
+ /**
+ * scsi_change_queue_depth - 调整SCSI设备队列深度
+ * @sdev: 指向要更改队列深度的SCSI设备的指针
+ * @tags 如果启用了标记队列，则表示允许的标记数，
+ * 或者在非标记模式下，LLD可以排队的命令
+ * 数（如 cmd_per_lun）。
+ *
+ * 无返回
+ *
+ * 是否阻塞：否
+ *
+ * 注意事项：可以在任何时刻调用该函数，只要该SCSI设备受该LLD控
+ * 制。[具体来说，可以在sdev_configure()执行期间或之后，且在
+ * sdev_destroy()执行之前调用。] 该函数可安全地在中断上下文中
+ * 调用。
+ *
+ * 函数定义：drivers/scsi/scsi.c [更多注释请参考源代码]
+ **/
+ int scsi_change_queue_depth(struct scsi_device *sdev, int tags)
+
+
+ /**
+ * scsi_bios_ptable - 返回块设备分区表的副本
+ * @dev: 指向块设备的指针
+ *
+ * 返回指向分区表的指针，失败返回NULL
+ *
+ * 是否阻塞：是
+ *
+ * 注意事项：调用方负责释放返回的内存（通过 kfree() 释放）
+ *
+ * 函数定义：drivers/scsi/scsicam.c
+ **/
+ unsigned char *scsi_bios_ptable(struct block_device *dev)
+
+
+ /**
+ * scsi_block_requests - 阻止向指定主机提交新命令
+ *
+ * @shost: 指向特定主机的指针，用于阻止命令的发送
+ *
+ * 无返回
+ *
+ * 是否阻塞：否
+ *
+ * 注意事项：没有定时器或其他任何机制可以解除阻塞，唯一的方式
+ * 是由LLD调用scsi_unblock_requests()方可恢复。
+ *
+ * 函数定义：drivers/scsi/scsi_lib.c
+ **/
+ void scsi_block_requests(struct Scsi_Host * shost)
+
+
+ /**
+ * scsi_host_alloc - 创建SCSI主机适配器实例并执行基础初始化
+ * @sht: 指向SCSI主机模板的指针
+ * @privsize: 在hostdata数组中分配的额外字节数（该数组是返
+ * 回的Scsi_Host实例的最后一个成员）
+ *
+ * 返回指向新的Scsi_Host实例的指针，失败返回NULL
+ *
+ * 是否阻塞：是
+ *
+ * 注意事项：当此调用返回给LLD时，该主机适配器上的
+ * SCSI总线扫描尚未进行。hostdata数组（默认长度为
+ * 零）是LLD专属的每主机私有区域，供LLD独占使用。
+ * 两个相关的引用计数都被设置为1。完整的注册（位于
+ * sysfs）与总线扫描由scsi_add_host()和
+ * scsi_scan_host()稍后执行。
+ * 函数定义：drivers/scsi/hosts.c
+ **/
+ struct Scsi_Host * scsi_host_alloc(const struct scsi_host_template * sht,
+ int privsize)
+
+
+ /**
+ * scsi_host_get - 增加SCSI主机适配器实例的引用计数
+ * @shost: 指向Scsi_Host实例的指针
+ *
+ * 无返回
+ *
+ * 是否阻塞：目前可能会阻塞，但可能迭代为不阻塞
+ *
+ * 注意事项：会同时增加struct Scsi_Host中两个子对
+ * 象的引用计数
+ *
+ * 函数定义：drivers/scsi/hosts.c
+ **/
+ void scsi_host_get(struct Scsi_Host *shost)
+
+
+ /**
+ * scsi_host_put - 减少SCSI主机适配器实例的引用计数
+ * （归零时释放）
+ * @shost: 指向Scsi_Host实例的指针
+ *
+ * 无返回
+ *
+ * 是否阻塞：当前可能会阻塞，但可能会改为不阻塞
+ *
+ * 注意事项：实际会递减两个子对象中的计数。当后一个引用
+ * 计数归零时系统会自动释放Scsi_Host实例。
+ * LLD 无需关注Scsi_Host实例的具体释放时机，只要在平衡
+ * 引用计数使用后不再访问该实例即可。
+ * 函数定义：drivers/scsi/hosts.c
+ **/
+ void scsi_host_put(struct Scsi_Host *shost)
+
+
+ /**
+ * scsi_remove_device - 卸载并移除SCSI设备
+ * @sdev: 指向SCSI设备实例的指针
+ *
+ * 返回值：成功返回0，若设备未连接，则返回-EINVAL
+ *
+ * 是否阻塞：是
+ *
+ * 如果LLD发现某个SCSI设备（逻辑单元，lu）已经被移除，
+ * 但其主机适配器实例依旧存在，则可以请求移除该SCSI设备。
+ * 如果该调用成功将触发sdev_destroy()回调函数的执行。调
+ * 用完成后，sdev将变成一个无效的指针。
+ *
+ * 函数定义：drivers/scsi/scsi_sysfs.c
+ **/
+ int scsi_remove_device(struct scsi_device *sdev)
+
+
+ /**
+ * scsi_remove_host - 卸载并移除主机控制器下的所有SCSI设备
+ * @shost: 指向SCSI主机适配器实例的指针
+ *
+ * 返回值：成功返回0，失败返回1（例如：LLD正忙？？）
+ *
+ * 是否阻塞：是
+ *
+ * 注意事项：仅在使用“热插拔初始化模型”时调用。应在调用
+ * scsi_host_put()前调用。
+ *
+ * 函数定义：drivers/scsi/hosts.c
+ **/
+ int scsi_remove_host(struct Scsi_Host *shost)
+
+
+ /**
+ * scsi_report_bus_reset - 报告检测到的SCSI总线复位事件
+ * @shost: 指向关联的SCSI主机适配器的指针
+ * @channel: 发生SCSI总线复位的通道号
+ *
+ * 返回值：无
+ *
+ * 是否阻塞：否
+ *
+ * 注意事项：仅当复位来自未知来源时才需调用此函数。
+ * 由SCSI中间层发起的复位无需调用，但调用也不会导
+ * 致副作用。此函数的主要作用是确保系统能正确处理
+ * CHECK_CONDITION状态。
+ *
+ * 函数定义：drivers/scsi/scsi_error.c
+ **/
+ void scsi_report_bus_reset(struct Scsi_Host * shost, int channel)
+
+
+ /**
+ * scsi_scan_host - 执行SCSI总线扫描
+ * @shost: 指向SCSI主机适配器实例的指针
+ *
+ * 是否阻塞：是
+ *
+ * 注意事项：应在调用scsi_add_host()后调用
+ *
+ * 函数定义：drivers/scsi/scsi_scan.c
+ **/
+ void scsi_scan_host(struct Scsi_Host *shost)
+
+
+ /**
+ * scsi_track_queue_full - 跟踪指定设备上连续的QUEUE_FULL
+ * 事件，以判断是否需要及何时调整
+ * 该设备的队列深度。
+ * @sdev: 指向SCSI设备实例的指针
+ * @depth: 当前该设备上未完成的SCSI命令数量（不包括返回
+ * QUEUE_FULL的命令）
+ *
+ * 返回值：0 - 当前队列深度无需调整
+ * >0 - 需要将队列深度调整为此返回值指定的新深度
+ * -1 - 需要回退到非标记操作模式，并使用
+ * host->cmd_per_lun作为非标记命令队列的
+ * 深度限制
+ *
+ * 是否阻塞：否
+ *
+ * 注意事项：LLD可以在任意时刻调用该函数。系统将自动执行“正确
+ * 的处理流程”；该函数支持在中断上下文中安全地调用
+ *
+ * 函数定义：drivers/scsi/scsi.c
+ **/
+ int scsi_track_queue_full(struct scsi_device *sdev, int depth)
+
+
+ /**
+ * scsi_unblock_requests - 恢复向指定主机适配器提交命令
+ *
+ * @shost: 指向要解除阻塞的主机适配器的指针
+ *
+ * 返回值：无
+ *
+ * 是否阻塞：否
+ *
+ * 函数定义：drivers/scsi/scsi_lib.c
+ **/
+ void scsi_unblock_requests(struct Scsi_Host * shost)
+
+
+
+接口函数
+========
+接口函数由底层驱动（LLD）定义实现，其函数指针保存在
+struct scsi_host_template实例中，并将该实例传递给
+scsi_host_alloc()。
+部分接口函数为必选实现项。所有
+接口函数都应声明为static，约定俗成的命名规则如下，
+驱动“xyz”应将其sdev_configure()函数声明为::
+
+ static int xyz_sdev_configure(struct scsi_device * sdev);
+
+其余接口函数的命名规范均依此类推。
+
+需将该函数指针赋值给“struct scsi_host_template”实例
+的‘sdev_configure’成员变量中，并将该结构体实例指针传
+递到中间层的scsi_host_alloc()函数。
+
+各个接口函数的详细说明可参考include/scsi/scsi_host.h
+文件，具体描述位于“struct scsi_host_template”结构体
+各个成员的上方。在某些情况下，scsi_host.h头文件中的描
+述比本文提供的更为详尽。
+
+以下按字母顺序列出所有接口函数及其说明。
+
+摘要：
+
+ - bios_param - 获取磁盘的磁头/扇区/柱面参数
+ - eh_timed_out - SCSI命令超时回调
+ - eh_abort_handler - 中止指定的SCSI命令
+ - eh_bus_reset_handler - 触发SCSI总线复位
+ - eh_device_reset_handler - 执行SCSI设备复位
+ - eh_host_reset_handler - 复位主机（主机总线适配器）
+ - info - 提供指定主机适配器的相关信息
+ - ioctl - 驱动可响应ioctl控制命令
+ - proc_info - 支持/proc/scsi/{驱动名}/{主机号}文件节点的读写操作
+ - queuecommand - 将SCSI命令提交到主机控制器，命令执行完成后调用‘done’回调
+ - sdev_init - 在向新设备发送SCSI命令前的初始化
+ - sdev_configure - 设备挂载后的精细化微调
+ - sdev_destroy - 设备即将被移除前的清理
+
+
+详细信息::
+
+ /**
+ * bios_param - 获取磁盘的磁头/扇区/柱面参数
+ * @sdev: 指向SCSI设备实例的指针（定义于
+ * include/scsi/scsi_device.h中）
+ * @bdev: 指向块设备实例的指针（定义于fs.h中）
+ * @capacity: 设备容量（以512字节扇区为单位）
+ * @params: 三元数组用于保存输出结果：
+ * params[0]：磁头数量（最大255）
+ * params[1]：扇区数量（最大63）
+ * params[2]：柱面数量
+ *
+ * 返回值：被忽略
+ *
+ * 并发安全声明: 无锁
+ *
+ * 调用上下文说明: 进程上下文（sd）
+ *
+ * 注意事项: 若未提供此函数，系统将基于READ CAPACITY
+ * 使用默认几何参数。params数组已预初始化伪值，防止函
+ * 数无输出。
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ int bios_param(struct scsi_device * sdev, struct block_device *bdev,
+ sector_t capacity, int params[3])
+
+
+ /**
+ * eh_timed_out - SCSI命令超时回调
+ * @scp: 标识超时的命令
+ *
+ * 返回值:
+ *
+ * EH_HANDLED: 我已修复该错误，请继续完成该命令
+ * EH_RESET_TIMER: 我需要更多时间，请重置定时器并重新开始计时
+ * EH_NOT_HANDLED 开始正常的错误恢复流程
+ *
+ * 并发安全声明: 无锁
+ *
+ * 调用上下文说明: 中断上下文
+ *
+ * 注意事项: 该回调函数为LLD提供一个机会进行本地
+ * 错误恢复处理。此处的恢复仅限于判断该未完成的命
+ * 令是否还有可能完成。此回调中不允许中止或重新启
+ * 动该命令。
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ int eh_timed_out(struct scsi_cmnd * scp)
+
+
+ /**
+ * eh_abort_handler - 中止指定的SCSI命令
+ * @scp: 标识要中止的命令
+ *
+ * 返回值：如果命令成功中止，则返回SUCCESS，否则返回FAILED
+ *
+ * 并发安全声明: 无锁
+ *
+ * 调用上下文说明: 内核线程
+ *
+ * 注意事项: 该函数仅在命令超时时才被调用。
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ int eh_abort_handler(struct scsi_cmnd * scp)
+
+
+ /**
+ * eh_bus_reset_handler - 发起SCSI总线复位
+ * @scp: 包含该设备的SCSI总线应进行重置
+ *
+ * 返回值：重置成功返回SUCCESS；否则返回FAILED
+ *
+ * 并发安全声明: 无锁
+ *
+ * 调用上下文说明: 内核线程
+ *
+ * 注意事项: 由SCSI错误处理线程（scsi_eh）调用。
+ * 在错误处理期间，当前主机适配器的所有IO请求均
+ * 被阻塞。
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ int eh_bus_reset_handler(struct scsi_cmnd * scp)
+
+
+ /**
+ * eh_device_reset_handler - 发起SCSI设备复位
+ * @scp: 指定将被重置的SCSI设备
+ *
+ * 返回值：如果命令成功中止返回SUCCESS，否则返回FAILED
+ *
+ * 并发安全声明: 无锁
+ *
+ * 调用上下文说明: 内核线程
+ *
+ * 注意事项: 由SCSI错误处理线程（scsi_eh）调用。
+ * 在错误处理期间，当前主机适配器的所有IO请求均
+ * 被阻塞。
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ int eh_device_reset_handler(struct scsi_cmnd * scp)
+
+
+ /**
+ * eh_host_reset_handler - 复位主机（主机总线适配器）
+ * @scp: 管理该设备的SCSI主机适配器应该被重置
+ *
+ * 返回值：如果命令成功中止返回SUCCESS，否则返回FAILED
+ *
+ * 并发安全声明: 无锁
+ *
+ * 调用上下文说明: 内核线程
+ *
+ * 注意事项: 由SCSI错误处理线程（scsi_eh）调用。
+ * 在错误处理期间，当前主机适配器的所有IO请求均
+ * 被阻塞。当使用默认的eh_strategy策略时，如果
+ * _abort_、_device_reset_、_bus_reset_和该处
+ * 理函数均未定义（或全部返回FAILED），系统强制
+ * 该故障设备处于离线状态
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ int eh_host_reset_handler(struct scsi_cmnd * scp)
+
+
+ /**
+ * info - 提供给定主机适配器的详细信息：驱动程序名称
+ * 以及用于区分不同主机适配器的数据结构
+ * @shp: 指向目标主机的struct Scsi_Host实例
+ *
+ * 返回值：返回以NULL结尾的ASCII字符串。[驱动
+ * 负责管理返回的字符串所在内存并确保其在整个
+ * 主机适配器生命周期内有效。]
+ *
+ * 并发安全声明: 无锁
+ *
+ * 调用上下文说明: 进程上下文
+ *
+ * 注意事项: 通常提供诸如I/O地址或中断号
+ * 等PCI或ISA信息。如果未实现该函数，则
+ * 默认使用struct Scsi_Host::name 字段。
+ * 返回的字符串应为单行（即不包含换行符）。
+ * 通过SCSI_IOCTL_PROBE_HOST ioctl可获
+ * 取该函数返回的字符串，如果该函数不可用，
+ * 则ioctl返回struct Scsi_Host::name中
+ * 的字符串。
+
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ const char * info(struct Scsi_Host * shp)
+
+
+ /**
+ * ioctl - 驱动可响应ioctl控制命令
+ * @sdp: ioctl操作针对的SCSI设备
+ * @cmd: ioctl命令号
+ * @arg: 指向用户空间读写数据的指针。由于他指向用
+ * 户空间，必须使用适当的内核函数
+ * （如 copy_from_user()）。按照Unix的风
+ * 格，该参数也可以视为unsigned long 类型。
+ *
+ * 返回值：如果出错则返回负的“errno”值。返回0或正值表
+ * 示成功，并将返回值传递给用户空间。
+ *
+ * 并发安全声明：无锁
+ *
+ * 调用上下文说明：进程上下文
+ *
+ * 注意事项：SCSI子系统使用“逐层下传
+ * （trickle down）”的ioctl模型。
+ * 用户层会对上层驱动设备节点
+ * （例如/dev/sdc）发起ioctl()调用，
+ * 如果上层驱动无法识别该命令，则将其
+ * 传递给SCSI中间层，若中间层也无法识
+ * 别，则再传递给控制该设备的LLD。
+ * 根据最新的Unix标准，对于不支持的
+ * ioctl()命令，应返回-ENOTTY。
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ int ioctl(struct scsi_device *sdp, int cmd, void *arg)
+
+
+ /**
+ * proc_info - 支持/proc/scsi/{驱动名}/{主机号}文件节点的读写操作
+ * @buffer: 输入或出的缓冲区锚点（writeto1_read0==0表示向buffer写
+ * 入，writeto1_read0==1表示由buffer读取）
+ * @start: 当writeto1_read0==0时，用于指定驱动实际填充的起始位置；
+ * 当writeto1_read0==1时被忽略。
+ * @offset: 当writeto1_read0==0时，表示用户关注的数据在缓冲区中的
+ * 偏移。当writeto1_read0==1时忽略。
+ * @length: 缓冲区的最大（或实际使用）长度
+ * @host_no: 目标SCSI Host的编号（struct Scsi_Host::host_no）
+ * @writeto1_read0: 1 -> 表示数据从用户空间写入驱动
+ * （例如，“echo some_string > /proc/scsi/xyz/2”）
+ * 0 -> 表示用户从驱动读取数据
+ * （例如，“cat /proc/scsi/xyz/2”）
+ *
+ * 返回值：当writeto1_read0==1时返回写入长度。否则，
+ * 返回从offset偏移开始输出到buffer的字符数。
+ *
+ * 并发安全声明：无锁
+ *
+ * 调用上下文说明：进程上下文
+ *
+ * 注意事项：该函数由scsi_proc.c驱动，与proc_fs交互。
+ * 当前SCSI子系统可移除对proc_fs的支持，相关配置选。
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ int proc_info(char * buffer, char ** start, off_t offset,
+ int length, int host_no, int writeto1_read0)
+
+
+ /**
+ * queuecommand - 将SCSI命令提交到主机控制器，命令执行完成后调用scp->scsi_done回调函数
+ * @shost: 指向目标SCSI主机控制器
+ * @scp: 指向待处理的SCSI命令
+ *
+ * 返回值：成功返回0。
+ *
+ * 如果发生错误，则返回：
+ *
+ * SCSI_MLQUEUE_DEVICE_BUSY表示设备队列满，
+ * SCSI_MLQUEUE_HOST_BUSY表示整个主机队列满
+ *
+ * 在这两种情况下，中间层将自动重新提交该I/O请求
+ *
+ * - 若返回SCSI_MLQUEUE_DEVICE_BUSY，则仅暂停该
+ * 特定设备的命令处理，当该设备的某个命令完成返回
+ * 时（或在短暂延迟后如果没有其他未完成命令）将恢
+ * 复其处理。其他设备的命令仍正常继续处理。
+ *
+ * - 若返回SCSI_MLQUEUE_HOST_BUSY，将暂停该主机
+ * 的所有I/O操作，当任意命令从该主机返回时（或在
+ * 短暂延迟后如果没有其他未完成命令）将恢复处理。
+ *
+ * 为了与早期的queuecommand兼容，任何其他返回值
+ * 都被视作SCSI_MLQUEUE_HOST_BUSY。
+ *
+ * 对于其他可立即检测到的错误，可通过以下流程处
+ * 理：设置scp->result为适当错误值，调用scp->scsi_done
+ * 回调函数，然后该函数返回0。若该命令未立即执行（LLD
+ * 正在启动或将要启动该命令），则应将scp->result置0并
+ * 返回0。
+ *
+ * 命令所有权说明：若驱动返回0，则表示驱动获得该命令的
+ * 所有权，
+ * 并必须确保最终执行scp->scsi_done回调函数。注意：驱动
+ * 可以在返回0之前调用scp->scsi_done，但一旦调用该回
+ * 调函数后，就只能返回0。若驱动返回非零值，则禁止在任何时
+ * 刻执行该命令的scsi_done回调函数。
+ *
+ * 并发安全声明：在2.6.36及更早的内核版本中，调用该函数时持有
+ * struct Scsi_Host::host_lock锁（通过“irqsave”获取中断安全的自旋锁），
+ * 并且返回时仍需保持该锁；从Linux 2.6.37开始，queuecommand
+ * 将在无锁状态下被调用。
+ *
+ * 调用上下文说明：在中断（软中断）或进程上下文中
+ *
+ * 注意事项：该函数执行应当非常快速，通常不会等待I/O
+ * 完成。因此scp->scsi_done回调函数通常会在该函数返
+ * 回后的某个时刻被调用（经常直接从中断服务例程中调用）。
+ * 某些情况下（如模拟SCSI INQUIRY响应的伪适配器驱动），
+ * scp->scsi_done回调可能在该函数返回前就被调用。
+ * 若scp->scsi_done回调函数未在指定时限内被调用，SCSI中
+ * 间层将启动错误处理流程。当调用scp->scsi_done回调函数
+ * 时，若“result”字段被设置为CHECK CONDITION，
+ * 则LLD应执行自动感知并填充
+ * struct scsi_cmnd::sense_buffer数组。在中间层将
+ * 命令加入LLD队列之前前，scsi_cmnd::sense_buffer数组
+ * 会被清零。
+ *
+ * 可选实现说明：LLD必须实现
+ **/
+ int queuecommand(struct Scsi_Host *shost, struct scsi_cmnd * scp)
+
+
+ /**
+ * sdev_init - 在向新设备发送任何SCSI命令前（即开始扫描
+ * 之前）调用该函数
+ * @sdp: 指向即将被扫描的新设备的指针
+ *
+ * 返回值：返回0表示正常。返回其他值表示出错，
+ * 该设备将被忽略。
+ *
+ * 并发安全声明：无锁
+ *
+ * 调用上下文说明：进程上下文
+ *
+ * 注意事项：该函数允许LLD在设备首次扫描前分配所需的资源。
+ * 对应的SCSI设备可能尚未真正存在，但SCSI中间层即将对其进
+ * 行扫描（例如发送INQUIRY命令等）。如果设备存在，将调用
+ * sdev_configure()进行配置；如果设备不存在，则调用
+ * sdev_destroy()销毁。更多细节请参考
+ * include/scsi/scsi_host.h文件。
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ int sdev_init(struct scsi_device *sdp)
+
+
+ /**
+ * sdev_configure - 在设备首次完成扫描（即已成功响应INQUIRY
+ * 命令）之后，LDD可调用该函数对设备进行进一步配置
+ * @sdp: 已连接的设备
+ *
+ * 返回值：返回0表示成功。任何其他返回值都被视为错误，此时
+ * 设备将被标记为离线。[被标记离线的设备不会调用sdev_destroy()，
+ * 因此需要LLD主动清理资源。]
+ *
+ * 并发安全声明：无锁
+ *
+ * 调用上下文说明：进程上下文
+ *
+ * 注意事项：该接口允许LLD查看设备扫描代码所发出的初始INQUIRY
+ * 命令的响应，并采取对应操作。具体实现细节请参阅
+ * include/scsi/scsi_host.h文件。
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ int sdev_configure(struct scsi_device *sdp)
+
+
+ /**
+ * sdev_destroy - 当指定设备即将被关闭时调用。此时该设备
+ * 上的所有I/O活动均已停止。
+ * @sdp: 即将关闭的设备
+ *
+ * 返回值：无
+ *
+ * 并发安全声明：无锁
+ *
+ * 调用上下文说明：进程上下文
+ *
+ * 注意事项：该设备的中间层数据结构仍然存在
+ * 但即将被销毁。驱动程序此时应当释放为该设
+ * 备分配的所有专属资源。系统将不再向此sdp
+ * 实例发送任何命令。[但该设备可能在未来被
+ * 重新连接，届时将通过新的struct scsi_device
+ * 实例，并触发后续的sdev_init()和
+ * sdev_configure()调用过程。]
+ *
+ * 可选实现说明：由LLD选择性定义
+ **/
+ void sdev_destroy(struct scsi_device *sdp)
+
+
+
+数据结构
+========
+struct scsi_host_template
+-------------------------
+每个LLD对应一个“struct scsi_host_template”
+实例 [#]_。该结构体通常被初始化为驱动头文件中的静
+态全局变量，此方式可确保未显式初始化的成员自动置零
+（0或NULL）。关键成员变量说明如下：
+
+ name
+ - 驱动程序的名称（可以包含空格，请限制在80个字符以内）
+
+ proc_name
+ - 在“/proc/scsi/<proc_name>/<host_no>”
+ 和sysfs的“drivers”目录中使用的名称。因此
+ “proc_name”应仅包含Unix文件名中可接受
+ 的字符。
+
+ ``(*queuecommand)()``
+ - 中间层使用的主要回调函数，用于将SCSI命令
+ 提交到LLD。
+
+ vendor_id
+ - 该字段是一个唯一标识值，用于确认提供
+ Scsi_Host LLD的供应商，最常用于
+ 验证供应商特定的消息请求。该值由标识符类型
+ 和供应商特定值组成，有效格式描述请参阅
+ scsi_netlink.h头文件。
+
+该结构体的完整定义及详细注释请参阅 ``include/scsi/scsi_host.h``。
+
+.. [#] 在极端情况下，单个驱动需要控制多种不同类型的硬件时，驱动可
+ 能包含多个实例，（例如某个LLD驱动同时处理ISA和PCI两种类型
+ 的适配卡，并为每种硬件类型维护独立的
+ struct scsi_host_template实例）。
+
+struct Scsi_Host
+----------------
+每个由LLD控制的主机适配器对应一个struct Scsi_Host实例。
+该结构体与struct scsi_host_template具有多个相同成员。
+当创建struct Scsi_Host实例时（通过hosts.c中的
+scsi_host_alloc()函数），这些通用成员会从LLD的
+struct scsi_host_template实例初始化而来。关键成员说明
+如下：
+
+ host_no
+ - 系统范围内唯一的主机标识号，按升序从0开始分配
+ can_queue
+ - 必须大于0，表示适配器可处理的最大并发命令数，禁
+ 止向适配器发送超过此数值的命令数
+ this_id
+ - 主机适配器的SCSI ID（SCSI启动器标识），若未知则
+ 设置为-1
+ sg_tablesize
+ - 主机适配器支持的最大散列表（scatter-gather）元素
+ 数。设置为SG_ALL或更小的值可避免使用链式SG列表，
+ 且最小值必须为1
+ max_sectors
+ - 单个SCSI命令中允许的最大扇区数（通常为512字节/
+ 扇区）。默认值为0，此时会使用
+ SCSI_DEFAULT_MAX_SECTORS（在scsi_host.h中定义），
+ 当前该值为1024。因此，如果未定义max_sectors，则磁盘的
+ 最大传输大小为512KB。注意：这个大小可能不足以支持
+ 磁盘固件上传。
+ cmd_per_lun
+ - 主机适配器的设备上，每个LUN可排队的最大命令数。
+ 此值可通过LLD调用scsi_change_queue_depth()进行
+ 调整。
+ hostt
+ - 指向LLD struct scsi_host_template实例的指针，
+ 当前struct Scsi_Host实例正是由此模板生成。
+ hostt->proc_name
+ - LLD的名称，sysfs使用的驱动名。
+ transportt
+ - 指向LLD struct scsi_transport_template实例的指
+ 针（如果存在）。当前支持FC与SPI传输协议。
+ hostdata[0]
+ - 为LLD在struct Scsi_Host结构体末尾预留的区域，大小由
+ scsi_host_alloc()的第二个参数(privsize)决定。
+
+scsi_host结构体的完整定义详见include/scsi/scsi_host.h。
+
+struct scsi_device
+------------------
+通常而言，每个SCSI逻辑单元（Logical Unit）对应一个该结构
+的实例。连接到主机适配器的SCSI设备通过三个要素唯一标识：通
+道号（Channel Number）、目标ID（Target ID）和逻辑单元号
+（LUN）。
+该结构体完整定义于include/scsi/scsi_device.h。
+
+struct scsi_cmnd
+----------------
+该结构体实例用于在LLD与SCSI中间层之间传递SCSI命令
+及其响应。SCSI中间层会确保：提交到LLD的命令数不超过
+scsi_change_queue_depth()（或struct Scsi_Host::cmd_per_lun）
+设定的上限，且每个SCSI设备至少分配一个struct scsi_cmnd实例。
+关键成员说明如下：
+
+ cmnd
+ - 包含SCSI命令的数组
+ cmd_len
+ - SCSI命令的长度（字节为单位）
+ sc_data_direction
+ - 数据的传输方向。请参考
+ include/linux/dma-mapping.h中的
+ “enum dma_data_direction”。
+ result
+ - LLD在调用“done”之前设置该值。值为0表示命令成功
+ 完成（并且所有数据（如果有）已成功在主机与SCSI
+ 目标设备之间完成传输）。“result”是一个32位无符
+ 号整数，可以视为2个相关字节。SCSI状态值位于最
+ 低有效位。请参考include/scsi/scsi.h中的
+ status_byte()与host_byte()宏以及其相关常量。
+ sense_buffer
+ - 这是一个数组（最大长度为SCSI_SENSE_BUFFERSIZE
+ 字节），当SCSI状态（“result”的最低有效位）设为
+ CHECK_CONDITION（2）时，该数组由LLD填写。若
+ CHECK_CONDITION被置位，且sense_buffer[0]的高
+ 半字节值为7，则中间层会认为sense_buffer数组
+ 包含有效的SCSI感知数据；否则，中间层会发送
+ REQUEST_SENSE SCSI命令来获取感知数据。由于命令
+ 排队的存在，后一种方式容易出错，因此建议LLD始终
+ 支持“自动感知”。
+ device
+ - 指向与该命令关联的scsi_device对象的指针。
+ resid_len (通过调用scsi_set_resid() / scsi_get_resid()访问)
+ - LLD应将此无符号整数设置为请求的传输长度（即
+ “request_bufflen”）减去实际传输的字节数。“resid_len”
+ 默认设置为0，因此如果LLD无法检测到数据欠载（不能报告溢出），
+ 则可以忽略它。LLD应在调用“done”之前设置
+ “resid_len”。
+ underflow
+ - 如果实际传输的字节数小于该字段值，LLD应将
+ DID_ERROR << 16赋值给“result”。并非所有
+ LLD都实现此项检查，部分LLD仅将错误信息输出
+ 到日志，而未真正报告DID_ERROR。更推荐
+ 的做法是由LLD实现“resid_len”的支持。
+
+建议LLD在从SCSI目标设备进行数据传输时设置“resid_len”字段
+（例如READ操作）。当这些数据传输的感知码是MEDIUM ERROR或
+HARDWARE ERROR（有时也包括RECOVERED ERROR）时设置
+resid_len尤为重要。在这种情况下，如果LLD无法确定接收了多
+少数据，那么最安全的做法是表示没有接收到任何数据。例如：
+为了表明没有接收到任何有效数据，LLD可以使用如下辅助函数::
+
+ scsi_set_resid(SCpnt, scsi_bufflen(SCpnt));
+
+其中SCpnt是一个指向scsi_cmnd对象的指针。如果表示仅接收到
+三个512字节的数据块，可以这样设置resid_len::
+
+ scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512));
+
+scsi_cmnd结构体定义在 include/scsi/scsi_cmnd.h文件中。
+
+
+锁
+===
+每个struct Scsi_Host实例都有一个名为default_lock
+的自旋锁（spin_lock），它在scsi_host_alloc()函数
+中初始化（该函数定义在hosts.c文件中）。在同一个函数
+中，struct Scsi_Host::host_lock指针会被初始化为指
+向default_lock。此后，SCSI中间层执行的加
+锁和解锁操作都会使用host_lock指针。过去，驱动程序可
+以重写host_lock指针，但现在不再允许这样做。
+
+
+自动感知
+========
+自动感知（Autosense或auto-sense）在SAM-2规范中被定
+义为：当SCSI命令完成状态为CHECK CONDITION时，“自动
+将感知数据（sense data）返回给应用程序客户端”。底层
+驱动（LLD）应当执行自动感知。当LLD检测到
+CHECK CONDITION状态时，可通过以下任一方式完成：
+
+ a) 要求SCSI协议（例如SCSI并行接口（SPI））在此
+ 类响应中执行一次额外的数据传输
+
+ b) 或由LLD主动发起REQUEST SENSE命令获取感知数据
+
+无论采用哪种方式，当检测到CHECK CONDITION状态时，中
+间层通过检查结构体scsi_cmnd::sense_buffer[0]的值来
+判断LLD是否已执行自动感知。若该字节的高半字节为7
+（或 0xf），则认为已执行自动感知；若该字节为其他值
+（且此字节在每条命令执行前会被初始化为0），则中间层将
+主动发起REQUEST SENSE命令。
+
+在存在命令队列的场景下，保存失败命令感知数据的“nexus”
+可能会在等待REQUEST SENSE命令期间变得不同步。因此，
+最佳实践是由LLD执行自动感知。
+
+
+自Linux内核2.4以来的变更
+========================
+io_request_lock已被多个细粒度锁替代。与底层驱动
+（LLD）相关的锁是struct Scsi_Host::host_lock，且每
+个SCSI主机都独立拥有一个该锁。
+
+旧的错误处理机制已经被移除。这意味着LLD的接口函数
+abort()与reset()已经被删除。
+struct scsi_host_template::use_new_eh_code标志
+也已经被移除。
+
+在Linux内核2.4中，SCSI子系统的配置描述与其他Linux子系
+统的配置描述集中存放在Documentation/Configure.help
+文件中。在Linux内核2.6中，SCSI子系统拥有独立的配置文
+件drivers/scsi/Kconfig（体积更小），同时包含配置信息
+与帮助信息。
+
+struct SHT已重命名为struct scsi_host_template。
+
+新增“热插拔初始化模型”以及许多用于支持该功能的额外函数。
+
+
+致谢
+====
+以下人员对本文档做出了贡献：
+
+ - Mike Anderson <andmike at us dot ibm dot com>
+ - James Bottomley <James dot Bottomley at hansenpartnership dot com>
+ - Patrick Mansfield <patmans at us dot ibm dot com>
+ - Christoph Hellwig <hch at infradead dot org>
+ - Doug Ledford <dledford at redhat dot com>
+ - Andries Brouwer <Andries dot Brouwer at cwi dot nl>
+ - Randy Dunlap <rdunlap at xenotime dot net>
+ - Alan Stern <stern at rowland dot harvard dot edu>
+
+
+Douglas Gilbert
+dgilbert at interlog dot com
+
+2004年9月21日
\ No newline at end of file
diff --git a/Documentation/translations/zh_CN/scsi/sd-parameters.rst b/Documentation/translations/zh_CN/scsi/sd-parameters.rst
new file mode 100644
index 000000000000..662caec15b4d
--- /dev/null
+++ b/Documentation/translations/zh_CN/scsi/sd-parameters.rst
@@ -0,0 +1,38 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/scsi/sd-parameters.rst
+
+:翻译:
+
+ 郝栋栋 Dongdong Hao <doubled@xxxxxxxxxxx>
+
+:校译:
+
+
+
+============================
+Linux SCSI磁盘驱动（sd）参数
+============================
+
+缓存类型（读/写）
+------------------
+启用/禁用驱动器读写缓存。
+
+=========================== ===== ===== ======= =======
+ 缓存类型字符串 WCE RCD 写缓存 读缓存
+=========================== ===== ===== ======= =======
+ write through 0 0 关闭 开启
+ none 0 1 关闭 关闭
+ write back 1 0 开启 开启
+ write back, no read (daft) 1 1 开启 关闭
+=========================== ===== ===== ======= =======
+
+将缓存类型设置为“write back”并将该设置保存到驱动器::
+
+ # echo "write back" > cache_type
+
+如果要修改缓存模式但不使更改持久化，可在缓存类型字符串前
+添加“temporary ”。例如::
+
+ # echo "temporary write back" > cache_type
diff --git a/Documentation/translations/zh_CN/subsystem-apis.rst b/Documentation/translations/zh_CN/subsystem-apis.rst
index 8b646c1010be..0f121f9b0f70 100644
--- a/Documentation/translations/zh_CN/subsystem-apis.rst
+++ b/Documentation/translations/zh_CN/subsystem-apis.rst
@@ -71,12 +71,12 @@ TODOList:
:maxdepth: 1
filesystems/index
+ scsi/index
TODOList:
* block/index
* cdrom/index
-* scsi/index
* target/index
**Fixme**: 这里还需要更多的分类组织工作。
--
2.25.1
