Doorbell、Queue Full 與 Wrap-around

1. 操作前先準備什麼

每條 SQ／CQ 各有自己的 Doorbell；更新其中一條不會自動更新另一條。

更新前，先確認 queue 仍然有效，而且 controller 已就緒。提交命令時也要確認 SQ 有足夠的可用位置，再依 CAP.DSTRD 找到正確的 Doorbell Register。

SQ Tail 指向下一個可放入 SQE 的位置；CQ Head 指向下一個等待 Host 處理的 CQE。Doorbell 要寫入更新後的索引值，而不是這次新增或處理了幾筆。

SQE

Submission Queue Entry，佇列中的命令項目

2. 先後順序與完成條件

提交時，Host 先寫好完整的 SQE，並依平台要求確保 controller 能看見這些記憶體內容，之後才更新 SQ Tail。接收完成結果時，則先讀取並處理有效的 CQE，再更新 CQ Head。Host 可以一次提交多筆命令，也可以一次釋放多個已處理的完成位置。

更新 SQ Tail 後，controller 才能得知哪些新命令可以讀取；更新 CQ Head 後，controller 才能得知哪些完成位置可以重用。因此，CQ Head 前進並不表示 Host 提交了新的 I/O 命令。

3. 未符合條件時如何處理

如果 Host 尚未處理 CQE 就提前釋放位置，該 CQE 可能被後續的完成結果覆寫。如果 SQE 尚未準備好就更新 Tail，controller 也可能讀到不完整的命令。這些都是使用順序錯誤，不能預期 controller 一定會回傳某個固定的錯誤 CQE。

驗證時，依時間先後比對 Host 寫入 SQE、更新 Tail、controller 寫入帶有新 Phase 的 CQE，以及 Host 更新 Head 這四個動作。它們分別代表準備命令、提交命令、回報完成及釋放完成位置，不能互相替代。

1. 先區分是哪一種失敗

錯誤會影響被寫入 Doorbell 的 queue。如果是多條 SQ 共用的 CQ，影響還可能延伸到這些 SQ。另外，向不存在的 queue 寫 Doorbell，與向有效 queue 寫入非法值，是兩種不同情況。

合法索引介於 0 與 size−1。寫入較小的值不一定是倒退，因為指標可能剛好繞回起點。再次寫入相同的值也不能視為一定安全的空更新：Base 2.4 Figure 153 將它列為 Invalid Doorbell Write Value 的可能原因之一。

向有效 queue 寫入非法值，而且已有尚未完成的 Asynchronous Event Request（AER，非同步事件要求）時，controller 透過該 AER 回報 Invalid Doorbell Write Value；事件資訊不是這次 MMIO 寫入的 CQE Status。若沒有等待中的 AER，不能單憑這條規則保證已收到通知。向不存在的 queue 寫 Doorbell，結果則是未定義。

MMIO

Memory-Mapped I/O，記憶體映射輸入輸出

2. 用哪些資料確認原因

判斷指標是否合法，需要知道 queue 大小、原來的指標、可用或已處理的位置數量，以及 Doorbell 對應的 QID。只看新寫入的數字，無法判斷這次移動是否正確。

【模擬資料】queue 大小為 8，Tail 從 6 變成 1，代表前進 3 個位置。這次提交是否合法，還要確認原本有 3 個可用位置，而且對應的 SQE 都已準備好。從 6 再寫回 6，不能表示提交了一整圈，也可能構成無效寫入。

3. 結果與後續驗證

合法的指標更新，能讓 controller 算出新提交或新釋放的位置數量。不過，Host 不應靠讀回 Doorbell 來驗證寫入結果，因為 Doorbell 的讀回值由廠商定義。

先依原指標、queue 大小及剩餘空間判斷移動是否合法，不要只比較新舊數字的大小。若發生 Doorbell 錯誤，還應一起檢查對應的非同步事件，以及受影響 queue 是否停止取得新命令。

先用 (new−old+size) modulo size 算出前進量，再確認這些位置是否確實可以提交或釋放。

4. 分開核對事件通知與 Log 紀錄

依 Base §3.3.1.2，若 Doorbell 值非法，而且有尚未完成的 Asynchronous Event Request，controller 會透過它回報對應錯誤事件。受影響的 SQ 可以完成已取得的命令，但不再取得新命令；Host 則需刪除並重建 queue。

這是 Error 類型的非同步事件，應讀取事件指定的 Log，取得補充資料。MMIO 寫入本身沒有 More 位元。另外，若是寫到不存在 QID 的 Doorbell，規範已將結果列為未定義，不能再要求它一定產生 Log。

MMIO

Memory-Mapped I/O，記憶體映射輸入輸出

1. 先確認資料的來源與範圍

Doorbell 位址以該 controller 的 MMIO 起始位址為基準，不是以 SQ 或 CQ 記憶體的起始位址為基準。

