_URB_ISOCH_TRANSFER struttura (usb.h)

Articolo
02/26/2024

La struttura _URB_ISOCH_TRANSFER viene usata dai driver client USB per inviare dati a o recuperare dati da una pipe di trasferimento isochronous.

Sintassi

struct _URB_ISOCH_TRANSFER {
  struct _URB_HEADER         Hdr;
  USBD_PIPE_HANDLE           PipeHandle;
  ULONG                      TransferFlags;
  ULONG                      TransferBufferLength;
  PVOID                      TransferBuffer;
  PMDL                       TransferBufferMDL;
  struct _URB                *UrbLink;
  struct _URB_HCD_AREA       hca;
  ULONG                      StartFrame;
  ULONG                      NumberOfPackets;
  ULONG                      ErrorCount;
  USBD_ISO_PACKET_DESCRIPTOR IsoPacket[1];
};

Members

Hdr

Puntatore a una struttura di _URB_HEADER che specifica le informazioni sull'intestazione DI CONTROLLO. Hdr.Function deve essere URB_FUNCTION_ISOCH_TRANSFER e Hdr.Length deve essere la dimensione di questa struttura di dati a lunghezza variabile.

PipeHandle

Specifica un handle opaco per la pipe isochronous. Il driver del controller host restituisce questo handle quando il driver client seleziona la configurazione del dispositivo con un URB_FUNCTION_SELECT_CONFIGURATION di tipo o quando il driver client modifica le impostazioni per un'interfaccia con un'interfaccia di tipo URB_FUNCTION_SELECT_INTERFACE.

TransferFlags

Specifica zero, uno o una combinazione dei flag seguenti:

Valore	Significato
USBD_TRANSFER_DIRECTION_IN	È impostato per richiedere i dati da un dispositivo. Per trasferire i dati in un dispositivo, questo flag deve essere chiaro.
USBD_SHORT_TRANSFER_OK	È impostato per indirizzare il controller host a non restituire un errore quando riceve un pacchetto dal dispositivo che è più breve rispetto alle dimensioni massime del pacchetto per l'endpoint. Questo flag non ha alcun effetto su una pipe isochronous, perché il driver del bus non restituisce un errore quando riceve pacchetti brevi su una pipe isochronous.
USBD_START_ISO_TRANSFER_ASAP	Causa l'inizio del trasferimento nel frame successivo, se non sono stati inviati trasferimenti alla pipe dopo l'apertura o l'ultima reimpostazione della pipe. In caso contrario, il trasferimento inizia sul primo frame che segue tutte le richieste attualmente in coda per la pipe. Il frame effettivo che il trasferimento inizia verrà modificato per la latenza del bus dal driver del controller host.

TransferBufferLength

Specifica la lunghezza, in byte, del buffer specificato in TransferBuffer o descritto in TransferBufferMDL. Il driver del controller host restituisce il numero di byte inviati o letti dalla pipe in questo membro.

TransferBuffer

Un puntatore a un buffer residente per il trasferimento è NULL se viene fornito un MDL in TransferBufferMDL. Il contenuto di questo buffer dipende dal valore di TransferFlags. Se viene specificato USBD_TRANSFER_DIRECTION_IN, questo buffer conterrà i dati letti dal dispositivo restituito dal driver del controller host. In caso contrario, questo buffer contiene dati forniti dal driver per il trasferimento nel dispositivo.

TransferBufferMDL

Un puntatore a un MDL che descrive un buffer residente è NULL se viene fornito un buffer in TransferBuffer. Il contenuto del buffer dipende dal valore di TransferFlags. Se viene specificato USBD_TRANSFER_DIRECTION_IN, il buffer descritto conterrà i dati letti dal dispositivo restituito dal driver del controller host. In caso contrario, il buffer contiene dati forniti dal driver per il trasferimento nel dispositivo. Questa MDL deve essere allocata dal pool non a pagina.

UrbLink

Riservato. Non usare.

hca

Riservato. Non usare.

StartFrame

Specifica il numero di frame che il trasferimento deve iniziare. Questa variabile deve trovarsi all'interno di un intervallo definito dal sistema del frame corrente. L'intervallo viene specificato dalla costante USBD_ISO_START_FRAME_RANGE.

Se START_ISO_TRANSFER_ASAP è impostato in TransferFlags, questo membro contiene il numero di frame avviato dal trasferimento, quando la richiesta viene restituita dal driver del controller host. In caso contrario, questo membro deve contenere il numero di frame che il trasferimento inizia.

NumberOfPackets

Specifica il numero di pacchetti descritti dal membro della matrice a lunghezza variabile IsoPacket.

ErrorCount

Contiene il numero di pacchetti completati con una condizione di errore restituita dal driver del controller host.

IsoPacket[1]

Contiene una matrice a lunghezza variabile di strutture USBD_ISO_PACKET_DESCRIPTOR che descrivono i pacchetti di trasferimento isochronous da trasferire sul bus USB. Per altre informazioni su questo membro, vedere la sezione Osservazioni.

Commenti

Il driver del bus USB restituisce sempre un valore di USBD_STATUS_SUCCESS in Hdr.Status, a meno che ogni pacchetto nel trasferimento non generasse un errore o che la richiesta non fosse ben formata e non poteva essere eseguita in tutto. La tabella seguente include i codici di errore possibili restituiti in Hdr.Status.

