EVT_SERCX2_PIO_RECEIVE_READ_BUFFER funzione di callback (sercx.h)

Articolo
08/07/2023

La funzione di callback dell'evento EvtSerCx2PioReceiveReadBuffer viene chiamata dalla versione 2 dell'estensione del framework seriale (SerCx2) per l'uso di operazioni di I/O programmate per trasferire i dati dalla ricezione FIFO nel controller seriale a un buffer di lettura.

Sintassi

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER EvtSercx2PioReceiveReadBuffer;

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

Parametri

[in] PioReceive

Handle SERCX2PIORECEIVE a un oggetto di ricezione PIO. Il driver del controller seriale precedentemente denominato metodo SerCx2PioReceiveCreate per creare questo oggetto.

[out] Buffer

Puntatore al buffer di lettura. Questo parametro è l'indirizzo virtuale di un buffer bloccato nella memoria di sistema.

[in] Length

Numero di byte nel buffer di lettura disponibili per archiviare i dati ricevuti.

Valore restituito

La funzione EvtSerCx2PioReceiveReadBuffer restituisce il numero di byte di dati trasferiti correttamente dalla ricezione FIFO nell'hardware del controller seriale al buffer di lettura.

Commenti

Il driver del controller seriale deve implementare questa funzione. Il driver registra la funzione nella chiamata SerCx2PioReceiveCreate che crea l'oggetto PIO-receive.

SerCx2 potrebbe chiamare la funzione EvtSerCx2PioReceiveReadBuffer più volte durante una transazione di ricezione PIO. Una singola chiamata EvtSerCx2PioReceiveReadBuffer è sufficiente se questa chiamata può riempire il buffer di lettura con i dati della ricezione FIFO. In caso contrario, SerCx2 continua a chiamare questa funzione, poiché nella ricezione FIFO diventano disponibili più dati, fino a quando il buffer di lettura non viene riempito.

La funzione EvtSerCx2PioReceiveReadBuffer usa PIO per trasferire il numero di byte possibile dalla ricezione FIFO al buffer di lettura. La funzione continua a trasferire i dati da FIFO finché il buffer passato a questa funzione non è pieno e il registro di stato della riga (LSR) indica che sono disponibili più dati da FIFO. Se l'LSR indica che fifo è vuoto, la funzione restituisce senza riempire il buffer. In caso contrario, la funzione riempie il buffer e restituisce. In entrambi i casi, il valore restituito da questa funzione è il numero di byte di dati trasferiti correttamente al buffer di lettura dalla ricezione FIFO.

In genere, la funzione EvtSerCx2PioReceiveReadBuffer non abilita interruzioni. Se invece la ricezione FIFO esaurisce i dati prima che la funzione possa riempire il buffer di lettura, SerCx2 chiama la funzione di callback dell'evento EvtSerCx2PioReceiveEnableReadyNotification per abilitare una notifica pronta e questa funzione abilita un'interruzione che si verifica quando sono disponibili altri dati nella ricezione FIFO.

Per ogni chiamata successiva alla funzione EvtSerCx2PioReceiveReadBuffer , SerCx2 regola Buffer in modo che punti all'area del buffer successiva da riempire e imposta Length sul numero di byte di spazio non riempito che rimangono nel buffer.

La notifica pronta non viene mai abilitata quando SerCx2 chiama la funzione EvtSerCx2PioReceiveEnableReadyNotification . SerCx2 potrebbe tuttavia chiamare questa funzione dallo stesso thread da cui il driver ha chiamato il metodo SerCx2PioReceiveReady .

Se il driver implementa una funzione EvtSerCx2PioReceiveInitializeTransaction , SerCx2 chiama questa funzione all'inizio di una transazione di trasmissione PIO, prima della prima chiamata alla funzione EvtSerCx2PioReceiveReadBuffer . Se il driver implementa una funzione EvtSerCx2PioReceiveCleanupTransaction , SerCx2 chiama questa funzione alla fine di una transazione di ricezione PIO, dopo la chiamata finale alla funzione EvtSerCx2PioReceiveReadBuffer .

Oltre a chiamare la funzione EvtSerCx2PioReceiveReadBuffer durante le transazioni di ricezione PIO, SerCx2 chiama questa funzione per salvare lo stato della ricezione FIFO appena prima che il controller seriale esca dallo stato di alimentazione del dispositivo D0. Per altre informazioni, vedere SerCx2SaveReceiveFifoOnD0Exit.

Per altre informazioni sulle transazioni di ricezione PIO, vedere SerCx2 PIO-Receive Transactions.

Esempio

Per definire una funzione di callback EvtSerCx2PioReceiveReadBuffer , è prima necessario fornire una dichiarazione di funzione che identifica il tipo di funzione di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una funzione di callback EvtSerCx2PioReceiveReadBuffer denominata MyPioReceiveReadBuffer, usare il tipo di funzione EVT_SERCX2_PIO_RECEIVE_READ_BUFFER , come illustrato nell'esempio di codice seguente:

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER  MyPioReceiveReadBuffer;

Implementare quindi la funzione di callback come indicato di seguito:

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

    )
  {...}

Il tipo di funzione EVT_SERCX2_PIO_RECEIVE_READ_BUFFER è definito nel file di intestazione Sercx.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations assicura che vengano utilizzate le annotazioni applicate al tipo di funzione EVT_SERCX2_PIO_RECEIVE_READ_BUFFER nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver KMDF. Per altre informazioni sulle Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 8.1.
Piattaforma di destinazione	Desktop
Intestazione	sercx.h
IRQL	Chiamato in IRQL <= DISPATCH_LEVEL.