8.8 Reservations 預訂

NVMe的reservation預訂功能，用於讓兩個或多個主機能夠協調配合的訪問共享namespace。使用這些功能的協議和方式超出了本規格說明書的範圍。對這些reservations功能的錯誤應用可能破壞資料或危害系統操作。

namespace上的reservation限制主機訪問namespace。如果namespace在reservation情況下，主機提交命令到namespace缺乏足夠的許可權，那麼命令就會被controller終止掉，返回Reservation Conflict狀態。如果主機提交命令，命令中NSID設定了0xFFFFFFFF，這裡邊有任何一個namespace呈現reservation功能但主機缺乏足夠許可權的話，命令就會被controller終止掉，返回Reservation Conflict狀態【預訂衝突狀態】。如下這種能力需要被提供的：允許從一個被故障或不配合的主機所持有的namespace上的reservation恢復回來。

Reservation要求主機和namespace之間相互關聯。如果圖Figure 460所示，在多路徑I/O和namespace共享環境中每個controller只與一個主機相關聯。而構建一個用兩個或者更多的主機共享一個單一的controller的系統也許是可能的，但這種用法超出了本規格說明書的範圍。

一個主機可以與多個controller關聯，在Figure 460中，主機A與兩個controller關聯，而主機 B和C都是與單個controller相關聯。在執行所有相關reservation的操作之前，主機通過Set Features命令（第5.21章節定義此命令）向與本主機已關聯的每個controller註冊主機識別符號（或稱為主機ID，第5.21.1.26章節定義Host Identifier）。主機ID能讓NVM subsystem來識別關聯到同一此主機的controller們，並讓所有這些controller們保持reservation屬性（即：主機下發的命令，不論哪個與此主機關聯的controller來處理這個命令，都具有相同的reservation許可權）。

對於reservations的支援是通過namespace或是controller這個是可選的。在Identify Namespace資料結構的Reservation Capabilities（RESCAP）域中報告非0值就表示這個namespace支援reservations功能。通過Identify Controller資料結構的Optional NVM Command Support（ONCS）域來表示controller支援reservations功能。如果主機提交一個reservations相關的命令（即：Reservation Report, Reservation Register, Reservation Acquire, Reservation Release）到controller或namespace，但controller和namespace並沒有同時都支援reservations，那麼命令就會被controller終止掉，返回Invalid Command Opcode非法命令操作碼狀態。

構成NVM subsystem的Controller們必須所有controller對reservations具有同樣的【一致的】支援。儘管強烈建議但並沒有要求所有組成NVM subsystem的namespace對reservations具有相同的支援。例如，單個controller中的某些namespace可能支援reservations而另外一些不支援，或者這些namespace們支援的reservation型別可能不同。如果controller支援reservations那麼這個controller必須：

• 通過在Identify Controller資料結構的Optional NVM Command Support（ONCS）域第5位返回‘1’表明對reservations支援；
• 支援Reservation Report 命令（參考第6.13章節），Reservation Register命令（參考第6.11章節），Reservation Acquire命令（參考第6.10章節），Reservation Release命令（參考第6.12章節）；
• 支援Reservation Notification log page；
• 支援Reservation Log Page Available非同步事件；
• 支援Reservation Notification Mask Feature；
• 支援Host Identify Feature；
• 支援Reservation Persistent Feature。

如果namespace支援reservations，那麼namespace必須：

• 在Identify Namespace資料結構的Reservation Capabilities（RESCAP）域中呈現非0值；
• 支援Persist Through Power Loss（PTPL）狀態；
• 支援給予主機充足的資源在NVM subsystem中每個controller上去順利地註冊一個reservation key，以便訪問共享namespace（即：Reservation Register命令必須永遠不會因為缺乏資源而失敗）。

注意：為了提高與SCSI基本實現的相容性，Ignore Existing Key的行為已經被做了變更。在Identify Namespace資料結構的Reservation Capabilities（RESCAP）域中表示的與變更後的行為相符合。對於之前的Ignore Existing Key行為，參考規格說明書的1.2.1版本。

8.8.1 Reservation Notifications

