EVT_SERCX2_PIO_RECEIVE_READ_BUFFER función de devolución de llamada (sercx.h)

Artículo
10/30/2024

La función de devolución de llamada de eventos EvtSerCx2PioReceiveReadBu ffer se llama mediante la versión 2 de la extensión del marco de serie (SerCx2) para usar E/S programada (PIO) para transferir datos de la recepción FIFO en el controlador serie a un búfer de lectura.

Sintaxis

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER EvtSercx2PioReceiveReadBuffer;

ULONG EvtSercx2PioReceiveReadBuffer(
  [in]  SERCX2PIORECEIVE PioReceive,
  [out] PUCHAR Buffer,
  [in]  ULONG Length
)
{...}

Parámetros

[in] PioReceive

Identificador de SERCX2PIORECEIVE a un objeto pio-receive. El controlador de controlador serie llamó anteriormente al método SerCx2PioReceiveCreate para crear este objeto.

[out] Buffer

Puntero al búfer de lectura. Este parámetro es la dirección virtual de un búfer bloqueado en la memoria del sistema.

[in] Length

Número de bytes del búfer de lectura que están disponibles para almacenar los datos recibidos.

Valor devuelto

La función EvtSerCx2PioReceiveReadBuffer devuelve el número de bytes de datos que transfirió correctamente desde el FIFO de recepción en el hardware del controlador serie al búfer de lectura.

Observaciones

El controlador de controlador serie debe implementar esta función. El controlador registra la función en la llamada SerCx2PioReceiveCreate que crea el objeto PIO-receive.

SerCx2 podría llamar a la función EvtSerCx2PioReceiveReadBu ffer más de una vez durante una transacción de recepción de PIO. Una sola llamada EvtSerCx2PioReceiveReadBuffer es suficiente si esta llamada puede rellenar el búfer de lectura con datos del FIFO de recepción. De lo contrario, SerCx2 sigue llamando a esta función, a medida que haya más datos disponibles en el FIFO de recepción, hasta que se rellene el búfer de lectura.

La función EvtSerCx2PioReceiveReadBu ffer usa PIO para transferir tantos bytes como pueda desde el FIFO de recepción al búfer de lectura. La función continúa transfiriendo datos de FIFO siempre que el búfer pasado a esta función no esté lleno y el registro de estado de línea (LSR) indica que hay más datos disponibles en el FIFO. Si el LSR indica que el FIFO está vacío, la función devuelve sin rellenar el búfer. De lo contrario, la función rellena el búfer y devuelve. En cualquier caso, el valor devuelto por esta función es el número de bytes de datos que se transfirieron correctamente al búfer de lectura desde el FIFO de recepción.

Normalmente, la función EvtSerCx2PioReceiveReadBuffer no habilita ninguna interrupción. En su lugar, si el FIFO de recepción se queda sin datos antes de que la función pueda rellenar el búfer de lectura, SerCx2 llama a la EvtSerCx2PioReceiveEnableReadyNotification función de devolución de llamada de eventos para habilitar una notificación lista y esta función habilita una interrupción que se produce cuando hay más datos disponibles en el FIFO de recepción.

Para cada llamada sucesiva a la función EvtSerCx2PioReceiveReadBuffer, SerCx2 ajusta Buffer para apuntar a la siguiente región del búfer que se va a rellenar y establece Longitud al número de bytes de espacio no rellenado que permanecen en el búfer.

La notificación lista nunca está habilitada cuando SerCx2 llama a la función EvtSerCx2PioReceiveEnableReadyNotification. Sin embargo, SerCx2 podría llamar a esta función desde el mismo subproceso desde el que el controlador llamó al método SerCx2PioReceiveReady.

Si el controlador implementa una función EvtSerCx2PioReceiveInitializeTransaction, SerCx2 llama a esta función al principio de una transacción pio-transmit, antes de la primera llamada a la función EvtSerCx2PioReceiveReadBuffer. Si el controlador implementa una función EvtSerCx2PioReceiveCleanupTransaction, SerCx2 llama a esta función al final de una transacción de recepción de PIO, después de la llamada final a la función EvtSerCx2PioReceiveReadBuffer.

Además de llamar a la función EvtSerCx2PioReceiveReadBuffer durante las transacciones de recepción de PIO, SerCx2 llama a esta función para guardar el estado del FIFO de recepción justo antes de que el controlador serie salga del estado de alimentación del dispositivo D0. Para obtener más información, vea SerCx2SaveReceiveFifoOnD0Exit.

Para obtener más información sobre las transacciones de recepción de PIO, consulte SerCx2 PIO-Receive Transactions.

Ejemplos

Para definir un EvtSerCx2PioReceiveReadBuffer 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 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 un EvtSerCx2PioReceiveReadBuffer función de devolución de llamada denominada MyPioReceiveReadBuffer, use el tipo de función EVT_SERCX2_PIO_RECEIVE_READ_BUFFER, como se muestra en este ejemplo de código:

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER  MyPioReceiveReadBuffer;

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

_Use_decl_annotations_
ULONG
  MyPioReceiveReadBuffer(
    SERCX2PIORECEIVE  PioReceive,
    PUCHAR  Buffer,
    ULONG  Length

    )
  {...}

El tipo de función EVT_SERCX2_PIO_RECEIVE_READ_BUFFER se define en el archivo de encabezado Sercx.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_SERCX2_PIO_RECEIVE_READ_BUFFER 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 kmDF. Para obtener más información sobre Use_decl_annotations, vea Anotación del comportamiento de la función.

Requisitos

Requisito	Valor
cliente mínimo admitido	Disponible a partir de Windows 8.1.
de la plataforma de destino de	Escritorio
encabezado de	sercx.h
irQL	Se llama a irQL <= DISPATCH_LEVEL.