Compartilhar via

Funções WinUSB para modificação de política de pipe

  • Artigo

Para permitir que os aplicativos obtenham e definam os parâmetros de política padrão de um pipe de endpoint, Winusb.dll expõe a função WinUsb_GetPipePolicy para recuperar a política padrão do pipe. A função WinUsb_SetPipePolicy permite que um aplicativo defina o parâmetro de política para um novo valor.

O WinUSB permite que você modifique seu comportamento padrão aplicando políticas ao pipe de um ponto de extremidade. Usando essas políticas, você pode configurar o WinUSB para melhor corresponder seu dispositivo aos seus recursos. A tabela a seguir fornece uma lista das políticas de pipe compatíveis com o WinUSB.

Observação

As políticas descritas na tabela são válidas apenas para os endpoints especificados. Definir a política em outros pontos de extremidade não afeta o comportamento do WinUSB para solicitações de leitura ou gravação.

Número da apólice Nome da política Descrição Ponto final (direção) Valor padrão
0x01 SHORT_PACKET_TERMINATE Envia um pacote de comprimento zero para uma solicitação de gravação na qual o buffer é um múltiplo do tamanho máximo do pacote suportado pelo endpoint. Massa (OUT)

Interrupção (OUT)		 FALSE
0x02 AUTO_CLEAR_STALL Limpa automaticamente um pipe parado sem interromper o fluxo de dados. Massa (IN)

Interrupção (IN)		 FALSE
0x03 PIPE_TRANSFER_TIMEOUT Aguarda um intervalo de tempo limite, em milissegundos, antes de cancelar a solicitação. Massa (IN)

Massa (OUT)

Interrupção (IN)

Interrupção (OUT)		 5 segundos (5000 milissegundos) para controle; 0 para os outros
0x04 IGNORE_SHORT_PACKETS Conclui uma solicitação de leitura quando um pacote curto é recebido ou um determinado número de bytes é lido. Se o tamanho do arquivo for desconhecido, a solicitação será encerrada em um pacote curto. Massa (IN)

Interrupção (IN)		 FALSE
0x05 ALLOW_PARTIAL_READS Permite solicitações de leitura de um dispositivo que retorna mais dados do que os solicitados pelo chamador. Massa (IN)

Interrupção (IN)		 TRUE
0x06 AUTO_FLUSH Salva os dados em excesso da solicitação de leitura e os adiciona à próxima solicitação de leitura ou descarta os dados em excesso. Massa (IN)

Interrupção (IN)		 FALSE
0x07 RAW_IO Ignora o enfileiramento e o tratamento de erros para aumentar o desempenho de várias solicitações de leitura. Massa (IN)

Interrupção (IN)		 FALSE
0x08 MAXIMUM_TRANSFER_SIZE Obtém o tamanho máximo de uma transferência USB com suporte do WinUSB. Essa é uma política somente leitura que pode ser recuperada chamando WinUsb_GetPipePolicy. Massa (IN)

Massa (OUT)

Interrupção (IN)

Interrupção (OUT)
0x09 RESET_PIPE_ON_RESUME Redefine o pipe do endpoint após retomar da suspensão antes de aceitar novas solicitações. Massa (IN)

Massa (OUT)

Interrupção (IN)

Interrupção (OUT)		 FALSE

A tabela a seguir identifica as práticas recomendadas de como usar cada uma das políticas de pipe e descreve o comportamento resultante quando a política é habilitada.

Policy Ative se... Comportamento
SHORT_PACKET_TERMINATE(0x01) O dispositivo requer que as transferências OUT sejam encerradas com um pacote de comprimento zero. A maioria dos dispositivos não tem esse requisito. Se habilitado (o valor do parâmetro de política é TRUE ou diferente de zero), cada solicitação de gravação que é um múltiplo do tamanho máximo do pacote suportado pelo endpoint é seguida por um pacote de comprimento zero.

Depois de enviar dados para o controlador de host, o WinUSB envia uma solicitação de gravação com um pacote de comprimento zero e, em seguida, conclui a solicitação criada por WinUsb_WritePipe.
AUTO_CLEAR_STALL Você não quer que as transferências com falha deixem o ponto de extremidade em um estado paralisado. Essa política é útil somente quando você tem várias solicitações de leitura pendentes para o ponto de extremidade quando RAW_IO está desabilitado.
  • Se habilitado (o valor do parâmetro de política é TRUE ou diferente de zero), uma condição de parada é apagada automaticamente. Esse parâmetro de política não afeta os pipes de controle.

    Quando uma solicitação de leitura falha e o controlador de host retorna um status diferente de STATUS_CANCELLED ou STATUS_DEVICE_NOT_CONNECTED, o WinUSB redefine o pipe antes de concluir a solicitação com falha. A redefinição do pipe limpa a condição de parada sem interromper o fluxo de dados. Os dados continuam a fluir nos endpoints, desde que novas transferências continuem chegando do dispositivo. Uma nova transferência pode incluir uma que estava na fila quando a paralisação ocorreu.

    Habilitar essa política não afeta significativamente o desempenho.

  • Se desabilitado (o valor do parâmetro de política é FALSE ou zero), todas as transferências que chegam ao ponto de extremidade após a transferência interrompida falham até que o chamador redefina manualmente o pipe do ponto de extremidade chamando WinUsb_ResetPipe.
