【NVMe2.0b 14-7】Set Features（上篇）

5.27Set Features command

Set Features命令指定了所指示的Feature的属性。

Set Features 命令使用Data Pointer、Command Dword 10和Command Dword 14。Command Dword 11、Command Dword 12、Command Dword 13和Command Dword 15字段的使用是针对Feature的。如果不使用Command Dword 11、Command Dword 12、Command Dword 13或Command Dword 15字段，那么这些Command Dwords 就被保留。

Figure 313: Set Features – Data Pointer

Bits	Description
127:00	Data Pointer (DPTR): 该字段指定了 data buffer 的起始位置。关于这个字段的定义，请参考Figure 87。如果使用PRP，这个字段不应该是指向PRP List的指针，因为data buffer不能跨越一个以上的page边界。如果没有使用data structure作为指定feature的一部分，那么这个字段就不使用。

Figure 314: Set Features – Command Dword 10

如果控制器支持通过Set Features命令选择UUID（参考Figure 316和第8.25节），并且控制器支持为指定的vendor specific feature identifier选择UUID（参考Figure 316），那么Command Dword 14用于指定UUID Index值（参考Figure 315）。如果控制器不支持通过Set Features命令选择UUID，或者控制器不支持为指定的vendor specific feature identifier选择UUID，那么Command Dword 14不指定UUID Index值。

Figure 315: Set Features – Command Dword 14

5.27.1Feature Specific Information

Figure 316定义了可以用Set Features命令配置和用Get Features命令检索的features。关于各种控制器类型的强制、可选和禁止features，请参考3.1.2节。一些 Features 利用 memory buffer 来配置或返回 Feature 的属性，而其他features只利用命令或completion queue entry中的一个dword。如果一个Feature在power cycle和reset中不是持久的，那么作为Controller Level Reset的一部分，该Feature的 current value 应被设置为该Feature的 default value。关于Features的更多信息，包括default value的定义、save value的定义和 current value的定义，请参考第4.2节。

在完成一个feature的Set Features后，主机应该重新发现、重新列举和/或重新初始化与该Feature相关的所有capabilities。例如，如果一个Feature可能发生namespace capability的变化，那么主机软件应该暂停使用任何相关的命名空间，提交该Feature的 Set Features命令并等待该命令完成，然后重新向受该Set Features命令影响的所有命名空间发出命令。

当一个Feature被改变时，可能有命令正在执行。新的设置可能适用于也可能不适用于改变Feature时已提交执行的命令。在成功完成Set Features命令后提交到Submission Queue的任何命令都应使用相关feature的新设置。为确保Features值适用于所有后续命令，主机应允许正在处理的命令在发出Set Features命令前完成。

如果控制器不支持某个Feature的可变的值（例如，该Feature是不可变的），并且为该Feature处理了一个Set Features的命令，那么如果该命令指定了一个Feature值，那么:

• 与该Feature的现有值不一样，那么控制器应中止该命令，状态码为Feature Not Changeable；
• 与该Feature的现有值相同，那么控制器可以：
  o成功完成该Set Features命令
  o中止该命令，状态码为Feature Not Changeable

Figure 316: Set Features – Feature Identifiers

5.27.1.1Arbitration (Feature Identifier 01h)

该特性控制命令仲裁。请参阅第3.4.4节，以了解命令仲裁的细节。这些属性在Command Dword 11中指定。

如果为这个特性提交了Get Features命令，Figure 317中指定的属性将在该命令的 completion queue entry 的Dword 0中返回。

Figure 317: Arbitration & Command Processing – Command Dword 11

5.27.1.2Power Management (Feature Identifier 02h)

该Feature允许主机配置 power state。这些属性在Command Dword 11中指定（参考Figure 318）。

成功完成该Feature的Set Features命令后，控制器应处于指定的 Power State。对于过渡到non-operational power state，设备可能会超过8.15.1节中定义的该non-operational power state所指示的功率（即，在完成该命令的同时）。如果enable，autonomous power state transitions 将从新的状态继续发生。

如果为这个Feature提交了Get Features命令，Figure 319中描述的属性将在该命令的completion queue entry 的Dword 0中返回。

Figure 318: Power Management – Command Dword 11

Figure 319: Power Management – Completion Queue Entry Dword 0

5.27.1.3Temperature Threshold (Feature Identifier 04h)

