Richieste di I/O SPB

La macro di CTL_CODE fornita dal sistema, descritta in Definizione dei codici di controllo I/O, viene usata per definire i codici di controllo IOCTL_SPB_* in Spb.h.

codice di controllo IOCTL_SPB_EXECUTE_SEQUENCE

Il codice di controllo I/O IOCTL_SPB_EXECUTE_SEQUENCE consente a un client (driver periferico) del driver del controller SPB di eseguire una sequenza di trasferimenti (letture e scritture) come singola operazione atomica con una richiesta di I/O. Il dispositivo designato nel bus è la destinazione per tutti i trasferimenti nella sequenza.

Specificando una sequenza di trasferimenti a lunghezza fissa come singola operazione atomica, la richiesta di controllo I/O IOCTL_SPB_EXECUTE_SEQUENCE consente al driver controller di ottimizzare i trasferimenti di I/O e migliorare le prestazioni.

Il client invia questa richiesta di controllo di I/O all'oggetto file per il dispositivo di destinazione.

Un driver del controller SPB registra una funzione di callback EvtSpbControllerIoSequence per eseguire i trasferimenti del bus per una sequenza di trasferimento di I/O. L'estensione spb framework (SpbCx) chiama questa funzione per passare una richiesta di IOCTL_SPB_EXECUTE_SEQUENCE al driver del controller SPB per l'elaborazione.

IOCTL_SPB_EXECUTE_SEQUENCE buffer di input

Il buffer di input è una struttura SPB_TRANSFER_LIST, che contiene un elenco di puntatori ai buffer di dati del client. Questo elenco contiene un buffer di dati per ogni trasferimento (lettura o scrittura) nella sequenza di trasferimento di I/O.

IOCTL_SPB_EXECUTE_SEQUENCE lunghezza del buffer di input

Dimensione di una struttura SPB_TRANSFER_LIST.

blocco di stato IOCTL_SPB_EXECUTE_SEQUENCE

Se l'operazione ha esito positivo, il driver del controller imposta il membro Status su STATUS_SUCCESS e imposta il membro Information sul numero totale di byte trasferiti durante la sequenza.

Questa operazione potrebbe non riuscire per vari motivi, che possono includere risorse basse, input client non valido e malfunzionamento del dispositivo.

Se il driver del controller inizia a elaborare la richiesta di I/O, ma si verifica un errore durante uno dei trasferimenti nella sequenza (ad esempio, il dispositivo di destinazione segnala un NACK per rifiutare il trasferimento), il driver del controller interrompe i trasferimenti rimanenti nella sequenza. Il driver imposta quindi lo stato di completamento su STATUS_SUCCESS, imposta il membro Informazioni sul numero di byte trasferiti correttamente prima dell'errore e completa la richiesta.

codice di controllo IOCTL_SPB_FULL_DUPLEX

Il codice di controllo IOCTL_SPB_FULL_DUPLEX viene usato da un client (driver periferica) per richiedere un'operazione di I/O full-duplex. Le operazioni di I/O full duplex sono supportate dai controller per gli autobus, ad esempio SPI, in grado di leggere e scrivere dati contemporaneamente. La macro di CTL_CODE fornita dal sistema, descritta in Definizione dei codici di controllo di I/O, viene usata per definire IOCTL_SPB_FULL_DUPLEX come indicato di seguito.

Il driver in modalità utente o il driver in modalità kernel per un dispositivo nel bus invia questa richiesta di controllo I/O all'oggetto file per il dispositivo di destinazione.

Questo IOCTL è supportato solo dai driver del controller SPB per gli autobus, ad esempio SPI, in grado di leggere e scrivere dati contemporaneamente.

I buffer di scrittura e lettura per il trasferimento full-duplex sono descritti da una struttura SPB_TRANSFER_LIST. Questa struttura deve usare il formato seguente:

• La matrice di strutture SPB_TRANSFER_LIST_ENTRY contiene esattamente due elementi. Il primo elemento descrive il buffer di scrittura (Direction = SpbTransferDirectionToDevice). Il secondo elemento descrive il buffer di lettura (Direction = SpbTransferDirectionFromDevice).

