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

Artículo
02/07/2025

La rutina de 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 miniporte 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 miniport debe completar el SRB llamando a StorPortNotification con un tipo de notificación de RequestComplete. Esto se puede hacer en HwStorBuildIo o en otro lugar del controlador de miniporte, siempre y cuando se complete el SRB antes del tiempo de espera especificado en el campo TimeOutValue de la estructura SRB.

Observaciones

El nombre HwStorBuildIo es simplemente un marcador de posición para la función de miniportar 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 de HwStorBuildIo en DISPATCH IRQL sin contener ningún bloqueo de giro. Debido a esto, se permite la asignación de memoria mediante storPortAllocatePool y la exclusión mutua a través de 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 miniport es necesario para sincronizar el acceso a los recursos del sistema, que puede estar en contención si hay más de una instancia de HwStorBuildIo está 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 miniporte 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 miniporte realicen tantos procesos previos 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 producir modificaciones en partes únicas del DeviceExtension de, 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 solicitudes de lectura y escritura. Para acceder a los datos asociados, use storPortGetScatterGatherList (para transferencias Dma) o storPortGetSystemAddress (para E/S controladas 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 a Srb.
- Srb->PathId es válido y representa el pathid proporcionado a Storport en StorPortNotification (BusChange). Los escritores de controladores de miniportar deben usar pathid como índice en una tabla de autobuses dentro de la minipuerta.
- Srb->TargetId y Srb->Lun son válidos.
SRB_FUNCTION_IO_CONTROL: minipuerto 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 miniportar que vacíe todos los datos almacenados en caché.
- Solo lo realiza el controlador de miniport si establece CachesData == TRUE en la estructura de PORT_CONFIGURATION_INFORMATION.
- Srb->PathId, Srb->TargetId y Srb->Lun son válidos.
SRB_FUNCTION_SHUTDOWN: indica al controlador de miniportar que vacíe todos los datos almacenados en caché para apagarlos.
- Solo lo realiza el controlador de miniport si establece CachesData == TRUE en la estructura de 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 que no son miniport virtuales pueden recibir esta solicitud opcionalmente.
- 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 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 un HwStorBuildIo función de devolución de llamada, 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 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 de HwStorBuildIo denominada MyHwBuildIo, use el tipo HW_BUILDIO tal 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, vea Anotación del comportamiento de la función.