Condividi tramite

Transazioni Custom-Receive SerCx2

  • Articolo

Alcuni hardware del controller seriale possono implementare un meccanismo di trasferimento dei dati diverso da PIO o DMA di sistema per la lettura dei dati da un controller seriale. Un driver controller seriale può supportare transazioni di ricezione personalizzate per rendere disponibile questo meccanismo di trasferimento dati da usare da SerCx2.

Per avviare una transazione di ricezione personalizzata, SerCx2 chiama la funzione di callback dell'evento EvtSerCx2CustomReceiveTransactionStart e fornisce come parametri la richiesta di lettura (IRP_MJ_READ) e una descrizione del buffer di lettura per la transazione. In questa chiamata, la funzione avvia la transazione e restituisce . Il driver è quindi responsabile del completamento della transazione e del completamento della richiesta di lettura.

Creazione dell'oggetto receive personalizzato

Prima che SerCx2 possa chiamare una qualsiasi delle funzioni EvtSerCx2CustomReceiveTransactionXxx**, il driver deve chiamare il metodo SerCx2CustomReceiveTransactionCreate per registrare queste funzioni con SerCx2. Questo metodo accetta, come parametro di input, un puntatore a una struttura SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG che contiene puntatori alle funzioni EvtSerCx2CustomReceiveTransactionXxx** del driver.

Il driver deve implementare le due funzioni seguenti:

Come opzione, il driver può implementare una o tutte le tre funzioni seguenti:

Il metodo SerCx2CustomReceiveTransactionCreate crea un oggetto di ricezione personalizzato e fornisce al driver chiamante un handle SERCX2CUSTOMRECEIVETRANSACTION per questo oggetto. Le funzioni EvtSerCx2CustomReceiveTransactionXxx** del driver accettano tutti questo handle come primo parametro. I metodi SerCx2 seguenti accettano questo handle come primo parametro:

Inizializzazione e pulizia dell'hardware

Alcuni driver del controller seriale potrebbero dover inizializzare l'hardware del controller seriale all'inizio di una transazione di ricezione personalizzata o per pulire lo stato hardware del controller seriale alla fine della transazione.

Se un driver implementa una funzione di callback degli eventi EvtSerCx2CustomReceiveTransactionInitialize , SerCx2 chiama questa funzione per inizializzare il controller seriale prima di avviare la transazione. Se implementato, la funzione EvtSerCx2CustomReceiveTransactionInitialize deve chiamare il metodo SerCx2CustomReceiveTransactionInitializeComplete per informare SerCx2 al termine dell'inizializzazione del controller seriale.

Se il driver implementa una funzione di callback dell'evento EvtSerCx2CustomReceiveTransactionCleanup , SerCx2 chiama questa funzione per pulire lo stato hardware al termine della transazione. Se implementato, la funzione EvtSerCx2CustomReceiveTransactionInitialize deve chiamare il metodo SerCx2CustomReceiveTransactionCleanupComplete per informare SerCx2 al termine della pulizia del controller seriale.

Notifiche di nuovi dati

Come opzione, il driver del controller seriale può implementare una funzione di callback dell'evento EvtSerCx2CustomReceiveTransactionEnableNewDataNotification . Se implementato, SerCx2 usa questa funzione per gestire in modo efficiente i timeout degli intervalli che si verificano durante la gestione delle richieste di lettura elaborate come transazioni di ricezione personalizzate.

Un timeout di intervallo si verifica se l'intervallo tra due byte successivi ricevuti dal controller seriale supera il tempo massimo specificato dal client. Dopo che un driver periferico invia una richiesta di lettura a SerCx2, un timeout di intervallo non può verificarsi fino a quando non viene ricevuto almeno un byte di dati dal dispositivo periferico connesso in modo seriale. L'ora tra l'arrivo di una richiesta di lettura e la ricezione del primo byte di dati dal dispositivo periferico potrebbe essere significativamente superiore al tempo necessario per ricevere il resto dei dati per la richiesta di lettura dopo la ricezione del primo byte. Per altre informazioni, vedere SERIAL_TIMEOUTS.

