STORAGE_REQUEST_BLOCK結構 (storport.h)
STORAGE_REQUEST_BLOCK是擴充格式的 SCSI 要求區塊 (SRB) 結構。 結構提供新增與SRB函式相關聯的擴充數據。
注意
SCSI 埠驅動程式和 SCSI 迷你埠驅動程式模型未來可能會改變或無法使用。 相反地,我們建議使用 Storport 驅動程式 和 Storport 迷你埠驅動程式 模型。
語法
typedef struct _STORAGE_REQUEST_BLOCK {
USHORT Length;
UCHAR Function;
UCHAR SrbStatus;
ULONG ReservedUlong1;
ULONG Signature;
ULONG Version;
ULONG SrbLength;
ULONG SrbFunction;
ULONG SrbFlags;
ULONG ReservedUlong2;
ULONG RequestTag;
USHORT RequestPriority;
USHORT RequestAttribute;
ULONG TimeOutValue;
union {
ULONG SystemStatus;
ULONG RequestTagHigh4Bytes;
} DUMMYUNIONNAME;
ULONG SystemStatus;
ULONG ZeroGuard1;
ULONG AddressOffset;
ULONG NumSrbExData;
ULONG DataTransferLength;
PVOID POINTER_ALIGN DataBuffer;
PVOID POINTER_ALIGN ZeroGuard2;
PVOID POINTER_ALIGN OriginalRequest;
PVOID POINTER_ALIGN ClassContext;
PVOID POINTER_ALIGN PortContext;
PVOID POINTER_ALIGN MiniportContext;
_STORAGE_REQUEST_BLOCK POINTER_ALIGN *NextSrb;
struct _STORAGE_REQUEST_BLOCK;
ULONG SrbExDataOffset[ANYSIZE_ARRAY];
} STORAGE_REQUEST_BLOCK, *PSTORAGE_REQUEST_BLOCK;
成員
Length
指定 SRB 標頭的大小,以便與 SCSI_REQUEST_BLOCK 結構相容。 這等於這個 結構的 Signature 成員位移。
Function
設定為 SRB_FUNCTION_STORAGE_REQUEST_BLOCK ,表示這是擴充的 SRB。 不同於 SCSI_REQUEST_BLOCK,SRB 函式標識符會改為位於 SrbFunction 成員中。
SrbStatus
傳回已完成要求的狀態。 此成員應該由迷你埠驅動程序設定,再通知操作系統特定的驅動程式,要求已完成,方法是呼叫 StorPortNotification with RequestComplete。 此成員的值可以是下列其中一項:
值 | 意義 |
---|---|
SRB_STATUS_PENDING | 表示要求正在進行中。 操作系統特定的埠驅動程式會將 SrbStatus 初始化為這個值。 |
SRB_STATUS_SUCCESS | 表示要求已順利完成。 |
SRB_STATUS_ABORTED | 表示要求已中止,如埠驅動程式所指示。 迷你埠驅動程式會在 NextSrb 成員中設定此狀態,以取得成功的SRB_FUNCTION_ABORT_COMMAND要求。 |
SRB_STATUS_ABORT_FAILED | 表示嘗試中止要求失敗。 當找不到指定的要求時,傳回SRB_FUNCTION_ABORT_COMMAND要求的這個狀態。 |
SRB_STATUS_ERROR | 指出要求已完成,且 SCSI 總線狀態發生錯誤。 |
SRB_STATUS_BUSY | 表示迷你埠驅動程式或目標裝置目前無法接受要求。 操作系統特定的埠驅動程式稍後會重新提交要求。 |
SRB_STATUS_INTERNAL_ERROR | 指出 Storport 驅動程式無法將要求傳遞至迷你埠驅動程式或目標裝置。 在這種情況下,狀態會記錄在 InternalStatus 中。 |
SRB_STATUS_INVALID_REQUEST | 表示迷你埠驅動程序不支援指定的要求。 |
SRB_STATUS_NO_DEVICE | 表示裝置沒有回應。 |
SRB_STATUS_TIMEOUT | 表示要求逾時。 |
SRB_STATUS_SELECTION_TIMEOUT | 指出 SCSI 裝置選取逾時。 |
SRB_STATUS_COMMAND_TIMEOUT | 表示目標未在時間限制內完成命令。 |
SRB_STATUS_MESSAGE_REJECTED | 表示目標已拒絕訊息。 這通常只會針對SRB_FUNCTION_TERMINATE_IO這類訊息類型要求傳回。 |
SRB_STATUS_BUS_RESET | 表示執行此要求時發生總線重設。 |
SRB_STATUS_PARITY_ERROR | 指出 SCSI 總線發生同位錯誤,且重試失敗。 |
SRB_STATUS_REQUEST_SENSE_FAILED | 表示要求感知命令失敗。 只有在主機總線適配卡 (HBA) 執行自動要求感知,而迷你埠驅動程式在此 HBA 的PORT_CONFIGURATION_INFORMATION中將 AutoRequestSense 設定為 TRUE 時,才會傳回此動作。 |
SRB_STATUS_NO_HBA | 表示 HBA 沒有回應。 |
SRB_STATUS_DATA_OVERRUN | 表示發生數據滿溢或不足錯誤。 迷你埠驅動程式也必須更新 SRB 的 DataTransferLength 成員,以指出如果發生不足的情況,實際傳輸的數據量。 |
SRB_STATUS_UNEXPECTED_BUS_FREE | 表示目標意外中斷連線。 |
SRB_STATUS_PHASE_SEQUENCE_FAILURE | 表示 HBA 偵測到不合法的階段順序失敗錯誤。 |
SRB_STATUS_REQUEST_FLUSHED | 指出狀態的要求已停止。 |
SRB_STATUS_BAD_FUNCTION | 表示不支援 SRB 函 式程式碼。 |
SRB_STATUS_INVALID_PATH_ID | 表示 SRB 中指定的 PathId 不存在。 |
SRB_STATUS_INVALID_TARGET_ID | 指出 SRB 中的 TargetID 值無效。 |
SRB_STATUS_INVALID_LUN | 表示 SRB 中的 Lun 值無效。 |
SRB_STATUS_ERROR_RECOVERY | 指出要求已完成,並出現 SCSI 總線狀態錯誤,且收到 SCSI 起始修復訊息。 |
SRB_STATUS_AUTOSENSE_VALID | 指出 SenseInfoBuffer 中傳回的資訊有效。 |
SRB_STATUS_QUEUE_FROZEN | 迷你埠驅動程序絕對不應該將 SrbStatus 成員設定為此值。 Windows 連接埠驅動程式可以設定此值,通知儲存設備類別驅動程式其特定周邊的要求佇列已凍結。 |
SRB_STATUS_NOT_POWERED | 表示要求失敗,因為目標未提供電源。 對於在 SrbFlags 中設定SRB_FLAGS_NO_KEEP_AWAKE的要求,傳送至已關閉電源之 LUN 的要求將會失敗,並具有此狀態。 |
SRB_STATUS_LINK_DOWN | 表示要求失敗,因為連結已關閉。 |
SRB_STATUS_BAD_SRB_BLOCK_LENGTH | 表示要求失敗,因為 SRB 長度無效。 |
ReservedUlong1
保留的。 設定為 0。
Signature
擴充 SRB 格式的簽章。 這會設定為 SRB_SIGNATURE。
Version
所使用的結構版本。 目前的版本 是STORAGE_REQUEST_BLOCK_VERSION_1。
SrbLength
這個擴充 SRB 的長度,以位元組為單位,包括這個結構、位址和任何 SRB 擴充數據。
SrbFunction
指定要執行的作業,它可以是下列其中一個值:
值 | 意義 |
---|---|
SRB_FUNCTION_EXECUTE_SCSI (0x00) | 應在目標邏輯單元上執行 SCSI 裝置 I/O 要求。 當 NumSrbExData 0 時,下列一或多個擴充要求區塊結構位於 SrbExDataOffset> 中指定的位移:SRBEX_DATA_SCSI_CDB16、SRBEX_DATA_SCSI_CDB32、SRBEX_DATA_SCSI_CDB_VAR、SRBEX_DATA_BIDIRECTIONAL、SRBEX_DATA_IO_INFO |
SRB_FUNCTION_IO_CONTROL (0x02) | 要求是 I/O 控制件要求,源自具有專用 HBA 的使用者模式應用程式。 SRB DataBuffer 指向 SRB_IO_CONTROL 標頭,後面接著數據區。 不論 MapBuffers 的值為何,驅動程式都可以使用 DataBuffer 中的值。 如果迷你埠驅動程式在初始化時要求 SRB 擴充功能,則只有 SRB 函式、SrbFlags、TimeOutValue、DataBuffer 和 DataTransferLength 成員是有效的,以及 SrbExtension 成員。 如果迷你埠驅動程式控制應用程式專用 HBA 以便支援此要求,迷你埠驅動程式應該執行要求,並在 SRB 完成時通知操作系統特定的埠驅動程式,並使用對 StorPortNotification 與 RequestComplete 和 NextRequest 的一般呼叫機制。 |
SRB_FUNCTION_RECEIVE_EVENT (0x03) | HBA 應該準備好從尋址的目標接收異步事件通知。 SRB DataBuffer 成員會指出應該放置數據的位置。 注意:此函式不會由 Storport 傳送至迷你埠。 |
SRB_FUNCTION_SHUTDOWN (0x07) | 系統正在關閉。 迷你埠驅動程式可以在所有系統活動實際停止之前收到其中幾個通知。 不過,最後一個關機通知會在上次啟動 I/O 之後發生。 此函式不需要擴充 SRB 數據。 |
SRB_FUNCTION_FLUSH (0x08) | 迷你埠驅動程序應該排清目標裝置的任何快取數據。 只有在 HBA 的 PORT_CONFIGURATION_INFORMATION中將 CachesData 設定為 TRUE 時,才會將此要求傳送至迷你埠驅動程式。 此函式不需要擴充 SRB 數據。 |
SRB_FUNCTION_ABORT_COMMAND (0x10) | 應該傳送SCSIMESS_ABORT訊息,以取消 NextSrb 成員所指向的要求。 如果這是標記佇列要求,則應該改用SCSIMESS_ABORT_WITH_TAG訊息。 如果指定的要求已完成,則應該正常完成此要求。 此函式不需要擴充 SRB 數據。 注意:此函式不會由 Storport 傳送至迷你埠。 |
SRB_FUNCTION_RELEASE_RECOVERY (0x11) | SCSIMESS_RELEASE_RECOVERY訊息應該傳送至目標控制器。 此函式不需要擴充 SRB 數據。 注意:此函式不會由 Storport 傳送至迷你埠。 |
SRB_FUNCTION_RESET_BUS (0x12) | 應該使用SCSIMESS_BUS_DEVICE_RESET訊息來重設 SCSI 總線。 迷你埠驅動程式只有在指定的要求逾時,以及後續中止逾時要求時,才會收到此要求。此函式不需要擴充 SRB 數據。 |
SRB_FUNCTION_TERMINATE_IO (0x14) | 應該傳送SCSIMESS_TERMINATE_IO_PROCESS訊息,以取消 NextSrb 成員所指向的要求。 如果指定的要求已經完成,則應該正常完成此要求。 此函式不需要擴充 SRB 數據。 注意:此函式不會由 Storport 傳送至迷你埠。 |
SRB_FUNCTION_RESET_DEVICE (0x16) | 應該使用SCSIMESS_BUS_DEVICE_RESET訊息來重設 SCSI 目標控制器。 迷你埠驅動程序應該完成目標控制器的任何作用中要求。 此函式不需要擴充 SRB 數據。 |
SRB_FUNCTION_WMI (0x17) | 要求是格式化為 SRBEX_DATA_WMI 結構的電源擴充要求。 擴充要求數據的位移位於 SrbExDataOffset[0]。 |
SRB_FUNCTION_LOCK_QUEUE (0x18) | 保留埠驅動程序針對特定邏輯單元排入佇列的要求,通常是在處理電源要求時。 只有 SRB Length、 Function、 SrbFlags 和 OriginalRequest 成員有效。 鎖定佇列時,只會處理具有 SrbFlags ORed 與 SRB_FLAGS_BYPASS_LOCKED_QUEUE 的要求。 SCSI 迷你埠驅動程式不會處理 SRB_FUNCTION_LOCK_QUEUE 要求。 |
SRB_FUNCTION_UNLOCK_QUEUE (0x19) | 釋放先前使用 SRB_FUNCTION_LOCK_QUEUE 鎖定之邏輯單元的埠驅動程式佇列。 解除鎖定要求的 SrbFlags 必須是 具有 SRB_FLAGS_BYPASS_LOCKED_QUEUE 的 ORed。 只有 SRB Length、 Function、 SrbFlags 和 OriginalRequest 成員有效。 SCSI 迷你埠驅動程式不會處理 SRB_FUNCTION_UNLOCK_QUEUE 要求。 |
SRB_FUNCTION_QUIESCE_DEVICE (0x1A) | 要求只在記憶體類別和記憶體埠驅動程序之間,而且不會傳送至迷你埠。 此函式可作為類別驅動程式等候埠驅動程式完成所有未完成的 I/O。 |
SRB_FUNCTION_RESET_LOGICAL_UNIT (0x20) | 如果可能的話,應該重設邏輯單元。 HBA 迷你埠驅動程序應該完成邏輯單元的任何作用中要求。 此函式不需要擴充 SRB 數據。 Storport 支援這種類型的重設,但 SCSI 埠則不支援。 |
SRB_FUNCTION_POWER (0x24) | 要求是格式化為 SRBEX_DATA_POWER 結構的電源擴充要求。 擴充要求數據的位移位於 SrbExDataOffset[0]。 |
SRB_FUNCTION_PNP (0x25) | 要求是格式化為 SRBEX_DATA_PNP 結構的 PnP 擴充要求。 擴充要求數據的位移位於 SrbExDataOffset[0]。 |
SRB_FUNCTION_DUMP_POINTERS (0x26) | 具有此函式的要求會傳送至 Storport 迷你埠驅動程式,用來控制保存損毀傾印數據的磁碟。 要求會收集迷你埠驅動程式所需的資訊,以支援損毀傾印和休眠。 請參閱 MINIPORT_DUMP_POINTERS 結構。 實體迷你埠驅動程序必須在其HW_INITIALIZATION_DATA的FeatureSupport成員中設定STOR_FEATURE_DUMP_POINTERS旗標,才能接收具有此函式的要求。 |
SRB_FUNCTION_FREE_DUMP_POINTERS (0x27) | 具有此函式的要求會傳送至 Storport 迷你埠驅動程式,以釋放先前要求期間針對 SRB_FUNCTION_DUMP_POINTERS 配置的任何資源。 |
SrbFlags
指出要求的各種參數和選項。 SrbFlags 是唯讀的,除非 設定SRB_FLAGS_UNSPECIFIED_DIRECTION ,而且需要次要 DMA 配接器的迷你埠驅動程式才能更新 SRB_FLAGS_DATA_IN 或 SRB_FLAGS_DATA_OUT。 此成員可以設定其中一或多個旗標。
旗標 | 意義 |
---|---|
SRB_FLAGS_QUEUE_ACTION_ENABLE | 指出要啟用標記佇列動作。 |
SRB_FLAGS_DISABLE_AUTOSENSE | 表示不應該傳回要求感知資訊。 |
SRB_FLAGS_DATA_IN | 指出數據會從裝置傳輸到系統。 |
SRB_FLAGS_DATA_OUT | 表示數據會從系統傳輸到裝置。 |
SRB_FLAGS_UNSPECIFIED_DIRECTION | 針對與 ASPI/CAM SCSI 介面的回溯相容性所定義,此旗標表示傳輸方向可能是上述任一項,因為已設定上述兩個旗標。 如果設定此旗標,迷你埠驅動程序應該檢查 SCSI 總線上目標的數據階段來判斷傳輸方向。 |
SRB_FLAGS_NO_DATA_TRANSFER | 表示此要求沒有數據傳輸。 如果已設定,則旗標 SRB_FLAGS_DATA_OUT、 SRB_FLAGS_DATA_IN和 SRB_FLAGS_UNSPECIFIED_DIRECTION 都是清楚的。 |
SRB_FLAGS_DISABLE_SYNCH_TRANSFER | 可能的話,表示 HBA 應該針對此傳輸要求執行異步 I/O。 如果先前交涉同步 I/O,HBA 必須先重新交涉異步 I/O,才能執行傳輸。 |
SRB_FLAGS_DISABLE_DISCONNECT | 指出 HBA 不應允許目標在此要求處理期間中斷與 SCSI 總線的連線。 |
SRB_FLAGS_BYPASS_FROZEN_QUEUE | 此旗標與迷你埠驅動程序無關。 |
SRB_FLAGS_NO_QUEUE_FREEZE | 此旗標與迷你埠驅動程序無關。 |
SRB_FLAGS_IS_ACTIVE | 此旗標與迷你埠驅動程序無關。 |
SRB_FLAGS_ALLOCATED_FROM_ZONE | 此旗標與迷你埠驅動程序無關,而且已過時於新的 Windows 類別驅動程式。 針對 Windows 舊版類別驅動程式,這表示 SRB 是否從區域緩衝區配置。 如果設定此旗標,類別驅動程序必須呼叫 ExInterlockedFreeToZone 以釋放 SRB;否則,它必須呼叫 ExFreePool。 新的類別驅動程式應該使用 lookaside 清單,而不是區域緩衝區。 |
SRB_FLAGS_SGLIST_FROM_POOL | 此旗標與迷你埠驅動程序無關。 針對類別驅動程式,這表示散佈/收集清單的記憶體是從非分頁集區配置。 如果設定此旗標,類別驅動程序必須呼叫 ExFreePool ,以在 SRB 完成後釋放記憶體。 |
SRB_FLAGS_BYPASS_LOCKED_QUEUE | 此旗標與迷你埠驅動程序無關。 若為埠驅動程式,此旗標表示是否鎖定邏輯單元佇列,都應該處理要求。 較高層級的驅動程式必須設定此旗標,才能傳送 SRB_FUNCTION_UNLOCK_QUEUE 要求。 |
SRB_FLAGS_NO_KEEP_AWAKE | 此旗標與迷你埠驅動程序無關。 Windows 類別驅動程式會使用此旗標向埠驅動程式指出要求失敗,而不是啟動裝置來處理此要求。 |
SRB_FLAGS_FREE_SENSE_BUFFER | 表示埠或迷你埠驅動程式已為感知數據配置緩衝區。 這會通知類別驅動程式,它必須在擷取數據之後釋放感知數據緩衝區。 |
SRB_FLAGS_D3_PROCESSING | 表示要求是 D3 處理的一部分。 支援運行時間電源控制的迷你埠不應該使用這些要求呼叫 StorPortPoFxActivateComponent 或 StorPortPoFxIdleComponent 。 |
SRB_FLAGS_ADAPTER_CACHE_ENABLE | 表示配接器可以快取數據。 |
ReservedUlong2
保留的。 設定為 0。
RequestTag
包含作業系統特定埠驅動程式指派的佇列標籤。 如果此成員用於標記的佇列,HBA 支援邏輯單元的內部佇列, (RU) ,而迷你埠驅動程式會在此 HBA 的PORT_CONFIGURATION_INFORMATION中將 TaggedQueueing 設定為 TRUE 。
RequestPriority
SRB 的優先順序指派。 可以是下列其中一個值。
值 | 意義 |
---|---|
StorIoPriorityVeryLow (0) | 非常低的優先順序。 |
StorIoPriorityLow (1) | 低優先順序。 |
StorIoPriorityNormal (2) | 一般優先順序。 |
StorIoPriorityHigh (3) | 高優先順序。 |
StorIoPriorityCritical (4) | 重要優先順序。 |
RequestAttribute
指出設定 SRB_FLAGS_QUEUE_ACTION_ENABLE 旗標時要使用的標記佇列訊息。 此值可以是下列其中一項: SRB_SIMPLE_TAG_REQUEST、 SRB_HEAD_OF_QUEUE_TAG_REQUEST或 SRB_ORDERED_QUEUE_TAG_REQUEST。
TimeOutValue
指出要求可以在操作系統特定埠驅動程序視為逾時之前執行間隔,以秒為單位。小型埠驅動程式不需要時間要求,因為埠驅動程式已經這麼做。
DUMMYUNIONNAME
內嵌聯集。
DUMMYUNIONNAME.SystemStatus
用來將系統失敗狀態資訊儲存在 SrbStatus 失敗狀況中,例如 (SRB_STATUS_INTERNAL_ERROR) 。
DUMMYUNIONNAME.RequestTagHigh4Bytes
如果啟用唯一標籤功能,則用來儲存高四個字節的唯一標記。
SystemStatus
每當無法將要求傳遞至迷你埠驅動程式時,Storport 驅動程式會使用,而不是 SrbStatus 來報告已完成要求的狀態。 在這種情況下, SrbStatus 會設定為 SRB_STATUS_INTERNAL_ERROR。 此成員專門用於 Storport 與類別驅動程式之間的通訊,而且不應該由迷你埠驅動程式使用。
ZeroGuard1
保護區域,以防止將此結構解譯為 SCSI_REQUEST_BLOCK的驅動程式。 設定為 0。
AddressOffset
此結構開頭的記憶體要求位址位移。 此位移會尋找包含要求位址 的STOR_ADDRESS 結構。
NumSrbExData
此要求的擴充 SRB 數據區塊計數。
DataTransferLength
表示數據緩衝區的大小,以位元組為單位。 如果發生不足狀況,迷你埠驅動程序必須將此成員更新為實際傳輸的位元元組數目。
DataBuffer
指向數據緩衝區。 除非迷你埠驅動程式在 HBA 的PORT_CONFIGURATION_INFORMATION中將 MapBuffers 設定為 TRUE,否則迷你埠驅動程式不應使用此值作為數據指標。 不過,在SRB_FUNCTION_IO_CONTROL要求的情況下,迷你埠驅動程式可以使用此值作為數據指標,而不論 MapBuffers 的值為何。
ZeroGuard2
保護區域,以防止將此結構解譯為 SCSI_REQUEST_BLOCK的驅動程式。 設定為 0。
OriginalRequest
指向此要求的 IRP。 此成員與迷你埠驅動程序無關。
ClassContext
指向此要求的類別驅動程式內容數據。 此成員與迷你埠驅動程序無關。
PortContext
指向此要求的埠驅動程序內容數據。 此成員與迷你埠驅動程序無關。
MiniportContext
指向 Srb 延伸模組。 如果迷你埠驅動程式在 HW_INITIALIZATION_DATA 中將 SrbExtensionSize 設定為零,則不得使用此成員。 MiniportContext 上的記憶體不是由操作系統特定的埠驅動程式初始化,而迷你埠驅動程式決定的數據可以直接由 HBA 存取。 您可以使用 MiniportContext 指標呼叫 StorportGetPhysicalAddress 來取得對應的實體位址。
NextSrb
指出套用此要求 STORAGE_REQUEST_BLOCK 。 只有一小部分的要求會使用第二個 SRB,例如SRB_FUNCTION_ABORT_COMMAND。
_STORAGE_REQUEST_BLOCK
SrbExDataOffset[ANYSIZE_ARRAY]
指定SRB擴充數據區塊位置的位移陣列。 如果 NumSrbExData = 0,則此陣列是空的。
備註
從 Windows 8 開始,使用 STORAGE_REQUEST_BLOCK 結構時,支援擴充 SRB 類型。 STORAGE_REQUEST_BLOCK 擴充 SRB 函式,允許將 SRB 函式的擴充數據區塊新增至要求。 使用 SCSI_REQUEST_BLOCK 結構的 SRB 要求支援將會繼續。
如果 NumSrbExData> 0,SRB 擴充數據區塊的位移會位於 SrbExDataOffset 陣列中。 每個位移都是相對於這個 結構的開頭,並指向包含擴充數據區塊 的SRBEX_DATA 結構。
SRB 的目標裝置位址位於 AddressOffset 所指示的STOR_ADDRESS結構中。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | 可在 Windows 8 和更新版本的 Windows 中使用。 |
標頭 | storport.h (包括 Storport.h、Srb.h、Minitape.h) |