VIRTUAL_HW_FIND_ADAPTER funzione di callback (storport.h)

Articolo
08/07/2023

Il miniport virtuale Storport usa le informazioni di configurazione fornite alla routine VIRTUAL_HW_FIND_ADAPTER per inizializzare ulteriormente se stesso.

Sintassi

VIRTUAL_HW_FIND_ADAPTER VirtualHwFindAdapter;

ULONG VirtualHwFindAdapter(
  PVOID DeviceExtension,
  PVOID HwContext,
  PVOID BusInformation,
  PVOID LowerDevice,
  PCHAR ArgumentString,
  PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  PBOOLEAN Again
)
{...}

Parametri

DeviceExtension

Puntatore all'area di archiviazione non di paging per adattatore del driver miniport. Il driver di porta specifico del sistema operativo alloca la memoria per e inizializza questa estensione con zeri prima di chiamare la routine VIRTUAL_HW_FIND_ADAPTER miniport.

HwContext

Puntatore al PDO nello stack di dispositivi. L'HBA è l'oggetto FDO. Il PDO potrebbe appartenere al driver Pci.sys se il driver miniport controlla l'hardware fisico. Ma nel caso di un driver miniport virtuale, il PDO appartiene al gestore PnP.

BusInformation

Puntatore all'oggetto dispositivo funzionale del miniport.

LowerDevice

Puntatore all'oggetto dispositivo controllato dall'oggetto FDO del miniport.

ArgumentString

Puntatore a una stringa ASCII con terminazione Null. Questa stringa, se specificata, contiene informazioni sul dispositivo dal Registro di sistema, ad esempio un parametro di base.

ConfigInfo

Puntatore a una struttura PORT_CONFIGURATION_INFORMATION . Il driver della porta inizializza questa struttura con tutte le informazioni di configurazione note, ad esempio i valori impostati dal driver del miniport nel VIRTUAL_HW_INITIALIZATION_DATA. VIRTUAL_HW_FIND_ADAPTER deve utilizzare tutte le informazioni fornite per determinare se l'HBA virtuale che descrive è uno che il driver miniport supporta. In tal caso, VIRTUAL_HW_FIND_ADAPTER inizializza e configura l'HBA e inserisce eventuali informazioni di configurazione mancanti. Se possibile, un driver miniport deve avere valori di configurazione predefiniti per ogni tipo di HBA supportato, nel caso in cui il driver di porta dipendente dal sistema operativo non possa fornire informazioni di configurazione aggiuntive non fornite dalla routine DriverEntry del driver miniport.

Again

Non usato.

Valore restituito

VIRTUAL_HW_FIND_ADAPTER deve restituire uno dei valori di stato seguenti:

Codice restituito	Descrizione
SP_RETURN_FOUND	È stato rilevato un HBA supportato e che le informazioni di configurazione rilevanti per HBA sono state determinate correttamente e impostate nella struttura PORT_CONFIGURATION_INFORMATION .
SP_RETURN_ERROR	È stato trovato un hbA, ma si è verificato un errore quando ha ottenuto le informazioni di configurazione. Se possibile, tale errore deve essere registrato con ScsiPortLogError.
SP_RETURN_BAD_CONFIG	Le informazioni di configurazione fornite non sono valide per l'adattatore.
SP_RETURN_NOT_FOUND	Non è stato trovato alcun hba supportato per le informazioni di configurazione fornite.

Commenti

Il campo VirtualDevice nella struttura delle informazioni di configurazione deve essere impostato su TRUE. Altri campi possono essere impostati in base alle esigenze.

Il driver della porta chiama il VIRTUAL_HW_FIND_ADAPTER del miniport virtuale Storport in PASSIVE_LEVEL .

Il nome VirtualHwStorFindAdapter è il testo segnaposto per il nome di routine effettivo. Il prototipo effettivo di questa routine è definito in Srb.h come indicato di seguito:

typedef
ULONG
VIRTUAL_HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_ PVOID  LowerDevice,
  _In_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _Out_ PBOOLEAN Again
  );

Esempio

Per definire una funzione di callback VIRTUAL_HW_FIND_ADAPTER, è 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 VIRTUAL_HW_FIND_ADAPTER denominata MyVirtualHwFindAdapter, usare il tipo VIRTUAL_HW_FIND_ADAPTER come illustrato nell'esempio di codice seguente:

VIRTUAL_HW_FIND_ADAPTER MyVirtualHwFindAdapter;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
ULONG
MyVirtualHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_ PVOID  LowerDevice,
  _In_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _Out_ PBOOLEAN Again
  );
  {
      ...
  }

Il tipo di funzione VIRTUAL_HW_FIND_ADAPTER è 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 assicura che vengano utilizzate le annotazioni applicate al tipo di funzione VIRTUAL_HW_FIND_ADAPTER 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.