estrutura _URB_ISOCH_TRANSFER (usb.h)

Artigo
02/26/2024

A estrutura _URB_ISOCH_TRANSFER é usada por drivers de cliente USB para enviar dados ou recuperar dados de um pipe de transferência isócrona.

Sintaxe

struct _URB_ISOCH_TRANSFER {
  struct _URB_HEADER         Hdr;
  USBD_PIPE_HANDLE           PipeHandle;
  ULONG                      TransferFlags;
  ULONG                      TransferBufferLength;
  PVOID                      TransferBuffer;
  PMDL                       TransferBufferMDL;
  struct _URB                *UrbLink;
  struct _URB_HCD_AREA       hca;
  ULONG                      StartFrame;
  ULONG                      NumberOfPackets;
  ULONG                      ErrorCount;
  USBD_ISO_PACKET_DESCRIPTOR IsoPacket[1];
};

Membros

Hdr

Um ponteiro para uma estrutura _URB_HEADER que especifica as informações de cabeçalho URB. Hdr.Function deve ser URB_FUNCTION_ISOCH_TRANSFER e Hdr.Length deve ter o tamanho dessa estrutura de dados de comprimento variável.

PipeHandle

Especifica um identificador opaco para o pipe isocrono. O driver do controlador de host retorna esse identificador quando o driver do cliente seleciona a configuração do dispositivo com um URB do tipo URB_FUNCTION_SELECT_CONFIGURATION ou quando o driver cliente altera as configurações de uma interface com um URB do tipo URB_FUNCTION_SELECT_INTERFACE.

TransferFlags

Especifica zero, um ou uma combinação dos seguintes sinalizadores:

Valor	Significado
USBD_TRANSFER_DIRECTION_IN	É definido para solicitar dados de um dispositivo. Para transferir dados para um dispositivo, esse sinalizador deve estar claro.
USBD_SHORT_TRANSFER_OK	É definido para direcionar o controlador de host para não retornar um erro quando ele recebe um pacote do dispositivo que é menor que o tamanho máximo do pacote para o ponto de extremidade. Esse sinalizador não tem efeito em um pipe isócrono, pois o motorista do ônibus não retorna um erro quando recebe pacotes curtos em um pipe isócrono.
USBD_START_ISO_TRANSFER_ASAP	Faz com que a transferência comece no próximo quadro, se nenhuma transferência tiver sido enviada para o pipe desde que o pipe foi aberto ou a última redefinição. Caso contrário, a transferência começa no primeiro quadro que segue todas as solicitações enfileiradas no momento para o pipe. O quadro real em que a transferência começa será ajustado para latência do barramento pelo driver do controlador de host.

TransferBufferLength

Especifica o comprimento, em bytes, do buffer especificado em TransferBuffer ou descrito em TransferBufferMDL. O driver do controlador host retorna o número de bytes enviados ou lidos do pipe neste membro.

TransferBuffer

Um ponteiro para um buffer residente para a transferência será NULL se um MDL for fornecido em TransferBufferMDL. O conteúdo desse buffer depende do valor de TransferFlags. Se USBD_TRANSFER_DIRECTION_IN for especificado, esse buffer conterá dados lidos do dispositivo no retorno do driver do controlador host. Caso contrário, esse buffer contém dados fornecidos pelo driver para transferência para o dispositivo.

TransferBufferMDL

Um ponteiro para um MDL que descreve um buffer residente será NULL se um buffer for fornecido no TransferBuffer. O conteúdo do buffer depende do valor de TransferFlags. Se USBD_TRANSFER_DIRECTION_IN for especificado, o buffer descrito conterá dados lidos do dispositivo no retorno do driver do controlador host. Caso contrário, o buffer contém dados fornecidos pelo driver para transferência para o dispositivo. Esse MDL deve ser alocado do pool nãopagado.

UrbLink

Reservado. Não use.

hca

Reservado. Não use.

StartFrame

Especifica o número do quadro em que a transferência deve começar. Essa variável deve estar dentro de um intervalo definido pelo sistema do quadro atual. O intervalo é especificado pela constante USBD_ISO_START_FRAME_RANGE.

Se START_ISO_TRANSFER_ASAP estiver definido em TransferFlags, esse membro conterá o número do quadro em que a transferência começou, quando a solicitação é retornada pelo driver do controlador host. Caso contrário, esse membro deverá conter o número de quadro no qual essa transferência começa.

NumberOfPackets

Especifica o número de pacotes descritos pelo membro da matriz de comprimento variável IsoPacket.

ErrorCount

Contém o número de pacotes que foram concluídos com uma condição de erro no retorno do driver do controlador de host.

IsoPacket[1]

Contém uma matriz de comprimento variável de estruturas de USBD_ISO_PACKET_DESCRIPTOR que descrevem os pacotes de transferência isócronos a serem transferidos no barramento USB. Para obter mais informações sobre esse membro, consulte a seção Comentários.

Comentários

O driver de barramento USB sempre retorna um valor de USBD_STATUS_SUCCESS em Hdr.Status, a menos que cada pacote na transferência tenha gerado um erro ou a solicitação não tenha sido bem formada e não possa ser executada. A tabela a seguir inclui possíveis códigos de erro retornados em Hdr.Status.

