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

Artículo
03/05/2024

La minipuerto virtual storport usa la información de configuración proporcionada a la rutina de VIRTUAL_HW_FIND_ADAPTER para inicializarse aún más.

Sintaxis

VIRTUAL_HW_FIND_ADAPTER VirtualHwFindAdapter;

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

Parámetros

DeviceExtension

Puntero al área de almacenamiento no paginada del controlador de miniporte por adaptador. El controlador de puerto específico del sistema operativo asigna memoria para e inicializa esta extensión con ceros antes de llamar a la rutina de VIRTUAL_HW_FIND_ADAPTER de miniporte.

HwContext

Puntero al PDO en la pila de dispositivos. El propio HBA es el FDO. El PDO puede pertenecer al controlador de Pci.sys si el controlador de minipuerto controla el hardware físico. Pero en el caso de un controlador de minipuerto virtual, el PDO pertenece al administrador de PnP.

BusInformation

Puntero al objeto de dispositivo funcional (FDO) del miniporte.

LowerDevice

Puntero al objeto de dispositivo controlado por el FDO de la miniporte.

ArgumentString

Puntero a una cadena ASCII terminada en null. Esta cadena, si se proporciona, contiene información del dispositivo del registro, como un parámetro base.

ConfigInfo

Puntero a una estructura de PORT_CONFIGURATION_INFORMATION . El controlador de puerto inicializa esta estructura con cualquier información de configuración conocida, como valores que el controlador driverentry de miniporte establece en el VIRTUAL_HW_INITIALIZATION_DATA. VIRTUAL_HW_FIND_ADAPTER debe usar cualquier información proporcionada para determinar si el HBA virtual que describe es el que admite el controlador de miniporte. Si es así, VIRTUAL_HW_FIND_ADAPTER inicializa y configura ese HBA y rellena cualquier información de configuración que falte. Si es posible, un controlador de miniporte debe tener valores de configuración predeterminados para cada tipo de HBA que admita, en caso de que el controlador de puerto dependiente del sistema operativo no pueda proporcionar información de configuración adicional que no proporcionó la rutina DriverEntry del controlador de miniporte.

Again

No se usa.

Valor devuelto

VIRTUAL_HW_FIND_ADAPTER debe devolver uno de los siguientes valores de estado:

Código devuelto	Descripción
SP_RETURN_FOUND	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	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 ScsiPortLogError.
SP_RETURN_BAD_CONFIG	La información de configuración proporcionada no era válida para el adaptador.
SP_RETURN_NOT_FOUND	No se encontró ningún HBA compatible para la información de configuración proporcionada.

Comentarios

El campo VirtualDevice de la estructura de información de configuración debe establecerse en TRUE. Otros campos se pueden establecer según sea necesario.

El controlador de puerto llama al VIRTUAL_HW_FIND_ADAPTER del miniport virtual de Storport en PASSIVE_LEVEL.

El nombre VirtualHwStorFindAdapter es texto de marcador de posición para el nombre de rutina real. El prototipo real de esta rutina se define en Srb.h de la siguiente manera:

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

Ejemplos

Para definir una función de devolución de llamada VIRTUAL_HW_FIND_ADAPTER, primero debe proporcionar una declaración de función que identifique el tipo de función de devolución de llamada que va a definir. 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 de VIRTUAL_HW_FIND_ADAPTER denominada MyVirtualHwFindAdapter, use el tipo VIRTUAL_HW_FIND_ADAPTER como se muestra en este ejemplo de código:

VIRTUAL_HW_FIND_ADAPTER MyVirtualHwFindAdapter;

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

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

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