EVT_SPB_CONTROLLER_SEQUENCE función de devolución de llamada (spbcx.h)
Una función de devolución de llamada de eventos EvtSpbControllerIoSequence del controlador SPB realiza una secuencia de transferencias de datos entre el dispositivo de destino especificado y los búferes que se proporcionan con la solicitud de secuencia.
Sintaxis
EVT_SPB_CONTROLLER_SEQUENCE EvtSpbControllerSequence;
void EvtSpbControllerSequence(
[in] WDFDEVICE Controller,
[in] SPBTARGET Target,
[in] SPBREQUEST Request,
[in] ULONG TransferCount
)
{...}
Parámetros
[in] Controller
Un controlador WDFDEVICE para el objeto de dispositivo de marco que representa el controlador SPB.
[in] Target
Identificador SPBTARGET para el destino de esta solicitud de E/S. El destino es un dispositivo periférico o puerto que está conectado al bus. La extensión del marco spB (SpbCx) asignó previamente este identificador al destino en la devolución de llamada EvtSpbTargetConnect que abrió la conexión al destino.
[in] Request
Identificador SPBREQUEST de la solicitud de E/S. El controlador del controlador SPB debe completar esta solicitud realizando la operación solicitada o devolviendo un estado de error. Para obtener más información, vea Comentarios.
[in] TransferCount
Número de transferencias individuales en esta secuencia de transferencia de E/S. Cada transferencia individual es una operación simple de lectura o escritura.
Valor devuelto
None
Observaciones
SpbCx administra la cola de E/S para el controlador SPB. SpbCx llama a la función de devolución de llamada EvtSpbControllerIoSequence del controlador SPB cuando un cliente (controlador periférico) del controlador SPB envía una solicitud de IOCTL_SPB_EXECUTE_SEQUENCE a un dispositivo de destino conectado al bus. El valor del parámetro Request es un identificador que encapsula esta solicitud.
Una devolución de llamada EvtSpbControllerIoSequence no devuelve un valor de estado. En su lugar, el controlador del controlador SPB indica el estado de la operación de secuencia en el estado de finalización de la solicitud de E/S.
Una devolución de llamada EvtSpbControllerIoSequence es asincrónica. Es decir, la función de devolución de llamada debe iniciar la secuencia solicitada (o la primera parte de la secuencia) y, a continuación, volver sin esperar a que se complete la operación. Más adelante, el controlador del controlador SPB continúa procesando la solicitud o lo completa durante las DPC de interrupción o los DPC del temporizador.
El controlador del controlador SPB puede recuperar los valores de parámetro de la solicitud de E/S para determinar la longitud máxima de las transferencias dentro de la secuencia. El controlador puede usar esta longitud para asignar recursos DMA que puede reutilizar para cada transferencia dentro de la secuencia.
El controlador del controlador SPB puede llamar al método SpbRequestGetTransferParameters para recuperar los parámetros de control y el búfer de datos para cada transferencia de la secuencia. El búfer es un objeto WDFMEMORY que, en la implementación actual, encapsula un MDL encadenado. Para obtener más información sobre los MDL encadenados, consulte Uso de MDL.
El controlador SPB debe mantener seleccionado el dispositivo de destino para toda la operación de secuencia. Si el destino se selecciona mediante una línea de selección de dispositivo, la línea se puede afirmar continuamente desde el inicio de la primera transferencia de la secuencia hasta que finaliza la última transferencia. Esta línea se puede declarar tan pronto como la operación de bloqueo al principio de la secuencia y puede permanecer aserida hasta que la operación de desbloqueo al final de la secuencia.
Se puede especificar un retraso opcional para cada transferencia en una secuencia. El controlador del controlador SPB es responsable de retrasar al menos ese número de microsegundos antes de iniciar la transferencia. Si la primera transferencia de la secuencia tiene un retraso asociado, el controlador debe transmitir primero la dirección o declarar la línea de selección de dispositivo del dispositivo de destino y, a continuación, retrasar la hora especificada antes de iniciar la transferencia de datos. Durante este retraso, el destino debe permanecer seleccionado, pero el controlador no debe ejecutar el reloj en el bus.
Si el dispositivo de destino señala una NACK durante una transferencia en una secuencia, el controlador SPB detiene la secuencia. (Es decir, el controlador no vuelve a intentar la transferencia con errores y no intenta realizar las transferencias restantes en la secuencia). Si esto ocurre, el controlador del controlador SPB debe establecer el estado de finalización de la solicitud de E/S en STATUS_SUCCESS, establezca el campo Información en el bloque de estado de E/S en el número de bytes transferidos realmente (sin contar los datos perdidos en la transferencia que recibió la NACK) y complete la solicitud.
El controlador del controlador SPB debe completar la solicitud de E/S con un código de estado de error solo si se produce una de las condiciones siguientes:
- El controlador SPB no puede seleccionar el dispositivo de destino (por ejemplo, un dispositivo de destino en un bus I2C señala una NACK cuando el controlador transmite el byte de dirección).
- El controlador del controlador SPB obtiene un estado de error de una llamada a un servicio WDF o WDM al procesar la operación de secuencia.
Para registrar una función de devolución de llamada EvtSpbControllerIoSequence , llame al método SpbDeviceInitialize .
Ejemplos
Para definir una función de devolución de llamada EvtSpbControllerIoSequence , 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 función de devolución de llamada EvtSpbControllerIoSequence denominada MyEvtSpbControllerIoSequence, use el tipo de función EVT_SPB_CONTROLLER_SEQUENCE, como se muestra en este ejemplo de código:
EVT_SPB_CONTROLLER_SEQUENCE MyEvtSpbControllerIoSequence;
A continuación, implemente la función de devolución de llamada de la siguiente manera:
_Use_decl_annotations_
VOID
MyEvtSpbControllerIoSequence(
WDFDEVICE Controller,
SPBTARGET Target,
SPBREQUEST Request,
ULONG TransferCount
)
{ ... }
El tipo de función EVT_SPB_CONTROLLER_SEQUENCE se define en el archivo de encabezado Spbcx.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 EVT_SPB_CONTROLLER_SEQUENCE del 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 KMDF. Para obtener más información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Se admite a partir de Windows 8. |
| Plataforma de destino | Escritorio |
| Encabezado | spbcx.h |
| IRQL | Se llama en IRQL <= DISPATCH_LEVEL. |