有三種類型的reservation通知：registration preempted，reservation released，reservation preempted。【註冊搶佔、預訂釋出、預訂搶佔】。引起reservation通知的條件將在後邊章節中描述。在一個已載入到controller的namespace上，只要發生了未被遮蔽的預訂通知，Reservation Notification log page就被會建立（參考第5.14.1.16.1章節）。預訂通知可以從每個預訂通知型別上產生預訂日誌頁，或者基於每個namespace ID通過Reservation Notification Mask特性，遮蔽掉的（參考第5.21.1.27章節）。主機可以使用Asynchronous Event Request命令（參考第5.2章節），出現了一個或多個可用的Reservation Notification日誌頁時就會被通知到（參考第5.14.1.16.1章節）。

8.8.2 註冊

在namespace上建立預訂之前，主機必須通過註冊一個reservation key成為這個namespace的登記者。這個reservation key可以被主機作為確認登記者（主機）、驗證登記者身份、搶佔一個已故障或不合作的登記者的一種手段來使用。reservation key的值如何被主機使用，以及用於選擇其值的方法超出了本規格說明書的範圍。

用namespace註冊一個reservation key將建立一個主機與namespace之間的關聯關係。作為一個namespace的登記者主機，可以使用任何一個已經與此主機關聯的controller（即：有相同的Host Identifier，參考第5.21.1.26章節）去訪問這個namespace。因此，一個主機成為namespace的登記者只需要在NVM subsystem中能夠訪問這個namespace的且已經與這個主機關聯的所有controller中的某一個單個controller上註冊即可。

主機註冊reservation key是通過在namespace上執行一個Reservation Register 命令（參考第6.11章節），把Reservation Register Action（RREGA）域清零（即：Register Reservation Key），並在New Reservation Key（NRKEY）域中提供一個reservation key。

namespace的登記者主機，可以在與此namespace相關的同一個或不同的controller上用相同的reservation key值註冊多次。對於一個Reservation Register命令RREGA域為000b：

a）IEKEY域必須被忽略；

b）如果一個主機已經是namespace的登記者，企圖再使用不同的註冊key值向這個namespace註冊，那麼命令必須被終止，返回Reservation Conflict狀態。

不同主機ID的主機使用的reservation key值沒有限制。例如，多個主機可以都用同一個reservation key值註冊。

namespace的登記者主機，可以在namespace上通過執行一個Reservation Register命令替換已經存在的reservation key值，帶如下資訊：

a）RREGA域設定為010b（即：Replace Reservation Key）；

b）在Current Reservation Key（CRKEY）域中填寫當前reservation key；

c）在NRKEY域中填寫新的reservation key。

替換reservation key時，namespace掛載的具有那個主機ID的所有controller中都必須把當前reservation key值替換成新reservation key值。如果CRKEY域中的內容與當前主機關聯的key不匹配，那麼命令必須被終止，返回Reservation Conflict狀態。主機替換它的reservation key時，可以通過把Reservation Register命令中Ignore Existing Key（IEKEY）位設定為1，從而不用再關心它的登記狀態或當前reservation key值。替換一個reservation key對在namespace上已經持有的任何預訂都沒啥影響。

8.3.3 Reservation Types預訂型別

NVMe介面支援六種預訂型別：

• Write Exclusive；
• Exclusive Access；
• Write Exclusive - Registrants Only；
• Exclusive Access - Registrants Only；
• Write Exclusive - All Registrants；
• Exclusive Access - All Registrants；

這些預訂型別之間的區別是：被排除的訪問型別，登記者是否與預訂持有者具有相同的訪問許可權，是否登記者也被視為預訂持有者。這些區別被總結在Figure 461中，每個NVMe命令的特定行為展示在Figure 462中。

除了斷電重啟之外，所有Controller Level Resets和所有NVM subsystem Resets，預訂和註冊仍然持久存在。由於使用Persist Through Power Loss State（PTPLS）斷電而重啟的情況，預訂的保留是可選性配置。一個Persist Through Power Loss State（PTPLS）是與每個支援預訂功能namespace關聯的，可以用Reservation Register命令的側面效果或Set Features命令來修改的。

8.8.4 登出

namespace的登記者主機可以在namespace上通過執行Reservation Register命令登出登記，命令RREGA域設定成001b（即Unregister Reservation Key），並在CRKEY域中提供當前的reservation key。如果CRKEY域中的內容與主機當前關聯的key不匹配，那麼命令就被終止掉，返回Reservation Conflict狀態。如果主機不是一個登記者，那麼命令被終止掉，返回Reservation Conflict狀態。

