Compartir vía

Funciones winUSB para la modificación de directivas de canalización

  • Artículo

Para permitir que las aplicaciones obtengan y establezcan los parámetros de directiva predeterminados de una canalización de punto de conexión, Winusb.dll expone la función WinUsb_GetPipePolicy para recuperar la directiva predeterminada de la canalización. La función WinUsb_SetPipePolicy permite a una aplicación establecer el parámetro de directiva en un nuevo valor.

WinUSB permite modificar su comportamiento predeterminado aplicando directivas a la canalización de un punto de conexión. Con estas directivas, puedes configurar WinUSB para que coincida mejor con tu dispositivo con sus funcionalidades. En la tabla siguiente se proporciona una lista de las directivas de canalización compatibles con WinUSB.

Nota:

Las directivas descritas en la tabla solo son válidas para los puntos de conexión especificados. Establecer la directiva en otros puntos de conexión no tiene ningún efecto en el comportamiento de WinUSB para las solicitudes de lectura o escritura.

Número de póliza Nombre de directiva Descripción Punto de conexión (dirección) Valor predeterminado
0x01 SHORT_PACKET_TERMINATE Envía un paquete de longitud cero para una solicitud de escritura en la que el búfer es un múltiplo del tamaño máximo de paquete admitido por el punto de conexión. Bulk (OUT)

Interrupción (OUT)		 FALSO
0x02 AUTO_CLEAR_STALL Borra automáticamente una canalización estancada sin detener el flujo de datos. Bulk (IN)

Interrupción (IN)		 FALSO
0x03 PIPE_TRANSFER_TIMEOUT Espera un intervalo de tiempo de espera, en milisegundos, antes de cancelar la solicitud. Bulk (IN)

Bulk (OUT)

Interrupción (IN)

Interrupción (OUT)		 5 segundos (5000 milisegundos) para el control; 0 para otros
0x04 IGNORE_SHORT_PACKETS Completa una solicitud de lectura cuando se recibe un paquete corto o se lee un número determinado de bytes. Si se desconoce el tamaño del archivo, la solicitud finaliza en un paquete corto. Bulk (IN)

Interrupción (IN)		 FALSO
0x05 ALLOW_PARTIAL_READS Permite las solicitudes de lectura de un dispositivo que devuelve más datos de los solicitados por el autor de la llamada. Bulk (IN)

Interrupción (IN)		 VERDADERO
0x06 AUTO_FLUSH Guarda los datos excesivos de la solicitud de lectura y los agrega a la siguiente solicitud de lectura o descarta el exceso de datos. Bulk (IN)

Interrupción (IN)		 FALSO
0x07 RAW_IO Omite la puesta en cola y el control de errores para aumentar el rendimiento de varias solicitudes de lectura. Bulk (IN)

Interrupción (IN)		 FALSO
0x08 MAXIMUM_TRANSFER_SIZE Obtiene el tamaño máximo de una transferencia USB compatible con WinUSB. Se trata de una directiva de solo lectura que se puede recuperar llamando a WinUsb_GetPipePolicy. Bulk (IN)

Bulk (OUT)

Interrupción (IN)

Interrupción (OUT)
0x09 RESET_PIPE_ON_RESUME Restablece la canalización del punto de conexión después de reanudarse de la suspensión antes de aceptar nuevas solicitudes. Bulk (IN)

Bulk (OUT)

Interrupción (IN)

Interrupción (OUT)		 FALSO

En la tabla siguiente se identifican los procedimientos recomendados para usar cada una de las directivas de canalización y se describe el comportamiento resultante cuando la directiva está habilitada.

Directiva Habilitar si... Comportamiento
SHORT_PACKET_TERMINATE(0x01) El dispositivo requiere que las transferencias OUT finalicen con un paquete de longitud cero. La mayoría de los dispositivos no tienen este requisito. Si está habilitado (el valor del parámetro de directiva es TRUE o distinto de cero), cada solicitud de escritura que sea un múltiplo del tamaño máximo de paquete admitido por el punto de conexión, va seguido de un paquete de longitud cero.

Después de enviar datos al controlador host, WinUSB envía una solicitud de escritura con un paquete de longitud cero y, a continuación, completa la solicitud creada por WinUsb_WritePipe.
AUTO_CLEAR_STALL No quiere que las transferencias con errores deje el punto de conexión en un estado detenido. Esta directiva solo es útil cuando tiene varias solicitudes de lectura pendientes al punto de conexión cuando RAW_IO está deshabilitada.
  • Si está habilitado (el valor del parámetro de directiva es TRUE o distinto de cero), se borra automáticamente una condición de parada. Este parámetro de directiva no afecta a las canalizaciones de control.

    Cuando se produce un error en una solicitud de lectura y el controlador de host devuelve un estado distinto de STATUS_CANCELLED o STATUS_DEVICE_NOT_CONNECTED, WinUSB restablece la canalización antes de completar la solicitud con error. Al restablecer la canalización se borra la condición de parada sin interrumpir el flujo de datos. Los datos continúan fluyendo en los puntos de conexión siempre que las nuevas transferencias sigan llegando desde el dispositivo. Una nueva transferencia puede incluir una que se encontraba en la cola cuando se produjo la parada.

    La habilitación de esta directiva no afecta significativamente al rendimiento.

  • Si está deshabilitado (el valor del parámetro de directiva es FALSE o cero), todas las transferencias que llegan al punto de conexión después de que se detenga la transferencia no se realicen hasta que el autor de la llamada restablezca manualmente la canalización del punto de conexión llamando a WinUsb_ResetPipe.