Valor do erro	Significado
USBD_STATUS_ISOCH_REQUEST_FAILED	Indica que cada pacote de uma solicitação isocrona foi concluído com erros.
USBD_STATUS_BAD_START_FRAME	Indica que o quadro inicial solicitado não está dentro USBD_ISO_START_FRAME_RANGE do quadro USB atual.
USBD_ISO_NOT_ACCESSED_LATE	Indica que cada pacote foi enviado tarde demais para o pacote ser enviado, com base no quadro inicial solicitado.
USBD_STATUS_INVALID_PARAMETER	Indica que um dos parâmetros URB estava incorreto.

Antes que o controlador de host envie uma solicitação isócrona para um dispositivo USB, ele requer informações sobre o ponto de extremidade do dispositivo para o qual ele deve enviar ou receber dados. Essas informações são armazenadas em descritores de ponto de extremidade (USB_ENDPOINT_DESCRIPTOR) recuperados do descritor de configuração selecionado. Depois que o driver de barramento obtém o descritor de ponto de extremidade, ele cria um pipe de transferência isócrono para configurar a transferência de dados. Os atributos do pipe são armazenados na estrutura USBD_PIPE_INFORMATION . Para transferências isocronas, os membros são definidos da seguinte maneira:

O membro PipeType especifica o tipo de transferência e é definido como UsbdPipeTypeIsochronous.
O membro MaximumPacketSize especifica a quantidade de dados, em bytes, que constitui um pacote. Para transferências isocronas, o tamanho do pacote é fixo e pode ser um valor de 0 a 1024. O tamanho do pacote é igual ou menor que o valor wMaxPacketSize do descritor de ponto de extremidade.
O membro Interval é derivado do valor bInterval do descritor de ponto de extremidade. Esse valor é usado para calcular o período de sondagem que indica a frequência em que os dados são enviados no barramento. Para dispositivos de velocidade total, o período é medido em unidades de 1 milissegundos de quadros; para dispositivos de alta velocidade, o período é medido em microframes.

O controlador host também determina a quantidade de dados que podem ser transferidos (dentro de um quadro ou um microframe) dependendo do tipo de dispositivo. Essas informações estão disponíveis nos bits 12.. 11 de wMaxPacketSize no descritor de ponto de extremidade.

Para dispositivos de velocidade total, apenas um pacote pode ser transferido dentro de um quadro; os bits 12.. 11 são reservados e definidos como zero.

Para dispositivos de alta velocidade, os dados podem ser transferidos em um único pacote ou podem abranger vários pacotes, dentro de um microframe. Se os bits 12.. 11 estiverem definidos como n, você poderá transferir (n+1)*MaximumPacketSize bytes por microframe. Os bits 12.. 11 definidos como zero indicam que apenas um pacote pode ser transferido em um microframe. Se os bits 12.. 11 estiverem definidos como 1, o controlador host poderá transferir dois pacotes em um microframe.

O membro IsoPacket do _URB_ISOCH_TRANSFER é uma matriz de USBD_ISO_PACKET_DESCRIPTOR que descreve o layout do buffer de transferência. Cada elemento na matriz correlaciona-se aos dados transferidos em um microframe. Se IsoPacket tiver n elementos, as transferências do controlador host usarão n quadros (para dispositivos de velocidade total) ou microframes (para dispositivos de alta velocidade) para transferir dados. O IsoPacket[i]. O membro offset é usado para acompanhar a quantidade de dados a serem enviados ou recebidos. Isso é feito definindo um deslocamento de bytes desde o início de todo o buffer de transferência para a solicitação.

Por exemplo, há cinco microframes disponíveis para transferir pacotes do tamanho de 1024 bytes.

Se os bits 12.. 11 estiverem definidos como zero (indicando um único pacote por transferência de microframe), IsoPacket conterá as seguintes entradas:

Microframe 1 IsoPacket.Element[0].Offset = 0 (endereço inicial)

Microframe 2 IsoPacket.Element[1].Offset = 1024

Microframe 3 IsoPacket.Element[2].Offset = 2048

Microframe 4 IsoPacket.Element[3].Offset = 3072

Microframe 5 IsoPacket.Element[4].Offset = 4096

Se os bits 12.. 11 estiverem definidos como 1 (indicando dois pacotes por microframe), IsoPacket conterá as seguintes entradas:

Microframe 1 IsoPacket.Element[0].Offset = 0 (endereço inicial)

Microframe 2 IsoPacket.Element[1].Offset = 2048

Microframe 3 IsoPacket.Element[2].Offset = 4096

Microframe 4 IsoPacket.Element[3].Offset = 6144

Microframe 5 IsoPacket.Element[4].Offset = 8192

Nota Para vários pacotes, o valor de deslocamento indica tamanhos para todos os pacotes dentro do microframe.

O IsoPacket[i]. O membro length é atualizado pelo controlador de host para indicar o número real de bytes recebidos do dispositivo para transferências IN isócronas. IsoPacket[i]. O comprimento não é usado para transferências OUT isócronas.

Os drivers podem usar a macro GET_ISO_URB_SIZE para determinar o tamanho necessário para manter todo o URB. Se o comprimento for muito pequeno para preencher o espaço reservado para esse pacote, o motorista do barramento deixará uma lacuna do final dos dados recuperados para o deslocamento para o próximo pacote. O motorista do ônibus não ajustará os deslocamentos para evitar o perda de espaço no buffer.

Os membros TransferBuffer ou TransferBufferMDL devem especificar um buffer virtualmente contíguo.

Trate outros membros que fazem parte dessa estrutura, mas não descritos aqui como opacos. Eles são reservados para uso do sistema.