Introductiondownload.microsoft.com/.../ContainerIDs.docx · Web viewUnless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos,

Multifunction Device Support and Device Container Groupings in Windows 7

Guidelines for IHVs, OEMs, and Hardware Developers

July 15, 2009

Abstract

This white paper provides information about the multifunction device support and device container groupings for the Windows® 7 operating system. It provides guidelines that independent hardware vendors (IHVs) and original equipment manufacturers (OEMs) should follow when they design and develop new hardware for the Windows 7 platform.

The improved support for multifunction devices and device container grouping is discussed in detail, including the following: An overview of the architecture.

Algorithms and heuristics that the operating system uses to detect multifunction devices.

Recommendations to hardware and driver developers to ensure that their devices work well with Windows 7.

This information applies to the Windows 7 operating system.

References and resources discussed here are listed at the end of this paper.

The current version of this paper is maintained on the Web at:http://www.microsoft.com/whdc/Device/DeviceExperience/ContainerIDs.mspx

http://www.microsoft.com/whdc/Device/DeviceExperience/ContainerIDs.mspx

Container Groupings in Windows 7 - 2

Disclaimer: This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred.

© 2009 Microsoft Corporation. All rights reserved.

Microsoft, Windows, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Document HistoryDate ChangeJuly 15, 2009 Restored to original title of “Multifunction Device Support and

Device Container Groupings in Windows 7” from “Container Groupings in Windows 7”. No other text changed.

July 6, 2009 Additional details on using ACPI _RMV, _EJx and _PLD objects to affect the generation of ContainerID.

March 23, 2009 Changes to Universal Serial Bus Devices section to add information on using ACPI to affect the generation of ContainerID.

November 14, 2008 Brought into WHDC template and minor corrections made that did not affect content or meaning.

November 5, 2008 First publication

July 6, 2009© 2009 Microsoft Corporation. All rights reserved.


ContentsIntroduction...................................................................................................................4Terminology and Definitions..........................................................................................4Devices in Windows Vista versus Windows 7................................................................5Grouping Functionality from One Device: the ContainerID...........................................5

How a ContainerID Is Assigned.................................................................................6Generating a ContainerID from the Bus-Specific Unique Identifier..........................7

USB Devices...........................................................................................................7Bluetooth Devices...............................................................................................13PnP-X for Network-Connected Devices...............................................................141394 Devices.......................................................................................................16eSATA Devices.....................................................................................................16PCI Express Devices.............................................................................................17

Generating a ContainerID from the Removable Capability.....................................18The Difference Between Removable and SurpriseRemovalOK Capabilities...........21Including ContainerID Support in a Custom Bus Driver...........................................22

Setting the Removable Capability.......................................................................22Handling BusQueryContainerID..........................................................................23

Using ACPI to Indicate Device Container Grouping.................................................24How ACPI Objects Are Evaluated........................................................................24Using _RMV (Remove)........................................................................................26Using _EJx (Eject)................................................................................................26Using _PLD (Physical Location Description).........................................................27

Overriding the Removable Capability in Legacy Devices..............................................28DeviceOverrides Registry Key.................................................................................31“HardwareID” or “CompatibleID” Registry Key......................................................31LocationPaths Registry Key.....................................................................................32ChildLocationPaths Registry Key.............................................................................32* Registry Key..........................................................................................................32“LocationPath” Registry Key...................................................................................33Removable Registry Value......................................................................................34Device Override Examples.......................................................................................35

Verifying Correct Implementation of the ContainerID Property.................................40Devices and Printers User Interface........................................................................41Solving Problems in the Devices and Printers User Interface..................................42

Call to Action...............................................................................................................43Resources....................................................................................................................44



IntroductionThe world of hardware and devices is rapidly changing. Today’s devices are integrating a richer and ever-increasing set of functionality into the hardware. Examples of this multifunction integration are everywhere and include the following: Multifunction printer, scanner, and copier products.

Smart storage devices with integrated security. Cellular phones that include media-playing capabilities.

One goal of the Windows® 7 operating system is to provide improved support for multifunction devices. This improved support stretches throughout the operating system platform and provides the following: Enhancements to the Windows Plug and Play infrastructure to detect and group

the functions in a device. A new Printers and Devices user interface (UI) for users to view and interact with

their devices. Devices in this UI appear as they do on the user’s physical desktop. This interface incorporates detailed icons and descriptions for the device and exposes device functionality to users.

This paper covers the changes to the Windows Plug and Play subsystem that detect and group device functionality. Additional Windows 7 white papers and developer documentation cover other platform enhancements that were previously mentioned.

Terminology and DefinitionsContainerID

An identifier that is common to all functional device instances that are in one physical multifunction device.

devnodeAn internal structure that represents a single device instance on the system. A devnode contains the device stack and information about the device, such as the state and attributes of the device as seen by Windows Plug and Play.

functional device instanceA single device instance as seen by Plug and Play. A functional device instance provides one of possibly many functional endpoints of a physical device.

multifunction deviceA device that is perceived as a single physical device to users, but that may contain many functional device instances. These functions are physically in the device enclosure or chassis.

Plug and Play Extensions (PnP-X)Extensions of Plug and Play that support network-connected devices. PnP-X currently supports a Plug and Play experience for devices that implement the Device Profile for Web Services (DPWS) and UPnP.PnP-X and DPWS are part of the Windows Rally™ technologies device connectivity service.



Devices in Windows Vista versus Windows 7A comparison of how Plug and Play represents devices in Windows Vista® and in Windows 7 shows the new Windows 7 platform support for multifunction devices.

In Windows, a device is basically a collection of one or more functional device instances. Each instance represents a functional endpoint that enables some form of communication with the device. The term devnode is often used to refer to both the driver stack for a functional endpoint and to the properties that describe the endpoint and its associated state. Windows platform components and third-party applications query a devnode for device status and information, and communicate with device hardware by using the interfaces that functional endpoints expose.

In a single-function device, one devnode contains all the information that relates to that device. Windows Vista and earlier Plug and Play–enabled versions of Windows accurately view a single-function device as one device or “piece of plastic.” However, a multifunction device—such as a printer, scanner, and fax device—has a Plug and Play devnode for each functional endpoint. Windows Vista and earlier versions of Windows cannot recognize that several devnodes originate from the same physical device, even though the functions are integrated into the physical device that users see.

Windows 7 extends Plug and Play to enable it to recognize that a group of devnodes can originate from and belong to one physical device instance. This view provides a more natural representation of a device to users, who can see all the functionality that the physical device exposes grouped under one object. This makes it possible to present users (or applications) with a device-centric view of devices instead of the traditional function-centric view.

Grouping Functionality from One Device: the ContainerIDIn Windows 7, a new Plug and Play property lets Windows components group all devnodes that originate from the same physical device container, enclosure, or chassis. This new property is named ContainerID.

ContainerID is a property of every devnode in Plug and Play. Its type is a globally unique identifier (GUID). The ContainerID property is unique to a single instance of a physical device, and all device function devnodes that belong to that instance of the physical device share the same ContainerID value. Figure 1 (on the following page) shows an example of that relationship.

Figure 1 shows a multifunction device that is connected to a Windows 7 computer. When users first connect the device to their computer, the bus driver detects the device and notifies Plug and Play, which begins installation. As part of installation, the bus driver enumerates each device function in the larger multifunction device. For each such device function, Plug and Play creates a devnode and stores bus-reported properties, such as hardware IDs, compatible IDs, and device capabilities. ContainerID is one of these properties. During enumeration, each devnode that originates from the same physical device is assigned the same ContainerID value.



Figure 1. ContainerIDs for devnodes on a multifunction device

How a ContainerID Is AssignedPlug and Play assigns the ContainerID value to a devnode in one of the following ways:

By retrieving a ContainerID value from a bus driver for the device.The bus driver obtains the ContainerID value from the physical device hardware or generates a ContainerID value by using a unique identifier from the device.

By examining the Removable capability of all devnodes that represent the device.

If the bus driver reports a devnode as removable, Plug and Play interprets this devnode as the root of a new device. Plug and Play generates a ContainerID value for the devnode to identify this devnode as part of the device.

By using the ContainerID of the parent devnode.

If the devnode is not marked with the Removable capability, the devnode represents a subfunction in a multifunction device and therefore inherits the ContainerID value of its parent devnode.

When Plug and Play assigns a ContainerID to a devnode, it first checks whether the bus driver of the devnode can provide a ContainerID. A bus driver can either obtain a genuine ContainerID that was embedded in physical device hardware or generate a ContainerID by using a bus-specific unique identifier from the device hardware. Some examples of a bus-specific unique identifier are a device serial number or a Media Access Control (MAC) address in the firmware of the device. The unique identifier varies, depending on the bus to which the device is attached. The following sections provide details about the bus-specific unique identifiers that Windows recognizes.



If the bus driver cannot provide a ContainerID for a devnode that it is enumerating, Plug and Play uses the Removable capability to determine which devnodes to group in a particular device container. In this case, Plug and Play assigns a newly generated ContainerID to each devnode that belongs to the individual device container. The ContainerID is unique to the host computer. In other words, the devnodes of a multifunction device that can be connected to more than one computer can have a different and nondeterministic ContainerID on each computer.

