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

Artículo
08/07/2023

El controlador storport llama a la rutina HwStorStartIo una vez para cada solicitud de E/S entrante.

Sintaxis

HW_STARTIO HwStartio;

BOOLEAN HwStartio(
  PVOID DeviceExtension,
  PSCSI_REQUEST_BLOCK Srb
)
{...}

Parámetros

DeviceExtension

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

Srb

Puntero al bloque de solicitud SCSI que se va a iniciar.

Valor devuelto

HwStorStartIo devuelve TRUE si la solicitud se inició correctamente. De lo contrario, devuelve FALSE.

Comentarios

HwStorStartIo inicia una operación de E/S. StorPort está diseñado para usar los datos privados de un miniport que se prepara en HwStorBuildIo y se almacena en DeviceExtension o Srb-SrbExtension>. Dado que se llama a HwStorBuildIo sin bloqueos de giro, el mejor rendimiento del controlador se logra preparando tantos datos como sea posible en HwStorBuildIo.

Storport llama a HwStorStartIo de las siguientes maneras:

En el caso de los controladores de miniport no virtuales de almacenamiento, según el valor de SynchronizationModel establecido en PORT_CONFIGURATION_INFORMATION, Storport siempre llama a HwStorStartIo en el mismo IRQL y usa un bloqueo de número interno para asegurarse de que las solicitudes de E/S se inician secuencialmente. IRQL es DISPATCH_LEVEL (modo dúplex completo) o DIRQL (modo dúplex medio).

Al controlar la E/S en modo dúplex medio, la rutina HwStorStartIo no tiene que adquirir su propio bloqueo de giro. Además, la asignación de memoria mediante StorPortAllocatePool y la exclusión mutua a través de StorPortAcquireSpinLock no se permiten en la rutina HwStorStartIo . En el modo dúplex completo, StorPortAllocatePool y StorPortAcquireSpinLock se pueden usar en la rutina HwStorStartIo .

Si un miniport no virtual admite la optimización de canales simultáneos (STOR_PERF_CONCURRENT_CHANNELS establecido por StorPortInitializePerfOpts), se pueden realizar varias llamadas a HwStorStartIo simultáneamente. En este caso, el miniporte deberá asegurarse de que los recursos compartidos estén protegidos por un bloqueo. Con esta optimización de rendimiento, Storport no adquirirá el bloqueo StartIo antes de llamar a HwStorStartIo y el miniport debe proporcionar su propio bloqueo si es necesario.
Para los controladores de miniport virtual de almacenamiento, Storport llama a HwStorStartIo en cualquier IRQL <= DISPATCH_LEVEL y no usa un bloqueo de número interno. La rutina HwStorStartIo puede adquirir su propio bloqueo de número llamando a StorPortAcquireSpinLock. Además, se permiten llamadas a StorPortAllocatePool en la rutina HwStorStartIo de un controlador de miniport virtual de almacenamiento.

Se espera que la SRB se complete cuando se reciba el estado SCSI. Cuando el controlador storport completa el SRB llamando a StorPortNotification con un NotificationType de RequestComplete, se espera que un SRB devuelva uno de los siguientes valores en el campo SrbStatus del Srb:

SRB_STATUS_SUCCESS
- Indica que se envió el Srb y se devolvió el estado SCSI (posiblemente con datos).
- Storport devuelve los datos y el estado al autor de la llamada.
- La acción Miniport no es ninguna, excepto para completar la solicitud mediante StorPortNotification para RequestComplete, probablemente de HwStorDpcRoutine.
SRB_STATUS_BUSY
- Indica que hay un problema temporal al enviar el Srb (por ejemplo, los registros del adaptador o los búferes están ocupados).
- Storport descarta la extensión Srb original a la que Srb-SrbExtension> apunta y emite una nueva. Storport envía el Srb original con la extensión Srb recién emitida en llamadas posteriores a HwStorBuildIo y HwStorStartIo. Se perderán todos los datos de la extensión Srb original.
- El minipuerto no debe actualizar el DataTransferLength de Srb.
- Dado que se emite una nueva extensión Srb, el miniporte debe asegurarse de que nunca emite SRB_STATUS_BUSY en medio de una transacción SCSI. Una vez iniciada la transacción, debe completarse o cancelarse. El controlador de minipuerto debe controlar los estados ocupados de hardware durante la transacción.

El nombre HwStorStartIo es un marcador de posición para describir la rutina de minipuerto establecida en el miembro HwStartIo de HW_INITIALIZATION_DATA estructura. Esta estructura se pasa en el parámetro HwInitializationData de StorPortInitialize. El prototipo real de esta rutina se define en Storport.h de la siguiente manera:

typedef
BOOLEAN
(*PHW_STARTIO) (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

A partir de Windows 8, el parámetro Srb puede apuntar a SCSI_REQUEST_BLOCK o STORAGE_REQUEST_BLOCK. Si el identificador de función del campo Función de Srb es SRB_FUNCTION_STORAGE_REQUEST_BLOCK, el SRB es una estructura de solicitud STORAGE_REQUEST_BLOCK .

Ejemplos

Para definir una rutina de devolución de llamada de HwStorStartIo , primero debe proporcionar una declaración de función que requieren el Comprobador de controladores estáticos (SDV) y otras herramientas de comprobación, como se muestra en el ejemplo de código siguiente:

Para definir una función de devolución de llamada HwStorStartIo , 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 HwStorStartIo denominada MyHwStartIo, use el tipo de HW_STARTIO e implemente la rutina de devolución de llamada de la siguiente manera:

HW_STARTIO MyHwStartIo

BOOLEAN
MyHwStartIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

El tipo de función HW_STARTIO 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 a la _Use_decl_annotations_ annotation definición de función. _Use_decl_annotations_ annotation garantiza que se usen las anotaciones aplicadas al tipo de función HW_STARTIO 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.