一個登出操作的成功完成使得主機不再是namespace的登記者。主機可以通過在Reservation Register命令中把IEKEY位設定為1而不關心它的當前reservation key值進行登出。

主機登出過程可以引起這個主機所持有的預訂被釋放。如果主機是剩下的最後一個預訂持有者（即：預訂型別是Write Exclusive - All Registrants 或 Exclusive Access - All Registrants）或者是僅有的預訂持有者，那麼當主機登出時預訂就被釋放。

如果預訂被釋放，並且已釋放的預訂型別是Write Exclusive - Registrants Only 或 Exclusive Access - Registrants Only，那麼在所有與已註冊主機關聯的controller上產生一個預訂釋放通知，除了下發了Reservation Register命令的主機。

8.8.5 獲得一個預訂

為了主機在namespace上得到一個預訂，該主機必須是namespace的登記者。登記者通過執行Reservation Acquire命令（參考第6.10章節）獲得預訂，把Reservation Acquire Action（RACQA）域清除為000b（Acquire），在Current Reservation Key（CRKEY）域中提供與主機關聯的當前reservation key。CRKEY值必須與登記者在namespace註冊時使用的值相匹配。如果CRKEY值不匹配，那麼命令被終止返回Reservation Conflict狀態。如果主機不是登記者，命令被終止返回Reservation Conflict狀態。

同一時間內一個namespace上只允許一個預訂。如果登記者在namespace上已經是預訂持有者而嘗試去獲得預訂，那麼命令被終止返回Reservation Conflict狀態。如果預訂持有者在namespace上嘗試去獲得一個不同型別的預訂，那麼命令被終止返回Reservation Conflict狀態。如果預訂持有者在namespace上嘗試去獲得這個主機已經持有的相同型別的預訂這不算是一個錯誤。預訂持有者可以搶佔預訂來變更預訂型別。

8.8.6 釋放預訂

只有預訂持有者才可以有秩序的釋放在namespace上持有的預訂。主機通過執行Reservation Release命令釋放預訂，把Reservation Release Action（RRELA）域清零，把Reservation Type（RTYPE）域設定成被釋放的預訂型別，在Current Reservation Key（CRKEY）域中提供與這個主機關聯的當前reservation key。CRKEY值必須與主機在namespace上註冊的值相匹配。如果key值不匹配，那麼命令被終止返回Reservation Conflict狀態。如果RTYPE域與當前預訂的型別不匹配，那麼命令完成返回命令中Invalid Field狀態。

登記者使用Reservation Release命令嘗試釋放一個預訂，但這個預訂還沒有在namespace上被持有預訂，或者這個主機不是這個預訂的預訂持有者，必須讓命令成功完成，但是必須對controller和namespace不產生任何影響。

像在本章節中描述的行為結果，當預訂被釋放，預訂型別不是Write Exclusive或Exclusive Access，在NVM subsystem中所有與登記者主機關聯的controller上產生一個預訂釋放通知，除了下發了Reservation Release命令的那個與主機關聯的controller。【也就是說主機下發預訂釋放命令的那個控制器不用再給自己產生釋放通知了】

8.8.7 搶佔一個預訂或登記

一個登記者主機可以通過執行Reservation Acquire命令搶佔一個預訂或登記，把Reservation Acquire Action（RACQA）域設定成001b（Preempt），在CRKEY域裡提供與主機關聯的當前預訂key。CRKEY值必須與登記者向namespace註冊時使用的值相匹配。如果CRKEY值不匹配，那麼命令被終止返回Reservation Conflict狀態。搶佔行為作用依賴於namespace上持有預訂的型別（如果有的話），以及命令中Preempt Reservation Key（PRKEY）域的值。如果主機不是一個登記者，那麼命令被終止返回Reservation Conflict狀態。本章節接下來的描述假定主機是登記者。

如果存在的預訂型別不是Write Exclusive - All Registrants 也不是Exclusive Access - All Registrants，那麼命令執行的操作依賴於PRKEY域的值，如下：

a）如果PRKEY域的值匹配當前預訂持有者的reservation key，那麼如下作為原子操作出現：

• • 除了下發命令的這個主機是未註冊的，所有登記者都匹配registration key；
  • 預訂被釋放；
  • 為下發命令的主機建立一個新的預訂，預訂型別由命令中的Reservation Type（RTYPE）域指定，該下發命令的主機作為reservation key持有者；