A software-generated ContainerID is not required to persist across reboots.

Generating a ContainerID from the Bus-Specific Unique IdentifierThe preferred way to generate a ContainerID value for a device is based on a bus-specific unique identifier. This is the most precise and reliable mechanism for generating ContainerIDs and is always used if:

The device contains a bus-specific unique identifier that is retrieved from the device hardware.

The bus driver recognizes this unique identifier as present and well formatted. The bus driver can reliably hash the unique identifier into a GUID and returns this

GUID in response to the IRP_MN_QUERY_ID function code that has the BusQueryContainerID subtype.

Windows 7 includes inbox support for several of the most common bus types, including USB, Bluetooth, and PnP-X (IP-connected) devices. For devices that use these interfaces, the device is required only to include the bus-specific unique identifier for that transport. The Windows-supplied bus drivers do the work of reading unique identifiers from devices and creating a ContainerID.

USB DevicesFor devices that are connected to the computer through the universal serial bus (USB), Figure 2 (on the following page) shows the heuristic that is used to determine the ContainerID value for a USB devnode.

This heuristic uses information from several sources to determine whether a USB devnode represents a new device on the USB bus (in which case it receives a new ContainerID value) or if the devnode is a child devnode of an existing device (in which case it inherits the ContainerID value of the parent).

From Figure 2, you can see that a ContainerID value can be generated in several ways. This decision is based on information in the device, which is retrieved from ACPI settings, the USB bus driver, and the USB hub.



Finish

Start

Is USBMS OS ContainerID Descriptor present?

Does ACPI have_UPC object at the port

address(_ADR) to which thedevice is attached? ContainerID

explicitly specified. Device is recognized as being detached/

external from its parent device.

Use MS OS ContainerID

Descriptor as ContinerID on this

devnode.

YesNo

Is PortIsConnectablefield set to non-zero

(0xFF) value on ACPI _UPC object?

Yes

Is ACPI_PLD object present?

Yes

Is UserVisible (bit 64)set on _PLD object?Yes

Any device connected to this port is external.

No Yes

Does the device have a USB serial number?

Port is connectable but not visible. The device connected to this port must be internal to the

computer.

No

Inherit ContainerID of parent devnode,

effectively grouping device with its parent

device container.

Generate a non-deterministic

ContainerID GUID for the device and assign to devnode.

No

Hash USB serial number into a deterministic

ContainerID GUID and assign to

devnode.

Yes

No

Is theDeviceRemovable

bit set for the givenport?

Yes

USB bus driver reports the device on the given port as not removable.

No

USB bus driver reports the device on the given port

as removable.

Yes

Port is not connectable. The

device connected to this port must be

internal to the computer.

No

Does USB hub have aHub Descriptor with a

RemoveAndPowerMask? No

Figure 2. ContainerID heuristic for USB devnodes



This heuristic follows these steps for each devnode that Plug and Play enumerates on the USB bus:1. A USB device can report a ContainerID by providing a Microsoft® ContainerID OS

descriptor. The ContainerID descriptor is a new Microsoft operating system feature descriptor in Windows 7.

The primary advantage of using a ContainerID OS descriptor is that IHVs can exactly specify a unique ContainerID value for a device. This value does not change if the device is connected to a different PC. A Microsoft ContainerID OS descriptor indicates to Windows that all enumerated devnodes are part of the same physical device.The Microsoft ContainerID OS descriptor is for use in devices that support concurrent connection of the device through multiple system buses. For example, a printer may support concurrent USB and IP network connections by using PnP-X. The serial number is insufficient for multitransport devices because USB does not define the serial number as a GUID. Internally, Windows hashes the serial number to a GUID, and the resulting hashed ContainerID value does not match the ContainerID value that is generated for the device on another transport. If a single Microsoft ContainerID OS descriptor is used, the device reports the same ContainerID value on both transports. Therefore, Plug and Play determines that the devnodes that each bus enumerates are part of the same physical device.

You can find complete information about Microsoft OS descriptors and how to implement the new ContainerID Descriptor on the WHDC Web site, which is listed in “Resources” at the end of this paper.

2. If the USB device does not report a Microsoft ContainerID OS descriptor, the Windows USB hub driver queries ACPI to determine whether the device is attached to an external port. The following evaluation sequence occurs:

a. Windows tries to locate an ACPI address (_ADR) object that matches the address of the USB port to which the device is connected. If Windows cannot find a matching address object, it continues to step 3.

b. Windows queries the USB port capabilities (_UPC) object and checks the PortIsConnectable value. If PortIsConnectable is a nonzero value (0xFF), Windows can use the port to connect external devices. Therefore, any device that is connected to this port must be external to the computer.

c. If PortIsConnectable is a nonzero value, Windows additionally queries the physical location description (_PLD) object. If the UserVisible flag (bit 64) is set on the _PLD object, the port is externally visible to users. Windows considers a USB device that is plugged into a connectable and user-visible port to be removable.

If the information from ACPI indicates that the device is external, Plug and Play creates a ContainerID for the device and assigns the ContainerID to the devnode. The ContainerID value is either a hash of the USB serial number of the device or randomly generated. If Windows determines that the device is internal to the computer, the devnode inherits the ContainerID of the parent devnode, which in this case is the ContainerID of the computer.



3. If ACPI has no ACPI _ADR object that matches the USB port address to which the device is connected, the USB hub driver makes the final decision about the removable status of the devnode.

The USB hub driver queries the USB hub descriptor from the hub hardware to retrieve the RemoveAndPowerMask value. The hub driver then checks the DeviceRemovable bit that corresponds to the port to which the device is connected. If the DeviceRemovable bit is set, devices that are attached to the port are removable from the hub. If the DeviceRemovable bit is not set, devices that are attached to the port cannot be removed from the hub. If a USB hub descriptor is not present, the USB hub driver reports devices that are attached to all ports as removable.

The USB bus driver reports whether the port is removable to Plug and Play, which generates a ContainerID for the devnode by performing the following steps:

a. If the devices that are attached to the given port are removable from the hub, Plug and Play determines that devices that are attached to this port are external to the computer. Plug and Play creates a ContainerID for the device, which is either a hash of the USB serial number of the device or randomly generated. The devnode is assigned this ContainerID value.

b. If the devices that are attached to the given port are not removable from the hub, Plug and Play determines that devices that are attached to this port are subfunctions of a multifunction device. If this is true, the devnode inherits the ContainerID of the parent devnode.

Best Practices for Device Containers on USBThe heuristic to determine the ContainerID for a USB devnode is complex and relies on information from several sources. Follow these recommendations to ensure that Windows can correctly determine the device container and provide the best user experience for your device: When to use the Microsoft ContainerID OS descriptor.

If your device supports more than one transport and is not integrated with a computer, use the Microsoft ContainerID OS. An explicitly defined Microsoft ContainerID OS descriptor ensures that all devnodes that are enumerated for the device on the USB bus are grouped into the same device container.

Note To avoid ContainerID conflicts if you implement a Microsoft ContainerID OS descriptor, make sure that the descriptor value is unique on every device.

The Microsoft ContainerID OS descriptor is useful when a device can concurrently connect through more than one bus. If the same ContainerID value is used on each bus that the device supports, Windows can determine whether functions on each bus are part of the same device container.

For devices that are not integrated into the computer (that is, all external devices), always provide a Microsoft ContainerID OS descriptor and a serial number in the USB device hardware. This ensures that Plug and Play can correctly group all the device functions that the device exposes. Components of the Windows 7 platform and later Windows versions rely on the correct grouping of device functions. Following this practice provides the best user experience for devices on the Windows platform.



USB devices that are integrated with a computer should never provide a Microsoft ContainerID OS descriptor. To ensure that integrated devices are correctly grouped with the computer’s device container, integrated devices should rely on ACPI BIOS settings or the USB hub descriptor DeviceRemovable bit for the port.

When to use ACPI settings to specify device container groupings.If you are a platform OEM for portable and desktop computers, you should use ACPI settings to specify device container groupings. This practice lets computer OEMs indicate which USB ports are internal to the computer and which USB ports users can attach external devices.We strongly encourage computer OEMs to configure the ACPI BIOS settings to accurately reflect the USB port topology of the computer. This practice ensures that USB devices that are physically integrated with the computer (such as an internal Bluetooth radio or an integrated webcam) are grouped into the computer’s device container. It also lets Windows better determine the boundary between the computer and externally attached devices because devices that are attached to connectable or user-visible ports are assumed to be external devices.

When to use the USB Removable capability for device grouping.If your device is an integrated component of a computer, Windows can use the USB Removable capability to create a device container for legacy devices. This mechanism provides backward compatibility for devices that cannot provide a Microsoft ContainerID OS descriptor or for devices that are integrated with a computer that does not have a _USB port capabilities (_UPC) value for the corresponding USB port.It is important to recognize that the USB hub driver uses the removability information from the physical USB hardware to report a more accurate Removable capability for devices that are connected to each of its internal-facing or external-facing ports. For more information, refer to “Generating ContainerID from the Removable Device Capability” later in this paper.

