EVT_SPB_CONTROLLER_SEQUENCE funzione di callback (spbcx.h)

  • Articolo

La funzione di callback dell'evento EvtSpbControllerIoSequence di un driver del controller SPB esegue una sequenza di trasferimenti di dati tra il dispositivo di destinazione specificato e i buffer forniti con la richiesta di sequenza.

Sintassi

EVT_SPB_CONTROLLER_SEQUENCE EvtSpbControllerSequence;

void EvtSpbControllerSequence(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST Request,
  [in] ULONG TransferCount
)
{...}

Parametri

[in] Controller

Handle WDFDEVICE per l'oggetto dispositivo framework che rappresenta il controller SPB.

[in] Target

Handle SPBTARGET per la destinazione per questa richiesta di I/O. La destinazione è un dispositivo periferico o una porta collegata al bus. L'estensione spb framework (SpbCx) assegnata in precedenza a questo handle alla destinazione nel callback EvtSpbTargetConnect che ha aperto la connessione alla destinazione.

[in] Request

Handle SPBREQUEST per la richiesta di I/O. Il driver del controller SPB deve completare questa richiesta eseguendo l'operazione richiesta o restituendo uno stato di errore. Per altre informazioni, vedere Osservazioni.

[in] TransferCount

Numero di singoli trasferimenti in questa sequenza di trasferimento di I/O. Ogni singolo trasferimento è una semplice operazione di lettura o scrittura.

Valore restituito

nessuno

Osservazioni

SpbCx gestisce la coda di I/O per il controller SPB. SpbCx chiama la funzione di callback EvtSpbControllerIoSequence del driver del controller SPB quando un client (driver periferica) del controller SPB invia una richiesta di IOCTL_SPB_EXECUTE_SEQUENCE a un dispositivo di destinazione collegato al bus. Il valore del parametro Request è un handle che incapsula questa richiesta.

Un callback EvtSpbControllerIoSequence non restituisce un valore di stato. Il driver del controller SPB indica invece lo stato dell'operazione di sequenza nello stato di completamento per la richiesta di I/O.

Un callback EvtSpbControllerIoSequence è asincrono. Ovvero, la funzione di callback deve avviare la sequenza richiesta (o la prima parte della sequenza) e quindi restituire senza attendere il completamento dell'operazione. Successivamente, il driver del controller SPB continua a elaborare la richiesta o la completa durante l'interruzione dei DPC o dei controller di dominio timer.

Il driver del controller SPB può recuperare i valori dei parametri dalla richiesta di I/O per determinare la lunghezza massima dei trasferimenti all'interno della sequenza. Il driver può usare questa lunghezza per allocare le risorse DMA che può riutilizzare per ogni trasferimento all'interno della sequenza.

Il driver del controller SPB può chiamare il metodo SpbRequestGetTransferParameters per recuperare i parametri di controllo e il buffer di dati per ogni trasferimento nella sequenza. Il buffer è un oggetto WDFMEMORY che, nell'implementazione corrente, incapsula un MDL concatenato. Per altre informazioni sugli mdls concatenati, vedere Using MDLs .For more information about chained MDLs, see Using MDLs.For more information about chained MDLs, see Using MDLs.

Il controller SPB deve mantenere selezionato il dispositivo di destinazione per l'intera operazione di sequenza. Se la destinazione viene selezionata da una riga di selezione del dispositivo, la riga può essere asserta continuamente dall'inizio del primo trasferimento nella sequenza fino al termine dell'ultimo trasferimento. Questa riga può essere asserta prima dell'operazione di blocco all'inizio della sequenza e può rimanere asserta fino alla fine della sequenza.

È possibile specificare un ritardo facoltativo per ogni trasferimento in una sequenza. Il driver del controller SPB è responsabile di ritardare almeno tale numero di microsecondi prima di avviare il trasferimento. Se il primo trasferimento nella sequenza ha un ritardo associato, il driver deve prima trasmettere l'indirizzo o asserire la riga di selezione del dispositivo di destinazione e quindi ritardare per l'ora specificata prima di avviare il trasferimento dei dati. Durante questo ritardo, la destinazione deve rimanere selezionata, ma il controller non deve eseguire l'orologio sul bus.

Se il dispositivo di destinazione segnala un NACK durante un trasferimento in una sequenza, il controller SPB arresta la sequenza. Ovvero, il controller non ritenta il trasferimento non riuscito e non tenta di eseguire i trasferimenti rimanenti nella sequenza. In questo caso, il driver del controller SPB deve impostare lo stato di completamento della richiesta di I/O su STATUS_SUCCESS, impostare il campo Informazioni nel blocco di stato di I/O sul numero di byte effettivamente trasferiti (senza contare i dati persi nel trasferimento che ha ricevuto il NACK) e completare la richiesta.

Il driver del controller SPB deve completare la richiesta di I/O con un codice di stato di errore solo se si verifica una delle condizioni seguenti:

  • Il controller SPB non può selezionare il dispositivo di destinazione( ad esempio, un dispositivo di destinazione in un bus I2C segnala un NACK quando il controller trasmette il byte dell'indirizzo).
  • Il driver del controller SPB ottiene uno stato di errore da una chiamata a un servizio WDF o WDM durante l'elaborazione dell'operazione di sequenza.

Per registrare una funzione di callback EvtSpbControllerIoSequence , chiamare il metodo SpbDeviceInitialize .

Esempio

Per definire una funzione di callback EvtSpbControllerIoSequence , è necessario innanzitutto 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 EvtSpbControllerIoSequence denominata MyEvtSpbControllerIoSequence, usare il tipo di funzione EVT_SPB_CONTROLLER_SEQUENCE, come illustrato in questo esempio di codice:

EVT_SPB_CONTROLLER_SEQUENCE  MyEvtSpbControllerIoSequence;

Implementare quindi la funzione di callback come indicato di seguito:

_Use_decl_annotations_
VOID
  MyEvtSpbControllerIoSequence(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST Request,
    ULONG TransferCount
    )
{ ... }

Il tipo di funzione EVT_SPB_CONTROLLER_SEQUENCE è definito nel file di intestazione Spbcx.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 garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione EVT_SPB_CONTROLLER_SEQUENCE 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 Supportato a partire da Windows 8.
Piattaforma di destinazione Desktop
Intestazione spbcx.h
IRQL Chiamato in IRQL <= DISPATCH_LEVEL.

Vedi anche