• I membri DelayInUs delle due strutture SPB_TRANSFER_LIST_ENTRY devono essere zero. I formati di buffer per il buffer di scrittura e il buffer di lettura possono essere i seguenti:

  • SpbTransferBufferFormatSimple
  • SpbTransferBufferFormatList
  • SpbTransferBufferFormatSimpleNonPaged
  • SpbTransferBufferFormatMdl

  Gli ultimi due formati nell'elenco precedente possono essere usati solo dai client in modalità kernel. I formati per i buffer di scrittura e lettura non devono essere uguali. Per altre informazioni su questi formati di buffer, vedere SPB_TRANSFER_BUFFER_FORMAT.

Un'operazione riuscita potrebbe impostare il membro Informazioni su un valore minore della somma delle dimensioni del buffer di scrittura e del buffer di lettura, che può verificarsi se la richiesta viene annullata o se l'operazione non può scrivere il contenuto completo del buffer di scrittura nel dispositivo o riempire completamente il buffer di lettura con i dati letti dal dispositivo.

Le dimensioni del buffer di scrittura e lettura non devono essere uguali. Se il buffer di scrittura è maggiore del buffer di lettura, l'operazione continua a scrivere dati dal buffer di scrittura dopo che il buffer di lettura è pieno. Se il buffer di lettura è maggiore del buffer di scrittura, l'operazione continua a riempire il buffer di lettura dopo che il buffer di scrittura viene svuotato.

Se un driver del controller SPB registra una funzione di callback EvtSpbControllerIoOther, l'estensione spb framework (SpbCx) chiama questa funzione per passare una richiesta di IOCTL_SPB_FULL_DUPLEX al driver del controller SPB per l'elaborazione. SpbCx non esegue alcun controllo dei parametri, convalida dell'elenco di trasferimento o altre elaborazioni per una richiesta di IOCTL_SPB_FULL_DUPLEX.

Per altre informazioni su come un driver del controller SPB implementa il supporto per questo IOCTL, vedere Gestione delle richieste di IOCTL_SPB_FULL_DUPLEX.

IOCTL_SPB_FULL_DUPLEX buffer di input

Puntatore a una struttura SPB_TRANSFER_LIST che contiene puntatori ai buffer di dati di input e output del client. Questa struttura contiene una matrice Transfers di esattamente due elementi. Il primo elemento descrive il buffer che contiene i dati da scrivere nel dispositivo. Il secondo elemento descrive il buffer usato per contenere i dati letti dal dispositivo. Per altre informazioni su come un driver del controller SPB implementa una richiesta I/O personalizzata (IOCTL) che usa strutture SPB_TRANSFER_LIST per descrivere i buffer, vedere Uso della struttura di SPB_TRANSFER_LIST per IOCTL personalizzati.

IOCTL_SPB_FULL_DUPLEX lunghezza del buffer di input

Dimensione di una struttura SPB_TRANSFER_LIST.

blocco di stato IOCTL_SPB_FULL_DUPLEX

Se l'operazione ha esito positivo, il driver del controller imposta il membro Status su STATUS_SUCCESS e imposta il membro Informazioni sul numero totale di byte trasferiti (byte letti più byte scritti) durante l'operazione full-duplex.

Questa operazione potrebbe non riuscire per vari motivi, che possono includere risorse basse, input client non valido e malfunzionamento del dispositivo.

codice di controllo IOCTL_SPB_LOCK_CONNECTION

Il codice di controllo IOCTL_SPB_LOCK_CONNECTION viene usato da un client (driver periferica) per acquisire il blocco di connessione su un dispositivo di destinazione connesso a SPB condiviso con un altro client. Mentre un client mantiene il blocco di connessione, questo client ha accesso esclusivo al dispositivo. La macro di CTL_CODE fornita dal sistema, descritta in Definizione dei codici di controllo I/O, viene usata per definire IOCTL_SPB_LOCK_CONNECTION come indicato di seguito.

Il IOCTL_SPB_LOCK_CONNECTION e le richieste di IOCTL_SPB_UNLOCK_CONNECTION acquisiscono e rilasciano il blocco di connessione su un dispositivo di destinazione collegato a un semplice bus periferico. La maggior parte dei client non usa queste richieste di controllo di I/O. Queste richieste vengono usate solo se due client condividono l'accesso allo stesso dispositivo di destinazione. Per altre informazioni, vedere Blocchi di connessione SPB.

