HW_STARTIO funzione di callback (storport.h)

Articolo
08/07/2023

Il driver Storport chiama la routine HwStorStartIo una sola volta per ogni richiesta di I/O in ingresso.

Sintassi

HW_STARTIO HwStartio;

BOOLEAN HwStartio(
  PVOID DeviceExtension,
  PSCSI_REQUEST_BLOCK Srb
)
{...}

Parametri

DeviceExtension

Puntatore all'area di archiviazione del driver miniport.

Srb

Puntatore al blocco di richiesta SCSI da avviare.

Valore restituito

HwStorStartIo restituisce TRUE se la richiesta è stata avviata correttamente. In caso contrario, restituisce FALSE.

Commenti

HwStorStartIo avvia un'operazione di I/O. StorPort è progettato per usare i dati privati di un miniport preparati in HwStorBuildIo e archiviati in DeviceExtension o Srb-SrbExtension>. Poiché HwStorBuildIo viene chiamato senza blocchi di spin, le migliori prestazioni del driver vengono ottenute preparando il maggior numero possibile di dati in HwStorBuildIo.

Storport chiama HwStorStartIo nei modi seguenti:

Per i driver miniport non virtuali di archiviazione, a seconda del valore di SyncModel impostato in PORT_CONFIGURATION_INFORMATION, Storport chiama sempre HwStorStartIo allo stesso IRQL e usa un blocco spin interno per assicurarsi che le richieste di I/O vengano avviate in sequenza. IRQL è DISPATCH_LEVEL (modalità full-duplex) o DIRQL (modalità half-duplex).

Quando si gestisce I/O in modalità half-duplex, la routine HwStorStartIo non deve acquisire il proprio blocco di rotazione. Inoltre, l'allocazione della memoria usando StorPortAllocatePool e l'esclusione reciproca tramite StorPortAcquireSpinLock non sono consentite nella routine HwStorStartIo . In modalità full-duplex, StorPortAllocatePool e StorPortAcquireSpinLock possono essere usati nella routine HwStorStartIo .

Se un miniport non virtuale supporta l'ottimizzazione dei canali simultanei (STOR_PERF_CONCURRENT_CHANNELS impostata da StorPortInitializePerfOpts), sono possibili più chiamate a HwStorStartIo . In questo caso, il miniport dovrà assicurarsi che tutte le risorse condivise siano protette da un blocco. Con questa ottimizzazione delle prestazioni Storport non acquisisce il blocco StartIo prima di chiamare HwStorStartIo e il miniport deve fornire il proprio blocco se necessario.
Per i driver miniport virtuali di archiviazione, Storport chiama HwStorStartIo in qualsiasi IRQL <= DISPATCH_LEVEL e non usa un blocco di spin interno. La routine HwStorStartIo può acquisire il proprio blocco spin chiamando StorPortAcquireSpinLock. Inoltre, le chiamate a StorPortAllocatePool sono consentite nella routine HwStorStartIo di un driver miniport virtuale di archiviazione.

La SRB deve essere completata al momento della ricezione dello stato SCSI. Quando il driver Storport completa la SRB chiamando StorPortNotification con un tipo di notificaRequestComplete, è previsto che una SRB restituisca uno dei valori seguenti nel campo SrbStatus di Srb :

SRB_STATUS_SUCCESS
- Indica che lo stato Srb è stato inviato e SCSI (possibilmente con dati) è stato restituito.
- Storport restituisce i dati e lo stato al chiamante.
- L'azione Miniport è none, ad eccezione del completamento della richiesta usando StorPortNotification for RequestComplete, probabilmente da HwStorDpcRoutine.
SRB_STATUS_BUSY
- Indica che si verifica un problema temporaneo con l'invio di Srb (ad esempio, i registri dell'adattatore o i buffer sono occupati).
- Storport elimina l'estensione Srb originale a cui Srb-SrbExtension> punta e ne genera uno nuovo. Storport invia la Srb originale con l'estensione Srb appena rilasciata nelle chiamate successive a HwStorBuildIo e HwStorStartIo. Tutti i dati nell'estensione Srb originale verranno persi.
- Il miniport non deve aggiornare il datatransferLength di Srb.
- Poiché viene emessa una nuova estensione Srb, il miniport deve assicurarsi che non venga mai generato SRB_STATUS_BUSY al centro di una transazione SCSI. Dopo l'avvio della transazione, deve essere completata o annullata. Gli stati occupati dell'hardware durante la transazione devono essere gestiti dal driver miniport.

Il nome HwStorStartIo è un segnaposto per descrivere la routine miniport impostata nel membro HwStartIo della struttura HW_INITIALIZATION_DATA . Questa struttura viene passata nel parametro HwInitializationData di StorPortInitialize. Il prototipo effettivo di questa routine è definito in Storport.h come segue:

typedef
BOOLEAN
(*PHW_STARTIO) (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

A partire da Windows 8, il parametro Srb può puntare a SCSI_REQUEST_BLOCK o STORAGE_REQUEST_BLOCK. Se l'identificatore di funzione nel campo Funzione di Srb è SRB_FUNCTION_STORAGE_REQUEST_BLOCK, SRB è una struttura di richiesta STORAGE_REQUEST_BLOCK .

Esempio

Per definire una routine di callback HwStorStartIo , è prima necessario specificare una dichiarazione di funzione che il verifica driver statico (SDV) e altri strumenti di verifica richiedono, come illustrato nell'esempio di codice seguente:

Per definire una funzione di callback HwStorStartIo , è prima necessario specificare una dichiarazione di funzione che identifica il tipo di funzione di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione usando i tipi di funzione callback consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una routine di callback HwStorStartIo denominata MyHwStartIo, usare il tipo di HW_STARTIO e implementare la routine di callback come indicato di seguito:

HW_STARTIO MyHwStartIo

BOOLEAN
MyHwStartIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

Il tipo di funzione HW_STARTIO è definito nel file di intestazione Storport.h . Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'oggetto _Use_decl_annotations_ annotation alla definizione della funzione. Garantisce _Use_decl_annotations_ annotation che vengano usate le annotazioni applicate al tipo di funzione HW_STARTIO nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver Storport. Per informazioni su _Use_decl_annotations_, vedere Annotazione del comportamento della funzione.