Condividi tramite


EVT_SERCX2_PIO_RECEIVE_READ_BUFFER funzione di callback (sercx.h)

La EvtSerCx2PioReceiveReadBuffer funzione di callback degli eventi viene chiamata dalla versione 2 dell'estensione del framework seriale (SerCx2) per usare 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.

Osservazioni

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

SerCx2 potrebbe chiamare la funzione EvtSerCx2PioReceiveReadBuffer più volte durante una transazione di ricezione PIO. Una singola EvtSerCx2PioReceiveReadBuffer chiamata è 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, man mano che 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 dal 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 il EvtSerCx2PioReceiveEnableReadyNotification funzione di callback degli eventi per abilitare una notifica pronta e questa funzione abilita un interrupt 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. Tuttavia, SerCx2 potrebbe 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.

Esempi

Per definire un EvtSerCx2PioReceiveReadBuffer funzione di callback, è 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 usando i tipi di funzione di callback consente di l'analisi del codice per i driver, del driver statico (SDV) e altri strumenti di verifica rilevano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire un EvtSerCx2PioReceiveReadBuffer funzione di callback denominata MyPioReceiveReadBuffer, usare il tipo di funzione EVT_SERCX2_PIO_RECEIVE_READ_BUFFER, come illustrato in questo esempio di codice:

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER  MyPioReceiveReadBuffer;

Implementare quindi la funzione di callback come segue:

_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 i tipi di ruolo della funzione per i driver KMDF. Per altre informazioni su Use_decl_annotations, vedere l'annotazione del comportamento della funzione.

Fabbisogno

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.

Vedere anche

EvtSerCx2PioReceiveCleanupTransaction

EvtSerCx2PioReceiveEnableReadyNotification

EvtSerCx2PioReceiveInitializeTransaction

SERCX2PIORECEIVE

SerCx2PioReceiveCreate