estrutura WDF_USB_CONTINUOUS_READER_CONFIG (wdfusb.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

A estrutura WDF_USB_CONTINUOUS_READER_CONFIG contém informações que a estrutura usa para configurar um leitor contínuo para um pipe USB.

Sintaxe

typedef struct _WDF_USB_CONTINUOUS_READER_CONFIG {
  ULONG                                 Size;
  size_t                                TransferLength;
  size_t                                HeaderLength;
  size_t                                TrailerLength;
  UCHAR                                 NumPendingReads;
  PWDF_OBJECT_ATTRIBUTES                BufferAttributes;
  PFN_WDF_USB_READER_COMPLETION_ROUTINE EvtUsbTargetPipeReadComplete;
  WDFCONTEXT                            EvtUsbTargetPipeReadCompleteContext;
  PFN_WDF_USB_READERS_FAILED            EvtUsbTargetPipeReadersFailed;
} WDF_USB_CONTINUOUS_READER_CONFIG, *PWDF_USB_CONTINUOUS_READER_CONFIG;

Membros

Size

O tamanho, em bytes, dessa estrutura.

TransferLength

O comprimento máximo, em bytes, dos dados que podem ser recebidos do dispositivo.

HeaderLength

Um deslocamento, em bytes, para o buffer que recebe dados do dispositivo. A estrutura armazenará dados do dispositivo em um buffer de leitura, começando pelo valor de deslocamento. Em outras palavras, esse espaço precede o espaço do tamanho transferLength no qual a estrutura armazena dados do dispositivo.

TrailerLength

O comprimento, em bytes, de um espaço de buffer à direita. Esse espaço segue o espaço do tamanho transferLength no qual a estrutura armazena dados do dispositivo.

NumPendingReads

O número de solicitações de leitura que a estrutura fará fila para receber dados do destino de E/S. Se esse valor for zero, a estrutura usará um número padrão de solicitações de leitura. Se o valor especificado for maior que o máximo permitido, a estrutura usará o máximo permitido. Para obter mais informações sobre o membro NumPendingReads , consulte a seção Comentários a seguir.

BufferAttributes

Uma estrutura WDF_OBJECT_ATTRIBUTES que especifica atributos de objeto para o objeto de memória da estrutura que a estrutura cria para cada solicitação de leitura. Esse membro pode ser NULL. Não é possível definir o membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES.

EvtUsbTargetPipeReadComplete

Um ponteiro para a função de retorno de chamada EvtUsbTargetPipeReadComplete do driver.

EvtUsbTargetPipeReadCompleteContext

Um ponteiro não tipado para informações de contexto definidas pelo driver que a estrutura passa para a função de retorno de chamada EvtUsbTargetPipeReadComplete do driver.

EvtUsbTargetPipeReadersFailed

Um ponteiro para a função de retorno de chamada EvtUsbTargetPipeReadersFailed do driver. Esse ponteiro é opcional e pode ser NULL. Para obter mais informações sobre esse parâmetro, consulte a seção Comentários de WdfUsbTargetPipeConfigContinuousReader.

Comentários

A estrutura WDF_USB_CONTINUOUS_READER_CONFIG é usada como entrada para o método WdfUsbTargetPipeConfigContinuousReader .

Para inicializar uma estrutura de WDF_USB_CONTINUOUS_READER_CONFIG, o driver deve chamar WDF_USB_CONTINUOUS_READER_CONFIG_INIT.

Use as seguintes diretrizes ao escolher um valor para o membro NumPendingReads :

Defina NumPendingReads como 0 se desejar que o driver use o valor padrão da estrutura.
O valor padrão é maior que 1 e foi determinado para fornecer um desempenho razoavelmente bom para muitos dispositivos em muitas configurações de processador.
Defina NumPendingReads como 1 se for importante que o driver receba buffers de dados na ordem exata em que o dispositivo entrega os dados.
Defina NumPendingReads como um número que atenda aos requisitos de desempenho do dispositivo, com base em medidas completas de desempenho.
Primeiro, teste seu dispositivo com o valor padrão (0) para NumPendingReads. Seus testes devem incluir várias configurações de hardware, incluindo diferentes tipos e números de processadores e diferentes controladores de host USB e configurações USB. Em seguida, você pode experimentar valores mais altos usando os mesmos testes. Um driver que pode exigir um valor mais alto é um para um dispositivo que tem uma alta taxa de interrupção, em que os dados podem ser perdidos se as interrupções não forem atendidas rapidamente.

Um valor NumPendingReads muito grande pode diminuir o desempenho de um sistema. Você deve usar o valor mais baixo que atende aos seus requisitos de desempenho. Normalmente, valores maiores que 3 ou 4 não melhoram a taxa de transferência de dados. Mas valores mais altos podem reduzir a latência ou a chance de dados ausentes em um pipe de alta frequência.