HW_ADAPTER_CONTROL funzione di callback (storport.h)

Articolo
02/29/2024

La routine HwStorAdapterControl di un driver miniport viene chiamata per eseguire operazioni sincrone per controllare lo stato o il comportamento di un adattatore, ad esempio arrestare o riavviare l'adattatore del bus host (HBA) per la gestione della potenza.

Sintassi

HW_ADAPTER_CONTROL HwAdapterControl;

SCSI_ADAPTER_CONTROL_STATUS HwAdapterControl(
  [in] PVOID DeviceExtension,
  [in] SCSI_ADAPTER_CONTROL_TYPE ControlType,
  [in] PVOID Parameters
)
{...}

Parametri

[in] DeviceExtension

Puntatore all'area di archiviazione del driver miniport.

[in] ControlType

Valore SCSI_ADAPTER_CONTROL_TYPE che specifica un'operazione di controllo adattatore, in cui ogni tipo di controllo avvia un'azione dal driver miniport. Per informazioni dettagliate, vedere SCSI_ADAPTER_CONTROL_TYPE .

[in] Parameters

Puntatore a una struttura o a un valore che contiene informazioni correlate al ControlType o NULL se il tipo di controllo non usa una struttura. Tutte le strutture sono allocate dal chiamante. Per informazioni dettagliate, vedere SCSI_ADAPTER_CONTROL_TYPE .

Valore restituito

A seconda del tipo di controllo, HwStorAdapterControl restituisce uno dei valori di SCSI_ADAPTER_CONTROL_STATUS seguenti:

Codice restituito	Descrizione
ScsiAdapterControlSuccesss	Il driver miniport ha completato correttamente l'operazione richiesta. Attualmente HwStorAdapterControl deve restituire questo valore per tutti i tipi di controllo.
SCSIAdapterControlUnsuccessful	L'operazione di controllo dell'adattatore non è riuscita.

Commenti

HwStorAdapterControl è una funzione obbligatoria.

Storport chiama HwStorAdapterControl di un miniport con un tipo di controllo SCSIQuerySupportedControlTypes dopo l'inizializzazione dell'HBA, ma prima del primo I/O. Il driver miniport riempie la struttura SCSI_SUPPORTED_CONTROL_TYPE_LIST in Parametri con le operazioni supportate. Dopo aver restituito HwStorAdapterControl da questa chiamata, il driver Storport chiama il callback HwStorAdapterControl del driver miniport solo per le operazioni supportate dal miniport.

Poiché i driver miniport che funzionano con il driver Storport devono supportare Plug and Play (PnP), i miniport devono supportare i tipi di controllo SCSIStopAdapter e SCSIRestartAdapter.

La tabella seguente elenca l'oggetto IRQL corrente e lo spinlock acquisito al momento dell'emissione del tipo di controllo.

Tipo di controllo	IRQL	Blocco di rotazione
SCSIQuerySupportedControlTypes	PASSIVE_LEVEL	Nessuno
SCSIStopAdapter	DIRQL	InterruptLock
SCSIRestartAdapter	DIRQL	InterruptLock
SCSISetBootConfig	PASSIVE_LEVEL	Nessuno
SCSISetRunningConfig	PASSIVE_LEVEL	Nessuno
SCSIPowerSettingNotification	PASSIVE_LEVEL	Nessuno
SCSIAdapterPower	<= DISPATCH_LEVEL	Nessuno
SCSIAdapterPoFxPowerRequired	<= DISPATCH_LEVEL	Nessuno
SCSIAdapterPoFxPowerActive	<= DISPATCH_LEVEL	Nessuno
SCSIAdapterPoFxPowerSetFState	<= DISPATCH_LEVEL	Nessuno
SCSIAdapterPoFxPowerControl	<= DISPATCH_LEVEL	Nessuno
ScsiAdapterPrepareForBusReScan	PASSIVE_LEVEL	Nessuno
SCSIAdapterSystemPowerHints	PASSIVE_LEVEL	Nessuno
SCSIAdapterFilterResourceRequirements	< DISPATCH_LEVEL	Nessuno
SCSIAdapterPoFxMaxOperationalPower	PASSIVE_LEVEL	Nessuno
SCSIAdapterPoFxSetPerfState	<= DISPATCH_LEVEL	Nessuno
ScsiAdapterSurpriseRemoval	< DISPATCH_LEVEL	Nessuno
SCSIAdapterSerialNumber	< DISPATCH_LEVEL	Nessuno
SCSIAdapterCryptoOperation	PASSIVE_LEVEL	Nessuno
SCSIAdapterQueryFruId	PASSIVE_LEVEL	Nessuno
SCSIAdapterSetEventLogging	PASSIVE_LEVEL	Nessuno

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

typedef
SCSI_ADAPTER_CONTROL_STATUS
HW_ADAPTER_CONTROL (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );

Esempio

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

HW_ADAPTER_CONTROL MyHwAdapterControl;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
SCSI_ADAPTER_CONTROL_STATUS
MyHwAdapterControl (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );
  {
      ...
  }

Il tipo di funzione HW_ADAPTER_CONTROL è 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_ADAPTER_CONTROL 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.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8
Piattaforma di destinazione	Universale
Intestazione	Storport.h (include Storport.h)
IRQL	Vedere la sezione Osservazioni.