PIPE_TRANSFER_TIMEOUT Espera que las transferencias a un punto de conexión se completen dentro de un tiempo específico.
  • Si se establece en cero (valor predeterminado), las transferencias no agotarán el tiempo de espera porque el controlador de host no cancelará la transferencia. En este caso, la transferencia espera indefinidamente hasta que se cancele manualmente o la transferencia se complete normalmente.
  • Si se establece en un valor distinto de cero (intervalo de tiempo de espera), el controlador de host inicia un temporizador cuando recibe la solicitud de transferencia. Cuando el temporizador supera el intervalo de tiempo de espera establecido, se cancela la solicitud.

    Se produce una menor penalización de rendimiento debido a la administración del temporizador.

    Las solicitudes no agota el tiempo de espera en una cola de WinUSB.

    En Windows Vista, para todas las transferencias (excepto las transferencias con RAW_IO habilitado), WinUSB pone en cola la solicitud hasta que se hayan completado todas las transferencias anteriores en el punto de conexión de destino. El controlador de host no incluye el tiempo de puesta en cola en el cálculo del intervalo de tiempo de espera.

    Con RAW_IO habilitado, WinUSB no pone en cola la solicitud. En su lugar, pasa la solicitud directamente a la pila USB, si la pila USB está ocupada procesando transferencias anteriores. Si la pila USB está ocupada, puede retrasar el procesamiento de la nueva solicitud. Esto puede provocar un tiempo de espera.
IGNORE_SHORT_PACKETS RAW_IO está deshabilitado y no desea que los paquetes cortos completen las solicitudes de lectura.
  • Si está habilitado (el valor del parámetro de directiva es TRUE o distinto de cero), el controlador de host no completará una operación de lectura inmediatamente después de recibir un paquete corto. En su lugar, completa la operación solo si:
    • Se produce un error.
    • La solicitud se cancela.
    • Se han recibido todos los bytes solicitados.
  • Si está deshabilitado (el valor del parámetro de directiva es FALSE o cero), el controlador de host completa una operación de lectura después de leer el número solicitado de bytes o ha recibido un paquete corto.
ALLOW_PARTIAL_READS El dispositivo puede enviar más datos de los solicitados si el tamaño del búfer de solicitudes es un múltiplo del tamaño máximo del paquete de punto de conexión.

Use si la aplicación quiere leer unos pocos bytes para determinar cuántos bytes totales se van a leer.
  • Si está deshabilitado (el valor del parámetro de directiva es FALSE o cero) y el dispositivo devuelve más datos de los solicitados, WinUSB completa la solicitud con un error.
  • Si está habilitado (el valor del parámetro de directiva es TRUE o distinto de cero) y el dispositivo devuelve más datos de los solicitados, WinUSB puede (dependiendo de AUTO_FLUSH configuración) agregar los datos excesivos de la solicitud de lectura al principio de la siguiente solicitud de lectura o descartar los datos excesivos.

    Si está habilitado, WinUSB completa inmediatamente las solicitudes de lectura de cero bytes correctamente y no enviará las solicitudes a la pila.
AUTO_FLUSH ALLOW_PARTIAL_READS directiva está habilitada.

El dispositivo puede enviar más datos de los solicitados y la aplicación no requiere ningún otro dato. Esto es posible si el tamaño del búfer de solicitudes es un múltiplo del tamaño máximo del paquete de punto de conexión.		 AUTO_FLUSH define el comportamiento de WinUSB cuando ALLOW_PARTIAL_READS está habilitado. Si ALLOW_PARTIAL_READS está deshabilitado, WinUSB omite el valor de AUTO_FLUSH.

WinUSB puede descartar los datos restantes o enviarlos con la siguiente solicitud de lectura del autor de la llamada.

  • Si está habilitado (el valor del parámetro de directiva es TRUE o distinto de cero), WinUSB descarta los bytes adicionales sin ningún código de error.
  • Si está deshabilitado (el valor del parámetro de directiva es FALSE o cero), WinUSB guarda los bytes adicionales, los agrega al principio de la siguiente solicitud de lectura del autor de la llamada y, a continuación, envía los datos al autor de la llamada en la siguiente operación de lectura.
RAW_IO El rendimiento es una prioridad y la aplicación envía solicitudes de lectura simultáneas al mismo punto de conexión.

RAW_IO impone ciertas restricciones en el búfer que pasa el autor de la llamada en WinUsb_ReadPipe:

  • La longitud del búfer debe ser un múltiplo del tamaño máximo del paquete del punto de conexión.
  • La longitud debe ser menor o igual que el valor de MAXIMUM_TRANSFER_SIZE recuperado por WinUsb_GetPipePolicy.
 Si está habilitada, transfiere la omisión de la puesta en cola y el control de errores para aumentar el rendimiento de varias solicitudes de lectura. WinUSB controla las solicitudes de lectura de la siguiente manera:

  • Se produce un error en una solicitud que no es un múltiplo del tamaño máximo del paquete de punto de conexión.
  • Se produce un error en una solicitud mayor que el tamaño máximo de transferencia admitido por WinUSB.
  • Todas las solicitudes bien formadas se envían inmediatamente a la pila del núcleo USB que se va a programar en el controlador host.


Habilitar esta configuración mejora significativamente el rendimiento de varias solicitudes de lectura al reducir el retraso entre el último paquete de una transferencia y el primer paquete de la siguiente transferencia.
RESET_PIPE_ON_RESUME El dispositivo no conserva su estado de alternancia de datos en la suspensión. Al reanudar desde la suspensión, WinUSB restablece el punto de conexión antes de permitir que el autor de la llamada envíe nuevas solicitudes al punto de conexión.