一个控制器可以在SMART / Health Information log 中报告最多九个温度值（即Composite Temperature 和 Temperature Sensor 1 到 Temperature Sensor 8；参考Figure 207）。与每个实施的temperature sensor相关联的是一个 over temperature threshold 和一个 under temperature threshold。当温度大于等于其相应的over temperature threshold或小于等于其相应的under temperature threshold时，那么SMART / Health Information Log（参考5.16.1.3节）中的Critical Warning字段的bit 1被设置为1。这可能会触发一个异步事件。

应实现Composite Temperature的over temperature threshold功能。如果在Identify Controller data structure中报告了一个非零的Warning Composite Temperature Threshold（WCTEMP）字段值（参考Figure 275），则应针对Composite Temperature实现 under temperature threshold Feature。应为所有实施的temperature sensor（即所有报告非零值的Temperature Sensor字段）实施 over temperature threshold 和 under temperature threshold。

如果WCTEMP为非零，Composite Temperature的over temperature threshold feature的默认值是Identify Controller data structure中的Warning Composite Temperature Threshold（WCTEMP）字段中的值；否则，默认值是具体实施所特定的。而Composite Temperature的under temperature threshold feature的默认值本来就是实施特定的。所有实现的temperature sensors的over temperature threshold的默认值是FFFh，temperature sensors的under temperature threshold的默认值是0h。

如果为这个Feature提交了 Get Features 的命令，由Command Dword 11选择的温度阈值将在该命令的completion queue entry的Dword 0中返回。

Figure 320: Temperature Threshold – Command Dword 11

5.27.1.4Volatile Write Cache (Feature Identifier 06h), (可选)

该Feature控制控制器上的易失性写缓存（volatile write cache，VWC，如果存在的话）。如果存在易失性写缓存（参考Figure 275中的VWC字段），则应支持该Feature。这些属性在Command Dword 11中指定。

注意：如果控制器能够保证write cache中的数据在断电时被写入非易失性介质，那么该write cache被认为是非易失性的，这个feature不适用于该write cache。

如果为该Feature提交了Get Features命令，Figure 321中指定的属性将在该命令的 completion queue entry 的 Dword 0 中返回。 如果不存在易失性写缓存，那么指定 Volatile Write Cache feature identifier 的Set Features命令应中止，状态码为Invalid Field in Command，且指定 Volatile Write Cache feature identifier 的Get Features命令应终止，状态码为Invalid Field in Command。

Figure 321: Volatile Write Cache – Command Dword 11

5.27.1.5Number of Queues (Feature Identifier 07h)

该Feature表示主机为处理命令的控制器请求的队列数量。该Feature只能在创建任意I/O Submission和/或 Completion Queues之前的初始化期间发出。如果在创建任何I/O Submission和/或 I/O Completion Queues之后为该特性发出Set Features命令，则Set Features命令应中止，状态码为 Command Sequence Error。控制器不得在reset之间改变分配的值。对于Set Features命令，属性在命令Dword 11中指定（参考Figure 322）。对于 Get Features 命令，Dword 11 被忽略。

如果为该Feature提交了 Set Features 或 Get Features 命令，Figure 323中指定的属性将在该命令的 completion queue entry 的 Dword 0 中返回。

Figure 322: Number of Queues – Command Dword 11

注意：分配的值可能小于或大于请求的队列数，在虚拟化实施中经常如此。控制器可能没有所请求的那么多队列可以分配。或者，控制器可能有一个队列的分配单位（例如，二的幂），并可能向主机软件提供更多的队列以满足其分配单位。

Figure 323: Number of Queues – Completion Queue Entry Dword 0

5.27.1.6Interrupt Coalescing (Feature Identifier 08h)

此Feature配置中断聚合并设置。当满足 Aggregation Time 或 Aggregation Threshold 条件时，控制器应发出中断信号。如果Aggregation Time 或 Aggregation Threshold 字段被清除为0h，那么可能会产生一个中断（即，中断聚合被隐含地disable）。这个 feature 只适用于I/O队列。建议不对错误完成的命令的中断进行合并处理。这些设置在 Command Dword 11 中指定。

如果控制器检测到该向量的中断已经被处理，那么控制器可以延迟额外的中断。具体而言，如果正在更新与特定中断向量相关的 Completion Queue Head Doorbell寄存器，那么控制器会有一个积极的指示，即 completion queue entries 已经被处理。在这种情况下，aggregation time 和/或 aggregation threshold 可在相关寄存器写入时被reset/restart。在 aggregation time 或 aggregation threshold 非零的某些 workload中，这可能会导致中断被无限期地延迟。