Devices that come to market in the Windows 7 timeframe should include a Microsoft ContainerID OS descriptor (if appropriate) and a USB serial number. Computers should configure ACPI to accurately reflect the USB topology of the computer.

Guidance for Using ACPI to Configure USB Ports on a ComputerIf the system requires ACPI BIOS changes to accurately reflect the USB port configuration, you should consider the user’s ability to connect a device to the port when you configure the port. Table 1 on the following page shows how the values of the ACPI objects for a given port affect the value of the DeviceRemovable bit that Windows reports for the device.

Table 1. How to mark a USB port by using ACPI objectsUSB Port Status Example _UPC.PortIsConnectable

Byte_PLD.UserVisible

BitResulting

DeviceRemovable Bit Value

Port is visible and user can

Port is exposed on the face of a

Set (OxFF)

Set

Set



USB Port Status Example _UPC.PortIsConnectable Byte

_PLD.UserVisible Bit

Resulting DeviceRemovable Bit Value

freely connect and disconnect devices.

panel on the computer that is visible to the user.

Port is hidden or internal and user cannot freely connect and disconnect devices.

Port is directly hard-wired to an integrated device, such as a laptop webcam or an internal USB hub.

Set (OxFF)

Clear

Cleared

Port is physically implemented by the USB host controller, but is not used.

Port is an excess port that is not connected to a port plug terminal or an integrated device.

Clear (0x00)

Clear

Cleared

Note It is an invalid configuration to define a port as both not connectable and visible to users.

If you use ACPI to specify the configuration of a USB port, you must define both a _UPC and a _PLD object. Although the ACPI 3.0 specification does not specifically prohibit the use of _UPC alone, the use of both objects more precisely indicates the user’s ability to connect devices to the port. The use of _UPC alone might not set the device container grouping correctly or as expected.

The following examples show correctly formed ACPI Source Language (ASL) that demonstrates the use of _UPC and _PLD objects to describe a USB port.

