Edit

Create device property keys from the MS OS descriptor in USB Video Class (UVC) camera firmware

  • Article

In the past, manufacturers of USB Video Class (UVC) cameras had to author custom INF files to provide functionality such as device property keys. For simple registry keys, the USBVideo driver has a mechanism for creating registry keys from the MS OS descriptor if the key name in question is prefaced with UVC-. This expands that functionality in the USBVideo driver to also create device property keys from an MS OS descriptor if it follows a specific format. This allows the USBVideo camera firmware to reach feature parity with a MIPI camera driver without authoring a custom INF for those cameras.

Note

If the same device property key is defined in a custom INF, it will override the value provided by the MS OS descriptor.

Applies to

  • Windows 11 and later operating systems

MS OS 2.0 registry property descriptor

The current MS OS 2.0 registry property descriptor is defined as follows:

Offset Field Size Description
0 wLength 2 Length, in bytes, of this descriptor.
2 wDescriptorType 2 MS_OS_20_FEATURE_REG_PROPERTY
4 wPropertyDataType 2 Type of registry property
6 wPropertyNameLength 2 Length of the property name.
8 PropertyName Variable Name of registry property.
8+M wPropertyDataLength 2 Length of property data
10+M PropertyData Variable Property data

wPropertyDataType values for the MS OS 2.0 registry property descriptor

The following table describes wPropertyDataType values for the MS OS 2.0 registry property descriptor:

Value Description
0 RESERVED
1 NULL-terminated Unicode String (REG_SZ)
2 NULL-terminated Unicode String that includes environment variables (REG_EXPAND_SZ)
3 Free-form binary (REG_BINARY)
4 Little-endian 32-bit integer (REG_DWORD_LITTLE_ENDIAN)
5 Big-endian 32-bit integer (REG_DWORD_BIG_ENDIAN)
6 NULL-terminated Unicode string that contains a symbolic link (REG_LINK)
7 Multiple NULL-terminated Unicode strings (REG_MULTI_SZ)
8 and higher RESERVED

The USBVideo driver will currently copy all MS OS descriptors that have a prefix of UVC- as registry variable names to each device interface node. These are straight one-to-one copies of one registry key to another, removing the UVC- prefix. For device property keys, additional information is required. For defining a device property key, there needs to be a defined GUID and ID. Additionally, each key requires a corresponding data type and value for that data. For this feature, the USBVideo driver will map a registry value and type to a DEVPROPTYPE.

Possible Registry Types

Registry Value Description DEVPROPTYPE value Description
1 REG_SZ DEVPROP_TYPE_STRING Null-terminated string
2 REG_EXPAND_SZ NA Not supported
3 REG_BINARY DEVPROP_TYPE_BINARY Custom binary data
4 REG_DWORD_LITTLE_ENDIAN DEVPROP_TYPE_UINT32 32-bit unsigned int (ULONG32)
5 REG_DWORD_BIG_ENDIAN NA Not supported
6 REG_LINK NA Not supported
7 REG_MULTI_SZ DEVPROP_TYPE_STRING_LIST Multi-sz string list

To determine that this device property key should be created, a new prefix will be defined. If a MS OS descriptor is found with the format of DKEY-<GUID>,<ID> then the USBVideo driver will attempt this creation. The registry value must be of one of the defined formats above (discarding and ignoring REG_LINK, REG_EXPAND_SZ, and REG_DWORD_BIG_ENDIAN). The format of GUID should be {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} and the format of the ID should be a numerical value greater than 2.

Example MS OS descriptor

The following example defines a MS OS descriptor:

UCHAR Example2_MSOS20DescriptorSet_UVCDevicePropertyKeyForFutureWindows\[0x3C\] =
{

//
// MS OS 2.0 Descriptor Set Header
//
0x0A, 0x00, // wLength - 10 bytes
0x00, 0x00, // MSOS20_SET_HEADER_DESCRIPTOR
0x00, 0x00, 0x0?, 0x06, // dwWindowsVersion – 0x060?0000 for future Windows version
0x76, 0x00, // wTotalLength – 118 bytes

//
// MS OS 2.0 Registry Value Feature Descriptor
//
0x6c, 0x00, // wLength - 108 bytes
0x04, 0x00, // wDescriptorType – 4 for Registry Property
0x04, 0x00, // wPropertyDataType - 4 for REG_DWORD_LITTLE_ENDIAN
0x5E, 0x00, // wPropertyNameLength – 94 bytes
'D', 0x00, 'K', 0x00, // Property Name – **DKEY-{4023440c-a74e-46e0-82df-e486fa545f40},3**
'E', 0x00, 'Y', 0x00,
'-', 0x00, '{', 0x00,
'4', 0x00, '0', 0x00,
'2', 0x00, '3', 0x00,
'4', 0x00, '4', 0x00,
'0', 0x00, 'C', 0x00,
'-', 0x00, 'A', 0x00,
'7', 0x00, '4', 0x00,
'E', 0x00, '-', 0x00,
'4', 0x00, '6', 0x00,
'E', 0x00, '0', 0x00,
'-', 0x00, '8', 0x00,
'2', 0x00, 'D', 0x00,
'F', 0x00, '-', 0x00,
'E', 0x00, '4', 0x00,
'8', 0x00, '6', 0x00,
'F', 0x00, 'A', 0x00,
'5', 0x00, '4', 0x00,
'5', 0x00, 'F', 0x00,
'4', 0x00, '0', 0x00,
'}', 0x00, ',', 0x00,
'3', 0x00, 0x00, 0x00,
0x00, 0x00,
0x04, 0x00, // wPropertyDataLength – 4 bytes
0xAC, 0x03, 0x00, 0x00 // PropertyData – 0x000003AC (940)
};

This would convert to the following device property key using IoSetDevicePropertyData with the following parameters:

DEVPROPKEY

    DEVPROPGUID = {4023440c-a74e-46e0-82df-e486fa545f40}

    DEVPROPID = 3

DEVPROPTYPE = DEVPROP_TYPE_UINT32

PropertyBuffer containing UINT32 value = 940