PCI BAR0／BAR1 用來找出 NVMe Register 空間的位置；CAP.DSTRD 則用來計算相鄰 Doorbell 的位址間距。

2. 欄位、單位與判讀例子

stride=4×2^DSTRD；SQy offset=1000h+2y×stride；CQy offset=1000h+(2y+1)×stride。每個 Doorbell 本身仍是 32 bits。

先取得映射後的 Register 起始位址，再由 DSTRD 算出 stride。接著依 QID 選用 SQ 或 CQ 的公式，算出 Doorbell 位址，最後使用規定的存取寬度執行 MMIO 寫入。

例：DSTRD=2、QID=3，SQ offset=1060h、CQ offset=1070h。把各 offset 加到 controller base，才是完整位址。

3. 判讀時要保留的條件

計算位址本身不會產生 Command Status。如果算錯位址，可能寫到另一條有效 queue，也可能形成結果未定義的存取。controller 無法因此得知 Host 原本想更新哪一條 queue。

把算出的 Doorbell 位址，與建立 queue 時使用的 QID 及 BAR 映射範圍交叉比對。DSTRD 是計算間距時使用的編碼，不能直接當成 byte 數，也不能直接拿來乘上 QID。

BAR

Base Address Register，基底位址暫存器

1. 先確認 Queue 的有效期間

I/O queue 必須在建立成功後才能使用；刪除成功或 Controller Reset 之後，Host 就不能再沿用原來的 queue。

檢查 Host 維護的 queue 紀錄，以及 CC.EN、CSTS.RDY。Doorbell 的讀回值不能用來判斷 queue 是否存在。

SQyTDBL 與 CQyHDBL 分別通知有效 queue 的新 Tail 與 Head。Admin Queue 的 QID 為 0，其設定來自 AQA、ASQ、ACQ，並隨 controller 初始化建立可用狀態。

對 I/O queue，Host 先建立並等待成功，再開始使用。準備刪除時，先停止提交新命令，並在 Delete 成功後停止使用原 queue。Controller Reset 之後，即使打算沿用相同 QID，也必須重新建立 I/O queue。

2. 不存在的 Queue 沒有固定錯誤回報

PCIe §3.1.2 將向不存在的 SQ 或 CQ 寫 Doorbell 列為結果未定義的行為。CSTS.RDY=0 時也不符合命令提交的前提，因此不能要求 controller 一定回報 Invalid Queue Identifier 或某個指定的非同步事件。

以 Create 與 Delete 的完成時間界定 queue 的有效期間，再檢查所有 Doorbell 更新是否都發生在這段期間內。

1. 操作前先準備什麼

SQ Tail 與 CQ Head 都由 Host 推進；SQ Head 與 CQ Tail 則由 controller 維護。判斷指標變化時，要先分清楚是哪一端負責更新。

計算時使用該 queue 實際配置的位置數 N，也就是 QSIZE+1。CAP.MQES 表示能力上限，不能直接當成每條 queue 的實際大小。

每前進一步計算 (index+1) modulo N。Tail 是下一個寫入位置，Head 是下一個讀取位置，兩者相等表示空。

2. 先後順序與完成條件

索引從 N−1 回到 0 時，Host 仍須正確追蹤這次實際前進了幾個位置。更新 SQ Tail 不能超過可用空間；更新 CQ Head 不能跳過尚未處理的 CQE。

例如 N=8，CQ Head 從 7 變成 2，表示 Host 已處理索引 7、0、1 的 3 筆 CQE，而不是指標倒退了 5 個位置。

3. 未符合條件時如何處理

合法的 wrap-around 不是錯誤。若誤把 queue 大小 N 當成最大合法索引，並將 N 寫入 Doorbell，才會超出範圍。非法指標的處理方式見第 23 題。

驗證時，要一起檢查 Head、Tail 與 queue 大小的環狀索引關係。Doorbell 數值變小，可能只是正常跨過尾端，不能單憑這點判定違反規範。

1. 操作前先準備什麼

Phase 用來辨識 CQE 屬於哪一圈，不表示命令成功或失敗，也不是 SQ 的指標。

Phase 是 PCIe CQE 的基本機制，不需要額外啟用 Feature。建立 CQ 前，Host 將每個位置的 Phase 初始化為 0，並將自己第一次等待的 Phase 設為 1。

CQE DW3 bit16 為 P；controller 每次在同一 slot 放入新 CQE 時反轉該 slot 的前次 Phase。

2. 先後順序與完成條件

CID

Command Identifier，同一提交佇列內的命令識別碼

3. 未符合條件時如何處理

Phase 不符合期待值，表示該位置還沒有這一圈的新完成結果，並不代表某種錯誤 Status。此時不能把該位置殘留的 CID 或 SC 當成新命令的結果。

CID

Command Identifier，同一提交佇列內的命令識別碼

