Condividi tramite

Funzioni WinUSB per la modifica dei criteri di pipe

  • Articolo

Per consentire alle applicazioni di ottenere e impostare i parametri predefiniti di un endpoint pipe, Winusb.dll espone la funzione WinUsb_GetPipePolicy per recuperare i criteri predefiniti della pipe. La funzione WinUsb_SetPipePolicy consente a un'applicazione di impostare il parametro dei criteri su un nuovo valore.

WinUSB consente di modificare il comportamento predefinito applicando i criteri alla pipe di un endpoint. Usando questi criteri, è possibile configurare WinUSB in modo che corrisponda meglio al dispositivo alle relative funzionalità. La tabella seguente fornisce un elenco dei criteri di pipe supportati da WinUSB.

Nota

I criteri descritti nella tabella sono validi solo per gli endpoint specificati. L'impostazione dei criteri in altri endpoint non ha alcun effetto sul comportamento di WinUSB per le richieste di lettura o scrittura.

Numero di criteri Nome criteri Descrizione Endpoint (direzione) Valore predefinito
0x01 SHORT_PACKET_TERMINATE Invia un pacchetto di lunghezza zero per una richiesta di scrittura in cui il buffer è un multiplo delle dimensioni massime dei pacchetti supportate dall'endpoint. Bulk (OUT)

Interruzione (OUT)		 FALSE
0x02 AUTO_CLEAR_STALL Cancella automaticamente una pipe bloccata senza arrestare il flusso di dati. Bulk (IN)

Interruzione (IN)		 FALSE
0x03 PIPE_TRANSFER_TIMEOUT Attende un intervallo di timeout, in millisecondi, prima di annullare la richiesta. Bulk (IN)

Bulk (OUT)

Interruzione (IN)

Interruzione (OUT)		 5 secondi (5000 millisecondi) per il controllo; 0 per gli altri
0x04 IGNORE_SHORT_PACKETS Completa una richiesta di lettura quando viene ricevuto un pacchetto breve o viene letto un determinato numero di byte. Se la dimensione del file è sconosciuta, la richiesta viene terminata in un pacchetto breve. Bulk (IN)

Interruzione (IN)		 FALSE
0x05 ALLOW_PARTIAL_READS Consente di leggere le richieste da un dispositivo che restituisce più dati che richiesti dal chiamante. Bulk (IN)

Interruzione (IN)		 true
0x06 AUTO_FLUSH Salva i dati in eccesso dalla richiesta di lettura e lo aggiunge alla richiesta di lettura successiva o elimina i dati in eccesso. Bulk (IN)

Interruzione (IN)		 FALSE
0x07 RAW_IO Ignora l'accodamento e la gestione degli errori per migliorare le prestazioni per più richieste di lettura. Bulk (IN)

Interruzione (IN)		 FALSE
0x08 MAXIMUM_TRANSFER_SIZE Ottiene la dimensione massima di un trasferimento USB supportato da WinUSB. Si tratta di un criterio di sola lettura che può essere recuperato chiamando WinUsb_GetPipePolicy. Bulk (IN)

Bulk (OUT)

Interruzione (IN)

Interruzione (OUT)
0x09 RESET_PIPE_ON_RESUME Reimposta la pipe dell'endpoint dopo aver ripreso dalla sospensione prima di accettare nuove richieste. Bulk (IN)

Bulk (OUT)

Interruzione (IN)

Interruzione (OUT)		 FALSE

La tabella seguente identifica le procedure consigliate per l'uso di ognuno dei criteri della pipe e descrive il comportamento risultante quando il criterio è abilitato.

Criteri Abilitare se... Comportamento
SHORT_PACKET_TERMINATE(0x01) Il dispositivo richiede che i trasferimenti OUT vengano terminati con un pacchetto a lunghezza zero. La maggior parte dei dispositivi non ha questo requisito. Se abilitato (il valore del parametro dei criteri è TRUE o diverso da zero), ogni richiesta di scrittura che è una più delle dimensioni massime dei pacchetti supportate dall'endpoint, viene seguita da un pacchetto a lunghezza zero.

Dopo l'invio di dati al controller host, WinUSB invia una richiesta di scrittura con un pacchetto a lunghezza zero e quindi completa la richiesta creata da WinUsb_WritePipe.
AUTO_CLEAR_STALL Non si vuole che i trasferimenti non riusciti lascino l'endpoint in uno stato bloccato. Questo criterio è utile solo quando si dispone di più richieste di lettura in sospeso all'endpoint quando RAW_IO è disabilitato.
  • Se abilitato (il valore del parametro criterio è TRUE o diverso da zero), viene cancellata automaticamente una condizione di stalla. Questo parametro di criterio non influisce sulle pipe di controllo.

    Quando una richiesta di lettura ha esito negativo e il controller host restituisce uno stato diverso da STATUS_CANCELLED o STATUS_DEVICE_NOT_CONNECTED, WinUSB reimposta la pipe prima di completare la richiesta non riuscita. La reimpostazione della pipe cancella la condizione di stalla senza interrompere il flusso di dati. I dati continuano a scorrere negli endpoint, purché i nuovi trasferimenti continuino ad arrivare dal dispositivo. Un nuovo trasferimento può includere uno che era nella coda quando si è verificato lo stallo.

    L'abilitazione di questo criterio non influisce significativamente sulle prestazioni.

  • Se disabilitato (il valore del parametro dei criteri è FALSE o zero), tutti i trasferimenti che arrivano all'endpoint dopo che il trasferimento bloccato non riesce fino a quando il chiamante reimposta manualmente la pipe dell'endpoint chiamando WinUsb_ResetPipe.
