HW_ADAPTER_CONTROL función de devolución de llamada (storport.h)

Artículo
08/07/2023

Se llama a la rutina HwStorAdapterControl de un controlador de miniporte para realizar operaciones sincrónicas para controlar el estado o el comportamiento de un adaptador, como detener o reiniciar el adaptador de bus host (HBA) para la administración de energía.

Sintaxis

HW_ADAPTER_CONTROL HwAdapterControl;

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

Parámetros

[in] DeviceExtension

Puntero al área de almacenamiento por HBA del controlador de minipuerto.

[in] ControlType

Valor de SCSI_ADAPTER_CONTROL_TYPE que especifica una operación de control de adaptador, donde cada tipo de control inicia una acción mediante el controlador de minipuerto. Consulte SCSI_ADAPTER_CONTROL_TYPE para obtener más información.

[in] Parameters

Puntero a una estructura o valor que contiene información relacionada con controlType o NULL si el tipo de control no usa una estructura. Todas las estructuras están asignadas por el autor de la llamada. Consulte SCSI_ADAPTER_CONTROL_TYPE para obtener más información.

Valor devuelto

Según el tipo de control, HwStorAdapterControl devuelve uno de los siguientes valores de SCSI_ADAPTER_CONTROL_STATUS:

Código devuelto	Descripción
ScsiAdapterControlSuccess	El controlador de minipuerto completó correctamente la operación solicitada. Actualmente, HwStorAdapterControl debe devolver este valor para todos los tipos de control.
ScsiAdapterControlUnsuccessful	La operación de control del adaptador no se realizó correctamente.

Comentarios

HwStorAdapterControl es una función necesaria.

Storport llama al HwStorAdapterControl de un miniporte con un tipo de control ScsiQuerySupportedControlTypes después de inicializar el HBA, pero antes de la primera E/S. El controlador de minipuerto rellena la estructura SCSI_SUPPORTED_CONTROL_TYPE_LIST en Parámetros con las operaciones que admite. Después de que HwStorAdapterControl vuelva de esta llamada, el controlador storport llama a la devolución de llamada HwStorAdapterControl del controlador de miniport solo para las operaciones admitidas por el miniport.

Dado que los controladores de minipuerto que funcionan con el controlador storport deben admitir Plug and Play (PnP), los miniportes deben admitir los tipos de control ScsiStopAdapter y ScsiRestartAdapter.

En la tabla siguiente se enumeran los IRQL actuales y el bloqueo por subproceso adquirido cuando se emite el tipo de control.

Tipo de control	IRQL	Bloqueo de número
ScsiQuerySupportedControlTypes	PASSIVE_LEVEL	None
ScsiStopAdapter	DIRQL	InterruptLock
ScsiRestartAdapter	DIRQL	InterruptLock
ScsiSetBootConfig	PASSIVE_LEVEL	None
ScsiSetRunningConfig	PASSIVE_LEVEL	None
ScsiPowerSettingNotification	PASSIVE_LEVEL	None
ScsiAdapterPower	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerRequired	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerActive	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerSetFState	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerControl	<= DISPATCH_LEVEL	None
ScsiAdapterPrepareForBusReScan	PASSIVE_LEVEL	None
ScsiAdapterSystemPowerHints	PASSIVE_LEVEL	None
ScsiAdapterFilterResourceRequirements	< DISPATCH_LEVEL	None
ScsiAdapterPoFxMaxOperationalPower	PASSIVE_LEVEL	None
ScsiAdapterPoFxSetPerfState	<= DISPATCH_LEVEL	None
ScsiAdapterSurpriseRemoval	< DISPATCH_LEVEL	None
ScsiAdapterSerialNumber	< DISPATCH_LEVEL	None
ScsiAdapterCryptoOperation	PASSIVE_LEVEL	None
ScsiAdapterQueryFruId	PASSIVE_LEVEL	None
ScsiAdapterSetEventLogging	PASSIVE_LEVEL	None

El nombre HwStorAdapterControl es simplemente un marcador de posición. El prototipo real de esta rutina se define en storport.h de la siguiente manera:

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

Ejemplos

Para definir una función de devolución de llamada HwStorAdapterControl , primero debe proporcionar una declaración de función que identifique el tipo de función de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una rutina de devolución de llamada HwStorAdapterControl denominada MyHwAdapterControl, use el tipo de HW_ADAPTER_CONTROL como se muestra en este ejemplo de código:

HW_ADAPTER_CONTROL MyHwAdapterControl;

A continuación, implemente la rutina de devolución de llamada de la siguiente manera:

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

El tipo de función HW_ADAPTER_CONTROL se define en el archivo de encabezado Storport.h . Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función HW_ADAPTER_CONTROL en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante tipos de roles de función para controladores storport. Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8
Plataforma de destino	Universal
Encabezado	storport.h (incluya Storport.h)
IRQL	Vea la sección Comentarios.