Due client possono aprire connessioni logiche separate allo stesso dispositivo di destinazione e usare il blocco di connessione quando uno dei due client richiede l'accesso esclusivo al dispositivo. Quando un client mantiene il blocco, le richieste di I/O al dispositivo dal secondo client vengono posticipate automaticamente fino a quando il primo client non rilascia il blocco.

Un client può contenere contemporaneamente un blocco di connessione nel dispositivo di destinazione e un blocco del controller nel controller SPB. Le richieste di IOCTL_SPB_LOCK_CONTROLLER e IOCTL_SPB_UNLOCK_CONTROLLER acquisiscono e rilasciano il blocco del controller. Il client deve acquisire il blocco di connessione prima di acquisire il blocco del controller e deve rilasciare il blocco del controller prima di rilasciare il blocco di connessione. Un client usa un blocco controller per eseguire un set ordinato di trasferimenti di bus (operazioni di lettura e scrittura) come singola operazione atomica del bus. Per altre informazioni, vedere Sequenze di trasferimento di I/O.

Un blocco di connessione viene terminato automaticamente se una richiesta di IRP_MJ_CLEANUP viene inviata a un dispositivo di destinazione mentre la connessione è bloccata nel dispositivo. Una richiesta di pulizia viene inviata a un dispositivo di destinazione quando un client chiude l'handle di file al dispositivo.

blocco di stato IOCTL_SPB_LOCK_CONNECTION

Se l'operazione ha esito positivo, il membro Status viene impostato su STATUS_SUCCESS.

Se l'operazione non riesce, il membro Status viene impostato su un codice di stato di errore appropriato.

Se il client contiene già il blocco di connessione nel dispositivo di destinazione o il blocco del controller nel controller SPB, questa operazione ha esito negativo con Status = STATUS_INVALID_DEVICE_REQUEST. Questa operazione potrebbe non riuscire per altri motivi, che possono includere risorse basse, input client non valido e malfunzionamento del dispositivo.

codice di controllo IOCTL_SPB_LOCK_CONTROLLER

Il codice di controllo IOCTL_SPB_LOCK_CONTROLLER viene usato da un client (driver di periferica) per bloccare il controller SPB. Mentre il controller è bloccato, il client ha l'uso esclusivo del bus per accedere al dispositivo di destinazione specificato per il blocco. La macro di CTL_CODE fornita dal sistema, descritta in Definizione dei codici di controllo I/O, viene usata per definire IOCTL_SPB_LOCK_CONTROLLER come indicato di seguito.

Per ottenere l'uso esclusivo del bus per accedere a un dispositivo di destinazione, un client (driver periferica) invia questo IOCTL all'oggetto file per la destinazione. Al termine dell'IOCTL, il controller viene bloccato e tutti i trasferimenti di I/O (lettura o scrittura) sul bus accedono alla destinazione designata. Tra i trasferimenti, il controller mantiene selezionato il dispositivo di destinazione, ma arresta l'orologio.

Il controller rimane bloccato fino a quando il client invia una richiesta di IOCTL_SPB_UNLOCK_CONTROLLER per sbloccare il controller. Al termine della sequenza di trasferimenti da o verso il dispositivo di destinazione, il client deve sbloccare il controller in modo che il controller possa elaborare le richieste di I/O per altre destinazioni nel bus.

Un blocco viene terminato automaticamente se una richiesta di IRP_MJ_CLEANUP viene inviata a un dispositivo di destinazione mentre il controller è bloccato nella destinazione. Una richiesta di pulizia viene inviata a una destinazione quando un client chiude il relativo handle alla destinazione.

I controller SPB non sono necessari per supportare le richieste di IOCTL_SPB_LOCK_CONTROLLER e IOCTL_SPB_UNLOCK_CONTROLLER e i driver di dispositivo periferici non devono presupporre che siano supportati.

Se un driver del controller SPB registra una funzione di callback EvtSpbControllerLock, l'estensione spb framework (SpbCx) chiama questa funzione per passare una richiesta di IOCTL_SPB_LOCK_CONTROLLER al driver del controller SPB per l'elaborazione.

blocco di stato IOCTL_SPB_LOCK_CONTROLLER

Se l'operazione ha esito positivo, il membro Status viene impostato su STATUS_SUCCESS. Questo IOCTL può restituire uno stato di errore per diversi motivi, incluso il mancato funzionamento del controller in modalità di accesso esclusivo. In questa modalità, il controller mantiene selezionato il dispositivo di destinazione in modo che sia la destinazione esclusiva per tutti i trasferimenti di I/O sul bus. Il controller rimane in questa modalità fino a quando non viene sbloccato.

