Partilhar via

Funções WinUSB para modificação da configuração de canal

Para permitir que os aplicativos obtenham e definam os parâmetros de política padrão de um pipe de ponto de extremidade, 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 policy 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 adequar seu dispositivo aos seus recursos. A tabela a seguir fornece uma lista das políticas de pipe suportadas pelo WinUSB.

Observação

As políticas descritas na tabela são válidas apenas para os pontos de extremidade especificados. Definir a política em outros pontos de extremidade não tem efeito sobre 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 predefinido
0x01 TERMINAR_PACOTE_CURTO Envia um pacote de comprimento zero para uma solicitação de gravação na qual o buffer é um múltiplo do tamanho máximo de pacote suportado pelo ponto de extremidade. A granel (OUT)

Interrupção (OUT)		 FALSO
0x02 AUTO_CLEAR_STALL Limpa automaticamente um tubo parado sem interromper o fluxo de dados. Bulk (IN)

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

Carga a Granel (Saída)

Interrupção (IN)

Interrupção (OUT)		 5 segundos (5000 milissegundos) para controlo; 0 para outros
0x04 IGNORAR_PACOTES_CORTOS 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. A granel (IN)

Interrupção (IN)		 FALSO
0x05 PERMITIR_LEITURAS_PARCIASI Permite solicitações de leitura de um dispositivo que retorna mais dados do que o solicitado pelo chamador. A granel (interno)

Interrupção (IN)		 VERDADEIRO
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. Volume (IN)

Interrupção (IN)		 FALSO
0x07 RAW_IO Ignora o enfileiramento e o tratamento de erros para melhorar o desempenho para múltiplas solicitações de leitura. A granel (IN)

Interrupção (IN)		 FALSO
0x08 MAXIMUM_TRANSFER_SIZE Obtém o tamanho máximo de uma transferência USB suportada pelo WinUSB. Esta é uma política só de leitura que pode ser obtida ao chamar WinUsb_GetPipePolicy. A granel (IN)

Saída (A granel)

Interrupção (IN)

Interrupção (OUT)
0x09 RESET_PIPE_ON_RESUME Redefine o pipe do ponto de extremidade depois de retomar da suspensão antes de aceitar novas solicitações. Encomenda a granel (IN)

A granel (SAÍDA)

Interrupção (IN)

Interrupção (OUT)		 FALSO

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

Policy Ativar 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 de pacote suportado pelo ponto de extremidade é seguida por um pacote de comprimento zero.

Depois de enviar dados para o controlador host, WinUSB envia uma solicitação de gravação com um pacote de comprimento zero e, em seguida, conclui a solicitação que foi criada por WinUsb_WritePipe.
Limpar automaticamente obstrução Não quer que as transferências falhadas deixem o endpoint num estado estagnado. Esta política é útil apenas quando tens várias solicitações de leitura pendentes para o endpoint quando o RAW_IO está desativado.
  • Se estiver habilitado (o valor do parâmetro de política é TRUE ou diferente de zero), uma condição de bloqueio é limpa automaticamente. Este parâmetro de política não afeta os tubos de controle.

    Quando uma solicitação de leitura falha e o controlador 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. Redefinir a canalização limpa a condição de bloqueio sem interromper o fluxo de dados. Os dados continuam a fluir nos pontos finais, desde que novas transferências continuem chegando do dispositivo. Uma nova transferência pode incluir uma que estava na fila quando a interrupçã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 paralisada 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 destino final sejam concluídas dentro de um tempo específico.
  • Se definido como zero (padrão), as transferências não expirarão porque o controlador host não cancelará a transferência. Neste caso, a transferência aguarda indefinidamente até ser cancelada manualmente ou a transferência ser concluída normalmente.
  • Se definido como um valor diferente de zero (intervalo de tempo limite), o controlador host inicia um temporizador quando recebe 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 temporizador.

    As solicitações não expiram enquanto aguardam numa fila de espera do 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 host não inclui o tempo de fila no cálculo do intervalo de tempo limite.

    Com o RAW_IO ativado, 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 está ocupada processando transferências anteriores. Se a pilha USB estiver ocupada, pode atrasar o processamento da nova solicitação. Isso pode causar um tempo de espera esgotado.
IGNORAR_PACOTES_CURTOS RAW_IO está desativado e você não quer pacotes curtos para concluir as solicitações de leitura.
  • Se ativado (o valor do parâmetro de política é TRUE ou diferente de zero), o controlador 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:
    • Ocorre um erro.
    • O pedido é cancelado.
    • Todos os bytes solicitados foram recebidos.
  • Se desabilitado (o valor do parâmetro de política é FALSE ou zero), o controlador host conclui uma operação de leitura depois de ler o número de bytes solicitado 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 final.

Utilize se a sua aplicação quiser ler alguns bytes para determinar quantos bytes totais ler.
  • Se desativado (o valor do parâmetro de política é FALSE ou zero) e o dispositivo retorna mais dados do que foi solicitado, o WinUSB conclui a solicitação com um erro.
  • Se ativado (o valor do parâmetro de política é TRUE ou diferente de zero) e o dispositivo retorna mais dados do que foi solicitado, o WinUSB pode (dependendo das configurações de 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 para zero bytes com êxito e não enviará as solicitações para baixo da pilha.
AUTO_FLUSH A política ALLOW_PARTIAL_READS está habilitada.

O dispositivo pode enviar mais dados do que foi solicitado, 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 ponto final.		 AUTO_FLUSH define o comportamento do WinUSB quando ALLOW_PARTIAL_READS está habilitado. Se ALLOW_PARTIAL_READS estiver desativado, o valor AUTO_FLUSH será ignorado pelo WinUSB.

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

  • Se ativado (o valor do parâmetro de política é TRUE ou diferente de zero), o WinUSB descarta os bytes extras sem qualquer código de erro.
  • Se desabilitado (o valor do parâmetro de política é FALSO ou zero), o WinUSB salva os bytes extras, adiciona-os ao início da próxima solicitação de leitura do chamador e, em seguida, 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 ponto final.
  • O comprimento deve ser menor ou igual ao valor de MAXIMUM_TRANSFER_SIZE recuperado por WinUsb_GetPipePolicy.
 Se ativada, as transferências ignoram o enfileiramento e o tratamento de erros para melhorar o desempenho em múltiplas solicitações de leitura. 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 do terminal irá falhar.
  • Uma solicitação que é maior do que o tamanho máximo de transferência suportado pelo WinUSB falha.
  • Todas as solicitações bem formadas são imediatamente enviadas para a stack central do USB para serem agendadas no controlador do 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.
REINICIAR_CANAL_AO_RETOMAR O dispositivo não preserva o estado de alternância dos dados durante a 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.
  • Last updated on