或者

b）如果PRKEY域值不匹配當前預訂持有者的值，且也不等於0h，那麼誰的reservation key能匹配PRKEY域值的這些登記者們就會被登出。如果PRKEY域值不匹配當前預訂持有者的值，且等於0h，那麼命令被終止返回Invalid Field in Command狀態。

如果存在的預訂型別是Write Exclusive - All Registrants 或 Exclusive Access - All Registrants，那麼命令執行行為依賴於PRKEY域，如下：

a）如果PKEY域值是0h，那麼如下作為院子操作出現：

• • 除了下發命令的這個主機，所有登記者們都被登出；
  • 預訂被釋放
  • 為下發命令的這個主機建立一個新的預訂，預訂型別由命令中的Reservation Type（RTYPE）域指定，這個下發命令的主機成為reservation key持有者；

或者

b）如果PRKEY值是非零，那麼誰的reservation key匹配PRKEY域值的登記者們就會被登出。如果PRKEY值是非零且沒有登記者的reservation key匹配PRKEY域值，controller應該返回一個Reservation Conflict的錯誤。

如果namespace上沒有預訂持有者，命令的執行會引起reservation key匹配PRKEY域值的登記者被登出。

如果存在的預訂型別不是Write Exclusive - All Registrants 也不是Exclusive Access - All Registrants，那麼預訂持有者可以使用上邊的機制搶佔它自身。當一個主機搶佔它自身時如下作為原子操作出現：

• 該主機的登記者身份被保持的；
• 預訂被釋放；
• 為主機建立一個新預訂，預訂型別由RTYPE域指定。

作為由執行Reservation Acquire命令搶佔一個預訂的輔助結果主機可以終止命令，設定RACQA域為010b（Preempt和Abort）。此命令的行為與上邊描述的RACQA域設定為001b（Preempt）完全相同，但有如下兩個例外：

• 原子操作變更namespace預訂和註冊狀態之後，所有與預訂和註冊的主機相關聯的controller們都被原子操作搶佔，要求對正在處理的定址這個namespace的命令都終止，這個namespace在Namespace Identifier域中指定（即：NSID域在Reservation Acquire命令）（‘“正在處理”的定義參考第4.13章節）；
• 不論每個被請求中止的命令是否實際中止，直到所有被請求終止的命令完成，不能Reservation Acquire命令的Completion。

像Abort Admin命令那樣（參考第5.1章節），中止作為搶佔預訂的額外效果是盡力而為；當一個Reservation Acquire或Abort Admin命令被提交，作為被請求中止的命令可能當前正在執行，這種命令不能在被中止，或者已經被完成。儘管提示中止請求執行，減小完成Reservation Acquire命令的延遲，被請求中止的命令在完成Reservation Acquire命令之前必須要麼被中止要麼被完成。

作為本章節中描述的行為結果，當一個登記者被登出，除了下發Reservation Acquire命令的那個主機，在所有與被登出的主機關聯的controller們上產生一個註冊登記搶佔通知。

作為本章節中描述的行為結果，當namespace上持有的預訂型別變更，除了下發Reservation Acquire命令的那個主機，與仍然是namespace的註冊者的主機相關聯的所有controller們上產生一個預訂釋放通知。

8.8.8 清除預訂

通過執行Reservation Release命令（參考第6.12章節），登記者主機可以清除預訂（即：強制namespace上持有的預訂釋放掉和登出所有登記者），設定Reservation Release Action（RRELA）域為001b（即Clear），在Current Reservation Key（CRKEY）域提供與主機相關的當前預訂key。如果CRKEY域中的值與主機在namespace上註冊使用的值不匹配，命令必須被中止返回Reservation Conflict狀態。如果主機不是一個登記者，命令被中止返回Reservation Conflict狀態。當命令清除預訂被執行以下作為原子操作出現：如果namespace上有預訂，則釋放，所有的登記者都被從namespace登出。

除了這些與下發Reservation Release命令主機相關聯的controller，那些NVM subsystem中的controller上都產生一個預訂搶佔通知，那些controller是指作為本章節提及的行為結果，與註冊被移除的主機相關聯的controller們。

8.8.9 報告預訂狀態

主機可以通過執行Reservation Report命令確認與namespace相關的當前預訂狀態（參考第6.13章節）。