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

Artículo
02/26/2024

La rutina HwStorFindAdapter usa la configuración proporcionada para determinar si se admite un HBA específico y, si es así, devolver información de configuración sobre ese adaptador.

Sintaxis

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
)
{...}

Parámetros

DeviceExtension

Proporciona un área de almacenamiento por adaptador.

[in] HwContext

Definición en NULL

[in] BusInformation

Definición en NULL

[in] ArgumentString

Proporciona una cadena terminada en NULL con información de contexto sobre el controlador.

[in/out] ConfigInfo

Proporciona una estructura de PORT_CONFIGURATION_INFORMATION inicializada que usa el controlador de minipuerto durante la inicialización.

[in] Reserved3

Reservado para uso del sistema.

Valor devuelto

HwStorFindAdapter debe devolver uno de los siguientes valores de estado:

Código devuelto	Descripción
SP_RETURN_FOUND	Indica que se encontró un HBA compatible y que la información de configuración pertinente para HBA se determinó correctamente y se estableció en la estructura de PORT_CONFIGURATION_INFORMATION .
SP_RETURN_ERROR	Indica que se encontró un HBA, pero se produjo un error al obtener la información de configuración. Si es posible, este error debe registrarse con StorPortLogError.
SP_RETURN_BAD_CONFIG	Indica que la información de configuración proporcionada no era válida para el adaptador.
SP_RETURN_NOT_FOUND	Indica que no se encontró ningún HBA compatible para la información de configuración proporcionada.

Comentarios

Dado que el controlador storport solo admite dispositivos Plug and Play (PnP), los parámetros HwContext y BusInformation a HwStorFindAdapter no se proporcionan a controladores de miniport no virtuales.

HwStorFindAdapter debe establecer los campos MaximumTransferLength y NumberOfPhysicalBreaks en la estructura ConfigInfo . Aparte de estos campos, la estructura de PORT_CONFIGURATION_INFORMATION siempre especificará completamente todos los recursos del adaptador necesarios para iniciar el adaptador.

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

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
  );

En la mayoría de los casos, StorPort llama a la rutina HwStorFindAdapter en IRQL == PASSIVE_LEVEL sin adquirir ningún bloqueo de giro. El caso de excepción es cuando el miniport no admite llamar a HwStorAdaptorControl con el tipo de control ScsiRestartAdapter . En esta situación, StorPort reinicializará el adaptador llamando a HwStorFindAdapter y HwStorInitialize. Cuando este es el caso, se llama a HwStorFindAdapter en IRQL == DISPATCH_LEVEL. Además, cuando está en modo de volcado, se llama a HwStorFindAdapter en IRQL == HIGH_LEVEL.

Ejemplos

Para definir una función de devolución de llamada HwStorFindAdapter , 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 HwStorFindAdapter denominada MyHwFindAdapter, use el tipo de HW_FIND_ADAPTER como se muestra en este ejemplo de código:

HW_FIND_ADAPTER MyHwFindAdapter;

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

_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
  );
  {
      ...
  }

El tipo de función HW_FIND_ADAPTER 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_FIND_ADAPTER 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.