如果为该 Feature 提交了Get Features命令，Figure 324中指定的属性将在该命令的completion queue entry 的Dword 0中返回。 当控制器被配置为Pin Based、MSI、Multiple MSI 或MSI-X 中断时，该Feature有效。如果改变中断模式，控制器不需要维持这些设置。建议主机在改变中断模式后重新设定该Feature。

Figure 324: Interrupt Coalescing – Command Dword 11

5.27.1.7Interrupt Vector Configuration (Feature Identifier 09h)

该Feature配置特定于某一中断向量的设置。这些设置是在 Command Dword 11 中指定的。

默认情况下，为每个中断向量启用聚合设置。Admin Completion Queue 不支持中断聚合。

如果为这个Feature提交了Get Features命令，则在Command Dword 11中指定了Interrupt Vector 的命令的 completion queue entry 的 Dword 0 中返回Figure 325 中指定的属性。

在发出指定该Feature的Set Features命令之前，主机应将指定的 Interrupt Vector 配置为I/O Completion Queue（参考5.4节）。如果指定的Interrupt Vector无效，或者没有与现有的 I/O Completion Queue 相关联（参考Figure 156），那么控制器应该以Invalid Field in Command的状态码中止命令。

Figure 325: Interrupt Vector Configuration – Command Dword 11

5.27.1.8Asynchronous Event Configuration (Feature Identifier 0Bh)

此Feature控制向主机触发 asynchronous event notification 的事件。 此Feature可用于在persistent情况下disable报告事件（请参阅第 5.2 节）。 如果enable相应通知时事件的条件为真，则将事件发送到主机。 属性在 Command Dword 11 中指定。

如果为此Feature提交了Get Features 命令，则Figure 326中指定的属性将在该命令的completion queue entry 的 Dword 0 中返回。

Figure 326: Asynchronous Event Configuration – Command Dword 11

5.27.1.9Autonomous Power State Transition (Feature Identifier 0Ch), (可选)

该Feature配置了 autonomous power state transitions 的设置，参考8.15.2节。

Autonomous Power State Transition 使用 Command Dword 11，并在Figure 327所示的数据结构中指定属性信息，Autonomous Power State Transition data structure 由Figure 328中定义的32个条目组成。

如果为该Feature发出Get Features命令，则在 completion queue entry 的Dword 0中返回Figure 327中指定的属性，并在该命令的data buffer中返回 Autonomous Power State Transition data structure，其条目结构在Figure 328中定义。

Figure 327: Autonomous Power State Transition – Command Dword 11

Figure 328中定义了 Autonomous Power State Transition data structure 的每个条目。每个条目的大小为64bits。在允许的32个power states中，每个都有一个条目。对于不支持的power states，所有未使用的 Autonomous Power State Transition data structure entries 应被清除为零。这些条目从power state 0开始，然后依次增加（即，power state 0在bytes 7:0中描述，power state 1在bytes 15:8中描述，等等）。该数据结构大小为256 bytes，应是物理上连续的。

Figure 328: Autonomous Power State Transition – Data Structure Entry

The Autonomous Power State Transition feature 可能与 Non-Operational Power State Config feature 相互作用（参考5.27.1.14节）。Figure 329显示了这些相互作用。

Figure 329: Interactions between APSTE and NOPPME

5.27.1.10Host Memory Buffer (Feature Identifier 0Dh), (可选)

该Feature控制 Host Memory Buffer。这些属性在Command Dword 11、Command Dword 12、Command Dword 13、Command Dword 14和Command Dword 15中指定。

Host Memory Buffer feature 为主机提供了一种机制，用于分配主机内存的一部分供控制器专用。在成功完成enable host memory buffer的Set Features命令后，主机不得写到：

  a)Host Memory Descriptor List（参考Figure 335）；以及
  b)相关的主机内存区域（即，由Host Memory Descriptor List描述的内存区域）。

直到host memory buffer被disable。

如果host memory buffer被enable，那么enable host memory buffer 的Set Features命令（即EHM位（参考Figure 330）设置为'1'）将被终止，状态码为Command Sequence Error。

如果host memory buffer没有被enable，那么disable host memory buffer的Set Features命令（即EHM位（参考Figure 330）被清除为'0'）将成功，但不采取任何行动。

在成功完成disable host memory buffer 的Set Features命令后，控制器不应访问host memory buffer中的任何数据，直到主机host memory buffer被enable。在发布disable host memory buffer 的Set Features命令的completion queue entry之前，控制器应从正在使用的 host memory buffer 中检索任何必要的数据。发布disable host memory buffer 的Set Features命令的 completion queue entry，以确认主机软件修改 host memory buffer 内容是安全的。请参考第8.9节。