Valore di errore	Significato
USBD_STATUS_ISOCH_REQUEST_FAILED	Indica che ogni pacchetto di una richiesta isochrono è stata completata con errori.
USBD_STATUS_BAD_START_FRAME	Indica che il frame di avvio richiesto non si trova all'interno di USBD_ISO_START_FRAME_RANGE del frame USB corrente.
USBD_ISO_NOT_ACCESSED_LATE	Indica che ogni pacchetto è stato inviato troppo tardi per l'invio del pacchetto, in base al frame di avvio richiesto.
USBD_STATUS_INVALID_PARAMETER	Indica che uno dei parametri DI URB non è corretto.

Prima che il controller host invii una richiesta isochronous a un dispositivo USB, richiede informazioni sull'endpoint del dispositivo a cui deve inviare o ricevere dati. Queste informazioni vengono archiviate nei descrittori dell'endpoint (USB_ENDPOINT_DESCRIPTOR) recuperati dal descrittore di configurazione selezionato. Dopo che il driver del bus ottiene il descrittore dell'endpoint, crea una pipe di trasferimento isochronous per configurare il trasferimento dei dati. Gli attributi della pipe vengono archiviati nella struttura USBD_PIPE_INFORMATION . Per i trasferimenti isochronous, i membri vengono impostati come segue:

Il membro PipeType specifica il tipo di trasferimento ed è impostato su UsbdPipeTypeIsochronous.
Il membro MaximumPacketSize specifica la quantità di dati, in byte, che costituisce un pacchetto. Per i trasferimenti isochronous, le dimensioni dei pacchetti sono fisse e possono essere un valore compreso tra 0 e 1024. Le dimensioni del pacchetto sono uguali o sono inferiori al valore wMaxPacketSize del descrittore dell'endpoint.
Il membro Interval deriva dal valore bInterval del descrittore dell'endpoint. Questo valore viene usato per calcolare il periodo di polling che indica la frequenza in cui vengono inviati i dati nel bus. Per i dispositivi a velocità completa, il periodo viene misurato in unità di 1 millisecondi; per i dispositivi ad alta velocità, il periodo viene misurato in microframe.

Il controller host determina anche la quantità di dati che possono essere trasferiti (all'interno di un frame o di un microframe) a seconda del tipo di dispositivo. Queste informazioni sono disponibili in bit 12.. 11 di wMaxPacketSize nel descrittore dell'endpoint.

Per i dispositivi a velocità completa, è possibile trasferire un solo pacchetto all'interno di un frame; i bit 12.. 11 sono riservati e impostati su zero.

Per i dispositivi ad alta velocità, i dati possono essere trasferiti in un singolo pacchetto o possono estendersi su più pacchetti, all'interno di un microframe. Se i bit 12.. 11 sono impostati su n, è possibile trasferire (n+1)*MaximumPacketSize byte per microframe. Bit 12.. 11 impostato su zero indicano che è possibile trasferire un solo pacchetto in un microframe. Se i bit 12.. 11 sono impostati su 1, il controller host può trasferire due pacchetti in un microframe.

Il membro IsoPacket di _URB_ISOCH_TRANSFER è una matrice di USBD_ISO_PACKET_DESCRIPTOR che descrive il layout del buffer di trasferimento. Ogni elemento della matrice correla ai dati trasferiti in un microframe. Se IsoPacket ha n elementi, il controller host trasferisce i fotogrammi (per i dispositivi a velocità completa) o microframe (per i dispositivi ad alta velocità) per trasferire i dati. IsoPacket[i]. Il membro offset viene usato per tenere traccia della quantità di dati da inviare o ricevere. Questa operazione viene eseguita impostando un offset di byte dall'inizio dell'intero buffer di trasferimento per la richiesta.

Ad esempio, sono disponibili cinque microframe per trasferire pacchetti di dimensioni di 1024 byte.

Se i bit 12.. 11 sono impostati su zero (che indica un singolo pacchetto per trasferimento microframe), IsoPacket contiene le voci seguenti:

Microframe 1 IsoPacket.Element[0].Offset = 0 (indirizzo iniziale)

Microframe 2 IsoPacket.Element[1].Offset = 1024

Microframe 3 IsoPacket.Element[2].Offset = 2048

Microframe 4 IsoPacket.Element[3].Offset = 3072

Microframe 5 IsoPacket.Element[4].Offset = 4096

Se i bit 12.. 11 sono impostati su 1 (che indica due pacchetti per microframe), IsoPacket contiene le voci seguenti:

Microframe 1 IsoPacket.Element[0].Offset = 0 (indirizzo iniziale)

Microframe 2 IsoPacket.Element[1].Offset = 2048

Microframe 3 IsoPacket.Element[2].Offset = 4096

Microframe 4 IsoPacket.Element[3].Offset = 6144

Microframe 5 IsoPacket.Element[4].Offset = 8192

Nota Per più pacchetti, il valore di offset indica le dimensioni per tutti i pacchetti all'interno del microframe.

IsoPacket[i]. Il membro di lunghezza viene aggiornato dal controller host per indicare il numero effettivo di byte ricevuti dal dispositivo per trasferimenti IN isocroni. IsoPacket[i]. La lunghezza non viene utilizzata per i trasferimenti OUT isocroni.

I driver possono utilizzare la macro GET_ISO_URB_SIZE per determinare le dimensioni necessarie per contenere l'intero OGGETTO). Se la lunghezza è troppo piccola per riempire lo spazio messo da parte per questo pacchetto, il conducente dell'autobus lascia uno spazio dalla fine dei dati recuperati all'offset per il pacchetto successivo. Il conducente del bus non regola gli offset per evitare di sprecare spazio buffer.

I membri TransferBuffer o TransferBufferMDL devono specificare un buffer virtualmente contiguo.

Trattare altri membri che fanno parte di questa struttura, ma non descritti qui come opachi. Sono riservati per l'uso del sistema.