Funzione StorPortBuildScatterGatherList (storport.h)

Articolo
02/29/2024

La routine StorPortBuildScatterGatherList crea un elenco di dispersione/raccolta per il buffer di dati specificato.

Sintassi

ULONG StorPortBuildScatterGatherList(
  [in]      PVOID                        HwDeviceExtension,
  [in]      PVOID                        Mdl,
  [in]      PVOID                        CurrentVa,
  [in]      ULONG                        Length,
  [in]      PPOST_SCATTER_GATHER_EXECUTE ExecutionRoutine,
  [in]      PVOID                        Context,
  [in]      BOOLEAN                      WriteToDevice,
  [in, out] PVOID                        ScatterGatherBuffer,
  [in]      ULONG                        ScatterGatherBufferLength
);

Parametri

[in] HwDeviceExtension

Puntatore all'estensione del dispositivo hardware per l'adattatore del bus host (HBA).

[in] Mdl

Puntatore a un elenco di descrittori di memoria (MDL) che descrive le pagine di memoria associate al buffer di dati.

[in] CurrentVa

Indirizzo virtuale del buffer dei dati.

[in] Length

Lunghezza, in byte, del buffer di dati.

[in] ExecutionRoutine

Puntatore a un driver miniport fornito da ExecutionRoutine. Il driver Storport chiama questa routine dopo aver creato l'elenco di dispersione/raccolta. Il driver miniport deve eseguire tutte le operazioni che usano l'elenco di dispersione/raccolta all'interno della routine di esecuzione, non nel codice che segue la chiamata alla routine StorPortBuildScatterGatherList .

Un executionRoutine viene dichiarato come segue:

VOID
ExecutionRoutine (
    IN PVOID  *DeviceObject,
    IN PVOID  *Irp,
    IN PSTOR_SCATTER_GATHER_LIST  ScatterGather,
    IN PVOID  Context
    );

DeviceObject

I driver miniport devono ignorare questo parametro.

Irp

I driver miniport devono ignorare questo parametro.

ScatterGather

Puntatore a una struttura STOR_SCATTER_GATHER_LIST che contiene l'elenco di dispersione/raccolta per il buffer di dati specificato.

Contesto

Valore di contesto specificato nel parametro Context della funzione StorPortBuildScatterGatherList.

Il driver Storport chiama un miniport driver ExecutionRoutine in IRQL = DISPATCH_LEVEL.

[in] Context

Valore di contesto passato dal driver di porta alla routine di esecuzione specificata nel parametro ExecutionRoutine . La routine di esecuzione usa questo valore per identificare in modo univoco la richiesta.

[in] WriteToDevice

Valore che indica la direzione del trasferimento DMA. Un valore true indica un trasferimento dal buffer di dati al dispositivo e un valore false indica un trasferimento dal dispositivo al buffer dei dati.

[in, out] ScatterGatherBuffer

Puntatore a un buffer fornito da miniport che riceve l'elenco di dispersione/raccolta. Un driver miniport può allocare memoria per questo buffer chiamando la routine StorPortAllocatePool .

[in] ScatterGatherBufferLength

Dimensioni, in byte, del buffer a cui punta il parametro ScatterGatherBuffer .

Valore restituito

StorPortBuildScatterGatherList restituisce uno dei valori seguenti:

Codice restituito	Descrizione
STOR_STATUS_NOT_IMPLEMENTED	Questa funzione non viene implementata nel sistema operativo attivo.
STOR_STATUS_SUCCESS	Indica che la routine ha creato correttamente l'elenco di dispersione/raccolta. Importante Vedere "Osservazioni".
STOR_STATUS_INVALID_PARAMETER	Il valore HwDeviceExtension passato è NULL.
STOR_STATUS_INVALID_IRQL	La chiamata è stata effettuata in un IRQL non valido.
STOR_STATUS_INSUFFICIENT_RESOURCES	Il sistema dispone di registri mappa insufficienti disponibili per il trasferimento.
STOR_STATUS_BUFFER_TOO_SMALL	Il parametro Length è troppo grande per adattarsi all'interno del buffer.

Commenti

Il driver miniport chiama StorPortPutScatterGatherList per rilasciare le risorse assegnate da StorPortBuildScatterGatherList durante la costruzione dell'elenco di dispersione/raccolta.

Il driver miniport deve chiamare StorPortPutScatterGatherList prima di liberare o riutilizzare la memoria allocata per l'elenco di dispersione/raccolta.

Nota Se StorPortBuildScatterGatherList restituisce STOR_STATUS_SUCCESS, il callback in ExecutionRoutine è stato accodato correttamente per l'esecuzione dopo la creazione dell'elenco di dispersione/raccolta. Il miniport non deve presupporre che ExecutionRoutine sia stato chiamato o che l'elenco di dispersione/raccolta sia pronto quando StorPortBuildScatterGatherList restituisce. Se necessario, il miniport può sincronizzare l'esecuzione del codice seguente StorPortBuildScatterGatherList con il callback in ExecutionRoutine per assicurarsi che sia disponibile l'elenco di dispersione/raccolta.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	Storport.h (include Storport.h)
IRQL	DISPATCH_LEVEL

Vedi anche

STOR_SCATTER_GATHER_LIST

StorPortAllocatePool

StorPortPutScatterGatherList

Condividi tramite