USB Video Class Extension Units 阅读笔记1（概念+架构）

USB Video Class Extension Units

This section provides guidelines for writing user-mode plug-ins to extend USB Video Class devices. By using a user-mode plug-in, you can expose extended device functionality as a COM application programming interface (API) in a standard way.

This section includes the following topics:

Introduction to USB Video Class Extension Units

Device Requirements for USB Video Class Extension Units

Extension Unit Plug-In Architecture

UVC Extension Unit Code Samples

Device Requirements for USB Video Class Extension Units

This section describes some specific requirements for implementing an Extension Unit in the device. If these requirements are not met, the USB Video Class driver might not work correctly with the Extension Unit.

Descriptor

The Extension Unit descriptor must contain a valid, unique GUID. This GUID is used by Usbvideo.sys to expose a property set on the corresponding extension node. You should create a unique GUID for the Extension Unit by using a tool named Guidgen.exe that is included with the Microsoft Windows SDK.

 

Property identifiers on the Extension Unit property set (KSPROPERTY_EXTENSION_UNIT) correspond to similarly numbered extension unit control IDs exposed by the USB Video Class firmware.  Extension unit controls can be accessed by using standard KSPROPERTY requests through the IKsControl interface.

 

浅 Property identifiers

 

The controls on the Extension Unit, known as extension unit control IDs, must be numbered continuously from 1 to some maximum value n. If there are gaps, the USB Video Class driver does not expose the controls that lie beyond the gap. The current implementation of the USB Video Class driver limits the number of controls on an Extension Unit to 31.

 

ps:unit计数

 

Use Property ID=0 (KSPROPERTY_EXTENSION_UNIT_INFO) to get part of the extension unit descriptor, the syntax for which is defined by the Universal Serial Bus Device Class Definition for Video Devices Specification. This specification is available at the USB Implementers Forum website.

 

ps:id=0 <--->get

 

Use Property ID=1 and higher to send requests to the corresponding extension unit control.

 

 

Be aware that KSPROPERTY_EXTENSION_UNIT_CONTROL (Property ID=1) is not a real property. Instead, it denotes that identifiers 1 and higher refer to actual extension unit control IDs.

 

浅

 

KSPROPERTY_EXTENSION_UNIT_PASS_THROUGH (Property ID=0xffff) is not implemented.

 

The following code example, taken from the complete sample shown in the Sample Extension Unit Plug-in DLL, shows how to make a KSPROPERTY_EXTENSION_UNIT_INFO request:

 

ps:发送get请求

ExtensionProp.Property.Set = PROPSETID_VIDCAP_EXTENSION_UNIT;
    ExtensionProp.Property.Id = KSPROPERTY_EXTENSION_UNIT_INFO;//【】
    ExtensionProp.Property.Flags = KSPROPERTY_TYPE_GET | 
                                   KSPROPERTY_TYPE_TOPOLOGY;
    ExtensionProp.NodeId = m_dwNodeId;

    hr = m_pKsControl->KsProperty(
        (PKSPROPERTY) &ExtensionProp,
                  sizeof(ExtensionProp),
        (PVOID) pInfo,
        ulSize,
        &ulBytesReturned);

        return hr;
}

 

Control Requests

The device must support GET_CUR, GET_INFO, GET_LEN, GET_MIN, GET_MAX, GET_DEF, and GET_RES requests for all Extension Unit controls according to the USB Video Class specification. If your device does not implement these functions, the corresponding properties will not be exposed to user mode.

ps:设备相应的需求有

get_cur

get_info

get_len'

get_min

get_max

get_def

get_res

During device initialization, the driver issues the following control requests to the device: GET_INFO, GET_LEN, GET_MIN and GET_MAX. If any of these initial requests fail, Usbvideo.sys disables the particular control.

 

 ps:设想在抓包的时候，将会在初始时抓到以上四种报文。

 

The value returned by GET_INFO tells the driver which GET and SET requests are valid for a given control. In addition, GET_INFO tells the driver whether the control is asynchronous. Asynchronous requests are supported by Status Interrupt Endpoints.

 

ps:get_info命令字的细节

 

Extension Unit Plug-In Architecture

 

The USB Video Class driver exposes Extension Units as nodes in the USB Video KS proxy filter. The Extension Unit controls are further exposed in user mode as a property set on the node, which is of type KSNODETYPE_DEV_SPECIFIC. The GUID of the property set matches the GUID of the Extension Unit descriptor.

 

ps:浅 反复

 

The individual Extension Unit controls should be continuously numbered from 1 to some maximum value n. These controls are directly mapped to property identifiers (IDs) on the Extension Unit property set, and they can be accessed by using standard KSPROPERTY requests through IKsControl.

 

 

In response to property requests from applications, the UVC driver returns property values that have the MembersFlags member of the KSPROPERTY_MEMBERSHEADER structure set exclusively to KSPROPERTY_MEMBER_RANGES. UVC does not support stepped ranges or extension unit default values of arbitrary length.

 

 

To expose Extension Unit properties to an application, you can write a user-mode plug-in DLL that exposes a COM API. You can implement this API by making requests to the KS property set by using the IKsControl interface. Vidcap.ax automatically loads the node interface plug-in based on certain registry entries. An application can access the interface by using IKsTopologyInfo::CreateNodeInstance followed by a call to QueryInterface on the node object to obtain the required COM API.

 

ps:反复出现IKsControl

 

 

The following elements are required to write and use an Extension Unit plug-in:

• A header and cpp file implementing the Extension Unit API and an interface named IKsNodeControl. Vidcap.ax uses the IKsNodeControl interface to inform the plug-in of the extension node identifier and provide it with an instance of IKsControl. Sample code for these files can be found in Sample Extension Unit Plug-in DLL.

• An .rgs file that registers the node interfaces and Class IDs (CLSIDs) under the HKLM\System\CCS\Control\NodeInterfaces\Property_Set_GUID registry subkey. The entries in this registry subkey contain the binary values for the Interface ID (IID) and CLSID. For more information, see Sample Registry Entry for UVC Extension Units.

• An application that invokes this interface. The application first creates a node instance with the correct node ID by using IKsTopologyInfo::CreateNodeInstance. The application then calls QueryInterface on the node instance to obtain the required Extension Unit interface. For more information, see Sample Application for UVC Extension Units and Supporting Autoupdate Events with Extension Units

ps:应用过程

 

The code examples in this section illustrate all of these elements. See Building the Extension Unit Sample Control to learn how to build the sample plug-in and ass

ociated sample application code.

 

 

After the plug-in DLL is registered and the registry entries described above are provided, Vidcap.ax automatically loads the relevant node interfaces when the node instance is created.

 

Note   As of Windows XP SP2, the Extension Unit property set is supported only on the node, and not on the filter.

 

Registry Considerations

To register the IID and CLSID of the interface exported by the plug-in, you can use DLL registration or a device-specific setup information (INF) file.

See Sample Registry Entry for UVC Extension Units for a sample .rgs file that shows the required values for the registry entries. This topic also demonstrates how to write a device-specific INF file to install a USB video device and to register the plug-in DLL. You may choose either DLL registration or a device-specific INF file, based on your specific needs.

 

ps:测试权限

 

Schematic

The following schematic diagram shows the relationships between the various modules involved in writing and using an Extension Unit plug-in. In particular it traces the connection from the application, to the plug-in DLL, down to the driver and finally to the Extension Unit on the device itself. The schematic also illustrates the various GUIDs involved; identical values are highlighted by the use of a matching color.

 

 

ps：架构图。

 

Eventing Mechanisms

 

The USB Video Class supports auto-update events, where the device notifies the host driver of changes in any of its controls. The Microsoft USB Video Class driver supports this concept by letting applications register for auto-update events. The process of getting updates involves three steps:

1. Registering for update events by using KSEVENTSETID_VIDCAPNotify::KSEVENT_VIDCAP_AUTO_UPDATE

2. Listening for events on the notify event handle

3. Canceling the notification when done

ps:auto-update 暂时不深入