SerCx2 chiama la funzione EvtSerCx2CustomReceiveTransactionEnableNewDataNotification, se implementata , per abilitare una notifica di nuovi dati. Se questa notifica è abilitata e il controller seriale riceve uno o più byte di nuovi dati dal dispositivo periferico o ha già dati nella ricezione FIFO, il driver del controller seriale deve chiamare il metodo SerCx2CustomReceiveTransactionNewDataNotification per notificare a SerCx2.

Per rilevare un possibile timeout dell'intervallo, SerCx2 chiama periodicamente la funzione di callback dell'evento EvtSerCx2CustomReceiveTransactionQueryProgress per verificare se sono stati ricevuti dati durante l'intervallo precedente. Il modo in cui SerCx2 rileva la ricezione del primo byte di dati dipende dal fatto che il driver del controller seriale implementi una funzione EvtSerCx2CustomReceiveTransactionEnableNewDataNotification . Se questa funzione viene implementata, SerCx2 chiama la funzione per abilitare una notifica di nuovi dati e riceve una notifica dal driver quando viene ricevuto il primo byte di dati. In caso contrario, SerCx2 chiama periodicamente la funzione EvtSerCx2CustomReceiveTransactionQueryProgress per rilevare la ricezione del primo byte e potrebbe essere necessario riattivare periodicamente il processore per effettuare queste chiamate. Pertanto, un driver che implementa una funzione EvtSerCx2CustomReceiveTransactionEnableNewDataNotification può ridurre il consumo di energia non richiedendo la riattivazione del processore come spesso.

SerCx2 non annulla in modo esplicito una notifica di nuovi dati in sospeso per una transazione di ricezione personalizzata. Tuttavia, il driver del controller seriale potrebbe dover annullare in modo implicito una notifica di nuovi dati se la notifica è abilitata e il driver deve completare la richiesta di lettura associata per uno dei motivi seguenti:

  • Timeout della richiesta di lettura o annullamento.
  • Il controller seriale sta per uscire dallo stato di alimentazione del dispositivo D0 per entrare in uno stato a basso consumo.

Il driver chiama in genere un metodo come WdfRequestComplete per completare la richiesta. Il driver non deve mai chiamare SerCx2CustomReceiveTransactionNewDataNotification dopo il completamento della richiesta.

Accesso all'oggetto richiesta

Per avviare una transazione di ricezione personalizzata, SerCx2 chiama la funzione EvtSerCx2CustomReceiveTransactionStart associata e passa la richiesta di lettura associata (incapsulata in un handle di oggetto WDFREQUEST) a questa funzione come parametro. Il driver è responsabile della chiamata di un metodo, ad esempio WdfRequestComplete , per completare la richiesta al termine della transazione. A meno che la richiesta non possa essere completata immediatamente, prima che la funzione EvtSerCx2CustomReceiveTransactionStart restituisca un risultato, il driver deve chiamare un metodo come WdfRequestMarkCancelableEx per contrassegnare la richiesta come annullabile.

Il driver del controller seriale non deve usare un metodo come WdfRequestRetrieveOutputBuffer per accedere al buffer dei dati nella richiesta di lettura. Al contrario, il driver deve usare i valori dei parametri Mdl, Offset e Length passati alla funzione EvtSerCx2CustomReceiveTransactionStart per accedere a questo buffer.

Durante una transazione di ricezione personalizzata, il driver potrebbe dover archiviare informazioni sulla transazione in un contesto associato all'oggetto richiesta. In tal caso, la funzione di callback dell'evento EvtDriverDeviceAdd del driver può chiamare il metodo WdfDeviceInitSetRequestAttributes per impostare gli attributi da usare per gli oggetti richiesta. Questi attributi includono il nome e le dimensioni di allocazione da usare per i contesti di richiesta. Gli attributi della richiesta specificati in questa chiamata devono corrispondere agli attributi della richiesta specificati dal driver nella chiamata al metodo SerCx2InitializeDevice . Questi attributi vengono specificati nel membro RequestAttributes della struttura SERCX2_CONFIG che il driver passa a SerCx2InitializeDevice. Per altre informazioni, vedere SERCX2_CONFIG.

Per una richiesta di lettura ricevuta dal driver del controller seriale all'inizio di una transazione di ricezione personalizzata, il contesto della richiesta allocato dal framework driver non è inizializzato. Il driver deve, come procedura consigliata, chiamare la routine RtlZeroMemory per inizializzare il contesto della richiesta a tutti gli zeri.