codice di controllo IOCTL_SPB_UNLOCK_CONNECTION

Il codice di controllo di I/O IOCTL_SPB_UNLOCK_CONNECTION viene usato da un client (driver di periferica) per rilasciare il blocco di connessione su un dispositivo di destinazione connesso a SPB condiviso con un altro client. Il client ha inviato in precedenza una richiesta di IOCTL_SPB_LOCK_CONNECTION per acquisire l'accesso esclusivo al dispositivo.

Il IOCTL_SPB_LOCK_CONNECTION e le richieste di IOCTL_SPB_UNLOCK_CONNECTION acquisiscono e rilasciano il blocco di connessione su un dispositivo di destinazione collegato a un semplice bus periferico. La maggior parte dei client non usa queste richieste di controllo di I/O. Queste richieste vengono usate solo se due client condividono l'accesso allo stesso dispositivo di destinazione. Per altre informazioni, vedere Blocchi di connessione SPB.

Dopo che un client (driver periferica) invia una richiesta di IOCTL_SPB_LOCK_CONNECTION a un dispositivo di destinazione nel bus e la richiesta viene completata correttamente, la connessione rimane bloccata fino a quando il client non invia una richiesta di IOCTL_SPB_UNLOCK_CONNECTION per sbloccare la connessione.

Il client invia una richiesta di IOCTL_SPB_UNLOCK_CONNECTION per rilasciare il blocco di connessione al dispositivo di destinazione quando il client non richiede più l'accesso esclusivo al dispositivo. La connessione deve essere sbloccata in modo che l'altro client possa accedere al dispositivo.

blocco di stato IOCTL_SPB_UNLOCK_CONNECTION

Se l'operazione ha esito positivo, il membro Status viene impostato su STATUS_SUCCESS.

Se l'operazione non riesce, il membro Status viene impostato su un codice di stato di errore appropriato. Se il client non mantiene il blocco di connessione nel dispositivo di destinazione o se il client mantiene ancora il blocco di connessione nel controller SPB, questa operazione ha esito negativo con Status = STATUS_INVALID_DEVICE_REQUEST. Questa operazione potrebbe non riuscire per altri motivi, che possono includere risorse basse, input client non valido e malfunzionamento del dispositivo.

codice di controllo IOCTL_SPB_UNLOCK_CONTROLLER

Il IOCTL_SPB_UNLOCK_CONTROLLER codice di controllo di I/O viene usato da un client (driver di periferica) per sbloccare il controller SPB. Il client ha precedentemente bloccato il controller per ottenere l'uso esclusivo del bus per accedere a un dispositivo di destinazione sul bus.

Dopo che un client (driver periferica) invia una richiesta di controllo di I/O IOCTL_SPB_LOCK_CONTROLLER a un dispositivo di destinazione nel bus, il controller rimane bloccato fino a quando il client non invia una richiesta di controllo I/O IOCTL_SPB_UNLOCK_CONTROLLER per sbloccare il controller. Il client invia queste richieste di controllo di I/O all'oggetto file per il dispositivo di destinazione.

Il client invia una richiesta di IOCTL_SPB_UNLOCK_CONTROLLER quando ha completato una sequenza di trasferimenti sul bus e vuole rilasciare il dispositivo di destinazione. Il controller deve essere sbloccato in modo che possa elaborare le richieste di I/O per altre destinazioni nel bus.

I controller SPB non sono necessari per supportare le richieste di IOCTL_SPB_LOCK_CONTROLLER e IOCTL_SPB_UNLOCK_CONTROLLER e i driver di dispositivo periferici non devono presupporre che siano supportati.

L'estensione spb framework (SpbCx) chiama la funzione di callback evtSpbControllerUnlock facoltativa di un driver del controller SPB per passare una richiesta di IOCTL_SPB_LOCK_CONTROLLER al driver del controller SPB per l'elaborazione.

blocco di stato IOCTL_SPB_UNLOCK_CONTROLLER

Se l'operazione ha esito positivo, il membro Status viene impostato su STATUS_SUCCESS.

Questo IOCTL può avere esito negativo solo se viene inviato da un client che non dispone del controller bloccato per l'accesso esclusivo alla destinazione designata.