PIPE_TRANSFER_TIMEOUT Você espera que as transferências para um ponto de extremidade sejam concluídas dentro de um tempo específico.
  • Se definido como zero (padrão), as transferências não atingirão o tempo limite porque o controlador de host não cancelará a transferência. Nesse caso, a transferência aguarda indefinidamente até que seja cancelada manualmente ou a transferência seja concluída normalmente.
  • Se definido como um valor diferente de zero (intervalo de tempo limite), o controlador de host iniciará um temporizador quando receber a solicitação de transferência. Quando o temporizador excede o intervalo de tempo limite definido, a solicitação é cancelada.

    Uma pequena penalidade de desempenho ocorre devido ao gerenciamento do cronômetro.

    As solicitações não atingem o tempo limite enquanto aguardam em uma fila WinUSB.

    No Windows Vista, para todas as transferências (exceto transferências com RAW_IO habilitado), o WinUSB enfileira a solicitação até que todas as transferências anteriores no ponto de extremidade de destino tenham sido concluídas. O controlador de host não inclui o tempo de enfileiramento no cálculo do intervalo de tempo limite.

    Com o RAW_IO habilitado, o WinUSB não enfileira a solicitação. Em vez disso, ele passa a solicitação diretamente para a pilha USB, se a pilha USB estiver ocupada processando transferências anteriores. Se a pilha USB estiver ocupada, ela poderá atrasar o processamento da nova solicitação. Isso pode causar um tempo limite.
IGNORE_SHORT_PACKETS RAW_IO está desabilitado e você não deseja que pacotes curtos concluam as solicitações de leitura.
  • Se habilitado (o valor do parâmetro de política é TRUE ou diferente de zero), o controlador de host não concluirá uma operação de leitura imediatamente após receber um pacote curto. Em vez disso, ele conclui a operação somente se:
    • Ocorrerá um erro.
    • A solicitação é cancelada.
    • Todos os bytes solicitados foram recebidos.
  • Se desabilitado (o valor do parâmetro de política é FALSE ou zero), o controlador de host conclui uma operação de leitura depois de ler o número solicitado de bytes ou receber um pacote curto.
ALLOW_PARTIAL_READS O dispositivo pode enviar mais dados do que o solicitado se o tamanho do buffer de solicitação for um múltiplo do tamanho máximo do pacote de ponto de extremidade.

Use se o aplicativo quiser ler alguns bytes para determinar quantos bytes totais ler.
  • Se desabilitado (o valor do parâmetro de política é FALSE ou zero) e o dispositivo retornar mais dados do que o solicitado, o WinUSB concluirá a solicitação com um erro.
  • Se habilitado (o valor do parâmetro de política é TRUE ou diferente de zero) e o dispositivo retornar mais dados do que foi solicitado, o WinUSB poderá (dependendo das configurações AUTO_FLUSH) adicionar os dados em excesso da solicitação de leitura ao início da próxima solicitação de leitura ou descartar os dados em excesso.

    Se habilitado, o WinUSB conclui imediatamente as solicitações de leitura de zero bytes com êxito e não envia as solicitações para baixo na pilha.
AUTO_FLUSH ALLOW_PARTIAL_READS política está habilitada.

O dispositivo pode enviar mais dados do que os solicitados e seu aplicativo não requer nenhum outro dado. Isso é possível se o tamanho do buffer de solicitação for um múltiplo do tamanho máximo do pacote de endpoint.		 AUTO_FLUSH define o comportamento do WinUSB quando ALLOW_PARTIAL_READS está habilitado. Se ALLOW_PARTIAL_READS estiver desabilitado, o valor AUTO_FLUSH será ignorado pelo WinUSB.

O WinUSB pode descartar os dados restantes ou enviá-los com a próxima solicitação de leitura do chamador.

  • Se habilitado (o valor do parâmetro de política é TRUE ou diferente de zero), o WinUSB descarta os bytes extras sem nenhum código de erro.
  • Se desabilitado (o valor do parâmetro de política é FALSE ou zero), o WinUSB salva os bytes extras, adiciona-os ao início da próxima solicitação de leitura do chamador e envia os dados para o chamador na próxima operação de leitura.
RAW_IO O desempenho é uma prioridade e o aplicativo envia solicitações de leitura simultâneas para o mesmo ponto de extremidade.

RAW_IO impõe certas restrições ao buffer que é passado pelo chamador em WinUsb_ReadPipe:

  • O comprimento do buffer deve ser um múltiplo do tamanho máximo do pacote de endpoint.
  • O comprimento deve ser menor ou igual ao valor de MAXIMUM_TRANSFER_SIZE recuperado por WinUsb_GetPipePolicy.
 Se habilitadas, as transferências ignoram o enfileiramento e o tratamento de erros para aumentar o desempenho de várias solicitações de leitura. O WinUSB lida com solicitações de leitura da seguinte maneira:

  • Uma solicitação que não é um múltiplo do tamanho máximo do pacote de ponto de extremidade falha.
  • Uma solicitação maior que o tamanho máximo de transferência com suporte do WinUSB falha.
  • Todas as solicitações bem formadas são enviadas imediatamente para a pilha de núcleo USB para serem agendadas no controlador de host.


Habilitar essa configuração melhora significativamente o desempenho de várias solicitações de leitura, reduzindo o atraso entre o último pacote de uma transferência e o primeiro pacote da próxima transferência.
RESET_PIPE_ON_RESUME O dispositivo não preserva seu estado de alternância de dados em suspensão. Ao retomar da suspensão, o WinUSB redefine o ponto de extremidade antes de permitir que o chamador envie novas solicitações para o ponto de extremidade.