Condividi tramite

Funzioni WinUSB per la modifica dei criteri pipe

  • Articolo

Per consentire alle applicazioni di ottenere e impostare i parametri di criteri predefiniti di una pipe dell'endpoint, 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 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 su 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) Default value
0x01 SHORT_PACKET_TERMINATE Invia un pacchetto di lunghezza zero per una richiesta di scrittura in cui il buffer è un multiplo delle dimensioni massime del pacchetto supportate dall'endpoint. Bulk (OUT)

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

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

Bulk (OUT)

Interrupt (IN)

Interrupt (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 le dimensioni del file sono sconosciute, la richiesta viene terminata in corrispondenza di un pacchetto breve. Bulk (IN)

Interrupt (IN)		 FALSE
0x05 ALLOW_PARTIAL_READS Consente le richieste di lettura da un dispositivo che restituisce più dati rispetto a quelli richiesti dal chiamante. Bulk (IN)

Interrupt (IN)		 TRUE
0x06 AUTO_FLUSH Salva i dati in eccesso dalla richiesta di lettura e li aggiunge alla richiesta di lettura successiva o rimuove i dati in eccesso. Bulk (IN)

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

Interrupt (IN)		 FALSE
0x08 MAXIMUM_TRANSFER_SIZE Ottiene le dimensioni massime 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)

Interrupt (IN)

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

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)		 FALSE

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

Criteri Abilita se... Comportamento
SHORT_PACKET_TERMINATE(0x01) Il dispositivo richiede che i trasferimenti OUT vengano terminati con un pacchetto di 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 costituita da un multiplo delle dimensioni massime del pacchetto supportate dall'endpoint viene seguita da un pacchetto di lunghezza zero.

Dopo l'invio di dati al controller host, WinUSB invia una richiesta di scrittura con un pacchetto di 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 di stallo. Questo criterio è utile solo quando sono presenti più richieste di lettura in sospeso all'endpoint quando RAW_IO è disabilitato.
  • Se abilitato (il valore del parametro dei criteri è TRUE o diverso da zero), una condizione di stallo viene cancellata automaticamente. Questo parametro di criteri 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 stallo senza interrompere il flusso di dati. I dati continuano a essere trasmessi negli endpoint, purché i nuovi trasferimenti continuino ad arrivare dal dispositivo. Un nuovo trasferimento può includere uno che si trovava 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 non reimposta manualmente la pipe dell'endpoint chiamando WinUsb_ResetPipe.
PIPE_TRANSFER_TIMEOUT Si prevede che i trasferimenti a un endpoint vengano completati entro un determinato periodo di tempo.
  • Se impostato su zero (impostazione predefinita), i trasferimenti non si verificaranno 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 abilitata, WinUSB non accoda la richiesta. Passa invece la richiesta direttamente allo stack USB, indipendentemente dal fatto che lo stack USB stia elaborando i 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. Al contrario, completa 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 multiple delle dimensioni massime del pacchetto 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 quanto richiesto, 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 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 di quanto richiesto e l'applicazione non richiede altri dati. Ciò è possibile se le dimensioni del buffer delle richieste sono multiple delle dimensioni massime del pacchetto 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ò rimuovere 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 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 multipla 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 il bypass dell'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 inviate immediatamente 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 durante la sospensione. Al riavvio dalla sospensione, WinUSB reimposta l'endpoint prima che consenta al chiamante di inviare nuove richieste all'endpoint.