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

Artículo
02/26/2024

La rutina HwStorBuildIo procesa la SRB con acceso no asincrónico a estructuras de datos del sistema compartidas antes de pasarla a HwStorStartIo.

Sintaxis

HW_BUILDIO HwBuildio;

BOOLEAN HwBuildio(
  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 (SRB) que se va a procesar.

Valor devuelto

HwStorBuildIo devuelve TRUE para informar al autor de la llamada de que StorPort debe llamar a la rutina HwStorStartIo si StorPort considera que el LUN está listo para recibir E/S. HwStorBuildIo devuelve FALSE para informar al autor de la llamada de que el SRB no debe pasarse a HwStorStartIo. En tales casos, el controlador de minipuerto debe completar el SRB llamando a StorPortNotification con un tipo de notificación requestComplete. Esto se puede hacer en HwStorBuildIo o en otro lugar del controlador de minipuerto, siempre y cuando se complete el SRB antes del tiempo de espera especificado en el campo TimeOutValue de la estructura SRB.

Comentarios

El nombre HwStorBuildIo es simplemente un marcador de posición para la función de minipuerto a la que apunta el miembro HwBuildIo en la estructura HW_INITIALIZATION_DATA . El prototipo real de esta rutina se define en Storport.h de la siguiente manera:

typedef
BOOLEAN
HW_BUILDIO (
  _In_ PVOID DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

El controlador de puerto llama a la rutina HwStorBuildIo en DISPATCH IRQL sin mantener ningún bloqueo de giro. Por este motivo, se permite la asignación de memoria mediante StorPortAllocatePool y la exclusión mutua mediante StorPortAcquireSpinLock en HwStorBuildIo. En un entorno de varios procesadores, más de un HwStorBuildIo puede estar activo a la vez, por lo que el controlador de minipuerto es necesario para sincronizar el acceso a los recursos del sistema, lo que puede estar en contención si hay más de una instancia de HwStorBuildIo activa en un momento dado.

Al completar las actividades de configuración de E/S que consumen mucho tiempo en HwStorBuildIo en lugar de en HwStorStartIo, el controlador de minipuerto permite una mayor simultaneidad de E/S y, por tanto, mejora el rendimiento de E/S. Para obtener el máximo rendimiento, se espera que los controladores de minipuerto realicen tanto preprocesamiento como sea posible en HwStorBuildIo para que pueda enviar solicitudes al HBA a través de HwStorStartIo en la menor cantidad de tiempo posible. Los datos preprocesados y el estado se pueden almacenar en las estructuras DeviceExtension o SrbExtension . Solo se deben realizar modificaciones en partes únicas de DeviceExtension , ya que no se mantienen bloqueos. HwStorBuildIo y HwStorStartIo reciben los siguientes tipos de función Srb:

SRB_FUNCTION_EXECUTE_SCSI: envía un CDB al bus,destino/lun especificado.
- Srb-DataTransferLength> es válido para todos los cdbs.
- Srb-DataBuffer> es NULL para las solicitudes de lectura y escritura. Para acceder a los datos asociados, use StorPortGetScatterGatherList (para transferencias Dma) o StorPortGetSystemAddress (para E/S controlada por programa) para obtener la lista Recopilación de dispersión o la dirección virtual del búfer. Para otras solicitudes, Srb-Databuffer> apunta a los datos asociados con el Srb.
- Srb-PathId> es válido y representa el pathid proporcionado a Storport en StorPortNotification (BusChange). Los escritores de controladores de minipuerto deben usar pathid como índice en una tabla de autobuses dentro del miniporte.
- Srb-TargetId> y Srb-Lun> son válidos.
SRB_FUNCTION_IO_CONTROL: Miniport definido.
- Srb-DataTransferLength> y Srb-DataBuffer> son válidos si lo establece el solicitante.
- Srb-PathId>, Srb-TargetId> y Srb-Lun> son válidos.
SRB_FUNCTION_RESET_LOGICAL_UNIT: restablezca la unidad lógica especificada (si el dispositivo es capaz).
- Srb-DataTransferLength> y Srb-DataBuffer> no son válidos.
- Srb-PathId>, Srb-TargetId> y Srb-Lun> son válidos.
SRB_FUNCTION_RESET_DEVICE: restablezca el destino Scsi especificado.
- Srb-DataTransferLength> y Srb-DataBuffer>, Srb-Lun> no son válidos.
- Srb-PathId> y Srb-TargetId> son válidos.
SRB_FUNCTION_RESET_BUS: restablezca todos los destinos en el bus SCSI especificado.
- Solo Srb-PathId> es válido.
SRB_FUNCTION_FLUSH: indica al controlador de minipuerto que vacíe todos los datos almacenados en caché.
- Solo lo realiza el controlador de minipuerto si establece CachesData == TRUE en la estructura PORT_CONFIGURATION_INFORMATION .
- Srb-PathId>, Srb-TargetId> y Srb-Lun> son válidos.
SRB_FUNCTION_SHUTDOWN: indica al controlador de minipuerto que vacíe todos los datos almacenados en caché para apagarlos.
- Solo lo realiza el controlador de minipuerto si establece CachesData == TRUE en la estructura PORT_CONFIGURATION_INFORMATION .
- Srb-PathId>, Srb-TargetId> y Srb-Lun> son válidos.
SRB_FUNCTION_DUMP_POINTERS: proporciona información necesaria para que el controlador de miniporte admita el volcado de memoria y la hibernación.
- Esta solicitud se envía a un controlador de miniport virtual storport que se usa para controlar el disco que contiene los datos del volcado de memoria. A partir de Windows 8, los controladores de minipuerto no virtuales pueden recibir opcionalmente esta solicitud.
- Srb-PathId>, Srb-TargetId> y Srb-Lun> son válidos.
SRB_FUNCTION_FREE_DUMP_POINTERS: a partir de Windows 8, esta solicitud se envía al miniporte para liberar recursos asignados durante la solicitud de SRB_FUNCTION_DUMP_POINTERS.
- Srb-PathId>, Srb-TargetId> y Srb-Lun> son válidos.

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 .

Para obtener más información sobre lo que puede y no puede hacer de forma segura en esta rutina de controlador de minipuerto, vea Rutina HwStorBuildIo sin sincronizar.

Ejemplos

Para definir una función de devolución de llamada HwStorBuildIo , 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 Análisis de código para controladores, Comprobador de controladores estáticos (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 HwStorBuildIo denominada MyHwBuildIo, use el tipo HW_BUILDIO como se muestra en este ejemplo de código:

HW_BUILDIO MyHwBuildIo;

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

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

El tipo de función HW_BUILDIO 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_BUILDIO 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 rol de función para controladores de Storport. Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.