HW_BUILDIO funzione di callback (storport.h)

Articolo
05/23/2024

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

Sintassi

HW_BUILDIO HwBuildio;

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

Parametri

DeviceExtension

Puntatore all'area di archiviazione del driver miniport.

Srb

Puntatore al blocco di richiesta SCSI 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 L/O. HwStorBuildIo restituisce FALSE per informare il chiamante che la SRB non deve essere passata a HwStorStartIo. In questi casi, il driver miniport deve completare la SRB chiamando StorPortNotification con un tipo di notifica RequestComplete. Questa operazione può essere eseguita in HwStorBuildIo o altrove nel driver miniport, purché la 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 punta il membro HwBuildIo nella struttura HW_INITIALIZATION_DATA . Il prototipo effettivo di questa routine è definito in Storport.h come segue:

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

Il driver di porta chiama la routine HwStorBuildIo in DISPATCH IRQL senza contenere blocchi di spin. A causa di questo, l'allocazione della 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 essere in contesa se più di un'istanza di HwStorBuildIo è attiva in qualsiasi momento.

Completando le attività di configurazione di I/O di I/O completate in HwStorBuildIo anziché in HwStorStartIo, il driver miniport abilita una concorrenza di I/O maggiore e quindi migliora la velocità effettiva di I/O. Per le prestazioni più elevate, 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 alle 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 cdbs.
- 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 controllati 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 scrittori 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 eseguire).
- 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 solo dal driver miniport 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 solo dal driver miniport 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 di dump di arresto anomalo. A partire da Windows 8, i driver miniport non virtuali possono ricevere facoltativamente 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 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 di driver miniport, vedere Routine HwStorBuildIo asincronizzata.

Esempio

Per definire una funzione di callback HwStorBuildIo , è 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 HwStorBuildIo denominata MyHwBuildIo, usare il tipo di HW_BUILDIO come illustrato in questo esempio di codice:

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 durante l'esecuzione degli 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 usate 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 su Use_decl_annotations, vedere Annotazione del comportamento della funzione.