To specify a port that is internal (not visible to users) and can be connected to an integrated device, set _UPC.PortIsConnectable = 0xFF and _PLD.UserVisible = 0. In the following example the device is grouped with the computer’s device container. Name(_UPC, Package(){ 0xFF, // Port is connectable 0xFF, // Connector type (N/A for non-visible ports) 0x00000000, // Reserved 0, must be zero 0x00000000}) // Reserved 1, must be zero

Name(_PLD, Buffer(0x10){ 0x81, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x1C, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00})



To specify a port that is external (visible to users) and can be connected to an external device, set _UPC.PortIsConnectable = 0xFF and _PLD.UserVisible = 1. Set the connector type byte to the appropriate USB connector type as specified in the ACPI specification. In the following example the device is assigned a new device container and appears as a separate physical device.Name(_UPC, Package(){ 0xFF, // Port is connectable 0x00, // Connector type, Type ‘A’ in this case 0x00000000, // Reserved 0, must be zero 0x00000000}) // Reserved 1, must be zero

Name(_PLD, Buffer(0x10){ 0x81, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x31, 0x1C, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00})

Avoiding Device Container ConflictsAttaching two or more devices to a computer that share the same ContainerID value (explicitly defined by using the Microsoft ContainerID OS descriptor or the same USB serial number) results in a device container conflict. Windows interprets all device functions as originating from a single device and creates one device container. This can cause unexpected behavior with the devices and within Windows.

To avoid this problem, ensure that the Microsoft ContainerID OS descriptor value and the USB serial number are unique to one physical device. Do not share these values among devices in a product line.

If your USB device relies on Windows to generate a ContainerID that is based on the USB serial number, the ContainerID is generated as follows:1. Windows creates a string by concatenating the USB device serial number,

vendor ID, product ID, and revision number.2. The resulting string is hashed into a GUID by using the UUID Version 5 (SHA-1)

hash algorithm under a USB-specific namespace. The generated ContainerID is unique if each physical device has a unique serial number.

Bluetooth DevicesAll Bluetooth technology devices must include a MAC address. For Bluetooth devices that are connected to the computer, the MAC address is used as the bus-specific unique identifier of the device. The Bluetooth driver stack uses the MAC address as a seed value to generate a ContainerID for the device. The Bluetooth bus driver supplies this ContainerID value for each Bluetooth devnode that a physical device enumerates. To ensure that a unique ContainerID is generated for every device, the Bluetooth device MAC address should be unique among all Bluetooth device instances.

Bluetooth devices often implement Bluetooth-specific services. These services are not installed as Plug and Play devices and therefore do not have associated devnodes. However, these services are effectively functional device instances because they provide specific functionality and enable communication with the Bluetooth device. Windows considers Bluetooth services to be functional device interfaces, and new infrastructure exists to group the Bluetooth services with the Bluetooth devnodes for



a device. This grouping is accomplished by using the ContainerID that is generated from the Bluetooth MAC address to identify the services and devnodes that originate from the same physical device. The grouping occurs within the Bluetooth stack and so is transparent to the device.

The Removable capability is never used as a basis for generating a ContainerID for Bluetooth devices. The ContainerID for Bluetooth devnodes and services is always based on the MAC address value.

PnP-X for Network-Connected DevicesPnP-X extends Plug and Play to support devices that are connected to the computer through an IP-based network. PnP-X devices can specify a ContainerID as an XML element in their device metadata. Two protocols are supported: DPWS and UPnP. For more information about PnP-X, DPWS, and UPnP, see the references in “Resources.”

If a PnP-X device does not specify a ContainerID in the DPWS device metadata or the UPnP device description document, Plug and Play generates a ContainerID for the device in one of the following ways: For DPWS devices, the generated ContainerID is a SHA-1 hash of the endpoint

reference address of the device. For UPnP devices, the generated ContainerID is the unique device name (UDN) of

the device.

For devices that operate on a single bus or PnP-X protocol, the PnP-X–generated ContainerID is sufficient.

A multiprotocol device can specify a ContainerID. In such a device, the same ContainerID would be shared on each transport to let Windows group all instances of the device into one device container. Both DPWS and UPnP can specify a ContainerID for the device, if necessary.

Specifying ContainerIDs for DPWS DevicesDevices that implement DPWS and support PnP-X can specify a ContainerID instead of letting Plug and Play generate one. To specify a ContainerID, include the <ContainerId> XML element in the device metadata document for the device.Namespace http://schemas.microsoft.com/windows/2008/09/devicefoundationXML element prototype

<df:ContainerId xmlns:df=”http://schemas.microsoft.com/windows/2008/09/devicefoundation”> xs:string</df:ContainerId>

The <ContainerId> XML element type is a string, for which the value is a GUID of the form {00000000-0000-0000-0000-000000000000}. For example:<df:ContainerId xmlns:df=”http://schemas.microsoft.com/windows/2008/09/devicefoundation”> {101392d0-5e91-11dd-ad8b-0800200c9a66}</df:ContainerId>


https://mail.exchange.microsoft.com/OWA/redir.aspx?C=2f9e5565fff246f88c0e5e0af1888fc6&URL=http%3A%2F%2Fschemas.microsoft.com%2Fwindows%2F2008%2F09%2Fdevicefoundation

http://schemas.microsoft.com/windows/2008/09/devicefoundation



The <ContainerId> XML element must be in the <ThisDevice> section of the device metadata exchange Simple Object Access Protocol (SOAP) message. The following example shows the correct placement of the <ContainerId> element in a metadata exchange message.

Note This is not a complete DPWS metadata exchange document. For more information about DPWS, refer to “Resources” later in this paper.<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsdisco="http://schemas.xmlsoap.org/ws/2005/04/discovery" xmlns:wsx="http://schemas.xmlsoap.org/ws/2004/09/mex" xmlns:wsd="http://schemas.xmlsoap.org/ws/2006/02/devprof" xmlns:df="http://schemas.microsoft.com/windows/2008/09/devicefoundation">

<soap:Header>  </soap:Header>

<soap:Body> <wsx:Metadata>

<wsx:MetadataSection Dialect="http://schemas.xmlsoap.org/ws/2005/05/devprof/ThisModel"> <wsd:ThisDevice>  <df:ContainerId>  {101392d0-5e91-11dd-ad8b-0800200c9a66} </df:ContainerId> </wsd:ThisDevice> </wsx:MetadataSection>

</wsx:Metadata> </soap:Body></soap:Envelope>

Specifying ContainerIDs for UPnP DevicesDevices that implement the UPnP protocol and support PnP-X can specify a ContainerID value. This is accomplished by including the <X_containerId> XML element in the device description document for the device.Namespace http://schemas.microsoft.com/windows/2008/09/devicefoundationXML element prototype

<df: X_containerId xmlns:df=”http://schemas.microsoft.com/windows/2008/09/devicefoundation”> xs:string</df: X_containerId >

The <X_containerId> XML element type is a string, for which the value is a GUID of the form {00000000-0000-0000-0000-000000000000}. For example:<df:X_containerId xmlns:df=”http://schemas.microsoft.com/windows/2008/09/devicefoundation”> {101392d0-5e91-11dd-ad8b-0800200c9a66}</df:X_containerId >


https://mail.exchange.microsoft.com/OWA/redir.aspx?C=2f9e5565fff246f88c0e5e0af1888fc6&URL=http%3A%2F%2Fschemas.microsoft.com%2Fwindows%2F2008%2F09%2Fdevicefoundation




The <X_containerID> XML element must be in the <device> section of the UPnP device description document. The following example shows the correct placement of the <X_containerID> element in a device description document.

Note This is not a complete UPnP device description document. For more information about UPnP, refer to “Resources” later in this paper.<?xml version="1.0" ?><root xmlns="urn:schemas-upnp-org:device-1-0" xmlns:df= "http://schemas.microsoft.com/windows/2008/09/devicefoundation">

<specVersion> <major>major version number</major> <minor>minor version number</minor> </specVersion>

<URLBase>device URL</URLBase>

<device>  <df:X_containerID>  {101392d0-5e91-11dd-ad8b-0800200c9a66} </ df:X_containerID >

</device></root>

1394 DevicesThe 1394 bus specification does not specify an in-hardware mechanism to indicate whether a device function is removable or not removable from the 1394 host controller. The Windows inbox 1394 bus driver marks every devnode as removable from the parent host controller. If a single 1394 device exposes multiple device functions, each devnode that the bus driver enumerates is marked as removable. However, the Windows inbox 1394 bus driver recognizes that each devnode originated from a single device and assigns the same ContainerID value to each devnode. Therefore, each 1394 device receives a single device container object and appears as a single device in the Devices and Printers UI.

eSATA DevicesThe eSATA bus cannot express a ContainerID value. When Windows determines the device container grouping for an eSATA device, it relies on the Removable capability that the ATA bus driver returns. The ATA bus driver marks an eSATA device as removable if one of the following conditions is set for the SATA controller port: If the eSATA port is a hot-plug-capable port, the following register bit is set:

Advanced Host Controller Interface (AHCI), Port x Command and Status (PxCMD) register (Offset 18h), bit location 18 (Hot Plug Capable Port (HPCP))When set to “1”, indicates that this port’s signal and power connectors are externally available through a joint signal and power connector for blindmate device hot plug.



If the eSATA port is a signal-only port, the following two register bits are set:Advanced Host Controller Interface (AHCI), HBA Capabilities (CAP) register (Offset 00h), bit location 5 (Supports External SATA (SXS))When set to ”1”, indicates that the host bus adapter (HBA) has one or more SATA ports that have a signal-only connector that is externally available (such as an eSATA connector). If this bit is set to ”1”, software can refer to the PxCMD.ESP bit to determine whether a specific port has its signal connector externally available as a signal-only connector (that is, power is not part of that connector). When the bit is cleared to ”0”, indicates that the HBA has no SATA ports that have a signal-only connector that is externally available.

Advanced Host Controller Interface (AHCI), Port x Command and Status (PxCMD) register (Offset 18h), bit location 21 (External SATA Port (ESP))When set to ”1”, indicates that this port’s signal connector is externally available on a signal-only connector (such as an eSATA connector). When set to ”1”, CAP.SXS shall be set to ”1”. ESP is mutually exclusive with the HPCP bit in this register. If ESP is set to ”1”, then the port may experience hot plug events.

Note that these conditions are mutually exclusive. An eSATA port may declare itself to be an external hot-plug-capable port or an external signal-only port, but not both. If either condition is set for an eSATA port, the ATA driver marks as removable any device that is attached to the port.

For additional details, refer to the Serial ATA AHCI 1.3 specification.

PCI Express DevicesThe PCIe bus cannot express a ContainerID value. Windows relies on the Removable capability that the PCI bus driver returns when it determines the device container grouping for a PCIe device. The PCI bus driver marks a PCIe device as removable if both of the following conditions are satisfied: The upstream Express Port indicates that it implements a physical slot:

PCI Express Capabilities Register (Offset 02h), bit location 8 (Slot Implemented)When set, indicates that the PCIe link that is associated with this port is connected to a slot (compared to being connected to an integrated component).

The slot indicates that it is hot-plug capable:Slot Capabilities Register (Offset 14h), bit location 6 (Hot-Plug Capable)When set, indicates that this slot can support hot-plug operations.

For additional details, refer to the PCIe Base Specification.

The mechanism that is used to set these register bits varies by PCIe chipset version and manufacturer. (Some chipsets let the firmware program these bits, whereas other chipsets require physical pins to be strapped to Vcc or GND.)

Note that if the device implements an _EJ0 method in the ACPI namespace, the ACPI driver marks the device as removable. This occurs regardless of the values of the slot-implemented and hot-plug-capable bits.



Generating a ContainerID from the Removable CapabilityIf the device hardware does not embed a ContainerID or unique identifier, Plug and Play examines the Removable capability on each devnode to determine how to group the devnodes into a device. It is important to understand the Removable capability and when a devnode should report its child devnodes as removable.

The value of the Removable bit in the DEVICE_CAPABILITIES structure indicates whether the device can be removed. This structure is populated during device enumeration when a device’s driver responds to an IRP_MJ_PNP request with the IRP_MN_QUERY_CAPABILITIES minor function code for a devnode that it has enumerated. For details on the DEVICE_CAPABILITIES structure, see the Windows Driver Kit (WDK).

The Removable capability is set for a devnode when the devnode and all its child devnodes constitute a device that can be physically removed, disconnected, or unplugged from its parent devnode while the computer is running. Typically, a devnode should be marked as removable if it is the topmost devnode in a devnode topology.

Setting the Removable capability correctly on a devnode is important. If the device does not include a unique identifier (as described earlier), Plug and Play uses this capability to determine which devnodes belong to a device.

For example, assume that a single function device, such as a mouse, is connected to the computer through USB. In this case, the USB bus sees that a new device has arrived, detects that it is a USB human interface device (HID), and creates a USB HID devnode for the device. The HID devnode, in turn, detects that the HID device is a mouse and creates a child devnode for a HID-compliant mouse. At this point, the mouse is installed and is functional on the system. Both of the new devnodes use independent driver stacks. Remember that the topmost devnode of the device should be set as removable, whereas its child devnodes should not be set as removable. Therefore, the USB HID devnode should have Removable set to TRUE, whereas its child devnode (the HID-compliant mouse) should have Removable set to FALSE.



Figure 3 shows the devnode topology for a generic USB mouse and indicates which devnodes of the mouse are marked as removable.

Figure 3. Devnode topology for a USB mouse as seen in Device Manager

If the device has no unique identifier (as in the mouse example), Plug and Play uses the Removable capability to determine which devnodes belong to a device and to assign ContainerID values as follows:1. If the bus driver of the device reported a genuine ContainerID (such as a

Microsoft OS descriptor) or a generated ContainerID that is based on a unique identifier in the hardware (such as a MAC address), then assign this ContainerID to the devnode.

2. If the Removable bit for the devnode is set to TRUE, generate a new ContainerID for the devnode.

3. If the Removable bit for the devnode is set to FALSE, inherit the ContainerID of its parent devnode.



A devnode cannot enumerate child devnodes until it is initialized and its driver stack is started. When Plug and Play assigns a ContainerID during devnode initialization, the devnode can propagate the ContainerID down to any of its nonremovable children as they are enumerated.

A devnode that has the Removable capability is considered the topmost devnode for the device, and Plug and Play generates a ContainerID value and assigns it to the devnode. All the children of this topmost devnode inherit the same ContainerID value, unless they are physically detachable from their parent devnode.

Applying this heuristic to the USB mouse example results in the following actions:

1. The USB HID devnode is created. No unique identifier exists in the hardware of this device.

The Removable bit is set to TRUE on this devnode because its parent USB hub devnode recognized that it was plugged into an external-facing USB port.

Plug and Play creates a ContainerID for this devnode because it is the topmost devnode of a removable device.

2. The HID-compliant mouse devnode is created. No unique identifier exists in the hardware of this device.

The Removable capability is set to FALSE on this devnode because its parent USB HID devnode reports all its children as nonremovable. The HID-compliant mouse has no notion of removability.This devnode inherits the ContainerID of the parent devnode.

After Plug and Play applies the heuristic, the same ContainerID is assigned to each devnode that belongs to the mouse. Plug and Play successfully grouped the devnodes into a logical device, even in the absence of a unique identifier for the device.

Be aware that the success of this heuristic depends on the Removable capability that the bus driver reports for each devnode. Therefore, make sure that your drivers accurately report the Removable capability for any device that they support.

The following table summarizes: The available mechanisms on each bus for supplying a ContainerID in the device

hardware. Not all bus types have a mechanism to explicitly define a ContainerID in the hardware. In this case, the Removable capability must be set correctly in the device hardware to ensure correct device container grouping.

The primary and secondary mechanisms for a given device type.Bus type Primary ContainerID

generation heuristicSecondary ContainerIDgeneration heuristic

USB Computers: _UPC and _PLD in ACPI BIOS tableExternal devices: Microsoft OS ContainerID Descriptor

Removable capability

Bluetooth Not applicable Bluetooth MAC addressPnP-X (IP connected)

DPWS: <ContainerId> elementUPnP: <X_containerId> element

DPWS: ContainerID is a SHA-1 hash of the endpoint reference address of the deviceUPnP: ContainerID is the UDN of the device



Bus type Primary ContainerIDgeneration heuristic

Secondary ContainerIDgeneration heuristic

1394 Removable capability (always set as removable by 1394 bus driver)

Not applicable

PCI Express (PCIe)

Removable capability (bus hardware specific) Not applicable

eSATA Removable capability (bus hardware specific) Not applicable1Bluetooth SIG to include ContainerID support in a future Bluetooth specification.

The Difference Between Removable and SurpriseRemovalOK Capabilities

The Removable capability is an important device attribute because it lets Windows 7 group functionality into the correct device container for a given physical device. Do not, however, confuse the Removable capability with the SurpriseRemovalOK capability.

Only the bus driver of a devnode should set the Removable capability. The bus driver for a devnode is the only driver in the system that knows whether the devnode can be removed. Therefore, the physical device object (PDO) is the only object in the stack that should set (or clear) the Removable bit. By setting the Removable capability, the bus driver indicates that the devnode and all of its descendants can be physically removed from the bus. If the Removable capability is set for a devnode, Windows treats the devnode and its nonremovable descendants as a single device container. In the UI, the device container results in a one-to-one relationship between the physical device that users perceive and a single object for the device in Devices and Printers.

The SurpriseRemovalOK capability determines whether Windows includes the device in the Safely Remove Hardware list. If users can remove the device safely without any preparation by the driver, SurpriseRemovalOK should be set to TRUE. If the device requires any type of preparation before users can safely remove it, this capability should be set to FALSE.

The Safely Remove Hardware icon in the system tray enables users to notify Windows before they detach a device so that the driver can prepare the device for removal. When users request safe removal of a device, Windows sends IRP_MN_QUERY_REMOVE_DEVICE to the driver so that the driver can prepare the device to be removed without loss of data or hardware damage.

If a device has one or more devnodes for which the SurpriseRemovalOK capability is set to FALSE, Windows includes the device in the Safely Remove Hardware list. Stated another way, if all devnodes in a device set SurpriseRemovalOK to TRUE, the device does not appear in the Safely Remove Hardware list. The Removable capability defines the boundary of the device to which Safely Remove Hardware applies.

The following are typical reasons for requiring safe removal and therefore setting SurpriseRemovalOK to FALSE:

Surprise removal of the device can cause data corruption or loss. Sudden removal of the device can cause hardware damage.



Users expect the device or device class to have the Safely Remove Hardware option, regardless of whether the device actually requires safe removal.

The following table indicates when to set the SurpriseRemovalOK capability for a devnode:Case SurpriseRemovalOK settingBus driver (PDO) knows that unsafe removal of the devnode might cause hardware damage.

Clear to FALSE.

Bus driver (PDO) knows that unsafe removal of the devnode cannot cause hardware damage.

Set to TRUE.

Function driver (functional device object—FDO) requires safe removal.

Clear to FALSE when the IRP_MN_QUERY_CAPABILITIES request travels back up the driver stack.

Function driver (FDO) does not require safe removal.

Set to TRUE when the IRP_MN_QUERY_CAPABILITIES request travels down the driver stack.However, drivers for USB devices that support surprise removal must set this to TRUE only when the IRP is traveling back up the driver stack. For more information, see “DEVICE_CAPABILITIES” in the WDK.

Including ContainerID Support in a Custom Bus DriverIn Windows 7, all Microsoft-supplied bus drivers are device-container aware. If a device-specific unique identifier is available, these bus drivers use that identifier to create a ContainerID for each devnode in a device. If a ContainerID cannot be generated that is based on a unique identifier, the reported Removable capability is used to guide Plug and Play as it creates or propagates a ContainerID for each devnode.

Third-party bus drivers should be written to be device-container aware. To support device containers, a custom bus driver must do the following: Correctly set the Removable capability on each devnode that the bus driver

enumerates, specifically, set Removable to TRUE only for devnodes that represent physically detachable device connection endpoints.

If the bus supports a ContainerID or unique identifier in the device hardware, handle the new BusQueryContainerID IdType for the IRP_MJ_PNP request with the IRP_MN_QUERY_ID minor function code.

Setting the Removable CapabilityThe guidelines for setting the Removable capability for a devnode that a custom bus driver enumerates are the same as for other bus drivers. For more information about which devnodes should be marked removable for a device, see “Generating a ContainerID from the Removable Capability” earlier in this paper.

Handling BusQueryContainerIDThe bus driver must report the ContainerID for its devnode during device initialization. Remember that a ContainerID should be reported only for devices that are external to the computer. Devices that are internal to the computer should be



reported as not removable, so that Plug and Play can group the device with the computer.

To report ContainerID, a kernel-mode driver framework (KMDF) bus driver calls WdfPdoInitAssignContainerID before it calls WdfDeviceCreate to create the PDO. This function is supported in Windows Driver Foundation (WDF) version 1.9 and later. For more information, see “WdfPdoInitAssignContainerID” in the WDK.

A Windows Driver Model (WDM) bus driver must respond to the IRP_MJ_PNP request for IRP_MN_QUERY_ID. The following code sample demonstrates how a WDM bus driver should return a ContainerID for a devnode. In this example, the PdoHandleIrpQueryId function handles the IRP_MN_QUERY_ID minor function code for a PDO in a WDM bus driver:NTSTATUSPdoHandleIrpQueryId( PDEVICE_OBJECT Pdo, PIRP Irp ){ NTSTATUS status; PIO_STACK_LOCATION ioStack; GUID containerId; UNICODE_STRING unicodeContainerId;

ioStack = IoGetCurrentIrpStackLocation(Irp);

switch (ioStack->Parameters.QueryId.IdType) {

case BusQueryHardwareIDs: ... break;

case BusQueryInstanceID: ... break;

...

case BusQueryContainerID: status = GET_CONTAINERID_FROM_PDO(Pdo,&containerId);

if (NT_SUCCESS(status)) { status = RtlStringFromGUID(&containerId, &unicodeContainerId);

if (NT_SUCCESS(status)) { Irp->IoStatus.Information = (ULONG_PTR) unicodeContainerId.Buffer; } } break;

default: ... break; }

Irp->IoStatus.Status = status;

IoCompleteRequest(Irp, IO_NO_INCREMENT);



return status;}

In response to the request for BusQueryContainerID, the bus driver must return a Unicode string buffer that is allocated from paged pool. This buffer contains a string representation of the ContainerID GUID that should be assigned to the devnode.

The example shows an undefined call into the driver-defined GET_CONTAINERID_FROM_PDO to obtain a ContainerID GUID. The details of where this ContainerID originates and how it is generated are specific to the bus. As with other ID types that are queried often, such as BusQueryHardwareIDs and BusQueryInstanceID, a good practice is to have a ContainerID value ready and stored in a bus-specific PDO extension to allow for efficient handling of I/O request packets (IRPs).

Using ACPI to Indicate Device Container GroupingSystem manufacturers can use ACPI BIOS objects to indicate to Windows whether a device is internal or external to the computer. By configuring ACPI objects in the computer BIOS, it is possible to indicate the precise configuration of the computer. This capability is in addition to other device container grouping mechanisms that are described in this paper.

The use of ACPI to indicate the computer configuration has several advantages: The settings persist in the computer BIOS and are preserved across operating

system upgrades. Windows evaluates ACPI settings after it evaluates bus driver–supplied

Removable capabilities. Therefore, a manufacturer can use the ACPI settings to fix devices that are incorrectly reported as removable and Windows can group the functionality into the computer’s device container.

If you use ACPI to affect the device container grouping of a USB-connected device, see “USB Devices” earlier in this paper. For USB devices, you should use both the _UPC.PortIsConnectable and _PLD.UserVisible objects to configure the device container grouping.

How ACPI Objects Are EvaluatedFigure 4 on the following page shows the effect of ACPI objects on the Removable and EjectSupported capabilities.



Figure 4. Effect of ACPI objects on Removable and EjectSupported capabilities



Using _RMV (Remove)The _RMV object indicates that a device can be removed from the system. The _RMV object can either set or clear the Removable capability on a system port, which changes the device container grouping of devices that are attached to the port. The result code that _RMV returns upon evaluation affects the Removable capability as follows:

_RMV Result Code

Result

0 The device cannot be removed from the system. The Removable capability is cleared for the devnode.

1 The device can be removed from the system. The Removable capability is set for the devnode.

Using _EJx (Eject)Devices that support warm or hot removal can supply one or more _EJx eject control methods. Warm removal occurs when the system is in a sleep state (S1, S2, S3, or S4), and hot removal occurs when the system is in S0. The x in _EJx indicates the sleep state from which the device supports removal. _EJ0 indicates that the device supports hot removal, and _EJ1 through_EJ4 indicate that the device supports warm removal. For details about which _EJx methods to define, see the ACPI Specification.

Manufacturers typically supply an _EJx method for removable optical storage devices, such as a DVD-ROM drive found in a portable computer. When Windows builds the device containers for the computer and attached devices, the presence of an _EJx method affects device container grouping and devnode capabilities as follows:

If an _EJx methods exists for the port and the Removable capability is set:1. The ACPI driver (acpi.sys) sets the EjectSupported capability for _EJ0 or the

WarmEjectSupported capability for _EJ1 through _EJ4 on the devnode.2. The ACPI driver sets the Removable capability on the devnode.

3. Windows creates a device container for the devnode because a bus driver further down the driver stack or an ACPI _RMV method on the port marked it as removable. The _PLD.UserVisible bit, the _PLD.Bay bit, or a DeviceOverride registry key can later change the device container grouping, if necessary.

If an _EJx method exists for the port and the Removable capability is not set:

1. The ACPI driver sets the EjectSupported capability (for _EJ0) or the WarmEjectSupported capability (for _EJ1-EJ4) on the devnode.

2. The ACPI driver sets the Removable capability on the devnode.3. Because neither a bus driver further down the driver stack nor an ACPI _RMV

method marked the devnode as removable, Windows does not create a device container for the devnode. The devnode inherits the ContainerID of its parent and therefore is included in the device container of its parent. The _PLD.UserVisible bit, the _PLD.Bay bit, or a DeviceOverride registry key can later change the device container grouping, if necessary.



Devices that can be ejected from the system but appear to be physically integrated are an exception to the device container grouping algorithm. This commonly occurs with optical drives that are integrated into a notebook computer. The port to which the optical drive attaches should have an _EJx control method to support ejection of the device. However, users perceive the optical drive as an integrated component of the computer. From the user’s point of view, the optical drive should not appear as its own device container. To ensure that users see the device as part of the computer device container, the Removable capability should not be set on the devnode before the system calls the _EJx method on the port. This allows Windows to determine that this device should be grouped with its parent device container—in this case, the computer. To indicate that the device that is attached to this port has its own device container and thus appears external to the computer, use the _RMV or _PLD ACPI object as appropriate for the device type.

Using _PLD (Physical Location Description)The _PLD object is a method that conveys a general description of the physical location of a device’s connection point. When called for a particular port, the _PLD method returns a buffer that describes the physical location of the given port. This buffer is a bit field and the individual bits represent attributes that describe the physical port. By setting the values of the UserVisible and Bay bits appropriately, _PLD can indicate to Windows whether devices that are attached to a port should be grouped with their parent device container—typically the computer—or if each attached device should have its own device container.

In _PLD, it is important to set correct values for all fields of the _PLD buffer, including the UserVisible and Bay bits.

_PLD.UserVisible (Bit 64)The UserVisible bit indicates whether a device connection point is visible to users. If the UserVisible bit is cleared (_PLD.UserVisible = 0), the port is not visible to

users and must be internal to the computer. Windows groups any device that is attached to the port with the computer.

If the UserVisible bit is set (_PLD.UserVisible = 1), the port is user visible. Setting a port as user visible has no effect on device container grouping. To indicate that an external device is attached to the port, use either a _RMV or _EJx ACPI object as described earlier in this paper.

The following examples show how to correctly form ASL for _PLD buffers that describe a port as not user visible and user visible, respectively.

In the first example, _PLD.UserVisible = 0 indicates that this port is not user visible. Windows groups any devices that are attached to this port into their parent’s device container, typically the computer. Name(_PLD, Buffer(0x10){ 0x81, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x1C, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00})



In the second example, _PLD.UserVisible = 1 indicates that the port is user visible. This setting has no effect on the device container grouping for any device that is attached to the port. Name(_PLD, Buffer(0x10){ 0x81, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x31, 0x1C, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00})

_PLD.Bay (Bit 95)Set the Bay bit to describe either a device or a device connection point that is in a bay. If the Bay bit is set (_PLD.Bay = 1), the port is in a bay or the device that is

attached to the port is in a bay. Because the device is physically integrated with the computer, Windows groups it with the computer device container.

If the Bay bit is cleared (_PLD.Bay = 0), neither the port nor the device that is attached to it is in a bay. Marking a port as not in a bay has no effect on device container grouping. To indicate that an external device is attached to this port, use either a _RMV or _EJx ACPI object as appropriate.

The following examples show how to correctly form ASL for _PLD buffers that describe a port in a bay and not in a bay. Notice the difference between the 0x80 and 0x00 values.

In the first example, _PLD.Bay = 1 indicates that either the port or the device that is attached to the port is in a bay. Windows groups devices that are attached to this port into their parent’s device container, typically the computer’s.Name(_PLD, Buffer(0x10){ 0x81, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x1C, 0x00, 0x80, 0x00, 0x00, 0x00, 0x00})

In the second example, _PLD.Bay = 0 indicates that neither the port nor the device that is attached to it is in a bay. Note that this has no effect on device container grouping for any device that is attached to the port.Name(_PLD, Buffer(0x10){ 0x81, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x1C, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00})

Overriding the Removable Capability in Legacy DevicesThe algorithm to group devnodes into a logical device, based on the Removable capability, supports legacy devices that do not provide recognized device-specific unique identifiers in their hardware. New devices should provide a device-specific unique identifier and set the Removable capability correctly.

However, some legacy devices do not report the Removable capability correctly. Therefore, Plug and Play cannot group these devices into the appropriate logical device containers. To solve this problem, Windows provides a mechanism to override the bus-reported Removable capability for a devnode.



This device override mechanism is a registry-based lookup table (LUT) that consists of registry keys that map to specific devices. This override table is maintained under the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\DeviceOverrides

Subkey entries under the DeviceOverrides key are device hardware IDs or compatible IDs, where slash (\) path separator characters are replaced with number (#) characters. These altered hardware and compatible IDs identify devices for which Plug and Play ignores the Removable capability when it generates a ContainerID.

Subkey entries in the override table do not actually change the global state of the Removable capability on the devnode, but instead affect only its evaluation for generating a ContainerID. Additional subkeys under the hardware or compatible ID subkeys enable finer grained specification of exactly which devnodes to override based on how they are connected within the computer.

The following are best practices for using the DeviceOverrides registry key: Apply the DeviceOverrides registry key for a device before you initially install the

device on the system. By setting the registry keys before the device arrives, you can ensure that the Removable override is applied correctly and that Windows creates the device container grouping that you expected.

If you apply a DeviceOverrides registry key after installation of the target device, it might be necessary to forcibly uninstall the device and then reinstall it for the override to be correctly applied.

Windows applies DeviceOverrides at system boot time. Therefore, you must reboot the system before a DeviceOverride takes effect.



Figure 4 shows the structure of the DeviceOverrides registry key and subkeys. The following sections explain the usage of each subkey in detail.

Figure 4. Removable override registry structure



DeviceOverrides Registry KeyRegistry key name DeviceOverridesRequired/optional RequiredFormat requirements NoneValid subkeys HardwareID

CompatibleID(See the following subkey format requirements and examples)

CommentsThe DeviceOverrides registry key indicates that one or more overrides for the Removable capability can exist on this computer. By using a device override, an IHV or OEM can change the interpreted value of the Removable capability on a devnode or group of devnodes. This is useful for legacy devices or third-party hardware components that might not report the Removable capability correctly and, in turn, cause the ContainerID generation heuristic to incorrectly group the related devnodes. The presence of the DeviceOverrides registry key does not change the global state of the Removable capability for a devnode.

The DeviceOverrides registry key must be created by the first device override that is added to the table. The key does not exist by default on a clean operating system installation.

“HardwareID” or “CompatibleID” Registry KeyRegistry key name Valid “HardwareID” or “CompatibleID” values.Required/optional RequiredFormat requirements Must include the bus prefix of the HardwareID or CompatibleID

All ”\” characters must be replaced with a “#”.Examples USB#VID_1234&PID_ABCD&REV_0001

PCI#VEN_ABCD&DEV_1234&SUBSYS_000Valid subkeys LocationPaths

ChildLocationPaths

CommentsThe HardwareID or CompatibleID registry subkey specifies a device for which Plug and Play ignores the Removable capability when it generates a ContainerID.

Notice in the examples that the bus prefix for the device must be present and that the backslash character “\” is replaced with the number sign “#”. Because the backslash character is not a valid character in a registry subkey name, you must replace it with the number sign when you specify a bus prefix.

Generally, you should use the most specific device hardware ID to identify a device, instead of a less specific hardware or compatible ID. This ensures that the override does not apply to any unintended devices that share the same hardware or compatible ID as the intended target device.

Valid subkeys are LocationPaths and ChildLocationPaths. Although these subkeys are defined as optional, either the LocationPaths or ChildLocationPaths subkey must be specified under each HardwareID or CompatibleID subkey. Both subkeys can be specified if it is necessary.



LocationPaths Registry KeyRegistry key name LocationPathsRequired/optional Optional. Either LocationPaths or ChildLocationPaths must be

present to indicate the parent/child relationship to which the device override applies.

Format requirements NoneValid subkeys A string that defines the location path

* (asterisk)

CommentsThe LocationPaths registry subkey indicates that the Removable override affects only devnodes that have the specified HardwareID or CompatibleID value. Children of the specified devnode are not affected, unless a ChildLocationPaths registry subkey is also specified.

ChildLocationPaths Registry KeyRegistry key name ChildLocationPathsRequired/optional Optional. Either LocationPaths or ChildLocationPaths must be

present to indicate the parent/child relationship to which the device override applies.

Format requirements NoneValid subkeys A string that defines the location path* (asterisk)

CommentsThe ChildLocationPaths registry subkey indicates that the Removable override affects only child devnodes of the parent devnode that have the specified HardwareID or CompatibleID value. The parent devnode is not affected by the override value, unless a LocationPaths registry subkey is also specified or a ChildLocationPaths registry subkey is specified for its parent devnode.

* Registry KeyRegistry key name *Required/optional Optional. However, either *or a valid location path must be present

to indicate the scope of the device override.Format requirements NoneValid subkeys NoneValid registry values under this key

Removable

CommentsThe * (asterisk) registry subkey indicates that the Removable override value has global scope. This subkey can be used under the LocationPaths or ChildLocationPaths registry subkeys. The effect of the * subkey is to apply the Removable override value to all the devnodes that have the specified HardwareID or CompatibleID according to the rules of the LocationPaths or ChildLocationPaths registry subkey under which it appears.



“LocationPath” Registry KeyRegistry key name Valid “LocationPath” valueRequired/optional Optional. However, either * or a valid location path must be present

to indicate the scope of the device override.Format requirements NoneValid subkeys None

Example PCIROOT(0)#PCI(1234)#USBROOT(0)#USB(1)#USB(3)#USB(3)Valid registry values under this key

Removable

CommentsA valid location path registry subkey overrides the Removable value for only the device that exists at the specified location path. This subkey can be specified under a LocationPaths or ChildLocationPaths registry subkey.

The LocationPath subkey lets you apply the Removable override value to a single instance of a device on the computer. Other devices that have the same HardwareID or CompatibleID at other location paths are not affected by such a Removable override value.

By convention, the location path string takes the form ServiceName(BusSpecificLocation. For example, PCI devices use PCI(XXYY), where XX is the device number and YY is the function number. The string is unique to the device in relationship to its bus. Plug and Play assembles the location path for each node in the devnode tree. Each devnode in the tree concatenates its service name string to the end of the location path string that its parent devnode supplies. Therefore, the location path can uniquely identify the position of any devnode in the tree.

To find the LocationPath string for a given devnode

1. Open Device Manager, view Devices by connection, and then locate the devnode for which to apply the registry override.

2. Right-click the devnode, click Properties, and then click the Details tab.3. In the Property drop-down list, find the LocationPaths property. This property

contains the location path string for this devnode. Use this value in the device override registry key.

It is possible that the devnode does not have a LocationPaths value if the driver for this devnode or one of its parents does not implement the GUID_PNP_LOCATION_INTERFACE interface. In this case, Device Manager does not report a LocationPaths property for the device. Check the parent devnode for a LocationPaths property.

The LocationPaths override is used to override the Removable capability of devices that are hardwired to a fixed bus location. This typically occurs in portable computers and includes the following devices:

Wireless network adapters. Bluetooth adapters.

Keyboards or pointing devices.



These devices exist on different internal buses at fixed locations that users cannot change. The LocationPaths override lets you specify that only the device at a given bus location is affected by the ContainerID override. This prevents the override from affecting devices at other bus locations that share the same HardwareID or CompatibleID as the override target. This is common when devices specify only a CompatibleID to match an inbox driver.

When you use a ChildLocationPaths registry subkey to override the Removable capability of child devnodes that were enumerated by a parent devnode, it is often useful to target only child devnodes at specific locations, regardless of what kind of devices they are.

For example, a mobile PC might have an internal USB hub that has both internal and external ports. If the USB hub incorrectly reports its internal ports as being external, any devices that are internally hardwired to these ports are incorrectly reported as removable. Similarly, if all ports are misreported as being internal, any externally connected devices are treated as if they are nondetachable parts of the portable computer.

You can easily find the location paths value for a device that is connected to an external USB port by simply plugging any device into the port and using Device Manager to inspect the LocationPaths property, as described previously. The LocationPaths value is the same for every USB device that is plugged into the same port because the parent bus remains the same and internally identifies the port in the same way, regardless of the attached device.

Removable Registry ValueRegistry value name RemovableRequired/optional RequiredValue type DWORD (32-bit) valueValid registry values 0 – Indicates that the applicable devnodes should be regarded as not

removable to create the ContainerID1 – Indicates that the applicable devnodes should be regarded as removable to create the ContainerID

CommentsThe Removable value must be created as a DWORD (32-bit) value type. Recognized values are {0, 1} as described previously.



Device Override ExamplesFigure 5 shows how different Removable overrides affect the ContainerID values that Plug and Play creates for devices.

Figure 5. Key for the following examples

We start with a hypothetical USB device that is connected to a computer. For this first example, we assume that the device correctly reports its Removable capability and that no Removable overrides are configured for it in the registry.

Figure 6. Devnode topology for a hypothetical computer and device


Example KeyHardwareID/CompatibleIDHardwareID/CompatibleID

Location Path

Location Path

Not RemovableDevnodeRemovableDevnode

ContainerID

DeviceContainer

ACPI\PNP0A08PCIROOT(0)PCI\

VEN_8086&DEV_27C9PCI(102)USB\

ROOT_HUBUSBROOT(0)

USB\VID_1234&PID_

5678 USB(1)

HID_DEVICE

USB\VID_062A&PID_

0000 USB\VID_0700&PID_

0001

USB\VID_062A&PID_

0002

ContainerID {A}

ContainerID {B}


Example 1The following registry example and Figure 7 show a device override for a devnode that matches a HardwareID at a specific LocationPaths.

In this example, the override is applied to devnodes that have a HardwareID of USB\VID_1234&PID_5678 at the specified LocationPaths. The registry format is as follows:HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\DeviceOverrides

USB#VID_1234&PID_5678LocationPaths

PCIROOT(0)#PCI(102)# USBROOT(0)# USB(1)Removable=0

Figure 7. Override showing the effect of marking a devnode not removable

This override changes the Plug and Play interpretation of the device topology. Notice that the devnode that has HardwareID USB\VID_1234&PID_5678 was marked as not removable in the registry. Plug and Play does not generate a new ContainerID value for this devnode because the override causes Plug and Play to interpret the devnode as not being removable from its parent. Instead, USB\VID_1234&PID_5678 (and all its children) inherit the ContainerID of its parent. In this case, the inherited value is ContainerID {A} because it is the first devnode above USB\VID_1234&PID_5678 that is assigned a ContainerID. The result of this override is a single device because all the devnodes in the tree have the identical ContainerID {A}, as Figure 7 shows. Because of this registry setting, Plug and Play interprets the device USB\VID_1234&PID_5678 as being integrated with the computer.

This example shows a typically encountered devnode topology: some portable computers have devices that are hardwired to specific bus locations, which incorrectly report themselves as removable. Devices that are physically integrated




ROOT_HUBUSBROOT(0)USB\

VID_1234&PID_5678 USB(1)

HID_DEVICE

USB\VID_062A&PID

_0000 USB\VID_0700&PID_

0001

USB\VID_062A&PID

_0002

ContainerID {A}


with a computer, such as a webcam or biometric (fingerprint) reader, should not be reported as removable because users cannot physically separate them from the computer. The Removable override lets an OEM change how Plug and Play interprets the Removable capability and thereby affects the ContainerID assignment for the device.

Example 2The following registry example and Figure 8 show a device override for all devnodes that match a given HardwareID.

The registry format is as follows:HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\DeviceOverrides

USB#VID_062A&PID_0000LocationPaths

*Removable=1

Figure 8. Breaking a device into two device containers

This override changes the interpretation of the device topology in Plug and Play. The device is assigned two ContainerID values, so Windows sees it as two device containers. In some instances, it might be necessary to split a single physical device into two or more device containers. An example is a wireless keyboard and mouse that connect to the computer by using a wireless transceiver. When the transceiver is




ROOT_HUBUSBROOT(0)

USB\VID_1234&PID_

5678 USB(1)

HID_DEVICE

USB\VID_062A&PID

_0000 USB\VID_0700&PID_

0001

USB\VID_062A&PID

_0002

ContainerID {A}

ContainerID {B}

ContainerID {C}


connected to the computer, Plug and Play enumerates additional keyboard and mouse devices that the transceiver exposes. These keyboard and mouse devnodes frequently do not report their removable relationship correctly. Often Plug and Play sees a single device container (for the transceiver) but not for the physical keyboard and mouse devices. By supplying a registry device override, the keyboard and mouse devnodes can be split from the transceiver and appear as their own device containers.

In this example, the override applies to devnodes that have a HardwareID of USB\VID_062A&PID_0000. Plug and Play interprets the devnode that has the HardwareID of USB\VID_062A&PID_0000 as removable in grouping the devnodes into devices. However, the Removable capability flag on the Plug and Play devnode does not change.

Additionally, the * registry subkey indicates that this override applies to all devnodes on this computer that have the HardwareID of USB\VID_062A&PID_0000.

Example 3The following registry example and Figure 9 show the effect of the ChildLocationPaths device override key.


USB#VID_062A&PID_0000ChildLocationPaths

*Removable=1



Figure 9. Device overrides that use the ChildLocationPaths key

The device is assigned three ContainerID values and therefore is seen by Windows as three devices. This example is similar to Example 2This example shows a typically encountered devnode topology: some portable computers have devices that are hardwired to specific bus locations, which incorrectly report themselves as removable. Devices that are physically integrated with a computer, such as a webcamor biometric (fingerprint) reader, should not be reported as removable because users cannot physically separate them from the computer. The Removable override lets an OEM change how Plug and Play interprets the Removable capability and thereby affects the ContainerID assignment for the device., except that the override is applied to the children of the devnode that have the specified HardwareID. Each child of the specified devnode is marked as removable and assigned a ContainerID by Plug and Play.

In this case, ChildLocationPaths is applied to the USB\VID_062A&PID_0000 devnode. Each child of the parent devnode that has the HardwareID of USB\VID_062A&PID_0000 is interpreted as removable in grouping the devnodes into devices. The Plug and Play devnode property is not changed.

Additionally, the * registry key indicates that this override applies to the children of all devnodes on this computer that have the parent HardwareID of USB\VID_062A&PID_0000.



VEN_8086&DEV_27C9PCI(102)

USB\ROOT_HUBUSBROOT(0)

USB\VID_1234&PID_

5678 USB(1)

HID_DEVICE

USB\VID_062A&PID_

0000

USB\VID_0700&PID_

0001

USB\VID_062A&PID_

0002

ContainerID {A}

ContainerID {B}

ContainerID {C}

ContainerID {D}


Example 4The following registry example and Figure 10 show the effect of applying several of the device override keys together. In this example, a devnode that is marked as removable at a given LocationPaths is overridden so that it is interpreted as not removable. The devnode inherits the ContainerID of its parent, which in this example is the computer. The children of this devnode are marked as removable by using both the LocationPaths and ChildLocationPaths overrides. Although this is an extreme example of applying the device override capability, it demonstrates the flexibility that this mechanism provides.


USB#VID_1234&PID_5678LocationPaths

PCIROOT(0)#PCI(102)#USBROOT(0)#USB(1)Removable=0

USB#VID_062A&PID_0000ChildLocationPaths

*Removable=1

USB#VID_062A&PID_0002LocationPaths

*Removable=1

Figure 10. Several overrides applied together



VEN_8086&DEV_27C9PCI(102)USB\ROOT_HUBUSBROOT(0)

USB(1)

USB\VID_1234&PI

D_5678

HID_DEVICE

USB\VID_062A&PI

D_0000USB\

VID_0700&PID_0001

USB\VID_062A&PI

D_0002

ContainerID {A}

ContainerID {B}

ContainerID {C}

ContainerID {D}


Verifying Correct Implementation of the ContainerID PropertyVerifying that a computer or device correctly implements the ContainerID property is an important part of the development process. An incorrect implementation adversely affects the usability of the device.

Windows 7 introduces a new way for users to see and interact with devices: the Devices and Printers UI. This UI lets users see all devices that are connected to the computer. Devices appear as they physically appear to users, as a single “piece of plastic.”

IHVs and OEMs can customize the representation of their devices in the Devices and Printers UI in many ways. A custom photorealistic icon and detailed information can be associated with the device and displayed to users. Actions can be associated with the device, so that users can start device-related tasks. Together, these changes enable users to consistently interact with their devices.

To take advantage of the new capabilities that the Devices and Printers UI provides, devices must correctly implement the ContainerID property as outlined in this document. The following section describes how to verify correct implementation of a ContainerID.



Devices and Printers User InterfaceThe simplest way to verify that a device complies with the ContainerID requirements is to open the Devices and Printers UI to see how the device appears. If the device complies with the ContainerID requirements that are outlined in this document, only one icon should appear in Devices and Printers for that device. The following example shows Devices and Printers for a computer that has an attached USB keyboard and mouse. Notice that only one icon appears for each device.

Figure 11. Devices and Printers user interface showing USB mouse



In the example, the mouse is attached to a USB port on a desktop PC. This is the same mouse from Figure 3 earlier in the paperFigure , which is associated with two devnodes. In the Devices and Printers UI, however, only one instance of the mouse appears, which matches the physical device. This device correctly implements the requirements for the ContainerID property. The physical device, which has one piece of plastic or “container,” is represented by one object in the Devices and Printers UI. In this example, the mouse does not contain a Microsoft ContainerID OS descriptor or serial number. Therefore, Plug and Play generates a ContainerID value by using the Removable capability for the mouse.

Solving Problems in the Devices and Printers User InterfaceIf more than one instance of a device in the Devices and Printers UI appears when you expect only one, the device does not correctly implement the ContainerID requirements and Plug and Play grouped one or more devnodes into additional device containers for the device. In such a case, examine the following:

Is the Removable capability set correctly for each devnode that is enumerated for the device?

This is the most common cause of multiple device instances in the Devices and Printers UI. Check that each devnode for the device has the Removable capability set appropriately. The top-most devnode of the device should be reported as removable, and children should be reported as not removable. Custom bus driver implementations must correctly assign the removable relationship for devnodes that they enumerate.

Device Manager is a valuable tool to diagnose these issues. By clicking View > View by connection, you can examine the complete devnode hierarchy. Locate the devnodes that make up your device. Open the Properties dialog for each devnode, click the Details tab, and then select the Capabilities entry in the Properties drop-down list. If the Value list contains the CM_DEVCAP_REMOVABLE flag, this devnode is marked as removable and Plug and Play creates a new device container for this devnode and its nonremovable children.

Does the device contain a ContainerID or other unique identifier in the hardware?Check that the format of the ContainerID or unique identifier in the hardware complies with the format requirements for the given bus. These requirements are discussed in “Generating a ContainerID from the Bus-Specific Unique Identifier” earlier in this paper.If devnodes for the device are enumerated by a custom bus driver, check that the bus driver correctly responds to the Plug and Play IRP_MN_QUERY_ID request for BusQueryContainerID. For more information, see “Including ContainerID Supportin a Custom Bus Driver” earlier in this paper.

Is the device concurrently connected to the computer through more than one bus?If the device is concurrently connected to the computer through two or more buses, two or more instances of the device can appear in the Devices and Printers UI (one or more device instance for each bus to which the device is attached). To resolve this problem, ensure that the device reports a ContainerID



or a device-specific unique identifier and that the reported value is identical on each bus.

Call to ActionDevice containers provide a new way to think about devices, with potential benefits to both users and the hardware industry. Users benefit from the new Devices and Printers UI, which enables them to interact with their hardware in a more natural, intuitive way. The hardware industry benefits from having the Devices and Printers UI as a starting point for new and exciting device-centric scenarios that IHVs and OEMs create.

To be successful, device manufacturers must be aware of the device container concept and engineer their devices to take full advantage of this new functionality.



ResourcesFor the latest information about the Microsoft Windows family, see the Windows Web site at http://www.microsoft.com/windows.

WHDC Web site:Home page

http://www.microsoft.com/whdc/default.mspx

Windows Device Experience nodal pagehttp://www.microsoft.com/whdc/device/DeviceExperience/default.mspx

Microsoft OS Descriptorshttp://www.microsoft.com/whdc/connect/usb/OS_Descdwn.mspx

PnP-X: Plug and Play Extensions for Windows Specificationhttp://www.microsoft.com/whdc/connect/rally/pnpx-spec.mspx

Windows Driver Kit:DEVICE_CAPABILITIES

http://msdn.microsoft.com/en-us/library/aa491648.aspx

GUID_PNP_LOCATION_INTERFACEhttp://msdn.microsoft.com/en-us/library/bb898834.aspx

SetupDiGetDeviceRegistryPropertyhttp://msdn.microsoft.com/en-us/library/ms792967.aspx

WdfPdoInitAssignContainerIDhttp://msdn.microsoft.com/en-us/library/dd434716.aspx

MSDN:Specification Profiles Index Page

http://msdn.microsoft.com/en-us/library/ms951214.aspx

Specifications:UPnP Device Architecture, Version 1.0

http://www.upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.0-20080424.pdf

Device Profile for Web Serviceshttp://specs.xmlsoap.org/ws/2005/05/devprof/devicesprofile.pdf

PCIe Base 2.1 Specificationhttp://www.pcisig.com/specifications/pciexpress/base2


http://www.pcisig.com/specifications/pciexpress/base2

http://specs.xmlsoap.org/ws/2005/05/devprof/devicesprofile.pdf



http://msdn.microsoft.com/en-us/library/dd434716.aspx

http://msdn.microsoft.com/en-us/library/ms792967.aspx

http://msdn.microsoft.com/en-us/library/bb898834.aspx

http://msdn.microsoft.com/en-us/library/aa491648.aspx

http://www.microsoft.com/whdc/connect/rally/pnpx-spec.mspx

http://www.microsoft.com/whdc/connect/usb/OS_Descdwn.mspx

http://www.microsoft.com/whdc/device/DeviceExperience/default.mspx

http://www.microsoft.com/whdc/default.mspx

http://www.microsoft.com/windows

Documents

Introductiondownload.microsoft.com/.../ContainerIDs.docx · Web viewUnless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos,