Cómo seleccionar una configuración alternativa en una interfaz USB

En este tema se describen los pasos para emitir una solicitud de interfaz de selección para activar una configuración alternativa en una interfaz USB. El controlador cliente debe emitir esta solicitud después de seleccionar una configuración USB. Al seleccionar una configuración, de forma predeterminada, también se activa la primera configuración alternativa en cada interfaz de esa configuración.

Cada configuración USB debe admitir una o varias interfaces USB. Cada interfaz expone uno o varios puntos de conexión que se usan para transferir datos hacia y desde el dispositivo. Las interfaces USB deben tener un índice de interfaz definido por el dispositivo que se usa para identificar la interfaz. La interfaz también debe tener una o varias configuraciones alternativas que agrupe los puntos de conexión de la interfaz. Como parte de la configuración del dispositivo, el controlador cliente debe seleccionar una de las opciones alternativas en la interfaz. Dado que los puntos de conexión se pueden compartir entre configuraciones alternativas, solo se puede activar una configuración en un momento dado. Una vez activa la configuración alternativa, sus puntos de conexión estarán disponibles para las transferencias de datos.

Para un dispositivo de interfaz múltiple, dos interfaces pueden estar activas en un momento dado. El controlador cliente debe activar una configuración alternativa en cada interfaz. Los puntos de conexión no se comparten entre interfaces y, por lo tanto, cada transferencia de datos simultánea se puede realizar en cada interfaz.

La configuración alternativa es definida por el dispositivo y se identifica con un número denominado índice de configuración. La configuración alternativa en el índice 0 se denomina configuración alternativa predeterminada en este conjunto de documentación. Una configuración alternativa se describe en una estructura de USB_INTERFACE_DESCRIPTOR . La estructura contiene el índice de interfaz con el que está asociado la configuración y el número de puntos de conexión definidos por la configuración. También contiene información sobre la especificación de clase a la que se ajusta la funcionalidad de la interfaz. La forma en que se agrupan los puntos de conexión depende de la funcionalidad del dispositivo.

Por ejemplo, una interfaz expone dos puntos de conexión isócronos y dos extremos masivos a través de tres configuraciones alternativas (índice 0, 1, 2). La configuración alternativa 0 no define ningún punto de conexión; La configuración alternativa 1 define los puntos de conexión masivos; La configuración alternativa 2 define los puntos de conexión isócronos. Dado que la configuración alternativa 0 no tiene ningún punto de conexión, el controlador de cliente puede seleccionar esta configuración para deshabilitar la transferencia de datos con el fin de conservar el ancho de banda. Cuando cualquiera de las demás opciones de configuración está activa, el dispositivo está listo para las transferencias de datos. La configuración alternativa 1 se puede usar para transferir datos masivos. Se puede seleccionar la configuración alternativa 2 cuando el dispositivo está en modo de streaming. Por lo tanto, la configuración alternativa proporciona al controlador cliente la flexibilidad de cambiar la configuración del dispositivo como y cuando sea necesario. En este ejemplo, el controlador cliente puede cambiar la funcionalidad del dispositivo de una transferencia masiva a streaming, simplemente seleccionando una configuración alternativa.

También se puede usar una configuración alternativa para establecer los requisitos de ancho de banda. Para obtener un ejemplo, consulte el diseño del dispositivo USB.

Windows Driver Foundation (WDF) proporciona métodos en el marco del controlador del modo kernel y en el marco del controlador en modo de usuario que el controlador cliente puede llamar para seleccionar una configuración alternativa diferente. El controlador cliente kmdf puede seleccionar una configuración especificando el índice de configuración, el descriptor de interfaz de la configuración o enviando un URB que contenga la solicitud. El controlador de cliente UMDF solo puede seleccionar una configuración alternativa especificando su índice de configuración.

Una vez completada correctamente una solicitud de selección de configuración, se desactiva la configuración alternativa activa anteriormente.

Lo que necesita saber

En este artículo se usan los siguientes marcos:

• Marco de controlador en modo kernel
• Marco de controlador en modo de usuario

Antes de empezar

Antes de que el controlador cliente pueda seleccionar una configuración alternativa, asegúrese de que se cumplen estos requisitos:

• El controlador cliente debe haber creado el objeto de dispositivo de destino USB de marco.

  • Un controlador cliente KMDF debe obtener un identificador WDFUSBDEVICE llamando al método WdfUsbTargetDeviceCreateWithParameters . Para obtener más información, vea "Código fuente del dispositivo" en Descripción de la estructura de código del controlador de cliente USB (KMDF).

  • Un controlador de cliente UMDF debe obtener un puntero IWDFUsbTargetDevice consultando el objeto de dispositivo de destino de la plataforma. Para obtener más información, consulte "IPnpCallbackHardware implementation and USB-specific tasks" (Implementación de IPnpCallbackHardware y tareas específicas de USB) en Descripción de la estructura de código del controlador de cliente USB (UMDF).

    Si usa las plantillas USB que se proporcionan con Microsoft Visual Studio Professional 2012, el código de plantilla realiza esas tareas. El código de plantilla obtiene el identificador del objeto de dispositivo de destino y almacena en el contexto del dispositivo.

• El dispositivo debe tener una configuración activa.

  • Un controlador cliente KMDF debe llamar al método WdfUsbTargetDeviceSelectConfig .

  • En el caso de un controlador cliente UMDF, el marco selecciona la primera configuración y la configuración alternativa predeterminada para cada interfaz de esa configuración.

    Si usa plantillas USB, el código selecciona la primera configuración y la configuración alternativa predeterminada en cada interfaz.

Seleccionar una configuración alternativa en un controlador cliente kmdf

1. Obtiene un identificador WDFUSBINTERFACE en la interfaz que tiene la configuración alternativa.

   Para obtener el identificador, primero obtenga el número de interfaces de la configuración seleccionada mediante una llamada a WdfUsbTargetDeviceGetNumInterfaces y, a continuación, enumerar interfaces en un bucle. En cada iteración, llame al método WdfUsbTargetDeviceGetInterface e incremente el índice (a partir de cero).

   Nota Durante la enumeración del dispositivo, la pila del controlador USB asigna números a la configuración alternativa. Los números de interfaz son de base cero y secuenciales. Esos números pueden ser diferentes al índice de configuración definido por el dispositivo. Para obtener el índice de configuración definido por el dispositivo, llame al método WdfUsbInterfaceGetInterfaceNumber .

2. Inicie una solicitud select-interface llamando al método WdfUsbInterfaceSelectSetting . En el parámetro Params de la llamada, elija una de estas opciones:

   • Especifique el número de configuración alternativo asignado por la pila de controladores USB. Normalmente, se pasa el mismo índice que usó en el paso 1 para enumerar la configuración.

   • Especifique un puntero al descriptor de interfaz que describe la configuración alternativa. A continuación, el controlador puede obtener descriptores de interfaz al enumerar la configuración alternativa en la interfaz llamando al método WdfUsbInterfaceGetDescriptor . Una vez completada la enumeración, el controlador obtiene información sobre todas las configuraciones alternativas enumeradas en la estructura USB_INTERFACE_DESCRIPTOR .

   • Especifique un puntero a un URB que contenga toda la información necesaria para la solicitud select-interface.

     1. Asigne una matriz de estructuras de USBD_INTERFACE_LIST_ENTRY . El número de elementos de esta matriz depende del número de interfaces de la configuración seleccionada. Para obtener información sobre cómo inicializar esta matriz, vea Cómo seleccionar una configuración para un dispositivo USB.
     2. Asigne un URB para la solicitud de interfaz de selección llamando a la rutina USBD_SelectInterfaceUrbAllocateAndBuild . En esta llamada, especifique la matriz de lista de interfaz y el identificador de configuración que se obtuvo después de seleccionar una configuración. Puede obtener ese identificador llamando al método WdfUsbTargetDeviceWdmGetConfigurationHandle .
     3. Llame a WdfUsbInterfaceSelectSetting y especifique el URB.

     **Controladores WDM:**Para enviar el URB, asocie el URB a un IRP y envíe el IRP a la pila del controlador USB. Para obtener más información, vea Cómo enviar un URB.

   Las opciones de la lista proporcionan al controlador cliente la flexibilidad necesaria para especificar los criterios de selección. Si ya conoce las funcionalidades del punto de conexión de la configuración alternativa, elija la primera opción (con el número de configuración alternativo) en la lista. De lo contrario, elija la segunda opción que especifica el descriptor de interfaz. Inspeccione USB_INTERFACE_DESCRIPTOR estructuras para todas las configuraciones alternativas. Para cada configuración, enumere sus puntos de conexión y sus características, como, el tipo de punto de conexión, el tamaño máximo del paquete, etc. Cuando encuentre el conjunto de puntos de conexión que necesita para las transferencias de datos, llame a WdfUsbInterfaceSelectSetting especificando un puntero a ese descriptor de interfaz. Normalmente, no necesitará la tercera opción a menos que sea un controlador cliente basado en WDM que solo pueda enviar solicitudes a la pila de controladores USB mediante el envío de direcciones URL.

   En función de la información proporcionada por el controlador cliente, la pila del controlador USB compila una solicitud de control estándar (SET INTERFACE) y la envía al dispositivo. Si la solicitud se completa correctamente, la pila del controlador USB obtiene los identificadores de canalizaciones a los puntos de conexión de la configuración alternativa.

   Después de seleccionar una configuración alternativa, el controlador cliente siempre debe obtener los identificadores de canalización de los puntos de conexión en la nueva configuración. Si no lo hace, el controlador podría enviar solicitudes de transferencia de datos mediante identificadores de canalización obsoletos. Para obtener información sobre cómo recuperar identificadores de canalización, vea Cómo enumerar canalizaciones USB.

NTSTATUS  FX3SelectInterfaceSetting(  
    _In_ WDFDEVICE Device,
    _In_ UCHAR SettingIndex)

{
    NTSTATUS                 status;  
    PDEVICE_CONTEXT          pDeviceContext;  
    WDF_OBJECT_ATTRIBUTES               pipeAttributes;

    WDF_USB_INTERFACE_SELECT_SETTING_PARAMS settingParams;

    PAGED_CODE();  

    pDeviceContext = GetDeviceContext(Device);

    if (pDeviceContext->UsbInterface == NULL)
    {
        status = USBD_STATUS_BAD_NUMBER_OF_INTERFACES;
        goto Exit;
    }

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&pipeAttributes, PIPE_CONTEXT);  

    pipeAttributes.EvtCleanupCallback = FX3EvtPipeContextCleanup;

    WDF_USB_INTERFACE_SELECT_SETTING_PARAMS_INIT_SETTING (&settingParams, SettingIndex);

    status = WdfUsbInterfaceSelectSetting (
        pDeviceContext->UsbInterface,
        &pipeAttributes,
        &settingParams);

    if (status != STATUS_SUCCESS)
    {
        goto Exit;
    }

    if (WdfUsbInterfaceGetNumConfiguredPipes (pDeviceContext->UsbInterface) > 0)
    {
        status = FX3EnumeratePipes (Device);

        if (status != STATUS_SUCCESS)
        {
            goto Exit;
        }
    }

Exit:
    return status;
}

Seleccionar una configuración alternativa en un controlador cliente umdf

1. Obtenga el número de interfaces USB que admite la configuración activa mediante una llamada al método IWDFUsbTargetDevice::GetNumInterfaces .

2. Obtiene un puntero IWDFUsbInterface para cada interfaz de la configuración.

   Para enumerar todas las interfaces, llame al método IWDFUsbTargetDevice::RetrieveUsbInterface en un bucle hasta que la función devuelva NULL. Con cada iteración, incremente el índice de miembro (basado en cero). El bucle recupera punteros IWDFUsbInterface a todas las interfaces enumeradas.

3. Para cada interfaz, obtenga el identificador winUSB llamando a IWDFUsbInterface::GetWinUsbHandle. El siguiente paso requiere este identificador.

4. Llame a WinUsb_GetAssociatedInterface para obtener un identificador de la interfaz. En el parámetro AssociatedInterfaceIndex , especifique el índice en el paso 2.

5. Determine el número de configuraciones alternativas en la interfaz.

   Llame a la función WinUsb_QueryInterfaceSettings en un bucle e incremente el índice (basado en cero) en cada iteración. Cuando se enumeran todas las configuraciones, la función devuelve ERROR_NO_MORE_ITEMS. La función también devuelve descriptores de interfaz para cada configuración.

6. Mediante el uso del valor recibido en el miembro bNumEndpoints de cada descriptor de interfaz y enumera sus puntos de conexión. Inspeccione los descriptores de punto de conexión y determine qué configuración cumple sus necesidades.

7. Inicie una solicitud select-interface mediante una llamada a la función WinUsb_SetCurrentAlternateSetting . En la llamada, especifique el número de configuración alternativo asociado al índice en el paso 4.

8. Libere el identificador de interfaz obtenido en el paso 4 llamando a la función WinUsb_Free .

9. Libere el identificador winUSB obtenido en el paso 3 llamando a la función WinUsb_Free .

10. Si ha terminado de usar métodos IWDFUsbInterface , libere todos los punteros de interfaz recuperados en el paso 2.

Comentarios

Para un controlador de cliente KMDF, en su llamada WdfUsbInterfaceSelectSetting , el controlador puede proporcionar un puntero a un contexto de canalización definido por el controlador. El controlador cliente puede almacenar información sobre las canalizaciones en el contexto de canalización. Para obtener más información sobre la canalización, vea Cómo enumerar canalizaciones USB.

Temas relacionados

• Configuración del dispositivo USB