HW_BUILDIO funzione di callback (storport.h)

Articolo
02/26/2024

La routine HwStorBuildIo elabora SRB con accesso non sincronizzato alle strutture di dati di sistema condivise prima di passarlo a HwStorStartIo.

Sintassi

HW_BUILDIO HwBuildio;

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

Parametri

DeviceExtension

Puntatore all'area di archiviazione del driver miniport per ogni area di archiviazione HBA.

Srb

Puntatore al blocco di richieste SCSI (SRB) da elaborare.

Valore restituito

HwStorBuildIo restituisce TRUE per informare il chiamante che StorPort deve chiamare la routine HwStorStartIo se StorPort considera il LUN pronto per ricevere I/O. HwStorBuildIo restituisce FALSE per informare il chiamante che SRB non deve essere passato a HwStorStartIo. In questi casi, il driver miniport deve completare l'SRB chiamando StorPortNotification con un tipo di notifica RequestComplete. Questa operazione può essere eseguita in HwStorBuildIo o altrove nel driver miniport, purché la funzione SRB venga completata prima del timeout specificato nel campo TimeOutValue della struttura SRB.

Commenti

Il nome HwStorBuildIo è solo un segnaposto per la funzione miniport a cui fa riferimento il membro HwBuildIo nella struttura HW_INITIALIZATION_DATA . Il prototipo effettivo di questa routine viene definito in Storport.h come indicato di seguito:

typedef
BOOLEAN
HW_BUILDIO (
  _In_ PVOID DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

Il driver di porta chiama la routine HwStorBuildIo in DISPATCH IRQL senza tenere premuti blocchi di rotazione. Per questo motivo, l'allocazione di memoria tramite StorPortAllocatePool e l'esclusione reciproca tramite StorPortAcquireSpinLock sono consentite in HwStorBuildIo. In un ambiente multiprocessore, più di un HwStorBuildIo può essere attivo alla volta, quindi il driver miniport è necessario per sincronizzare l'accesso alle risorse di sistema, che possono trovarsi in contesa se più di un'istanza di HwStorBuildIo è attiva in qualsiasi momento.

Completando le attività di configurazione di I/O che richiedono molto tempo in HwStorBuildIo anziché in HwStorStartIo, il driver miniport abilita una maggiore concorrenza di I/O e quindi migliora la velocità effettiva di I/O. Per ottenere prestazioni ottimali, i driver miniport devono eseguire il maggior numero possibile di pre-elaborazione in HwStorBuildIo in modo che possa inviare richieste all'HBA tramite HwStorStartIo nel minor tempo possibile. I dati e lo stato pre-elaborati possono essere archiviati nelle strutture DeviceExtension o SrbExtension . Solo le modifiche apportate a parti univoche di DeviceExtension devono verificarsi perché non vengono mantenuti blocchi. HwStorBuildIo e HwStorStartIo ricevono i tipi di funzione Srb seguenti:

SRB_FUNCTION_EXECUTE_SCSI: invia un CDB al bus/destinazione/lun specificato.
- Srb-DataTransferLength> è valido per tutti i cdb.
- Srb-DataBuffer> è NULL per le richieste di lettura e scrittura. Per accedere ai dati associati, usare StorPortGetScatterGatherList (per i trasferimenti Dma) o StorPortGetSystemAddress (per I/O controllato dal programma) per ottenere l'elenco Raccolta a dispersione o l'indirizzo virtuale del buffer. Per altre richieste, Srb-Databuffer> punta ai dati associati a Srb.
- Srb-PathId> è valido e rappresenta il pathid assegnato a Storport in StorPortNotification (BusChange). Gli autori di driver miniport devono usare pathid come indice in una tabella di bus all'interno del miniport.
- Srb-TargetId> e Srb-Lun> sono validi.
SRB_FUNCTION_IO_CONTROL: Miniport definito.
- Srb-DataTransferLength> e Srb-DataBuffer> sono validi se impostati dal richiedente.
- Srb-PathId>, Srb-TargetId> e Srb-Lun> sono tutti validi.
SRB_FUNCTION_RESET_LOGICAL_UNIT: reimpostare l'unità logica specificata (se il dispositivo è in grado di supportare).
- Srb-DataTransferLength> e Srb-DataBuffer> non sono validi.
- Srb-PathId>, Srb-TargetId> e Srb-Lun> sono tutti validi.
SRB_FUNCTION_RESET_DEVICE: reimpostare la destinazione Scsi specificata.
- Srb-DataTransferLength> e Srb-DataBuffer>, Srb-Lun> non sono validi.
- Srb-PathId> e Srb-TargetId> sono validi.
SRB_FUNCTION_RESET_BUS: reimpostare tutte le destinazioni nel bus SCSI specificato.
- Solo Srb-PathId> è valido.
SRB_FUNCTION_FLUSH: indica al driver miniport di scaricare tutti i dati memorizzati nella cache.
- Eseguito dal driver miniport solo se imposta CachesData == TRUE nella struttura PORT_CONFIGURATION_INFORMATION .
- Srb-PathId>, Srb-TargetId> e Srb-Lun> sono tutti validi.
SRB_FUNCTION_SHUTDOWN: indica al driver miniport di scaricare tutti i dati memorizzati nella cache per arrestare.
- Eseguito dal driver miniport solo se imposta CachesData == TRUE nella struttura PORT_CONFIGURATION_INFORMATION .
- Srb-PathId>, Srb-TargetId> e Srb-Lun> sono tutti validi.
SRB_FUNCTION_DUMP_POINTERS: fornisce informazioni necessarie per il driver miniport per supportare il dump di arresto anomalo e l'ibernazione.
- Questa richiesta viene inviata a un driver miniport virtuale Storport usato per controllare il disco che contiene i dati del dump di arresto anomalo del sistema. A partire da Windows 8, i driver miniport non virtuali possono facoltativamente ricevere questa richiesta.
- Srb-PathId>, Srb-TargetId> e Srb-Lun> sono tutti validi.
SRB_FUNCTION_FREE_DUMP_POINTERS: a partire da Windows 8, questa richiesta viene inviata al miniport per liberare le risorse allocate durante la richiesta di SRB_FUNCTION_DUMP_POINTERS.
- Srb-PathId>, Srb-TargetId> e Srb-Lun> sono tutti validi.

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 .

Per altre informazioni su ciò che è possibile e non è possibile eseguire in modo sicuro in questa routine del driver miniport, vedere Routine HwStorBuildIo non sincronizzata.

Esempio

Per definire una funzione di callback HwStorBuildIo , è necessario innanzitutto fornire 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 tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una routine di callback HwStorBuildIo denominata MyHwBuildIo, usare il tipo di HW_BUILDIO come illustrato nell'esempio di codice seguente:

HW_BUILDIO MyHwBuildIo;

Implementare quindi la routine di callback come indicato di seguito:

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

Il tipo di funzione HW_BUILDIO è 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'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione HW_BUILDIO 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 sulle Use_decl_annotations, vedere Annotazione del comportamento della funzione.