HW_FIND_ADAPTER funzione di callback (storport.h)

Articolo
08/07/2023

La routine HwStorFindAdapter usa la configurazione fornita per determinare se è supportato un HBA specifico e, se è, per restituire informazioni di configurazione su tale scheda.

Sintassi

HW_FIND_ADAPTER HwFindAdapter;

ULONG HwFindAdapter(
           PVOID DeviceExtension,
  [in]     PVOID HwContext,
  [in]     PVOID BusInformation,
  [in]     PCHAR ArgumentString,
  [in/out] PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  [in]     PBOOLEAN Reserved3
)
{...}

Parametri

DeviceExtension

Fornisce un'area di archiviazione per adattatore.

[in] HwContext

Impostata su NULL.

[in] BusInformation

Impostata su NULL.

[in] ArgumentString

Fornisce una stringa con terminazione NULL con informazioni di contesto sul driver.

[in/out] ConfigInfo

Fornisce una struttura di PORT_CONFIGURATION_INFORMATION inizializzata usata dal driver miniport durante l'inizializzazione.

[in] Reserved3

Riservato per l'utilizzo nel sistema.

Valore restituito

HwStorFindAdapter deve restituire uno dei valori di stato seguenti:

Codice restituito	Descrizione
SP_RETURN_FOUND	Indica che è stato trovato un HBA supportato e che le informazioni di configurazione rilevanti per HBA sono state determinate e impostate correttamente nella struttura PORT_CONFIGURATION_INFORMATION .
SP_RETURN_ERROR	Indica che è stato trovato un HBA, ma si è verificato un errore durante l'acquisizione delle informazioni di configurazione. Se possibile, tale errore deve essere registrato con StorPortLogError.
SP_RETURN_BAD_CONFIG	Indica che le informazioni di configurazione fornite non sono valide per l'adapter.
SP_RETURN_NOT_FOUND	Indica che non è stato trovato alcun HBA supportato per le informazioni di configurazione fornite.

Commenti

Poiché il driver Storport supporta solo i dispositivi Plug and Play (PnP), i parametri HwContext e BusInformation su HwStorFindAdapter non vengono forniti ai driver miniport non virtuali.

HwStorFindAdapter deve impostare i campi MaximumTransferLength e NumberOfPhysicalBreaks nella struttura ConfigInfo . Oltre a questi campi, la struttura PORT_CONFIGURATION_INFORMATION specifica sempre tutte le risorse dell'adattatore necessarie per avviare l'adapter.

Il nome HwStorFindAdapter è solo un segnaposto. Il prototipo effettivo di questa routine è definito in Storport.h come segue:

typedef
ULONG
HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );

Nella maggior parte dei casi StorPort chiama la routine HwStorFindAdapter in IRQL == PASSIVE_LEVEL senza acquisire blocchi di spin. Il caso di eccezione è quando il miniport non supporta la chiamata di HwStorAdaptorControl con il tipo di controllo SCSIRestartAdapter . In questa situazione StorPort reinizializzerà invece l'adattatore chiamando sia HwStorFindAdapter che HwStorInitialize. Quando si tratta del caso, HwStorFindAdapter viene chiamato irQL == DISPATCH_LEVEL. Inoltre, quando in modalità dump , HwStorFindAdapter viene chiamato in IRQL == HIGH_LEVEL.

Esempio

Per definire una funzione callback HwStorFindAdapter , è prima necessario 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 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 HwStorFindAdapter denominata MyHwFindAdapter, usare il tipo di HW_FIND_ADAPTER come illustrato in questo esempio di codice:

HW_FIND_ADAPTER MyHwFindAdapter;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
ULONG
MyHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );
  {
      ...
  }

Il tipo di funzione HW_FIND_ADAPTER è 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_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 su Use_decl_annotations, vedere Annotazione del comportamento della funzione.