Figure 330: Host Memory Buffer – Command Dword 11

Figure 331: Host Memory Buffer – Command Dword 12

Bits	Description
31:00	Host Memory Buffer Size (HSIZE): 这个字段指定了以memory page size（CC.MPS）单位分配的host memory buffer的大小。

Figure 332: Host Memory Buffer– Command Dword 13

Figure 333: Host Memory Buffer – Command Dword 14

Bits	Description
31:00	Host Memory Descriptor List Upper Address (HMDLUA): 这个字段指定了 Host Memory Descriptor List 的物理位置中最高有效32位，用于Host Memory Buffer。

Host Memory Descriptor List Address（HMDLLA/HMDLUA）指定了主机内存中物理上连续的数据结构的地址，它描述了 Host Memory Buffer 的地址和长度对。地址和长度对的数量在Figure 334 中的Host Memory Descriptor List Entry Count中指定。Host Memory Descriptor List 的描述见Figure 335。

Figure 334: Host Memory Buffer – Command Dword 15

Bits	Description
31:00	Host Memory Descriptor List Entry Count (HMDLEC): 这个字段指定了 Host Memory Descriptor List 中提供的条目数量。

Figure 335: Host Memory Buffer – Host Memory Descriptor List

每个 Host Memory Buffer Descriptor Entry 应描述一个以memory page size 为单位的主机内存地址，以及与该主机地址相关的连续 memory page size 单位的数量。

Figure 336: Host Memory Buffer – Host Memory Buffer Descriptor Entry

如果为这个Feature发出Get Features命令，Figure 337中指定的属性将在 completion queue entry 的Dword 0中返回，Host Memory Buffer Attributes data structure（其结构定义见Figure 338）将在该命令的data buffer中返回。

Figure 337: Host Memory Buffer – Completion Queue Entry Dword 0

Figure 338: Host Memory Buffer – Attributes Data Structure

5.27.1.11Timestamp (Feature Identifier 0Eh), (可选)

Timestamp feature 能使主机可以在控制器中设置一个时间戳值。控制器通过Identify Controller data structure 中的Optional NVM Command Support (ONCS)字段表示对Timestamp feature 的支持。Set Features 命令中的Timestamp字段值（参考Figure 339）在控制器中设置一个时间戳值。该Feature的current value被设置后，控制器会随着时间的推移更新该值。请求当前值的Get Features命令报告了Get Features命令被处理时控制器中的时间戳值（例如，用Set Features命令为当前值设置的值加上被设置后过去的时间）。

注意：如果Timestamp feature是saveable的（参考Figure 195），并且主机保存了一个值，那么在随后的power on或reset事件后恢复的时间戳值就是被保存的值（参考4.2节）。因此，时间戳可能会出现时间上的倒退。

初始化后的Timestamp值的准确性可能会受到供应商特定因素的影响，如控制器在时间戳初始化后是否持续计数，或者控制器是否在某些间隔期间（如non-operational power states）停止计数。如果控制器在这种间隔期间停止计数，那么Timestamp – Data Structure for Get Features 的Synch位（参考Figure 340）应被设置为'1'。

如果控制器在任何类型的Controller Level Reset中保持（即继续更新）时间戳值（例如，在Controller Reset中），那么控制器也应在该类型的Controller Level Reset中保留Timestamp Origin字段（参考Figure 340）。

如果控制器在最近一次 Controller Level Reset 时没有保持timestamp的值，那么由于该Controller Level Reset，Timestamp字段被清除为0h。

Timestamp值不应该被用于安全应用。其他应用对Timestamp feature的使用超出了本规范的范围。

如果为该Feature发出Set Features命令，则在该命令的 data buffer 中传输 Figure 339 中指定的数据结构，指定Timestamp值。

Figure 339: Timestamp – Data Structure for Set Features

如果为该Feature发出Get Features命令，Figure 340中指定的数据结构将在该命令的data buffer中返回。

Figure 340: Timestamp – Data Structure for Get Features

5.27.1.12Keep Alive Timer (Feature Identifier 0Fh)

此 Feature 控制 Keep Alive Timer。 有关 Keep Alive 的详细信息，请参阅第 3.9 节。 属性在命令 Dword 11 中指定。 如果为此 Feature 提交了 Get Features 命令，则Figure 341 中指定的属性将在该命令的 completion queue entry 的 Dword 0 中返回。

Figure 341: Keep Alive Timer – Command Dword 11