測試至少要讓 CQ 完整繞過一圈，並比對 CQ Head、Host 期待的 P 與 CQE 實際的 P。重建 queue 時必須重新初始化，不能沿用前一次 queue 的期待值。

1. 機制與適用範圍

影響該 CQ 與其關聯 SQ；其他不使用此 CQ 的 SQ 必須繼續處理。

CQ 保留一個位置不用；當 (Tail+1) modulo N = Head 時，就表示 CQ 已滿。這裡的 Tail 由 controller 維護，Host 不能直接讀取它。

2. 用操作與結果理解

判斷容量時，要看 CQ 的實際大小、Host 更新 CQ Head 的情況，以及尚未處理的完成結果。Number of Queues 表示 queue 數量，不能用來推算一條 CQ 能容納多少筆 CQE。

Host 逐筆確認 Phase 並處理 CQE，之後再更新 Head，釋放已處理的位置。在可用位置出現之前，controller 不得向這條 CQ 寫入新的完成結果。

controller 可以停止處理關聯 SQ 中的新 entry。規範在這裡使用 may，因此不能進一步推論：所有已取得的命令都必須立刻停止，或都必須繼續執行。

3. 容易誤判的地方

CQ Full 是空間已滿的狀態，不是一個必須回報的 NVMe 錯誤碼。controller 不能為了騰出空間，覆寫 Host 尚未確認處理完畢的 CQE。

如果只有共用這條 CQ 的 SQ 停滯，先檢查 Host 是否持續處理並釋放 CQE。如果連使用其他獨立 CQ 的 SQ 也因這條 CQ 已滿而停止，則要檢查是否違反繼續處理其他 SQ 的要求。

1. 操作前先準備什麼

Host 釋放的是這條 CQ 中的完成位置，讓關聯 SQ 的命令可以回報結果。這不會改變可建立的 queue 數量，也不會改變 namespace 的能力。

先確認 queue 仍然存在，而且沒有其他停止處理的原因，例如正在重設、CSTS.CFS 已設定，或 queue 處於 Processing Paused 狀態。

Host 將新的 Head 索引寫入 CQ Head Doorbell。controller 根據 Head 的前進量得知哪些位置可以重用，後續寫入 CQE 時仍須使用正確的 Phase。

2. 先後順序與完成條件

Host 處理 CQE 並更新 Head 後，controller 才得知有新的可用空間，接著可以寫入等待回報的完成結果，並繼續處理受影響的工作。實際執行次序仍受仲裁設定及其他正常條件限制。

已釋放的位置可以再次使用，不必重建 queue。不過，規範沒有為所有裝置訂出同一個固定時間，要求從 Head 更新到下一筆 CQE 出現必須相隔多久。

3. 未符合條件時如何處理

正確更新 CQ Head 不會另外產生一筆成功 CQE。如果 Head 值非法，應依 Doorbell 的錯誤處理規則判斷，不能套用 Create Queue 的錯誤 Status。

檢查後續 CQE 是否寫入合法且已釋放的位置，並比較共用這條 CQ 的 SQ 與其他獨立 SQ 的處理進度。

1. 先確認資料的來源與範圍

Host 追蹤命令時，必須一起考慮 controller、SQ 的這次建立與使用期間、SQID 及 CID。controller 與 queue 的使用期間是 Host 自己維護的上下文，並不是 CQE 裡額外增加的欄位。

SQID

Submission Queue Identifier，提交佇列識別碼

Host 使用建立 queue 時記錄的 SQ 與 CQ 對應關係，以及未完成命令的追蹤表，來尋找原命令。Identify 不會回報每筆未完成命令的位置。

2. 欄位、單位與判讀例子

CQE.SQID 指出命令來自哪條 SQ，CID 則指出該 SQ 內的哪筆命令。SQHD 回報 controller 已消費到的 SQ 位置，不代表這筆完成命令原先所在的 SQ 位置。

Host 先確認 CQE 的 Phase 有效，再用 SQID 與 CID 找到原命令，處理 Status 及回傳資料，並更新該 SQ 的 Head 紀錄。這些工作完成後，才釋放 CQ 中的這個位置。

例如 SQ1 的 CID9 與 SQ2 的 CID9 可以共用同一條 CQ。即使兩筆命令以相反順序完成，Host 仍可透過 SQID 與 CID 分別找到正確的原命令。

3. 判讀時要保留的條件

同一條 SQ 中，未完成命令的 CID 重複時，可能回報 Command ID Conflict（0/03h）。controller 為了偵測衝突，會搜尋多少筆既有命令，由實作決定；這不免除 Host 維持 CID 唯一性的責任。

先確認 CQE 指出的 SQID 確實關聯到這條 CQ，再確認 CID 屬於目前這次建立的 SQ，而不是前一次 queue 留下的追蹤資料。