PIPE_TRANSFER_TIMEOUT Si prevede che i trasferimenti a un endpoint vengano completati entro un periodo di tempo specifico.
  • Se impostato su zero (impostazione predefinita), i trasferimenti non verranno annullati perché il controller host non annulla il trasferimento. In questo caso, il trasferimento attende per un periodo illimitato fino a quando non viene annullato manualmente o il trasferimento viene completato normalmente.
  • Se impostato su un valore diverso da zero (intervallo di timeout), il controller host avvia un timer quando riceve la richiesta di trasferimento. Quando il timer supera l'intervallo di timeout impostato, la richiesta viene annullata.

    Una riduzione delle prestazioni si verifica a causa della gestione del timer.

    Le richieste non si timeout durante l'attesa in una coda WinUSB.

    In Windows Vista, per tutti i trasferimenti (ad eccezione dei trasferimenti con RAW_IO abilitato), WinUSB accoda la richiesta fino al completamento di tutti i trasferimenti precedenti nell'endpoint di destinazione. Il controller host non include il tempo di accodamento nel calcolo dell'intervallo di timeout.

    Con RAW_IO abilitato, WinUSB non accoda la richiesta. Passa invece la richiesta direttamente allo stack USB, indipendentemente dal fatto che lo stack USB sia occupato nell'elaborazione dei trasferimenti precedenti. Se lo stack USB è occupato, può ritardare l'elaborazione della nuova richiesta. Ciò può causare un timeout.
IGNORE_SHORT_PACKETS RAW_IO è disabilitato e non si desidera che i pacchetti brevi completino le richieste di lettura.
  • Se abilitato (il valore del parametro dei criteri è TRUE o diverso da zero), il controller host non completerà un'operazione di lettura immediatamente dopo la ricezione di un pacchetto breve. Completa invece l'operazione solo se:
    • Si verifica un errore.
    • La richiesta viene annullata.
    • Tutti i byte richiesti sono stati ricevuti.
  • Se disabilitato (il valore del parametro dei criteri è FALSE o zero), il controller host completa un'operazione di lettura dopo aver letto il numero di byte richiesto o ha ricevuto un pacchetto breve.
ALLOW_PARTIAL_READS Il dispositivo può inviare più dati rispetto a quanto richiesto se le dimensioni del buffer delle richieste sono un multiplo delle dimensioni massime dei pacchetti dell'endpoint.

Usare se l'applicazione vuole leggere alcuni byte per determinare il numero totale di byte da leggere.
  • Se disabilitato (il valore del parametro dei criteri è FALSE o zero) e il dispositivo restituisce più dati di quelli richiesti, WinUSB completa la richiesta con un errore.
  • Se abilitato (il valore del parametro dei criteri è TRUE o diverso da zero) e il dispositivo restituisce più dati di quelli richiesti, WinUSB può (a seconda delle impostazioni di AUTO_FLUSH) aggiungere i dati in eccesso dalla richiesta di lettura all'inizio della richiesta di lettura successiva o eliminare i dati in eccesso.

    Se abilitata, WinUSB completa immediatamente le richieste di lettura per zero byte e non invierà le richieste nello stack.
AUTO_FLUSH ALLOW_PARTIAL_READS criterio è abilitato.

Il dispositivo può inviare più dati rispetto a quanto richiesto e l'applicazione non richiede altri dati. Ciò è possibile se le dimensioni del buffer delle richieste sono multiple delle dimensioni massime dei pacchetti dell'endpoint.		 AUTO_FLUSH definisce il comportamento di WinUSB quando ALLOW_PARTIAL_READS è abilitato. Se ALLOW_PARTIAL_READS è disabilitato, il valore AUTO_FLUSH viene ignorato da WinUSB.

WinUSB può eliminare i dati rimanenti o inviarli con la richiesta di lettura successiva del chiamante.

  • Se abilitato (il valore del parametro dei criteri è TRUE o diverso da zero), WinUSB rimuove i byte aggiuntivi senza alcun codice di errore.
  • Se disabilitato (il valore del parametro dei criteri è FALSE o zero), WinUSB salva i byte aggiuntivi, li aggiunge all'inizio della successiva richiesta di lettura del chiamante e quindi invia i dati al chiamante nell'operazione di lettura successiva.
RAW_IO Le prestazioni sono una priorità e l'applicazione invia richieste di lettura simultanee allo stesso endpoint.

RAW_IO impone determinate restrizioni al buffer passato dal chiamante in WinUsb_ReadPipe:

  • La lunghezza del buffer deve essere un multiplo delle dimensioni massime del pacchetto dell'endpoint.
  • La lunghezza deve essere minore o uguale al valore di MAXIMUM_TRANSFER_SIZE recuperato da WinUsb_GetPipePolicy.
 Se abilitata, trasferisce ignora l'accodamento e la gestione degli errori per migliorare le prestazioni per più richieste di lettura. WinUSB gestisce le richieste di lettura come indicato di seguito:

  • Una richiesta che non è un multiplo delle dimensioni massime del pacchetto dell'endpoint ha esito negativo.
  • Una richiesta maggiore della dimensione massima di trasferimento supportata da WinUSB ha esito negativo.
  • Tutte le richieste ben formate vengono immediatamente inviate allo stack di core USB da pianificare nel controller host.


L'abilitazione di questa impostazione migliora significativamente le prestazioni di più richieste di lettura riducendo il ritardo tra l'ultimo pacchetto di un trasferimento e il primo pacchetto del trasferimento successivo.
RESET_PIPE_ON_RESUME Il dispositivo non mantiene lo stato di attivazione/disattivazione dei dati nella sospensione. In caso di ripresa dalla sospensione, WinUSB reimposta l'endpoint prima che consenta al chiamante di inviare nuove richieste all'endpoint.